# Neon Postgres Documentation

> Neon is a complete set of cloud backend primitives built around Lakebase Postgres, for developers, startups, and agent platforms, from Databricks. Services include Lakebase Postgres, Managed Better Auth, Realtime, Data API, Functions, Object Storage, AI Gateway. Lakebase Postgres on Neon includes autoscaling, instant restore, and scale-to-zero, with native branching, realtime and a fully reactive DX and works with any language, framework, or ORM that supports Postgres.
> This file contains the full Neon documentation. For a table of contents, see https://neon.com/docs/llms.txt

--- [Document source](https://neon.com/docs/ai-gateway/anthropic-messages.md) ---

> Summary: The Anthropic Messages endpoint lets you use the Anthropic SDK with Neon AI Gateway by changing only the base URL. Supports streaming, prompt caching, and extended thinking on Claude models.

# Anthropic Messages API

Use the Anthropic SDK with Neon AI Gateway

Last updated: 2026-10-31

The Anthropic Messages endpoint exposes the [Anthropic Messages API](https://docs.anthropic.com/en/api/messages) through Neon AI Gateway. Use it when you need extended thinking or prompt caching, which require the native Anthropic SDK. For standard completions, the [chat completions](https://neon.com/docs/ai-gateway/chat-completions) endpoint works with all Anthropic models and doesn't require the Anthropic SDK.

**Base URL:** `https://<branch-host>/anthropic`

**Note:** The Anthropic SDK appends `/v1/messages` to the base URL automatically. Set the base URL to `/anthropic` (without `/v1`).

This endpoint is also reachable at the longer `/ai-gateway/anthropic/v1/messages` path. Both behave identically and neither is deprecated. See [Shorter paths](https://neon.com/docs/ai-gateway/models#shorter-paths) for the full list of aliases.

## Setup

Set these environment variables. See [Get started](https://neon.com/docs/ai-gateway/get-started) for how to obtain them.

```bash
NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://br-winter-pond-aptw82ef-api.ai.c-2.us-east-2.aws.neon.tech
```

## Supported models

This endpoint accepts Anthropic models only. See the [AI Gateway catalog](https://neon.com/docs/ai-gateway/models) for the full list. Supported models:

- `claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-fable-5`, `claude-fable-5-1`
- `claude-opus-4-8`, `claude-opus-4-7`, `claude-opus-4-6`, `claude-opus-4-5`, `claude-opus-4-1`
- `claude-sonnet-4-6`, `claude-sonnet-4-5`
- `claude-haiku-4-5`

Sending a non-Anthropic model ID returns `400 model "<model-id>" is not available on the anthropic_messages endpoint`, naming whichever model you sent. Use the [chat completions endpoint](https://neon.com/docs/ai-gateway/chat-completions) if you need to call multiple providers from the same code.

## Basic request

**TypeScript (Anthropic SDK)**

```typescript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  authToken: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/anthropic`,
});

const message = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'What is Neon?' }],
});

for (const block of message.content) {
  if (block.type === 'text') console.log(block.text);
}
```

**Python (Anthropic SDK)**

```python
import anthropic
import os

client = anthropic.Anthropic(
    auth_token=os.environ['NEON_AI_GATEWAY_TOKEN'],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/anthropic",
)

message = client.messages.create(
    model='claude-sonnet-4-6',
    max_tokens=1024,
    messages=[{'role': 'user', 'content': 'What is Neon?'}],
)

print(message.content[0].text)
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/anthropic/v1/messages" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "What is Neon?"}]
  }'
```

## Streaming

Streaming works the same as with the Anthropic SDK directly. Use `client.messages.stream()` or pass `"stream": true` in a cURL request. The only change from standard usage is `base_url`.

## Prompt caching

The gateway forwards the `cache_control` field to Anthropic unchanged. Prompt caching works exactly as described in the [Anthropic prompt caching docs](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching).

**TypeScript (Anthropic SDK)**

```typescript
const message = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 1024,
  system: [
    { type: 'text', text: 'You are a helpful assistant.' },
    {
      type: 'text',
      text: longDocumentContent,
      cache_control: { type: 'ephemeral' },
    },
  ],
  messages: [{ role: 'user', content: 'Summarize the key points.' }],
});

console.log(message.usage);
// { input_tokens: 50, output_tokens: 200,
//   cache_creation_input_tokens: 10000, cache_read_input_tokens: 0 }
```

**Python (Anthropic SDK)**

```python
message = client.messages.create(
    model='claude-sonnet-4-6',
    max_tokens=1024,
    system=[
        {'type': 'text', 'text': 'You are a helpful assistant.'},
        {
            'type': 'text',
            'text': long_document_content,
            'cache_control': {'type': 'ephemeral'},
        },
    ],
    messages=[{'role': 'user', 'content': 'Summarize the key points.'}],
)

print(message.usage)
# input_tokens=50, output_tokens=200,
# cache_creation_input_tokens=10000, cache_read_input_tokens=0
```

## Extended thinking

The gateway forwards the `thinking` parameter to Anthropic unchanged. Set `budget_tokens` to control how many tokens Claude can use for thinking. `max_tokens` must be greater than `budget_tokens`.

**Important:**

`claude-opus-5-5`, `claude-opus-5`, `claude-sonnet-5`, `claude-fable-5`, `claude-fable-5-1`, `claude-opus-4-8`, and `claude-opus-4-7` do not accept `thinking.type: "enabled"`. They return `400` with:

```
"thinking.type.enabled" is not supported for this model.
Use "thinking.type.adaptive" and "output_config.effort" to control thinking.
```

Use `thinking: { type: 'adaptive' }` with `output_config: { effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max' }` instead. `claude-opus-5-5`, `claude-fable-5`, and `claude-fable-5-1` also reject `thinking.type: "disabled"` — they always think adaptively.

`claude-opus-4-6`, `claude-opus-4-5`, `claude-opus-4-1`, `claude-sonnet-4-6`, `claude-sonnet-4-5`, and `claude-haiku-4-5` accept the `enabled` + `budget_tokens` form shown below.

**TypeScript (Anthropic SDK)**

```typescript
const message = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 16000,
  thinking: {
    type: 'enabled',
    budget_tokens: 10000,
  },
  messages: [{ role: 'user', content: 'Design a database schema for a multi-tenant SaaS app.' }],
});

for (const block of message.content) {
  if (block.type === 'thinking') {
    console.log('Thinking:', block.thinking);
  } else if (block.type === 'text') {
    console.log(block.text);
  }
}
```

**Python (Anthropic SDK)**

```python
message = client.messages.create(
    model='claude-sonnet-4-6',
    max_tokens=16000,
    thinking={
        'type': 'enabled',
        'budget_tokens': 10000,
    },
    messages=[{'role': 'user', 'content': 'Design a database schema for a multi-tenant SaaS app.'}],
)

for block in message.content:
    if block.type == 'thinking':
        print('Thinking:', block.thinking)
    elif block.type == 'text':
        print(block.text)
```

## Forwarded headers

The gateway forwards these request headers to the upstream provider:
`Accept`, `Anthropic-Beta`, `Anthropic-Version`, `Content-Type`, `OpenAI-Beta`, `User-Agent`.

All other headers are stripped. The `Authorization` header is replaced with the workspace credential before forwarding. Your `NEON_AI_GATEWAY_TOKEN` is never sent to Anthropic directly.

## Error handling

| Status            | Message                                                                  | Cause                                     |
| ----------------- | ------------------------------------------------------------------------ | ----------------------------------------- |
| `400 Bad Request` | `unknown model "<model-id>"`                                             | Model ID not in the catalog               |
| `400 Bad Request` | `model "<model-id>" is not available on the anthropic_messages endpoint` | Non-Anthropic model sent to this endpoint |

For authentication, quota, and upstream errors, see [Troubleshooting](https://neon.com/docs/ai-gateway/troubleshooting).

## Next steps

- [Models](https://neon.com/docs/ai-gateway/models): full model catalog
- [Chat completions](https://neon.com/docs/ai-gateway/chat-completions): use any model including Anthropic via the unified endpoint
- [Authentication](https://neon.com/docs/ai-gateway/authentication): credential scopes and branch binding

--- [Document source](https://neon.com/docs/ai-gateway/authentication.md) ---

> Summary: AI Gateway uses Neon bearer credentials with the ai_gateway:invoke scope. Credentials are scoped to a branch and its descendants, so a credential created on your main branch works in all preview branches. No provider API keys are required.

# AI Gateway authentication

How Neon credentials work with AI Gateway

Last updated: 2026-10-09

AI Gateway uses Neon bearer credentials, the same scoped-credential system as [Object Storage](https://neon.com/docs/storage/authentication): one credential API mints branch-scoped tokens that differ by scope (AI Gateway uses `ai_gateway:invoke`). No provider API keys are needed.

## Creating a credential

A credential must include the `ai_gateway:invoke` scope.

**CLI**

Create a credential with the [Neon CLI](https://neon.com/docs/cli/credentials):

```bash
neon credentials create --scope ai_gateway:invoke --name my-app-credential
```

The `api_token` is printed once; set it as `NEON_AI_GATEWAY_TOKEN`. Run it in a directory [linked](https://neon.com/docs/cli/link) to your project, or pass `--project-id` and `--branch`.

**Console**

In the Neon Console, click **Connect** at the top of the sidebar and open the **AI Gateway** tab. The snippet includes both gateway env vars (see [Environment variables](https://neon.com/docs/ai-gateway/authentication#environment-variables) below). Click **Reveal credential** to show the token, or **Copy snippet** to copy the full `.env`. Use **Rotate credential** to replace the token in place.

The Connect dialog reveals and rotates the current credential. To create a credential with specific scopes, open your project's **Settings** > **Credentials** and select **Create credential**. To list all credentials for the branch or revoke one, use the [Neon CLI](https://neon.com/docs/cli/credentials) or the API (below).

**API**

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["ai_gateway:invoke"], "principal_type": "user"}'
```

The response includes an `api_token` field. Store it as an environment variable:

```bash
export NEON_AI_GATEWAY_TOKEN=nt_live_...
```

## Pull credentials with neon

For local development, `neon env pull` writes your AI Gateway credentials to your `.env` file automatically, with no manual copy-paste from the API response:

```bash
neon env pull --file .env
```

This populates `NEON_AI_GATEWAY_TOKEN` and `NEON_AI_GATEWAY_BASE_URL` for the current branch alongside your database connection string. Running `neon config apply` or `neon deploy` also auto-pulls credentials after a successful apply. To check current credential status:

```bash
neon config status
```

For production deployments, use the [API-based workflow](https://neon.com/docs/ai-gateway/authentication#creating-a-credential) to create named credentials. `expires_at` is accepted but not currently enforced. Revoke credentials explicitly instead of relying on expiry.

## Using your credential

Pass your credential as a bearer token on every request:

```
Authorization: Bearer <your-credential>
```

When using an AI SDK, set this as the `apiKey` parameter:

**TypeScript**

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});
```

**Python**

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)
```

## Environment variables

Neon provides two gateway env vars. `NEON_AI_GATEWAY_BASE_URL` is the bare branch host, so you append the dialect path yourself when configuring an SDK.

| Variable                   | Value                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| `NEON_AI_GATEWAY_TOKEN`    | Bearer token (`nt_live_...`)                                                              |
| `NEON_AI_GATEWAY_BASE_URL` | Bare branch host: `https://<branch-host>`, with no path. Append the dialect path yourself |

Append the dialect path for the endpoint you need:

```
NEON_AI_GATEWAY_BASE_URL + /v1            → chat completions (all providers)
NEON_AI_GATEWAY_BASE_URL + /openai/v1     → OpenAI Responses API
NEON_AI_GATEWAY_BASE_URL + /anthropic     → Anthropic Messages API
NEON_AI_GATEWAY_BASE_URL + /gemini        → Gemini generateContent API
```

The Anthropic and Gemini values are SDK base URLs: the Anthropic SDK appends `/v1/messages` and google-genai appends `/v1beta/models/...`, so don't add those segments yourself. Calling either endpoint directly takes the full path, `/anthropic/v1/messages` or `/gemini/v1beta/models/<model>:<action>`.

Each inference dialect is also reachable at a longer `/ai-gateway/<dialect>/v1` path (e.g. `/ai-gateway/mlflow/v1` for chat completions, `/ai-gateway/openai/v1` for Responses, `/ai-gateway/anthropic/v1` for Anthropic Messages, `/ai-gateway/gemini` for Gemini). Both forms behave identically and neither is deprecated, but the shorter paths are what the docs and SDKs use. The model list is the exception: it has only `GET /v1/models`, with no `/ai-gateway/...` form. See [Shorter paths](https://neon.com/docs/ai-gateway/models#shorter-paths) for the full mapping.

To use an OpenAI SDK, set its `apiKey` and `baseURL` from these variables (see the examples below).

## Credentials in Neon Functions

When your code runs inside Neon Functions, both gateway env vars are injected automatically. No credential creation step required:

| Variable                   | Value                                               |
| -------------------------- | --------------------------------------------------- |
| `NEON_AI_GATEWAY_TOKEN`    | Bearer token for the AI Gateway                     |
| `NEON_AI_GATEWAY_BASE_URL` | Branch gateway host with `https://` prefix, no path |

See [Environment variables](https://neon.com/docs/compute/functions/environment-variables) for the full list of variables Neon injects into a function.

Configure an OpenAI SDK by setting `apiKey` and `baseURL` from these variables. Use the OpenAI Responses dialect for `responses.create()`:

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const response = await client.responses.create({
  model: 'gpt-5-mini',
  input: 'What is Neon?',
});
```

For the chat completions endpoint, point the base URL at `/v1` instead:

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});
```

## How branch binding works

Each credential is tied to the branch it was created on. It's valid for:

- That branch (the anchor branch)
- Any branch descended from it: preview branches, feature branches, CI branches

It's **not** valid for branches outside that lineage.

This means a credential created on your `main` branch works in all branches that were forked from `main`. A credential created on a feature branch only works within that feature branch's descendants.

```
main  ──── credential valid here
  └── preview/feature-x  ──── and here
        └── preview/sub-branch  ──── and here
staging  ──── credential NOT valid here (different lineage)
```

This design lets you use a single credential across your entire development workflow (local dev, preview deployments, and CI) without creating separate credentials for each environment.

## Common auth errors

| Error                     | Cause                                      | Fix                                                                                                                             |
| ------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`        | Missing or invalid credential              | Check that `NEON_AI_GATEWAY_TOKEN` is set and contains the full token                                                           |
| `403 Forbidden`           | Credential lacks `ai_gateway:invoke` scope | Recreate the credential with the correct scope                                                                                  |
| `403 Forbidden`           | Branch not in credential lineage           | Use a credential created on this branch or an ancestor branch. The gateway returns: `credential not authorized for this branch` |
| `503 Service Unavailable` | Auth store temporarily unavailable         | Retry the request                                                                                                               |

## Rotating credentials

To rotate a credential in place with the [Neon CLI](https://neon.com/docs/cli/credentials), run `neon credentials rotate <token_id>` (find the id with `neon credentials list`). The `token_id` stays the same and a new `api_token` is minted, so update `NEON_AI_GATEWAY_TOKEN` with it. Otherwise, create a new credential, update your environment variables, then revoke the old one.

The Console's **Connect** dialog can rotate a credential (**AI Gateway** tab > **Rotate credential**) but not revoke one. To revoke, use the [Neon CLI](https://neon.com/docs/cli/credentials) (`neon credentials revoke <token_id>`) or the API:

```bash
curl -X DELETE "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials/{token_id}" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Or with the [Neon CLI](https://neon.com/docs/cli/credentials):

```bash
neon credentials revoke <token_id>
```

--- [Document source](https://neon.com/docs/ai-gateway/chat-completions.md) ---

> Summary: The chat completions endpoint is the recommended starting point for Neon AI Gateway. It is OpenAI Chat Completions-compatible, works with any model in the catalog, and lets you switch providers without changing your SDK code.

# Chat completions

The OpenAI-compatible unified endpoint

Last updated: 2026-10-23

The chat completions endpoint is the recommended way to use Neon AI Gateway. It's fully compatible with the [OpenAI Chat Completions API](https://platform.openai.com/docs/api-reference/chat) and works with every model in the [AI Gateway catalog](https://neon.com/docs/ai-gateway/models). Switch models by changing a single field.

**Base URL:** `https://<branch-host>/v1`

This endpoint is also reachable at the longer `/ai-gateway/mlflow/v1/chat/completions` path. Both behave identically and neither is deprecated. See [Shorter paths](https://neon.com/docs/ai-gateway/models#shorter-paths) for the full list of aliases.

If you're using an OpenRouter-compatible client that asks for a base URL, set it to `https://<branch-host>/v1` and call `/chat/completions`.

## Setup

Set these environment variables. See [Get started](https://neon.com/docs/ai-gateway/get-started) for how to obtain them.

```bash
NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://br-winter-pond-aptw82ef-api.ai.c-2.us-east-2.aws.neon.tech
```

## Basic request

**TypeScript (OpenAI SDK)**

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const response = await client.chat.completions.create({
  model: 'gpt-5-mini',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'What is Neon?' },
  ],
  max_tokens: 256,
});

console.log(response.choices[0].message.content);
```

**Python (OpenAI SDK)**

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Neon?"},
    ],
    max_tokens=256,
)

print(response.choices[0].message.content)
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is Neon?"}
    ],
    "max_tokens": 256
  }'
```

## Streaming

Add `stream: true` to receive a server-sent events response.

**TypeScript (OpenAI SDK)**

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const stream = await client.chat.completions.create({
  model: 'gpt-5-mini',
  messages: [{ role: 'user', content: 'Explain branching in Postgres.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}
```

**Python (OpenAI SDK)**

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

with client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "Explain branching in Postgres."}],
    stream=True,
) as stream:
    for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [{"role": "user", "content": "Explain branching in Postgres."}],
    "stream": true
  }'
```

## Switching models

Change the `model` field to use a different provider. Everything else stays the same.

```typescript
// OpenAI
model: 'gpt-5-4'

// Google
model: 'gemini-3-flash'

// Alibaba
model: 'qwen3-next-80b-a3b-instruct'
```

For a few models, `message.content` comes back as an array of content blocks instead of a plain string. See [Content shape varies by model](https://neon.com/docs/ai-gateway/models#which-endpoint-to-use) before swapping in a model you haven't used yet.

Gemini models don't support `parallel_tool_calls: false`, and a request that sets it returns `400` with `Unknown name "parallel_tool_calls"`. Leave the field out instead. Gemini makes parallel tool calls by default, so your code needs to handle more than one tool call per turn.

`gemini-4-argon` doesn't support `temperature` or `reasoning_effort` on this endpoint, and a request that sets either returns `400`. Leave both out. If you need to control them, call the model through the [Gemini endpoint](https://neon.com/docs/ai-gateway/gemini) instead, where `temperature` and `thinkingConfig.thinkingLevel` both work.

See [Models](https://neon.com/docs/ai-gateway/models) for the full list.

## Rate limiting

There are two separate rate limit tiers:

- **Neon account quota:** enforced by Neon. Returns `429` with error code `REQUEST_LIMIT_EXCEEDED`. See [Rate limits](https://neon.com/docs/ai-gateway/models#rate-limits) for current limits.
- **Upstream provider limit:** enforced by the Databricks workspace serving the model. Returns `429` with forwarded rate limit headers.

When the upstream provider rate-limits a request, AI Gateway forwards the relevant headers so your client can back off correctly:

| Header                           | Description                                |
| -------------------------------- | ------------------------------------------ |
| `Retry-After`                    | Seconds to wait before retrying (RFC 9110) |
| `X-Ratelimit-Limit-Requests`     | Request limit                              |
| `X-Ratelimit-Remaining-Requests` | Remaining requests                         |
| `X-Ratelimit-Reset-Requests`     | Time until request limit resets            |
| `X-Ratelimit-Limit-Tokens`       | Token limit                                |
| `X-Ratelimit-Remaining-Tokens`   | Remaining tokens                           |
| `X-Ratelimit-Reset-Tokens`       | Time until token limit resets              |

## Error handling

| Status                         | Meaning                | Common cause                                                                                                                                 |
| ------------------------------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`              | Invalid request        | Unknown model ID, or model used on the wrong endpoint                                                                                        |
| `413 Request Entity Too Large` | Body too large         | Request body exceeds 32 MiB. Reduce the size of your request.                                                                                |
| `401 Unauthorized`             | Authentication failed  | Missing or invalid `NEON_AI_GATEWAY_TOKEN`                                                                                                   |
| `403 Forbidden`                | Access denied          | Credential lacks `ai_gateway:invoke` scope, or branch not in credential lineage                                                              |
| `429 Too Many Requests`        | Account quota exceeded | Your account's AI Gateway quota is blocked. Error code: `REQUEST_LIMIT_EXCEEDED`. Check `Retry-After` for when to retry, or contact support. |
| `429 Too Many Requests`        | Upstream rate limited  | Upstream provider rate limit. Check the `Retry-After` and `X-Ratelimit-*` headers.                                                           |
| `502 Bad Gateway`              | Upstream error         | Temporary issue with the upstream workspace. Retry the request.                                                                              |

Error responses are a JSON object with an `error.message` field:

```json
{
  "error": {
    "message": "unknown model \"<model-id>\""
  }
}
```

## Next steps

- [Models](https://neon.com/docs/ai-gateway/models): full model catalog
- [OpenAI Responses API](https://neon.com/docs/ai-gateway/openai-responses): Responses API endpoint
- [Authentication](https://neon.com/docs/ai-gateway/authentication): credential scopes and branch binding

--- [Document source](https://neon.com/docs/ai-gateway/data-retention.md) ---

> Summary: Most Neon AI Gateway models run on Databricks Model Serving, where Databricks may temporarily store inputs and outputs for up to 30 days to prevent, detect, and mitigate abuse. OpenAI and Anthropic may retain data for safety purposes for certain models. Jev is hosted by TypeSafe AI, and TypeSafe AI's terms apply.

# Neon AI Gateway data retention

What Databricks and model providers retain when you use Neon AI Gateway

Last updated: 2026-10-29

Neon AI Gateway gives you one credential for many models. Most models are served through [Databricks Model Serving](https://docs.databricks.com/aws/en/machine-learning/model-serving), and data retention for those requests follows Databricks' policy, which covers what Databricks retains and what partner model providers may retain.

This page summarizes those policies. For the authoritative and latest terms, see [Databricks Model Serving data retention](https://docs.databricks.com/aws/en/machine-learning/model-serving#data-retention) and, for Jev, the TypeSafe AI [data processing addendum](https://typesafe.ai/legal/data-processing).

## Databricks data retention

For all Model Serving workloads, Databricks retains container build logs for up to 30 days and metrics data for up to 14 days.

As part of providing the service, Databricks may temporarily process and store your inputs and outputs to prevent, detect, and mitigate abuse or harmful uses. Your inputs and outputs are:

- Isolated from those of other customers
- Stored in the region where your request was processed, for up to 30 days
- Only accessible for detecting and responding to security or abuse concerns

## Partner model provider data retention

Partner model providers may retain data for safety purposes. This retention relies on automated scanning before any limited human review.

### OpenAI

In accordance with [OpenAI's safety retention policy](https://developers.openai.com/api/docs/guides/your-data#safety-retention), for `gpt-5-5`, `gpt-5-5-pro`, and future models, OpenAI may retain certain coding and routing customers' content that OpenAI's classifiers detect as potentially violating OpenAI's usage policies. Otherwise, retention isn't affected.

Coding and routing customers are customers that:

- Provide software engineering or deployment work for third parties, such as code generation, code completion, and agentic development or deployment workflows
- Act as model-access intermediary platforms or services that let third parties use OpenAI models for cyber-risk-relevant software development, alongside access to other providers' models

All other customers may be subject to additional retention upon advance notice.

### Anthropic

For Anthropic's Fable 5 and future Mythos-class models, all customers are subject to data retention for safety purposes, as described in [Anthropic's data retention practices](https://support.claude.com/en/articles/15425996-data-retention-practices-for-mythos-class-models).

## TypeSafe AI data retention

Jev is hosted by TypeSafe AI, Inc. Its [data processing addendum](https://typesafe.ai/legal/data-processing) and [privacy policy](https://typesafe.ai/legal/privacy-policy) describe how TypeSafe AI handles your requests. The privacy policy states that TypeSafe AI:

- Doesn't train or fine-tune AI or machine learning models on your prompts or other input
- Retains personal data for as long as reasonably necessary to provide its services
- Hosts its services in the United States

Neither document gives a fixed retention period for inputs or outputs.

--- [Document source](https://neon.com/docs/ai-gateway/decisions.md) ---

> Summary: Neon AI Gateway serves TypeSafe's System One decision models, Jev 1.14 and OpenJev, on the /typesafe/v1/systemone endpoint. Ask yes/no, choice, and score questions about text, JSON, or images and get back probabilities instead of generated text, with the same Neon credential you use for chat completions.

# Decisions

Answer questions about text, JSON, or images with System One decision models

Last updated: 2026-10-30

Decision models don't generate text. You send a piece of text or JSON, called the state, and a set of named questions about it. The model answers each one with numbers: the probability of a yes, the option it picked and how sure it is, or where the input falls on a scale you define. Use them to classify, route, or score input without prompting a chat model and parsing its reply. You can also [ask about an image](https://neon.com/docs/ai-gateway/decisions#ask-about-an-image).

The Neon AI Gateway serves TypeSafe's [System One](https://docs.typesafe.ai/) decision models, using the same Neon credential as the other AI Gateway endpoints. You can call them with the TypeSafe SDKs, the [Vercel AI SDK](https://neon.com/docs/ai-gateway/decisions#use-with-the-vercel-ai-sdk), or plain HTTP.

**Endpoint:** `POST https://<branch-host>/typesafe/v1/systemone`

Decision models aren't available on any other endpoint, and this one doesn't serve chat models.

## Models

| Model ID                | Name                  | Context window | Notes                         |
| ----------------------- | --------------------- | -------------- | ----------------------------- |
| `typesafeai-jev-1-14-0` | Jev 1.14              | 65,536 tokens  | TypeSafe's proprietary model. |
| `openjev-qwen35-4b`     | OpenJev (Qwen 3.5 4B) | 131,072 tokens | Open weights.                 |

Both are billed on **input tokens only**. See the [model catalog](https://neon.com/docs/ai-gateway/overview#available-models) for rates.

## Setup

The examples use two environment variables:

```bash
NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://br-...
```

Run `neon env pull --file .env` to write both to your `.env` for the current branch. You can also copy them from the Neon Console's **Connect** panel, on the **AI Gateway** tab. Inside Neon Functions they're injected automatically. See [Authentication](https://neon.com/docs/ai-gateway/authentication) for details.

Install the TypeSafe SDK with `npm install @typesafe-ai/sdk` or `pip install typesafe-sdk`. The SDKs take `${NEON_AI_GATEWAY_BASE_URL}/typesafe` as their base URL and add `/v1/systemone` themselves.

The TypeSafe SDKs are built for TypeSafe's own API, where the default model is `jev-latest`. The gateway uses its own model IDs, so set one when you create the client (`defaultModel` in TypeScript, `model` in Python), as the examples below do.

## Basic request

This request asks three questions about a support message, one of each type:

**TypeScript (TypeSafe SDK)**

```typescript
import { choice, noul, score, TypeSafeClient } from '@typesafe-ai/sdk';

const client = new TypeSafeClient({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/typesafe`,
  defaultModel: 'typesafeai-jev-1-14-0',
});

const { answers } = await client.systemOne({
  state: 'I was charged twice this month and need the extra charge refunded.',
  questions: {
    department: choice('Which team should handle this?', {
      billing: 'Payments and refunds',
      support: 'Other requests',
    }),
    severity: score('How severe is the issue?', [
      'Cosmetic',
      'Workaround exists',
      'Blocking; no workaround',
    ]),
    refund: noul('Is the customer asking for money back?'),
  },
});

console.log(answers.department.choice); // billing
console.log(answers.refund.noul); // 0.98
```

**Python (TypeSafe SDK)**

```python
import os
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/typesafe",
    model="typesafeai-jev-1-14-0",
) as client:
    response = client.system_one(
        state="I was charged twice this month and need the extra charge refunded.",
        questions={
            "department": Choice(
                instructions="Which team should handle this?",
                criteria={"billing": "Payments and refunds", "support": "Other requests"},
            ),
            "severity": Score(
                instructions="How severe is the issue?",
                criteria=["Cosmetic", "Workaround exists", "Blocking; no workaround"],
            ),
            "refund": Noul(instructions="Is the customer asking for money back?"),
        },
    )

print(response.answers["department"].choice)  # billing
print(response.answers["refund"].noul)  # 0.98
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/typesafe/v1/systemone" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafeai-jev-1-14-0",
    "state": "I was charged twice this month and need the extra charge refunded.",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {"billing": "Payments and refunds", "support": "Other requests"}
      },
      "severity": {
        "type": "score",
        "instructions": "How severe is the issue?",
        "criteria": ["Cosmetic", "Workaround exists", "Blocking; no workaround"]
      },
      "refund": {
        "type": "noul",
        "instructions": "Is the customer asking for money back?"
      }
    }
  }'
```

The model answers each question on its own, so you can ask several in one request. The state can be a string, as here, or a JSON object such as `{ "message": "...", "plan": "Launch" }`.

## Question types

| Type            | Criteria                                                                                 | Answer                                                                                                                       |
| --------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `noul` (yes/no) | Optional `true` and `false` descriptions                                                 | `noul`: the probability of a yes, from 0 to 1                                                                                |
| `choice`        | A map of option names to descriptions                                                    | `choice`: the option picked, plus a `confidence` and per-option `probabilities`                                              |
| `score`         | Level descriptions, indexed from 0. Use at least two: with one, the answer is always `0` | `score`: the expected level, which can fall between levels, plus `confidence`, `probabilities`, and a `legend` of the levels |

A `score` of `1.02` with the rubric above means "about `Workaround exists`"; read `probabilities` when you need the full distribution.

## Response shape

A response for the request above. Values can vary slightly from run to run:

```json
{
  "model": "jev-1.14.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "confidence": 1.0,
      "probabilities": { "billing": 1.0, "support": 0.0 }
    },
    "severity": {
      "type": "score",
      "score": 1.02,
      "confidence": 0.52,
      "legend": { "0": "Cosmetic", "1": "Workaround exists", "2": "Blocking; no workaround" },
      "probabilities": { "0": 0.15, "1": 0.68, "2": 0.17 }
    },
    "refund": { "type": "noul", "noul": 0.98 }
  },
  "usage": { "input_tokens": 383, "output_tokens": 61 }
}
```

`model` reports the name that served the request (`jev-1.14.0` here, `databricks-openjev-qwen35-4b` for OpenJev). Keep sending the model IDs from [Models](https://neon.com/docs/ai-gateway/decisions#models).

## Ask about an image

Add a top-level `assets` field and link it to the question:

1. `assets` holds the image under a reference you choose (`img-7d2f`).
2. A `state` field holds that reference (`"photo": "img-7d2f"`).
3. The question names that field in backticks (`` `photo` ``).

Jev 1.14 also needs the `TypeSafe-Danger-Zone-Images: true` header, TypeSafe's opt-in for its experimental image input, and returns `400` without it. OpenJev doesn't need the header.

**cURL**

```bash
IMAGE_B64=$(base64 < package.png | tr -d '\n')
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/typesafe/v1/systemone" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "TypeSafe-Danger-Zone-Images: true" \
  -d @- <<EOF
{
  "model": "typesafeai-jev-1-14-0",
  "state": { "photo": "img-7d2f" },
  "assets": {
    "img-7d2f": { "type": "image", "format": "png", "data_base64": "$IMAGE_B64" }
  },
  "questions": {
    "damaged": { "type": "noul", "instructions": "Does the package in \`photo\` look damaged?" }
  }
}
EOF
```

**Python (TypeSafe SDK)**

```python
import base64
import os
from typesafe_sdk import Noul, TypeSafeClient

with TypeSafeClient(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/typesafe",
    model="typesafeai-jev-1-14-0",
    headers={"TypeSafe-Danger-Zone-Images": "true"},
) as client:
    with open("package.png", "rb") as f:
        image_b64 = base64.b64encode(f.read()).decode()
    response = client.system_one(
        state={"photo": "img-7d2f"},
        questions={"damaged": Noul(instructions="Does the package in `photo` look damaged?")},
        # Send the image as JSON. The SDK's Image helper sends multipart, which the gateway doesn't accept.
        extra_body={"assets": {"img-7d2f": {"type": "image", "format": "png", "data_base64": image_b64}}},
    )

print(response.answers["damaged"].noul)
```

**JavaScript (fetch)**

```javascript
import { readFile } from 'node:fs/promises';

const res = await fetch(`${process.env.NEON_AI_GATEWAY_BASE_URL}/typesafe/v1/systemone`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NEON_AI_GATEWAY_TOKEN}`,
    'Content-Type': 'application/json',
    'TypeSafe-Danger-Zone-Images': 'true',
  },
  body: JSON.stringify({
    model: 'typesafeai-jev-1-14-0',
    state: { photo: 'img-7d2f' },
    assets: {
      'img-7d2f': {
        type: 'image',
        format: 'png',
        data_base64: (await readFile('package.png')).toString('base64'),
      },
    },
    questions: {
      damaged: { type: 'noul', instructions: 'Does the package in `photo` look damaged?' },
    },
  }),
});

const { answers } = await res.json();
console.log(answers.damaged.noul);
```

The answer has the same shape as for text. Image requests have a few rules:

- Send PNG or JPEG files as plain base64 in `data_base64`, with no `data:` prefix, and set `format` to `png` or `jpeg`.
- Jev 1.14 returns `400` for an image smaller than 280 × 280 pixels. OpenJev accepts smaller images.
- Images count as input tokens, and the count depends on resolution, not file size. With a short question, a 448 × 448 image is about 800 tokens on Jev 1.14 and 250 on OpenJev; a 1024 × 1024 image is about 3,000 and 1,100.
- Send images only in `assets`. An OpenAI-style `image_url` part in `state` returns `200`, but the model reads it as text and doesn't see the image.
- When Jev 1.14 rejects an image request, the error is `400` with the message `ai gateway upstream model rejected the request as invalid` and no reason.

## Use with the Vercel AI SDK

[`@neon/ai-sdk-provider`](https://www.npmjs.com/package/@neon/ai-sdk-provider) exposes the decision models to the AI SDK's `experimental_decide`. The AI SDK marks this API as experimental, so it may change in patch releases. It reads `NEON_AI_GATEWAY_BASE_URL` and `NEON_AI_GATEWAY_TOKEN` from [Setup](https://neon.com/docs/ai-gateway/decisions#setup) and needs `ai@7.0.133` or later. Install it with `npm install @neon/ai-sdk-provider ai@7`.

```typescript
import { neon } from '@neon/ai-sdk-provider';
import { experimental_decide as decide } from 'ai';

const { answers } = await decide({
  model: neon.decisionModel('typesafeai-jev-1-14-0'),
  state: 'I was charged twice this month and need the extra charge refunded.',
  questions: {
    department: {
      type: 'choice',
      instructions: 'Which team should handle this?',
      criteria: { billing: 'Payments and refunds', support: 'Other requests' },
    },
    refund: {
      type: 'boolean',
      instructions: 'Is the customer asking for money back?',
    },
  },
});

console.log(answers.department.choice); // billing
console.log(answers.refund.probability); // 0.98
```

The AI SDK calls the yes/no type `boolean` and returns its answer as `probability`; the provider sends it as `noul`. `choice` and `score` answers leave out `confidence`, which is in `providerMetadata.neon.confidence` instead. The provider accepts text and JSON state and throws `UnsupportedFunctionalityError` for file parts. To ask about an image, use HTTP or the Python SDK, as in [Ask about an image](https://neon.com/docs/ai-gateway/decisions#ask-about-an-image).

You can also use TypeSafe's [`@ai-sdk/typesafe-ai`](https://www.npmjs.com/package/@ai-sdk/typesafe-ai) provider. Point it at the gateway's `/typesafe/v1` path, since it appends `/systemone` itself, and pass your Neon credential as `apiKey`:

```typescript
import { createTypeSafeAi } from '@ai-sdk/typesafe-ai';
import { experimental_decide as decide } from 'ai';

const typesafe = createTypeSafeAi({
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/typesafe/v1`,
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
});

const { answers } = await decide({
  model: typesafe.decisionModel('typesafeai-jev-1-14-0'),
  state: 'I was charged twice this month.',
  questions: {
    billing: { type: 'boolean', instructions: 'Is the user asking about billing?' },
  },
});

console.log(answers.billing.probability); // 0.94
```

## List the models

`GET /typesafe/v1/models` lists the decision models your branch can call:

```bash
curl "$NEON_AI_GATEWAY_BASE_URL/typesafe/v1/models" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN"
```

They also appear in `GET /v1/models` with `"dialects": ["systemone"]`.

## Not supported

- **Streaming.** A request with `stream: true` returns `400 systemone does not support streaming`.
- **Image helpers and file parts.** The TypeSafe SDKs' `image()` (TypeScript) and `Image` (Python) helpers, and file parts in `@ai-sdk/typesafe-ai`, send images as `multipart/form-data`, which the gateway doesn't accept: it returns `400 missing or invalid model`. Send images as JSON, as in [Ask about an image](https://neon.com/docs/ai-gateway/decisions#ask-about-an-image); with the Python SDK, pass them in `extra_body`.
- **`box` questions.** The TypeSafe SDKs document `box` for the `jev-preview` model, which the gateway doesn't serve. A `box` question returns `400`.
- **Other endpoints.** A decision model on `/v1/chat/completions`, or a chat model on this endpoint, returns `400` with `is not available on the ... endpoint`.

## Error handling

| Status                         | Meaning               | Common cause                                                                                                                                                                                             |
| ------------------------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`              | Invalid request       | Missing or unknown model (including `jev-latest`), no questions, `stream: true`, a `box` question, or an [image request](https://neon.com/docs/ai-gateway/decisions#ask-about-an-image) Jev 1.14 rejects |
| `401 Unauthorized`             | Authentication failed | Missing or invalid `NEON_AI_GATEWAY_TOKEN`                                                                                                                                                               |
| `403 Forbidden`                | Access denied         | Credential lacks `ai_gateway:invoke` scope, or branch not in credential lineage                                                                                                                          |
| `413 Request Entity Too Large` | Body too large        | Request body exceeds 32 MiB, before or after decompression                                                                                                                                               |
| `415 Unsupported Media Type`   | Unsupported encoding  | `Content-Encoding` is something other than a single `gzip`, `x-gzip`, or `zstd` layer                                                                                                                    |
| `429 Too Many Requests`        | Quota or rate limited | Account quota or per-minute token limit. See [Rate limits](https://neon.com/docs/ai-gateway/models#rate-limits).                                                                                         |
| `503 Service Unavailable`      | Gateway busy          | Too many compressed requests are being decoded at once. Retry after the `Retry-After` interval.                                                                                                          |

For exact error messages and fixes, see [Troubleshooting](https://neon.com/docs/ai-gateway/troubleshooting).

## Next steps

- [Models](https://neon.com/docs/ai-gateway/models): full model catalog, rate limits, and pricing
- [Chat completions](https://neon.com/docs/ai-gateway/chat-completions): the OpenAI-compatible chat endpoint
- [TypeSafe docs](https://docs.typesafe.ai/): System One concepts and the full SDK reference

--- [Document source](https://neon.com/docs/ai-gateway/embeddings.md) ---

> Summary: Neon AI Gateway serves text-embedding models on an OpenAI-compatible /v1/embeddings endpoint. Use short model IDs like qwen3-embedding-0-6b, bge-large-en, or gte-large-en, all 1024-dimensional, with the same Neon credential you use for chat completions.

# Embeddings

The OpenAI-compatible embeddings endpoint

Last updated: 2026-10-23

Embeddings turn text into vectors that capture meaning, so you can match text by what it means rather than by the exact words. They power semantic search, recommendations, clustering, and retrieval-augmented generation (RAG).

The Neon AI Gateway embeddings endpoint generates those vectors so you can store and search them in Postgres. It's compatible with the [OpenAI Embeddings API](https://platform.openai.com/docs/api-reference/embeddings): the same OpenAI SDK you use elsewhere works against the gateway, using the same Neon credential as the other AI Gateway endpoints.

**Base URL:** `https://<branch-host>/v1`

This endpoint is also reachable at the longer `/ai-gateway/mlflow/v1/embeddings` path. Both behave identically and neither is deprecated. See [Shorter paths](https://neon.com/docs/ai-gateway/models#shorter-paths).

**Important: OpenAI JavaScript SDK v6: pass encoding_format: float**

On the `openai` JavaScript/TypeScript SDK **v6**, pass `encoding_format: "float"` on embedding calls (as shown below), or upgrade to v7 or later. Without it, v6 returns a broken all-zeros vector with no error. The Python SDK and raw HTTP are unaffected.

## Models

Three embedding models are available today. All return **1024-dimensional** vectors and are billed on **input tokens only**.

| Model ID                                                                               | Dimensions | Notes                                                                                                                                                      |
| -------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`qwen3-embedding-0-6b`](https://neon.com/docs/ai-gateway/models/qwen3-embedding-0-6b) | 1024       | Unit-normalized (L2 norm = 1), so dot product equals cosine similarity. Supports the `dimensions` parameter for shorter vectors.                           |
| [`bge-large-en`](https://neon.com/docs/ai-gateway/models/bge-large-en)                 | 1024       | Unit-normalized (L2 norm = 1), so dot product equals cosine similarity. Reads only the first 512 tokens of each input. Ignores the `dimensions` parameter. |
| [`gte-large-en`](https://neon.com/docs/ai-gateway/models/gte-large-en)                 | 1024       | Not normalized (L2 norm ≈ 24). Use cosine distance, or normalize the vectors yourself. Ignores the `dimensions` parameter.                                 |

Use the short model IDs shown above. The `databricks-` prefixed forms (`databricks-qwen3-embedding-0-6b`, `databricks-bge-large-en`, `databricks-gte-large-en`) are also accepted. Each model ID links to its catalog page, which lists the input price per million tokens and has copy-paste quickstarts in TypeScript, Python, and cURL.

## Setup

The examples use two environment variables:

```bash
NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://br-...
```

Run `neon env pull --file .env` to write both to your `.env` for the current branch (`neon deploy` and `neon config apply` also pull them). You can also copy them from the Neon Console's **Connect** panel, on the **AI Gateway** tab. Inside Neon Functions they're injected automatically. See [Authentication](https://neon.com/docs/ai-gateway/authentication) for details.

The examples below use the `openai` SDK. Install it with `npm install openai` or `pip install openai`.

## Basic request

**TypeScript (OpenAI SDK)**

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const response = await client.embeddings.create({
  model: 'qwen3-embedding-0-6b',
  input: 'The quick brown fox jumps over the lazy dog.',
  encoding_format: 'float', // required on the openai SDK v6; harmless on v7+
});

console.log(response.data[0].embedding.length); // 1024
```

**Python (OpenAI SDK)**

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

response = client.embeddings.create(
    model="qwen3-embedding-0-6b",
    input="The quick brown fox jumps over the lazy dog.",
)

print(len(response.data[0].embedding))  # 1024
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/v1/embeddings" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-embedding-0-6b",
    "input": "The quick brown fox jumps over the lazy dog."
  }'
```

## Response shape

The response is OpenAI-compatible: a list of embedding objects, one per input, each with the vector and its position.

```json
{
  "id": "...",
  "object": "list",
  "model": "qwen3-embedding-0-6b-112025",
  "data": [
    {
      "index": 0,
      "object": "embedding",
      "embedding": [-0.0149, 0.0172, -0.0119, "..."]
    }
  ],
  "usage": { "prompt_tokens": 11, "total_tokens": 11 }
}
```

The `model` field reports the resolved, versioned name that served the request (`qwen3-embedding-0-6b-112025` here), which is handy for logging. Keep sending the short model ID (`qwen3-embedding-0-6b`, `bge-large-en`, or `gte-large-en`) in your requests.

## Use with the Vercel AI SDK

For TypeScript apps and agents, [`@neon/ai-sdk-provider`](https://www.npmjs.com/package/@neon/ai-sdk-provider) exposes the gateway's embedding models to the [Vercel AI SDK](https://ai-sdk.dev). It reads `NEON_AI_GATEWAY_BASE_URL` and `NEON_AI_GATEWAY_TOKEN` (the same variables from [Setup](https://neon.com/docs/ai-gateway/embeddings#setup)), so no extra configuration is needed. Install it with `npm install @neon/ai-sdk-provider ai`.

```typescript
import { neon } from '@neon/ai-sdk-provider';
import { embed } from 'ai';

const { embedding } = await embed({
  model: neon.embeddingModel('qwen3-embedding-0-6b'),
  value: 'The quick brown fox jumps over the lazy dog.',
});

console.log(embedding.length); // 1024
```

Use `embedMany()` to embed a batch in one call. The gateway accepts up to 150 inputs per request (see [Batch input](https://neon.com/docs/ai-gateway/embeddings#batch-input)).

## Batch input

Pass an array of strings to embed many inputs in one request. The response returns one embedding per input, in the same order, with a matching `index`.

`bge-large-en` embeds only the first 512 tokens of each input and silently drops the rest, with no error (`usage.prompt_tokens` stops at 512). Split longer documents into chunks and send the chunks as a batch.

**TypeScript (OpenAI SDK)**

```typescript
const response = await client.embeddings.create({
  model: 'qwen3-embedding-0-6b',
  input: ['First document.', 'Second document.', 'Third document.'],
  encoding_format: 'float',
});

for (const item of response.data) {
  console.log(item.index, item.embedding.length);
}
```

**Python (OpenAI SDK)**

```python
response = client.embeddings.create(
    model="qwen3-embedding-0-6b",
    input=["First document.", "Second document.", "Third document."],
)

for item in response.data:
    print(item.index, len(item.embedding))
```

## Shorter vectors with `dimensions`

`qwen3-embedding-0-6b` supports the `dimensions` parameter to return a shorter, Matryoshka-style vector (for example `dimensions: 256`), which trades some accuracy for smaller storage and faster search. `bge-large-en` and `gte-large-en` ignore this parameter and always return 1024 dimensions.

```typescript
const response = await client.embeddings.create({
  model: 'qwen3-embedding-0-6b',
  input: 'A shorter embedding.',
  dimensions: 256,
  encoding_format: 'float',
});

console.log(response.data[0].embedding.length); // 256
```

## Choosing a distance operator

The models differ in how their vectors are scaled, which affects the pgvector operator class you index and query with:

- **`qwen3-embedding-0-6b`** and **`bge-large-en`** are unit-normalized (every vector has L2 norm 1), so cosine distance and inner product rank results identically. Cosine (`vector_cosine_ops`, `<=>`) is a safe default.
- **`gte-large-en`** is not normalized (L2 norm ≈ 24). Use cosine distance (`vector_cosine_ops`, `<=>`), which is scale-invariant, or normalize the vectors before storing them.

For an end-to-end example that stores AI Gateway embeddings in Postgres and searches them, see [Get started with Lakebase Search](https://neon.com/docs/ai/lakebase-search-get-started).

## Not supported

- **Streaming.** Embeddings don't stream. A request with `stream: true` returns `400`.
- **Wrong endpoint.** An embedding model called on a chat endpoint (or a chat model on this endpoint) is rejected. Send embedding requests to `/v1/embeddings`.

## Error handling

| Status                  | Meaning               | Common cause                                                                                                     |
| ----------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`       | Invalid request       | Unknown model ID, an embedding model used on a chat endpoint, or `stream: true`                                  |
| `401 Unauthorized`      | Authentication failed | Missing or invalid `NEON_AI_GATEWAY_TOKEN`                                                                       |
| `403 Forbidden`         | Access denied         | Credential lacks `ai_gateway:invoke` scope, or branch not in credential lineage                                  |
| `429 Too Many Requests` | Quota or rate limited | Account quota or per-minute token limit. See [Rate limits](https://neon.com/docs/ai-gateway/models#rate-limits). |

## Next steps

- [Get started with Lakebase Search](https://neon.com/docs/ai/lakebase-search-get-started): store and search AI Gateway embeddings in Postgres
- [Models](https://neon.com/docs/ai-gateway/models): full model catalog
- [Chat completions](https://neon.com/docs/ai-gateway/chat-completions): the OpenAI-compatible chat endpoint

--- [Document source](https://neon.com/docs/ai-gateway/gemini.md) ---

> Summary: The Gemini endpoint exposes the Google Gemini generateContent and streamGenerateContent APIs through Neon AI Gateway. Use the google-genai SDK with a custom base URL.

# Gemini API

Use the Google Gemini API with Neon AI Gateway

Last updated: 2026-10-23

The Gemini endpoint exposes the [Google Gemini API](https://ai.google.dev/api/generate-content) through Neon AI Gateway. Use it when you're already working with the `google-genai` SDK and want to keep your existing code. For most use cases, the [chat completions](https://neon.com/docs/ai-gateway/chat-completions) endpoint is simpler to set up and works with Gemini models via the OpenAI SDK.

**Supported actions:** `:generateContent` and `:streamGenerateContent`

**Endpoint pattern:** `https://<branch-host>/gemini/v1beta/models/<model>:<action>`

**Note:** Only `generateContent` and `streamGenerateContent` are supported. Requests to other actions (such as `countTokens`) return `404 unsupported gemini action`.

This endpoint is also reachable at the longer `/ai-gateway/gemini/v1beta/models/<model>:<action>` path. Both behave identically and neither is deprecated. See [Shorter paths](https://neon.com/docs/ai-gateway/models#shorter-paths) for the full list of aliases.

## Setup

Set these environment variables. See [Get started](https://neon.com/docs/ai-gateway/get-started) for how to obtain them.

```bash
NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://br-winter-pond-aptw82ef-api.ai.c-2.us-east-2.aws.neon.tech
```

## Supported models

This endpoint accepts Google models only:

| Model ID                | Notes                                                                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `gemini-4-argon`        | Supports `temperature` and `thinkingConfig.thinkingLevel` on this endpoint, but not on [chat completions](https://neon.com/docs/ai-gateway/chat-completions#switching-models). |
| `gemini-3-8-flash`      |                                                                                                                                                                                |
| `gemini-3-7-flash`      |                                                                                                                                                                                |
| `gemini-3-6-flash`      |                                                                                                                                                                                |
| `gemini-3-5-flash`      |                                                                                                                                                                                |
| `gemini-3-5-flash-lite` |                                                                                                                                                                                |
| `gemini-3-1-pro`        |                                                                                                                                                                                |
| `gemini-3-1-flash-lite` |                                                                                                                                                                                |
| `gemini-3-flash`        |                                                                                                                                                                                |

Sending a non-Google model ID returns `400 model "<model-id>" is not available on the gemini_generate_content endpoint`, naming whichever model you sent. Use the [chat completions endpoint](https://neon.com/docs/ai-gateway/chat-completions) if you want to call Gemini models alongside other providers from the same code.

## Basic request

**Note:** The `google-genai` SDK's `apiKey` option sends an `x-goog-api-key` header, but Neon AI Gateway expects `Authorization: Bearer <token>`. Set your credential as an explicit header instead, and pass any non-empty string as `apiKey` since the SDK requires the field even though the gateway ignores it.

**TypeScript (google-genai)**

```typescript
import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({
  apiKey: 'placeholder',
  httpOptions: {
    baseUrl: `${process.env.NEON_AI_GATEWAY_BASE_URL}/gemini`,
    headers: {
      Authorization: `Bearer ${process.env.NEON_AI_GATEWAY_TOKEN}`,
    },
  },
});

const response = await client.models.generateContent({
  model: 'gemini-3-flash',
  contents: [{ role: 'user', parts: [{ text: 'What is Neon?' }] }],
});

console.log(response.text);
```

**Python (google-genai)**

```python
from google import genai
from google.genai import types
import os

client = genai.Client(
    api_key='placeholder',
    http_options=types.HttpOptions(
        base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/gemini",
        headers={'Authorization': f"Bearer {os.environ['NEON_AI_GATEWAY_TOKEN']}"},
    ),
)

response = client.models.generate_content(
    model='gemini-3-flash',
    contents='What is Neon?',
)

print(response.text)
```

**cURL**

```bash
curl -X POST \
  "$NEON_AI_GATEWAY_BASE_URL/gemini/v1beta/models/gemini-3-flash:generateContent" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "What is Neon?"}]}]
  }'
```

## Streaming

**TypeScript (google-genai)**

```typescript
const stream = await client.models.generateContentStream({
  model: 'gemini-3-flash',
  contents: [{ role: 'user', parts: [{ text: 'Explain database branching.' }] }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? '');
}
```

**Python (google-genai)**

```python
for chunk in client.models.generate_content_stream(
    model='gemini-3-flash',
    contents='Explain database branching.',
):
    print(chunk.text, end='', flush=True)
```

## URL structure

The gateway uses the model ID and action directly in the URL path. The `google-genai` SDK constructs this automatically from the base URL and model parameter:

```
base_url: https://<branch-host>/gemini
model:    gemini-3-flash
action:   generateContent or streamGenerateContent

→ https://<branch-host>/gemini/v1beta/models/gemini-3-flash:generateContent
→ https://<branch-host>/gemini/v1beta/models/gemini-3-flash:streamGenerateContent
```

When calling the REST API directly, the model ID and action must appear in the path as shown above.

## Error handling

| Status            | Message                                                                       | Cause                                                                 |
| ----------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `400 Bad Request` | `unknown model "<model-id>"`                                                  | Model ID not in the catalog                                           |
| `400 Bad Request` | `model "<model-id>" is not available on the gemini_generate_content endpoint` | Non-Google model sent to this endpoint                                |
| `404 Not Found`   | `unsupported gemini action`                                                   | Action other than `generateContent` or `streamGenerateContent` in URL |
| `404 Not Found`   | `invalid gemini model path`                                                   | Malformed `model:action` segment in URL                               |

For authentication, quota, and upstream errors, see [Troubleshooting](https://neon.com/docs/ai-gateway/troubleshooting).

## Next steps

- [Models](https://neon.com/docs/ai-gateway/models): full model catalog
- [Chat completions](https://neon.com/docs/ai-gateway/chat-completions): use Gemini models via the unified OpenAI-compatible endpoint
- [Authentication](https://neon.com/docs/ai-gateway/authentication): credential scopes and branch binding

--- [Document source](https://neon.com/docs/ai-gateway/get-started.md) ---

> Summary: This quickstart walks you through getting a credential, finding your branch host, and making your first request to the Neon AI Gateway using the OpenAI SDK. No provider API keys required. Authenticate with your Neon credential.

# Get started with Neon AI Gateway

Make your first inference request in minutes

Last updated: 2026-10-01

To set up Neon AI Gateway with an AI coding assistant, install the Neon Platform (`neon`) and Neon AI Gateway skills with the [Neon CLI](https://neon.com/docs/cli):

```bash
neon skills -s neon -s neon-ai-gateway
```

Without the Neon CLI, run `npx skills add neondatabase/agent-skills -s neon -s neon-ai-gateway` instead.

## Get access

You need a project in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). Using the AI Gateway requires prepaid credits, which you can buy on any Neon plan, including Free. Credits give you every model in the catalog. See [Model access](https://neon.com/docs/ai-gateway/models#model-access) for details.

## Create a credential

With the [Neon CLI](https://neon.com/docs/cli/credentials), run:

```bash
neon credentials create --scope ai_gateway:invoke
```

Or, in the Neon Console, click **Connect** at the top of the sidebar and open the **AI Gateway** tab. Click **Reveal credential** to show `NEON_AI_GATEWAY_TOKEN`, or **Copy snippet** to copy it together with `NEON_AI_GATEWAY_BASE_URL`. Use **Rotate credential** to issue a new token.

Or use the API:

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["ai_gateway:invoke"], "principal_type": "user"}'
```

**Using neon.ts?:**

If your project has a `neon.ts` file, run [`neon config add ai-gateway`](https://neon.com/docs/cli/config#add) (or declare `aiGateway: true` yourself) and then `neon deploy`. Credentials are provisioned and pulled into your local `.env` automatically, with no manual creation step. See [Authentication](https://neon.com/docs/ai-gateway/authentication) for details.

Store the credential as an environment variable:

```bash
export NEON_AI_GATEWAY_TOKEN=nt_live_...
```

## Find your branch host

Your branch's AI Gateway host is available in the Neon Console from the **Connect** dialog's **AI Gateway** tab, or via the Neon API. It follows this format:

```
br-<name>-api.ai.<cell>.<region>.aws.neon.tech
```

For example:

```bash
export NEON_AI_GATEWAY_BASE_URL=https://br-winter-pond-aptw82ef-api.ai.c-2.us-east-2.aws.neon.tech
```

This is different from your database connection string.

## Install dependencies

The quickstart uses the OpenAI SDK because the chat completions endpoint is OpenAI-compatible. It works with any model in the catalog, including GPT and Gemini.

**npm**

```bash
npm install openai dotenv
```

**yarn**

```bash
yarn add openai dotenv
```

**pnpm**

```bash
pnpm add openai dotenv
```

**pip**

```bash
pip install openai python-dotenv
```

## Make your first request

The chat completions endpoint is OpenAI-compatible. Set `baseURL` to your branch host and `apiKey` to your credential. No other changes needed.

**TypeScript**

```typescript
import OpenAI from 'openai';
import 'dotenv/config';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const response = await client.chat.completions.create({
  model: 'gpt-5-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
});

console.log(response.choices[0].message.content);
```

**Python**

```python
from openai import OpenAI
from dotenv import load_dotenv
import os

load_dotenv()

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "Hello!"}],
)

print(response.choices[0].message.content)
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## Stream a response

Add `stream: true` to receive a streamed response. Your existing streaming code works without changes. The gateway forwards `text/event-stream` responses from the upstream provider.

**TypeScript**

```typescript
import OpenAI from 'openai';
import 'dotenv/config';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const stream = await client.chat.completions.create({
  model: 'gpt-5-mini',
  messages: [{ role: 'user', content: 'Write a haiku about serverless databases.' }],
  stream: true,
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? '');
}
```

**Python**

```python
from openai import OpenAI
from dotenv import load_dotenv
import os

load_dotenv()

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

with client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "Write a haiku about serverless databases."}],
    stream=True,
) as stream:
    for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [{"role": "user", "content": "Write a haiku about serverless databases."}],
    "stream": true
  }'
```

## Swap models

Change the `model` field to use a different provider. No other code changes required.

```typescript
// OpenAI
model: 'gpt-5-mini'

// Google
model: 'gemini-3-flash'

// Alibaba
model: 'qwen3-next-80b-a3b-instruct'
```

See [Models](https://neon.com/docs/ai-gateway/models) for the full list of available model IDs.

**Using the AI SDK?:**

For TypeScript apps and agents, use [`@neon/ai-sdk-provider`](https://www.npmjs.com/package/@neon/ai-sdk-provider) with the Vercel AI SDK. It reads `NEON_AI_GATEWAY_BASE_URL` and `NEON_AI_GATEWAY_TOKEN`, then routes each catalog model to the best AI Gateway endpoint for that provider.

## Next steps

- [Models](https://neon.com/docs/ai-gateway/models): full model catalog and which endpoint to use per provider
- [Chat completions](https://neon.com/docs/ai-gateway/chat-completions): detailed reference for the unified endpoint
- [Authentication](https://neon.com/docs/ai-gateway/authentication): credential scopes, branch binding, and rotation

--- [Document source](https://neon.com/docs/ai-gateway/models.md) ---

> Summary: Reference for Neon AI Gateway: model access and how to request foundation models, which endpoint to use, shorter and longer request paths, the /v1/models API, rate limits, pricing, and provider terms.

# Model reference

How to call models through AI Gateway, with the endpoints, limits, and rules that apply

Last updated: 2026-11-04

This page covers how to call models through Neon AI Gateway and the rules that apply. For the full list of models you can call, see the [model catalog](https://neon.com/ai-gateway#models).

> **See every model on Neon AI Gateway**
>
> Compare every available model by lab, inputs, context window, and pricing.
>
> [Browse all models](https://neon.com/ai-gateway#models)

Neon AI Gateway serves models from many providers behind one credential. Use short model IDs in the `model` field, for example `gpt-5-mini` or `gemini-3-flash`. The `databricks-` prefixed form is also accepted. The Neon Console and most examples use the short form.

**Important:** Most models are served through Databricks. Jev is the exception: TypeSafe AI, which made it, also hosts it. [Provider terms](https://neon.com/docs/ai-gateway/models#provider-terms) links each provider's terms and notes where hosting differs. Wherever a model is hosted, you're responsible for complying with its provider's terms of use.

Model availability may vary by region, and the catalog expands over time, so check back for new additions.

> AI Gateway is currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Create your project in one of these regions to use it. Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). It's available on any Neon plan with prepaid credits. See [Pricing](https://neon.com/docs/ai-gateway/models#pricing) for details.

The full catalog is served as JSON at [`neon.com/models.json`](https://neon.com/models.json), the machine-readable source of truth, and mirrored as the [`neon` provider on models.dev](https://models.dev/providers/neon). Each model lists its `lab`, the organization that made it, and its `provider`, the organization that provides it: Databricks for every model except Jev, which TypeSafe AI hosts. Both field names follow models.dev.

Every model in the catalog carries a `released` boolean. `false` marks a model listed ahead of its announcement: it stays in `neon.com/models.json` and `neon.com/models`, and an app that shows a model list should leave it out:

```js
const models = Object.values(catalog.neon.models).filter((model) => model.released);
```

## Model access

Neon AI Gateway gives you one credential for both open-weight and foundation models. Any account with prepaid credits can use every model in the catalog, on any plan. The [model catalog](https://neon.com/docs/ai-gateway/overview#available-models) is always the source of truth for what you can call today.

## Rate limits

The following limits apply per account. Input and output tokens are limited separately:

| Limit                          | Value   |
| ------------------------------ | ------- |
| Input tokens per minute (TPM)  | 200,000 |
| Output tokens per minute (TPM) | 200,000 |

If you hit the limit, you'll receive a `429 Too Many Requests` response with a message that starts with `You've exceeded your AI Gateway input token limit for model "<model-id>"`. Requests resume when the rate limit window resets.

The TPM limit applies to input tokens and output tokens separately. Each direction has its own limit, so using up your output allowance doesn't use up your input allowance. Upstream output token limits (20,000 OTPM for most models) apply independently, so you can hit a `429` on output tokens without reaching the gateway's TPM limit. See [Databricks Foundation Model API limits](https://docs.databricks.com/aws/en/machine-learning/foundation-model-apis/limits) for details.

Both 200,000 TPM limits are soft limits. If you need a higher limit, [contact Support](https://neon.com/docs/introduction/support).

A separate account-level daily spend cap also applies and can block AI Gateway requests with a `429` / `REQUEST_LIMIT_EXCEEDED`. It isn't a fixed published number and can vary by account. See [Pricing](https://neon.com/docs/ai-gateway/models#pricing) for details, or [Troubleshooting](https://neon.com/docs/ai-gateway/troubleshooting#429-account-quota-exceeded) if you hit it.

## Pricing

AI Gateway usage draws down a prepaid credit balance. Here's how pricing works:

- **Any plan.** AI Gateway is available on every Neon plan, including Free, with no difference in pricing or model access between plans. On the Free plan, you add a payment card to buy credits and your organization stays on Free. Any account with prepaid credits can use every model in the catalog. See [Model access](https://neon.com/docs/ai-gateway/models#model-access) for details.
- **No markup.** Neon charges the same per-token rate as the model provider. Published provider prices are passed on to users with no additional markup.
- **Prepaid credits.** Inference draws down a prepaid credit balance. 1 credit equals $1 USD, with a $5 minimum purchase, and credits are valid for 12 months from purchase. You buy credits from the **Billing** page in the [Neon Console](https://console.neon.tech/app/billing).

See the [model catalog](https://neon.com/docs/ai-gateway/overview#available-models) for per-model rates, and [AI Gateway prepaid credits](https://neon.com/docs/ai-gateway/prepaid-credits) for how to buy credits and manage your balance.

Independent of billing, Neon enforces an account-level daily spend cap on AI Gateway usage, separate from the per-minute rate limits above. If your account exceeds it, every AI Gateway endpoint returns `429 Too Many Requests` with error code `REQUEST_LIMIT_EXCEEDED` until the cap resets or the block is lifted. The cap is $20 per day by default, but it may vary by account. To have it raised, [contact Support](https://neon.com/docs/introduction/support). See [Troubleshooting](https://neon.com/docs/ai-gateway/troubleshooting#429-account-quota-exceeded) if you hit this.

## Which endpoint to use

Most models work with the [Chat completions](https://neon.com/docs/ai-gateway/chat-completions) endpoint. It is the recommended starting point and works with all providers. Use a provider-specific endpoint when required:

All paths below are appended to your branch's bare AI Gateway host (`NEON_AI_GATEWAY_BASE_URL`).

| Provider                                | Recommended endpoint     | Notes                                                                                                                    |
| --------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| OpenAI (most models)                    | `/v1/chat/completions`   | Use `/openai/v1/responses` for Responses API features                                                                    |
| OpenAI (`gpt-5-3-codex`, `gpt-5-5-pro`) | `/openai/v1/responses`   | These models require the Responses API and don't work with chat/completions                                              |
| Anthropic Claude                        | `/v1/chat/completions`   | Use `/anthropic/v1/messages` with the Anthropic SDK for extended thinking and prompt caching                             |
| Google Gemini                           | `/v1/chat/completions`   | Use `/gemini/v1beta/models/{model}:generateContent` with the google-genai SDK                                            |
| Google Gemma 3 12B                      | `/v1/chat/completions`   | Chat completions only. Doesn't support the Gemini SDK endpoint                                                           |
| Meta, Zhipu AI, Moonshot AI             | `/v1/chat/completions`   | Chat completions only                                                                                                    |
| Alibaba (chat models)                   | `/v1/chat/completions`   | Chat completions only                                                                                                    |
| Alibaba, BAAI (embedding models)        | `/v1/embeddings`         | No chat completions. Returns a vector, not text                                                                          |
| TypeSafe AI (decision models)           | `/typesafe/v1/systemone` | No chat completions. Returns answers to questions, not text. See [Decisions](https://neon.com/docs/ai-gateway/decisions) |

**Warning: Content shape varies by model**

For most models, `message.content` in a chat completions response is a plain string. For `claude-opus-5-5`, it's an array of typed content blocks once the model reasons (`{ type: 'reasoning', ... }`, `{ type: 'text', text: ... }`); a trivial prompt still returns a string. For `gemini-4-argon`, it's an array of `text` blocks, even for a trivial prompt. A low `max_tokens` value can also cut a response off before the `text` block appears, leaving only a `reasoning` block. Handle both shapes:

```typescript
// The OpenAI SDK types content as string | null, so read it as unknown.
const content: unknown = response.choices[0].message.content;
const text =
  typeof content === 'string'
    ? content
    : Array.isArray(content)
      ? (content.find((block) => block?.type === 'text')?.text ?? '')
      : '';
```

## Shorter paths

Each inference dialect is reachable at two equivalent paths: a shorter top-level path (recommended, and what most examples and the `@neon/ai-sdk-provider` use) and a longer `/ai-gateway/<dialect>/v1` path. Both forms behave identically, using the same branch host, bearer token, request body, response body, model routing, rate limits, and quota, and **neither is deprecated**. The longer `/ai-gateway/...` paths keep working indefinitely.

The shorter form isn't a uniform `/v1/<dialect>` rule. The unified chat completions endpoint is a bare `/v1/chat/completions`, matching the OpenAI and OpenRouter convention. The native dialects are prefixed by provider instead, and each keeps its own upstream version segment so the path matches what that provider's SDK expects: `/openai/v1/...`, `/anthropic/v1/...`, and `/gemini/v1beta/...`.

Decisions are the exception: they're served only at `/typesafe/v1/systemone`.

Use the shorter paths when you want OpenAI/OpenRouter-style URLs. Use the `/ai-gateway/...` paths when a framework or existing Neon example expects the older dialect-specific route.

| Shorter path                                         | Equivalent to                                              |
| ---------------------------------------------------- | ---------------------------------------------------------- |
| `POST /v1/chat/completions`                          | `/ai-gateway/mlflow/v1/chat/completions`                   |
| `POST /openai/v1/responses`                          | `/ai-gateway/openai/v1/responses`                          |
| `POST /anthropic/v1/messages`                        | `/ai-gateway/anthropic/v1/messages`                        |
| `POST /gemini/v1beta/models/{model}:generateContent` | `/ai-gateway/gemini/v1beta/models/{model}:generateContent` |

### List available models

`GET /v1/models` lists the model catalog in an OpenRouter-shaped response, authenticated the same way as the endpoints above. Unlike the inference dialects, the model list has only this `/v1/models` path, with no `/ai-gateway/...` form. Decision models are also listed at `GET /typesafe/v1/models`; see [Decisions](https://neon.com/docs/ai-gateway/decisions#list-the-models).

```bash
curl "$NEON_AI_GATEWAY_BASE_URL/v1/models" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN"
```

```json
{
  "object": "list",
  "data": [
    {
      "id": "gpt-5-mini",
      "canonical_slug": "gpt-5-mini",
      "name": "GPT-5 Mini",
      "object": "model",
      "owned_by": "openai",
      "created": 0,
      "enabled": true,
      "context_length": null,
      "architecture": {
        "modality": "text->text",
        "input_modalities": ["text"],
        "output_modalities": ["text"],
        "tokenizer": "GPT",
        "instruct_type": null
      },
      "top_provider": {
        "is_moderated": false,
        "context_length": null,
        "max_completion_tokens": null
      },
      "pricing": null,
      "per_request_limits": null
    }
  ]
}
```

The response returns one object per model. Key fields:

- `enabled` is whether the model is currently callable. Any account with prepaid credits can call every model in the catalog. See [Model access](https://neon.com/docs/ai-gateway/models#model-access) for details.
- `id`, `name`, and `owned_by` identify the model. Use `id` (or its `databricks-` prefixed form) in the `model` field of a request.
- `canonical_slug`, `architecture`, and `top_provider` are OpenRouter-compatible descriptive fields.
- `created` is always `0`, and `pricing`, `per_request_limits`, and `context_length` are currently always `null`. Use the [model catalog](https://neon.com/docs/ai-gateway/overview#available-models) for context windows and model details.

### Check what your account can call

To list only the models your account can call, filter on `enabled`:

```bash
curl "$NEON_AI_GATEWAY_BASE_URL/v1/models" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  | jq -r '.data[] | select(.enabled) | .id'
```

## Provider terms

Review a model's provider terms before you use it. You're responsible for complying with them, including any acceptable-use restrictions and license requirements.

| Provider          | Terms                                                                                                                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| OpenAI            | [OpenAI Usage Policies](https://openai.com/policies/usage-policies)                                                                                                                  |
| Google Gemini     | [Google Cloud Acceptable Use Policy](https://cloud.google.com/terms/aup) · [Google Generative AI Prohibited Use Policy](https://policies.google.com/terms/generative-ai/use-policy)  |
| Google Gemma      | [Gemma Terms of Use](https://ai.google.dev/gemma/terms) · [Gemma Prohibited Use Policy](https://ai.google.dev/gemma/prohibited_use_policy)                                           |
| Meta              | Terms differ by Llama version. See the Notes column in the [models catalog](https://neon.com/docs/ai-gateway/overview#available-models).                                             |
| TypeSafe AI (Jev) | [Terms of use](https://typesafe.ai/legal/terms) · [Data processing addendum](https://typesafe.ai/legal/data-processing) · [Privacy policy](https://typesafe.ai/legal/privacy-policy) |

Jev is hosted by TypeSafe AI, Inc. and served through Neon AI Gateway. Neon provides access, authentication, and routing, and TypeSafe AI operates the environment the model runs in. OpenJev, the open-weight decision model, is hosted by Databricks. See [Decisions](https://neon.com/docs/ai-gateway/decisions#models).

**Important:** Use of AI Gateway is subject to our Terms of Service. Access is not available to users, organizations, or entities located in or operating from regions restricted by Anthropic's [Supported Regions Policy](https://www.anthropic.com/supported-countries). This restriction also applies to entities that are majority owned, directly or indirectly, by companies headquartered in unsupported regions.

For what Databricks and model providers retain, see [Data retention](https://neon.com/docs/ai-gateway/data-retention).

--- [Document source](https://neon.com/docs/ai-gateway/models/bge-large-en.md) ---

# BGE Large (En)

## About

Neon AI Gateway provides BGE Large (En) by BAAI. It returns 1024-dimensional embeddings on `POST /v1/embeddings`.

## Command

### Embeddings

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.embeddings.create({
  model: "bge-large-en",
  input: ["Explain Serverless Postgres."],
  encoding_format: "float",
});
console.log(resp.data[0].embedding.length, resp.usage);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.embeddings.create(
    model="bge-large-en",
    input=["Explain Serverless Postgres."],
    encoding_format="float",
)
print(len(resp.data[0].embedding), resp.usage)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/embeddings" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-large-en",
    "input": ["Explain Serverless Postgres."],
    "encoding_format": "float"
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

bge-large-en

## Lab

BAAI makes BGE Large (En). Access it through the Neon AI Gateway's `POST /v1/embeddings` endpoint.

## Provider

Databricks

## Dimensions

1024

## Released

Sep 2023

## Input /M

$0.10

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-fable-5-1.md) ---

# Claude Fable 5.1

## About

Neon AI Gateway provides Claude Fable 5.1 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-fable-5-1"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-fable-5-1",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-fable-5-1",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-fable-5-1",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5-1",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-fable-5-1

## Lab

Anthropic makes Claude Fable 5.1. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Sep 2026

## Input /M

$10

## Output /M

$50

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-fable-5.md) ---

# Claude Fable 5

## About

Neon AI Gateway provides Claude Fable 5 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-fable-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-fable-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-fable-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-fable-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-fable-5

## Lab

Anthropic makes Claude Fable 5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Jun 2026

## Input /M

$10

## Output /M

$50

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-haiku-4-5.md) ---

# Claude Haiku 4.5

## About

Neon AI Gateway provides Claude Haiku 4.5 by Anthropic. The model supports text, image, pdf inputs and a 200K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-haiku-4-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-haiku-4-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-haiku-4-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-haiku-4-5

## Lab

Anthropic makes Claude Haiku 4.5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

200K

## Released

Oct 2025

## Input /M

$1

## Output /M

$5

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-haiku-5-5.md) ---

# Claude Haiku 5.5

## About

Neon AI Gateway provides Claude Haiku 5.5 by Anthropic. The model supports text, image, pdf inputs and a 200K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-haiku-5-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: neon("claude-haiku-5-5"),
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/anthropic/v1/messages" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-haiku-5-5

## Lab

Anthropic makes Claude Haiku 5.5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

200K

## Released

Oct 2026

## Input /M

$0.10

## Output /M

$0.50

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-opus-4-1.md) ---

# Claude Opus 4.1

## About

Neon AI Gateway provides Claude Opus 4.1 by Anthropic. The model supports text, image, pdf inputs and a 200K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-opus-4-1"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-opus-4-1",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-opus-4-1",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-4-1",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-1",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-opus-4-1

## Lab

Anthropic makes Claude Opus 4.1. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

200K

## Released

Aug 2025

## Input /M

$15

## Output /M

$75

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-opus-4-5.md) ---

# Claude Opus 4.5

## About

Neon AI Gateway provides Claude Opus 4.5 by Anthropic. The model supports text, image, pdf inputs and a 200K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-opus-4-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-opus-4-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-opus-4-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-4-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-opus-4-5

## Lab

Anthropic makes Claude Opus 4.5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

200K

## Released

Nov 2025

## Input /M

$5

## Output /M

$25

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-opus-4-6.md) ---

# Claude Opus 4.6

## About

Neon AI Gateway provides Claude Opus 4.6 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-opus-4-6"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-opus-4-6",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-opus-4-6",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-4-6",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-6",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-opus-4-6

## Lab

Anthropic makes Claude Opus 4.6. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Feb 2026

## Input /M

$5

## Output /M

$25

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-opus-4-7.md) ---

# Claude Opus 4.7

## About

Neon AI Gateway provides Claude Opus 4.7 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-opus-4-7"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-opus-4-7",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-opus-4-7",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-4-7",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-opus-4-7

## Lab

Anthropic makes Claude Opus 4.7. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Apr 2026

## Input /M

$5

## Output /M

$25

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-opus-4-8.md) ---

# Claude Opus 4.8

## About

Neon AI Gateway provides Claude Opus 4.8 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-opus-4-8"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-opus-4-8",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-opus-4-8",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-4-8",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-opus-4-8

## Lab

Anthropic makes Claude Opus 4.8. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

May 2026

## Input /M

$5

## Output /M

$25

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-opus-5-5.md) ---

# Claude Opus 5.5

## About

Neon AI Gateway provides Claude Opus 5.5 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-opus-5-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: neon("claude-opus-5-5"),
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/anthropic/v1/messages" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-opus-5-5

## Lab

Anthropic makes Claude Opus 5.5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Sep 2026

## Input /M

$4

## Output /M

$20

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-opus-5.md) ---

# Claude Opus 5

## About

Neon AI Gateway provides Claude Opus 5 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-opus-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-opus-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-opus-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-opus-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-opus-5

## Lab

Anthropic makes Claude Opus 5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Jul 2026

## Input /M

$5

## Output /M

$25

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-sonnet-4-5.md) ---

# Claude Sonnet 4.5

## About

Neon AI Gateway provides Claude Sonnet 4.5 by Anthropic. The model supports text, image, pdf inputs and a 200K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-sonnet-4-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-sonnet-4-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-sonnet-4-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-sonnet-4-5

## Lab

Anthropic makes Claude Sonnet 4.5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

200K

## Released

Sep 2025

## Input /M

$3

## Output /M

$15

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-sonnet-4-6.md) ---

# Claude Sonnet 4.6

## About

Neon AI Gateway provides Claude Sonnet 4.6 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-sonnet-4-6"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-sonnet-4-6",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-sonnet-4-6",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-sonnet-4-6

## Lab

Anthropic makes Claude Sonnet 4.6. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Feb 2026

## Input /M

$3

## Output /M

$15

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-sonnet-5-5.md) ---

# Claude Sonnet 5.5

## About

Neon AI Gateway provides Claude Sonnet 5.5 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-sonnet-5-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-sonnet-5-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-sonnet-5-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-sonnet-5-5

## Lab

Anthropic makes Claude Sonnet 5.5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Sep 2026

## Input /M

$2

## Output /M

$10

--- [Document source](https://neon.com/docs/ai-gateway/models/claude-sonnet-5.md) ---

# Claude Sonnet 5

## About

Neon AI Gateway provides Claude Sonnet 5 by Anthropic. The model supports text, image, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("claude-sonnet-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/claude-sonnet-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

claude-sonnet-5

## Lab

Anthropic makes Claude Sonnet 5. Access the model through the Neon AI Gateway using chat/completions and anthropic/messages.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1M

## Released

Jun 2026

## Input /M

$2

## Output /M

$10

--- [Document source](https://neon.com/docs/ai-gateway/models/deepseek-v4-1-flash.md) ---

# DeepSeek V4.1 Flash

## About

Neon AI Gateway provides DeepSeek V4.1 Flash by DeepSeek. The model supports text, image inputs and a 128K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("deepseek-v4-1-flash"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/deepseek-v4-1-flash",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "deepseek-v4-1-flash",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="deepseek-v4-1-flash",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-1-flash",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

deepseek-v4-1-flash

## Lab

DeepSeek makes DeepSeek V4.1 Flash. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text, image

## Context

128K

## Released

Sep 2026

## Input /M

$0.30

## Output /M

$1.20

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-3-1-flash-lite.md) ---

# Gemini 3.1 Flash Lite

## About

Neon AI Gateway provides Gemini 3.1 Flash Lite by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-3-1-flash-lite"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gemini-3-1-flash-lite",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gemini-3-1-flash-lite",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-1-flash-lite",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-1-flash-lite",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-3-1-flash-lite

## Lab

Google makes Gemini 3.1 Flash Lite. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

Mar 2026

## Input /M

$0.25

## Output /M

$1.50

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-3-1-pro.md) ---

# Gemini 3.1 Pro

## About

Neon AI Gateway provides Gemini 3.1 Pro by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-3-1-pro"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gemini-3-1-pro",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gemini-3-1-pro",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-1-pro",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-1-pro",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-3-1-pro

## Lab

Google makes Gemini 3.1 Pro. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

Feb 2026

## Input /M

$2

## Output /M

$12

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-3-5-flash-lite.md) ---

# Gemini 3.5 Flash Lite

## About

Neon AI Gateway provides Gemini 3.5 Flash Lite by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-3-5-flash-lite"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gemini-3-5-flash-lite",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gemini-3-5-flash-lite",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-5-flash-lite",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-5-flash-lite",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-3-5-flash-lite

## Lab

Google makes Gemini 3.5 Flash Lite. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

Jul 2026

## Input /M

$0.30

## Output /M

$2.50

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-3-5-flash.md) ---

# Gemini 3.5 Flash

## About

Neon AI Gateway provides Gemini 3.5 Flash by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-3-5-flash"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gemini-3-5-flash",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gemini-3-5-flash",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-5-flash",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-5-flash",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-3-5-flash

## Lab

Google makes Gemini 3.5 Flash. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

May 2026

## Input /M

$1.50

## Output /M

$9

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-3-6-flash.md) ---

# Gemini 3.6 Flash

## About

Neon AI Gateway provides Gemini 3.6 Flash by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-3-6-flash"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gemini-3-6-flash",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gemini-3-6-flash",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-6-flash",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-6-flash",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-3-6-flash

## Lab

Google makes Gemini 3.6 Flash. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

Jul 2026

## Input /M

$1.50

## Output /M

$7.50

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-3-7-flash.md) ---

# Gemini 3.7 Flash

## About

Neon AI Gateway provides Gemini 3.7 Flash by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-3-7-flash"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: neon("gemini-3-7-flash"),
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/gemini/v1beta/models/gemini-3-7-flash:generateContent" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Explain Serverless Postgres."}]}
    ]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-3-7-flash

## Lab

Google makes Gemini 3.7 Flash. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

Aug 2026

## Input /M

$1.50

## Output /M

$7.50

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-3-8-flash.md) ---

# Gemini 3.8 Flash

## About

Neon AI Gateway provides Gemini 3.8 Flash by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-3-8-flash"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: neon("gemini-3-8-flash"),
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/gemini/v1beta/models/gemini-3-8-flash:generateContent" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Explain Serverless Postgres."}]}
    ]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-3-8-flash

## Lab

Google makes Gemini 3.8 Flash. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

Sep 2026

## Input /M

$1.50

## Output /M

$7.50

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-3-flash.md) ---

# Gemini 3 Flash

## About

Neon AI Gateway provides Gemini 3 Flash by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-3-flash"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gemini-3-flash",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gemini-3-flash",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gemini-3-flash",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-flash",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-3-flash

## Lab

Google makes Gemini 3 Flash. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

Dec 2025

## Input /M

$0.50

## Output /M

$3

--- [Document source](https://neon.com/docs/ai-gateway/models/gemini-4-argon.md) ---

# Gemini 4 Argon

## About

Neon AI Gateway provides Gemini 4 Argon by Google. The model supports text, image, video, audio, pdf inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemini-4-argon"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: neon("gemini-4-argon"),
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/gemini/v1beta/models/gemini-4-argon:generateContent" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Explain Serverless Postgres."}]}
    ]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemini-4-argon

## Lab

Google makes Gemini 4 Argon. Access the model through the Neon AI Gateway using chat/completions and gemini.

## Provider

Databricks

## Inputs

Text, image, video, audio, pdf

## Context

1M

## Released

Oct 2026

## Input /M

$4

## Output /M

$20

--- [Document source](https://neon.com/docs/ai-gateway/models/gemma-3-12b.md) ---

# Gemma 3 12B

## About

Neon AI Gateway provides Gemma 3 12B by Google. The model supports text, image inputs and a 131K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gemma-3-12b"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gemma-3-12b",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gemma-3-12b",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gemma-3-12b",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemma-3-12b",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gemma-3-12b

## Lab

Google makes Gemma 3 12B. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text, image

## Context

131K

## Released

Mar 2025

## Input /M

$0.15

## Output /M

$0.50

--- [Document source](https://neon.com/docs/ai-gateway/models/glm-5-2.md) ---

# GLM 5.2

## About

Neon AI Gateway provides GLM 5.2 by Zhipu AI. The model supports text inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("glm-5-2"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/glm-5-2",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "glm-5-2",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="glm-5-2",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5-2",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

glm-5-2

## Lab

Zhipu AI makes GLM 5.2. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text

## Context

1M

## Released

Jun 2026

## Input /M

$1.40

## Output /M

$4.40

--- [Document source](https://neon.com/docs/ai-gateway/models/glm-5-3-flash.md) ---

# GLM 5.3 Flash

## About

Neon AI Gateway provides GLM 5.3 Flash by Zhipu AI. The model supports text, image inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("glm-5-3-flash"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/glm-5-3-flash",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "glm-5-3-flash",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="glm-5-3-flash",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5-3-flash",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

glm-5-3-flash

## Lab

Zhipu AI makes GLM 5.3 Flash. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text, image

## Context

1M

## Released

Aug 2026

## Input /M

$0.15

## Output /M

$0.50

--- [Document source](https://neon.com/docs/ai-gateway/models/glm-5-3.md) ---

# GLM 5.3

## About

Neon AI Gateway provides GLM 5.3 by Zhipu AI. The model supports text inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("glm-5-3"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/glm-5-3",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "glm-5-3",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="glm-5-3",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5-3",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

glm-5-3

## Lab

Zhipu AI makes GLM 5.3. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text

## Context

1M

## Released

Aug 2026

## Input /M

$1.40

## Output /M

$4.40

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-1.md) ---

# GPT-5.1

## About

Neon AI Gateway provides GPT-5.1 by OpenAI. The model supports text, image inputs and a 400K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-1"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-1",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-1",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-1",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-1",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-1"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-1",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-1",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-1",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-1

## Lab

OpenAI makes GPT-5.1. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image

## Context

400K

## Released

Nov 2025

## Input /M

$1.25

## Output /M

$10

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-2.md) ---

# GPT-5.2

## About

Neon AI Gateway provides GPT-5.2 by OpenAI. The model supports text, image inputs and a 400K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-2"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-2",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-2",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-2",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-2",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-2"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-2",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-2",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-2",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-2

## Lab

OpenAI makes GPT-5.2. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image

## Context

400K

## Released

Dec 2025

## Input /M

$1.75

## Output /M

$14

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-3-codex.md) ---

# GPT-5.3 Codex

## About

Neon AI Gateway provides GPT-5.3 Codex by OpenAI. The model supports text, image, pdf inputs and a 400K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-3-codex"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: neon("gpt-5-3-codex"),
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const response = await client.responses.create({
  model: "gpt-5-3-codex",
  input: "Explain Serverless Postgres.",
});
console.log(response.output_text);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

response = client.responses.create(
    model="gpt-5-3-codex",
    input="Explain Serverless Postgres.",
)
print(response.output_text)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/openai/v1/responses" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-3-codex",
    "input": "Explain Serverless Postgres."
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-3-codex"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-3-codex",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-3-codex",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-3-codex",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-3-codex

## Lab

OpenAI makes GPT-5.3 Codex. Access the model through the Neon AI Gateway using openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

400K

## Released

Feb 2026

## Input /M

$1.75

## Output /M

$14

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-4-mini.md) ---

# GPT-5.4 Mini

## About

Neon AI Gateway provides GPT-5.4 Mini by OpenAI. The model supports text, image inputs and a 400K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-4-mini"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-4-mini",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-4-mini",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-4-mini",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4-mini",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-4-mini"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-4-mini",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-4-mini",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-4-mini",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-4-mini

## Lab

OpenAI makes GPT-5.4 Mini. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image

## Context

400K

## Released

Mar 2026

## Input /M

$0.75

## Output /M

$4.50

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-4-nano.md) ---

# GPT-5.4 Nano

## About

Neon AI Gateway provides GPT-5.4 Nano by OpenAI. The model supports text, image inputs and a 400K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-4-nano"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-4-nano",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-4-nano",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-4-nano",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4-nano",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-4-nano"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-4-nano",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-4-nano",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-4-nano",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-4-nano

## Lab

OpenAI makes GPT-5.4 Nano. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image

## Context

400K

## Released

Mar 2026

## Input /M

$0.20

## Output /M

$1.25

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-4.md) ---

# GPT-5.4

## About

Neon AI Gateway provides GPT-5.4 by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-4"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-4",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-4",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-4",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-4"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-4",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-4",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-4",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-4

## Lab

OpenAI makes GPT-5.4. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Mar 2026

## Input /M

$2.50

## Output /M

$15

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-5-pro.md) ---

# GPT-5.5 Pro

## About

Neon AI Gateway provides GPT-5.5 Pro by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-5-pro"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: neon("gpt-5-5-pro"),
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const response = await client.responses.create({
  model: "gpt-5-5-pro",
  input: "Explain Serverless Postgres.",
});
console.log(response.output_text);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

response = client.responses.create(
    model="gpt-5-5-pro",
    input="Explain Serverless Postgres.",
)
print(response.output_text)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/openai/v1/responses" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-5-pro",
    "input": "Explain Serverless Postgres."
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-5-pro"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-5-pro",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-5-pro",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-5-pro",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-5-pro

## Lab

OpenAI makes GPT-5.5 Pro. Access the model through the Neon AI Gateway using openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Apr 2026

## Input /M

$30

## Output /M

$180

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-5.md) ---

# GPT-5.5

## About

Neon AI Gateway provides GPT-5.5 by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-5"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-5",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-5",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-5",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-5

## Lab

OpenAI makes GPT-5.5. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Apr 2026

## Input /M

$5

## Output /M

$30

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-6-luna.md) ---

# GPT-5.6 Luna

## About

Neon AI Gateway provides GPT-5.6 Luna by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-6-luna"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-6-luna",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-6-luna",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-6-luna",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-luna",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-6-luna"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-6-luna",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-6-luna",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-6-luna",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-6-luna

## Lab

OpenAI makes GPT-5.6 Luna. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Jul 2026

## Input /M

$0.20

## Output /M

$1.20

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-6-sol.md) ---

# GPT-5.6 Sol

## About

Neon AI Gateway provides GPT-5.6 Sol by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-6-sol"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-6-sol",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-6-sol",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-6-sol",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-sol",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-6-sol"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-6-sol",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-6-sol",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-6-sol",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-6-sol

## Lab

OpenAI makes GPT-5.6 Sol. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Jul 2026

## Input /M

$5

## Output /M

$30

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-6-terra.md) ---

# GPT-5.6 Terra

## About

Neon AI Gateway provides GPT-5.6 Terra by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-6-terra"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-6-terra",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-6-terra",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-6-terra",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-6-terra",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-6-terra"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-6-terra",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-6-terra",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-6-terra",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-6-terra

## Lab

OpenAI makes GPT-5.6 Terra. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Jul 2026

## Input /M

$2

## Output /M

$12

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-mini.md) ---

# GPT-5 Mini

## About

Neon AI Gateway provides GPT-5 Mini by OpenAI. The model supports text, image inputs and a 400K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-mini"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-mini",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-mini",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-mini",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-mini"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-mini",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-mini",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-mini",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-mini

## Lab

OpenAI makes GPT-5 Mini. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image

## Context

400K

## Released

Aug 2025

## Input /M

$0.25

## Output /M

$2

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5-nano.md) ---

# GPT-5 Nano

## About

Neon AI Gateway provides GPT-5 Nano by OpenAI. The model supports text, image inputs and a 400K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5-nano"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5-nano",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5-nano",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5-nano",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-nano",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5-nano"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5-nano",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5-nano",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5-nano",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5-nano

## Lab

OpenAI makes GPT-5 Nano. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image

## Context

400K

## Released

Aug 2025

## Input /M

$0.05

## Output /M

$0.40

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-5.md) ---

# GPT-5

## About

Neon AI Gateway provides GPT-5 by OpenAI. The model supports text, image inputs and a 400K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-5"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-5",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-5"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-5",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-5",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-5",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-5

## Lab

OpenAI makes GPT-5. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image

## Context

400K

## Released

Aug 2025

## Input /M

$1.25

## Output /M

$10

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-6-1-sol.md) ---

# GPT-6.1 Sol

## About

Neon AI Gateway provides GPT-6.1 Sol by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-6-1-sol"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-6-1-sol",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-6-1-sol",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-6-1-sol",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-1-sol",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-6-1-sol"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-6-1-sol",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-6-1-sol",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-6-1-sol",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-6-1-sol

## Lab

OpenAI makes GPT-6.1 Sol. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Sep 2026

## Input /M

$2

## Output /M

$10

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-6-astra.md) ---

# GPT-6 Astra

## About

Neon AI Gateway provides GPT-6 Astra by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-6-astra"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-6-astra",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-6-astra",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-astra",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-6-astra"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-6-astra",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-6-astra",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-6-astra",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-6-astra

## Lab

OpenAI makes GPT-6 Astra. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Sep 2026

## Input /M

$10

## Output /M

$50

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-6-luna.md) ---

# GPT-6 Luna

## About

Neon AI Gateway provides GPT-6 Luna by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-6-luna"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-6-luna",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-6-luna",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-6-luna",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-6-luna"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-6-luna",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-6-luna",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-6-luna",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-6-luna

## Lab

OpenAI makes GPT-6 Luna. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Sep 2026

## Input /M

$0.10

## Output /M

$0.50

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-6-sol.md) ---

# GPT-6 Sol

## About

Neon AI Gateway provides GPT-6 Sol by OpenAI. The model supports text, image, pdf inputs and a 1.1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-6-sol"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-6-sol",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-6-sol",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-6-sol",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-sol",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

### Image generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

```typescript
import { streamText } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const result = streamText({
  model: neon("gpt-6-sol"),
  prompt: "A red apple on a wooden table.",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

for await (const _ of result.textStream) {}

const images = (await result.toolResults).filter((r) => r.toolName === "image_generation");
console.log(images.length);
```

#### Mastra

Install:

```bash
npm i @mastra/core ai @neon/ai-sdk-provider
```

```typescript
import { Agent } from "@mastra/core/agent";
import { neon } from "@neon/ai-sdk-provider";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "Generate the image the user asks for.",
  model: "neon/gpt-6-sol",
  tools: {
    image_generation: neon.tools.imageGeneration({
      model: "gpt-image-2",
      outputFormat: "jpeg",
    }),
  },
});

const { toolResults } = await agent.generate("A red apple on a wooden table.");
const images = toolResults.filter((r) => r.payload.toolName === "image_generation");
console.log(images.map((r) => r.payload.result.result.length));
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const stream = client.responses.stream({
  model: "gpt-6-sol",
  input: "A red apple on a wooden table.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }],
});

const response = await stream.finalResponse();
const sizes = response.output.flatMap((item) => {
  if (item.type !== "image_generation_call") return [];
  if (!("result" in item) || typeof item.result !== "string") return [];
  return [item.result.length];
});
console.log(sizes);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

with client.responses.stream(
    model="gpt-6-sol",
    input="A red apple on a wooden table.",
    tools=[{"type": "image_generation", "model": "gpt-image-2"}],
) as stream:
    for _ in stream:
        pass
    response = stream.get_final_response()

sizes = [
    len(item.result)
    for item in response.output
    if item.type == "image_generation_call" and getattr(item, "result", None)
]
print(sizes)
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-6-sol

## Lab

OpenAI makes GPT-6 Sol. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image, pdf

## Context

1.1M

## Released

Sep 2026

## Input /M

$2

## Output /M

$10

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-oss-120b.md) ---

# GPT OSS 120B

## About

Neon AI Gateway provides GPT OSS 120B by OpenAI. The model supports text inputs and a 131K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-oss-120b"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-oss-120b",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-oss-120b",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-oss-120b",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-120b",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-oss-120b

## Lab

OpenAI makes GPT OSS 120B. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text

## Context

131K

## Released

Aug 2025

## Input /M

$0.15

## Output /M

$0.60

--- [Document source](https://neon.com/docs/ai-gateway/models/gpt-oss-20b.md) ---

# GPT OSS 20B

## About

Neon AI Gateway provides GPT OSS 20B by OpenAI. The model supports text inputs and a 131K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("gpt-oss-20b"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/gpt-oss-20b",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "gpt-oss-20b",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="gpt-oss-20b",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-oss-20b",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gpt-oss-20b

## Lab

OpenAI makes GPT OSS 20B. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text

## Context

131K

## Released

Aug 2025

## Input /M

$0.07

## Output /M

$0.30

--- [Document source](https://neon.com/docs/ai-gateway/models/grok-4-6.md) ---

# Grok 4.6

## About

Neon AI Gateway provides Grok 4.6 by xAI. The model supports text, image inputs and a 500K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("grok-4-6"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/grok-4-6",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "grok-4-6",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="grok-4-6",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4-6",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

grok-4-6

## Lab

xAI makes Grok 4.6. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text, image

## Context

500K

## Released

Aug 2026

## Input /M

$2

## Output /M

$6

--- [Document source](https://neon.com/docs/ai-gateway/models/grok-4-7.md) ---

# Grok 4.7

## About

Neon AI Gateway provides Grok 4.7 by xAI. The model supports text inputs and a 500K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("grok-4-7"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/grok-4-7",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "grok-4-7",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="grok-4-7",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4-7",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

grok-4-7

## Lab

xAI makes Grok 4.7. Access the model through the Neon AI Gateway using chat/completions and openai/responses.

## Provider

Databricks

## Inputs

Text

## Context

500K

## Released

Sep 2026

## Input /M

$2.50

## Output /M

$7.50

--- [Document source](https://neon.com/docs/ai-gateway/models/gte-large-en.md) ---

# GTE Large (En)

## About

Neon AI Gateway provides GTE Large (En) by Alibaba. It returns 1024-dimensional embeddings on `POST /v1/embeddings`.

## Command

### Embeddings

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.embeddings.create({
  model: "gte-large-en",
  input: ["Explain Serverless Postgres."],
  encoding_format: "float",
});
console.log(resp.data[0].embedding.length, resp.usage);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.embeddings.create(
    model="gte-large-en",
    input=["Explain Serverless Postgres."],
    encoding_format="float",
)
print(len(resp.data[0].embedding), resp.usage)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/embeddings" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gte-large-en",
    "input": ["Explain Serverless Postgres."],
    "encoding_format": "float"
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

gte-large-en

## Lab

Alibaba makes GTE Large (En). Access it through the Neon AI Gateway's `POST /v1/embeddings` endpoint.

## Provider

Databricks

## Dimensions

1024

## Released

Jul 2023

## Input /M

$0.13

--- [Document source](https://neon.com/docs/ai-gateway/models/kimi-k3-1-pro.md) ---

# Kimi K3.1 Pro

## About

Neon AI Gateway provides Kimi K3.1 Pro by Moonshot AI. The model supports text, image inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("kimi-k3-1-pro"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/kimi-k3-1-pro",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "kimi-k3-1-pro",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="kimi-k3-1-pro",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3-1-pro",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

kimi-k3-1-pro

## Lab

Moonshot AI makes Kimi K3.1 Pro. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text, image

## Context

1M

## Released

Nov 2026

## Input /M

Free

## Output /M

Free

--- [Document source](https://neon.com/docs/ai-gateway/models/kimi-k3.md) ---

# Kimi K3

## About

Neon AI Gateway provides Kimi K3 by Moonshot AI. The model supports text, image, video inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("kimi-k3"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/kimi-k3",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "kimi-k3",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="kimi-k3",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

kimi-k3

## Lab

Moonshot AI makes Kimi K3. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text, image, video

## Context

1M

## Released

Jul 2026

## Input /M

$3

## Output /M

$15

--- [Document source](https://neon.com/docs/ai-gateway/models/llama-4-maverick.md) ---

# Llama 4 Maverick

## About

Neon AI Gateway provides Llama 4 Maverick by Meta. The model supports text, image inputs and a 1M context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("llama-4-maverick"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/llama-4-maverick",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "llama-4-maverick",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="llama-4-maverick",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-4-maverick",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

llama-4-maverick

## Lab

Meta makes Llama 4 Maverick. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text, image

## Context

1M

## Released

Apr 2025

## Input /M

$0.50

## Output /M

$1.50

--- [Document source](https://neon.com/docs/ai-gateway/models/meta-llama-3-1-8b-instruct.md) ---

# Meta Llama 3.1 8B Instruct

## About

Neon AI Gateway provides Meta Llama 3.1 8B Instruct by Meta. The model supports text inputs and a 131K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("meta-llama-3-1-8b-instruct"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/meta-llama-3-1-8b-instruct",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "meta-llama-3-1-8b-instruct",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="meta-llama-3-1-8b-instruct",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama-3-1-8b-instruct",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

meta-llama-3-1-8b-instruct

## Lab

Meta makes Meta Llama 3.1 8B Instruct. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text

## Context

131K

## Released

Jul 2024

## Input /M

$0.15

## Output /M

$0.45

--- [Document source](https://neon.com/docs/ai-gateway/models/meta-llama-3-3-70b-instruct.md) ---

# Meta Llama 3.3 70B Instruct

## About

Neon AI Gateway provides Meta Llama 3.3 70B Instruct by Meta. The model supports text inputs and a 128K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("meta-llama-3-3-70b-instruct"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/meta-llama-3-3-70b-instruct",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "meta-llama-3-3-70b-instruct",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="meta-llama-3-3-70b-instruct",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama-3-3-70b-instruct",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

meta-llama-3-3-70b-instruct

## Lab

Meta makes Meta Llama 3.3 70B Instruct. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text

## Context

128K

## Released

Dec 2024

## Input /M

$0.50

## Output /M

$1.50

--- [Document source](https://neon.com/docs/ai-gateway/models/openjev-qwen35-4b.md) ---

# OpenJev (Qwen 3.5 4B)

## About

Neon AI Gateway provides OpenJev (Qwen 3.5 4B) by Alibaba, a System One decision model. It answers questions about a given state with a choice, a probability, or a score; it does not generate text.

## Command

### Decisions

#### AI SDK

Install:

```bash
npm i ai@7 @neon/ai-sdk-provider
```

```typescript
import { experimental_decide as decide } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const { answers, usage } = await decide({
  model: neon.decisionModel("openjev-qwen35-4b"),
  state: "I was charged twice this month.",
  questions: {
    billing: {
      type: "boolean",
      instructions: "Is the user asking about billing?",
      criteria: { true: "Billing related", false: "Not billing" },
    },
  },
});
console.log(answers, usage);
```

#### TypeScript

Install:

```bash
npm i @typesafe-ai/sdk
```

```typescript
import { noul, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/typesafe`,
  defaultModel: "openjev-qwen35-4b",
});

const { answers, usage } = await client.systemOne({
  state: "I was charged twice this month.",
  questions: {
    billing: noul("Is the user asking about billing?", {
      true: "Billing related",
      false: "Not billing",
    }),
  },
});
console.log(answers, usage);
```

#### Python

Install:

```bash
pip install typesafe-sdk
```

```python
import os
from typesafe_sdk import Noul, TypeSafeClient

with TypeSafeClient(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/typesafe",
    model="openjev-qwen35-4b",
) as client:
    response = client.system_one(
        state="I was charged twice this month.",
        questions={
            "billing": Noul(
                instructions="Is the user asking about billing?",
                criteria={"true": "Billing related", "false": "Not billing"},
            ),
        },
    )
print(response.answers, response.usage)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/typesafe/v1/systemone" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openjev-qwen35-4b",
    "state": "I was charged twice this month.",
    "questions": {
      "billing": {
        "type": "noul",
        "instructions": "Is the user asking about billing?",
        "criteria": {"true": "Billing related", "false": "Not billing"}
      }
    }
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

openjev-qwen35-4b

## Lab

Alibaba makes OpenJev (Qwen 3.5 4B), a System One decision model. It answers questions about a given state with a choice, a probability, or a score; it does not generate text.

## Provider

Databricks

## Context

131K

## Released

Oct 2026

## Input /M

$0.042

--- [Document source](https://neon.com/docs/ai-gateway/models/qwen3-embedding-0-6b.md) ---

# Qwen3 Embedding 0.6B

## About

Neon AI Gateway provides Qwen3 Embedding 0.6B by Alibaba. It returns 1024-dimensional embeddings on `POST /v1/embeddings`.

## Command

### Embeddings

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.embeddings.create({
  model: "qwen3-embedding-0-6b",
  input: ["Explain Serverless Postgres."],
  encoding_format: "float",
});
console.log(resp.data[0].embedding.length, resp.usage);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.embeddings.create(
    model="qwen3-embedding-0-6b",
    input=["Explain Serverless Postgres."],
    encoding_format="float",
)
print(len(resp.data[0].embedding), resp.usage)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/embeddings" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-embedding-0-6b",
    "input": ["Explain Serverless Postgres."],
    "encoding_format": "float"
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

qwen3-embedding-0-6b

## Lab

Alibaba makes Qwen3 Embedding 0.6B. Access it through the Neon AI Gateway's `POST /v1/embeddings` endpoint.

## Provider

Databricks

## Dimensions

1024

## Released

Jun 2025

## Input /M

$0.02

--- [Document source](https://neon.com/docs/ai-gateway/models/qwen3-next-80b-a3b-instruct.md) ---

# Qwen3 Next Instruct

## About

Neon AI Gateway provides Qwen3 Next Instruct by Alibaba. The model supports text inputs and a 131K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("qwen3-next-80b-a3b-instruct"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/qwen3-next-80b-a3b-instruct",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "qwen3-next-80b-a3b-instruct",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="qwen3-next-80b-a3b-instruct",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-next-80b-a3b-instruct",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

qwen3-next-80b-a3b-instruct

## Lab

Alibaba makes Qwen3 Next Instruct. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text

## Context

131K

## Released

Sep 2025

## Input /M

$0.15

## Output /M

$1.20

--- [Document source](https://neon.com/docs/ai-gateway/models/qwen35-122b-a10b.md) ---

# Qwen3.5 122B A10B

## About

Neon AI Gateway provides Qwen3.5 122B A10B by Alibaba. The model supports text inputs and a 262K context window.

## Command

### Text generation

#### AI SDK

Install:

```bash
npm i ai @neon/ai-sdk-provider
```

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

const { text } = await generateText({
  model: neon("qwen35-122b-a10b"),
  prompt: "Explain Serverless Postgres.",
});

console.log(text);
```

#### Mastra

Install:

```bash
npm i @mastra/core
```

```typescript
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "neon-demo",
  name: "neon-demo",
  instructions: "You are a helpful assistant.",
  model: "neon/qwen35-122b-a10b",
});

const { text } = await agent.generate("Explain Serverless Postgres.");
console.log(text);
```

#### TypeScript

Install:

```bash
npm i openai
```

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});

const resp = await client.chat.completions.create({
  model: "qwen35-122b-a10b",
  messages: [{ role: "user", content: "Explain Serverless Postgres." }],
});
console.log(resp.choices[0].message.content);
```

#### Python

Install:

```bash
pip install openai
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/v1",
)

resp = client.chat.completions.create(
    model="qwen35-122b-a10b",
    messages=[{"role": "user", "content": "Explain Serverless Postgres."}],
)
print(resp.choices[0].message.content)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen35-122b-a10b",
    "messages": [{"role": "user", "content": "Explain Serverless Postgres."}]
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

qwen35-122b-a10b

## Lab

Alibaba makes Qwen3.5 122B A10B. Access the model through the Neon AI Gateway using chat/completions.

## Provider

Databricks

## Inputs

Text

## Context

262K

## Released

Feb 2026

## Input /M

$0.22

## Output /M

$2.20

--- [Document source](https://neon.com/docs/ai-gateway/models/typesafeai-jev-1-14-0.md) ---

# Jev 1.14

## About

Neon AI Gateway provides Jev 1.14 by TypeSafe AI, a System One decision model. It answers questions about a given state with a choice, a probability, or a score; it does not generate text.

## Command

### Decisions

#### AI SDK

Install:

```bash
npm i ai@7 @neon/ai-sdk-provider
```

```typescript
import { experimental_decide as decide } from "ai";
import { neon } from "@neon/ai-sdk-provider";

const { answers, usage } = await decide({
  model: neon.decisionModel("typesafeai-jev-1-14-0"),
  state: "I was charged twice this month.",
  questions: {
    billing: {
      type: "boolean",
      instructions: "Is the user asking about billing?",
      criteria: { true: "Billing related", false: "Not billing" },
    },
  },
});
console.log(answers, usage);
```

#### TypeScript

Install:

```bash
npm i @typesafe-ai/sdk
```

```typescript
import { noul, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/typesafe`,
  defaultModel: "typesafeai-jev-1-14-0",
});

const { answers, usage } = await client.systemOne({
  state: "I was charged twice this month.",
  questions: {
    billing: noul("Is the user asking about billing?", {
      true: "Billing related",
      false: "Not billing",
    }),
  },
});
console.log(answers, usage);
```

#### Python

Install:

```bash
pip install typesafe-sdk
```

```python
import os
from typesafe_sdk import Noul, TypeSafeClient

with TypeSafeClient(
    api_key=os.environ["NEON_AI_GATEWAY_TOKEN"],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/typesafe",
    model="typesafeai-jev-1-14-0",
) as client:
    response = client.system_one(
        state="I was charged twice this month.",
        questions={
            "billing": Noul(
                instructions="Is the user asking about billing?",
                criteria={"true": "Billing related", "false": "Not billing"},
            ),
        },
    )
print(response.answers, response.usage)
```

#### cURL

```bash
curl "${NEON_AI_GATEWAY_BASE_URL}/typesafe/v1/systemone" \
  -H "Authorization: Bearer ${NEON_AI_GATEWAY_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafeai-jev-1-14-0",
    "state": "I was charged twice this month.",
    "questions": {
      "billing": {
        "type": "noul",
        "instructions": "Is the user asking about billing?",
        "criteria": {"true": "Billing related", "false": "Not billing"}
      }
    }
  }'
```

**Environment variables**

```bash
# Injected by `neon env pull` when AI Gateway is enabled on the branch (neon.ts preview.aiGateway).
# Neon injects ONLY the NEON_AI_GATEWAY_* vars (not OPENAI_*). Build the OpenAI SDK / curl
# apiKey + baseURL from them: apiKey = NEON_AI_GATEWAY_TOKEN (the bearer, nt_live_...).
#
# NEON_AI_GATEWAY_BASE_URL is the bare gateway host (no path). Append the route you need:
#   - `/v1`        - unified Chat Completions and `/v1/embeddings`
#   - `/openai/v1` - OpenAI Responses API
#   - `/typesafe`  - TypeSafe SDK base URL for System One decisions (`/typesafe/v1/systemone`)
# @neon/ai-sdk-provider and Mastra route requests automatically.

NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://<branch-id>-api.ai.<cell>.<region>.<cloud>.neon.tech
```

## Model ID

typesafeai-jev-1-14-0

## Lab

TypeSafe AI makes Jev 1.14, a System One decision model. It answers questions about a given state with a choice, a probability, or a score; it does not generate text.

## Provider

TypeSafe AI

## Context

66K

## Released

Oct 2026

## Input /M

$0.042

--- [Document source](https://neon.com/docs/ai-gateway/openai-responses.md) ---

> Summary: The OpenAI Responses endpoint exposes the OpenAI Responses API through Neon AI Gateway. Required for codex model variants, which do not work with the chat completions endpoint.

# OpenAI Responses API

Use the OpenAI Responses API with Neon AI Gateway

Last updated: 2026-10-23

The OpenAI Responses endpoint exposes the [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) through Neon AI Gateway. Use it with the OpenAI SDK's `responses.create()` method by changing only the `baseURL`.

**Base URL:** `https://<branch-host>/openai/v1`

This endpoint is also reachable at the longer `/ai-gateway/openai/v1/responses` path. Both behave identically and neither is deprecated. See [Shorter paths](https://neon.com/docs/ai-gateway/models#shorter-paths) for the full list of aliases.

If you're using an OpenAI-compatible client that accepts a base URL, set it to either `https://<branch-host>/openai/v1` or `https://<branch-host>/ai-gateway/openai/v1`. The request and response shapes are the standard OpenAI Responses API shape.

**Warning:** Codex model variants such as `gpt-5-3-codex` **require this endpoint**. They don't work with the [chat completions endpoint](https://neon.com/docs/ai-gateway/chat-completions).

## Setup

Set these environment variables. See [Get started](https://neon.com/docs/ai-gateway/get-started) for how to obtain them.

```bash
NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://br-winter-pond-aptw82ef-api.ai.c-2.us-east-2.aws.neon.tech
```

## Supported models

This endpoint accepts OpenAI models only:

| Model ID        | Notes                  |
| --------------- | ---------------------- |
| `gpt-6-astra`   |                        |
| `gpt-5-6-sol`   |                        |
| `gpt-5-6-terra` |                        |
| `gpt-5-6-luna`  |                        |
| `gpt-5-5`       |                        |
| `gpt-5-5-pro`   | Requires this endpoint |
| `gpt-5-4`       |                        |
| `gpt-5-4-mini`  |                        |
| `gpt-5-4-nano`  |                        |
| `gpt-5-3-codex` | Requires this endpoint |
| `gpt-5-2`       |                        |
| `gpt-5-1`       |                        |
| `gpt-5`         |                        |
| `gpt-5-mini`    |                        |
| `gpt-5-nano`    |                        |

Sending a non-OpenAI model ID returns `400 model "<model-id>" is not available on the openai_responses endpoint`.

## Basic request

**TypeScript (OpenAI SDK)**

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/openai/v1`,
});

const response = await client.responses.create({
  model: 'gpt-5-4',
  input: [{ role: 'user', content: 'What is Neon?' }],
});

console.log(response.output_text);
```

**Python (OpenAI SDK)**

```python
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ['NEON_AI_GATEWAY_TOKEN'],
    base_url=f"{os.environ['NEON_AI_GATEWAY_BASE_URL']}/openai/v1",
)

response = client.responses.create(
    model='gpt-5-4',
    input=[{'role': 'user', 'content': 'What is Neon?'}],
)

print(response.output_text)
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/openai/v1/responses" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4",
    "input": [{"role": "user", "content": "What is Neon?"}]
  }'
```

## Streaming

**TypeScript (OpenAI SDK)**

```typescript
const stream = await client.responses.create({
  model: 'gpt-5-4',
  input: [{ role: 'user', content: 'Explain database branching.' }],
  stream: true,
});

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}
```

**Python (OpenAI SDK)**

```python
with client.responses.stream(
    model='gpt-5-4',
    input=[{'role': 'user', 'content': 'Explain database branching.'}],
) as stream:
    for event in stream:
        if event.type == 'response.output_text.delta':
            print(event.delta, end='', flush=True)
```

**cURL**

```bash
curl -X POST "$NEON_AI_GATEWAY_BASE_URL/openai/v1/responses" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-4",
    "input": [{"role": "user", "content": "Explain database branching."}],
    "stream": true
  }'
```

## Image generation with Vercel AI SDK

The `@neon/ai-sdk-provider` package re-exports the OpenAI provider's Responses image-generation tool as `neon.tools.imageGeneration()`. Use it with OpenAI-routed models such as `gpt-5-mini`. Set `model` on the tool to `gpt-image-2`, `gpt-image-1.5`, or `gpt-image-1-mini`. `gpt-image-1` is deprecated and not available on AI Gateway. In `@neon/ai-sdk-provider` 1.3.0 and later, the tool sends `gpt-image-2` when you leave out `model`, and throws `UnsupportedFunctionalityError` for `gpt-image-1`.

Use `streamText`, not `generateText`. A non-streaming response is limited to 655,360 bytes, and most base64 images are larger, so the request fails with `400` and `The response content length cannot be greater than 655360 bytes long`. With the OpenAI SDK, pass `stream: true` to `client.responses.create()`.

```typescript
import { neon } from '@neon/ai-sdk-provider';
import { streamText } from 'ai';

const result = streamText({
  model: neon('gpt-5-mini'),
  messages: [{ role: 'user', content: 'Create a simple Neon database mascot.' }],
  tools: {
    image: neon.tools.imageGeneration({
      model: 'gpt-image-2',
      outputFormat: 'jpeg',
      size: '1024x1024',
      partialImages: 3,
    }),
  },
});

return result.toUIMessageStreamResponse();
```

AI SDK `generateImage()` is not supported by AI Gateway; image generation is available only through this Responses tool.

## Error handling

| Status            | Message                                                                | Cause                                  |
| ----------------- | ---------------------------------------------------------------------- | -------------------------------------- |
| `400 Bad Request` | `unknown model "<model-id>"`                                           | Model ID not in the catalog            |
| `400 Bad Request` | `model "<model-id>" is not available on the openai_responses endpoint` | Non-OpenAI model sent to this endpoint |

For authentication, quota, and upstream errors, see [Troubleshooting](https://neon.com/docs/ai-gateway/troubleshooting).

## Next steps

- [Models](https://neon.com/docs/ai-gateway/models): full model catalog and which models require this endpoint
- [Chat completions](https://neon.com/docs/ai-gateway/chat-completions): use any model via the unified OpenAI-compatible endpoint
- [Authentication](https://neon.com/docs/ai-gateway/authentication): credential scopes and branch binding

--- [Document source](https://neon.com/docs/ai-gateway/overview.md) ---

> Summary: Neon AI Gateway is the LLM gateway built into your Neon project. One Neon credential gives you access to models across multiple providers. Standard AI SDKs work without code changes. Each branch gets its own gateway endpoint.

# Neon AI Gateway

One API for open-weight and foundation models from OpenAI, Google, and more. Built into your Neon project.

Last updated: 2026-10-30

Add chat, agents, and embeddings to your app through one endpoint and one Neon credential, with models from many providers, scoped to your branch the same way your data is.
Before you start: AI Gateway needs [prepaid credits](https://neon.com/docs/ai-gateway/prepaid-credits) ($5 minimum), which you can buy on any Neon plan, including Free, and a project in AWS US East (Ohio) (aws-us-east-2), AWS US East (N. Virginia) (aws-us-east-1), AWS Europe (Frankfurt) (aws-eu-central-1), or AWS Asia Pacific (Singapore) (aws-ap-southeast-1). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions).

[View prompt](https://neon.com/prompts/ai-gateway-landing.md)

## Available models

Browse the full catalog below. Switch between the **Text**, **Image**, **Embeddings**, and **Decisions** tabs, filter by lab or open weights, sort any column, and click a model for a copy-paste quickstart. Chat and image models get AI SDK, Mastra, Python, TypeScript, and cURL; embedding models get Python, TypeScript, and cURL; System One decision models get AI SDK, TypeScript, Python, and cURL. The endpoint each snippet targets is baked into its base URL: `/v1` for chat completions and embeddings, `/openai/v1` for the Responses API (image generation), `/typesafe/v1/systemone` for decisions.

### Text models

#### Anthropic

| Model                                                                             | Model ID            | Inputs           | Context | Released | Reasoning | Input /M | Output /M | Endpoints                             | License |
| --------------------------------------------------------------------------------- | ------------------- | ---------------- | ------- | -------- | --------- | -------- | --------- | ------------------------------------- | ------- |
| [Claude Haiku 5.5](https://neon.com/docs/ai-gateway/models/claude-haiku-5-5.md)   | `claude-haiku-5-5`  | text, image, pdf | 200K    | Oct 2026 | Yes       | $0.10    | $0.50     | chat/completions · anthropic/messages | —       |
| [Claude Sonnet 5.5](https://neon.com/docs/ai-gateway/models/claude-sonnet-5-5.md) | `claude-sonnet-5-5` | text, image, pdf | 1M      | Sep 2026 | Yes       | $2       | $10       | chat/completions · anthropic/messages | —       |
| [Claude Opus 5.5](https://neon.com/docs/ai-gateway/models/claude-opus-5-5.md)     | `claude-opus-5-5`   | text, image, pdf | 1M      | Sep 2026 | Yes       | $4       | $20       | chat/completions · anthropic/messages | —       |
| [Claude Fable 5.1](https://neon.com/docs/ai-gateway/models/claude-fable-5-1.md)   | `claude-fable-5-1`  | text, image, pdf | 1M      | Sep 2026 | Yes       | $10      | $50       | chat/completions · anthropic/messages | —       |
| [Claude Opus 5](https://neon.com/docs/ai-gateway/models/claude-opus-5.md)         | `claude-opus-5`     | text, image, pdf | 1M      | Jul 2026 | Yes       | $5       | $25       | chat/completions · anthropic/messages | —       |
| [Claude Sonnet 5](https://neon.com/docs/ai-gateway/models/claude-sonnet-5.md)     | `claude-sonnet-5`   | text, image, pdf | 1M      | Jun 2026 | Yes       | $2       | $10       | chat/completions · anthropic/messages | —       |
| [Claude Fable 5](https://neon.com/docs/ai-gateway/models/claude-fable-5.md)       | `claude-fable-5`    | text, image, pdf | 1M      | Jun 2026 | Yes       | $10      | $50       | chat/completions · anthropic/messages | —       |
| [Claude Opus 4.8](https://neon.com/docs/ai-gateway/models/claude-opus-4-8.md)     | `claude-opus-4-8`   | text, image, pdf | 1M      | May 2026 | Yes       | $5       | $25       | chat/completions · anthropic/messages | —       |
| [Claude Opus 4.7](https://neon.com/docs/ai-gateway/models/claude-opus-4-7.md)     | `claude-opus-4-7`   | text, image, pdf | 1M      | Apr 2026 | Yes       | $5       | $25       | chat/completions · anthropic/messages | —       |
| [Claude Sonnet 4.6](https://neon.com/docs/ai-gateway/models/claude-sonnet-4-6.md) | `claude-sonnet-4-6` | text, image, pdf | 1M      | Feb 2026 | Yes       | $3       | $15       | chat/completions · anthropic/messages | —       |
| [Claude Opus 4.6](https://neon.com/docs/ai-gateway/models/claude-opus-4-6.md)     | `claude-opus-4-6`   | text, image, pdf | 1M      | Feb 2026 | Yes       | $5       | $25       | chat/completions · anthropic/messages | —       |
| [Claude Opus 4.5](https://neon.com/docs/ai-gateway/models/claude-opus-4-5.md)     | `claude-opus-4-5`   | text, image, pdf | 200K    | Nov 2025 | Yes       | $5       | $25       | chat/completions · anthropic/messages | —       |
| [Claude Haiku 4.5](https://neon.com/docs/ai-gateway/models/claude-haiku-4-5.md)   | `claude-haiku-4-5`  | text, image, pdf | 200K    | Oct 2025 | Yes       | $1       | $5        | chat/completions · anthropic/messages | —       |
| [Claude Sonnet 4.5](https://neon.com/docs/ai-gateway/models/claude-sonnet-4-5.md) | `claude-sonnet-4-5` | text, image, pdf | 200K    | Sep 2025 | Yes       | $3       | $15       | chat/completions · anthropic/messages | —       |
| [Claude Opus 4.1](https://neon.com/docs/ai-gateway/models/claude-opus-4-1.md)     | `claude-opus-4-1`   | text, image, pdf | 200K    | Aug 2025 | Yes       | $15      | $75       | chat/completions · anthropic/messages | —       |

#### OpenAI

| Model                                                                     | Model ID        | Inputs           | Context | Released | Reasoning | Input /M | Output /M | Endpoints                           | License      |
| ------------------------------------------------------------------------- | --------------- | ---------------- | ------- | -------- | --------- | -------- | --------- | ----------------------------------- | ------------ |
| [GPT-6.1 Sol](https://neon.com/docs/ai-gateway/models/gpt-6-1-sol.md)     | `gpt-6-1-sol`   | text, image, pdf | 1.1M    | Sep 2026 | Yes       | $2       | $10       | chat/completions · openai/responses | —            |
| [GPT-6 Sol](https://neon.com/docs/ai-gateway/models/gpt-6-sol.md)         | `gpt-6-sol`     | text, image, pdf | 1.1M    | Sep 2026 | Yes       | $2       | $10       | chat/completions · openai/responses | —            |
| [GPT-6 Luna](https://neon.com/docs/ai-gateway/models/gpt-6-luna.md)       | `gpt-6-luna`    | text, image, pdf | 1.1M    | Sep 2026 | Yes       | $0.10    | $0.50     | chat/completions · openai/responses | —            |
| [GPT-6 Astra](https://neon.com/docs/ai-gateway/models/gpt-6-astra.md)     | `gpt-6-astra`   | text, image, pdf | 1.1M    | Sep 2026 | Yes       | $10      | $50       | chat/completions · openai/responses | —            |
| [GPT-5.6 Luna](https://neon.com/docs/ai-gateway/models/gpt-5-6-luna.md)   | `gpt-5-6-luna`  | text, image, pdf | 1.1M    | Jul 2026 | Yes       | $0.20    | $1.20     | chat/completions · openai/responses | —            |
| [GPT-5.6 Sol](https://neon.com/docs/ai-gateway/models/gpt-5-6-sol.md)     | `gpt-5-6-sol`   | text, image, pdf | 1.1M    | Jul 2026 | Yes       | $5       | $30       | chat/completions · openai/responses | —            |
| [GPT-5.6 Terra](https://neon.com/docs/ai-gateway/models/gpt-5-6-terra.md) | `gpt-5-6-terra` | text, image, pdf | 1.1M    | Jul 2026 | Yes       | $2       | $12       | chat/completions · openai/responses | —            |
| [GPT-5.5](https://neon.com/docs/ai-gateway/models/gpt-5-5.md)             | `gpt-5-5`       | text, image, pdf | 1.1M    | Apr 2026 | Yes       | $5       | $30       | chat/completions · openai/responses | —            |
| [GPT-5.5 Pro](https://neon.com/docs/ai-gateway/models/gpt-5-5-pro.md)     | `gpt-5-5-pro`   | text, image, pdf | 1.1M    | Apr 2026 | Yes       | $30      | $180      | openai/responses                    | —            |
| [GPT-5.4 Mini](https://neon.com/docs/ai-gateway/models/gpt-5-4-mini.md)   | `gpt-5-4-mini`  | text, image      | 400K    | Mar 2026 | Yes       | $0.75    | $4.50     | chat/completions · openai/responses | —            |
| [GPT-5.4 Nano](https://neon.com/docs/ai-gateway/models/gpt-5-4-nano.md)   | `gpt-5-4-nano`  | text, image      | 400K    | Mar 2026 | Yes       | $0.20    | $1.25     | chat/completions · openai/responses | —            |
| [GPT-5.4](https://neon.com/docs/ai-gateway/models/gpt-5-4.md)             | `gpt-5-4`       | text, image, pdf | 1.1M    | Mar 2026 | Yes       | $2.50    | $15       | chat/completions · openai/responses | —            |
| [GPT-5.3 Codex](https://neon.com/docs/ai-gateway/models/gpt-5-3-codex.md) | `gpt-5-3-codex` | text, image, pdf | 400K    | Feb 2026 | Yes       | $1.75    | $14       | openai/responses                    | —            |
| [GPT-5.2](https://neon.com/docs/ai-gateway/models/gpt-5-2.md)             | `gpt-5-2`       | text, image      | 400K    | Dec 2025 | Yes       | $1.75    | $14       | chat/completions · openai/responses | —            |
| [GPT-5.1](https://neon.com/docs/ai-gateway/models/gpt-5-1.md)             | `gpt-5-1`       | text, image      | 400K    | Nov 2025 | Yes       | $1.25    | $10       | chat/completions · openai/responses | —            |
| [GPT-5](https://neon.com/docs/ai-gateway/models/gpt-5.md)                 | `gpt-5`         | text, image      | 400K    | Aug 2025 | Yes       | $1.25    | $10       | chat/completions · openai/responses | —            |
| [GPT-5 Mini](https://neon.com/docs/ai-gateway/models/gpt-5-mini.md)       | `gpt-5-mini`    | text, image      | 400K    | Aug 2025 | Yes       | $0.25    | $2        | chat/completions · openai/responses | —            |
| [GPT-5 Nano](https://neon.com/docs/ai-gateway/models/gpt-5-nano.md)       | `gpt-5-nano`    | text, image      | 400K    | Aug 2025 | Yes       | $0.05    | $0.40     | chat/completions · openai/responses | —            |
| [GPT OSS 120B](https://neon.com/docs/ai-gateway/models/gpt-oss-120b.md)   | `gpt-oss-120b`  | text             | 131K    | Aug 2025 | Yes       | $0.15    | $0.60     | chat/completions                    | Open weights |
| [GPT OSS 20B](https://neon.com/docs/ai-gateway/models/gpt-oss-20b.md)     | `gpt-oss-20b`   | text             | 131K    | Aug 2025 | Yes       | $0.07    | $0.30     | chat/completions                    | Open weights |

#### Google

| Model                                                                                     | Model ID                | Inputs                         | Context | Released | Reasoning | Input /M | Output /M | Endpoints                 | License      |
| ----------------------------------------------------------------------------------------- | ----------------------- | ------------------------------ | ------- | -------- | --------- | -------- | --------- | ------------------------- | ------------ |
| [Gemini 4 Argon](https://neon.com/docs/ai-gateway/models/gemini-4-argon.md)               | `gemini-4-argon`        | text, image, video, audio, pdf | 1M      | Oct 2026 | Yes       | $4       | $20       | chat/completions · gemini | —            |
| [Gemini 3.8 Flash](https://neon.com/docs/ai-gateway/models/gemini-3-8-flash.md)           | `gemini-3-8-flash`      | text, image, video, audio, pdf | 1M      | Sep 2026 | Yes       | $1.50    | $7.50     | chat/completions · gemini | —            |
| [Gemini 3.7 Flash](https://neon.com/docs/ai-gateway/models/gemini-3-7-flash.md)           | `gemini-3-7-flash`      | text, image, video, audio, pdf | 1M      | Aug 2026 | Yes       | $1.50    | $7.50     | chat/completions · gemini | —            |
| [Gemini 3.5 Flash Lite](https://neon.com/docs/ai-gateway/models/gemini-3-5-flash-lite.md) | `gemini-3-5-flash-lite` | text, image, video, audio, pdf | 1M      | Jul 2026 | Yes       | $0.30    | $2.50     | chat/completions · gemini | —            |
| [Gemini 3.6 Flash](https://neon.com/docs/ai-gateway/models/gemini-3-6-flash.md)           | `gemini-3-6-flash`      | text, image, video, audio, pdf | 1M      | Jul 2026 | Yes       | $1.50    | $7.50     | chat/completions · gemini | —            |
| [Gemini 3.5 Flash](https://neon.com/docs/ai-gateway/models/gemini-3-5-flash.md)           | `gemini-3-5-flash`      | text, image, video, audio, pdf | 1M      | May 2026 | Yes       | $1.50    | $9        | chat/completions · gemini | —            |
| [Gemini 3.1 Flash Lite](https://neon.com/docs/ai-gateway/models/gemini-3-1-flash-lite.md) | `gemini-3-1-flash-lite` | text, image, video, audio, pdf | 1M      | Mar 2026 | Yes       | $0.25    | $1.50     | chat/completions · gemini | —            |
| [Gemini 3.1 Pro](https://neon.com/docs/ai-gateway/models/gemini-3-1-pro.md)               | `gemini-3-1-pro`        | text, image, video, audio, pdf | 1M      | Feb 2026 | Yes       | $2       | $12       | chat/completions · gemini | —            |
| [Gemini 3 Flash](https://neon.com/docs/ai-gateway/models/gemini-3-flash.md)               | `gemini-3-flash`        | text, image, video, audio, pdf | 1M      | Dec 2025 | Yes       | $0.50    | $3        | chat/completions · gemini | —            |
| [Gemma 3 12B](https://neon.com/docs/ai-gateway/models/gemma-3-12b.md)                     | `gemma-3-12b`           | text, image                    | 131K    | Mar 2025 | —         | $0.15    | $0.50     | chat/completions          | Open weights |

#### Meta

| Model                                                                                                 | Model ID                      | Inputs      | Context | Released | Reasoning | Input /M | Output /M | Endpoints        | License      |
| ----------------------------------------------------------------------------------------------------- | ----------------------------- | ----------- | ------- | -------- | --------- | -------- | --------- | ---------------- | ------------ |
| [Llama 4 Maverick](https://neon.com/docs/ai-gateway/models/llama-4-maverick.md)                       | `llama-4-maverick`            | text, image | 1M      | Apr 2025 | —         | $0.50    | $1.50     | chat/completions | Open weights |
| [Meta Llama 3.3 70B Instruct](https://neon.com/docs/ai-gateway/models/meta-llama-3-3-70b-instruct.md) | `meta-llama-3-3-70b-instruct` | text        | 128K    | Dec 2024 | —         | $0.50    | $1.50     | chat/completions | Open weights |
| [Meta Llama 3.1 8B Instruct](https://neon.com/docs/ai-gateway/models/meta-llama-3-1-8b-instruct.md)   | `meta-llama-3-1-8b-instruct`  | text        | 131K    | Jul 2024 | —         | $0.15    | $0.45     | chat/completions | Open weights |

#### Alibaba

| Model                                                                                         | Model ID                      | Inputs | Context | Released | Reasoning | Input /M | Output /M | Endpoints        | License      |
| --------------------------------------------------------------------------------------------- | ----------------------------- | ------ | ------- | -------- | --------- | -------- | --------- | ---------------- | ------------ |
| [Qwen3.5 122B A10B](https://neon.com/docs/ai-gateway/models/qwen35-122b-a10b.md)              | `qwen35-122b-a10b`            | text   | 262K    | Feb 2026 | Yes       | $0.22    | $2.20     | chat/completions | Open weights |
| [Qwen3 Next Instruct](https://neon.com/docs/ai-gateway/models/qwen3-next-80b-a3b-instruct.md) | `qwen3-next-80b-a3b-instruct` | text   | 131K    | Sep 2025 | —         | $0.15    | $1.20     | chat/completions | Open weights |

#### Zhipu AI

| Model                                                                     | Model ID        | Inputs      | Context | Released | Reasoning | Input /M | Output /M | Endpoints        | License      |
| ------------------------------------------------------------------------- | --------------- | ----------- | ------- | -------- | --------- | -------- | --------- | ---------------- | ------------ |
| [GLM 5.3](https://neon.com/docs/ai-gateway/models/glm-5-3.md)             | `glm-5-3`       | text        | 1M      | Aug 2026 | Yes       | $1.40    | $4.40     | chat/completions | Open weights |
| [GLM 5.3 Flash](https://neon.com/docs/ai-gateway/models/glm-5-3-flash.md) | `glm-5-3-flash` | text, image | 1M      | Aug 2026 | Yes       | $0.15    | $0.50     | chat/completions | Open weights |
| [GLM 5.2](https://neon.com/docs/ai-gateway/models/glm-5-2.md)             | `glm-5-2`       | text        | 1M      | Jun 2026 | Yes       | $1.40    | $4.40     | chat/completions | Open weights |

#### Moonshot AI

| Model                                                                     | Model ID        | Inputs             | Context | Released | Reasoning | Input /M | Output /M | Endpoints        | License      |
| ------------------------------------------------------------------------- | --------------- | ------------------ | ------- | -------- | --------- | -------- | --------- | ---------------- | ------------ |
| [Kimi K3.1 Pro](https://neon.com/docs/ai-gateway/models/kimi-k3-1-pro.md) | `kimi-k3-1-pro` | text, image        | 1M      | Nov 2026 | Yes       | Free     | Free      | chat/completions | Open weights |
| [Kimi K3](https://neon.com/docs/ai-gateway/models/kimi-k3.md)             | `kimi-k3`       | text, image, video | 1M      | Jul 2026 | Yes       | $3       | $15       | chat/completions | Open weights |

#### xAI

| Model                                                           | Model ID   | Inputs      | Context | Released | Reasoning | Input /M | Output /M | Endpoints                           | License |
| --------------------------------------------------------------- | ---------- | ----------- | ------- | -------- | --------- | -------- | --------- | ----------------------------------- | ------- |
| [Grok 4.7](https://neon.com/docs/ai-gateway/models/grok-4-7.md) | `grok-4-7` | text        | 500K    | Sep 2026 | Yes       | $2.50    | $7.50     | chat/completions · openai/responses | —       |
| [Grok 4.6](https://neon.com/docs/ai-gateway/models/grok-4-6.md) | `grok-4-6` | text, image | 500K    | Aug 2026 | Yes       | $2       | $6        | chat/completions · openai/responses | —       |

#### DeepSeek

| Model                                                                                 | Model ID              | Inputs      | Context | Released | Reasoning | Input /M | Output /M | Endpoints        | License      |
| ------------------------------------------------------------------------------------- | --------------------- | ----------- | ------- | -------- | --------- | -------- | --------- | ---------------- | ------------ |
| [DeepSeek V4.1 Flash](https://neon.com/docs/ai-gateway/models/deepseek-v4-1-flash.md) | `deepseek-v4-1-flash` | text, image | 128K    | Sep 2026 | Yes       | $0.30    | $1.20     | chat/completions | Open weights |

Select a linked model for code examples matched to its measured AI Gateway capabilities.

### Image models

These models support image generation through the Responses API (base URL `/openai/v1`):

#### OpenAI

| Model                                                                     | Model ID        | Inputs           | Context | Released | Reasoning | Input /M | Output /M | Endpoints                           | License |
| ------------------------------------------------------------------------- | --------------- | ---------------- | ------- | -------- | --------- | -------- | --------- | ----------------------------------- | ------- |
| [GPT-6.1 Sol](https://neon.com/docs/ai-gateway/models/gpt-6-1-sol.md)     | `gpt-6-1-sol`   | text, image, pdf | 1.1M    | Sep 2026 | Yes       | $2       | $10       | chat/completions · openai/responses | —       |
| [GPT-6 Sol](https://neon.com/docs/ai-gateway/models/gpt-6-sol.md)         | `gpt-6-sol`     | text, image, pdf | 1.1M    | Sep 2026 | Yes       | $2       | $10       | chat/completions · openai/responses | —       |
| [GPT-6 Luna](https://neon.com/docs/ai-gateway/models/gpt-6-luna.md)       | `gpt-6-luna`    | text, image, pdf | 1.1M    | Sep 2026 | Yes       | $0.10    | $0.50     | chat/completions · openai/responses | —       |
| [GPT-6 Astra](https://neon.com/docs/ai-gateway/models/gpt-6-astra.md)     | `gpt-6-astra`   | text, image, pdf | 1.1M    | Sep 2026 | Yes       | $10      | $50       | chat/completions · openai/responses | —       |
| [GPT-5.6 Luna](https://neon.com/docs/ai-gateway/models/gpt-5-6-luna.md)   | `gpt-5-6-luna`  | text, image, pdf | 1.1M    | Jul 2026 | Yes       | $0.20    | $1.20     | chat/completions · openai/responses | —       |
| [GPT-5.6 Sol](https://neon.com/docs/ai-gateway/models/gpt-5-6-sol.md)     | `gpt-5-6-sol`   | text, image, pdf | 1.1M    | Jul 2026 | Yes       | $5       | $30       | chat/completions · openai/responses | —       |
| [GPT-5.6 Terra](https://neon.com/docs/ai-gateway/models/gpt-5-6-terra.md) | `gpt-5-6-terra` | text, image, pdf | 1.1M    | Jul 2026 | Yes       | $2       | $12       | chat/completions · openai/responses | —       |
| [GPT-5.5](https://neon.com/docs/ai-gateway/models/gpt-5-5.md)             | `gpt-5-5`       | text, image, pdf | 1.1M    | Apr 2026 | Yes       | $5       | $30       | chat/completions · openai/responses | —       |
| [GPT-5.5 Pro](https://neon.com/docs/ai-gateway/models/gpt-5-5-pro.md)     | `gpt-5-5-pro`   | text, image, pdf | 1.1M    | Apr 2026 | Yes       | $30      | $180      | openai/responses                    | —       |
| [GPT-5.4 Mini](https://neon.com/docs/ai-gateway/models/gpt-5-4-mini.md)   | `gpt-5-4-mini`  | text, image      | 400K    | Mar 2026 | Yes       | $0.75    | $4.50     | chat/completions · openai/responses | —       |
| [GPT-5.4 Nano](https://neon.com/docs/ai-gateway/models/gpt-5-4-nano.md)   | `gpt-5-4-nano`  | text, image      | 400K    | Mar 2026 | Yes       | $0.20    | $1.25     | chat/completions · openai/responses | —       |
| [GPT-5.4](https://neon.com/docs/ai-gateway/models/gpt-5-4.md)             | `gpt-5-4`       | text, image, pdf | 1.1M    | Mar 2026 | Yes       | $2.50    | $15       | chat/completions · openai/responses | —       |
| [GPT-5.3 Codex](https://neon.com/docs/ai-gateway/models/gpt-5-3-codex.md) | `gpt-5-3-codex` | text, image, pdf | 400K    | Feb 2026 | Yes       | $1.75    | $14       | openai/responses                    | —       |
| [GPT-5.2](https://neon.com/docs/ai-gateway/models/gpt-5-2.md)             | `gpt-5-2`       | text, image      | 400K    | Dec 2025 | Yes       | $1.75    | $14       | chat/completions · openai/responses | —       |
| [GPT-5.1](https://neon.com/docs/ai-gateway/models/gpt-5-1.md)             | `gpt-5-1`       | text, image      | 400K    | Nov 2025 | Yes       | $1.25    | $10       | chat/completions · openai/responses | —       |
| [GPT-5](https://neon.com/docs/ai-gateway/models/gpt-5.md)                 | `gpt-5`         | text, image      | 400K    | Aug 2025 | Yes       | $1.25    | $10       | chat/completions · openai/responses | —       |
| [GPT-5 Mini](https://neon.com/docs/ai-gateway/models/gpt-5-mini.md)       | `gpt-5-mini`    | text, image      | 400K    | Aug 2025 | Yes       | $0.25    | $2        | chat/completions · openai/responses | —       |
| [GPT-5 Nano](https://neon.com/docs/ai-gateway/models/gpt-5-nano.md)       | `gpt-5-nano`    | text, image      | 400K    | Aug 2025 | Yes       | $0.05    | $0.40     | chat/completions · openai/responses | —       |

Select a linked model for image-generation examples matched to that model.

### Embedding models

These models return a fixed-length vector on `POST /v1/embeddings` rather than generating text — a different endpoint from every model above:

| Model                                                                                   | Model ID               | Lab     | Dimensions | Released | Input /M | Endpoints  | License      |
| --------------------------------------------------------------------------------------- | ---------------------- | ------- | ---------- | -------- | -------- | ---------- | ------------ |
| [Qwen3 Embedding 0.6B](https://neon.com/docs/ai-gateway/models/qwen3-embedding-0-6b.md) | `qwen3-embedding-0-6b` | Alibaba | 1024       | Jun 2025 | $0.02    | embeddings | Open weights |
| [GTE Large (En)](https://neon.com/docs/ai-gateway/models/gte-large-en.md)               | `gte-large-en`         | Alibaba | 1024       | Jul 2023 | $0.13    | embeddings | Open weights |
| [BGE Large (En)](https://neon.com/docs/ai-gateway/models/bge-large-en.md)               | `bge-large-en`         | BAAI    | 1024       | Sep 2023 | $0.10    | embeddings | Open weights |

Select a linked model for embeddings-specific code examples.

### Decision models

These System One models answer questions about a given state with a choice, a probability, or a score rather than generating text:

| Model                                                                                 | Model ID                | Lab         | Context | Released | Input /M | License      |
| ------------------------------------------------------------------------------------- | ----------------------- | ----------- | ------- | -------- | -------- | ------------ |
| [OpenJev (Qwen 3.5 4B)](https://neon.com/docs/ai-gateway/models/openjev-qwen35-4b.md) | `openjev-qwen35-4b`     | Alibaba     | 131K    | Oct 2026 | $0.042   | Open weights |
| [Jev 1.14](https://neon.com/docs/ai-gateway/models/typesafeai-jev-1-14-0.md)          | `typesafeai-jev-1-14-0` | TypeSafe AI | 66K     | Oct 2026 | $0.042   | —            |

Prices are provider list prices per million tokens. Inference is free during the private preview. Click a model for a copy-paste quickstart.

For full request paths and when to prefer each endpoint, see [Which endpoint to use](https://neon.com/docs/ai-gateway/models#which-endpoint-to-use). For embedding models (dimensions, normalization, and choosing a distance operator), see [Embeddings](https://neon.com/docs/ai-gateway/embeddings). For decision models (question types and answer shapes), see [Decisions](https://neon.com/docs/ai-gateway/decisions).

## Get started

- [Quickstart](https://neon.com/docs/ai-gateway/get-started): Get a credential and make your first inference request in minutes.
- [Model reference](https://neon.com/docs/ai-gateway/models): Endpoints, model IDs, rate limits, pricing, and provider terms.
- [Chat completions](https://neon.com/docs/ai-gateway/chat-completions): Use the OpenAI-compatible endpoint with any model in the catalog.
- [Embeddings](https://neon.com/docs/ai-gateway/embeddings): Turn text into vectors for search with the OpenAI-compatible embeddings endpoint.
- [Decisions](https://neon.com/docs/ai-gateway/decisions): Ask yes/no, choice, and score questions about text and get back probabilities.
- [Authentication](https://neon.com/docs/ai-gateway/authentication): Understand how Neon credentials work with AI Gateway.

## Starter templates

Browse working examples at [build-on-neon.vercel.app](https://build-on-neon.vercel.app/). Two templates use AI Gateway:

**`ai-sdk`**: An image-generation agent that routes model calls through AI Gateway, stores results in Neon Object Storage, and writes metadata to Postgres on a Neon Function.

```bash
neon bootstrap --template ai-sdk
```

**`mastra`**: A personal assistant that uses AI Gateway for LLM calls with Postgres-backed memory on a Neon Function.

```bash
neon bootstrap --template mastra
```

--- [Document source](https://neon.com/docs/ai-gateway/prepaid-credits.md) ---

> Summary: Learn how AI Gateway prepaid credits work, who can buy them, how to purchase credits, how to set up automatic top-up, how to check your balance, and how usage limits and metering affect access.

# AI Gateway prepaid credits

Buy credits, understand pricing and limits, and manage your balance for the Neon AI Gateway

Last updated: 2026-11-04

The Neon AI Gateway is billed with **prepaid credits**. You buy credits up front,
and AI Gateway usage draws down your balance. This page explains who can buy
credits, how pricing and usage limits work, how to purchase or top up, and how to
check your balance.

**Note:** The AI Gateway is available on **every Neon plan**, including Free. On the Free
plan, you add a payment card and buy credits without upgrading. Your
organization stays on the Free plan. See [Neon plans](https://neon.com/docs/introduction/plans) and
[About billing](https://neon.com/docs/introduction/about-billing).

## How credits and pricing work

- **1 credit = $1 USD.** Credits are prepaid, purchased before use.
- **Minimum purchase: $5.**
- **Minimum balance: $2.** Once your balance drops below $2, new requests return
  HTTP 429 until you add credits.
- **Credits expire 12 months after purchase.**
- Your balance can go **below $2, or negative**. Usage is metered after a
  request is served, so a long or large request, or several running at once,
  can take the balance below $2 or below zero before new requests are blocked.

Your balance **draws down as usage is metered**. Each request consumes credits
based on its token usage, so your balance decreases as you send requests. For
example, a small request might reduce a $25.00 balance to $24.99.

## Who can buy credits

- Only **organization admins** can purchase credits.
- The organization must be billed directly by payment card. On the Free plan,
  add a payment card first. Adding a card doesn't change your plan.
- Members, editors, and viewers cannot purchase credits.
- Sales-invoiced, marketplace, trial, sponsored, and shared-token accounts cannot
  purchase credits through this self-service flow. Contact your account team for
  assistance.

## Buy or top up credits

Buying credits is a Neon Console flow:

1. In the Neon Console, select **Billing**.
2. Find the **AI gateway credits** card and select **Add credits**. On the Free
   plan with no payment card on file, the card shows **Add a card** instead.
   Select it, add your card, and then select **Add credits**.
3. Select a preset amount: **$5**, **$10**, **$25**, **$50**, or **$100**. You can
   also select **Other** to enter a custom amount. The default selection is $25,
   and the minimum purchase is $5.
4. Confirm the purchase. Neon applies a **one-time charge** to the payment card
   already on file for your organization.

![AI Gateway credits purchase modal with preset and custom amounts](https://neon.com/docs/ai-gateway/ai-gateway-add-credits-modal.png)

Credits post to your balance promptly after the charge succeeds. The purchase
appears in your credit history as **Manual purchase**, with the date and amount.

**Important:** Only **one purchase can be open at a time** per account. You can't start a second
purchase until the first completes. If an automatic top-up is in progress, a
manual purchase fails with "Another credit purchase is in progress. Try again in a
moment."

**If a purchase fails.** If the payment card on file is declined, the purchase
fails and no credits are added to your balance. Neon doesn't leave a payable
invoice behind, and failed attempts don't appear in your credit history. Update
your card in **Billing** and try again.

## View your balance and usage history

In the Console, select **Billing** and find the **AI gateway credits** card. The
card shows:

- **Credits remaining**: your organization's current credit balance.
- **Credits added in last 30 days**: a history panel that lists each entry's date,
  source, and amount, plus the total credits added during the period. Automatic
  top-ups are listed with the source **Auto-reload**.

![AI Gateway credits balance and credits added in the last 30 days](https://neon.com/docs/ai-gateway/ai-gateway-credits-balance.png)

The balance is shown in **whole cents**, so small or occasional requests might not
visibly change it even though their metered usage still draws down the balance.

## Usage limits

AI Gateway usage is subject to **soft limits** that guard against runaway cost
and abuse:

- **Per-minute token limit.** A soft limit of **200,000 tokens per minute
  (TPM)** applies to input and output tokens separately, but this may vary by
  account.
- **Daily spend cap.** A **$20 per day** limit applies to total usage, but this
  may vary by account.

Short-window rate limits, the daily spend cap, and balance depletion are distinct:

- **Short-window rate limits** return HTTP 429 with a `Retry-After` header that
  points to the start of the next minute. `x-ratelimit-*` headers, when present,
  come from the upstream provider, not from Neon's limits.
- The **daily spend cap** limits how much you can spend in a single day.
- **Balance depletion** happens when your prepaid credits run out.

If you're blocked and need a limit raised, [contact Support](https://neon.com/docs/introduction/support).
See [Rate limits](https://neon.com/docs/ai-gateway/models#rate-limits) for details.

When you exceed a limit, the API returns **HTTP 429**:

```json
{
  "error_code": "REQUEST_LIMIT_EXCEEDED",
  "message": "You've reached your AI Gateway daily spend limit. You can retry after it resets, or ask Neon support to raise it (we review all increases to prevent abuse): https://console.neon.tech/app/projects?modal=support"
}
```

## Model access

Any account with prepaid credits can use every AI Gateway model.
See [Model access](https://neon.com/docs/ai-gateway/models#model-access) for details.

After you buy credits, locked models unlock once Neon confirms access. If a
model still shows a padlock on the **AI Gateway** page, reload the page. See
[Locked models in the Console](https://neon.com/docs/ai-gateway/troubleshooting#some-models-are-restricted-in-the-console).

The model list is subject to change. See
[Supported models](https://neon.com/docs/ai-gateway/models) for the current catalog.

## Automatic top-up

Turn on **auto-reload** to keep your balance from running out. When your balance
drops below a threshold you set, Neon buys a fixed amount of credits with the
payment card on file, with no action needed from you.

Auto-reload is available on paid plans only. It isn't available on the Free
plan yet. Only organization admins can set it up, and the organization must be
billed directly by payment card.

To set up auto-reload:

1. In the Neon Console, select **Billing**.
2. On the **AI gateway credits** card, select **Auto-reload**.
3. Turn on **Enable auto-reload** and set:
   - **When balance drops below (USD)**: the threshold that triggers a top-up. It
     must be higher than the $2 minimum balance. The default is $10.
   - **Automatically purchase (USD)**: how many credits to buy each time. The
     amount must be at least the threshold and within the same range as a manual
     purchase. The default is $25.
4. Click **Save**.

![Auto-reload credits dialog with a $10 threshold and a $25 purchase amount](https://neon.com/docs/ai-gateway/ai-gateway-auto-reload-modal.png)

You can also turn on auto-reload in the **Add credits** dialog when you buy
credits. Neon saves those settings only if the purchase succeeds.

The **Auto-reload** button shows **On** or **Off** so you can check its status at
a glance. If your balance is already below the threshold when you turn on
auto-reload, Neon tops it up right away.

Neon turns auto-reload off when it can't complete a top-up, for example when your
card is declined or a top-up keeps failing. It also turns off if your
organization no longer qualifies, such as after a downgrade to Free or removing
your payment card. When this happens, an alert on the **AI gateway credits** card
and in the **Auto-reload** dialog explains why. To resume, fix the issue and turn
auto-reload back on.

## Availability

The AI Gateway is available in AWS US East (Ohio), US East (N. Virginia), Europe (Frankfurt), and Asia Pacific (Singapore) (more [regions](https://neon.com/docs/introduction/regions) to follow).

**Note:** **IP Allow** and **Private Networking** do not cover AI Gateway traffic.

## If you downgrade to Free

If your organization moves to the Free plan, your AI Gateway credits **remain on
your account** and you can keep using them. Auto-reload turns off when you
downgrade.

## Related

- [AI Gateway overview](https://neon.com/docs/ai-gateway/overview)
- [Supported models](https://neon.com/docs/ai-gateway/models)
- [AI Gateway troubleshooting](https://neon.com/docs/ai-gateway/troubleshooting)
- [About billing](https://neon.com/docs/introduction/about-billing)
- [Manage billing](https://neon.com/docs/introduction/manage-billing)

## Frequently asked questions

### Who can use AI Gateway?

Any Neon organization with prepaid credits, on any plan, including Free. On the Free plan, add a payment card to buy credits. You don't need to upgrade. Credits give you every model in the catalog.

### How much do AI Gateway credits cost?

1 credit equals $1 USD, with a $5 minimum purchase. You buy credits from the **Billing** page in the [Neon Console](https://console.neon.tech/app/billing).

### Can my credit balance go negative?

Yes, by a small amount. Usage can exceed your remaining balance before it's detected, so a minimum balance of $2 applies to account for this.

### Can I top up credits automatically?

Yes, on paid plans. Auto-reload isn't available on the Free plan yet. Organization admins can turn it on from the **AI gateway credits** card on the **Billing** page. When your balance drops below the threshold you set, Neon buys the amount you chose with the payment card on file. See [Automatic top-up](https://neon.com/docs/ai-gateway/prepaid-credits#automatic-top-up).

### Do credits expire?

Credits are valid for 12 months from the date of purchase.

### What happens to my credits if I downgrade to Free?

Your credits stay on your account, and you can keep using AI Gateway on the Free plan. Auto-reload turns off when you downgrade.

### What are the default usage limits?

By default, each account has a soft limit of 200,000 tokens per minute (TPM), applied to input and output tokens separately, and a $20 per day spend cap, though both may vary by account. Both guard against runaway costs. If you're blocked and need a limit raised, [contact Support](https://neon.com/docs/introduction/support). See [Usage limits](https://neon.com/docs/ai-gateway/prepaid-credits#usage-limits) for details.

### What happens if I hit a usage limit?

Requests are blocked once you reach your per-minute token limit or daily spend cap, and the gateway returns an `HTTP 429` response with error code `REQUEST_LIMIT_EXCEEDED`. See [Usage limits](https://neon.com/docs/ai-gateway/prepaid-credits#usage-limits) for details, or [Troubleshooting](https://neon.com/docs/ai-gateway/troubleshooting#429-account-quota-exceeded) if you hit it.

--- [Document source](https://neon.com/docs/ai-gateway/troubleshooting.md) ---

> Summary: Solutions for common errors when using Neon AI Gateway, including authentication failures, model errors, quota limits, and upstream issues.

# AI Gateway troubleshooting

Common errors and how to fix them

Last updated: 2026-11-04

## Authentication errors

### `401 invalid or missing credential`

The bearer token is missing, malformed, or has been revoked.

**Fix:** Check that `NEON_AI_GATEWAY_TOKEN` is set and contains the full `nt_live_...` token returned when you created the credential. If the credential was revoked, create a new one. See [Authentication](https://neon.com/docs/ai-gateway/authentication#creating-a-credential).

### `403 credential not authorized for ai gateway`

The credential exists but lacks the `ai_gateway:invoke` scope.

**Fix:** Create a new credential that includes `ai_gateway:invoke` in the `scopes` array. You can't add scopes to an existing credential. See [Authentication](https://neon.com/docs/ai-gateway/authentication#creating-a-credential).

### `403 credential not authorized for this branch`

The credential was issued on a branch that is not an ancestor of the branch in the request hostname.

**Fix:** Use a credential issued on the current branch or an ancestor branch. See [Authentication](https://neon.com/docs/ai-gateway/authentication#how-branch-binding-works) for how branch lineage works.

### `503 authorization temporarily unavailable`

The credential store or branch resolver is temporarily unavailable.

**Fix:** Retry the request. This is a transient infrastructure error, not a client error.

---

## Model errors

### `400 unknown model "<model-id>"`

The `model` field in the request body does not match any entry in the AI Gateway catalog. The error message includes the model ID you sent.

**Fix:** Check the model ID against the [full model catalog](https://neon.com/docs/ai-gateway/models). Use the short form (e.g., `gpt-5-mini`) or the `databricks-` prefixed form (`databricks-gpt-5-mini`) — both are accepted.

### `400 model "<model-id>" is not available on the <endpoint> endpoint`

The model exists in the catalog but doesn't work with the endpoint you're calling. The error message names both the model and the endpoint dialect it was sent to (for example, `openai_responses`, `gemini_generate_content`, or `chat_completions`).

**Fix:** Check which endpoint the model requires:

- OpenAI codex models on `/v1/chat/completions` → use `/openai/v1/responses`
- Google models on `/openai/v1/responses` → use `/gemini/v1beta/...` or `/v1/chat/completions`

See [Which endpoint to use](https://neon.com/docs/ai-gateway/models#which-endpoint-to-use).

### `400 missing or invalid model`

The request body does not contain a valid `model` field.

**Fix:** Include `"model": "<model-id>"` in the request body.

### Locked models in the Console

On your project's **AI Gateway** page, a locked model shows a padlock. Hover over the padlock to see why the model is locked, along with a link to fix it:

| Tooltip                                                        | What to do                                                                                                                                                                                                                                                                 |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Add a card to buy AI gateway credits for this model.**       | Your organization is on the Free plan with no payment card on file. Select **Add a card**, add your card, then buy credits. You don't need to upgrade your plan. See [AI Gateway prepaid credits](https://neon.com/docs/ai-gateway/prepaid-credits#buy-or-top-up-credits). |
| **AI Gateway credits are required to use this model.**         | Select **Buy credits**. See [AI Gateway prepaid credits](https://neon.com/docs/ai-gateway/prepaid-credits).                                                                                                                                                                |
| **A paid plan is required to use this model.**                 | Your organization can't buy credits on its current plan, for example because it's billed through the Vercel Marketplace. Select **Upgrade plan**.                                                                                                                          |
| **Account verification is required to use this model.**        | Neon checks your account after your first credit purchase. Wait a few minutes and reload the page. If the tooltip links to **Complete verification** or **Contact support for verification**, follow that link.                                                            |
| **Your account has reached its daily AI Gateway spend limit.** | [Contact Support](https://neon.com/docs/introduction/support) to raise the limit. See [Usage limits](https://neon.com/docs/ai-gateway/prepaid-credits#usage-limits).                                                                                                       |
| **Your account is restricted from using this model.**          | [Contact Support](https://neon.com/docs/introduction/support).                                                                                                                                                                                                             |
| **This model is not available to your account.**               | [Contact Support](https://neon.com/docs/introduction/support).                                                                                                                                                                                                             |

Only organization admins can add a card or buy credits. After you buy credits, models unlock once Neon confirms access, usually within a few seconds. Reload the page if a model still shows as locked.

---

## Gemini-specific errors

### `404 unsupported gemini action`

The action in the Gemini endpoint URL is unsupported. The AI Gateway supports Gemini `generateContent` and streaming `streamGenerateContent` calls.

**Fix:** Use either `:<model-id>:generateContent` or `:<model-id>:streamGenerateContent`. Other actions (`countTokens`, etc.) are not available.

### `404 invalid gemini model path`

The `{modelAction}` segment in the Gemini URL path is malformed. It must follow the format `<model>:<action>` where both parts are non-empty.

**Fix:** Ensure the URL path contains exactly one colon separating the model ID and action, e.g. `gemini-3-flash:generateContent`.

---

## Workspace resolution errors

### `403` or `400`: `could not resolve workspace from host`

The request host does not match the expected format or region.

**Common causes:**

- The host does not end with a trusted suffix (`.neon.tech` in production). Returns 403.
- The host has no parseable AWS region label. Returns 400.
- The region in the host has no configured workspace. Returns 404.

**Fix:** Verify that you are using the correct AI Gateway host from the Neon Console or API. The host format for production is `<branch-id>-api.ai.<cell>.<region>.aws.neon.tech`. Do not construct the host manually.

---

## Rate limiting and quota

### `429`: upstream provider rate limit

The request hit the upstream Databricks/provider rate limit.

**Fix:** Implement exponential backoff. The response includes a `Retry-After` header and provider-specific rate limit headers (`X-Ratelimit-*`). See [Rate limiting](https://neon.com/docs/ai-gateway/chat-completions#rate-limiting).

### `429`: account quota exceeded

Your account's AI Gateway quota is blocked. This happens when you exceed a token-per-minute (TPM) rate limit or your account's daily spend limit, or when your prepaid credit balance drops below the $2 minimum. All three return `REQUEST_LIMIT_EXCEEDED`, and the message names the limit that was hit and how to recover.

An account-wide TPM limit:

```json
{
  "error_code": "REQUEST_LIMIT_EXCEEDED",
  "message": "You've exceeded your AI Gateway account input token limit (<N> input tokens per minute across all models). You can retry once the current minute resets, or ask Neon support to raise it (we review all increases to prevent abuse): https://console.neon.tech/app/projects?modal=support"
}
```

A per-model TPM limit names the model instead. Only the `message` value changes:

```text
You've exceeded your AI Gateway input token limit for model "<model-id>" (<N> input tokens per minute). You can retry once the current minute resets, or ask Neon support to raise it (we review all increases to prevent abuse): https://console.neon.tech/app/projects?modal=support
```

Input and output tokens are limited separately. When the output limit is hit, the same messages say `output` instead of `input`.

A daily spend limit:

```json
{
  "error_code": "REQUEST_LIMIT_EXCEEDED",
  "message": "You've reached your AI Gateway daily spend limit. You can retry after it resets, or ask Neon support to raise it (we review all increases to prevent abuse): https://console.neon.tech/app/projects?modal=support"
}
```

A credit balance below the minimum. The response includes a link to add credits:

```json
{
  "error_code": "REQUEST_LIMIT_EXCEEDED",
  "message": "AI Gateway credit balance is below the required minimum. Add credits to continue. <recovery URL>",
  "unavailable_reason": "credits_required",
  "recovery_url": "<recovery URL>"
}
```

This block has no `Retry-After` header and doesn't clear on its own. [Buy credits](https://neon.com/docs/ai-gateway/prepaid-credits#buy-or-top-up-credits), or turn on [automatic top-up](https://neon.com/docs/ai-gateway/prepaid-credits#automatic-top-up) so it doesn't happen again.

**Fix:** Check the `Retry-After` header. If present, the block is temporary and lifts at that time; retry with exponential backoff. If absent, the block lasts until it's resolved: for a low credit balance, add credits; for a limit, ask Support to raise it. See [Support](https://neon.com/docs/introduction/support) for your plan's support options and [Rate limits](https://neon.com/docs/ai-gateway/models#rate-limits) for current values.

---

## Upstream errors

When the upstream model provider or Databricks returns an error, the AI Gateway replaces the upstream response body with its own `{"error_code","message"}` envelope and preserves the upstream status code. Upstream internal details, such as endpoints, workspace IDs, Unity Catalog objects, principals, and internal headers, are never exposed to the caller.

The message identifies the condition:

| Condition               | Message                                                                                                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Endpoint disabled       | `This model is temporarily disabled. Contact Neon support for help: https://console.neon.tech/app/projects?modal=support`                                              |
| Timeout                 | `The model took too long to respond. Reduce max_tokens or your input size, or use streaming.`                                                                          |
| Request too large       | `ai gateway upstream rejected the request: body too large`                                                                                                             |
| Model unavailable       | `ai gateway upstream model is not available. Contact Neon support`                                                                                                     |
| Access denied           | `ai gateway upstream denied the request. Contact Neon support`                                                                                                         |
| Over capacity           | `ai gateway upstream model is temporarily over capacity. Retry later`                                                                                                  |
| Upstream internal error | `ai gateway upstream model error. Retry later, or contact Neon support if it persists`                                                                                 |
| Invalid request         | `ai gateway upstream model rejected the request: <provider message>` (redacted to `...rejected the request as invalid` when the provider detail can't be shown safely) |
| Unknown                 | `ai gateway upstream request failed. Contact Neon support if it persists`                                                                                              |

**Fix:** Follow the guidance in the message. Retry transient conditions (over capacity, upstream internal error) with exponential backoff, respecting any `Retry-After` header. Don't retry a timeout as is: the gateway sends `X-Should-Retry: false` so the OpenAI and Anthropic SDKs skip their automatic retry, because each retry runs the whole slow generation again. Reduce `max_tokens` or the input size, or use streaming. If an error persists, check the [Neon status page](https://neonstatus.com). For paid plan support options, see [Support](https://neon.com/docs/introduction/support).

---

## Error response formats

Errors the gateway generates itself (authentication, model validation, workspace resolution) use the standard OpenAI error envelope:

```json
{
  "error": {
    "message": "unknown model \"<model-id>\""
  }
}
```

Quota blocks and all upstream (non-2xx) errors use a flat envelope, with the upstream status code preserved:

```json
{
  "error_code": "REQUEST_LIMIT_EXCEEDED",
  "message": "You've reached your AI Gateway daily spend limit. You can retry after it resets, or ask Neon support to raise it (we review all increases to prevent abuse): https://console.neon.tech/app/projects?modal=support"
}
```

--- [Document source](https://neon.com/docs/ai/agent-setup.md) ---

> Summary: Set up Neon in an AI coding agent (Claude Code, Cursor, Codex, VS Code with GitHub Copilot, and more) or a chat app (ChatGPT, Claude.ai, Grok Bot). Copy the Set up agent prompt so your agent installs the Neon CLI and the Neon plugin (agent skills plus the Neon MCP Server), or run `npx neon@latest init` in your project. Per-agent pages cover chat apps, manual installs, and MCP-only setup.

# Set up your AI agent for Neon

Connect Neon to your coding agent or chat app

[View prompt](https://neon.com/prompts/agent-setup-landing.md)

That's all most coding agents need: your agent installs the Neon CLI, signs you in, and installs the Neon plugin. Restart it afterward. Prefer a terminal? Run [`npx neon@latest init`](https://neon.com/docs/cli/init) instead.

## Set up a specific agent

Use these pages to connect a chat app like ChatGPT or Claude.ai, to run the install yourself, or for MCP-only and API key setup.

- [Claude Code](https://neon.com/docs/ai/agent-setup/claude-code)
- [Cursor](https://neon.com/docs/ai/agent-setup/cursor)
- [Codex](https://neon.com/docs/ai/agent-setup/codex)
- [VS Code and GitHub Copilot](https://neon.com/docs/ai/agent-setup/vscode)
- [ChatGPT](https://neon.com/docs/ai/agent-setup/chatgpt)
- [Claude.ai and Claude Desktop](https://neon.com/docs/ai/agent-setup/claude-ai)
- [Grok Bot](https://neon.com/docs/ai/agent-setup/grok-bot)
- [Zed, Devin, Kiro, and more](https://neon.com/docs/ai/connect-mcp-clients-to-neon)

## What gets installed

The Neon plugin bundles seven Neon [agent skills](https://neon.com/docs/ai/agent-skills): `neon`, `neon-postgres`, `neon-auth`, `neon-functions`, `neon-object-storage`, `neon-ai-gateway`, and `neon-realtime`. It also includes the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server), which your agent signs in to with OAuth the first time it uses it.

## Building agents on Neon?

- [Agent plan](https://neon.com/docs/introduction/agent-plan): A pricing tier for platforms that provision databases for their users
- [AI agent integration](https://neon.com/docs/guides/ai-agent-integration): Provision per-tenant databases and versions with the Neon API
- [Database versioning](https://neon.com/docs/ai/ai-database-versioning): Snapshot APIs for codegen and agent platforms
- [Claimable Neon](https://neon.com/docs/reference/claimable-neon): Provision a project now; your user claims it later

--- [Document source](https://neon.com/docs/ai/agent-setup/chatgpt.md) ---

> Summary: Add the Neon plugin to ChatGPT from Settings > Plugins > Browse directory. The plugin includes Neon's agent skills and the Neon app, which connects ChatGPT to your Neon account through the Neon MCP Server with OAuth.

# Set up Neon in ChatGPT

Add the Neon plugin from the ChatGPT plugins directory

The Neon plugin for ChatGPT includes Neon's agent skills and the **Neon** app. The app connects ChatGPT to your Neon account through the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server). With the plugin, ChatGPT can manage your projects, branches, and SQL in natural language.

**Important: Security**

The Neon MCP Server is intended for **development and testing only**. Always review LLM-requested actions before execution. See [MCP security guidance](https://neon.com/docs/ai/neon-mcp-server#mcp-security-guidance).

## Add the Neon plugin

1. In ChatGPT, go to **Settings** → **Plugins** → **Browse directory**.
2. Search for **Neon** and click **+ Install plugin**.
3. Sign in to Neon when prompted. During authorization, choose read-only or full access.

Then ask in natural language, for example:

```text
List my Neon projects
```

See [Available tools](https://neon.com/docs/ai/neon-mcp-server#available-tools) for everything the Neon app can do.

## Use Neon with dots

Dots, ChatGPT's always-on agents, use the same plugin settings as your ChatGPT account. After you install the Neon plugin, connect it to a dot from **Customize** → **Plugins** in the dot's profile. See [Getting started with your dot](https://help.openai.com/en/articles/20001530-getting-started-with-your-dot).

To build an app on Neon with OpenAI's coding agent, see [Set up Neon in Codex](https://neon.com/docs/ai/agent-setup/codex).

--- [Document source](https://neon.com/docs/ai/agent-setup/claude-ai.md) ---

> Summary: Connect Claude.ai or Claude Desktop to Neon by adding the official Neon connector (Settings > Connectors > Browse connectors) and signing in with OAuth. Claude Desktop can also load the Neon MCP Server from claude_desktop_config.json through the mcp-remote bridge.

# Set up Neon in Claude.ai and Claude Desktop

Add Neon as a Claude connector, or configure the Neon MCP Server in Claude Desktop

Claude.ai and Claude Desktop connect to Neon through the hosted [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server), which is an official Claude connector. Add the connector once and sign in, and Claude can manage your projects, branches, and SQL in natural language.

Using Claude Code? See [Set up Neon in Claude Code](https://neon.com/docs/ai/agent-setup/claude-code) instead.

**Important: Security**

The Neon MCP Server is intended for **development and testing only**. Always review LLM-requested actions before execution. See [MCP security guidance](https://neon.com/docs/ai/neon-mcp-server#mcp-security-guidance).

## Add the Neon connector

You don't need a custom connector URL. In [Claude.ai](https://claude.ai) or Claude Desktop:

1. Open **Settings** from your profile menu.
2. Select **Connectors** (sometimes shown under **Customize > Connectors**).
3. Click **Browse connectors** (top-right of that page), find **Neon**, and add it.
4. Authorize access to your Neon account.

Then ask in natural language, for example:

```text
List my Neon projects
```

See [Available tools](https://neon.com/docs/ai/neon-mcp-server#available-tools) for everything the server can do.

## Use a config file instead

Claude Desktop's `claude_desktop_config.json` only supports local (stdio) servers. If you manage Claude Desktop with that file, add the [`mcp-remote` bridge config](https://neon.com/docs/ai/neon-mcp-server#deprecated-stdio). Open the file from **Settings** → **Developer** → **Edit Config**, then restart Claude Desktop. For a walkthrough, see [Get started with Claude Desktop and Neon MCP Server](https://neon.com/guides/neon-mcp-server).

--- [Document source](https://neon.com/docs/ai/agent-setup/claude-code.md) ---

> Summary: Install the Neon plugin in Claude Code with `npx neon@latest plugins --agent claude-code --global`, or from Neon's plugin marketplace with `/plugin install neon-postgres@neon`. The plugin bundles seven Neon agent skills and the Neon MCP Server. Also covers the official Claude marketplace listing, MCP-only setup with OAuth or an API key, and skills-only setup.

# Set up Neon in Claude Code

Install the Neon plugin for agent skills and the Neon MCP Server

The Neon plugin gives [Claude Code](https://docs.anthropic.com/en/docs/claude-code) Neon's agent skills, so it knows how to build on Neon, and the Neon MCP Server, so it can act on your Neon account.

## Install the plugin

Run:

```bash
npx neon@latest plugins --agent claude-code
```

This installs the plugin at user level, for all your projects. See [`neon plugins`](https://neon.com/docs/cli/plugins) for all options.

Then run `/reload-plugins` in Claude Code, or start a new session. Claude Code asks you to sign in to Neon with OAuth the first time it uses an MCP tool.

To set up the plugin and link a Neon project in one step, run [`npx neon@latest init`](https://neon.com/docs/cli/init) instead.

## Check that it works

Ask Claude Code:

```text
Which Neon skills do you have access to?
```

You should see the Neon skills listed. Then try:

```text
Get started with Neon
```

## Other ways to install

### From a plugin marketplace

In a Claude Code session, install the plugin from Neon's marketplace. This is the same plugin `neon plugins` installs:

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

It's also in Anthropic's official marketplace as `neon@claude-plugins-official`. That listing is pinned to a specific commit and updated separately, so it can lag behind. Install from one marketplace only.

### MCP Server only

To add only the Neon MCP Server, without skills, use OAuth:

```bash
claude mcp add --transport http neon https://mcp.neon.tech/mcp
```

Start a new `claude` session, or run `/mcp`, to sign in. For a [Neon API key](https://neon.com/docs/manage/api-keys) instead, run [`npx neon@latest mcp --agent claude-code`](https://neon.com/docs/cli/mcp), which mints one. The [config generator](https://neon.com/docs/ai/neon-mcp-server#config-generator) also builds an API key config, with read-only mode and other access controls.

### Skills only

```bash
npx neon@latest skills --agent claude-code
```

For an end-to-end example, see [Get started with Claude Code and Neon MCP Server](https://neon.com/guides/claude-code-mcp-neon). If something isn't working, see [MCP troubleshooting](https://neon.com/docs/ai/neon-mcp-server#troubleshooting).

--- [Document source](https://neon.com/docs/ai/agent-setup/codex.md) ---

> Summary: Install the Neon plugin in OpenAI Codex from the plugin directory (`/plugins` in the Codex CLI, or Plugins in the Codex app), or run `npx neon@latest plugins --agent codex`. The plugin bundles the Neon MCP Server, shown in Codex as the Neon app, and Neon's agent skills. Also covers MCP-only setup in .codex/config.toml and skills-only setup.

# Set up Neon in Codex

Install the Neon plugin in the Codex CLI or the Codex app

The Neon plugin gives [OpenAI Codex](https://developers.openai.com/codex/) Neon's [agent skills](https://developers.openai.com/codex/skills/), so it knows how to build on Neon. It also adds the Neon MCP Server, so Codex can act on your Neon account. In Codex, the MCP Server appears as the **Neon** app.

## Install the plugin

**Codex CLI**

In the Codex CLI, run `/plugins`, open **Neon**, and choose **Add to Codex**. To install the Codex CLI first, see [Codex CLI](https://developers.openai.com/codex/cli).

**Codex app**

In the Codex app, open **Plugins**, search for **Neon**, and choose **Add to Codex**.

**Neon CLI**

Install the plugin:

```bash
npx neon@latest plugins --agent codex
```

If Codex asks you to connect Neon, follow the prompts. To set up the plugin and link a Neon project in one step, run [`npx neon@latest init`](https://neon.com/docs/cli/init) instead.

## Check that it works

Start a new thread, or type `@` to pick the **Neon** plugin, and ask:

```text
Use Neon to create a new Postgres database for my project and help me connect to it.
```

## Other ways to install

### MCP Server only

```bash
npx add-mcp https://mcp.neon.tech/mcp -a codex
```

This adds a `neon` entry to `.codex/config.toml` (add `-g` to write `~/.codex/config.toml` instead). Restart Codex. If Codex doesn't prompt you to sign in, run `codex mcp login neon` and click **Authorize** in the OAuth window.

Or run [`npx neon@latest mcp --agent codex`](https://neon.com/docs/cli/mcp). For read-only mode and other access controls, see the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server) reference.

### Skills only

```bash
npx neon@latest skills --agent codex
```

For a schema refactoring walkthrough, see [Safe AI-powered schema refactoring with OpenAI Codex and Neon](https://neon.com/guides/openai-codex-neon-mcp). If something isn't working, see [MCP troubleshooting](https://neon.com/docs/ai/neon-mcp-server#troubleshooting).

--- [Document source](https://neon.com/docs/ai/agent-setup/cursor.md) ---

> Summary: Install the Neon plugin in Cursor with `/add-plugin neon-postgres` in Cursor chat, from the Cursor marketplace, or with `npx neon@latest plugins --agent cursor --global`. The plugin bundles seven Neon agent skills and the Neon MCP Server. Also covers MCP-only setup (one-click install, OAuth, or an API key) and skills-only setup.

# Set up Neon in Cursor

Install the Neon plugin for agent skills and the Neon MCP Server

The Neon plugin gives Cursor Neon's agent skills, so it knows how to build on Neon, and the Neon MCP Server, so it can act on your Neon account.

## Install the plugin

In Cursor chat, run:

```text
/add-plugin neon-postgres
```

Or install it from [cursor.com/marketplace/neon](https://cursor.com/marketplace/neon), or from a terminal:

```bash
npx neon@latest plugins --agent cursor
```

When Cursor first uses a Neon MCP tool, follow the prompts to sign in to Neon.

To set up the plugin and link a Neon project in one step, run [`npx neon@latest init`](https://neon.com/docs/cli/init) instead.

## Check that it works

Ask Cursor:

```text
Get started with Neon
```

## Other ways to install

### MCP Server only

[https://cursor.com/en-US/install-mcp?name=Neon&config=eyJ1cmwiOiJodHRwczovL21jcC5uZW9uLnRlY2gvbWNwIn0%3D](https://cursor.com/en-US/install-mcp?name=Neon\&config=eyJ1cmwiOiJodHRwczovL21jcC5uZW9uLnRlY2gvbWNwIn0%3D)

Click the button to add the Neon MCP Server with OAuth. For a [Neon API key](https://neon.com/docs/manage/api-keys) instead, run [`npx neon@latest mcp --agent cursor`](https://neon.com/docs/cli/mcp), which mints one. The [config generator](https://neon.com/docs/ai/neon-mcp-server#config-generator) also builds an API key config, with read-only mode and other access controls.

### Skills only

```bash
npx neon@latest skills --agent cursor
```

For an end-to-end example, see [Get started with Cursor and the Neon MCP Server](https://neon.com/guides/cursor-mcp-neon). If something isn't working, see [MCP troubleshooting](https://neon.com/docs/ai/neon-mcp-server#troubleshooting).

--- [Document source](https://neon.com/docs/ai/agent-setup/grok-bot.md) ---

> Summary: Connect Neon to Grok Bot so you can create projects, work with branches, and run SQL from chat.

# Set up Neon in Grok Bot

Add the Neon plugin to Grok Bot to work with projects, branches, and SQL from chat

Last updated: 2026-11-05

The Neon plugin for Grok Bot connects your Neon account. After you authorize it, you can create projects, work with branches, and run SQL without leaving Grok Bot.

## Install the plugin

[Add the Neon plugin](https://neon.com/docs/ai/agent-setup/grokbot://app/v1/plugin/add?id=669) in Grok Bot. The link opens the Neon Postgres plugin page.

If the link doesn't open Grok Bot, install from the plugins directory:

1. Launch Grok Bot.
2. Select **Plugins** in the sidebar.
3. Enter `neon` in the search field.
4. Select **Add** next to **Neon Postgres**.

![Plugins directory in Grok Bot, searching for Neon](https://neon.com/docs/ai/grok_bot_plugins_search.png)

## Ask for the Neon connector

You can skip the plugins directory. In a Grok Bot chat, ask it to connect Neon:

```text
Can you connect Neon?
```

The bot finds the Neon Postgres plugin and asks you to confirm. Then it shows a connect card in the chat. Authorize Neon in the browser when that card appears.

## Connect your Neon account

After you add the plugin, Grok Bot asks you to authorize Neon in the browser. The plugin page then shows the default account as **Connected**.

To connect another Neon account, add it from the plugin page and authorize it the same way.

![Neon Postgres plugin in Grok Bot, with the default account Connected](https://neon.com/docs/ai/grok_bot_plugin.png)

## Use Neon in Grok Bot

Once it's connected, you can ask a bot to:

- Create a project and get a connection string for your app
- Create an isolated branch to test a migration
- List projects and see which databases are unused
- Create a routine that summarizes database usage
- Coordinate a branch handoff between bots

![Grok Bot using the Neon plugin to list organizations](https://neon.com/docs/ai/grok_bot_chat.png)

For example:

```text
Create a Neon project for this application and help me connect to it.
```

To use Neon from a coding agent instead, see [Set up your AI agent](https://neon.com/docs/ai/agent-setup).

--- [Document source](https://neon.com/docs/ai/agent-setup/vscode.md) ---

> Summary: Set up Neon for GitHub Copilot in VS Code and the GitHub Copilot CLI. Install the Neon plugin at user level with `npx neon@latest plugins --agent vscode --global`, or add only the Neon MCP Server to .vscode/mcp.json with OAuth or an API key. Also covers the Neon VS Code extension, which configures the MCP Server on sign-in, and the Neon Migration Specialist and Neon Performance Analyzer custom agents for Copilot.

# Set up Neon in VS Code and GitHub Copilot

Install the Neon plugin, the Neon MCP Server, or Neon's custom agents for GitHub Copilot

GitHub Copilot in VS Code gets Neon through the Neon plugin, which bundles Neon's agent skills and the Neon MCP Server. To use MCP servers in VS Code, you need the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) and [GitHub Copilot Chat](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) extensions.

## Install the plugin

Run:

```bash
npx neon@latest plugins --agent vscode
```

The GitHub Copilot CLI uses the same plugin target (`github-copilot`), so `--agent github-copilot-cli` installs to the same place.

[`npx neon@latest init`](https://neon.com/docs/cli/init) sets up VS Code with the skills and MCP Server installed separately (not the plugin) and links a Neon project.

## Check that it works

Open GitHub Copilot Chat, [switch to Agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode), and ask:

```text
Get started with Neon
```

## Other ways to install

### MCP Server only

```bash
npx add-mcp https://mcp.neon.tech/mcp -a vscode
```

This writes `.vscode/mcp.json` in your project (`-g` writes your user-level `mcp.json`). Restart VS Code or enable the server in settings, and click **Authorize** when the OAuth window opens. Or run [`npx neon@latest mcp --agent vscode`](https://neon.com/docs/cli/mcp).

To configure it by hand with a [Neon API key](https://neon.com/docs/manage/api-keys), add this to `.vscode/mcp.json`:

```json
{
  "servers": {
    "neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_NEON_API_KEY>"
      }
    }
  }
}
```

For read-only mode and other access controls, see the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server) reference.

### Skills only

```bash
npx neon@latest skills --agent vscode
```

### Neon VS Code extension

The [Neon VS Code extension](https://neon.com/docs/local/vscode-extension) lets you browse projects, branches, and tables in the editor. When you sign in, it also configures the Neon MCP Server.

## Neon custom agents for GitHub Copilot

Neon publishes two custom agents for GitHub Copilot in the [awesome-copilot](https://github.com/github/awesome-copilot) repository. Both work on temporary branches (default TTL of 4 hours), away from your main branch:

- The [Neon Migration Specialist](https://github.com/github/awesome-copilot/blob/main/agents/neon-migration-specialist.agent.md) tests a migration on a temporary branch, then opens a PR with the migration files for you or your CI/CD to apply. It works with your ORM's migration system (Prisma, Drizzle, SQLAlchemy, Django, Rails, and more) and never runs migrations on your main branch.
- The [Neon Performance Analyzer](https://github.com/github/awesome-copilot/blob/main/agents/neon-optimization-analyzer.agent.md) finds slow queries with `pg_stat_statements` and `EXPLAIN`, tests indexes and query rewrites on a temporary branch, and opens a PR with before and after metrics.

Both agents call the Neon API directly, so they need a [Neon API key](https://console.neon.tech/app/settings#api-keys) and a project ID or connection string. They ask for these if you haven't provided them. To install an agent, use its **Install in VS Code** button in the [awesome-copilot custom agents list](https://github.com/github/awesome-copilot/blob/main/docs/README.agents.md), or add its `.agent.md` file to your repository's `.github/agents/` directory. Then mention it in GitHub Copilot Chat:

```text
@neon-migration-specialist Add a new email column to my users table
```

--- [Document source](https://neon.com/docs/ai/agent-skills.md) ---

> Summary: Agent Skills are structured context files (SKILL.md) that give AI coding assistants accurate knowledge of Neon's cloud backend primitives, APIs, SDKs, and best practices. Install them when using Cursor, Claude Code, OpenAI Codex, or any Agent Skills-compatible tool. Skills cover Postgres, Managed Better Auth, Neon Functions, Object Storage, AI Gateway, branching workflows, and more. Install them with `neon skills`, `npx skills add neondatabase/agent-skills -y`, `neon init`, or the Neon plugin, at project or user level.

# Agent Skills

Teach your AI coding assistant how to work with Neon

Last updated: 2026-11-05

Agent Skills provide your AI coding assistant with structured context about Neon's platform, APIs, and best practices. With skills installed, your assistant produces more accurate code and avoids common mistakes when working with Neon, from Postgres and Auth to [Neon Functions](https://neon.com/docs/compute/functions/overview), [Object Storage](https://neon.com/docs/storage/overview), and the [AI Gateway](https://neon.com/docs/ai-gateway/overview).

[Watch on YouTube](https://youtube.com/watch?v=NN251KTjAo8)

## Install

There are several ways to install Neon skills depending on your editor and workflow.

### neon skills

The [Neon CLI](https://neon.com/docs/cli) installs skills interactively:

```bash
neon skills
```

It pre-selects your detected agents, lets you pick which skills to add, and confirms before writing. Pass `-s <skill>` and `--agent <name>` to skip the prompts, `--global` to install user-level, and run `neon skills update` to refresh installed skills. To see which installed skills have updates, run `neon skills status`. Other `neon` commands also warn you once a day when a skill is out of date. Both cover skills installed with `neon skills` or `npx skills add`, not plugins. See the [`neon skills` reference](https://neon.com/docs/cli/skills) for all options.

### npx skills

For any AI tool that supports the [Agent Skills](https://agentskills.io) format, install skills from the [Agent Skills repository](https://github.com/neondatabase/agent-skills):

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

This installs **all** skills in the repository. To install a specific skill instead, pass the `-s` flag:

```bash
npx skills add neondatabase/agent-skills -s neon -y
```

Useful flags:

- `-y` skips the interactive prompt and installs immediately
- `-s` selects one or more skills (repeat the flag for multiple skills)
- `-g` installs globally instead of at the project level (see [Project vs. user level](https://neon.com/docs/ai/agent-skills#project-level-vs-global-install))

### Plugins

The Neon plugin bundles seven Neon [agent skills](https://neon.com/docs/ai/agent-skills): `neon`, `neon-postgres`, `neon-auth`, `neon-functions`, `neon-object-storage`, `neon-ai-gateway`, and `neon-realtime`. It also includes the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server), which your agent signs in to with OAuth the first time it uses it.

For most coding agents, the plugin is the easier option. To install it, see [Set up your AI agent](https://neon.com/docs/ai/agent-setup).

### neon init

[`npx neon@latest init`](https://neon.com/docs/cli/init) installs the plugin, or skills and the MCP Server, for your coding agents and links a Neon project.

## Available skills

Skills are grouped by area. Each skill is a `SKILL.md` entry point that your agent reads and invokes when relevant. Browse and install individual skills on [skills.sh](https://skills.sh/neondatabase/agent-skills).

Install any of them by name with [`neon skills`](https://neon.com/docs/cli/skills) (`-s` is repeatable):

```bash
neon skills -s neon -s neon-postgres
```

Without the Neon CLI, run `npx skills add neondatabase/agent-skills -s neon -s neon-postgres` instead.

### Core

Start here for platform overview and Postgres development.

| Skill                                                                        | Description                                                                                                                                                |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`neon`](https://skills.sh/neondatabase/agent-skills/neon)                   | Platform overview for apps and agents: Postgres, Auth, Data API, Functions, Storage, and AI Gateway, including Claimable Neon when there is no account yet |
| [`neon-postgres`](https://skills.sh/neondatabase/agent-skills/neon-postgres) | Full index of Neon Serverless Postgres documentation and best practices, including branching workflows and egress optimization                             |

### Neon Platform

Use Neon services beyond core Postgres. **Functions**, **Object Storage**, **AI Gateway**, and **Realtime** are available in AWS US East (Ohio), US East (N. Virginia), Europe (Frankfurt), and Asia Pacific (Singapore), with more regions coming. See the [backend overview](https://neon.com/docs/get-started/backend-overview) for details.

| Skill                                                                                    | Description                                                                                                         | Docs                                                               |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [`neon-functions`](https://skills.sh/neondatabase/agent-skills/neon-functions)           | Long-running serverless Node.js HTTP functions on your branch, with `DATABASE_URL` injected automatically           | [Neon Functions](https://neon.com/docs/compute/functions/overview) |
| [`neon-object-storage`](https://skills.sh/neondatabase/agent-skills/neon-object-storage) | S3-compatible object storage that branches with your project                                                        | [Object Storage](https://neon.com/docs/storage/overview)           |
| [`neon-ai-gateway`](https://skills.sh/neondatabase/agent-skills/neon-ai-gateway)         | One API and credential for frontier and open-source LLMs; compatible with OpenAI, Anthropic, and Vercel AI SDKs     | [AI Gateway](https://neon.com/docs/ai-gateway/overview)            |
| [`neon-auth`](https://skills.sh/neondatabase/agent-skills/neon-auth)                     | Add authentication with Managed Better Auth: sign-up, sign-in, OAuth, magic links, OTP, passkeys, and organizations | [Managed Better Auth](https://neon.com/docs/auth/overview)         |
| [`neon-realtime`](https://skills.sh/neondatabase/agent-skills/neon-realtime)             | Live SQL queries and reactivity primitives, so app UI and agent state update as rows change                         | [Realtime](https://neon.com/docs/realtime/overview)                |

### Agent platforms

For codegen tools and multi-tenant products that provision Neon for their users, see the companion skill in [neondatabase/neon-for-agent-platforms](https://github.com/neondatabase/neon-for-agent-platforms) (`neon-postgres-agent-platforms` on [skills.sh](https://skills.sh/neondatabase/neon-for-agent-platforms/neon-postgres-agent-platforms)).

## Project vs. user level

Project-level installs live in your project directory and can be committed with it. User-level (global) installs apply across all your projects. Each install method has its own default:

| How you install                                             | Where it goes                                                                                                                                                                                         |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Set up agent prompt](https://neon.com/docs/ai/agent-setup) | User level                                                                                                                                                                                            |
| `neon init` (recommended setup)                             | User level, for each detected agent. With no agent detected, skills go in the current directory. [Custom setup](https://neon.com/docs/cli/init#recommended-and-custom-setup) can write to the project |
| [`neon plugins`](https://neon.com/docs/cli/plugins)         | User level                                                                                                                                                                                            |
| [`neon skills`](https://neon.com/docs/cli/skills)           | Project by default; `--global` for user level                                                                                                                                                         |
| `npx skills add`                                            | Project by default; `-g` for user level                                                                                                                                                               |
| [`neon mcp`](https://neon.com/docs/cli/mcp)                 | Asks; `--project` for the project, `-y` for user level                                                                                                                                                |

## What's covered

With the full skill set installed, your assistant can guide you across Neon:

**Postgres and platform basics (`neon`, `neon-postgres`)**

- **Getting started** with Neon, including project setup and key features (branching, autoscaling, scale-to-zero, instant restore, read replicas)
- **Connections**, including the serverless driver, connection pooling, and connection strings
- **Authentication** with Managed Better Auth
- **Data API** via `@neon/neon-js`
- **Platform APIs and SDKs**, including the REST API, TypeScript SDK, and Python SDK
- **Developer tools**, including the CLI, VS Code extension, and MCP server

**Database workflows**

- **Disposable projects** via [Claimable Neon](https://neon.com/claimable-neon), for agents and tests
- **Branch types and workflows** for migrations, schema-only branches, and reset-from-parent
- **Egress optimization** for high transfer costs and query anti-patterns

**Platform services**

- **Neon Functions**: declare, deploy, and connect long-running compute next to your database
- **Object Storage**: S3-compatible storage that branches with your data
- **AI Gateway**: model routing, logging, and cost controls with a single Neon credential

For example, ask your assistant to "set up Managed Better Auth in my Next.js app" and it will provide the correct imports, configuration, and middleware setup. Or ask it to "add an AI Gateway route in my `neon.ts` file" and it will follow the correct constraints and SDK patterns.

## Example prompts

```
Get started with Neon
```

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

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

```
Set up Managed Better Auth for my Next.js app
```

```
Create a Neon branch for this feature
```

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

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

```
Add a serverless function to my Neon branch
```

```
Set up S3-compatible storage in neon.ts
```

```
Route LLM calls through the Neon AI Gateway
```

## How it works

Your AI assistant reads the `SKILL.md` file to understand what Neon guidance is available. When you ask about a specific topic, the skill fetches the relevant documentation from online, so your assistant always has up-to-date context without bundling everything locally. For the complete source, see the [Agent Skills repository](https://github.com/neondatabase/agent-skills).

--- [Document source](https://neon.com/docs/ai/ai-azure-notebooks.md) ---

> Summary: Azure Data Studio Notebooks support Jupyter-style Python notebooks that connect to a Lakebase Postgres database and run pgvector similarity search queries using the psycopg driver. Use this guide when you want to combine SQL, Python, and markdown in a single interactive document to prototype vector search without leaving Azure Data Studio. The walkthrough covers installing psycopg, enabling the pgvector extension with CREATE EXTENSION, inserting 3-dimensional vector embeddings, and querying nearest neighbors with the <-> distance operator.

# Azure Data Studio Notebooks

Use Azure Data Studio Notebooks with Neon for vector similarity search

Last updated: 2026-09-16

A Jupyter Notebook is an open-source web application that allows you to create and share documents containing live code, equations, visualizations, and narrative text. Azure Data Studio supports Jupyter Notebooks, enabling users to combine SQL queries, Python code, and markdown text in a single interactive document.

This guide describes how to create a new python notebook in Azure Data Studio, connect to a Neon database, install the `pgvector` extension to enable Neon as a vector store, and run a vector search query.

## Prerequisites

To perform the steps in this guide, you will require:

- Azure Data Studio - Download the latest version of Azure Data Studio for your operating system [here](https://learn.microsoft.com/en-us/azure-data-studio/download-azure-data-studio).

- A Neon account - If you do not have one, sign up at [Neon](https://console.neon.tech/signup). Your Neon project comes with a ready-to-use Postgres database named `neondb`. You can use it, or create your own by following the instructions [here](https://neon.com/docs/manage/databases#create-a-database).

## Retrieve your Neon database connection string

Click **Connect** in the Console nav to open the **Connect to your branch** modal, and select a branch, a user, and the database you want to connect to. A connection string is constructed for you.

![Connection modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

## Create a notebook

1. Go to the **File** menu for Azure Data Studio and select **New Notebook**.
2. Select **Python 3** for the Kernel and set **Attach to** to "localhost" where it can access your Python installation.

You can save the notebook using the **Save** or **Save as...** command from the **File** menu.

## Configure Python for Notebooks

The first time you connect to the Python kernel in a notebook, the **Configure Python for Notebooks** page is displayed. You can select either:

- **New Python installation** to install a new copy of Python for Azure Data Studio, or
- **Use existing Python installation** to specify the path to an existing Python installation for Azure Data Studio to use

To view the location and version of the active Python kernel, you can create a code cell and run the following Python commands:

```python
import os
import sys
print(sys.version_info)
print(os.path.dirname(sys.executable))
```

## Running a code cell

You can create cells containing Python code that you can run in place by clicking the **Run cell** button (the round blue arrow) to the left of the cell. The results are shown in the notebook after the cell finishes running. In the `pgvector` example that follows, you'll add and execute several code cells.

## pgvector example

After you've set up Azure Data Studio and have created a notebook, you can use the following basic example to get started with Neon and `pgvector`.

### Install the psycopg driver

psycopg is a popular Postgres database adapter for the Python programming language. It allows Python applications to connect to and interact with Postgres databases.

Install the `psycopg` adapter by adding and executing the following code cell:

```python
!pip install psycopg
```

### Connect to your database

1. In your notebook, create a code block to define your Neon database connection and create a cursor object. Replace `postgresql://[user]:[password]@[neon_hostname]/[dbname]` with the database connection string you retrieved previously.

   ```python
   import os
   import psycopg

   # Provide your Neon connection string
   connection_string = "postgresql://[user]:[password]@[neon_hostname]/[dbname]"

   # Connect using the connection string
   connection = psycopg.connect(connection_string)

   # Create a new cursor object
   cursor = connection.cursor()
   ```

2. Execute the code block.

3. Add a code block for testing the database connection.

   ```python
   # Execute this query to test the database connection
   cursor.execute("SELECT 1;")
   result = cursor.fetchone()

   # Check the query result
   if result == (1,):
       print("Your database connection was successful!")
   else:
       print("Your connection failed.")
   ```

4. Execute the code block.

### Install the pgvector extension

1. Create a codeblock to install the `pgvector` extension to enable your Neon database as a vector store:

   ```python
   # Execute this query to install the pgvector extension
   cursor.execute("CREATE EXTENSION IF NOT EXISTS vector;")
   ```

2. Execute the code block.

### Create a table and add vector data

1. Add a code block to create a table and insert data:

   ```python
   create_table_sql = '''
   CREATE TABLE items (
   id BIGSERIAL PRIMARY KEY,
   embedding VECTOR(3)
   );
   '''

   # Insert data
   insert_data_sql = '''
   INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[7,8,9]');
   '''

   # Execute the SQL statements
   cursor.execute(create_table_sql)
   cursor.execute(insert_data_sql)

   # Commit the changes
   connection.commit()
   ```

2. Execute the code block.

### Query your data

1. Add a codeblock to perform a vector similarity search.

   ```python
   cursor.execute("SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 1;")
   all_data = cursor.fetchall()
   print(all_data)
   ```

2. Execute the code block.

### Next steps

For more information about using Neon with `pgvector`, see [The pgvector extension](https://neon.com/docs/extensions/pgvector).

--- [Document source](https://neon.com/docs/ai/ai-concepts.md) ---

> Summary: Embeddings are floating-point vectors that encode semantic meaning from unstructured data, enabling similarity search by computing vector distance in Postgres. Read this page to understand how embeddings work before building AI features such as semantic search, recommendations, or anomaly detection on Neon. Topics include distance metrics (Euclidean, Manhattan, cosine), generating embeddings with the Neon AI Gateway or OpenAI, storing vectors with the pgvector extension, and searching them at scale with Lakebase Search.

# AI Concepts

Learn how embeddings are used to build AI applications

Last updated: 2026-10-23

Embeddings are an essential component in building AI applications. This topic describes embeddings and how they are used, generated, and stored in Postgres.

## What are embeddings?

Embeddings transform unstructured data into a structured format that's easier to analyze and retrieve. They're vectors containing an array of floating-point numbers that represent the features or dimensions of your data. For example, a sentence like "The cow jumped over the moon" might be represented by an embedding that looks like this: [0.5, 0.3, 0.1].

Embeddings let you measure similarity between pieces of text. By calculating the distance between two embeddings, you can assess how related they are — the smaller the distance, the greater the similarity. This quality is particularly useful as it enables embeddings to capture the underlying meaning of the text.

Take the following three sentences, for example:

- Sentence 1: "The cow jumped over the moon."
- Sentence 2: "The bovine leaped above the celestial body."
- Sentence 3: "I enjoy eating pancakes."

You can determine the most similar sentences by following these steps:

1. Generate embeddings for each sentence. For illustrative purposes, assume these values represent actual embeddings:
   - Embedding for sentence 1 → [0.5, 0.3, 0.1]
   - Embedding for sentence 2 → [0.6, 0.29, 0.12]
   - Embedding for sentence 3 → [0.1, -0.2, 0.4]

2. Compute the distance between all pairs of embeddings (1 & 2, 2 & 3, and 1 & 3).

3. Identify the pair of embeddings with the shortest distance between them.

Applying this process, sentences 1 and 2 should come out as most similar (both involve jumping cattle).

## Vector similarity search

Transforming data into embeddings and computing similarities between items is called vector search or similarity search. This process has a wide range of applications, including:

- **Information retrieval:** By representing user queries as vectors, we can perform more accurate searches based on the meaning behind the queries, allowing us to retrieve more relevant information.
- **Natural language processing:** Embeddings capture the essence of the text, making them excellent tools for tasks such as text classification and sentiment analysis.
- **Recommendation systems:** Using vector similarity, we can recommend items similar to a given item, whether they be movies, products, books, or otherwise. This technique allows us to create more personalized and relevant recommendations.
- **Anomaly detection:** By determining the similarity between items within a dataset, we can identify outliers or anomalies (items that don't quite fit the pattern). This can be crucial in many fields, from cybersecurity to quality control.

### Distance metrics

Vector similarity search computes similarities (the distance) between data points. Calculating how far apart data points are helps us understand the relationship between them. Distance can be computed in different ways using different metrics. Some popular distance metrics include:

- Euclidean (L2): Often referred to as the "ordinary" distance you'd measure with a ruler.
- Manhattan (L1): Also known as "taxicab" or "city block" distance.
- Cosine: This calculates the cosine of the angle between two vectors.

Other distance metrics supported by the `pgvector` extension include [Hamming distance](https://en.wikipedia.org/wiki/Hamming_distance) and [Jaccard distance](https://en.wikipedia.org/wiki/Jaccard_index).

Different distance metrics can be more appropriate for different tasks, depending on the nature of the data and the specific relationships you're interested in. For instance, cosine similarity is often used in text analysis.

## Generating embeddings

A common approach to generating embeddings is to use an embeddings API, such as the [Neon AI Gateway](https://neon.com/docs/ai-gateway/embeddings) or [OpenAI's Embeddings API](https://platform.openai.com/docs/api-reference/embeddings). These APIs let you input a text string into an API endpoint, which then returns the corresponding embedding. The "cow jumped over the moon" is a simplistic example with 3 dimensions, but most embedding models generate vectors with many more.

The examples below send the same text to each API and get a vector back. Size your `vector` column to match the model you choose.

**Neon AI Gateway**

The [Neon AI Gateway](https://neon.com/docs/ai-gateway/embeddings) serves embedding models on an OpenAI-compatible endpoint, using the same Neon credential as the rest of your project instead of a separate provider key. Its `qwen3-embedding-0-6b`, `bge-large-en`, and `gte-large-en` models return 1024-dimensional vectors.

```bash
curl "$NEON_AI_GATEWAY_BASE_URL/v1/embeddings" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEON_AI_GATEWAY_TOKEN" \
  -d '{
    "input": "Your text string goes here",
    "model": "qwen3-embedding-0-6b",
    "encoding_format": "float"
  }'
```

The `model` field in the response reports the resolved, versioned model name that served the request:

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.00520731508731842,
        -0.01622946560382843,
        -0.011803247034549713,
        -0.06526501476764679,
        ... (1024 values total, omitted for spacing)
      ]
    }
  ],
  "model": "qwen3-embedding-0-6b-112025",
  "usage": {
    "prompt_tokens": 6,
    "total_tokens": 6
  }
}
```

**OpenAI**

OpenAI's `text-embedding-3-small` and `text-embedding-3-large` models generate 1536- and 3072-dimensional vectors by default. Generating an embedding requires an API key from [OpenAI](https://platform.openai.com/).

```bash
curl https://api.openai.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "input": "Your text string goes here",
    "model": "text-embedding-3-small",
    "encoding_format": "float"
  }'
```

If it works, you'll get a response like this:

```json
{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        -0.006929283495992422,
        -0.005336422007530928,
        ... (omitted for spacing)
        -4.547132266452536e-05,
        -0.024047505110502243
      ]
    }
  ],
  "model": "text-embedding-3-small",
  "usage": {
    "prompt_tokens": 5,
    "total_tokens": 5
  }
}
```

See [Embeddings](https://neon.com/docs/ai-gateway/embeddings) for the full gateway model list and options.

To learn more about OpenAI's embeddings, see [Embeddings](https://platform.openai.com/docs/guides/embeddings). Here, you'll find an example of obtaining embeddings from an [Amazon fine-food reviews](https://www.kaggle.com/datasets/snap/amazon-fine-food-reviews) dataset supplied as a CSV file. See [Obtaining the embeddings](https://platform.openai.com/docs/guides/embeddings/use-cases).

There are many embedding models you can use, such as those provided by Mistral AI, Cohere, Hugging Face, etc. AI tools like [LangChain](https://www.langchain.com/) provide interfaces and integrations for working with a variety of models. See [LangChain: Text embedding models](https://js.langchain.com/v0.1/docs/integrations/text_embedding/). You'll also find a [Neon Postgres guide](https://js.langchain.com/v0.1/docs/integrations/vectorstores/neon/) on the LangChain site and [Class NeonPostgres](https://v02.api.js.langchain.com/classes/langchain_community_vectorstores_neon.NeonPostgres.html), which provides an interface for working with a Lakebase Postgres database.

## Storing vector embeddings in Postgres

Neon supports the [pgvector](https://neon.com/docs/extensions/pgvector) Postgres extension, which enables the storage and retrieval of vector embeddings directly within your Postgres database. When building AI applications, installing this extension eliminates the need to extend your architecture to include a separate vector store. Installing the `pgvector` extension requires running the following `CREATE EXTENSION` statement from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any SQL client connected to your Lakebase Postgres database.

```sql
CREATE EXTENSION vector;
```

After installing `pgvector`, you can create a table to store your embeddings. For example:

```sql
CREATE TABLE items(id BIGSERIAL PRIMARY KEY, embedding VECTOR(1536));
```

To add embeddings to the table, you would insert the data as shown:

```sql
INSERT INTO items(embedding) VALUES ('[
    -0.006929283495992422,
    -0.005336422007530928,
    ...
    -4.547132266452536e-05,
    -0.024047505110502243
]');
```

For detailed information about using `pgvector`, refer to our guide: [The pgvector extension](https://neon.com/docs/extensions/pgvector).

## Searching vector embeddings at scale

`pgvector` gives you the `vector` type and similarity operators. To index and search embeddings at scale, Neon offers [Lakebase Search](https://neon.com/docs/ai/lakebase-search). Its [`lakebase_vector`](https://neon.com/docs/extensions/lakebase-vector) extension adds the `lakebase_ann` index for approximate nearest-neighbor search on your existing `pgvector` columns, with no schema or query changes, and scales to over a billion vectors on a single index. Pair it with `lakebase_text` for BM25 keyword search and hybrid results.

For an end-to-end walkthrough that generates embeddings with the AI Gateway, stores them in Postgres, and runs vector, keyword, and hybrid searches, see [Get started with Lakebase Search](https://neon.com/docs/ai/lakebase-search-get-started).

--- [Document source](https://neon.com/docs/ai/ai-database-versioning.md) ---

> Summary: Database versioning with Neon snapshots is a pattern for AI agents and codegen platforms that captures point-in-time database states and restores them without changing the connection string, by transferring compute endpoints to a new branch via the `finalize_restore: true` flag. Use this pattern when you need instant rollbacks to a previous version while keeping the active branch connection string stable, or when you need temporary preview branches from any saved version. Snapshot limits and storage pricing vary by plan.

# Database versioning with snapshots

How AI agents and codegen platforms implement database version control using snapshots and preview branches

Last updated: 2026-09-17

**Note:** Please give us [Feedback](https://console.neon.tech/app/projects?modal=feedback) from the Neon Console or by connecting with us on [Discord](https://neon.com/discord).

**Limits and pricing:** The Free plan includes 1 manual snapshot, and paid plans (including the [Agent plan](https://neon.com/use-cases/ai-agents)) include 100 manual snapshots. On paid plans, snapshots created by backup schedules do not count toward this limit. Snapshot storage is billed at $0.09/GB-month. If you need higher limits, please reach out to [Neon support](https://neon.com/docs/introduction/support).

## Overview

This guide describes how you can implement database versioning for AI agent and code generation platforms using Neon's snapshot APIs. With snapshots, you can create point-in-time database versions, perform instant rollbacks, and maintain stable database connection strings for your applications. See a working implementation in the [demonstration repository](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo).

> **Terminology note:** This guide uses "versions" to describe saved database states from the user's perspective, and "snapshots" when referring to Neon's technical implementation. You may also see these called "checkpoints" or "edits" in some AI agent contexts.

**Tip: Synopsis**

Use the project's root branch for production, whose database connection string stays the same when a snapshot restore is finalized. Create snapshots to save database versions. For rollbacks, restore snapshots with `finalize_restore: true` and `target_branch_id` set to your root branch ID, then poll operations until complete before connecting. For previews, use `finalize_restore: false` to create temporary branches with their own database connection strings.

## Why use snapshots for versioning

Standard database branching is great for development but less suitable for versioning. Each new branch gets a new database connection string and creates dependency chains that complicate deletion. This pattern solves both problems.

By restoring a Neon snapshot to your active branch with `finalize_restore: true`, you replace its data in-place while preserving the original, stable connection string. This makes the snapshot-restore pattern ideal for versioned environments where connection stability is needed.

## Quick start with the demo

The best way to understand this pattern is to see it in action:

1. **Clone the snapshots demo app**:
   - [https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo)
2. **Key files to examine**:
   - [lib/neon/create-snapshot.ts](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo/blob/main/lib/neon/create-snapshot.ts) - Snapshot creation implementation
   - [lib/neon/apply-snapshot.ts](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo/blob/main/lib/neon/apply-snapshot.ts) - Complete restore workflow with operations polling
   - [lib/neon/operations.ts](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo/blob/main/lib/neon/operations.ts) - Operation status polling logic
   - [app/[checkpointId]/page.tsx](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo/blob/main/app/\[checkpointId]/page.tsx) - UI integration showing versions and rollbacks
3. Run locally or use the [public demo](https://snapshots-as-checkpoints-demo.vercel.app/) to see version creation, rollbacks, and previews in action

> **Note:** The demo repository uses "checkpoint" terminology which maps to "version" in this guide.
> The demo implements a contacts application that evolves through agent prompts, demonstrating version creation and restoration at each stage:

**v0: empty app** → **v1: basic contacts** → **v2: add role/company** → **v3: add tags**

## The active branch pattern

Every agent project maps to one Neon project with a designated [root branch](https://neon.com/docs/reference/glossary#root-branch) that serves as the production database.

**Important:** Snapshots can only be created from root branches in Neon. A root branch is a branch with no parent (typically named `main` or `production`).

**The active branch:**

- Gets its data replaced during finalized rollbacks
- Maintains a consistent database connection string through Neon's restore mechanism; see [How restore works](https://neon.com/docs/ai/ai-database-versioning#how-restore-works) for details
- Must be a root branch for snapshot creation

**The snapshots:**

- Capture point-in-time database versions
- Store only incremental changes (cost-efficient)
- Can be restored to the active branch or to a temporary preview branch

![Active branch pattern diagram](https://neon.com/docs/guides/active_branch_pattern.jpg)

## Implementation

### Creating snapshots

Create a snapshot to capture the current database version using the [snapshot endpoint](https://neon.com/docs/reference/api/snapshots/create-snapshot):

```bash
POST /api/v2/projects/{project_id}/branches/{branch_id}/snapshot
```

> **Demo implementation:** See [lib/neon/create-snapshot.ts](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo/blob/main/lib/neon/create-snapshot.ts) for an example with error handling and operation polling.
> **Path parameters:**

- `project_id` (string, required): The Neon project ID
- `branch_id` (string, required): The active branch ID (must be a root branch)

**Query parameters:**

- `lsn` (string): Target Log Sequence Number. Cannot be used with `timestamp`
- `timestamp` (string): Target timestamp (RFC 3339). Cannot be used with `lsn`
- `name` (string): Name for the snapshot
- `expires_at` (string): Auto-deletion time (RFC 3339)

**Example:**

```bash
curl --request POST \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/snapshot?name=version-session-1&expires_at=2025-08-13T00:00:00Z' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

**Response:** The JSON body includes a `snapshot` object. It may include optional **`full_size`** and **`diff_size`** (bytes) for storage size; the same fields appear when you [list](https://neon.com/docs/reference/api/snapshots/list-snapshots) or [update](https://neon.com/docs/reference/api/snapshots/update-snapshot) snapshots. See [Snapshot size fields in API responses](https://neon.com/docs/guides/backup-restore#snapshot-size-fields-in-api-responses).

**When to create snapshots:**

- Start of each agent session
- Before database schema changes
- After successful operations
- User-initiated save points

**Tip:** Learn how our Developer Advocate approaches snapshot-based workflows in [Promoting Postgres changes safely to production](https://neon.com/blog/promoting-postgres-changes-safely-production).

### Rolling back to (restoring) a snapshot

Restore any snapshot to recover a previous version using the [restore endpoint](https://neon.com/docs/reference/api/snapshots/restore-snapshot):

```bash
POST /api/v2/projects/{project_id}/snapshots/{snapshot_id}/restore
```

> **Demo implementation:** See [lib/neon/apply-snapshot.ts](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo/blob/main/lib/neon/apply-snapshot.ts) for the complete restore workflow including operation polling and error handling.
> **Path parameters:**

- `project_id` (string, required): The Neon project ID
- `snapshot_id` (string, required): The snapshot ID being restored

**Body parameters:**

- `name` (string): A name for the newly restored branch. If omitted, a default name is generated
- `target_branch_id` (string): The ID of the branch to restore the snapshot into. If not specified, the branch from which the snapshot was originally created will be used. **Set this value to your root branch ID for rollbacks to preserve connection strings**
- `finalize_restore` (boolean): Set to `true` to finalize the restore operation immediately. This will complete the restore and move computes from the current branch to the new branch, which keeps the database connection string the same. Defaults to `false`. **Set to `true` when restoring to the active branch for rollbacks, `false` to create preview branches**

**Note: Connection warning**

Do not connect to the database until current API operations are complete. Any connection attempt before operations finish will either fail or connect to the old database state, not your restored version.

#### How restore works

Understanding the restore mechanism explains why the connection string remains stable:

1. **New branch creation**: When you restore with `finalize_restore: true`, Neon first creates a new branch from your snapshot. This new branch has a different, system-generated branch ID.

2. **Endpoint transfer**: Neon then transfers the compute endpoint (and its associated connection string) from your original active branch to this newly created branch.

3. **Settings migration**: All branch settings, including its name, are copied to the new active branch, making it appear identical to the old one. Only the branch ID is different.

4. **Branch orphan**: Your original branch becomes "orphaned." It is disconnected from the compute endpoint and renamed by adding an "(old)" suffix (for example, `main (old)`) to the branch name.

**Info: Branch ID changes after restore**

The connection string remains stable, but the branch ID changes with every `finalize_restore: true` operation. If you store the branch ID for use in subsequent API calls (for example, to create the next snapshot), you must retrieve and store the new branch ID after the restore operation completes.

#### Rollback workflow

Restore any snapshot to your active branch, preserving the connection string:

```json
{
  "target_branch_id": "br-active-branch-123456", // Your root branch ID
  "finalize_restore": true // Moves computes and preserves connection string
}
```

> **Important:** When restoring with `finalize_restore: true`, your previous active branch becomes orphaned and is renamed with `(old)` appended, such as `production (old)` or similar. This orphaned branch is no longer connected to any compute endpoint but preserves your pre-restore state. Delete it during cleanup to avoid unnecessary costs.
> After calling the restore API:

1. Extract the array of operation IDs from the API response.
2. For each operation ID, poll the operations endpoint until its status reaches a terminal state (finished, failed, cancelled, or skipped).
3. Do not attempt to connect to the database until all operations are complete. Connections made before completion will point to the old, pre-restore database state.
4. After verifying a successful restore, delete the orphaned branch (for example, `main (old)`) to avoid incurring storage costs.

> See the [poll operation status](https://neon.com/docs/manage/operations#poll-operation-status) documentation for related information.
> **Polling operations example:**

```javascript
// Poll operation status until complete
async function waitForOperation(projectId, operationId) {
  while (true) {
    const response = await fetch(
      `https://console.neon.tech/api/v2/projects/${projectId}/operations/${operationId}`,
      { headers: { Authorization: `Bearer ${NEON_API_KEY}` } }
    );
    const { status } = await response.json();

    // Terminal states - safe to proceed
    if (['finished', 'skipped', 'cancelled'].includes(status)) {
      return;
    }

    // Error state - handle appropriately
    if (status === 'failed') {
      throw new Error('Operation failed');
    }

    // Still running - wait and retry
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

// After restore API call
const restoreResponse = await restoreSnapshot(projectId, snapshotId);
const operationIds = restoreResponse.operations.map((op) => op.id);

// Wait for all operations to complete
for (const id of operationIds) {
  await waitForOperation(projectId, id);
}
// NOW safe to connect to the restored database
```

![Polling operations flow diagram](https://neon.com/docs/guides/polling_operations_flow.jpg)

**Potential restore-related problems:**

- **Connection to old state**: Ensure all operations completed
- **Target branch not found**: Verify branch exists
- **Operation timeout**: Retry with longer timeout
- **Accumulating orphaned branches**: Delete orphaned branches (for example, `production (old)`) after successful restore verification

#### Preview environments

Create a temporary branch to preview a version without affecting the active branch:

```json
{
  "name": "preview-version-123",
  "finalize_restore": false // Creates new branch for preview without moving computes
}
```

This creates a new branch with its own connection string for preview. The active branch remains unchanged. Preview branches should be deleted after use to avoid storage costs.

### Managing snapshots

#### List available snapshots

Get all snapshots with IDs, names, and timestamps using the [list snapshots endpoint](https://neon.com/docs/reference/api/snapshots/list-snapshots):

```bash
GET /api/v2/projects/{project_id}/snapshots
```

**Path parameters:**

- `project_id` (string, required): The Neon project ID

#### Delete snapshot

Remove a snapshot using the [delete endpoint](https://neon.com/docs/reference/api/snapshots/delete-snapshot):

```bash
DELETE /api/v2/projects/{project_id}/snapshots/{snapshot_id}
```

**Path parameters:**

- `project_id` (string, required): The Neon project ID
- `snapshot_id` (string, required): The snapshot ID

#### Update a snapshot

Rename a snapshot or change its expiration using the [update endpoint](https://neon.com/docs/reference/api/snapshots/update-snapshot):

```bash
PATCH /api/v2/projects/{project_id}/snapshots/{snapshot_id}
```

**Path parameters:**

- `project_id` (string, required): The Neon project ID
- `snapshot_id` (string, required): The snapshot ID

**Body fields (all optional):**

- `name` (string): A new name for the snapshot
- `expires_at` (string or `null`): The auto-deletion time in [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) format. Set a future timestamp to change the retention deadline, or send `null` to clear the expiration so the snapshot never expires. Omit the field to leave the current expiration unchanged. A past timestamp is rejected.

Rename a snapshot:

```json
{
  "snapshot": {
    "name": "important-milestone"
  }
}
```

Extend a snapshot's expiration:

```json
{
  "snapshot": {
    "expires_at": "2026-12-31T00:00:00Z"
  }
}
```

Remove the expiration so the snapshot never expires:

```json
{
  "snapshot": {
    "expires_at": null
  }
}
```

#### Cleanup strategy

Proper cleanup reduces costs and keeps your project manageable:

- Delete snapshots when no longer reachable by users
- Restoring from a snapshot doesn't lock that snapshot from deletion, unlike branches where creating child branches prevents deleting the parent
- Delete orphaned branches created during restores (named like `production (old)`)
- These orphaned branches accumulate with each restore and consume storage
- Reduces snapshot management fees while shared storage remains
- Set `expires_at` for automatic cleanup or delete manually as needed
- Consider removing snapshots after merging features or completing rollback testing

## Concepts and terminology

### Neon core concepts

- [Project](https://neon.com/docs/reference/glossary#project): Neon project that owns branches, computes, and snapshots, and more
- [Branch](https://neon.com/docs/reference/glossary#branch): An isolated database environment with its own data and schema that you can connect to and modify
- [Snapshot](https://neon.com/docs/reference/glossary#snapshot): An immutable, point-in-time backup of a branch's schema and data. Read-only until restored
- [Root branch](https://neon.com/docs/reference/glossary#root-branch): A branch with no parent (typically named `main` or `production`). The only type of branch from which snapshots can be created
- [Operations](https://neon.com/docs/manage/operations#operations-and-the-neon-api): Backend operations that return operation IDs you must poll to completion

### Pattern-specific terminology

- **Active branch**: The root branch that serves as your agent's production database (though technically replaced during restores). Connection string never changes even when data is replaced via restore. Preview branches may be created alongside for temporary exploration.
- **Version**: A saved database state captured as a snapshot, which may also be referred to a checkpoint or edit. Users create and restore versions through your application interface.
- **Orphaned branch**: Created when restoring with `finalize_restore: true`. The previous active branch becomes orphaned (disconnected from compute) and is renamed to `branch-name (old)`. Can be safely deleted after verifying the restore.
- **Preview branch**: Temporary branch created from a snapshot for safe exploration, to preview a version

## API quick reference

| Operation                                                                                         | Endpoint                                                             | Description                                  |
| ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------- |
| [Create snapshot](https://neon.com/docs/reference/api/snapshots/create-snapshot)                  | `POST /api/v2/projects/{project_id}/branches/{branch_id}/snapshot`   | Save current database state as a new version |
| [Restore snapshot](https://neon.com/docs/reference/api/snapshots/restore-snapshot)                | `POST /api/v2/projects/{project_id}/snapshots/{snapshot_id}/restore` | Restore database to a previous version       |
| [List snapshots](https://neon.com/docs/reference/api/snapshots/list-snapshots)                    | `GET /api/v2/projects/{project_id}/snapshots`                        | Get all available versions                   |
| [Delete snapshot](https://neon.com/docs/reference/api/snapshots/delete-snapshot)                  | `DELETE /api/v2/projects/{project_id}/snapshots/{snapshot_id}`       | Remove a saved version                       |
| [Update snapshot](https://neon.com/docs/reference/api/snapshots/update-snapshot)                  | `PATCH /api/v2/projects/{project_id}/snapshots/{snapshot_id}`        | Rename a version or change its expiration    |
| [Poll operation](https://neon.com/docs/reference/api/operations/get-project-operation)            | `GET /api/v2/projects/{project_id}/operations/{operation_id}`        | Check restore status                         |
| [List branches](https://neon.com/docs/reference/api/branches/list-project-branches) (for cleanup) | `GET /api/v2/projects/{project_id}/branches`                         | Find orphaned branches to clean up           |

## Implementation checklist

- [ ] Create one Neon project per agent project
- [ ] Designate the root branch (main/production) as the "active" branch
- [ ] Store the active branch connection string and branch ID
- [ ] Create snapshots at key points to save database versions
- [ ] For rollbacks: restore with `finalize_restore: true` and set `target_branch_id` to the root branch ID
- [ ] After a rollback, update your stored active branch ID
- [ ] For previews: restore with `finalize_restore: false` to create temporary branches
- [ ] Poll all operation IDs to terminal states before connecting
- [ ] Implement a cleanup strategy: set snapshot expiration dates and delete orphaned branches

## Best practices

- **Set `target_branch_id` for rollbacks**: When restoring to the active branch, always specify `target_branch_id` to prevent accidental restores.
- **Poll operations**: Wait for terminal states before connecting to the database.
- **Snapshot naming conventions**: Use descriptive conventions like `prod_snap_2025-01-17_pre-promotion`, `dev_snap_2025-01-17_candidate_v2`, `prod_snap_2025-01-17_after-promotion` to make automation easier.
- **Snapshot production before promotion**: Take a snapshot of your production branch before promoting changes to provide a rollback point if needed.
- **Differential retention**: Keep production snapshots longer for potential rollback, and development snapshots briefly (hours max) for promotion cycles only.
- **Implement connection retry logic**: Design application code to retry queries automatically, as restore operations briefly drop active connections (typically milliseconds, occasionally up to a second).
- **Keep backup branches briefly**: After restore, keep the automatically-created backup branch (for example, `prod (old)`) for sanity checks before deletion, or assign a [time to live](https://neon.com/docs/guides/branch-expiration) for automatic cleanup.
- **Cleanup strategy**: Set `expires_at` on temporary snapshots and preview branches. Delete orphaned branches (for example, `production (old)`) created during restores.
- **Version metadata**: Keep version metadata separate to preserve audit trail across restores.

## Frequently asked questions

### Why must I poll operations after restore?

With `finalize_restore: true`, Neon moves compute resources to the new state. Until operations complete, connections still point to the old compute.

### What happens to my active branch when I restore?

When restoring with `finalize_restore: true`, your current active branch becomes orphaned (disconnected from the compute endpoint) and is renamed with "(old)" appended. This orphaned branch preserves your pre-restore state temporarily, but you should delete it after verifying the restore to avoid storage costs.

### What if we need multiple preview environments?

Restore different snapshots to new branches using `finalize_restore: false`. Each restore creates a new branch with its own connection string.

### Why use snapshots instead of branches for versioning?

- **Snapshots**: Restoring a snapshot onto your active branch (`finalize_restore: true`) replaces the data but keeps the same database connection string. This is ideal for production rollbacks.
- **Branches**: Creating a new branch always generates a new connection string, which would require reconfiguring your application for every version change. Branches also create dependency chains that can complicate deletion.

## Summary

The active branch pattern with Neon snapshots provides a simple, reliable versioning solution for AI agent and codegen platforms. By keeping database connection strings stable through the restore mechanism and using snapshots to implement version control, you get stable connection strings for your main database, instant rollbacks to previous versions, and the flexibility to create preview branches when needed. The implementation is straightforward: create snapshots to save versions, restore with `finalize_restore: true` to the active branch for rollbacks, or with `finalize_restore: false` for preview branches. Always poll operations to completion before connecting. See the [demo repository](https://github.com/neondatabase-labs/snapshots-as-checkpoints-demo) for a complete example.

--- [Document source](https://neon.com/docs/ai/ai-google-colab.md) ---

> Summary: Google Colab integration with Neon lets you run Python notebooks in a browser-based Jupyter environment that connects to Lakebase Postgres and uses the pgvector extension to store and query vector embeddings. Use this guide when you want to prototype vector similarity search without local setup, using psycopg2 to connect, CREATE EXTENSION vector to enable pgvector, and the <-> distance operator to run nearest-neighbor queries. A pre-built Colab notebook is available for one-click setup.

# Google Colab

Use Google Colab with Neon for vector similarity search

Last updated: 2026-09-16

[Google Colab](https://colab.research.google.com/) is a hosted Jupyter Notebook service that requires no setup to use and provides free access to computing resources, including GPUs and TPUs.
You can use Google Colab to run python code through the browser.

This guide shows how to create a notebook in Colab, connect to a Neon database, install the `pgvector` extension to enable Neon as a vector store, and run a vector search query.

## Prerequisites

To perform the steps in this guide, you require a Neon database for storing vectors. You can use the ready-to-use `neondb` database or create your own. See [Create a database](https://neon.com/docs/manage/databases#create-a-database) for instructions.

## Retrieve your database connection string

Click **Connect** in the Console nav to open the **Connect to your branch** modal, and select a branch, a user, and the database you want to connect to. A connection string is constructed for you.

![Connection modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

## Create a notebook

In your browser, navigate to [Google Colab](https://colab.research.google.com/), and click **New notebook**.

![Google Colab](https://neon.com/docs/ai/google_colab.png)

Alternatively, you can open a predefined Google Colab notebook for this guide by clicking the **Open in Colab** button below.

[https://colab.research.google.com/github/neondatabase/neon-google-colab-notebooks/blob/main/neon_pgvector_quickstart.ipynb](https://colab.research.google.com/github/neondatabase/neon-google-colab-notebooks/blob/main/neon_pgvector_quickstart.ipynb)

## Connect to your database

1. In your Colab notebook, create a code block to define your database connection and create a cursor object. Replace `postgresql://[user]:[password]@[neon_hostname]/[dbname]` with the database connection string you retrieved in the previous step.

   ```python
   import os
   import psycopg2

   # Provide your Neon connection string
   connection_string = "postgresql://[user]:[password]@[neon_hostname]/[dbname]"

   # Connect using the connection string
   connection = psycopg2.connect(connection_string)

   # Create a new cursor object
   cursor = connection.cursor()
   ```

2. Execute the code block (**Ctrl** + **Enter**).

3. Add a code block for testing the database connection.

   ```python
   # Execute this query to test the database connection
   cursor.execute("SELECT 1;")
   result = cursor.fetchone()

   # Check the query result
   if result == (1,):
       print("Your database connection was successful!")
   else:
       print("Your connection failed.")
   ```

4. Execute the code block (**Ctrl** + **Enter**).

## Install the pgvector extension

1. Create a codeblock to install the `pgvector` extension to enable your Neon database as a vector store:

   ```python
   # Execute this query to install the pgvector extension
   cursor.execute("CREATE EXTENSION IF NOT EXISTS vector;")
   ```

2. Execute the code block (**Ctrl** + **Enter**).

## Create a table and add vector data

1. Add a code block to create a table and insert data:

   ```python
   create_table_sql = '''
   CREATE TABLE items (
   id BIGSERIAL PRIMARY KEY,
   embedding VECTOR(3)
   );
   '''

   # Insert data
   insert_data_sql = '''
   INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]'), ('[7,8,9]');
   '''

   # Execute the SQL statements
   cursor.execute(create_table_sql)
   cursor.execute(insert_data_sql)

   # Commit the changes
   connection.commit()
   ```

2. Execute the code block (**Ctrl** + **Enter**).

## Query your data

1. Add a codeblock to perform a vector similarity search.

   ```python
   cursor.execute("SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 3;")
   all_data = cursor.fetchall()
   print(all_data)
   ```

2. Execute the code block (**Ctrl** + **Enter**).

## Next steps

For more information about using Neon with `pgvector`, see [The pgvector extension](https://neon.com/docs/extensions/pgvector).

--- [Document source](https://neon.com/docs/ai/ai-intro.md) ---

> Summary: Neon AI Starter Kit is the central hub for building AI and vector search applications on Lakebase Postgres on Neon, collecting concepts, framework integrations, and deployable starter apps in one place. Use this page when starting an AI project on Neon and need to orient across pgvector setup, RAG pipelines, semantic search, or scaling strategies before diving into a specific guide. Supported frameworks include LangChain, LlamaIndex, Semantic Kernel, and Inngest; app types covered include RAG chatbots, hybrid search, reverse image search, and text-to-SQL.

# AI Starter Kit

Resources for building AI applications with Lakebase Postgres on Neon

Last updated: 2026-08-04

Build AI applications and agents on Neon. This guide collects resources for AI workloads: core concepts, starter applications, framework integrations, and deployment guides. Use them to build applications like RAG chatbots, semantic search engines, or custom AI tools.

> **Start building AI apps with Neon**
>
> Sign up for Lakebase Postgres on Neon and jumpstart your AI application with our starter apps and resources.
>
> [Sign Up](https://console.neon.tech/signup)

## Getting started

Learn the fundamentals of building AI applications with Neon:

- [AI concepts](https://neon.com/docs/ai/ai-concepts): Learn the fundamentals of embeddings and vector search for AI applications
- [pgvector extension](https://neon.com/docs/extensions/pgvector): Get started with pgvector for storing and querying vector embeddings

## AI frameworks and integrations

Build AI applications faster with these popular frameworks, tools, and services:

- [LangChain](https://neon.com/docs/ai/langchain): Create AI applications using LangChain with OpenAI and Neon
- [LlamaIndex](https://neon.com/docs/ai/llamaindex): Build RAG applications using LlamaIndex with OpenAI and Neon
- [Semantic Kernel](https://neon.com/docs/ai/semantic-kernel): Develop AI applications using Semantic Kernel with Azure OpenAI
- [Inngest](https://neon.com/docs/ai/inngest): Build reliable AI workflows with Inngest and Neon
- [app.build](https://neon.com/docs/ai/ai-app-build): Generate and deploy web applications using the open-source app.build agent

## Starter applications

Hackable, fully-featured, pre-built starter apps to get you up and running:

- [AI chatbot (OpenAI + LllamIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/chatbot-nextjs): A Next.js AI chatbot starter app built with OpenAI and LlamaIndex
- [AI chatbot (OpenAI + LangChain)](https://github.com/neondatabase/examples/tree/main/ai/langchain/chatbot-nextjs): A Next.js AI chatbot starter app built with OpenAI and LangChain
- [RAG chatbot (OpenAI + LlamaIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/rag-nextjs): A Next.js RAG chatbot starter app built with OpenAI and LlamaIndex
- [RAG chatbot (OpenAI + LangChain)](https://github.com/neondatabase/examples/tree/main/ai/langchain/rag-nextjs): A Next.js RAG chatbot starter app built with OpenAI and LangChain
- [Semantic search (OpenAI + LlamaIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/semantic-search-nextjs): A Next.js Semantic Search chatbot starter app built with OpenAI and LlamaIndex
- [Semantic search (OpenAI + LangChain)](https://github.com/neondatabase/examples/tree/main/ai/langchain/semantic-search-nextjs): A Next.js Semantic Search chatbot starter app built with OpenAI and LangChain
- [Hybrid search (OpenAI)](https://github.com/neondatabase/examples/tree/main/ai/hybrid-search-nextjs): A Next.js Hybrid Search starter app built with OpenAI
- [Reverse image search (OpenAI + LlamaIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/reverse-image-search-nextjs): A Next.js Reverse Image Search Engine starter app built with OpenAI and LlamaIndex
- [Chat with PDF (OpenAI + LlamaIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/chat-with-pdf-nextjs): A Next.js Chat with PDF chatbot starter app built with OpenAI and LlamaIndex
- [Chat with PDF (OpenAI + LangChain)](https://github.com/neondatabase/examples/tree/main/ai/langchain/chat-with-pdf-nextjs): A Next.js Chat with PDF chatbot starter app built with OpenAI and LangChain

## Scale your AI application

- [Scale with Neon](https://neon.com/docs/ai/ai-scale-with-neon): Learn how to scale your AI application with Autoscaling and Read Replicas
- [Optimize vector search](https://neon.com/docs/ai/ai-vector-search-optimization): Best practices for optimizing vector search performance

## Featured examples

Real-world AI applications built with Neon that you can reference as code examples or inspiration.

**Tip: Built something cool?**

Share your AI app on our [#showcase](https://discord.gg/neon) channel on Discord.

- [AI vector database per tenant](https://github.com/neondatabase/ai-vector-db-per-tenant): Deploy an AI vector database per-tenant architecture with Neon
- [Guide: Build a RAG chatbot](https://neon.com/guides/chatbot-astro-postgres-llamaindex): Build a RAG chatbot in an Astro application with LlamaIndex and Postgres
- [Guide: Build a Reverse Image Search Engine](https://neon.com/guides/llamaindex-postgres-search-images): Using LlamaIndex with Postgres to Build your own Reverse Image Search Engine
- [Ask Neon Chatbot](https://github.com/neondatabase/ask-neon): An Ask Neon AI-powered chatbot built with pgvector
- [Vercel Postgres pgvector Starter](https://vercel.com/templates/next.js/postgres-pgvector): Enable vector similarity search with Vercel Postgres powered by Neon
- [YCombinator Semantic Search App](https://github.com/neondatabase/yc-idea-matcher): YCombinator semantic search application
- [Web-based AI SQL Playground](https://github.com/neondatabase/postgres-ai-playground): An AI-enabled SQL playground application for natural language queries
- [Jupyter Notebook for vector search with Neon](https://github.com/neondatabase/neon-vector-search-openai-notebooks): Jupyter Notebook for vector search with Neon, pgvector, and OpenAI
- [Image search with Neon and Vertex AI](https://github.com/ItzCrazyKns/Neon-Image-Search): Community: An image search app built with Neon and Vertex AI
- [Text-to-SQL conversion with Mistral + LangChain](https://github.com/mistralai/cookbook/blob/main/third_party/Neon/neon_text_to_sql.ipynb): A Text-to-SQL conversion app built with Mistral AI, Neon, and LangChain
- [Postgres GPT Expert](https://neon.com/blog/openais-gpt-store-is-live-create-and-publish-a-custom-postgres-gpt-expert): Blog + repo: Create and publish a custom Postgres GPT Expert using OpenAI's GPT

## Vector search tools and notebooks

Optimize your vector search implementation and experiment with different approaches:

- [Vector search optimization](https://neon.com/docs/ai/ai-vector-search-optimization): Best practices for optimizing vector search performance
- [Vector search notebooks](https://github.com/neondatabase/neon-vector-search-openai-notebooks): Interactive notebooks for vector search with OpenAI
- [Google Colab guide](https://neon.com/docs/ai/ai-google-colab): Use Neon with Google Colab for ML experiments
- [Azure Data Studio Notebooks](https://neon.com/docs/ai/ai-azure-notebooks): A cloud-based Jupyter notebook service integrated with Azure Data Studio

--- [Document source](https://neon.com/docs/ai/ai-scale-with-neon.md) ---

> Summary: Scaling options for AI applications that use pgvector on Lakebase Postgres, covering vertical scaling from 0.25 CU (1 GB RAM) to 56 CU (224 GB RAM) with autoscaling up to 16 CU, and horizontal scaling via read replicas for offloading vector similarity search workloads at no extra storage cost.

# Scale your AI application with Neon

Scale your AI application with Neon's Autoscaling and Read Replica features

Last updated: 2026-10-01

You can scale your AI application built on Postgres with `pgvector` in the same way you would any Postgres app: Vertically with added CPU, RAM, and storage, or horizontally with read replicas.

In Neon, scaling vertically is a matter of selecting the desired compute size. Neon supports compute sizes ranging from .25 CU (1 GB RAM) up to 56 CU (224 GB RAM). Autoscaling is supported up to 16 CU. Larger computes are fixed size computes (no autoscaling). The `maintenance_work_mem` values shown below are approximate.

| Compute Units (CU) | RAM    | maintenance\_work\_mem |
| :----------------- | :----- | :--------------------- |
| 0.25               | 1 GB   | 64 MB                  |
| 0.50               | 2 GB   | 64 MB                  |
| 1                  | 4 GB   | 67 MB                  |
| 2                  | 8 GB   | 134 MB                 |
| 3                  | 12 GB  | 201 MB                 |
| 4                  | 16 GB  | 268 MB                 |
| 5                  | 20 GB  | 335 MB                 |
| 6                  | 24 GB  | 402 MB                 |
| 7                  | 28 GB  | 470 MB                 |
| 8                  | 32 GB  | 537 MB                 |
| 9                  | 36 GB  | 604 MB                 |
| 10                 | 40 GB  | 671 MB                 |
| 11                 | 44 GB  | 738 MB                 |
| 12                 | 48 GB  | 805 MB                 |
| 13                 | 52 GB  | 872 MB                 |
| 14                 | 56 GB  | 939 MB                 |
| 15                 | 60 GB  | 1007 MB                |
| 16                 | 64 GB  | 1074 MB                |
| 18                 | 72 GB  | 1208 MB                |
| 20                 | 80 GB  | 1342 MB                |
| 22                 | 88 GB  | 1476 MB                |
| 24                 | 96 GB  | 1610 MB                |
| 26                 | 104 GB | 1744 MB                |
| 28                 | 112 GB | 1878 MB                |
| 30                 | 120 GB | 2012 MB                |
| 32                 | 128 GB | 2146 MB                |
| 34                 | 136 GB | 2280 MB                |
| 36                 | 144 GB | 2414 MB                |
| 38                 | 152 GB | 2548 MB                |
| 40                 | 160 GB | 2682 MB                |
| 42                 | 168 GB | 2816 MB                |
| 44                 | 176 GB | 2950 MB                |
| 46                 | 184 GB | 3084 MB                |
| 48                 | 192 GB | 3218 MB                |
| 50                 | 200 GB | 3352 MB                |
| 52                 | 208 GB | 3486 MB                |
| 54                 | 216 GB | 3620 MB                |
| 56                 | 224 GB | 3754 MB                |

See [Edit a compute](https://neon.com/docs/manage/computes#edit-a-compute) to configure your compute size. Available compute sizes differ according to your Neon plan.

To optimize `pgvector` index build time, you can increase the `maintenance_work_mem` setting for the current session beyond the preconfigured default shown in the table above with a command similar to this:

```sql
SET maintenance_work_mem='10 GB';
```

The recommended `maintenance_work_mem` setting is your working set size (the size of your tuples for vector index creation). However, your `maintenance_work_mem` setting should not exceed 50 to 60 percent of your compute's available RAM (see the table above). For example, the `maintenance_work_mem='10 GB'` setting shown above has been successfully tested on a 7 CU compute, which has 28 GB of RAM, as 10 GB is less than 50% of the RAM available for that compute size.

## Autoscaling

You can also enable Neon's autoscaling feature for automatic scaling of compute resources. Neon's _Autoscaling_ feature automatically scales up compute on demand in response to application workload and down to zero on inactivity.

For example, if your AI application experiences heavy load during certain hours of the day or at different times throughout the week, month, or calendar year, Neon automatically scales compute resources without manual intervention according to the compute size boundaries that you configure. This enables you to handle peak demand while avoiding consuming compute resources during periods of low activity.

Enabling autoscaling is also recommended for initial data loads and memory-intensive index builds to ensure sufficient compute resources for this phase of your AI application setup.

To learn more about Neon's autoscaling feature and how to enable it, refer to our [Autoscaling guide](https://neon.com/docs/introduction/autoscaling).

## Storage

On the Free plan, you get 1 GB of Postgres storage per project. Storage on paid plans is usage based. See [Neon plans](https://neon.com/docs/introduction/plans) for details.

## Read replicas

Neon supports read replicas, which are independent read-only computes designed to perform read operations on the same data as your primary read-write compute. Read replicas do not replicate data across database instances. Instead, read requests are directed to the same data source. This architecture enables read replicas to be created instantly, enabling you to scale out CPU and RAM, but because data is read from a single source, there are no additional storage costs.

Since vector similarity search is a read-only workload, you can use read replicas to offload reads from your primary compute to a dedicated compute. After you create a read replica, swap your Neon connection string for the read replica connection string.

Neon's read replicas support the same compute sizes outlined above. Read replicas also support autoscaling.

To learn more about the Neon read replicas, see [read replicas](https://neon.com/docs/introduction/read-replicas) and refer to our [Working with Neon read replicas](https://neon.com/docs/guides/read-replica-guide) guide.

--- [Document source](https://neon.com/docs/ai/ai-vector-search-optimization.md) ---

> Summary: pgvector similarity search optimization in Postgres covers profiling with EXPLAIN ANALYZE, choosing between sequential scans and approximate nearest neighbor indexes (HNSW or IVFFlat), and tuning build and query-time parameters to balance speed and recall. Use this page when query latency is too high and you need to select an index type, set build parameters, or tune query-time settings like ef_search or probes. HNSW delivers better query speed than IVFFlat at the cost of higher build time and memory; IVFFlat requires existing data before the index can be created.

# Optimize pgvector search

Fine-tune parameters for efficient and accurate similarity searches in Postgres

Last updated: 2026-06-05

This guide covers how to use `pgvector` for vector similarity searches. We'll address the following key questions:

1. How to profile your vector search queries, when using `pgvector`?
2. When to use indexes and tradeoffs between the available options?
3. Which parameters to tune for best performance?

We'll examine sequential scans, HNSW indexing, and IVFFlat indexing, providing benchmarks and practical recommendations for various dataset sizes. This will help you optimize `pgvector` queries in your Neon database for both accuracy and speed.

Without indexes, `pgvector` performs a sequential scan on the database and calculates the distance between the query vector and all vectors in the table. This approach does an exact search and guarantees 100% **recall**, but it can be costly with large datasets.

**Note: what is recall?**

Recall is a metric used to evaluate the performance of a search algorithm. It measures how effectively the search retrieves relevant items from a dataset. It is defined as the ratio of the number of relevant items retrieved by the search to the total number of relevant items in the dataset.

The query below uses `EXPLAIN ANALYZE` to generate an execution plan and display the performance of the similarity search query.

```sql
EXPLAIN ANALYZE SELECT * FROM items ORDER BY embedding <-> '[0.011699999682605267,..., 0.008700000122189522]' LIMIT 100;
```

This is what the query plan looks like:

```sql
Limit  (cost=748.19..748.44 rows=100 width=173) (actual time=39.475..39.487 rows=100 loops=1)
  ->  Sort  (cost=748.19..773.19 rows=10000 width=173) (actual time=39.473..39.480 rows=100 loops=1)
        Sort Key: ((vec <-> '[0.0117,..., 0.0866]'::vector))
        Sort Method: top-N heapsort  Memory: 70kB
        ->  Seq Scan on items  (cost=0.00..366.00 rows=10000 width=173) (actual time=0.087..37.571 rows=10000 loops=1)
Planning Time: 0.213 ms
Execution Time: 39.527 ms
```

You can see in the plan that the query performs a sequential scan (`Seq Scan`) on the `items` table, which means that the query compares the query vector against all vectors in the `items` table. In other words, the query does not use an index.

To understand how queries perform at scale, we tested sequential scan vector searches with `pgvector` on subsets of the [GIST-960 dataset](http://corpus-texmex.irisa.fr/) with 10k, 50k, 100k, 500k, and 1M rows using a Neon database instance with 4 CU (16 GB of RAM).

The sequential scan search performed reasonably well for tables with 10k rows (~36ms). However, sequential scans start to become costly at 50k rows.

So, when should you use sequential scans rather than defining an index?

- When your dataset is small and you do not intend to scale it.
- When you need 100% recall (accuracy). Adding indexes trades recall for performance.
- When you do not expect a high volume of queries per second, which would require indexes for performance.

Otherwise, consider adding an index for better performance.

## Indexing with HNSW

HNSW is a graph-based approach to indexing multi-dimensional data. It constructs a multi-layered graph, where each layer is a subset of the previous one. During a vector similarity search, the algorithm navigates through the graph from the top layer to the bottom to quickly find the nearest neighbor. An HNSW graph is known for its superior performance in terms of speed and accuracy.

**Note:** An HNSW index performs better than IVFFlat (in terms of speed-recall tradeoff) and can be created without any data in the table since there isn't a training step like there is for an IVFFlat index. However, HNSW indexes have slower build times and use more memory.

![HNSW graph](https://neon.com/docs/extensions/hnsw_graph.png)

The search process begins at the topmost layer of the HNSW graph. From the starting node, the algorithm navigates to the nearest neighbor in the same layer. The algorithm repeats this step until it can no longer find neighbors more similar to the query vector.

Using the found node as an entry point, the algorithm moves down to the next layer in the graph and repeats the process of navigating to the nearest neighbor. The process of navigating to the nearest neighbor and moving down a layer is repeated until the algorithm reaches the bottom layer.

In the bottom layer, the algorithm continues navigating to the nearest neighbor until it cannot find any nodes that are more similar to the query vector. The current node is then returned as the most similar node to the query vector.

The key idea behind HNSW is that by starting the search at the top layer and moving down through each layer, the algorithm can quickly navigate to the area of the graph that contains the node that is most similar to the query vector. This makes the search process much faster than if it had to search through every node in the graph.

### Tuning the HNSW algorithm

The following options allow you to tune the HNSW algorithm when creating an index:

- `m`: Defines the maximum number of links created for each node during graph construction. A higher value increases accuracy (recall), but it also increases the size of the index in memory and index construction time. Higher values are typically used with high-dimensionality datasets or when a high degree of accuracy is required. The default value is 16. Acceptable values for m typically fall between 2 and 100. For many applications, beginning with a range of 12 to 48 is advisable.
- `ef_construction`: Defines the size of the list for the nearest neighbors. This value influences the tradeoff between index quality and construction speed. A high `ef_construction` value creates a higher quality graph, enabling more accurate search results but also means that index construction takes longer. The value should be set to at least twice the value of `m`. The default setting is 64. There comes a point where increasing `ef_construction` no longer improves index quality. To evaluate search accuracy, you can start by setting `ef_construction` equal to `ef_search` and incrementally increasing `ef_construction` to achieve the desired result. If accuracy is lower than 0.9, there may be opportunity for improvement by increasing `ef_construction`.

This example demonstrates how to set the parameters:

```sql
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64);
```

HNSW search tuning:

- `ef_search`: Defines the size of the dynamic candidate list for search. The default value is 40. This value influences the trade-off between query accuracy (recall) and speed. A higher value increases accuracy at the cost of speed. The value should be equal to or larger than `k`, which is the number of nearest neighbors you want your search to return (defined by the `LIMIT` clause in your `SELECT` query).

To configure this value, do so using a `SET` statement before executing queries:

```sql
SET hnsw.ef_search = 100;
```

You can also use `SET LOCAL` inside a transaction to set it for a single query:

```sql
BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;
```

In summary:

- To prioritize search speed over accuracy, use lower values for `m` and `ef_search`.
- Conversely, to prioritize accuracy over search speed, use a higher value for `m` and `ef_search`.
- Using a higher value for `ef_construction` yields more accurate search results at the cost of index build time.

## Indexing with IVFFlat

IVFFlat indexes partition the dataset into clusters ("lists") to optimize for vector search.

You can create an IVFFlat index using the query below:

```sql
CREATE INDEX items_embedding_cosine_idx ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 1000);
```

IVFFlat in `pgvector` has two parameters:

1. `lists`
   - This parameter specifies the number of [k-means clusters](https://en.wikipedia.org/wiki/K-means_clustering) (or "lists") to divide the dataset into
   - Each cluster contains a subset of the data, and each data point belongs to the closest cluster centroid.

2. `probes`
   - This parameter determines the number of lists to explore during the search for the nearest neighbors.
   - By probing multiple lists, the search algorithm can find the closest points more accurately, balancing between speed and accuracy.

By default, the `probes` parameter is set to `1`. This means that during a search, only one cluster is explored. This approach is fine if your query vector is close to the centroid. However, if the query vector is located near the edge of the cluster, closer neighbors in adjacent clusters will not be included in the search, which can result in a lower recall.

You must specify the number of probes in the same connection as the search query:

```sql
SET ivfflat.probes = 100;
SET enable_seqscan=off;
SELECT * FROM items ORDER BY embedding <-> '[0.011699999682605267,..., 0.008700000122189522]' LIMIT 100;
```

**Note:** In the example above, `enable_seqscan=off` forces Postgres to use index scans.

The output of this query appears as follows:

```sql
Limit  (cost=1971.50..1982.39 rows=100 width=173) (actual time=4.500..5.738 rows=100 loops=1)
  ->  Index Scan using items_embedding_idx on vectors  (cost=1971.50..3060.50 rows=10000 width=173) (actual time=4.499..5.726 rows=100 loops=1)
        Order By: (vec <-> '[0.0117, ... ,0.0866]'::vector)
Planning Time: 0.295 ms
Execution Time: 5.867 ms
```

We've experimented with `lists` equal to 1000, 2000, and 4000, and `probes` equal to 1, 2, 10, 50, 100, 200.

Although there is a substantial gain in recall for increasing the number of `probes`, you will reach a point of diminishing returns when recall plateaus and execution time increases.

Try different values for `probes` and `lists` to find the right balance for your dataset. Good places to start:

- Using a `lists` size equal to rows / 1000 for tables with up to 1 million rows, and `sqrt(rows)` for larger datasets.
- Start with a `probes` value equal to lists / 10 for tables up to 1 million rows, and `sqrt(lists)` for larger datasets.

## Conclusion

The sequential scan approach of `pgvector` performs well for small datasets but can be costly for larger ones. Use sequential scans if you require 100% accuracy, but expect performance issues with higher volumes of queries per second.

You can optimize searches using HNSW or IVFFlat indexes for approximate nearest neighbor (ANN) search, but HNSW indexes have better query performance than IVFFlat with build time and memory usage tradeoffs.

Be sure to test different index tuning parameter settings to find the right balance between speed and accuracy for your specific use case and dataset.

--- [Document source](https://neon.com/docs/ai/connect-mcp-clients-to-neon.md) ---

> Summary: Set up Neon in AI agents and MCP clients that don't have their own setup page, including Antigravity, Cline, Devin Desktop, fx, Gamut, Gemini CLI, Grok Build, Jules, Kimi Code, Kiro, Pi, and Zed. Install agent skills and the hosted Neon MCP Server (https://mcp.neon.tech/mcp) with the Neon CLI or add-mcp, or configure the server by hand with OAuth or an API key.

# Set up other agents and MCP clients

Install Neon's agent skills and the Neon MCP Server in Devin Desktop, Cline, Zed, Gemini CLI, Kiro, Kimi Code, and other agents

Last updated: 2026-11-05

This page covers agents and MCP clients that don't have their own setup page. If you use Claude Code, Cursor, Codex, VS Code, Claude.ai, ChatGPT, or Grok Bot, start from [Set up your AI agent](https://neon.com/docs/ai/agent-setup) instead.

**Important: Security**

The Neon MCP Server is intended for **development and testing only**. Always review LLM-requested actions before execution. See [MCP security guidance](https://neon.com/docs/ai/neon-mcp-server#mcp-security-guidance).

## Install for any supported agent

Most agents get Neon's [agent skills](https://neon.com/docs/ai/agent-skills) and the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server) as two installs. From your project directory, run:

```bash
npx neon@latest skills --agent <agent>
npx neon@latest mcp --agent <agent>
```

Replace `<agent>` with your agent's ID; `neon skills --help` and `neon mcp --help` list the IDs each command accepts. [`neon mcp`](https://neon.com/docs/cli/mcp) mints a Neon API key by default; pass `--oauth` to sign in on first use instead.

To write only the MCP config, use [add-mcp](https://github.com/neondatabase/add-mcp), the tool the Neon CLI uses to patch each agent's MCP config:

```bash
npx add-mcp https://mcp.neon.tech/mcp -a <agent>
```

Add `-g` for user-level config instead of project-level, then restart your agent. On first use, an OAuth window opens to authorize; for API key auth, add `--header "Authorization: Bearer $NEON_API_KEY"`.

## Supported agents (add-mcp)

Run `npx add-mcp list-agents` for the live list from your installed version. As of [add-mcp](https://github.com/neondatabase/add-mcp) 2.6.0, `--agent` values include:

| Assistant                 | `--agent`            | Setup                                                                                                       |
| :------------------------ | :------------------- | :---------------------------------------------------------------------------------------------------------- |
| Antigravity               | `antigravity`        | [Antigravity](https://neon.com/docs/ai/connect-mcp-clients-to-neon#antigravity)                             |
| Claude Code               | `claude-code`        | [Claude Code page](https://neon.com/docs/ai/agent-setup/claude-code)                                        |
| Claude Desktop            | `claude-desktop`     | [Claude.ai and Claude Desktop page](https://neon.com/docs/ai/agent-setup/claude-ai)                         |
| Cline (VS Code extension) | `cline`              | [Cline](https://neon.com/docs/ai/connect-mcp-clients-to-neon#cline-vs-code-extension)                       |
| Cline CLI                 | `cline-cli`          | [Cline](https://neon.com/docs/ai/connect-mcp-clients-to-neon#cline-vs-code-extension)                       |
| Codex                     | `codex`              | [Codex page](https://neon.com/docs/ai/agent-setup/codex)                                                    |
| Cursor                    | `cursor`             | [Cursor page](https://neon.com/docs/ai/agent-setup/cursor)                                                  |
| Factory Droid             | `factory-droid`      | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| fx                        | `fx`                 | [fx](https://neon.com/docs/ai/connect-mcp-clients-to-neon#fx)                                               |
| Gemini CLI                | `gemini-cli`         | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| GitHub Copilot CLI        | `github-copilot-cli` | [VS Code page](https://neon.com/docs/ai/agent-setup/vscode)                                                 |
| Goose                     | `goose`              | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| Grok Build                | `grok-build`         | [Grok Build](https://neon.com/docs/ai/connect-mcp-clients-to-neon#grok-build)                               |
| Hermes Agent              | `hermes`             | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| Junie                     | `junie`              | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| Kilo Code                 | `kilo-code`          | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| Kimi Code                 | `kimi-code`          | [Kimi Code](https://neon.com/docs/ai/connect-mcp-clients-to-neon#kimi-code)                                 |
| Kiro CLI                  | `kiro-cli`           | [Kiro](https://neon.com/docs/ai/connect-mcp-clients-to-neon#kiro)                                           |
| Mastra Code               | `mastracode`         | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| MCPorter                  | `mcporter`           | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| OpenCode                  | `opencode`           | [Any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent) |
| Pi                        | `pi`                 | [Pi](https://neon.com/docs/ai/connect-mcp-clients-to-neon#pi)                                               |
| VS Code                   | `vscode`             | [VS Code page](https://neon.com/docs/ai/agent-setup/vscode)                                                 |
| Windsurf                  | `windsurf`           | [Devin Desktop](https://neon.com/docs/ai/connect-mcp-clients-to-neon#devin-desktop)                         |
| Zed                       | `zed`                | [Zed](https://neon.com/docs/ai/connect-mcp-clients-to-neon#zed)                                             |

**Aliases:** `cline-vscode` → `cline`, `droid`/`factory` → `factory-droid`, `gemini` → `gemini-cli`, `github-copilot` → `vscode`, `grok` → `grok-build`, `hermes-agent` → `hermes`, `kilo`/`kilocode` → `kilo-code`, `kimi` → `kimi-code`, `kiro` → `kiro-cli`, `mastra` → `mastracode`, `pi-agent` → `pi`, `codeium`/`cascade` → `windsurf`. Config paths differ by agent and by project vs global (`-g`); see the [add-mcp README](https://github.com/neondatabase/add-mcp#supported-agents).

## Agents with their own page

### ChatGPT

See [Set up Neon in ChatGPT](https://neon.com/docs/ai/agent-setup/chatgpt).

### Claude Code

See [Set up Neon in Claude Code](https://neon.com/docs/ai/agent-setup/claude-code).

### Claude Desktop

See [Set up Neon in Claude.ai and Claude Desktop](https://neon.com/docs/ai/agent-setup/claude-ai).

### Codex

See [Set up Neon in Codex](https://neon.com/docs/ai/agent-setup/codex).

### Cursor

See [Set up Neon in Cursor](https://neon.com/docs/ai/agent-setup/cursor).

### VS Code (with GitHub Copilot)

See [Set up Neon in VS Code and GitHub Copilot](https://neon.com/docs/ai/agent-setup/vscode).

## Antigravity

Antigravity can install Neon's [agent-skills repository](https://github.com/neondatabase/agent-skills) as a plugin, which includes the skills and the Neon MCP Server:

```bash
agy plugin install https://github.com/neondatabase/agent-skills
```

Confirm that Antigravity found the plugin, its skills, and the MCP Server with `agy plugin list`. To authenticate, run `/mcp` in Antigravity, select the Neon MCP Server, and complete the OAuth flow.

To install with the Neon CLI instead, use `--agent antigravity` with the commands in [Install for any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent).

## Cline (VS Code extension)

For skills plus the MCP Server, use the commands in [Install for any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent). To add only the MCP Server:

```bash
npx add-mcp https://mcp.neon.tech/mcp -a cline
```

For the Cline CLI, use `-a cline-cli`. To configure the extension by hand:

1. Open Cline in VS Code (sidebar → Cline icon).

2. Click the **MCP Servers** icon → **Installed** → **Configure MCP Servers** to open the configuration file.

3. Add the Neon server entry within the `mcpServers` object. For OAuth, leave out `headers`. For an API key, replace `<YOUR_NEON_API_KEY>` with your [Neon API key](https://neon.com/docs/manage/api-keys):

   ```json
   {
     "mcpServers": {
       "neon": {
         "type": "streamableHttp",
         "url": "https://mcp.neon.tech/mcp",
         "headers": {
           "Authorization": "Bearer <YOUR_NEON_API_KEY>"
         }
       }
     }
   }
   ```

4. Save the file. Cline should reload the configuration automatically. With OAuth, review the requested permissions and click **Authorize** when the browser window opens.

For more, see [Get started with Cline and Neon MCP Server](https://neon.com/guides/cline-mcp-neon).

## Devin Desktop (formerly Windsurf)

Install Neon from the Devin marketplace:

1. In Devin Desktop, open **Customize**, then **Marketplace**.
2. Find **Neon** and install it.
3. Click **Connect MCP** and sign in to Neon in the browser. The plugin's status changes to **Enabled**.
4. Start a new session so Devin loads the plugin.

The marketplace plugin includes the Neon MCP Server and Neon agent skills.

## fx

[fx](https://fx.sh) reads MCP servers only from `~/.fx/mcp.json`. A project file can't add a server. add-mcp always writes that global file; `-g` isn't required.

**Note:** fx rejects a literal `Authorization` header. Don't pass `--header "Authorization: Bearer $NEON_API_KEY"` when installing to fx. Use `bearer_token_env` (API key tab) or `/mcp auth` (OAuth tab).

**OAuth**

```bash
npx add-mcp https://mcp.neon.tech/mcp -a fx
```

This writes `~/.fx/mcp.json`:

```json
{
  "mcp": {
    "neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "enabled": true
    }
  }
}
```

A running session applies the change with `/mcp reload`. Then authorize from the fx shell:

```text
/mcp auth neon --open
```

Confirm with `/mcp list`.

**API key**

1. Create a [Neon API key](https://neon.com/docs/manage/api-keys#creating-api-keys) and export it in the environment fx will inherit:

   ```bash
   export NEON_API_KEY=<YOUR_NEON_API_KEY>
   ```

2. Write `~/.fx/mcp.json`:

   ```json
   {
     "mcp": {
       "neon": {
         "type": "http",
         "url": "https://mcp.neon.tech/mcp",
         "enabled": true,
         "bearer_token_env": "NEON_API_KEY"
       }
     }
   }
   ```

3. Start a new `fx` or `fx ask` session from this shell. Confirm with `/mcp list`. `/mcp reload` applies a later file change only in a session that already has `NEON_API_KEY`.

See [fx MCP](https://fx.sh/docs/capabilities/mcp) for `/mcp reload`, `/mcp auth`, `/mcp list`, and `bearer_token_env`.

## Gamut

1. In your [Gamut](https://www.gamut.so/mcp/developer-tools/neon) agent, go to **Connections** and click **Add Connection**.
2. Search for **Neon** and click **+** to add it.
3. When the OAuth window opens, sign in to Neon and authorize the connection.
4. Ask your agent to query or manage your database on Neon to verify the connection.

## Grok Build

Grok Build supports the Neon plugin at user level:

```bash
npx neon@latest plugins --agent grok-build
```

The plugin includes the Neon skills and the Neon MCP Server. To add only the MCP Server, run `npx add-mcp https://mcp.neon.tech/mcp -a grok-build`. For the Grok Bot chat app, see [Set up Neon in Grok Bot](https://neon.com/docs/ai/agent-setup/grok-bot).

## Jules

1. Create a [Neon API key](https://neon.com/docs/manage/api-keys#creating-api-keys) from your Neon Console **Settings**.
2. Go to [jules.google.com](https://jules.google.com) > **Settings** > **MCP** (or use [this direct link](https://jules.google.com/settings/mcp)).
3. Click **Connect** on the Neon server and paste your API key when prompted.
4. Run a task invoking the Neon MCP Server to verify the connection.

## Kimi Code

Install Neon's [agent-skills repository](https://github.com/neondatabase/agent-skills) as a plugin. Kimi reads its own manifest (`kimi.plugin.json`), which declares the Neon MCP Server, so one command wires up the skills and the MCP connection. In the Kimi CLI chat, run:

```text
/plugins install https://github.com/neondatabase/agent-skills
```

Plugin changes apply to new sessions, so run `/new` afterward. You can also run `npx neon@latest plugins --agent kimi-code`. To add only the MCP Server, run `npx add-mcp https://mcp.neon.tech/mcp -a kimi-code`, start a new session, and click **Authorize** when the OAuth window opens.

## Kiro

For skills plus the MCP Server, use the commands in [Install for any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent). To add only the MCP Server:

```bash
npx add-mcp https://mcp.neon.tech/mcp -a kiro-cli
```

Restart Kiro (or enable the MCP Server in settings). When the OAuth window opens, click **Authorize** to complete the connection.

For manual configuration, Kiro reads `~/.kiro/settings/mcp.json` (global) or `.kiro/settings/mcp.json` (project). See [Kiro MCP documentation](https://kiro.dev/docs/mcp/).

**Tip: One-click install for Kiro**

[https://kiro.dev/launch/mcp/add?name=Neon&config=%7B%22url%22%3A%20%22https%3A//mcp.neon.tech/mcp%22%7D](https://kiro.dev/launch/mcp/add?name=Neon\&config=%7B%22url%22%3A%20%22https%3A//mcp.neon.tech/mcp%22%7D)

## Pi

Install Neon's skills in [Pi](https://pi.dev) from npm:

```bash
pi install npm:@neon/skills
```

Or straight from the repository:

```bash
pi install git:github.com/neondatabase/agent-skills
```

Pi reads the `skills/` directory directly, so there's no separate sync step. This installs the skills only. To add the Neon MCP Server, run `npx neon@latest mcp --agent pi`.

## Zed

Zed calls MCP servers **context servers**. For skills plus the MCP Server, use the commands in [Install for any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent). To add only the MCP Server:

**OAuth**

```bash
npx add-mcp https://mcp.neon.tech/mcp -a zed
```

Restart Zed (or enable the MCP Server in settings). When the OAuth window opens, click **Authorize** to complete the connection.

**API key**

Add this to `~/.config/zed/settings.json`. Replace `<YOUR_NEON_API_KEY>` with your [Neon API key](https://neon.com/docs/manage/api-keys):

```json
"context_servers": {
  "Neon": {
    "source": "custom",
    "type": "http",
    "url": "https://mcp.neon.tech/mcp",
    "headers": {
      "Authorization": "Bearer <YOUR_NEON_API_KEY>"
    }
  }
}
```

For more details, including workflow examples and troubleshooting, see [Get started with Zed and the Neon MCP Server](https://neon.com/guides/zed-mcp-neon).

## Other MCP clients

For Gemini CLI, Goose, OpenCode, and the other agents in the [table above](https://neon.com/docs/ai/connect-mcp-clients-to-neon#supported-agents-add-mcp), use [Install for any supported agent](https://neon.com/docs/ai/connect-mcp-clients-to-neon#install-for-any-supported-agent).

For a client that add-mcp doesn't support, build its config with the [config generator](https://neon.com/docs/ai/neon-mcp-server#config-generator) or write it by hand. Most clients accept `"type": "http"` with the URL `https://mcp.neon.tech/mcp`. If your client only supports local (stdio) servers, use the [`mcp-remote` bridge](https://neon.com/docs/ai/neon-mcp-server#deprecated-stdio).

## Troubleshooting

See [MCP troubleshooting](https://neon.com/docs/ai/neon-mcp-server#troubleshooting) for retired SSE endpoints, stdio-only clients, and OAuth `invalid redirect uri` errors.

--- [Document source](https://neon.com/docs/ai/inngest.md) ---

> Summary: Inngest is a TypeScript workflow framework for building AI RAG and agentic pipelines on Lakebase Postgres, providing per-step caching, automatic retries, concurrency controls, and LLM request offloading via step.ai.infer() that pauses compute while waiting for slow model responses. Use this page when you need database-change-triggered or event-driven AI workflows, or want to avoid unnecessary serverless compute costs during LLM calls. Starter apps for Next.js RAG, multi-tenant RAG, and auto-embeddings with OpenAI are included.

# Inngest

Quickly build AI RAG and Agentic workflows that scale with Inngest and Neon

Last updated: 2026-07-31

Inngest is a popular framework for building AI RAG and Agentic workflows. [Inngest](https://www.inngest.com/?utm_source=neon\&utm_medium=inngest-ai-integration) provides automatic retries, caching along with concurrency and throttling management and AI requests offloading.

Inngest also integrates with the database to trigger workflows based on database changes.

## Build RAG with `step.run()`

Inngest provides a `step.run()` API that allows you to compose your workflows into cacheable, retryable, and concurrency-safe steps:

![A RAG workflow built with Inngest. A failing step is retried while the previous steps results are cached.](https://neon.com/docs/guides/inngest-rag-workflow.png)

In the above workflow, a network issue prevented the AI workflow to connect to the vector store. Fortunately, Inngest retries the failed step and uses the cached results from the previous steps, avoiding an unnecessary additional OpenAI call.

This workflow translates to the following code:

```typescript
import { inngest } from '@/inngest';
import { getToolsForMessage, vectorSearch } from '@/helpers';

export const ragWorkflow = client.createFunction(
  { id: 'rag-workflow', concurrency: 10 },
  { event: 'chat.message' },
  async ({ event, step }) => {
    const { message } = event.data;

    const page = await step.run('tools.search', async () => {
      // Calls OpenAI
      return getToolsForMessage(message);
    });

    await step.run('vector-search', async () => {
      // Search in Neon's vector store
      return vectorSearch(page);
    });

    // step 3 and 4...
  }
);
```

Configuring [concurrency](https://www.inngest.com/docs/guides/concurrency?utm_source=neon\&utm_medium=inngest-ai-integration) or [throttling](https://www.inngest.com/docs/guides/throttling?utm_source=neon\&utm_medium=inngest-ai-integration) to match your LLM provider's limits is achieved with a single line of code.

Learn more about using Inngest for RAG in the following article: [Multi-Tenant RAG With One Neon Project Per User](https://neon.com/blog/multi-tenant-rag).

## AI requests offloading: `step.ai.infer()`

Inngest also provides a `step.ai.infer()` API that offloads AI requests.
By using `step.ai.infer()` your AI workflows will pause while waiting for the slow LLM response, avoiding unnecessary compute use on Serverless environments:

![An AI workflow built with Inngest. The AI request is offloaded to the LLM provider.](https://neon.com/docs/guides/inngest-with-step-ai-infer.png)

![An AI workflow built with Inngest. The AI request is offloaded to the LLM provider.](https://neon.com/docs/guides/inngest-without-step-ai-infer.png)

The previous RAG workflow can be rewritten to use [`step.ai.infer()`](https://www.inngest.com/docs/features/inngest-functions/steps-workflows/step-ai-orchestration?utm_source=neon\&utm_medium=inngest-ai-integration#step-ai-infer) to offload the AI request to the LLM provider:

```typescript
import { inngest } from '@/inngest';
import { getPromptForToolsSearch, vectorSearch } from '@/helpers';

export const ragWorkflow = client.createFunction(
  { id: 'rag-workflow', concurrency: 10 },
  { event: 'chat.message' },
  async ({ event, step }) => {
    const { message } = event.data;

    const prompt = getPromptForToolsSearch(message);
    await step.ai.infer('tools.search', {
      model: openai({ model: 'gpt-4o' }),
      body: {
        messages: prompt,
      },
    });

    // other steps...
  }
);
```

`step.ai.infer()`, combined with Neon's Scale-to-zero feature, allows you to build AI workflows that scale costs with its success!

Learn more about using `step.ai.infer()` in the following article: [step.ai: Build Serverless AI Applications That Won't Break the Bank](https://www.inngest.com/blog/step-ai-for-serverless-ai-applications?utm_source=neon\&utm_medium=inngest-ai-integration).

## Trigger AI workflows based on database changes

Inngest also integrates with Lakebase Postgres to trigger AI workflows based on database changes:

![Inngest integrates with Lakebase Postgres to trigger AI workflows based on database changes](https://neon.com/docs/guides/inngest.jpg)

This integration allows you to trigger AI workflows based on database changes, such as generating embeddings as soon as a new row is inserted into a table (see example below).

Configure the Inngest's Neon integration to trigger AI workflows from your Neon database changes [by following this guide](https://neon.com/docs/guides/trigger-serverless-functions).

## Starter apps

Hackable, fully-featured, pre-built [starter apps](https://github.com/neondatabase/examples/tree/main/ai/inngest) to get you up and running with Inngest and Postgres.

- [RAG starter (OpenAI + Inngest)](https://github.com/neondatabase/examples/tree/main/ai/inngest/rag-starter-nextjs): A Next.js RAG starter app built with OpenAI and Inngest
- [multi-tenant RAG (OpenAI + Inngest)](https://github.com/inngest/multi-tenant-rag-example): A Next.js contacts importer multi-tenant RAG built with OpenAI and Inngest
- [Auto-embedding (OpenAI + Inngest)](https://github.com/neondatabase/examples/tree/main/ai/inngest/auto-embeddings-nextjs): A Next.js app example of auto-embedding with Inngest

--- [Document source](https://neon.com/docs/ai/lakebase-search-get-started.md) ---

> Summary: Step-by-step guide to enabling lakebase_vector and lakebase_text on a Neon Postgres database, creating a documents table with vector embeddings and a BM25 full-text index, and running vector and keyword searches from a TypeScript application using @neondatabase/serverless and the Vercel AI SDK.

# Get started with Lakebase Search

Set up vector and full-text search on Neon in minutes

Last updated: 2026-10-23

This guide sets up Lakebase Search on a Neon project: enabling both extensions, creating a schema that supports vector and full-text search, inserting documents with embeddings, and querying from TypeScript.

## Prerequisites

- A Neon project. You enable Lakebase Search on it in the first step below.
- Postgres 16 or later (Lakebase Search requires PG16+)
- Node.js 22 or later
- Choose an embedding provider to turn text into vectors:
  - **Neon AI Gateway** (this guide's default): set `NEON_AI_GATEWAY_TOKEN` and `NEON_AI_GATEWAY_BASE_URL` (see [Get started](https://neon.com/docs/ai-gateway/get-started)) and use the [`qwen3-embedding-0-6b`](https://neon.com/docs/ai-gateway/embeddings) model (1024 dimensions). Requires [prepaid AI Gateway credits](https://neon.com/docs/ai-gateway/prepaid-credits), available on any plan, and a project in a [Neon AI Gateway region](https://neon.com/docs/ai-gateway/overview).
  - **OpenAI directly**: install `@ai-sdk/openai`, set `OPENAI_API_KEY`, and use `openai.embeddingModel('text-embedding-3-small')` from that provider (1536 dimensions).
  - **Any other provider**: generate the vector with its SDK and match the `VECTOR` column to its dimensions.

## Enable the extensions

Install the extensions in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any connected Postgres client:

```sql
CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
CREATE EXTENSION IF NOT EXISTS lakebase_text CASCADE;
```

`CASCADE` automatically installs `pgvector` if it is not already present, since `lakebase_vector` depends on it.

## Create a table

```sql
CREATE TABLE documents (
  id        SERIAL PRIMARY KEY,
  title     TEXT NOT NULL,
  body      TEXT NOT NULL,
  embedding VECTOR(1024),
  body_tsv  TSVECTOR GENERATED ALWAYS AS (to_tsvector('english', body)) STORED
);

CREATE INDEX documents_embedding_idx ON documents
  USING lakebase_ann (embedding vector_cosine_ops);
```

The `lakebase_bm25` index is created in a later step, after data is inserted. BM25 computes corpus-wide statistics (document count, term frequencies) at index build time, so the index must be built on populated data to return meaningful scores.

## Set up your project

The remaining steps run from a local TypeScript project. Install dependencies:

```bash
npm install @neondatabase/serverless @neon/ai-sdk-provider@1.1.0 ai@7.0.133 dotenv
```

This guide uses Neon's provider with the Vercel AI SDK for embeddings and Jev. The provider reads your AI Gateway credentials automatically. Keep the SDK versions pinned while `experimental_decide` is experimental.

Create a `.env` file with your Neon connection string and AI Gateway credentials. See [Get started with AI Gateway](https://neon.com/docs/ai-gateway/get-started) for how to obtain the gateway values:

```ini filename=".env"
DATABASE_URL=postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require
NEON_AI_GATEWAY_TOKEN=nt_live_...
NEON_AI_GATEWAY_BASE_URL=https://[branch-host]
```

## Run the demo

Create `search.ts` and paste the following. It inserts documents with embeddings, creates the `lakebase_bm25` index, runs a vector search, then runs a BM25 text search:

```typescript filename="search.ts"
import 'dotenv/config';
import { neon } from '@neondatabase/serverless';
import { neon as neonAi } from '@neon/ai-sdk-provider';
import { embed } from 'ai';

const sql = neon(process.env.DATABASE_URL!);

const documents = [
  {
    title: 'Vector search on Postgres',
    body: 'lakebase_vector adds a lakebase_ann index to Postgres for fast approximate nearest-neighbor search at billion-vector scale.',
  },
  {
    title: 'BM25 full-text search',
    body: 'lakebase_text adds a lakebase_bm25 index that provides BM25 ranking and top-K pushdown while preserving standard tsvector types.',
  },
  {
    title: 'AI agent memory',
    body: 'Store conversation history, session state, and vector embeddings in a single Postgres database to power AI agent backends.',
  },
  {
    title: 'Branching for retrieval experiments',
    body: 'Neon branching lets you test new chunking strategies or embedding models on a branch without rebuilding your search indexes.',
  },
  {
    title: 'Scale-to-zero search',
    body: 'Lakebase Search indexes survive cold starts. Your vector and BM25 indexes are available immediately after a Neon compute wakes up.',
  },
];

async function embedText(text: string): Promise<string> {
  const { embedding } = await embed({
    model: neonAi.embeddingModel('qwen3-embedding-0-6b'),
    value: text,
  });
  return JSON.stringify(embedding);
}

async function embedAndInsert() {
  for (const doc of documents) {
    const vector = await embedText(doc.body);
    await sql`
      INSERT INTO documents (title, body, embedding)
      VALUES (${doc.title}, ${doc.body}, ${vector}::vector)
    `;
  }
}

async function vectorSearch(query: string, limit = 5) {
  const queryVector = await embedText(query);

  return sql`
    SELECT id, title,
           embedding <=> ${queryVector}::vector AS distance
    FROM documents
    ORDER BY distance
    LIMIT ${limit}
  `;
}

// BM25 scores are negative — lower (more negative) means more relevant
async function textSearch(query: string, limit = 5) {
  return sql`
    SELECT id, title, score
    FROM (
      SELECT id, title,
             body_tsv <@> to_bm25query(
               to_tsvector('english', ${query}),
               'documents_bm25'
             ) AS score
      FROM documents
    ) AS scored
    WHERE score < 0
    ORDER BY score, id
    LIMIT ${limit}
  `;
}

async function main() {
  console.log('Inserting documents...');
  await embedAndInsert();

  console.log('Building BM25 index...');
  await sql`
    CREATE INDEX IF NOT EXISTS documents_bm25 ON documents
    USING lakebase_bm25 (body_tsv)
    WITH (default_limit = 10)
  `;

  console.log('\nVector search — "how do agents store memory?":');
  console.log(await vectorSearch('how do agents store memory?'));

  console.log('\nBM25 search — "vector search":');
  console.log(await textSearch('vector search'));
}

main();
```

Run it:

```bash
npx tsx search.ts
```

## Combine results with hybrid search

Vector search finds matches by meaning, while keyword search finds matches by wording. You can combine their results in two ways:

- **Jev through Neon AI Gateway** reads each result alongside your query and scores how likely it is to answer your question.
- **Reciprocal Rank Fusion (RRF)** uses each result's position in the two search lists to build a combined ranking, without an extra model call.

### Use Jev through Neon AI Gateway

Jev reads each result alongside your query and estimates how likely it is to answer your question. The example below combines both searches, removes duplicates, and puts the most likely answers first. It follows the [TypeSafe reranking cookbook](https://docs.typesafe.ai/cookbooks/rerank_typesafe).

Jev runs through AI Gateway, so it has the same credits requirement as AI Gateway embeddings. If you don't have AI Gateway, use [RRF](https://neon.com/docs/ai/lakebase-search-get-started#fuse-ranks-with-rrf) instead.

Add the following code to `search.ts`. It reuses the provider and credentials from the embedding example. See [Decision models](https://neon.com/docs/ai-gateway/decisions#use-with-the-vercel-ai-sdk) for more about the SDK.

```typescript filename="search.ts"
import { experimental_decide as decide } from 'ai';

type Candidate = { id: number; title: string; body: string };

async function hybridSearchWithJev(query: string, limit = 5): Promise<Candidate[]> {
  if (!Number.isInteger(limit) || limit < 1) {
    throw new Error('limit must be a positive integer');
  }

  const queryVector = await embedText(query);
  const candidates = (await sql`
    WITH vector_candidates AS (
      SELECT id
      FROM documents
      WHERE embedding IS NOT NULL
      ORDER BY embedding <=> ${queryVector}::vector
      LIMIT 40
    ),
    keyword_candidates AS (
      SELECT id
      FROM (
        SELECT id, body_tsv <@> to_bm25query(
          to_tsvector('english', ${query}), 'documents_bm25'
        ) AS score
        FROM documents
      ) AS scored
      WHERE score < 0
      ORDER BY score, id
      LIMIT 40
    ),
    candidate_ids AS (
      SELECT id FROM vector_candidates
      UNION
      SELECT id FROM keyword_candidates
    )
    SELECT d.id, d.title, d.body
    FROM candidate_ids AS c
    JOIN documents AS d ON d.id = c.id
    ORDER BY d.id
  `) as Candidate[];
  if (candidates.length === 0) return [];

  const { answers } = await decide({
    model: neonAi.decisionModel('typesafeai-jev-1-14-0'),
    state: { query },
    questions: Object.fromEntries(
      candidates.map((doc, index) => [
        `d${index}`,
        {
          type: 'boolean' as const,
          instructions: {
            question:
              'Given the search query in state.query, does this candidate passage supply the specific information the user is looking for?',
            candidate: { title: doc.title, body: doc.body },
          },
          criteria: {
            true: 'The candidate states the specific facts or steps the query asks for.',
            false:
              'The candidate only shares keywords or a topic with the query, answers a different question, or lacks the requested information.',
          },
        },
      ])
    ),
    maxRetries: 0,
    abortSignal: AbortSignal.timeout(10_000),
  });

  return candidates
    .map((doc, index) => {
      const answer = answers[`d${index}`];
      if (answer?.type !== 'boolean') {
        throw new Error(`Missing relevance probability for d${index}`);
      }
      return { doc, index, probability: answer.probability };
    })
    .sort((a, b) => b.probability - a.probability || a.index - b.index)
    .slice(0, limit)
    .map(({ doc }) => doc);
}
```

Call `hybridSearchWithJev(query)` after inserting the documents and building the indexes. It sends the query and all the search results to Jev in one request, which must fit within the model's 65,536-token context window. For long documents, search shorter passages or send fewer results. If your app restricts documents by tenant or user, apply those filters to both searches before limiting the results.

One result will always rank first, even if none answers the query. If your app needs to say "no answer," test it with unanswered queries to choose a minimum score for accepting a result. If the Jev call fails, you can catch the error and fall back to `hybridSearch`.

### Fuse ranks with RRF

RRF gives each result a score of `1 / (60 + rank)` for its position in each search list, then adds the two scores. Results near the top of either list get higher scores.

Add a `hybridSearch` function to `search.ts`, alongside `vectorSearch` and `textSearch`. It reuses the `documents` table and indexes from above:

```typescript filename="search.ts"
async function hybridSearch(query: string, limit = 5) {
  const queryVector = await embedText(query);

  return sql`
    WITH vector_ranked AS (
      SELECT id, RANK() OVER (ORDER BY dist) AS rank
      FROM (
        SELECT id, embedding <=> ${queryVector}::vector AS dist
        FROM documents
        WHERE embedding IS NOT NULL
        ORDER BY dist
        FETCH FIRST 40 ROWS WITH TIES
      ) v
    ),
    keyword_ranked AS (
      SELECT id, RANK() OVER (ORDER BY score) AS rank
      FROM (
        SELECT id, score
        FROM (
          SELECT id, body_tsv <@> to_bm25query(
            to_tsvector('english', ${query}), 'documents_bm25'
          ) AS score
          FROM documents
        ) AS scored
        WHERE score < 0
        ORDER BY score, id
        LIMIT 40
      ) k
    )
    SELECT d.id, d.title,
      COALESCE(1.0 / (60 + v.rank), 0) + COALESCE(1.0 / (60 + k.rank), 0) AS rrf_score
    FROM documents d
    LEFT JOIN vector_ranked v ON d.id = v.id
    LEFT JOIN keyword_ranked k ON d.id = k.id
    WHERE v.id IS NOT NULL OR k.id IS NOT NULL
    ORDER BY rrf_score DESC, d.id
    LIMIT ${limit}
  `;
}
```

`WITH TIES` keeps vector results that share the 40th result's distance, so the search can return more than 40 rows. The keyword search leaves out non-matches and stops at 40 because many BM25 matches can have the same score. `RANK()` gives tied results the same rank, and `d.id` keeps the final order stable when scores are equal. Try different candidate counts and RRF constants to find what works best for your data.

## Next steps

- [lakebase_vector reference](https://neon.com/docs/extensions/lakebase-vector): index options, operator classes, tuning guide
- [lakebase_text reference](https://neon.com/docs/extensions/lakebase-text): BM25 operators, functions, fallback parameters, prefilter
- [lakebase_tokenizer reference](https://neon.com/docs/extensions/lakebase-tokenizer): optional configurable tokenization, stop words, synonyms, and stemming

--- [Document source](https://neon.com/docs/ai/lakebase-search.md) ---

> Summary: Lakebase Search adds vector, keyword, and hybrid search to Neon through the lakebase_vector and lakebase_text Postgres extensions, with optional configurable tokenization from lakebase_tokenizer. Use this page to understand the search types, how the extensions work, the scale-to-zero architecture advantages, and where to get started.

# Lakebase Search

Scalable vector and full-text search for Postgres

Last updated: 2026-10-23

**About Lakebase:**

Lakebase Search is developed by Databricks. These extensions are part of the shared technology foundation between Neon and the Databricks Lakebase platform.

Lakebase Search adds vector, keyword, and hybrid search to your Neon project. Install `lakebase_vector` for vector search, `lakebase_text` for BM25 keyword search, and `lakebase_tokenizer` for configurable tokenization.

[View prompt](https://neon.com/prompts/lakebase-search-landing.md)

## Vector, keyword, and hybrid search

Lakebase Search gives you two complementary ways to search. Use either on its own, or combine them:

- **Vector (semantic) search** finds rows whose meaning is closest to your query, even when they share no words. You search with an embedding (a numeric vector from a model), and the `lakebase_ann` index returns the nearest vectors by distance. Use it for natural-language questions, recommendations, and retrieval-augmented generation (RAG).
- **Keyword (full-text) search** ranks rows by how well they match the exact terms in your query, using BM25 relevance scoring from the `lakebase_bm25` index. Use it for names, codes, and exact-term lookups where wording matters.
- **Hybrid search** combines vector and keyword results with fusion or reranking, so you get semantic and exact-term matches together. Use it when queries mix intent with specific terms, which covers most real-world search. The [Get started guide](https://neon.com/docs/ai/lakebase-search-get-started#combine-results-with-hybrid-search) shows how to combine results with Jev through Neon AI Gateway or RRF.

![Keyword search matches only documents that contain the typed words and misses synonyms like "quick automobile" for "fast sports car." Vector search places the query and documents in the same embedding space and returns the nearest neighbors by meaning, including those synonyms.](https://neon.com/docs/ai/lakebase-search-keyword-vs-vector.png)

## How it works

Lakebase Search is built on three Postgres extensions:

- **[`lakebase_vector`](https://neon.com/docs/extensions/lakebase-vector)**: adds the `lakebase_ann` index type for vector similarity search. No migration from `pgvector` required. The same `vector` types, distance operators, and query syntax work unchanged. Scales to over 1 billion vectors on a single index.
- **[`lakebase_text`](https://neon.com/docs/extensions/lakebase-text)**: adds the `lakebase_bm25` index type for BM25 keyword search. No migration from Postgres full-text search required. Standard `tsvector` types and query operators work unchanged. Adds BM25 ranking and top-K pushdown that native GIN lacks.
- **[`lakebase_tokenizer`](https://neon.com/docs/extensions/lakebase-tokenizer)**: adds configurable whole-word tokenization and Chinese, Japanese, and Korean (CJK) morphological analysis through Postgres's text-search dictionary interface. It produces standard `tsvector` values that work with GIN and `lakebase_bm25` indexes.

## How `lakebase_ann` scales

`lakebase_ann` is designed for the separated compute/storage architecture that powers Neon. Because the index lives in storage rather than in compute memory, it works naturally with Neon's scale-to-zero model: your vector index is available immediately after a cold start, with no warmup required. You only pay for compute when your database is actively serving requests. This holds for production workloads and for development or staging environments where the database sits idle most of the time.

It uses IVF (Inverted File) partitioning to divide the vector space into lists and searches only the relevant ones at query time, using sequential I/O that suits storage-backed systems. RaBitQ quantization compresses vectors 4–8x, keeping index size and build time down. The result:

- **Scale to 1 billion+ vectors**: a single `lakebase_ann` index grows with your data without resharding or rebuilding
- **Faster index builds**: compression reduces index size significantly, making builds 50–100x faster than HNSW
- **Branching without index rebuilds**: Neon branches copy-on-write; your search indexes are available instantly on every branch without re-indexing
- **Scale-to-zero compatible**: indexes survive cold starts without warmup; you don't pay for idle compute

## Get started

- [Quickstart](https://neon.com/docs/ai/lakebase-search-get-started): Install lakebase_vector and lakebase_text, create a schema, insert documents with embeddings, and run your first searches
- [lakebase_vector reference](https://neon.com/docs/extensions/lakebase-vector): Index options, operator classes, and tuning reference for lakebase_vector
- [lakebase_text reference](https://neon.com/docs/extensions/lakebase-text): BM25 operators, functions, fallback parameters, and prefilter reference for lakebase_text
- [lakebase_tokenizer reference](https://neon.com/docs/extensions/lakebase-tokenizer): Whole-word and CJK tokenization, built-in language configurations, custom stop words, synonyms, and stemming

--- [Document source](https://neon.com/docs/ai/langchain.md) ---

> Summary: LangChain integration with Neon uses the `NeonPostgres` vector store class (backed by `pgvector`) to store embeddings and run similarity search directly in Postgres. Use this page when building RAG pipelines, AI chatbots, or semantic search in JavaScript/TypeScript and you need LangChain's retrieval chain wired to a Neon database. Includes full TypeScript code for initializing the vector store with OpenAI embeddings, streaming chat completions via `createRetrievalChain`, and links to Next.js starter apps for chatbot, RAG, semantic search, and PDF chat.

# LangChain

Build AI applications faster with LangChain and Postgres

Last updated: 2026-09-30

LangChain is a popular framework for working with AI, Vectors, and embeddings. LangChain supports using Neon as a vector store, using the `pgvector` extension.

## Initialize Postgres Vector Store

LangChain handles document insertion and embedding generation through its vector store methods.

Here's how you can initialize Postgres Vector with LangChain. `OpenAIEmbeddings` works against either OpenAI directly or the [Neon AI Gateway](https://neon.com/docs/ai-gateway/embeddings), which serves embedding models on an OpenAI-compatible endpoint using the same Neon credential as the rest of your project:

**Neon AI Gateway**

```tsx
// File: vectorStore.ts

import { NeonPostgres } from '@langchain/community/vectorstores/neon';
import { OpenAIEmbeddings } from '@langchain/openai';

const embeddings = new OpenAIEmbeddings({
  model: 'qwen3-embedding-0-6b', // 1024-dimensional; supports the `dimensions` parameter
  dimensions: 512,
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  configuration: {
    baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
  },
});

export async function loadVectorStore() {
  return await NeonPostgres.initialize(embeddings, {
    connectionString: process.env.POSTGRES_URL as string,
  });
}

// Use in your code (say, in API routes)
const vectorStore = await loadVectorStore();
```

**OpenAI**

```tsx
// File: vectorStore.ts

import { NeonPostgres } from '@langchain/community/vectorstores/neon';
import { OpenAIEmbeddings } from '@langchain/openai';

const embeddings = new OpenAIEmbeddings({
  dimensions: 512,
  model: 'text-embedding-3-small',
});

export async function loadVectorStore() {
  return await NeonPostgres.initialize(embeddings, {
    connectionString: process.env.POSTGRES_URL as string,
  });
}

// Use in your code (say, in API routes)
const vectorStore = await loadVectorStore();
```

**Note:** Set `NEON_AI_GATEWAY_TOKEN` and `NEON_AI_GATEWAY_BASE_URL` from your branch (`neon env pull`, or the Neon Console's **Connect** panel). On the `openai` JavaScript SDK v6, embedding calls need `encoding_format: 'float'`, or upgrade to v7 or later. See [Embeddings](https://neon.com/docs/ai-gateway/embeddings) for model IDs, dimensions, and this SDK caveat.

## Generate Embeddings with OpenAI

LangChain handles embedding generation internally while adding vectors to the Postgres database, simplifying the process for users. For more detailed control over embeddings, refer to the respective [JavaScript](https://js.langchain.com/v0.2/docs/integrations/text_embedding/openai#specifying-dimensions) and [Python](https://python.langchain.com/v0.2/docs/how_to/embed_text/#embed_query) documentation.

## Stream Chat Completions with OpenAI

LangChain can find similar documents to the user's latest query and invoke the OpenAI API to power [chat completion](https://platform.openai.com/docs/guides/text-generation/chat-completions-api) responses, providing a seamless integration for creating dynamic interactions.

Here's how you can power chat completions in an API route:

```tsx
import { loadVectorStore } from './vectorStore';

import { pull } from 'langchain/hub';
import { ChatOpenAI } from '@langchain/openai';
import { createRetrievalChain } from 'langchain/chains/retrieval';
import type { ChatPromptTemplate } from '@langchain/core/prompts';
import { AIMessage, HumanMessage } from '@langchain/core/messages';
import { createStuffDocumentsChain } from 'langchain/chains/combine_documents';

const topK = 3;

export async function POST(request: Request) {
  const llm = new ChatOpenAI();
  const encoder = new TextEncoder();
  const vectorStore = await loadVectorStore();
  const { messages = [] } = await request.json();
  const userMessages = messages.filter((i) => i.role === 'user');
  const input = userMessages[userMessages.length - 1].content;
  const retrievalQAChatPrompt = await pull<ChatPromptTemplate>('langchain-ai/retrieval-qa-chat');
  const retriever = vectorStore.asRetriever({ k: topK, searchType: 'similarity' });
  const combineDocsChain = await createStuffDocumentsChain({
    llm,
    prompt: retrievalQAChatPrompt,
  });
  const retrievalChain = await createRetrievalChain({
    retriever,
    combineDocsChain,
  });
  const customReadable = new ReadableStream({
    async start(controller) {
      const stream = await retrievalChain.stream({
        input,
        chat_history: messages.map((i) =>
          i.role === 'user' ? new HumanMessage(i.content) : new AIMessage(i.content)
        ),
      });
      for await (const chunk of stream) {
        controller.enqueue(encoder.encode(chunk.answer));
      }
      controller.close();
    },
  });
  return new Response(customReadable, {
    headers: {
      Connection: 'keep-alive',
      'Content-Encoding': 'none',
      'Cache-Control': 'no-cache, no-transform',
      'Content-Type': 'text/plain; charset=utf-8',
    },
  });
}
```

## Starter apps

Hackable, fully-featured, pre-built [starter apps](https://github.com/neondatabase/examples/tree/main/ai/llamaindex) to get you up and running with LlamaIndex and Postgres.

- [AI chatbot (OpenAI + LangChain)](https://github.com/neondatabase/examples/tree/main/ai/langchain/chatbot-nextjs): A Next.js AI chatbot starter app built with OpenAI and LangChain
- [RAG chatbot (OpenAI + LangChain)](https://github.com/neondatabase/examples/tree/main/ai/langchain/rag-nextjs): A Next.js RAG chatbot starter app built with OpenAI and LangChain
- [Semantic search chatbot (OpenAI + LangChain)](https://github.com/neondatabase/examples/tree/main/ai/langchain/semantic-search-nextjs): A Next.js Semantic Search chatbot starter app built with OpenAI and LangChain
- [Chat with PDF (OpenAI + LangChain)](https://github.com/neondatabase/examples/tree/main/ai/langchain/chat-with-pdf-nextjs): A Next.js Chat with PDF chatbot starter app built with OpenAI and LangChain

--- [Document source](https://neon.com/docs/ai/llamaindex.md) ---

> Summary: LlamaIndex integrates with Lakebase Postgres as a vector store via the pgvector extension, enabling RAG pipelines, semantic search, and AI chatbots backed by serverless Postgres. Use this page to wire up PGVectorStore, generate OpenAI embeddings, and stream chat completions through ContextChatEngine in a Next.js API route. Includes TypeScript code for initialization and streaming, plus links to starter apps for chatbot, RAG, semantic search, reverse image search, and PDF chat.

# LlamaIndex

Build AI applications faster with LlamaIndex and Postgres

Last updated: 2026-09-30

LlamaIndex is a popular framework for working with AI, Vectors, and embeddings. LlamaIndex supports using Neon as a vector store, using the `pgvector` extension.

## Initialize Postgres Vector Store

LlamaIndex simplifies the complexity of managing document insertion and embeddings generation using vector stores by providing streamlined methods for these tasks.

Here's how you can initialize Postgres Vector with LlamaIndex. `OpenAIEmbedding` works against either OpenAI directly or the [Neon AI Gateway](https://neon.com/docs/ai-gateway/embeddings), which serves embedding models on an OpenAI-compatible endpoint using the same Neon credential as the rest of your project:

**Neon AI Gateway**

```tsx
// File: vectorStore.ts

import { OpenAIEmbedding, Settings } from 'llamaindex';
import { PGVectorStore } from 'llamaindex/storage/vectorStore/PGVectorStore';

Settings.embedModel = new OpenAIEmbedding({
  model: 'qwen3-embedding-0-6b', // 1024-dimensional; supports the `dimensions` parameter
  dimensions: 512,
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  additionalSessionOptions: {
    baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
  },
});

const vectorStore = new PGVectorStore({
  dimensions: 512,
  connectionString: process.env.POSTGRES_URL,
});

export default vectorStore;

// Use in your code (say, in API routes)
const index = await VectorStoreIndex.fromVectorStore(vectorStore);
```

**OpenAI**

```tsx
// File: vectorStore.ts

import { OpenAIEmbedding, Settings } from 'llamaindex';
import { PGVectorStore } from 'llamaindex/storage/vectorStore/PGVectorStore';

Settings.embedModel = new OpenAIEmbedding({
  dimensions: 512,
  model: 'text-embedding-3-small',
});

const vectorStore = new PGVectorStore({
  dimensions: 512,
  connectionString: process.env.POSTGRES_URL,
});

export default vectorStore;

// Use in your code (say, in API routes)
const index = await VectorStoreIndex.fromVectorStore(vectorStore);
```

**Note:** Set `NEON_AI_GATEWAY_TOKEN` and `NEON_AI_GATEWAY_BASE_URL` from your branch (`neon env pull`, or the Neon Console's **Connect** panel). Keep the `PGVectorStore` `dimensions` in sync with the embedding model's output size. See [Embeddings](https://neon.com/docs/ai-gateway/embeddings) for model IDs and dimensions.

## Generate Embeddings with OpenAI

LlamaIndex handles embedding generation internally while adding vectors to the Postgres database, simplifying the process for users. For more detailed control over embeddings, refer to the respective [JavaScript](https://ts.llamaindex.ai/docs/llamaindex/modules/models/embeddings/openai) and [Python](https://docs.llamaindex.ai/en/stable/examples/embeddings/OpenAI) documentation.

## Stream Chat Completions with OpenAI

LlamaIndex can find similar documents to the user's latest query and invoke the OpenAI API to power [chat completion](https://platform.openai.com/docs/guides/text-generation/chat-completions-api) responses, providing a seamless integration for creating dynamic interactions.

Here's how you can power chat completions in an API route:

```tsx
import vectorStore from './vectorStore';

import { ContextChatEngine, VectorStoreIndex } from 'llamaindex';

interface Message {
  role: 'user' | 'assistant' | 'system' | 'memory';
  content: string;
}

export async function POST(request: Request) {
  const encoder = new TextEncoder();
  const { messages = [] } = (await request.json()) as { messages: Message[] };
  const userMessages = messages.filter((i) => i.role === 'user');
  const query = userMessages[userMessages.length - 1].content;
  const index = await VectorStoreIndex.fromVectorStore(vectorStore);
  const retriever = index.asRetriever();
  const chatEngine = new ContextChatEngine({ retriever });
  const customReadable = new ReadableStream({
    async start(controller) {
      const stream = await chatEngine.chat({ message: query, chatHistory: messages, stream: true });
      for await (const chunk of stream) {
        controller.enqueue(encoder.encode(chunk.response));
      }
      controller.close();
    },
  });
  return new Response(customReadable, {
    headers: {
      Connection: 'keep-alive',
      'Content-Encoding': 'none',
      'Cache-Control': 'no-cache, no-transform',
      'Content-Type': 'text/plain; charset=utf-8',
    },
  });
}
```

## Starter apps

Hackable, fully-featured, pre-built [starter apps](https://github.com/neondatabase/examples/tree/main/ai/llamaindex) to get you up and running with LlamaIndex and Postgres.

- [AI chatbot (OpenAI + LllamIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/chatbot-nextjs): A Next.js AI chatbot starter app built with OpenAI and LlamaIndex
- [RAG chatbot (OpenAI + LlamaIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/rag-nextjs): A Next.js RAG chatbot starter app built with OpenAI and LlamaIndex
- [Semantic search chatbot (OpenAI + LlamaIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/semantic-search-nextjs): A Next.js Semantic Search chatbot starter app built with OpenAI and LlamaIndex
- [Reverse image search (OpenAI + LlamaIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/reverse-image-search-nextjs): A Next.js Reverse Image Search Engine starter app built with OpenAI and LlamaIndex
- [Chat with PDF (OpenAI + LlamaIndex)](https://github.com/neondatabase/examples/tree/main/ai/llamaindex/chat-with-pdf-nextjs): A Next.js Chat with PDF chatbot starter app built with OpenAI and LlamaIndex

--- [Document source](https://neon.com/docs/ai/neon-mcp-server.md) ---

> Summary: The Neon MCP Server implements the Model Context Protocol (MCP), letting AI assistants interact with your Neon projects on your behalf. Set up with `npx neon@latest mcp` or use the config generator. Supports OAuth and API key auth.

# Neon MCP Server overview

Connect your AI assistant to Neon to manage projects, run queries, and make schema changes

Last updated: 2026-11-06

The Neon MCP Server implements the Model Context Protocol (MCP), letting AI assistants interact with your Neon projects on your behalf. Your AI agent can interact with Neon via MCP tools or by running [Neon CLI](https://neon.com/docs/cli) commands directly.

**Important: Security**

The Neon MCP Server grants broad database management capabilities. **Always review and authorize actions requested by the LLM before execution.** Restrict access to trusted users only. See [MCP security guidance](https://neon.com/docs/ai/neon-mcp-server#mcp-security-guidance).

## Quick setup

To set up the Neon MCP Server in your agent, follow [Set up your AI agent](https://neon.com/docs/ai/agent-setup). For most coding agents, the Neon plugin installs the MCP Server together with Neon's agent skills. To install only the MCP Server, run [`neon mcp`](https://neon.com/docs/cli/mcp):

```bash
npx neon@latest mcp
```

It prompts for where to write the config, which agents to install into, and how to authenticate, then writes it for you. For CI or headless agents, run `neon mcp -y --agent <agent> --api-key <key>`. The CLI signs in with that key and mints a new one for the MCP Server. Or use the API key option in the [config generator](https://neon.com/docs/ai/neon-mcp-server#config-generator).

## Config generator

Use the generator to build an MCP config for your editor and auth method, including the `Authorization` header for API key or remote agent setups.

If you'd rather write the config by hand, most clients accept this format. With OAuth, your client opens a browser to authorize on first use:

**OAuth**

```json
{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp"
    }
  }
}
```

**API key**

```json
{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <NEON_API_KEY>"
      }
    }
  }
}
```

Add [access control](https://neon.com/docs/ai/neon-mcp-server#access-control) parameters to the `url` as needed.

## Claude connector

The Neon MCP Server is an official Claude connector for Claude.ai and Claude Desktop. See [Set up Neon in Claude.ai and Claude Desktop](https://neon.com/docs/ai/agent-setup/claude-ai).

This page covers the hosted Neon MCP Server, which manages your Neon resources. To give your own application an MCP server that customers connect to, see [Build an MCP server with Managed Better Auth](https://neon.com/docs/compute/functions/mcp-server).

## Access control

The Neon MCP Server supports URL parameters to restrict scope and permissions. Append them to the MCP URL (`https://mcp.neon.tech/mcp`).

### Read-only mode

Append `?readonly=true` to restrict the server to read operations:

```
https://mcp.neon.tech/mcp?readonly=true
```

`SELECT` queries and schema inspection remain available. Write operations (creating branches, running migrations, modifying auth config) are disabled. `run_sql_transaction` and `get_connection_string` aren't available in read-only mode; use `run_sql` for read queries.

With OAuth, you can also choose read-only scope during the authorization flow instead of using the URL parameter.

### Project-scoped mode

Scope all operations to a single project:

```
https://mcp.neon.tech/mcp?projectId=<your-project-id>
```

Cross-project search and navigation are disabled in this mode, and project management tools such as `list_projects` and `create_project` are hidden.

### Category filtering

Restrict active tools to specific categories using `?category=<name>` (repeatable):

```
https://mcp.neon.tech/mcp?category=querying&category=schema
```

See [Available tools](https://neon.com/docs/ai/neon-mcp-server#available-tools) for the full category list. To verify which tools are active for a given config without authenticating:

```bash
curl "https://mcp.neon.tech/api/list-tools?readonly=true&category=querying"
```

### Postgres role

By default, SQL tools connect as the database owner. Set `?roleName=<role>` to make every SQL tool log in as that Postgres role instead, so the role's grants decide what the agent can read and change:

```
https://mcp.neon.tech/mcp?readonly=true&roleName=app_reader
```

The role must exist on each branch you query and be able to log in. For example, a role that can only read one table:

```sql
CREATE ROLE app_reader LOGIN PASSWORD '<password>';
GRANT SELECT ON public.orders TO app_reader;
```

Create the role with SQL, as shown above, or create a read-only or read-write role with [`neon roles create --access`](https://neon.com/docs/cli/roles#create). Roles created in the Neon Console or API, and roles created with the CLI or MCP Server without an access level, are members of [`neon_superuser`](https://neon.com/docs/manage/roles#the-neonsuperuser-role), which can read all data, so pinning one of those roles doesn't limit what the agent can read. See [Manage database access](https://neon.com/docs/manage/database-access) for least-privilege role examples.

- `role_name` arguments that name a different role are rejected, and a role that cannot log in fails the call without falling back to the owner.
- `get_connection_string` is not available on a pinned connection.
- The role applies to SQL only. Combine it with `readonly=true` and `category` to limit Management API tools too.
- With OAuth, `roleName` on the URL is fixed when you authorize. With the plain `https://mcp.neon.tech/mcp` URL, enter the role in the optional **Postgres role** field on the authorization page instead.

## MCP security guidance

We recommend MCP for **development and testing only**, not production environments.

- Use MCP only for local development or IDE-based workflows
- Never connect MCP agents to production databases
- Avoid exposing production or PII data; use anonymized data only
- Always review and authorize LLM-requested actions before execution
- Restrict MCP access to trusted users and regularly audit access

To limit what an agent can do, combine [read-only mode](https://neon.com/docs/ai/neon-mcp-server#read-only-mode), a [Postgres role](https://neon.com/docs/ai/neon-mcp-server#postgres-role) with limited grants, and [category filtering](https://neon.com/docs/ai/neon-mcp-server#category-filtering).

### Check the authorization page

When you connect with OAuth, the authorization page shows where the sign-in returns before you click **Approve**, for example "Returns to claude.ai". Approve only when that matches the client you're connecting:

- **Returns to an app on this computer:** The sign-in returns to a `localhost` or `127.0.0.1` address. Continue only if you started the sign-in from an app on your computer.
- **App identity published at a host:** Clients such as Claude, ChatGPT, Codex, VS Code, Zed, GitHub Copilot CLI, and Antigravity identify themselves with a [Client ID Metadata Document](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration), an `https` URL that describes the client. The page names the host that published that document, such as `claude.ai`. This confirms who controls the client ID, not which app is behind it.

Clients that don't support metadata documents register through dynamic client registration and don't show an app identity line. Select **App details** to see the client's website and every registered redirect URI.

### Allowlist IP addresses

The hosted Neon MCP Server (`mcp.neon.tech`) connects to your Neon databases from the following static IP addresses:

- `34.192.103.46`
- `23.22.233.166`

If [IP Allow](https://neon.com/docs/introduction/ip-allow) is enabled on your project, add these addresses to your allowlist so the MCP server can connect.

## Database diagnostics

When you ask why a branch is slow, large, or behind, the MCP server can run `inspect_database` instead of inventing catalog SQL. It exposes the same 15 read-only checks as [`neon inspect db`](https://neon.com/docs/cli/inspect): table and index sizes, unused indexes, sequential scans, long-running and stalled queries and locks, heavy and frequent statements, cache hit rate and working set, autovacuum and bloat, and replication state. The `stalled-queries` check reports active queries running longer than 30 seconds, with their waits, blockers, parallel workers, query IDs, and query text.

Pick a check with the `check` parameter (for example `table-sizes` or `unused-indexes`). The tool runs inside a read-only transaction, so it works with [`?readonly=true`](https://neon.com/docs/ai/neon-mcp-server#read-only-mode). It belongs to the `querying` category, not `observability`. Some checks need [`pg_stat_statements`](https://neon.com/docs/extensions/pg_stat_statements) or the [`neon`](https://neon.com/docs/extensions/neon) extension; the tool reports that and asks before suggesting installation.

## Available tools

Tools are grouped into categories. Use the `?category=` URL parameter to restrict which categories are active. You can pass it more than once to enable multiple categories.

| Category                          | What it enables                                                                                                                                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Project management (`projects`)   | List, create, describe, and delete projects; count projects; get project and branch consumption; list organizations                                                                                                |
| Branch management (`branches`)    | Create, reset, and delete branches; manage Postgres roles and databases                                                                                                                                            |
| Compute endpoints (`endpoints`)   | List, create, start, suspend, and restart branch computes                                                                                                                                                          |
| Snapshots (`snapshots`)           | Create, restore, and schedule snapshots                                                                                                                                                                            |
| Schema (`schema`)                 | Inspect tables and columns; compare schemas                                                                                                                                                                        |
| SQL (`querying`)                  | Execute queries and transactions; apply schema changes on a temporary branch; run the same diagnostics as `neon inspect db`                                                                                        |
| Managed Better Auth (`neon_auth`) | Provision Auth; configure branch settings (localhost access, email and password, email provider, plugins, webhooks); manage OAuth providers, the OAuth provider plugin and its clients, trusted domains, and users |
| Neon Data API (`data_api`)        | Enable, update, and disable the Data API for a branch                                                                                                                                                              |
| Observability (`observability`)   | Query function and storage logs; check AI Gateway availability                                                                                                                                                     |
| Documentation (`docs`)            | Search and read Neon docs, the API reference, guides, the PostgreSQL tutorial, the blog, and the changelog from within your assistant (no OAuth required)                                                          |
| Functions (`functions`)           | List, deploy, update, and delete Neon Functions                                                                                                                                                                    |
| Object storage (`storage`)        | Manage buckets and objects; create presigned URLs                                                                                                                                                                  |
| Realtime (`realtime`)             | Enable and disable Realtime for a branch; get and rotate its secret                                                                                                                                                |

Search and navigation tools (search across projects, fetch resource details by ID) are available by default but disabled in [project-scoped mode](https://neon.com/docs/ai/neon-mcp-server#project-scoped-mode).

Schema tools accept schema-qualified table names, such as `crm.contacts`. An unqualified name resolves against the database `search_path`, which defaults to the `public` schema.

**Note:** The `observability` tools query [Neon Functions logs](https://neon.com/docs/compute/functions/logs) and [object storage logs](https://neon.com/docs/storage/logs), which are part of the Neon backend, currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). Log querying returns results only for projects in a supported region. Database diagnostics via `inspect_database` are under `querying`, not `observability`.

## Legacy transports

### Deprecated local stdio

**Important:**

The local stdio package (`@neondatabase/mcp-server-neon`) is deprecated. Use the hosted server at `https://mcp.neon.tech/mcp`.

If your client only supports local stdio servers, put one of these in the client config so [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridges to Streamable HTTP.

**OAuth:**

```json
{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.neon.tech/mcp"]
    }
  }
}
```

**API key:**

```json
{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://mcp.neon.tech/mcp",
        "--header",
        "Authorization:${NEON_AUTH_HEADER}"
      ],
      "env": {
        "NEON_AUTH_HEADER": "Bearer <YOUR_NEON_API_KEY>"
      }
    }
  }
}
```

### Retired HTTP+SSE transport

**Important:**

The hosted Neon MCP Server uses Streamable HTTP at `https://mcp.neon.tech/mcp`. The older HTTP+SSE endpoints (`https://mcp.neon.tech/sse` and `/message`) are retired and return `410 Gone`.

If your client still points at `/sse`, change the URL to `https://mcp.neon.tech/mcp`. If your client only supports local stdio servers, bridge to Streamable HTTP with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote):

```json
{
  "mcpServers": {
    "Neon": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.neon.tech/mcp"]
    }
  }
}
```

## Troubleshooting

### Client still points at the SSE endpoint

The HTTP+SSE endpoints (`https://mcp.neon.tech/sse` and `/message`) are retired and return `410 Gone`. Point your client at `https://mcp.neon.tech/mcp` instead. See [Retired HTTP+SSE transport](https://neon.com/docs/ai/neon-mcp-server#retired-sse).

### Client doesn't support remote servers

If your client only supports local (stdio) servers, bridge to the hosted server with `mcp-remote`. See [Deprecated local stdio](https://neon.com/docs/ai/neon-mcp-server#deprecated-stdio).

### OAuth error: invalid redirect uri

When you use OAuth with the hosted server, you might see this error:

```json
{"code":"invalid_request","error":"invalid redirect uri"}
```

This typically means the cached OAuth credentials are stale. To fix it:

1. Remove the MCP authentication cache directory:
   ```bash
   rm -rf ~/.mcp-auth
   ```
2. Restart your MCP client.
3. Sign in again when the OAuth flow starts.

## Resources

- [MCP Protocol](https://modelcontextprotocol.org)
- [Neon API Reference](https://neon.com/docs/reference/api)
- [Neon API Keys](https://neon.com/docs/manage/api-keys#creating-api-keys)
- [Neon MCP server GitHub](https://github.com/neondatabase/mcp-server-neon)
- [Get started with Claude Code and Neon MCP Server](https://neon.com/guides/claude-code-mcp-neon)
- [Get started with Cursor and the Neon MCP Server](https://neon.com/guides/cursor-mcp-neon)
- [Get started with Claude Desktop and Neon MCP Server](https://neon.com/guides/neon-mcp-server)

--- [Document source](https://neon.com/docs/ai/semantic-kernel.md) ---

> Summary: Semantic Kernel is Microsoft's open-source SDK for building RAG and agentic AI workflows in .NET (C#), and this page shows how to connect it to Neon Postgres using the `Microsoft.SemanticKernel.Connectors.Postgres` NuGet package and the `pgvector` extension as a vector store. Use this page when you need to initialize a `PostgresVectorStore`, generate embeddings with Azure OpenAI, or run chat-completion queries against a Neon-backed vector index from a C# application. The guide covers the full pipeline: NpgsqlDataSourceBuilder setup, embedding generation, and kernel-based prompt invocation, with a companion .NET RAG console app on GitHub.

# Semantic Kernel

Quickly build AI RAG and Agentic workflows with Semantic Kernel and Neon

Last updated: 2026-06-05

[Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/) is an open-source SDK developed by Microsoft that enables the integration of large language models (LLMs) with traditional programming constructs. It allows developers to build AI-powered applications by combining natural language processing, planning, and memory capabilities. Semantic Kernel supports orchestration of AI workflows, plugin-based extensibility, and vector-based memory storage for retrieval-augmented generation (RAG) use cases. It is commonly used to create intelligent agents, chatbots, and automation tools that leverage LLMs like OpenAI's GPT models.

## Initialize Postgres Vector Store

Semantic Kernel supports using Neon as a vector store, using the `pgvector` extension and existing [Postgres Vector Store connector](https://learn.microsoft.com/en-us/semantic-kernel/concepts/vector-store-connectors/out-of-the-box-connectors/postgres-connector?pivots=programming-language-csharp) to access and manage data in Neon. It establishes a Neon connection, enables vector support, and initializes a vector store for AI-driven search and retrieval tasks

Here's how you can initialize Postgres Vector Store with Semantic Kernel in .NET using `Microsoft.SemanticKernel.Connectors.Postgres` NuGet package:

```csharp
// File: Program.cs

using Microsoft.SemanticKernel.Connectors.Postgres;
using Npgsql;

class Program
{
    static void Main()
    {
        var connectionString = "Host=myhost;Username=myuser;Password=mypass;Database=mydb";
        var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
        dataSourceBuilder.UseVector();
        using var dataSource = dataSourceBuilder.Build();

        var vectorStore = new PostgresVectorStore(dataSource);
        Console.WriteLine("Vector store created successfully.");
    }
}

```

## Generate Embeddings with Azure OpenAI

You can generate text embeddings using Azure OpenAI in the same .NET application.

```csharp
// File: Program.cs

using Microsoft.SemanticKernel.Connectors.Postgres;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Npgsql;
using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string connectionString = "Host=myhost;Username=myuser;Password=mypass;Database=mydb";

        // Create and configure the vector store
        var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
        dataSourceBuilder.UseVector();
        using var dataSource = dataSourceBuilder.Build();
        var vectorStore = new PostgresVectorStore(dataSource);
        Console.WriteLine("Vector store created successfully.");

        // Generate embeddings using Azure OpenAI
        var embeddingService = new AzureOpenAITextEmbeddingGenerationService(
            deploymentName: "your-deployment-name",
            endpoint: "https://api.openai.com",
            apiKey: "your-api-key"
        );

        string text = "This is an example sentence for embedding.";
        var embedding = await embeddingService.GenerateEmbeddingsAsync(new[] { text });

        Console.WriteLine($"Generated Embedding: [{string.Join(", ", embedding[0].AsReadOnlySpan().Slice(0, 5))}...]");
    }
}
```

## Chat Completions with Azure OpenAI

Here is how you can run a chat completion query with Azure OpenAI and Semantic Kernel

```csharp
// File: Program.cs

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.Postgres;
using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
using Npgsql;
using System;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        string connectionString = "Host=myhost;Username=myuser;Password=mypass;Database=mydb";

        // Step 1: Create and configure the vector store
        var dataSourceBuilder = new NpgsqlDataSourceBuilder(connectionString);
        dataSourceBuilder.UseVector();
        using var dataSource = dataSourceBuilder.Build();
        var vectorStore = new PostgresVectorStore(dataSource);
        Console.WriteLine("✅ Vector store created successfully.");

        // Step 2: Generate embeddings using Azure OpenAI
        var embeddingService = new AzureOpenAITextEmbeddingGenerationService(
            deploymentName: "your-deployment-name",
            endpoint: "https://api.openai.com",
            apiKey: "your-api-key"
        );

        string text = "This is an example sentence for embedding.";
        var embedding = await embeddingService.GenerateEmbeddingsAsync(new[] { text });

        Console.WriteLine($"✅ Generated Embedding: [{string.Join(", ", embedding[0].AsReadOnlySpan().Slice(0, 5))}...]");

        // Step 3: Perform chat completion using Azure OpenAI
        var kernel = Kernel.CreateBuilder()
            .AddAzureOpenAIChatCompletion(
                deploymentName: "your-chat-deployment-name",
                endpoint: "https://api.openai.com",
                apiKey: "your-api-key"
            ).Build();

        string userPrompt = "Explain Retrieval-Augmented Generation (RAG) in simple terms.";
        var response = await kernel.InvokePromptAsync(userPrompt);

        Console.WriteLine("✅ Chat Completion Response:");
        Console.WriteLine(response);
    }
}
```

## Examples

Explore examples and sample code for using SemanticKernel with Neon Serverless Postgres.

- [RAG .NET console app (Azure OpenAI + Semantic Kernel)](https://github.com/neondatabase-labs/neon-semantic-kernel-examples): A .NET RAG example app built with Azure OpenAI and Semantic Kernel

--- [Document source](https://neon.com/docs/auth/about.md) ---

> Summary: Managed Better Auth is a managed authentication service built on Better Auth. It stores users, sessions, and OAuth configuration in your database under the neon_auth schema, compatible with Row Level Security. This page covers how it compares to self-hosting Better Auth, basic SDK usage, use cases, example applications, availability, pricing, and migration from Stack Auth.

# About Managed Better Auth

How Neon's managed Better Auth works, when to use it, and what it costs

Last updated: 2026-10-30

Managed Better Auth is the managed authentication service in the Neon backend for apps and agents. It stores users, sessions, and auth configuration directly in your Neon database. When you branch your database, your entire auth state branches with it, so you can test real authentication workflows in preview environments.

- **Identity lives in your database.** All authentication data is stored in the `neon_auth` schema, queryable with SQL and compatible with Row Level Security (RLS) policies.
- **Zero server management.** It runs as a managed REST API service. Configure it in the Console and use the [client SDK](https://neon.com/docs/reference/javascript-sdk) or [server SDK](https://neon.com/docs/auth/reference/nextjs-server) in your app.
- **Auth that branches with your data.** Test sign-up, login, password reset, and OAuth flows in isolated branches without touching production data.

## Set up with your AI editor

The fastest way to connect your editor to Managed Better Auth is to run `npx neon@latest init` from your project root:

```bash
npx neon@latest init
```

This command configures the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server) and installs **[Agent Skills](https://neon.com/docs/ai/agent-skills)** (`neon-postgres`) in your project. Together they help you set up Managed Better Auth in two ways:

1. **Configure Managed Better Auth on your branch (MCP).** After `init`, ask your assistant to enable and configure auth in natural language. The MCP server exposes:

   - `provision_neon_auth`: Enable Managed Better Auth on a branch
   - `add_auth_oauth_provider`, `add_auth_trusted_domain`, `update_auth_config`: Change Auth settings
   - `get_neon_auth_config`: Read the current configuration (secrets redacted)

   See [Available tools](https://neon.com/docs/ai/neon-mcp-server#available-tools) (`neon_auth`) for the full set.

2. **Add Managed Better Auth to your application (Agent Skills).** Skills teach your assistant how to install the SDK, environment variables, and routes for your framework. Use the quick start guides on this page, or ask your assistant directly.

**Example prompt:**

```text
Set up Managed Better Auth for my project. Enable Google OAuth and email/password sign-in,
and set the application name to "My App".
```

You can also enable Managed Better Auth in the [Neon Console](https://console.neon.tech) (Project → Branch → Auth) and configure settings manually.

## Built on Better Auth

Managed Better Auth is powered by [Better Auth](https://www.better-auth.com/), which means you get familiar APIs. You can use Better Auth UI components or call auth methods directly to build your own UI.

Managed Better Auth runs Better Auth version **1.7.12**. Use `@neon/auth` **0.8.1 or later**, which uses a Better Auth 1.7.12 client. Apps on older `@neondatabase/auth` versions keep working, so you don't need to upgrade. If you use your own Better Auth client, use Better Auth 1.7 or later.

### When to use Managed Better Auth vs. self-hosting Better Auth

Managed Better Auth is a managed authentication service built into Lakebase Postgres on Neon:

- **Branch-aware authentication**: Every Neon branch gets its own isolated auth environment, so you can test authentication features without affecting your production branch.
- **Built-in Data API integration**: JWT token validation for the Data API has native support for Managed Better Auth.
- **No infrastructure to manage**: Managed Better Auth is deployed in the same region as your database, reducing latency without requiring you to run auth infrastructure.
- **Shared OAuth credentials for testing**: Get started quickly with out-of-the-box Google OAuth credentials, eliminating the setup complexity for testing and prototyping.

Self-hosting Better Auth makes sense if you need:

- Flexibility in auth configuration: custom plugins, hooks, and options not yet supported by Managed Better Auth.
- Full control over your auth code and the ability to run it inside your own infrastructure.

For more details on the SDK differences between `@neon/auth` and `better-auth/client`, see [Why use @neon/auth over better-auth/client](https://github.com/neondatabase/neon-js/blob/main/packages/auth/neon-auth_vs_better-auth.md).

As Managed Better Auth evolves, more Better Auth integrations and features will be added. Check the [roadmap](https://neon.com/docs/auth/roadmap) to see what's currently supported and what's coming next.

## Basic usage

Enable Auth in the Neon Console, from the terminal with [`neon neon-auth enable`](https://neon.com/docs/cli/neon-auth#enable) or declaratively with [`neon config add auth`](https://neon.com/docs/cli/config#add), or [with your AI editor](https://neon.com/docs/auth/about#set-up-with-your-ai-editor), then add authentication to your app.

**For Next.js (server-side):**

See the [Next.js Server SDK reference](https://neon.com/docs/auth/reference/nextjs-server) for complete API documentation.

```typescript filename="lib/auth/server.ts"
import { createNeonAuth } from '@neon/auth/next/server';

export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: { secret: process.env.NEON_AUTH_COOKIE_SECRET! },
});
```

```typescript filename="app/api/auth/[...path]/route.ts"
import { auth } from '@/lib/auth/server';

export const { GET, POST, PUT, PATCH, DELETE } = auth.handler();
```

**For React/Vite (client-side):**

See the [Client SDK reference](https://neon.com/docs/reference/javascript-sdk) for complete API documentation. If you want one client for both Managed Better Auth and the Data API, initialize `createClient()` from a single Neon URL as shown in [`createClient()` initialization](https://neon.com/docs/reference/javascript-sdk#initializing).

```typescript filename="src/auth.ts"
import { createAuthClient } from '@neon/auth';
import { BetterAuthReactAdapter } from '@neon/auth/react/adapters';

// credentials: 'include' sends the session cookie on cross-origin requests.
export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL, {
  adapter: BetterAuthReactAdapter({ fetchOptions: { credentials: 'include' } }),
});
```

For pre-built sign-in and sign-up forms, add [Better Auth UI](https://neon.com/docs/auth/reference/ui-components) with `npx shadcn@latest add @better-auth-ui/auth` and pass the client to its `AuthProvider`:

```tsx filename="src/App.tsx"
import { getSafeRedirectTo } from '@better-auth-ui/core';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { AuthProvider } from '@/components/auth/auth-provider';
import { Auth } from '@/components/auth/auth';
import { Toaster } from '@/components/ui/sonner';
import { authClient } from './auth';

const queryClient = new QueryClient();

export default function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider
        authClient={authClient}
        emailAndPassword={{ requireEmailVerification: false }} // match your branch's setting
        navigate={({ to }) => {
          const path = getSafeRedirectTo(to, window.location.origin);
          window.location.assign(path.startsWith('//') ? '/' : path);
        }}
        Link={({ to: _to, ...props }) => <a {...props} />}
      >
        <Auth view="signIn" />
        <Toaster />
      </AuthProvider>
    </QueryClientProvider>
  );
}
```

`navigate` checks the target because the components pass it the URL's `?redirectTo=` value after sign-in; see [Validate redirect targets](https://neon.com/docs/auth/reference/ui-components#validate-redirect-targets).

## Use cases

- **Production authentication**  
  Use Managed Better Auth as the identity system for your app. Store users, sessions, and OAuth configuration directly in Postgres, and pair with RLS for secure, database-centric access control.

- **Preview environments**  
  Test full authentication flows in Vercel previews with real users and sessions

- **Multi-tenant SaaS**  
  Test complex org and role hierarchies safely in isolated branches

- **CI/CD workflows**  
  Run end-to-end auth tests without touching production. The [Neon Create Branch GitHub Action](https://github.com/marketplace/actions/neon-create-branch-github-action) supports retrieving branch-specific auth URLs for testing authentication flows in GitHub Actions workflows.

- **Development workflows**  
  Spin up complete environments instantly with database and auth together

See [Branching authentication](https://neon.com/docs/auth/branching-authentication) for details on how auth branches with your database.

## Example applications

Beyond the quick starts on this site, the [neondatabase/neon-js](https://github.com/neondatabase/neon-js) monorepo ships **more runnable Managed Better Auth and `neon-js` samples** under [`examples/`](https://github.com/neondatabase/neon-js/tree/main/examples), including plugin demos (see [Plugins](https://neon.com/docs/auth/guides/plugins#example-applications)), Next.js and React apps, cross-subdomain setups, alternative UI stacks, and Data API patterns. Each folder includes its own README (many workflows use **bun** from the repository root). Browse there when you want a full project to clone next to the guides here.

## Availability

Managed Better Auth is currently available for AWS regions only. Azure support is not yet available.

Managed Better Auth does not currently support projects with [IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow) or [Private Networking](https://neon.com/docs/guides/neon-private-networking) enabled.

## Pricing

Managed Better Auth is included in all Neon plans based on Monthly Active Users (MAU):

- **Free**: Up to 60,000 MAU per project
- **Launch**: Up to 1M MAU per project
- **Scale**: Up to 1M MAU per project

An MAU (Monthly Active User) is a unique user who authenticates at least once during a monthly billing period. If you need more than 1M MAU, request an increase in the [console feedback form](https://console.neon.tech/app/settings?modal=feedback\&modalparams=%22Neon%20auth%20limit%20increase%22).

See [Neon plans](https://neon.com/docs/introduction/plans#auth) for more details.

## Migration from Stack Auth

If you're using legacy Neon Auth (Stack Auth), your version will continue to work. When you're ready to migrate to Managed Better Auth, see our [migration guide](https://neon.com/docs/auth/migrate/from-legacy-auth).

--- [Document source](https://neon.com/docs/auth/authentication-flow.md) ---

> Summary: Managed Better Auth authentication flow traces every step from SDK call to HTTP-only session cookie, JWT issuance, and writes to the neon_auth schema, covering email sign-in, sign-up, and OAuth providers such as Google and GitHub. Use this page to understand what happens under the hood during login, debug session or token problems, or wire auth.uid() into Row-Level Security policies via the Data API. All auth state lands directly in your Neon database with no sync delay, and each branch holds isolated auth data.

# Authentication flow

Understanding the complete sign-in and sign-up process

Last updated: 2026-11-05

This guide explains the authentication flow: how sign-in works from SDK call to session creation.

**Note:** Anyone can sign up for your application by default. Support for restricted signups is coming soon. Until then, consider adding a verification step by enabling [email verification](https://neon.com/docs/auth/guides/email-verification) via verification link or verification code.

## Architecture overview

Managed Better Auth is a managed REST API service built on Better Auth that connects directly to your Neon database. You use the SDK in your application and configure settings in the Console; no servers to manage.

```
Your App (SDK)
    ↓ HTTP requests
Managed Better Auth Service (REST API)
    ↓ connects to database
Your Neon Database (neon_auth schema)
```

All authentication data (users, sessions, OAuth configurations) lives in your database's `neon_auth` schema. You can query these tables directly with SQL for debugging, analytics, or custom logic.

## Complete sign-in flow

Here's what happens when a user signs in, from your code to the database:

## User signs in

Your application calls the SDK's sign-in method:

```typescript
const { data, error } = await client.auth.signIn.email({
  email: 'user@example.com',
  password: 'password',
});
```

The SDK posts to `{NEON_AUTH_BASE_URL}/sign-in/email`. The Auth service validates credentials against `neon_auth.account`, creates a session in `neon_auth.session`, and returns the session cookie with user data.

**Response you receive:**

```typescript
{
  data: {
    session: {
      access_token: "eyJhbGc...",  // JWT token
      expires_at: 1763848395,
      // ... other session fields
    },
    user: {
      id: "dc42fa70-09a7-4038-a3bb-f61dda854910",
      email: "user@example.com",
      emailVerified: true,
      // ... other user fields
    }
  }
}
```

## Session cookie is set

The Auth service sets an HTTP-only cookie (`__Secure-neon-auth.session_token`) in your browser. This cookie:

- Contains an opaque session token (not a JWT)
- Is automatically sent with every request to the Auth API
- Is secure (HTTPS only, HttpOnly, SameSite=None)
- Is managed entirely by the SDK; you never touch it

**Where to see it:** Open DevTools → Application → Cookies → look for `__Secure-neon-auth.session_token`

## JWT token is retrieved

The SDK automatically retrieves a JWT token and stores it in `session.access_token`. You don't need to call the `/token` endpoint separately; the SDK handles this behind the scenes.

**What's in the JWT:**

```json
{
  "sub": "dc42fa70-09a7-4038-a3bb-f61dda854910", // User ID
  "email": "user@example.com",
  "role": "authenticated",
  "exp": 1763848395, // Expiration timestamp
  "iat": 1763847495 // Issued at timestamp
}
```

The `sub` claim contains the user ID from `neon_auth.user.id`. This is what Row Level Security policies use to identify the current user.

## JWT is used for database queries

When you query your database via Data API, the SDK automatically includes the JWT in the `Authorization` header:

```typescript
// JWT is automatically included in Authorization header
const { data } = await client.from('posts').select('*');
```

**What happens:**

1. SDK gets JWT from `session.access_token`
2. Adds `Authorization: Bearer <jwt-token>` header
3. Data API validates JWT signature using JWKS public keys
4. Data API extracts user ID from JWT and makes it available to RLS policies
5. Your query runs with the authenticated user context

## Sign-up flow

The sign-up flow creates a new user:

```typescript
const { data, error } = await client.auth.signUp.email({
  email: 'newuser@example.com',
  password: 'securepassword',
  name: 'New User',
});
```

The SDK posts to `{NEON_AUTH_BASE_URL}/sign-up/email`. The Auth service creates a new row in `neon_auth.user`, stores hashed credentials in `neon_auth.account`, and returns user data. If email verification is required, it creates a verification token in `neon_auth.verification` and may delay session creation until verification.

**Note:** By default, anyone can sign up for your application. To add an additional verification layer, enable email verification (see [Email Verification](https://neon.com/docs/auth/guides/email-verification)). Built-in signup restrictions are coming soon.

## OAuth flow

OAuth authentication (Google, GitHub, Vercel, Microsoft, Apple, etc.):

```typescript
await client.auth.signIn.social({
  provider: 'google',
  callbackURL: 'http://localhost:3000/auth/callback',
});
```

The SDK redirects to the OAuth provider. After the user authenticates, the provider redirects back with an authorization code. The SDK exchanges the code for an access token, then the Auth service creates or updates the user in `neon_auth.user`, stores OAuth tokens in `neon_auth.account`, and creates a session.

## Database as source of truth

Managed Better Auth stores all data in your database's `neon_auth` schema:

- Changes are immediate (no sync delays)
- Query auth data directly with SQL
- Each branch has isolated auth data
- You own your data

```sql
SELECT id, email, "emailVerified", "createdAt"
FROM neon_auth.user
ORDER BY "createdAt" DESC;
```

## Data API integration

When you enable the [Data API](https://neon.com/docs/data-api/get-started), JWT tokens from Managed Better Auth are validated automatically. Two helper functions make the user ID available to RLS policies. Use the one that matches your column type:

- `auth.user_id()`: returns `sub` as `text`
- `auth.uid()`: returns `sub` as `uuid` (returns `NULL` if `sub` isn't a valid UUID)

The Data API also works with [other authentication providers](https://neon.com/docs/data-api/custom-authentication-providers) that issue JWTs, such as Auth0, Clerk, and Firebase.

**Example RLS policy:**

```sql
CREATE POLICY "Users can view own posts"
ON posts FOR SELECT TO authenticated
USING (user_id = auth.user_id());
```

**Learn more about securing your data:**

- [Row-Level Security with Neon](https://neon.com/docs/guides/row-level-security)
- [Simplify RLS with Drizzle](https://neon.com/docs/guides/rls-drizzle)

## What's next

- [Branching Authentication](https://neon.com/docs/auth/branching-authentication): How auth works with database branches
- [Row Level Security](https://neon.com/docs/guides/row-level-security): Secure your data with RLS policies

--- [Document source](https://neon.com/docs/auth/branching-authentication.md) ---

> Summary: Managed Better Auth stores users, sessions, and configuration in the database's neon_auth schema, so authentication data is automatically cloned when you create a branch, giving each branch its own fully isolated auth environment. Use this page when you need to safely test OAuth providers, RBAC policy changes, password reset flows, or full application refactors without touching production users. Each branch gets a unique Auth API URL, and sessions and tokens do not cross between branches.

# Branching authentication

How authentication works with Neon database branches

Last updated: 2026-09-16

Authentication is often one of the hardest parts of the application stack to test. In traditional architectures, identity data lives in a separate third-party service, while your business data lives in your database. This separation makes it difficult to create realistic staging environments or test changes to permissions without affecting production users.

One of Managed Better Auth's unique features is native support for [database branching](https://neon.com/docs/introduction/branching). Because authentication data (users, sessions, and configuration) lives directly in your database's `neon_auth` schema, it is cloned along with your business data when you create a branch.

This gives each branch its own isolated authentication environment, enabling safe testing of permission changes, new OAuth providers, or full application refactors.

**Info:** Managed Better Auth branching is also supported via API. See the [Managed Better Auth API reference](https://neon.com/docs/reference/api/auth/get-neon-auth) for a full set of REST API endpoints.

## How it works

When you create a [database branch](https://neon.com/docs/introduction/branching), you get an exact copy of all authentication data from the parent branch at that point in time:

```
Production (main)                Preview Branch (preview-pr-123)
├── Users                   →    ├── Users (copied at branch time)
├── Sessions                →    ├── Sessions (copied, but will expire)
├── Configuration           →    ├── Configuration (independent copy)
├── OAuth providers         →    ├── OAuth providers (same credentials)
├── JWKS keys               →    ├── JWKS keys (copied)
└── Organizations           →    └── Organizations (copied)
```

After branching, the environments operate independently:

1. **Data Isolation:** Changes in one branch don't affect others. Creating a user in a preview branch does not create them in production.
2. **Config Isolation:** You can modify auth settings (for example, email templates, token settings) in the branch without affecting the parent.
3. **Endpoint Isolation:** Each branch gets a unique Auth API URL. Tokens issued in one branch are not valid in another.

```
Production Branch              Preview Branch
├── New user: alice@co.com     ├── New user: test@co.com
├── Alice's sessions           ├── Test user's sessions
├── Config: email with links   ├── Config: testing email codes
└── ep-abc123.neonauth...      └── ep-xyz789.neonauth...
    (production endpoint)          (preview endpoint)
```

**Note:** Managed Better Auth uses your branch's default database, typically `neondb`, when you don't specify a database. You can select another database in the same branch when you enable Auth through the API by setting `database_name`. Managed Better Auth requires a read-write endpoint.

## Session management details

Sessions do not transfer between branches. If you sign in to your production app and then visit your staging environment:

1. The session _record_ exists in the staging database (if it was created before the branch happened).
2. However, your browser's _cookie_ is scoped to the production domain.
3. Therefore, you will need to sign in again on the staging environment.

This isolation is intentional and prevents security issues like sessions accidentally working across environments or test actions affecting production users.

## Common Use Cases

This branch isolation supports several useful workflows for developers, QA teams, and product managers.

### 1. Developer isolation

In a team environment, developers often step on each other's toes when sharing a single development database. With branching, each developer can have their own instance:

```bash filename="Terminal"
# Alice and Bob create their own branches
neon branches create --name dev-alice
neon branches create --name dev-bob
```

- **Alice** works on a "Delete Account" flow. She can delete users and test the full flow without worrying about affecting others.
- **Bob** works on the "User Dashboard". His user list remains intact, even though Alice is deleting users in her environment.

Because Managed Better Auth is part of the database, Alice and Bob don't need to set up separate auth providers or mock data. They can work in parallel without conflicts.

### 2. Testing auth configuration safely

Say you want to add Google OAuth to your production app, but you're not sure if your configuration will work. Instead of testing directly in production, create a branch:

```bash filename="Terminal"
# Create test branch from production
neon branches create --name test-google-oauth
```

```env filename=".env.local"
# Point your local app to the test branch's Auth URL
VITE_NEON_AUTH_URL=https://ep-test-google-oauth.neonauth.region.aws.neon.tech/neondb/auth
```

Now configure Google OAuth in the test branch's Console and verify the sign-in flow works locally. Your production app and users are completely unaffected. Once you confirm it works, apply the same OAuth settings to your production branch.

The same approach works for any auth changes: password reset flows, email verification settings, or testing with anonymized production data.

### 3. Preview environments for pull requests

When building full-stack applications, you often deploy "Preview Deployments" (using Vercel, Netlify, etc.) for every Pull Request. Without Auth Branching, these previews usually share a single "Staging" auth tenant. This leads to data conflicts where one developer deletes a user that another developer was testing with.

**The workflow:**

You can automate this using GitHub Actions. When a PR is opened:

1. Create a Neon branch.
2. Deploy your frontend/backend to a preview URL.
3. Inject the **Branch Auth URL** into the preview deployment's environment variables.
4. Set the Redirect URLs in the branch's Auth configuration to point to the preview URL using the [Neon API](https://neon.com/docs/reference/api/auth/add-branch-neon-auth-trusted-domain).

Because the branch contains a snapshot of production data, the preview environment is fully functional immediately. You can log in with real test accounts that exist in production, but any actions taken (changing passwords, updating profiles) happen in isolation.

**Tip:** See the [GitHub Actions guide](https://neon.com/docs/guides/branching-github-actions) for instructions on how to automate branch creation for preview environments.

### 4. Testing multi-tenant & RBAC hierarchies

For applications with complex Role-Based Access Control (RBAC) or multi-tenant architectures, testing permission changes can be risky. A misconfiguration could lock out users or expose sensitive data.

**The scenario:** You are refactoring your RLS policies to allow "Managers" to view "Department" data, but not modify it.

**The workflow:**

1. Create a branch `refactor-rbac`.
2. This branch contains your real production users and their existing role assignments.
3. Modify your RLS policies in the branch.
4. You can log in as a "Manager" user and verify they can only view the appropriate data.
5. If the policy is incorrect and you accidentally expose data or lock a user out, **it only affects the branch**. Production users are never impacted.

### 5. Major refactors and "v2" betas

When rebuilding your application from scratch or launching a major "v2" update, you often need to validate the new system with real user data before the official switch-over. Traditionally, this required complex data dumps or asking users to re-register on a beta site.

With Managed Better Auth, you can spin up a complete parallel environment for your new version instantly.

**The workflow:**

1. **Branch production:** Create a branch named `v2-beta` from your main production database. This clones your entire application state, including the `neon_auth` schema containing all user identities and hashed passwords.
2. **Deploy v2:** Deploy your new application code (for example, to `beta.myapp.com`) and point it to the `v2-beta` branch's Auth URL.
3. **Seamless login:** Existing users can visit your new v2 site and **log in immediately using their existing credentials**. They do not need to sign up again or reset their passwords.

This allows you to test radical architectural changes such as renaming database columns, changing table structures, or modifying authentication flows in a live environment. Your v1 application remains completely unaffected, while your v2 beta feels like a production-ready extension of your platform.

**Note: Data separation**

Remember that once branched, the environments are separate. If a user changes their password on the v2 site, it will not change on the v1 site, and vice versa. This makes this workflow ideal for "Public Betas" or staging environments prior to a final cutover.

### 6. AI agents and ephemeral sandboxes

AI Agents, particularly those designed for coding or QA, require safe, isolated environments to generate code, run migrations, and validate features. Traditionally, giving an agent access to a full authentication stack was complex - you had to mock auth tokens or risk exposing production user pools.

With Neon, an agent can programmatically provision its own "sandbox." Because Managed Better Auth moves with the data, this branch instantly creates a working Authentication service isolated from production, complete with its own user tables, sessions, and configuration. **The branch provides a full production-like environment without touching real user data.**

**The workflow:**

1. **Provision:** The Agent uses the Neon API to create a new database branch. It instantly receives a dedicated Auth URL for that specific environment.
2. **Interact:** The Agent uses tools like Playwright or Puppeteer to interact with the application, registering new users and performing real login flows against the branch's auth service.
3. **Validate:** The Agent runs a test suite to verify that the code it generated works correctly with the database schema, RLS policies, and authentication rules.
4. **Teardown:** Once the task is complete, the Agent deletes the branch, cleaning up all data and auth state.

Agents can spin up full-stack environments (Database + Auth + Compute) in seconds and run autonomous test loops against real user-facing security flows, with no manual setup.

**Important:** An AI agent cannot log in as a real production user in a branch. Although user records are copied, valid session cookies are domain-scoped and remain with the user's browser; they are not sent to the branch URL. Unless the agent explicitly knows a user's password, it must either perform a sign-up flow or use existing test credentials to log in.

To streamline this, consider maintaining specific test users with known credentials in your production database; these records are automatically cloned to child branches during creation, allowing agents to log in immediately without needing to perform a sign-up step.

## What's Next

- [Database Branching](https://neon.com/docs/introduction/branching): Learn about database branching fundamentals
- [Branching with CLI](https://neon.com/docs/guides/branching-neon-cli): Create and manage branches with CLI
- [Branching with GitHub Actions](https://neon.com/docs/guides/branching-github-actions): Automate branching in CI/CD
- [Row-Level Security](https://neon.com/docs/guides/row-level-security): Secure data with RLS

--- [Document source](https://neon.com/docs/auth/guides/configure-domains.md) ---

> Summary: Managed Better Auth's trusted domain allowlist restricts OAuth and email verification redirects to domains you explicitly approve, blocking unauthorized redirects. Add exact production origins (https://myapp.com) or wildcard patterns (https://*.preview.vercel.app) in Console > Auth > Configuration > Domains. Localhost ports are pre-approved and need no entry.

# Configure trusted domains

Add your application domains to enable secure authentication redirects

Last updated: 2026-11-05

Add your application domains to Managed Better Auth's allowlist to enable OAuth and email verification redirects in production.

## Why domains are required

Managed Better Auth only redirects to domains in your allowlist. This prevents phishing attacks and unauthorized redirects by ensuring users are only sent to your legitimate application URLs.

Without adding your production domain, OAuth sign-in and verification links will fail when users try to access your application.

The same list decides which `Origin` headers the Auth API accepts, so sign-in and sign-up requests from an origin that isn't on it fail with `INVALID_ORIGIN`. See [Origin errors](https://neon.com/docs/auth/troubleshooting#origin-errors).

## Add a domain

**Console**

1. Go to **Console → Auth → Configuration → Domains**
2. Enter your domain with protocol: `https://myapp.com`
3. Click **Add domain**

Repeat for each domain where your app runs.

**CLI**

Add a domain with [`neon neon-auth domain add`](https://neon.com/docs/cli/neon-auth#domain-add):

```bash
neon neon-auth domain add https://myapp.com
```

Use `neon neon-auth domain list` and `neon neon-auth domain delete` to view and remove entries.

**API**

Send a `POST` request to the [add trusted domain](https://neon.com/docs/reference/api/auth/add-branch-neon-auth-trusted-domain) endpoint. Replace `{project_id}` and `{branch_id}` with your project and branch IDs.

```bash
curl -X POST 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/domains' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"domain": "https://myapp.com", "auth_provider": "better_auth"}'
```

Use [`GET`](https://neon.com/docs/reference/api/auth/list-branch-neon-auth-trusted-domains) on the same path to list domains, and [`DELETE`](https://neon.com/docs/reference/api/auth/delete-branch-neon-auth-trusted-domain) to remove them. See [Manage Managed Better Auth via the API](https://neon.com/docs/auth/guides/manage-auth-api#related-auth-endpoints) for the full set of auth endpoints.

**Note:** Include the protocol (`https://`) and omit trailing slashes. For example: `https://myapp.com` not `https://myapp.com/`

## Localhost is pre-configured

Development domains are automatically allowed, so you don't need to add them:

- `http://localhost:3000`
- `http://localhost:5173`
- Any `localhost` port

## Production domains

Add all domains where users access your application:

- `https://myapp.com`
- `https://www.myapp.com` (if you support www subdomain)
- `https://app.myapp.com` (if using a subdomain)

## Wildcard domains for previews

For preview environments with dynamic hostnames (for example Vercel preview deployments), you can add a **wildcard trusted domain** such as `https://*.my-app-preview.vercel.app`. One entry can match every preview under that pattern instead of adding hosts one by one.

Use the same rules as fixed domains: include `https://` (or `http://` where appropriate) and omit trailing slashes after the pattern.

**Note:** Wildcard patterns apply to the hostname segment you replace with `*`. Production apex domains (for example `https://myapp.com`) are usually still added as exact entries unless your wildcard covers them.

## Common issues

**Redirect blocked after OAuth sign-in:**

- Verify the domain is in your allowlist
- Ensure you included `https://` (not `http://` for production)
- Check spelling matches exactly (including www vs non-www)

**Verification link doesn't redirect:**

- Verification links use the same domain allowlist
- Add the domain where users should land after clicking the verification link

## Next steps

- [Production checklist](https://neon.com/docs/auth/production-checklist) - Complete setup for launch

--- [Document source](https://neon.com/docs/auth/guides/customize-emails.md) ---

> Summary: Managed Better Auth email customization lets you intercept OTP code and magic link delivery events via webhooks and send fully branded emails through your own provider (Resend, SendGrid, Postmark, or any SMTP service) instead of Neon's default shared-branded emails. Use this page when you need custom sender addresses, HTML templates, multi-language support, or your own branding for sign-in, email-verification, and password-reset emails. Dashboard-based email templates are not yet available; webhook-based delivery is the current customization path.

# Customize emails

Custom branding, content, and delivery for Managed Better Auth emails

Last updated: 2026-09-16

Managed Better Auth sends verification codes, magic links, and password reset emails using its built-in email provider. By default, emails use shared Neon branding and your Neon project name as the main header. To make emails recognizable to users, update the Application Name in your [Auth settings](https://neon.com/docs/auth/production-checklist#application-name) to match your app's public-facing name.

For deeper customization, use webhooks to intercept email events and send fully branded emails through your preferred provider. Dashboard-based email templates aren't available yet, but they're planned for a future release. If you only need a custom sender address without changing the email content, you can configure a custom SMTP provider instead (see the [Auth production checklist](https://neon.com/docs/auth/production-checklist#email-provider)).

## How it works

Managed Better Auth fires two events when it needs to send an email to a user:

| Event             | Triggers when                                      | Without webhook                           |
| ----------------- | -------------------------------------------------- | ----------------------------------------- |
| `send.otp`        | A verification code needs delivery                 | Neon sends the code via its default email |
| `send.magic_link` | A magic link or password reset link needs delivery | Neon sends the link via its default email |

When you subscribe to either event, Managed Better Auth **skips its default email** and calls your webhook handler instead. Your handler receives the code or link in the payload and is responsible for sending it through Resend, SendGrid, Postmark, or any email provider you choose.

See the [Webhooks reference](https://neon.com/docs/auth/guides/webhooks) for configuration, payload structure, signature verification, and retry behavior.

## What you can customize

Using webhooks, you can customize every aspect of the email experience:

- **Sender identity:** Use your own domain and sender name instead of `auth@mail.myneon.app`
- **App name and branding:** Replace Neon's default branding with your app's logo, colors, and name
- **Subject line and body:** Write custom HTML templates with your own copy
- **Verification links:** Wrap the link from the `send.magic_link` payload in your branded email template, or build a custom redirect URL using the raw `token`
- **Multi-language support:** Detect the user's locale and deliver emails in their language
- **Delivery channel:** Send codes via email, SMS (with the [Phone Number plugin](https://neon.com/docs/auth/guides/plugins/phone-number)), or both

## Event payloads

When your webhook receives a `send.otp` or `send.magic_link` event, the payload includes the user's email and name, the OTP code or magic link URL, the type of email being sent, and the expiration time.

### `send.otp`

Your handler receives a 6-digit OTP code, the OTP type (`sign-in`, `email-verification`, or `forget-password`), and the user's email. Send it through your email provider.

```json
{
  "event_id": "xxx-yyy-zzz",
  "event_type": "send.otp",
  "timestamp": "20xx-xx-xxTxx:xx:xx.xxxZ",
  "context": {
    "endpoint_id": "ep-xxx",
    "project_name": "Your App Name"
  },
  "user": {
    "name": "User Name",
    "email": "user@email.com",
    "image": null,
    "role": "user",
    "banned": false,
    "id": "user-id",
    "email_verified": true,
    "created_at": "20xx-xx-xxTxx:xx:xx.xxxZ",
    "updated_at": "20xx-xx-xxTxx:xx:xx.xxxZ",
    "ban_reason": null,
    "ban_expires": null
  },
  "event_data": {
    "otp_code": "123456",
    "otp_type": "sign-in",
    "expires_at": "20xx-xx-xxTxx:xx:xx.xxxZ",
    "ip_address": "IP_ADDRESS_OF_USER",
    "user_agent": "USER_AGENT_OF_USER"
  }
}
```

### `send.magic_link`

Your handler receives a full verification URL and a raw token. The `link_type` is `sign-in`, `email-verification`, or `forget-password`. Wrap the link in your branded email template.

```json
{
  "event_id": "xxx-yyy-zzz",
  "event_type": "send.magic_link",
  "timestamp": "20xx-xx-xxTxx:xx:xx.xxxZ",
  "context": {
    "endpoint_id": "ep-xxx",
    "project_name": "Your App Name"
  },
  "user": {
    "email": "user@email.com"
  },
  "event_data": {
    "link_type": "sign-in",
    "link_url": "https://magic-link-url",
    "token": "raw-token-value",
    "expires_at": "20xx-xx-xxTxx:xx:xx.xxxZ",
    "ip_address": "IP_ADDRESS_OF_USER",
    "user_agent": "USER_AGENT_OF_USER"
  }
}
```

## Example handler

Before your handler can receive events, you must register its endpoint. Follow the [Webhooks guide](https://neon.com/docs/auth/guides/webhooks) to configure your webhook URL and subscribe to the `send.otp` and `send.magic_link` events.

Here's an example Next.js API route that verifies the webhook signature, handles the `send.otp` and `send.magic_link` events, and sends emails through Resend.

```ts
import crypto from 'node:crypto';
import { NextRequest, NextResponse } from 'next/server';
import { Resend } from 'resend';

const resend = new Resend(process.env.RESEND_API_KEY);

async function verifyWebhook(rawBody: string, headers: Headers) {
  const signature = headers.get('x-neon-signature');
  const kid = headers.get('x-neon-signature-kid');
  const timestamp = headers.get('x-neon-timestamp');

  if (!signature || !kid || !timestamp) {
    throw new Error('Missing required Neon webhook headers');
  }

  // 1. Fetch JWKS and find the matching key
  const res = await fetch(`${process.env.NEON_AUTH_BASE_URL}/.well-known/jwks.json`);
  const jwks = await res.json();
  const jwk = jwks.keys.find((k: { kid: string }) => k.kid === kid);
  if (!jwk) throw new Error(`Key ${kid} not found in JWKS`);

  // 2. Import the Ed25519 public key
  const publicKey = crypto.createPublicKey({ key: jwk, format: 'jwk' });

  // 3. Parse detached JWS (header..signature)
  const [headerB64, emptyPayload, signatureB64] = signature.split('.');
  if (emptyPayload !== '') throw new Error('Expected detached JWS format');

  // 4. Reconstruct signing input (standard JWS, double base64url encoding)
  const payloadB64 = Buffer.from(rawBody, 'utf8').toString('base64url');
  const signaturePayload = `${timestamp}.${payloadB64}`;
  const signaturePayloadB64 = Buffer.from(signaturePayload, 'utf8').toString('base64url');
  const signingInput = `${headerB64}.${signaturePayloadB64}`;

  // 5. Verify Ed25519 signature
  const isValid = crypto.verify(
    null,
    Buffer.from(signingInput),
    publicKey,
    Buffer.from(signatureB64, 'base64url')
  );

  if (!isValid) throw new Error('Invalid webhook signature');

  // 6. Check timestamp freshness (recommended)
  const ageMs = Date.now() - parseInt(timestamp, 10);
  if (ageMs > 5 * 60 * 1000) throw new Error('Webhook timestamp too old');

  return JSON.parse(rawBody);
}

export async function POST(request: NextRequest) {
  const rawBody = await request.text();
  const payload = await verifyWebhook(rawBody, request.headers);
  const { event_type, event_data, user, context } = payload;

  const appName = context.project_name || 'My App';

  if (event_type === 'send.otp') {
    await resend.emails.send({
      from: 'My App <auth@myapp.com>',
      to: user.email,
      subject: 'Your verification code',
      html: `<h1>Welcome to ${appName}</h1><p>Your code: <strong>${event_data.otp_code}</strong></p>`,
    });
  }

  if (event_type === 'send.magic_link') {
    await resend.emails.send({
      from: 'My App <auth@myapp.com>',
      to: user.email,
      subject: 'Your sign-in link',
      html: `<h1>Welcome to ${appName}</h1><p><a href="${event_data.link_url}">Sign in</a></p>`,
    });
  }

  return NextResponse.json({ success: true });
}
```

You can customize your emails to reflect your brand by adding your logo and using your brand colors in the HTML templates.

--- [Document source](https://neon.com/docs/auth/guides/email-verification.md) ---

> Summary: Managed Better Auth email verification confirms that users own the email address they register with, using either a numeric OTP code (works with shared or custom email providers) or a click-through verification link (requires a custom email provider). Both methods expire after 15 minutes and can be resent; verification can be configured as required or optional in the Neon Console, controlling whether unverified users can sign in.

# Email verification

Verify user email addresses during sign-up or account creation

Last updated: 2026-11-05

Email verification ensures users own the email addresses they register with. The application name shown in these emails is configurable per branch. See [Application name](https://neon.com/docs/auth/production-checklist#application-name).

Managed Better Auth supports two verification methods:

- **Verification codes** (users enter a numeric code from their email) - works with shared or custom email providers
- **Verification links** (users click a link in their email) - requires a custom email provider

**Note:** Verification links require a [custom email provider](https://neon.com/docs/auth/production-checklist#email-provider). If you're using the shared email provider, use verification codes instead.

## Enable email verification

**Console**

In your project's **Settings** → **Better Auth** page, enable **Sign-up with Email** and **Verify at Sign-up**. Choose your verification method.

![Email verification settings in Neon Console](https://neon.com/docs/auth/email-verification-settings.png)

**CLI**

Enable email and password authentication with verification required using [`neon neon-auth config email-password update`](https://neon.com/docs/cli/neon-auth#config-email-password-update):

```bash
neon neon-auth config email-password update --enabled --require-email-verification
```

**API**

Update the configuration with the [Update email and password configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-email-and-password-config) endpoint. Replace `{project_id}` and `{branch_id}` with your project and branch IDs:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/email_and_password' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "enabled": true,
  "require_email_verification": true
}'
```

## Verification links

Verification links require a custom email provider. See [Email provider configuration](https://neon.com/docs/auth/production-checklist#email-provider) to set this up.

When a user clicks the verification link in their email, the Managed Better Auth server handles verification and redirects them back to your application. Your app checks for the new session and shows the appropriate UI.

### 1. Check session on mount

Add a session check when your component mounts to detect when a user returns from clicking the verification link:

```jsx filename="src/App.jsx" {9-14}
import { useEffect, useState } from 'react';
import { authClient } from './auth';

export default function App() {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    authClient.getSession().then(({ data }) => {
      if (data?.session) {
        setUser(data.session.user);
      }
      setLoading(false);
    });
  }, []);
}
```

### 2. Handle sign-up with verification

After calling `signUp.email()`, check if verification is required and show a message:

```jsx {16-18} filename="src/App.jsx"
const handleSignUp = async (e) => {
  e.preventDefault();
  setMessage('');

  try {
    const { data, error } = await authClient.signUp.email({
      email,
      password,
      name: name || email.split('@')[0] || 'User',
    });

    if (error) throw error;

    // Check if email verification is required
    if (data?.user && !data.user.emailVerified) {
      setMessage('Check your email for a verification link!');
    } else {
      setMessage('Account created! Please sign in.');
    }
  } catch (error) {
    setMessage(error?.message || 'An error occurred');
  }
};
```

### 3. Check verification status

Access the `emailVerified` field from the user object:

```jsx {3} filename="src/App.jsx"
const { data } = await authClient.getSession();

if (data?.session?.user && !data.session.user.emailVerified) {
  // Show verification prompt or restrict features
  console.log('Please verify your email to continue');
}
```

## Verification codes

If you prefer verification codes, users receive a numeric code via email and enter it in your application. Your app switches between the auth form and a verification form.

### 1. Add verification state

Add state to track which form to show:

```jsx filename="src/App.jsx"
const [step, setStep] = useState('auth'); // 'auth' or 'verify'
const [code, setCode] = useState('');
```

### 2. Handle code verification

Create a handler for code verification:

```jsx {6-9} filename="src/App.jsx"
const handleVerify = async (e) => {
  e.preventDefault();
  setMessage('');

  try {
    const { data, error } = await authClient.emailOtp.verifyEmail({
      email,
      otp: code,
    });

    if (error) throw error;

    // Check if auto-sign-in is enabled (default behavior)
    if (data?.session) {
      setUser(data.session.user);
      setStep('auth');
    } else {
      setMessage('Email verified! You can now sign in.');
      setStep('auth');
      setIsSignUp(false);
      setCode('');
    }
  } catch (error) {
    setMessage(error?.message || 'An error occurred');
  }
};
```

### 3. Show verification form

When `step` is `'verify'`, show the verification form:

```jsx filename="src/App.jsx"
if (step === 'verify') {
  return (
    <div>
      <h1>Verify Your Email</h1>
      <p>Enter the code sent to {email}</p>
      <form onSubmit={handleVerify}>
        <input
          type="text"
          placeholder="Verification code"
          value={code}
          onChange={(e) => setCode(e.target.value)}
          required
        />
        <button type="submit">Verify</button>
      </form>
      {message && <p>{message}</p>}
    </div>
  );
}
```

### 4. Switch to verification after sign-up

After calling `signUp.email()`, switch to the verification step:

```jsx {3} filename="src/App.jsx"
if (data?.user && !data.user.emailVerified) {
  setMessage('Check your email for a verification code');
  setStep('verify'); // Switch to verification form
}
```

<details>

<summary>Complete example: App.jsx with verification codes</summary>

Here's a complete, minimal `App.jsx` file that includes sign-up, sign-in, and verification code functionality:

```jsx filename="src/App.jsx"
import { useState, useEffect } from 'react';
import { authClient } from './auth';
import './App.css';

export default function App() {
  const [session, setSession] = useState(null);
  const [user, setUser] = useState(null);
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [loading, setLoading] = useState(true);
  const [message, setMessage] = useState('');
  const [step, setStep] = useState('auth'); // 'auth' or 'verify'
  const [code, setCode] = useState('');
  const [isSignUp, setIsSignUp] = useState(true);

  useEffect(() => {
    authClient.getSession().then((result) => {
      if (result.data?.session && result.data?.user) {
        setSession(result.data.session);
        setUser(result.data.user);
      }
      setLoading(false);
    });
  }, []);

  const handleSignUp = async (e) => {
    e.preventDefault();
    setMessage('');
    const { data, error } = await authClient.signUp.email({
      email,
      password,
      name: email.split('@')[0] || 'User',
    });
    if (error) {
      setMessage(error.message);
      return;
    }
    if (data?.user && !data.user.emailVerified) {
      setMessage('Check your email for a verification code');
      setStep('verify'); // Switch to verification form
    } else {
      const sessionResult = await authClient.getSession();
      if (sessionResult.data?.session && sessionResult.data?.user) {
        setSession(sessionResult.data.session);
        setUser(sessionResult.data.user);
      }
    }
  };

  const handleSignIn = async (e) => {
    e.preventDefault();
    setMessage('');
    const { data, error } = await authClient.signIn.email({ email, password });
    if (error) {
      setMessage(error.message);
      return;
    }
    if (data?.session && data?.user) {
      setSession(data.session);
      setUser(data.user);
    }
  };
  const handleVerify = async (e) => {
    e.preventDefault();
    setMessage('');
    try {
      const { data, error } = await authClient.emailOtp.verifyEmail({
        email,
        otp: code,
      });
      if (error) throw error;
      if (data?.session) {
        setSession(data.session);
        setUser(data.session.user);
        setStep('auth');
      } else {
        setMessage('Email verified! You can now sign in.');
        setStep('auth');
        setIsSignUp(false);
        setCode('');
      }
    } catch (error) {
      setMessage(error?.message || 'An error occurred');
    }
  };

  const handleSignOut = async () => {
    await authClient.signOut();
    setSession(null);
    setUser(null);
  };

  if (loading) return <div>Loading...</div>;

  if (session && user) {
    return (
      <div>
        <h1>Logged in as {user.email}</h1>
        <button onClick={handleSignOut}>Sign Out</button>
      </div>
    );
  }
  if (step === 'verify') {
    return (
      <div>
        {' '}
        <h1>Verify Your Email</h1>
        <p>Enter the code sent to {email}</p>
        <form onSubmit={handleVerify}>
          {' '}
          <input
            type="text"
            placeholder="Verification code"
            value={code}
            onChange={(e) => setCode(e.target.value)}
            required
          />{' '}
          <button type="submit">Verify</button>
        </form>{' '}
        {message && <p>{message}</p>}
      </div>
    );
  }

  return (
    <div>
      <h1>{isSignUp ? 'Sign Up' : 'Sign In'}</h1>
      {message && <p>{message}</p>}
      <form onSubmit={isSignUp ? handleSignUp : handleSignIn}>
        <input
          type="email"
          placeholder="Email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          required
        />
        <input
          type="password"
          placeholder="Password"
          value={password}
          onChange={(e) => setPassword(e.target.value)}
          required
        />
        <button type="submit">{isSignUp ? 'Sign Up' : 'Sign In'}</button>
      </form>
      <p>
        <button onClick={() => setIsSignUp(!isSignUp)}>
          {isSignUp ? 'Already have an account? Sign in' : "Don't have an account? Sign up"}
        </button>
      </p>
    </div>
  );
}
```

</details>

## Resending verification emails

Both verification links and verification codes expire after **15 minutes**. Allow users to request a new one:

```jsx {3-6} filename="src/App.jsx"
const handleResend = async () => {
  try {
    const { error } = await authClient.sendVerificationEmail({
      email,
      callbackURL: window.location.origin + '/',
    });

    if (error) throw error;
    setMessage('Verification email sent! Check your inbox.');
  } catch (error) {
    setMessage(error?.message || 'An error occurred');
  }
};
```

The server sends whichever type (verification link or verification code) you configured in the Console.

## Required vs optional verification

When email verification is **required** in your Console settings, users cannot sign in until they verify. When verification is **optional**, which is the default, users can sign in immediately but their `emailVerified` field remains `false` until verified. If your app links a signed-in user to existing data by matching their email address, check that `emailVerified` is `true` first. Otherwise, anyone who signs up with that address gets that data.

--- [Document source](https://neon.com/docs/auth/guides/manage-auth-api.md) ---

> Summary: Managed Better Auth REST API operations for enabling (POST), retrieving (GET), updating (PATCH), and disabling (DELETE) auth on a per-branch basis, with curl examples and a full response field reference. Use this page when automating auth provisioning or teardown: the enable response is the only call that returns `pub_client_key` and `secret_server_key`, and the `delete_data` flag on DELETE controls whether the `neon_auth` schema is permanently removed. Also covers related branch-scoped endpoints for OAuth providers, email configuration, domains, users, plugins, and webhooks, plus equivalent MCP tools for AI-editor workflows.

# Manage Managed Better Auth via the API

Enable, configure, and disable Managed Better Auth using the Neon API

Last updated: 2026-10-09

You can manage Managed Better Auth programmatically using the [Neon API](https://neon.com/docs/reference/api), or from the terminal with the [Neon CLI](https://neon.com/docs/cli/neon-auth) (`neon neon-auth`), which wraps these same operations. You can also enable and configure Managed Better Auth from an AI editor using the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server#available-tools) (`provision_neon_auth`, `update_auth_config`, `add_auth_oauth_provider`, `get_neon_auth_config`). See [Set up with your AI editor](https://neon.com/docs/auth/about#set-up-with-your-ai-editor).

**Note:** Managed Better Auth operates at the **branch level**. Each branch can have its own independent auth configuration, which means preview and development branches can have separate auth state from your production branch.

## Prerequisites

- A [Neon API key](https://neon.com/docs/manage/api-keys)
- A Neon project with at least one branch

All requests use the base URL `https://console.neon.tech/api/v2` and require the `Authorization: Bearer $NEON_API_KEY` header. The `project_id` and `branch_id` values are returned when you [create a project](https://neon.com/docs/manage/projects#create-a-project-with-the-api) or [list branches](https://neon.com/docs/manage/branches#list-branches-with-the-api) via the API.

## Enable Managed Better Auth

Send a `POST` request to enable Managed Better Auth on a branch:

```bash
curl -X POST 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"auth_provider": "better_auth"}'
```

Response (201 Created):

```json
{
  "auth_provider": "better_auth",
  "auth_provider_project_id": "cab6949a-10e3-4d25-a879-512beed281e3",
  "pub_client_key": "",
  "secret_server_key": "",
  "jwks_url": "https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth/.well-known/jwks.json",
  "schema_name": "neon_auth",
  "table_name": "users_sync",
  "base_url": "https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth"
}
```

The response includes:

| Field                      | Description                                                                                               |
| -------------------------- | --------------------------------------------------------------------------------------------------------- |
| `auth_provider`            | The configured provider (`better_auth`)                                                                   |
| `auth_provider_project_id` | Unique ID for the auth provider instance                                                                  |
| `pub_client_key`           | Public client key (shown once at creation, may be empty for `better_auth`)                                |
| `secret_server_key`        | Secret server key (shown once at creation, may be empty for `better_auth`)                                |
| `jwks_url`                 | JWKS endpoint for JWT verification                                                                        |
| `schema_name`              | Database schema created for auth tables (`neon_auth`)                                                     |
| `table_name`               | Table name for synced user data (`users_sync`)                                                            |
| `base_url`                 | Base URL of the auth service, used for SDK configuration and the interactive API reference (`/reference`) |

**Important:** The enable response is the only time the API returns `pub_client_key` and `secret_server_key`. Store them securely. Subsequent `GET` requests do not include these fields. For client initialization examples that combine Managed Better Auth and the Data API from a single Neon URL, see [`createClient()` in the JavaScript SDK reference](https://neon.com/docs/reference/javascript-sdk#initializing).

If Managed Better Auth is already enabled on the branch, this call returns an error.

**Tip: Using a non-default database**

By default, Managed Better Auth uses the branch's default database. To target a different database, add `database_name` to the request body: `{"auth_provider": "better_auth", "database_name": "my_other_db"}`

## Get Auth configuration

Retrieve the current Managed Better Auth configuration for a branch:

```bash
curl -X GET 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth' \
  -H 'Authorization: Bearer $NEON_API_KEY'
```

Response (200 OK):

```json
{
  "auth_provider": "better_auth",
  "auth_provider_project_id": "cab6949a-10e3-4d25-a879-512beed281e3",
  "branch_id": "br-example-abc123",
  "db_name": "neondb",
  "created_at": "2026-02-26T04:29:05Z",
  "owned_by": "neon",
  "jwks_url": "https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth/.well-known/jwks.json",
  "base_url": "https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth",
  "name": "My App"
}
```

## Update auth configuration

Update auth settings for a branch. Currently supports changing the application name shown in user-facing auth messages. Applies to Managed Better Auth integrations only. Defaults to the Neon project name.

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/config' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "My App"}'
```

Response (200 OK):

```json
{
  "name": "My App"
}
```

| Field  | Description                                                    |
| ------ | -------------------------------------------------------------- |
| `name` | The name shown in user-facing auth messages (1-256 characters) |

Each branch manages its own application name independently. You can also update this from **Settings** > **Better Auth** > **Project Info** in the Neon Console.

## Disable Managed Better Auth

Send a `DELETE` request to disable Managed Better Auth on a branch:

```bash
curl -X DELETE 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"delete_data": true}'
```

Response (200 OK): Empty body.

The `delete_data` field controls whether the system removes the `neon_auth` schema from your database:

- **`true`**: Deletes the `neon_auth` schema and all auth tables (users, sessions, accounts).
- **`false`** (default): Disables the auth service but leaves the schema and data intact. You can re-enable later without losing user data.

**Warning:** Setting `delete_data` to `true` permanently removes all auth data from the database. You cannot undo this.

## Related auth endpoints

The Neon API also provides endpoints for managing auth configuration at the branch level. These are available at `https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/...`:

| Endpoint                  | Methods                  | Description                                                                                                      |
| ------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `/domains`                | GET, POST, DELETE        | Manage trusted redirect domains                                                                                  |
| `/oauth_providers`        | GET, POST, PATCH, DELETE | Configure OAuth providers (Google, GitHub, etc.)                                                                 |
| `/email_provider`         | GET, PATCH               | Configure the email provider                                                                                     |
| `/email_and_password`     | GET, PATCH               | Configure email/password authentication                                                                          |
| `/users`                  | POST, DELETE, PUT        | Create, delete, and manage user roles                                                                            |
| `/plugins`                | GET, PATCH               | View and configure [auth plugins](https://neon.com/docs/auth/guides/plugins)                                     |
| `/plugins/magic-link`     | PATCH                    | Configure the [Magic Link plugin](https://neon.com/docs/auth/guides/plugins/magic-link)                          |
| `/plugins/phone-number`   | GET, PATCH               | Configure the [Phone Number plugin](https://neon.com/docs/auth/guides/plugins/phone-number)                      |
| `/plugins/oauth-provider` | GET, PATCH               | Configure the [OAuth provider plugin](https://neon.com/docs/auth/guides/plugins/oauth-provider)                  |
| `/oauth-provider/clients` | GET, POST, PATCH, DELETE | Manage [OAuth clients](https://neon.com/docs/auth/guides/plugins/oauth-provider#create-and-manage-oauth-clients) |
| `/webhooks`               | GET, PUT                 | Configure webhook notifications                                                                                  |
| `/allow_localhost`        | GET, PATCH               | Toggle localhost access for development                                                                          |
| `/config`                 | PATCH                    | Update auth configuration (application name)                                                                     |
| `/send_test_email`        | POST                     | Send a test email to verify email configuration                                                                  |

For full request/response details on these endpoints, see the [interactive API Reference](https://neon.com/docs/reference/api). For the OAuth provider, see the reference for [retrieving](https://neon.com/docs/reference/api/auth/get-neon-auth-o-auth-provider-plugin) and [updating](https://neon.com/docs/reference/api/auth/update-neon-auth-o-auth-provider-plugin) the plugin configuration, and for [listing](https://neon.com/docs/reference/api/auth/list-neon-auth-o-auth-clients), [creating](https://neon.com/docs/reference/api/auth/create-neon-auth-o-auth-client), [retrieving](https://neon.com/docs/reference/api/auth/get-neon-auth-o-auth-client), [updating](https://neon.com/docs/reference/api/auth/update-neon-auth-o-auth-client), [deleting](https://neon.com/docs/reference/api/auth/delete-neon-auth-o-auth-client), and [rotating the secret of](https://neon.com/docs/reference/api/auth/rotate-neon-auth-o-auth-client-secret) OAuth clients.

**Tip: TypeScript SDK**

You can also manage Managed Better Auth using the [Neon TypeScript SDK](https://neon.com/docs/reference/typescript-sdk).

--- [Document source](https://neon.com/docs/auth/guides/password-reset.md) ---

> Summary: Managed Better Auth password reset sends a verification link to the user's email and requires email authentication to be enabled in project Settings. The pre-built `<ForgotPasswordForm>` and `<ResetPasswordForm>` components handle the full forgot-password flow; reset links expire after 15 minutes, and the SDK `resetPasswordForEmail` method is not yet supported. An optional per-branch setting, `revoke_sessions_on_password_reset`, signs the user out of every existing session after a successful reset.

# Password reset

Allow users to reset forgotten passwords

Last updated: 2026-11-05

Password reset allows users to securely reset forgotten passwords. Managed Better Auth supports password reset via verification links sent to the user's email address.

## Enable password reset

In your project's **Settings** → **Better Auth** page, ensure **Sign-in with Email** is enabled. Password reset is automatically available when email authentication is enabled.

## Using UI components

With [Better Auth UI](https://neon.com/docs/auth/reference/ui-components), password reset is built in. `npx shadcn@latest add @better-auth-ui/auth` adds the `forgot-password`, `reset-link-sent`, and `reset-password` views, and the sign-in view links to **Forgot password?**.

### 1. Route the auth views

Render `<Auth>` for every auth path, as in the [Next.js App Router example](https://neon.com/docs/auth/reference/ui-components#nextjs-app-router):

```tsx filename="app/auth/[path]/page.tsx"
import { viewPaths } from '@better-auth-ui/core';
import { Auth } from '@/components/auth/auth';

export const dynamicParams = false;

export function generateStaticParams() {
  return Object.values(viewPaths.auth).map((path) => ({ path }));
}

export default async function AuthPage({ params }: { params: Promise<{ path: string }> }) {
  const { path } = await params;
  return <Auth path={path} />;
}
```

`/auth/forgot-password` asks for the email and sends the reset link. The link opens `/auth/reset-password`, where the user sets a new password.

### 2. Render a single view

To place a view somewhere else, pass the view name instead of a path:

```tsx filename="src/ForgotPasswordPage.tsx"
import { Auth } from '@/components/auth/auth';

export function ForgotPasswordPage() {
  return <Auth view="forgotPassword" />;
}
```

The copied components (`components/auth/forgot-password.tsx` and `components/auth/reset-password.tsx`) are yours to edit.

**Note:** SDK methods for password reset (`resetPasswordForEmail`) are not fully supported yet. Use the UI components for password reset functionality.

## Password reset flow

The complete password reset flow works as follows:

1. **User requests reset**: User enters their email and clicks "Send reset link"
2. **Email sent**: User receives a verification link with a reset token
3. **User clicks link**: User is redirected to your app's reset password page
4. **User enters new password**: User submits the new password
5. **Password reset**: Password is updated and user is signed in (if auto-sign-in is enabled)

## Reset link expiration

Password reset links expire after **15 minutes**. If a link expires, users need to request a new one.

## Sign users out after a reset

By default, resetting a password doesn't end the user's existing sessions. Turn on **Revoke sessions on password reset** to sign the user out of every existing session when they reset their password. This applies to resets through a reset link (`/reset-password`) and through [Email OTP](https://neon.com/docs/auth/guides/plugins/email-otp#reset-password-with-otp) (`/email-otp/reset-password`), whether your app calls those endpoints directly or through a proxy.

**Console**

In your project's **Settings** → **Better Auth** page, turn on **Revoke sessions on password reset**. The switch appears under **Sign-in with Email** while that switch is on.

**CLI**

Turn on the setting using [`neon neon-auth config email-password update`](https://neon.com/docs/cli/neon-auth#config-email-password-update):

```bash
neon neon-auth config email-password update --revoke-sessions-on-password-reset
```

`neon neon-auth config email-password get` shows the current value.

**API**

Use the [Update email and password configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-email-and-password-config) endpoint. Replace `{project_id}` and `{branch_id}` with your project and branch IDs:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/email_and_password' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"revoke_sessions_on_password_reset": true}'
```

A `GET` request to the same endpoint returns the current value.

Consuming the reset link or code, deleting the user's sessions, and saving the new password happen in a single database transaction. If any step fails, the reset returns an error, so a successful reset never leaves an old session valid. A revoked session is rejected on its next request. Managed Better Auth doesn't use a session cookie cache or secondary session storage, so every session check reads the database.

The setting is off by default so existing apps don't sign users out unexpectedly. It's configured per branch. A new branch copies its parent's auth configuration when you create it, so turning the setting on for a parent doesn't change branches that already exist.

To sign out other devices when a signed-in user changes their password, pass `revokeOtherSessions: true` to `changePassword()`. See [Revoke other sessions](https://neon.com/docs/auth/guides/user-management#revoke-other-sessions).

## Next steps

- [Add email verification](https://neon.com/docs/auth/guides/email-verification) to ensure users own their email addresses
- [Customize the application name](https://neon.com/docs/auth/production-checklist#application-name) shown in password reset emails
- [Learn how to branch your auth](https://neon.com/docs/auth/branching-authentication) to use database branches with isolated auth environments

--- [Document source](https://neon.com/docs/auth/guides/plugins.md) ---

> Summary: Managed Better Auth exposes a managed subset of Better Auth plugins (Admin, Email OTP, JWT, Magic Link, OAuth Provider, Organization, Open API, Phone Number) through the Neon SDK; plugins are not installed or configured directly. Use this page to check which plugins are fully supported versus partially supported, and how to configure them via the Neon Console or Neon API. The Organization plugin has partial support.

# Plugins

Supported Better Auth plugins in Managed Better Auth

Last updated: 2026-10-30

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/), which supports a variety of plugins to extend authentication functionality.

**Info: Plugins are managed by Managed Better Auth**

Managed Better Auth is a **managed** Better Auth service. You **don't install or configure Better Auth plugins directly** - instead, Managed Better Auth exposes a supported subset of plugins through the Neon SDK.

For plugins that have Console settings (for example [Organization](https://neon.com/docs/auth/guides/plugins/organization)), open **Settings** > **Better Auth** in the Neon Console, or use the Neon API. From the terminal, [`neon neon-auth config organization update`](https://neon.com/docs/cli/neon-auth#config-organization-update) configures the Organization plugin, [`neon neon-auth config oauth-server update`](https://neon.com/docs/cli/neon-auth#config-oauth-server-update) configures the OAuth Provider plugin, and [`neon neon-auth plugins list`](https://neon.com/docs/cli/neon-auth#plugins-list) shows the current plugin configurations. Additional plugin options may still arrive over time; see the [Managed Better Auth roadmap](https://neon.com/docs/auth/roadmap).

The following Better Auth plugins are currently supported in Managed Better Auth:

## Supported plugins

| Plugin                                                                     | Status      |
| -------------------------------------------------------------------------- | ----------- |
| [Admin](https://neon.com/docs/auth/guides/plugins/admin)                   | ✅ Supported |
| [Email OTP](https://neon.com/docs/auth/guides/plugins/email-otp)           | ✅ Supported |
| [JWT](https://neon.com/docs/auth/guides/plugins/jwt)                       | ✅ Supported |
| [Magic Link](https://neon.com/docs/auth/guides/plugins/magic-link)         | ✅ Supported |
| [OAuth Provider](https://neon.com/docs/auth/guides/plugins/oauth-provider) | ✅ Supported |
| [Organization](https://neon.com/docs/auth/guides/plugins/organization)     | ⚠️ Partial  |
| [Open API](https://neon.com/docs/auth/guides/plugins/openapi)              | ✅ Supported |
| [Phone Number](https://neon.com/docs/auth/guides/plugins/phone-number)     | ✅ Supported |

For more runnable Managed Better Auth samples, see the [neondatabase/neon-js](https://github.com/neondatabase/neon-js/tree/main/examples) examples repository:

| Plugin       | Demo                                                                                                                    |
| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Organization | [neon-auth-orgs-example](https://github.com/neondatabase/neon-js/tree/main/examples/neon-auth-orgs-example)             |
| Magic Link   | [neon-auth-magic-link-example](https://github.com/neondatabase/neon-js/tree/main/examples/neon-auth-magic-link-example) |
| Phone Number | [nextjs-phone-login](https://github.com/neondatabase/neon-js/tree/main/examples/nextjs-phone-login)                     |

For the latest status (including what's coming next), see the [Managed Better Auth roadmap](https://neon.com/docs/auth/roadmap).

--- [Document source](https://neon.com/docs/auth/guides/plugins/admin.md) ---

> Summary: The Managed Better Auth Admin plugin exposes Better Auth admin APIs through the Neon SDK without manual plugin configuration, letting server-side code create users, assign roles, ban accounts, list or revoke sessions, and impersonate users for support and debugging. Use this page when building admin dashboards or support tooling that must manage user authentication state programmatically. Admin operations require an authenticated session with HTTP-only cookies, and impersonation sessions are capped at 1 hour.

# Admin

Manage users, roles, bans, sessions, and impersonation

Last updated: 2026-09-16

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/) and provides support for Admin plugin APIs through the Neon SDK. You do not need to manually install or configure the Better Auth Admin plugin.

The Admin plugin provides APIs to manage your users and their authentication state. It's commonly used to build internal tooling (admin dashboards, support tools) that can:

- Create and update users
- Assign roles
- Ban and unban users
- List and revoke sessions
- Impersonate a user for support/debugging

## Prerequisites

- A Neon project with **Auth enabled**
- An existing user with an **admin** role to call Admin APIs.

  You can assign the **admin** role to a user through the Neon Console. Navigate to **Auth** → **Users**, open the three‑dot menu next to the user, and select **Make admin**.

  ![Assign admin role in Neon Console](https://neon.com/docs/auth/make-admin.png)

## Use Admin with SDK methods

You can call Admin plugin methods using the Neon SDK auth client.

> If you haven't set up Managed Better Auth yet, follow the [Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only) or [React](https://neon.com/docs/auth/quick-start/react) quick start to create an `authClient`.

### Create a user

Use the Admin APIs to create users on behalf of others (for example, back-office onboarding).

#### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type                              | Required | Notes                                                    |
| --------- | --------------------------------- | :------: | -------------------------------------------------------- |
| email     | string                            |     ✓    | Email address for the new user                           |
| password  | string                            |     ✓    | Password for the new user                                |
| name      | string                            |     ✓    | Display name                                             |
| role      | string \| string\[] \| undefined  |          | Optional role(s) for the user (for example: user, admin) |
| data      | Record\<string, any> \| undefined |          | Optional custom fields                                   |

</details>

```ts
const { data, error } = await authClient.admin.createUser({
  email: 'user@email.com',
  password: 'secure-password',
  name: 'User Name',
  role: 'user',
  data: { customUserField: 'value' },
});
```

### List users

List users with optional search, filtering, sorting, and pagination.

#### Parameters

<details>

<summary>View parameters</summary>

| Parameter      | Type                                                        | Required | Notes                                |
| -------------- | ----------------------------------------------------------- | :------: | ------------------------------------ |
| searchValue    | string \| undefined                                         |          | Value to search for                  |
| searchField    | 'email' \| 'name' \| undefined                              |          | Field to search in                   |
| searchOperator | 'contains' \| 'starts\_with' \| 'ends\_with' \| undefined   |          | Search operator                      |
| limit          | number \| string \| undefined                               |          | Max users to return (page size)      |
| offset         | number \| string \| undefined                               |          | Number of users to skip (pagination) |
| sortBy         | string \| undefined                                         |          | Field to sort by                     |
| sortDirection  | 'asc' \| 'desc' \| undefined                                |          | Sort direction                       |
| filterField    | string \| undefined                                         |          | Field to filter by                   |
| filterValue    | string \| number \| boolean \| undefined                    |          | Filter value                         |
| filterOperator | 'eq' \| 'ne' \| 'lt' \| 'lte' \| 'gt' \| 'gte' \| undefined |          | Filter operator                      |

</details>

```ts
const { data, error } = await authClient.admin.listUsers({
  query: {
    // Following parameters are optional
    searchValue: 'text to search',
    searchField: 'email',
    searchOperator: 'contains',
    limit: 10,
    offset: 0,
    sortBy: 'name',
    sortDirection: 'asc',
  },
});
```

> Use `filterField`, `filterValue`, and `filterOperator` to further filter results (for example, by role etc)

The `data` object contains a list of users and pagination metadata:

```ts
{
  users: [/* array of user objects */],
  total: 100, // total number of users matching the query
  limit: 10,  // limit used in the query
  offset: 0   // offset used in the query
}
```

Use the `total`, `limit`, and `offset` values to implement pagination in your admin tooling.

### Set a user role

Assign roles to control who can call admin operations.

#### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type                | Required | Notes                                 |
| --------- | ------------------- | :------: | ------------------------------------- |
| userId    | string              |     ✓    | The user ID to update                 |
| role      | string \| string\[] |     ✓    | Role(s) to apply (for example, admin) |

</details>

```ts
const { error } = await authClient.admin.setRole({ userId: 'user-id', role: 'admin' });
```

### Set a user password

Set or reset a user's password.

<details>

<summary>View parameters</summary>

| Parameter   | Type   | Required | Notes                 |
| ----------- | ------ | :------: | --------------------- |
| userId      | string |     ✓    | The user ID to update |
| newPassword | string |     ✓    | The new password      |

</details>

```ts
const { error } = await authClient.admin.setUserPassword({
  userId: 'user-id',
  newPassword: 'new-secure-password',
});
```

### Update user details

Update user information such as email, name, and custom fields.

<details>

<summary>View parameters</summary>

| Parameter | Type                 | Required | Notes                                         |
| --------- | -------------------- | :------: | --------------------------------------------- |
| userId    | string               |     ✓    | The user ID to update                         |
| data      | Record\<string, any> |     ✓    | Fields to update (email, name, custom fields) |

</details>

```ts
const { error } = await authClient.admin.updateUser({
  userId: 'user-id',
  data: { name: 'New Name' },
});
```

### Ban user

Banning prevents sign-in for a user. You can optionally provide a reason and expiration for the ban.

<details>

<summary>View parameters</summary>

| Parameter    | Type                | Required | Notes                                                                               |
| ------------ | ------------------- | :------: | ----------------------------------------------------------------------------------- |
| userId       | string              |     ✓    | The user ID to ban                                                                  |
| banReason    | string \| undefined |          | Reason for the ban                                                                  |
| banExpiresIn | number \| undefined |          | Duration in seconds until the ban expires. If not provided, the ban does not expire |

</details>

```ts
const { error } = await authClient.admin.banUser({
  userId: 'user-id',
  banReason: 'Policy violation',
  // banExpiresIn: 60 * 60 * 24, // optional (seconds)
});
```

### Unban user

Unban a previously banned user.

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required | Notes                |
| --------- | ------ | :------: | -------------------- |
| userId    | string |     ✓    | The user ID to unban |

</details>

```ts
const { error } = await authClient.admin.unbanUser({ userId: 'user-id' });
```

### Manage sessions

Use session APIs to view active sessions and revoke them.

#### List sessions

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required | Notes                                       |
| --------- | ------ | :------: | ------------------------------------------- |
| userId    | string |     ✓    | The user ID whose sessions you want to list |

</details>

```ts
const { data, error } = await authClient.admin.listUserSessions({ userId: 'user-id' });
```

#### Revoke a session

<details>

<summary>View parameters</summary>

| Parameter    | Type   | Required | Notes                       |
| ------------ | ------ | :------: | --------------------------- |
| sessionToken | string |     ✓    | The session token to revoke |

</details>

```ts
const { error } = await authClient.admin.revokeUserSession({ sessionToken: 'session-token' });
```

#### Revoke all sessions

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required | Notes                                         |
| --------- | ------ | :------: | --------------------------------------------- |
| userId    | string |     ✓    | The user ID whose sessions you want to revoke |

</details>

```ts
const { error } = await authClient.admin.revokeUserSessions({ userId: 'user-id' });
```

### Impersonate a user

Impersonation creates a session that behaves like the target user (useful for support and debugging).

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required | Notes                      |
| --------- | ------ | :------: | -------------------------- |
| userId    | string |     ✓    | The user ID to impersonate |

</details>

```ts
const { data, error } = await authClient.admin.impersonateUser({ userId: 'user-id' });
```

### Stop impersonation

Stop an active impersonation session.

<details>

<summary>View parameters</summary>

This method does not take any parameters.

</details>

```ts
const { error } = await authClient.admin.stopImpersonating();
```

## Limitations

- Admin operations require an authenticated session (HTTP-only cookies). This means your admin tooling must run on the same site that can send those cookies to the Managed Better Auth API.
- Impersonation sessions are intentionally time‑limited, lasting for the duration of the active browser session or up to 1 hour. This design helps minimize security risks associated with long‑lived impersonation.

--- [Document source](https://neon.com/docs/auth/guides/plugins/email-otp.md) ---

> Summary: Managed Better Auth Email OTP delivers one-time passwords by email for passwordless sign-in, password reset, and email verification without requiring manual installation of the Better Auth plugin. Use this page to implement these flows via Neon SDK methods or with Better Auth UI's Email OTP plugin (`emailOtpPlugin()`) for pre-built UI components. OTP codes are time-limited and rate-limited (exceeding attempts returns `TOO_MANY_ATTEMPTS`), and production deployments require a dedicated SMTP provider.

# Email OTP

Sign in and verify email addresses with one-time passwords

Last updated: 2026-11-05

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/) and provides full support for Email OTP plugin APIs through the Neon SDK. You do not need to manually install or configure the Better Auth Email OTP plugin.

Email OTP lets users receive a one-time password (OTP) by email and use it to:

- Sign in without a password
- Perform password resets
- Verify their email address (verification codes)

Managed Better Auth UI and Neon SDK are client-side SDKs, so you only invoke their methods. OTP generation and delivery are handled automatically - you do not have direct control over the codes sent to users.

## Prerequisites

- A Neon project with **Auth enabled**
- **Sign-up and Sign-in with Email** enabled in your project's **Settings** → **Better Auth**.

  **Note: Email verification during sign-up**

  To use Email OTP for sign-up verification, enable **Verify at Sign-up** and select **Verification code** under **Verification method**.
  ![Email OTP verification code setting](https://neon.com/docs/auth/email-otp.png)

## Use Email OTP with UI components

If you're using [Better Auth UI](https://neon.com/docs/auth/reference/ui-components), add its Email OTP components and pass the plugin to `AuthProvider`. `emailOtpPlugin()` adds OTP sign-in; pass `emailOtpPlugin({ passwordReset: true, emailVerification: true })` to also use codes for password reset and email verification.

```bash
npx shadcn@latest add @better-auth-ui/email-otp
```

```tsx filename="components/providers.tsx"
import { emailOtpPlugin } from '@/lib/auth/email-otp-plugin';

<AuthProvider
  authClient={authClient}
  navigate={navigate}
  Link={Link}
  plugins={[emailOtpPlugin()]}
>
  {children}
</AuthProvider>
```

Add the plugin's views to your auth route's paths with `emailOtpPlugin().viewPaths.auth` from `@better-auth-ui/core/plugins/email-otp`. The UI plugin doesn't enable Email OTP on your branch; enable it in Managed Better Auth first.

Users can now sign in with Email OTP by selecting the option on the sign-in screen and entering the one-time code sent to their email.

![Email OTP verification](https://neon.com/docs/auth/email-otp-verification.png)

> If you haven't set up Managed Better Auth UI components yet, see the [UI components reference](https://neon.com/docs/auth/reference/ui-components) and the [Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only) or [React](https://neon.com/docs/auth/quick-start/react) quick start.

## Use Email OTP with SDK methods

You can also implement OTP flows directly using the [Neon SDK](https://neon.com/docs/reference/javascript-sdk).

### Send an OTP

To send an OTP, call `emailOtp.sendVerificationOtp()` and specify a `type`:

- `sign-in` - passwordless sign-in
- `email-verification` - verify an email address

```ts filename="src/send-otp.ts"
import { authClient } from './auth';

export async function sendSignInOtp(email: string) {
  const { error } = await authClient.emailOtp.sendVerificationOtp({ email, type: 'sign-in' });

  if (error) throw error;
}
```

> For more details, see the [Send verification OTP code](https://neon.com/docs/reference/javascript-sdk#auth-sendverificationotp) in Neon SDK.

### Sign in with OTP

After the user receives the code, sign them in using `signIn.emailOtp()`:

```ts filename="src/sign-in-with-otp.ts"
import { authClient } from './auth';

export async function signInWithOtp(email: string, otp: string) {
  const { data, error } = await authClient.signIn.emailOtp({ email, otp });

  if (error) throw error;
  return data;
}
```

> For more details, see the [Sign in with OTP code](https://neon.com/docs/reference/javascript-sdk#auth-signinwithemailotp) in Neon SDK.

### Verify email with OTP

If your project has email verification enabled with **verification codes**, Managed Better Auth sends an OTP during sign-up.

Once the user enters the code, verify the email address using `emailOtp.verifyEmail()`:

```ts filename="src/verify-email.ts"
import { authClient } from './auth';

export async function verifyEmail(email: string, otp: string) {
  const { data, error } = await authClient.emailOtp.verifyEmail({ email, otp });

  if (error) throw error;
  return data;
}
```

> For more details, see the [Verify email with OTP code](https://neon.com/docs/reference/javascript-sdk#auth-verifyemail) in Neon SDK.

Check out our [Email verification guide](https://neon.com/docs/auth/guides/email-verification) for a complete walkthrough.

### Check an OTP (optional)

If you want to validate an OTP without completing the flow (for example, to check the code before enabling a sensitive UI), you can use `emailOtp.checkVerificationOtp()`:

```ts filename="src/otp.ts"
import { authClient } from './auth';

export async function isOtpValid(email: string, otp: string) {
  const { data, error } = await authClient.emailOtp.checkVerificationOtp({
    email,
    otp,
    type: 'sign-in',
  });

  if (error) throw error;
  return Boolean(data?.success);
}
```

> For more details, see the [Check verification OTP code](https://neon.com/docs/reference/javascript-sdk#auth-checkverificationotp) in Neon SDK.

## Reset Password with OTP

You can also use Email OTP to implement password reset flows. To do this use the `authClient.forgetPassword.emailOtp` method to send a password reset OTP to the user's email address.

```ts filename="src/send-reset-otp.ts"
import { authClient } from './auth';

export async function sendPasswordResetOtp(email: string) {
  const { error } = await authClient.forgetPassword.emailOtp({ email });
  if (error) throw error;
}
```

Once the user receives the OTP, verify it using `authClient.emailOtp.checkVerificationOtp()` with the `type` set to `forget-password`.

```ts filename="src/verify-reset-otp.ts"
import { authClient } from './auth';

export async function verifyPasswordResetOtp(email: string, otp: string) {
  const { data, error } = await authClient.emailOtp.checkVerificationOtp({
    email,
    otp,
    type: 'forget-password',
  });

  if (error) throw error;
  return Boolean(data?.success);
}
```

Finally, reset the user's password using `authClient.emailOtp.resetPassword()`:

```ts filename="src/reset-password.ts"
import { authClient } from './auth';

export async function resetPasswordUsingOtp(email: string, otp: string, newPassword: string) {
  const { data, error } = await authClient.emailOtp.resetPassword({
    email,
    otp,
    password: newPassword,
  });
}
```

To sign the user out of every existing session after an OTP reset, turn on [Revoke sessions on password reset](https://neon.com/docs/auth/guides/password-reset#sign-users-out-after-a-reset).

## Limitations

Email OTP codes are time-limited and rate-limited.

If users exceed the allowed verification attempts, the API returns an error code like `TOO_MANY_ATTEMPTS` and the user must request a new code.

## Email provider configuration

For production environments, we strongly recommend using a dedicated email provider. The default shared SMTP should be used only during development. Refer to the [Email provider configuration guide](https://neon.com/docs/auth/production-checklist#email-provider) for setup instructions.

A custom SMTP provider changes the sender address but still sends Neon's default templates. For full branding control, use webhooks. See [Customize emails](https://neon.com/docs/auth/guides/customize-emails).

--- [Document source](https://neon.com/docs/auth/guides/plugins/jwt.md) ---

> Summary: Managed Better Auth's JWT plugin lets backend services, CLI tools, and cross-domain API requests retrieve raw JSON Web Tokens via `authClient.getSession()` (`data.session.token`) or the `set-auth-jwt` response header, rather than relying on HTTP-only session cookies. Tokens are signed with EdDSA (Ed25519) and expire in 15 minutes; verify them using the JWKS endpoint at `<YOUR_NEON_AUTH_URL>/.well-known/jwks.json`. This plugin is not a substitute for session management in browser-based apps, and custom JWT claims are not supported.

# JWT

Authenticate using JSON Web Tokens (JWT) for external services

Last updated: 2026-11-05

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/) and provides support for JWT plugin APIs through the Neon SDK. You do not need to manually install or configure the Better Auth JWT plugin.

While Managed Better Auth primarily relies on **secure, HTTP‑only cookies** (sessions) for browser‑based authentication, certain scenarios require a raw token. In these cases, the JWT plugin is especially useful:

- **Microservices:** Sharing identity between backend services.
- **Separate frontend and backend domains:** Authenticating API requests from a domain different than your main application.
- **CLI tools:** Enabling authentication from the command‑line interface.

**Warning: Sessions vs. JWTs**

This plugin is **not** a replacement for session management in web applications. For standard browser-based apps (Next.js, React, Vue, etc.), rely on the default session cookie mechanism provided by `authClient.signIn` and `authClient.getSession`.

Only use JWTs when you specifically need to authorize requests to services that cannot access the browser's cookie jar.

## Prerequisites

- A Neon project with **Auth enabled**.

## Retrieve a token

You can retrieve a JWT for the currently signed-in user using the Neon SDK.

### Using the SDK method

To get a raw token string, call `authClient.getSession()`. The SDK puts the session's JWT in `data.session.token`. This is the recommended approach for client applications that need to attach a token to an API request header manually.

```ts filename="src/get-token.ts"
import { authClient } from './auth';

export async function getJwtToken() {
  const { data, error } = await authClient.getSession();

  if (error) throw error;

  // The JWT string (for example, "eyJhbGciOiJFZ..."), or undefined when no one is signed in
  return data?.session.token;
}
```

If your app is served from a different origin than your Managed Better Auth URL (for example a Vite or SPA dev server on `localhost` talking to auth on `*.neon.tech`), make sure the auth client sends the session cookie on cross-origin requests, so that `getSession()` can find the session:

```ts filename="src/auth.ts"
import { createAuthClient } from '@neon/auth';
import { BetterAuthReactAdapter } from '@neon/auth/react/adapters';

export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL, {
  adapter: BetterAuthReactAdapter({ fetchOptions: { credentials: 'include' } }),
});
```

Cross-domain setups have further limitations, notably Safari ITP blocking third-party cookies, with reverse-proxy or shared-parent-domain workarounds. See [Better Auth: Safari, ITP, and Cross-Domain Setups](https://www.better-auth.com/docs/concepts/cookies#safari-itp-and-cross-domain-setups).

### Using the session header

When you call `authClient.getSession()`, Managed Better Auth automatically includes a JWT in the response headers. If you are using a custom fetcher or need to intercept the token immediately after a session check:

```ts
await authClient.getSession({
  fetchOptions: {
    onSuccess: (ctx) => {
      const jwt = ctx.response.headers.get('set-auth-jwt');
      console.log('JWT:', jwt);
    },
  },
});
```

### Example decoded JWT payload

A typical decoded JWT payload looks like this:

```json
{
  "iat": 1766320685,
  "name": "User Name",
  "email": "user@email.com",
  "emailVerified": false,
  "image": null,
  "createdAt": "2025-12-20T11:04:41.437Z",
  "updatedAt": "2025-12-20T11:04:41.437Z",
  "role": "authenticated",
  "banned": false,
  "banReason": null,
  "banExpires": null,
  "id": "860dc360-609f-4b7d-9e70-ec93fe6414d3",
  "sub": "860dc360-609f-4b7d-9e70-ec93fe6414d3",
  "exp": 1766321585,
  "iss": "<YOUR_NEON_AUTH_URL_ORIGIN>",
  "aud": "<YOUR_NEON_AUTH_URL_ORIGIN>"
}
```

### Organization claim

If the user belongs to an [organization](https://neon.com/docs/auth/guides/plugins/organization), the JWT includes an `o` claim describing the session's active organization:

```json
{
  "o": {
    "id": "2644b1c7-6d77-46bf-bcf1-832f7616db16",
    "slug": "example-org",
    "role": "owner"
  }
}
```

- `id`: the organization ID
- `slug`: the organization slug
- `role`: the user's role in the organization, such as `owner`, `admin`, or `member`

The `o` claim is `null` when the session has no active organization or the Organization plugin is disabled for the branch. Creating an organization makes it the active organization for that session. To switch, call `authClient.organization.setActive()`.

The `role` value is read when the token is issued. If a user's role changes, tokens issued afterward include the new role, but an existing token keeps the old role until it expires. Tokens expire after 15 minutes.

## Verify a token

To verify the authenticity of a JWT, you need to validate its signature using the public keys provided by JWKS (JSON Web Key Set).

Managed Better Auth exposes a public JWKS endpoint that contains the public keys necessary to verify the signature of your JWTs.

### The JWKS endpoint

Your Managed Better Auth JWKS endpoint is located at:

```
<YOUR_NEON_AUTH_URL>/.well-known/jwks.json
```

If you verify Managed Better Auth JWTs inside [Neon Functions](https://neon.com/docs/compute/functions/overview), the platform injects `NEON_AUTH_BASE_URL` and `NEON_AUTH_JWKS_URL` when Managed Better Auth is provisioned on the branch. Use `NEON_AUTH_JWKS_URL` directly instead of deriving it yourself. See [Functions environment variables](https://neon.com/docs/compute/functions/environment-variables#neon-injected-variables).

### Verification example

The following examples demonstrate how to verify a Managed Better Auth JWT in several programming languages. No matter which language you use, the process is the same: fetch the JWKS from the provided endpoint and use it to validate the token's signature and claims. If your preferred language isn't included here, you can apply these same principles in your own environment.

**Info: Production Readiness**

The following examples are provided for reference only and are not guaranteed to be production‑ready. Be sure to implement proper caching, error handling, and security best practices as required for your application.

**Node.js**

1. Install the library:

   ```bash
   npm install jose
   ```

2. Use the following example code as a reference to verify a JWT:

   ```ts
   import { jwtVerify, createRemoteJWKSet } from 'jose';

   const NEON_AUTH_BASE_URL = process.env.NEON_AUTH_BASE_URL!;
   const NEON_JWKS_URL = `${NEON_AUTH_BASE_URL}/.well-known/jwks.json`;
   const JWKS = createRemoteJWKSet(new URL(NEON_JWKS_URL));
   // Managed Better Auth sets both `iss` and `aud` to the origin of your auth URL
   const ORIGIN = new URL(NEON_AUTH_BASE_URL).origin;

   export async function validateNeonToken(token: string) {
       try {
           const { payload } = await jwtVerify(token, JWKS, {
               algorithms: ['EdDSA'],
               issuer: ORIGIN,
               audience: ORIGIN,
           });

           return payload;
       } catch (error) {
           console.error('Token validation failed:', error);
           return null;
       }
   }

   validateNeonToken('<YOUR_JWT_TOKEN>').then((payload) => {
       if (payload) {
           console.log('Token is valid. Payload:', payload);
       } else {
           console.log('Token is invalid.');
       }
   });
   ```

   > Replace `<YOUR_JWT_TOKEN>` with the actual JWT token you want to verify.

**Python**

1. Install the library:

   ```bash
   pip install PyJWT requests cryptography
   ```

2. Use the following example code as a reference to verify a JWT:

   ```py
   import base64
   import os
   from urllib.parse import urlparse

   import jwt
   import requests
   from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
   from jwt import PyJWTError

   NEON_AUTH_BASE_URL = os.environ.get("NEON_AUTH_BASE_URL", "")
   NEON_JWKS_URL = f"{NEON_AUTH_BASE_URL}/.well-known/jwks.json"
   parsed = urlparse(NEON_AUTH_BASE_URL)
   ORIGIN = f"{parsed.scheme}://{parsed.netloc}"

   def get_jwks():
       response = requests.get(NEON_JWKS_URL)
       response.raise_for_status()
       return response.json()

   def get_signing_key(token, jwks):
       unverified_header = jwt.get_unverified_header(token)
       kid = unverified_header["kid"]

       for jwk in jwks["keys"]:
           if jwk["kid"] == kid:
               x = jwk["x"]
               public_key_bytes = base64.urlsafe_b64decode(x + "==")
               return Ed25519PublicKey.from_public_bytes(public_key_bytes)

       raise ValueError("Matching JWK not found")

   def validate_neon_token(token: str):
       try:
           jwks = get_jwks()
           signing_key = get_signing_key(token, jwks)

           payload = jwt.decode(
               token, key=signing_key, algorithms=["EdDSA"], issuer=ORIGIN, audience=ORIGIN
           )

           return payload

       except PyJWTError as error:
           print("Token validation failed:", error)
           return None
       except Exception as error:
           print("Unexpected error:", error)
           return None


   payload = validate_neon_token("<YOUR_JWT_TOKEN>")

   if payload:
       print("Token is valid. Payload:", payload)
   else:
       print("Token is invalid.")
   ```

   > Replace `<YOUR_JWT_TOKEN>` with the actual JWT token you want to verify.

**Go**

1. Install the library:

   ```bash
   go get github.com/golang-jwt/jwt/v5
   go get github.com/MicahParks/keyfunc/v3
   ```

2. Use the following example code as a reference to verify a JWT:

   ```go
   package main

   import (
       "fmt"
       "log"
       "net/url"
       "os"

       "github.com/MicahParks/keyfunc/v3"
       "github.com/golang-jwt/jwt/v5"
   )

   func ValidateNeonToken(tokenString string) (jwt.MapClaims, error) {
       baseURL := os.Getenv("NEON_AUTH_BASE_URL")
       if baseURL == "" {
           return nil, fmt.Errorf("NEON_AUTH_BASE_URL is not set")
       }

       jwksURL := fmt.Sprintf("%s/.well-known/jwks.json", baseURL)

       u, err := url.Parse(baseURL)
       if err != nil {
           return nil, fmt.Errorf("failed to parse base URL: %w", err)
       }
       expectedIssuer := fmt.Sprintf("%s://%s", u.Scheme, u.Host)

       jwks, err := keyfunc.NewDefault([]string{jwksURL})
       if err != nil {
           return nil, fmt.Errorf("failed to create JWKS from resource at %s: %w", jwksURL, err)
       }

       token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
           return jwks.Keyfunc(token)
       },
           jwt.WithIssuer(expectedIssuer),
           jwt.WithValidMethods([]string{"EdDSA"}),
       )

       if err != nil {
           return nil, err
       }

       if claims, ok := token.Claims.(jwt.MapClaims); ok && token.Valid {
           return claims, nil
       }

       return nil, fmt.Errorf("invalid token claims")
   }

   func main() {
       tokenString := "<YOUR_JWT_TOKEN>"

       claims, err := ValidateNeonToken(tokenString)
       if err != nil {
           log.Printf("Token validation failed: %v\n", err)
           return
       }

       fmt.Printf("Token is valid. Payload: %+v\n", claims)
   }
   ```

   > Replace `<YOUR_JWT_TOKEN>` with the actual JWT token you want to verify.

## Limitations

Because Managed Better Auth is a managed service, certain server-side configurations available in the standalone Better Auth library are pre-configured by Neon and cannot be changed:

- **Signing algorithm:** Managed Better Auth uses **EdDSA (Ed25519)** by default for high security and performance. Ensure your verification libraries support this algorithm.
- **Expiration:** Tokens expire in **15 minutes** (access tokens). Call `authClient.getSession()` whenever you need a token. The SDK fetches a new one when the cached token is about to expire.
- **Custom claims:** Currently, the JWT payload contains the default user information. Custom claims are not supported at this time.

## Troubleshooting

### Token rejection

If a token is rejected during verification, check the following:

1. Verify that you are using the correct JWKS endpoint for your Managed Better Auth instance. The issuer (`iss`) and audience (`aud`) of the token must both match the origin of your Managed Better Auth URL, not the full URL. For example, if your Managed Better Auth URL is `https://ep-xx.aws.neon.tech/neondb/auth`, both should be `https://ep-xx.aws.neon.tech`.
2. Confirm that your verification library supports **EdDSA** (Ed25519).
3. Make sure the token has not expired.
4. Check that the `kid` in the JWT header matches one of the keys in the JWKS response. If not, fetch the latest keys from the JWKS endpoint.

--- [Document source](https://neon.com/docs/auth/guides/plugins/magic-link.md) ---

> Summary: Magic Link is a Managed Better Auth plugin that lets users sign in without a password by clicking a time-limited link sent to their email, with expiration configurable from 5 to 1440 minutes. Use this page when you want to add passwordless email authentication to a project that already has Managed Better Auth enabled, using either the Neon SDK's `signIn.magicLink()` method or Better Auth UI's Magic Link plugin (`magicLinkPlugin()`). The plugin also supports a webhook event (`send.magic_link`) to bypass the built-in mailer and deliver links through a custom email provider.

# Magic Link

Passwordless sign-in via email magic links

Last updated: 2026-10-09

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/) and provides full support for the [Magic Link](https://www.better-auth.com/docs/plugins/magic-link) plugin APIs through the Neon SDK. You do not need to manually install or configure the Better Auth Magic Link plugin.

Magic Link lets users sign in by clicking a link sent to their email. No password is required. The flow works like this:

1. The user enters their email address.
2. Managed Better Auth sends an email containing a unique, time-limited link.
3. The user clicks the link, which verifies the token, creates a session, and redirects them to your app.

## Prerequisites

- A Neon project with **Auth enabled**
- The **Magic Link plugin enabled** (see [Enable Magic Link](https://neon.com/docs/auth/guides/plugins/magic-link#enable-magic-link) below)

## Enable Magic Link

**Console**

1. Open the [Neon Console](https://console.neon.tech).
2. Select your project and go to **Settings** > **Better Auth**.
3. In the **Magic Link** section, toggle **Enable Magic Link** on.
4. Configure the options:
   - **Link Expiration** (5-1440 minutes, default: 5) controls how long a magic link stays valid.
   - **Allow New User Registration** controls whether magic links can be used to create new accounts. When off, magic links only work for existing users.

**API**

Send a `PATCH` request to configure the Magic Link plugin. All request body fields are optional; send only the fields you want to change.

```bash
curl -X PATCH \
  "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/plugins/magic-link" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "expires_in": 5,
    "disable_sign_up": false
  }'
```

| Field             | Type    | Default | Description                                           |
| ----------------- | ------- | ------- | ----------------------------------------------------- |
| `enabled`         | boolean | `false` | Whether the Magic Link plugin is active               |
| `expires_in`      | integer | `5`     | Minutes before the magic link expires (5-1440)        |
| `disable_sign_up` | boolean | `false` | When `true`, magic links only work for existing users |

## Use Magic Link with SDK methods

Build a custom magic link flow using the [Neon SDK](https://neon.com/docs/reference/javascript-sdk). Call `signIn.magicLink()` with the user's email and a callback URL. Managed Better Auth sends the email and redirects the user to `callbackURL` after they click the link.

```ts filename="src/send-magic-link.ts"
import { authClient } from '@/lib/auth/client';

export async function sendMagicLink(email: string) {
  const { error } = await authClient.signIn.magicLink({
    email,
    callbackURL: '/dashboard',
  });

  if (error) throw error;
}
```

After calling `signIn.magicLink()`, show the user a "check your email" message. For a complete working example with error handling, resend, and state management, see the [magic link example app](https://github.com/neondatabase/neon-js/tree/main/examples/neon-auth-magic-link-example) in the neon-js repository.

## Use Magic Link with UI components

If you're already using [Better Auth UI](https://neon.com/docs/auth/reference/ui-components), add its Magic Link components and pass the plugin to `AuthProvider` instead of building a custom form:

```bash
npx shadcn@latest add @better-auth-ui/magic-link
```

```tsx filename="components/providers.tsx"
import { magicLinkPlugin } from '@/lib/auth/magic-link-plugin';

<AuthProvider
  authClient={authClient}
  navigate={navigate}
  Link={Link}
  plugins={[magicLinkPlugin()]}
>
  {children}
</AuthProvider>
```

Add the plugin's views to your auth route's paths with `magicLinkPlugin().viewPaths.auth` from `@better-auth-ui/core/plugins/magic-link`. The UI plugin doesn't enable Magic Link on your branch; enable it in Managed Better Auth first.

Users can now sign in with a magic link by selecting the option on the sign-in screen and entering their email.

> If you haven't set up Better Auth UI yet, see the [UI components reference](https://neon.com/docs/auth/reference/ui-components) for setup, or the [Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only) or [React](https://neon.com/docs/auth/quick-start/react) quick start for building custom forms instead.

## Webhooks

If you subscribe to the `send.magic_link` event, Managed Better Auth skips its built-in email and calls your webhook instead, passing `link_type: "sign-in"` in the payload. Your handler is responsible for delivering the link (for example, via a custom email template or SMS).

See the [Webhooks guide](https://neon.com/docs/auth/guides/webhooks) for configuration details and payload format.

## Email provider configuration

For production environments, we strongly recommend using a dedicated email provider. The default shared SMTP should be used only during development. See the [Email provider configuration guide](https://neon.com/docs/auth/production-checklist#email-provider) for setup instructions.

--- [Document source](https://neon.com/docs/auth/guides/plugins/oauth-provider.md) ---

> Summary: The OAuth provider plugin turns Managed Better Auth into an OAuth 2.1 authorization server for your own apps. Use it to protect an MCP server so MCP clients can sign in your users, or to let other apps call your API on behalf of your users. Covers enabling the plugin in the Console or API, the login and consent pages you host, Client ID Metadata Documents and legacy dynamic client registration, managed confidential and public clients, scopes and refresh tokens, and how a resource server verifies the issuer, audience, and signature of access tokens.

# OAuth Provider

Let your MCP server, API, or other apps sign in your Managed Better Auth users

Last updated: 2026-11-06

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/) and can act as an OAuth 2.1 authorization server for your own apps. With the OAuth provider plugin enabled, Managed Better Auth issues access tokens to OAuth clients on behalf of your signed-in users, and your MCP server or API verifies those tokens.

Use it to:

- **Protect an MCP server.** MCP clients discover your authorization server, identify themselves with a [Client ID Metadata Document](https://neon.com/docs/auth/guides/plugins/oauth-provider#client-id-metadata-documents) (CIMD), and call your tools with an access token for your users. Legacy [dynamic client registration](https://neon.com/docs/auth/guides/plugins/oauth-provider#dynamic-client-registration-legacy) (DCR) is available as an opt-in. MCP support is part of this plugin, not a separate plugin: you set it up with the **Server URL** field in the **MCP server** section.
- **Sign in your users to another app or API.** A web app, single-page app, desktop app, or CLI runs the authorization code flow with PKCE and calls your API with the resulting token.

The OAuth provider plugin is available to all Managed Better Auth projects.

## Prerequisites

- A Neon project with **Auth enabled**.
- **A login page and a consent page, both hosted by you.** Both are required. Managed Better Auth doesn't provide default pages. Authorization requests redirect users to your login page, and then to your consent page to approve the client. See [Build your consent page](https://neon.com/docs/auth/guides/plugins/oauth-provider#build-your-consent-page) and [How the pages complete the flow](https://neon.com/docs/auth/guides/plugins/oauth-provider#how-the-pages-complete-the-flow).
- The origin of each page added as a [trusted domain](https://neon.com/docs/auth/guides/configure-domains) for the branch. Pages must use `https`, with no query string or fragment. `http` is allowed on `localhost` when [localhost access](https://neon.com/docs/auth/guides/manage-auth-api#related-auth-endpoints) is enabled for the branch.
- At least one protected resource: an MCP server URL, or an API identifier. A resource is an absolute URL that identifies what the token is for. It becomes the token's `aud` claim and doesn't need to resolve.

Configuration is per branch. Each branch has its own issuer, OAuth clients, and settings.

## Enable the OAuth provider

**Console**

1. Open the [Neon Console](https://console.neon.tech).
2. Select your project and go to **Settings** > **Better Auth**.
3. In the **OAuth provider** section, toggle **Enable OAuth provider** on.
4. Fill in the settings:
   - **Login page URL**: where authorization requests redirect for sign-in.
   - **Consent page URL**: where authorization requests redirect for user consent.
   - **Server URL** (in the **MCP server** section): the URL of your MCP server, if you're protecting one. MCP is configured here, in the OAuth provider panel.
   - **Client ID Metadata Documents**: on by default once you set a server URL. See [Client ID Metadata Documents](https://neon.com/docs/auth/guides/plugins/oauth-provider#client-id-metadata-documents).
   - **Dynamic client registration (legacy)**: off by default. Requires a server URL. See [Dynamic client registration (legacy)](https://neon.com/docs/auth/guides/plugins/oauth-provider#dynamic-client-registration-legacy).
   - **Resource URLs**: URLs of other APIs that clients can request tokens for.
5. Click **Enable**.

You need an MCP server URL or at least one protected resource to enable the provider.

**CLI**

Use [`neon neon-auth config oauth-server`](https://neon.com/docs/cli/neon-auth#config-oauth-server). Add a protected resource, then enable the server with its login and consent pages, which must be on a [trusted domain](https://neon.com/docs/auth/guides/configure-domains):

```bash
neon neon-auth config oauth-server resource add https://api.example.com/reports
neon neon-auth config oauth-server update --enabled --login-page https://app.example.com/login --consent-page https://app.example.com/consent
```

To protect an MCP server, add `--mcp-resource https://mcp.example.com/mcp`. `neon neon-auth config oauth-server get` shows the current configuration.

**API**

Send a `PATCH` request to the [update OAuth provider plugin](https://neon.com/docs/reference/api/auth/update-neon-auth-o-auth-provider-plugin) endpoint. A `GET` on the same path ([retrieve](https://neon.com/docs/reference/api/auth/get-neon-auth-o-auth-provider-plugin)) returns the current configuration.

```bash
curl -X PATCH \
  "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/plugins/oauth-provider" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "login_page": "https://app.example.com/login",
    "consent_page": "https://app.example.com/consent",
    "mcp": {
      "resource": "https://mcp.example.com/mcp"
    },
    "resources": [
      { "identifier": "https://api.example.com/reports" }
    ]
  }'
```

The response returns the stored configuration:

```json
{
  "enabled": true,
  "login_page": "https://app.example.com/login",
  "consent_page": "https://app.example.com/consent",
  "mcp": {
    "resource": "https://mcp.example.com/mcp",
    "dynamic_registration": false,
    "client_id_metadata_documents": true
  },
  "resources": [{ "identifier": "https://api.example.com/reports" }]
}
```

| Field                              | Type    | Description                                                                                                                                                   |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`                          | boolean | Whether the OAuth provider is active                                                                                                                          |
| `login_page`                       | string  | URL of your login page                                                                                                                                        |
| `consent_page`                     | string  | URL of your consent page                                                                                                                                      |
| `mcp.resource`                     | string  | URL of your MCP server. Required whenever `mcp` is sent                                                                                                       |
| `mcp.client_id_metadata_documents` | boolean | Allow MCP clients to identify themselves with a Client ID Metadata Document. Defaults to `true`; takes effect only when `mcp.resource` is set                 |
| `mcp.dynamic_registration`         | boolean | Legacy. Allow MCP clients to register themselves with RFC 7591 dynamic client registration. Defaults to `false`; takes effect only when `mcp.resource` is set |
| `resources`                        | array   | Other protected resources, as `{ "identifier": "<url>" }` objects. Up to 10                                                                                   |

To remove MCP support, send `"mcp": { "resource": "" }`. CIMD and DCR then have no effect, and clients that onboarded through them stop working. Omitted fields keep their current values. A provided `resources` list replaces the stored list, so send the full list when you add a resource. A provided `mcp` object must include `resource`; its toggles keep their stored values when omitted.

Enabling requires `login_page`, `consent_page`, and at least one of `mcp.resource` or `resources`. Resource identifiers must be absolute `https` URLs (or `http` on a loopback host) without credentials, query string, or fragment. They can't point at your Managed Better Auth host.

## Protect an MCP server

An MCP client connects to your MCP server and learns where to authenticate from the server's protected resource metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728)). The flow is:

1. The client calls your MCP server and receives a `401` response that points to the server's protected resource metadata.
2. The metadata lists your Managed Better Auth issuer as the authorization server. The client reads the issuer's metadata to find the authorize and token endpoints, and whether the issuer supports client ID metadata documents. The issuer serves the same metadata at `<issuer>/.well-known/oauth-authorization-server` and `<issuer>/.well-known/openid-configuration`, so clients that append the well-known path to the issuer URL find it either way.
3. The client identifies itself, usually with a [Client ID Metadata Document](https://neon.com/docs/auth/guides/plugins/oauth-provider#client-id-metadata-documents) (or, if you enabled it, [dynamic client registration](https://neon.com/docs/auth/guides/plugins/oauth-provider#dynamic-client-registration-legacy)).
4. The user signs in on your login page and approves the client on your consent page.
5. The client exchanges the authorization code (with PKCE) for an access token and calls your MCP server with it.

Your MCP server is responsible for two things: serving its protected resource metadata, and verifying access tokens.

For a full walkthrough that runs the MCP server on a Neon Function with Managed Better Auth, see [Build an MCP server with Managed Better Auth](https://neon.com/docs/compute/functions/mcp-server).

### Find the issuer

The issuer is the Auth URL of the branch, for example `https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth`. Copy it from the Console, or read `base_url` from `GET .../auth`. Don't build it from the endpoint ID. The issuer is different on every branch, so keep it in configuration per branch and check that the `issuer` field of the metadata document equals it.

### Verify access tokens

When the client sends the `resource` parameter, access tokens are signed JWTs (EdDSA). Verify them against the JWKS at `<issuer>/.well-known/jwks.json`. Your resource server must check both of these claims:

- `iss` equals the exact issuer of your branch.
- `aud` contains the exact resource identifier of your server.

**Important: Verify iss and aud, not only the signature**

All branches of a project share the same signing keys, and only the issuer (`iss`) differs per branch. A token issued by one branch has a valid signature on every other branch, so the signature alone doesn't tell you which branch issued it. A resource server must verify `iss` against the issuer of its own branch and `aud` against its own resource identifier. The `aud` claim can be an array: with the `openid` [scope](https://neon.com/docs/auth/guides/plugins/oauth-provider#scopes-and-refresh-tokens) it also contains the issuer's userinfo endpoint, so check for membership rather than equality. When you create a branch, it starts with the parent's OAuth clients (same client ID and secret), so also pin the issuer in each branch's resource server.

The following example protects an MCP server built with the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) and Express. The [`@neon/oauth`](https://www.npmjs.com/package/@neon/oauth) SDK (beta) does the token work: install it with `npm install @neon/oauth`.

```ts filename="src/server.ts"
import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { createMcpAuth } from '@neon/oauth/mcp';
import { expressMcp } from '@neon/oauth/mcp/express';

const auth = createMcpAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!, // the Auth URL of your branch
  resource: 'https://mcp.example.com/mcp', // the MCP server URL configured on the provider
});

const app = express();
app.use(expressMcp(auth));
app.use(express.json());

// A stateless transport serves one request, so create the server and transport per request.
app.post('/mcp', async (req, res) => {
  const server = new McpServer({ name: 'reports', version: '1.0.0' });
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });
  res.on('close', () => {
    transport.close();
    server.close();
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);
```

`createMcpAuth()` verifies the signature, `iss`, and `aud` of each access token. `expressMcp()` serves the protected resource metadata, answers requests without a valid token with a `401` that points to it, and sets `req.auth` for valid ones, in the MCP SDK's `AuthInfo` shape, so the transport passes it to your tools as `extra.authInfo`. The full verification result is on `req.authResult`. Use `@neon/oauth` 0.3.0 or later. The SDK also has adapters for Hono, Next.js, and `node:http`.

#### Without the SDK

The same server using only [`jose`](https://github.com/panva/jose) and the MCP TypeScript SDK:

```ts filename="src/server.ts"
import express from 'express';
import { createRemoteJWKSet, errors, jwtVerify } from 'jose';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
import { requireBearerAuth } from '@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js';
import {
  getOAuthProtectedResourceMetadataUrl,
  mcpAuthMetadataRouter,
} from '@modelcontextprotocol/sdk/server/auth/router.js';
import { InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';

const AUTH_URL =
  'https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth'; // the Auth URL of your branch
const RESOURCE = new URL('https://mcp.example.com/mcp'); // the MCP server URL configured on the provider

const discovery = await fetch(
  `${AUTH_URL}/.well-known/oauth-authorization-server`
);
if (!discovery.ok) {
  throw new Error(`Discovery failed with status ${discovery.status}`);
}
const oauthMetadata = await discovery.json();
if (oauthMetadata.issuer !== AUTH_URL) throw new Error('Unexpected issuer'); // RFC 8414 section 3.3

const jwks = createRemoteJWKSet(new URL(oauthMetadata.jwks_uri));

const verifier = {
  async verifyAccessToken(token: string) {
    try {
      const { payload } = await jwtVerify(token, jwks, {
        issuer: AUTH_URL, // exact match
        audience: RESOURCE.href, // must be one of the token's aud values
        algorithms: ['EdDSA'],
      });
      return {
        token,
        clientId: String(payload.client_id ?? ''),
        scopes: String(payload.scope ?? '')
          .split(' ')
          .filter(Boolean),
        expiresAt: payload.exp,
        resource: RESOURCE,
        extra: { sub: payload.sub },
      };
    } catch (error) {
      if (error instanceof errors.JOSEError) {
        throw new InvalidTokenError('Invalid access token');
      }
      throw error;
    }
  },
};

const app = express();

// Serves /.well-known/oauth-protected-resource/mcp, which names the issuer as the authorization server.
// It also mirrors the authorization server metadata at /.well-known/oauth-authorization-server on this origin.
app.use(mcpAuthMetadataRouter({ oauthMetadata, resourceServerUrl: RESOURCE }));

app.use(
  '/mcp',
  requireBearerAuth({
    verifier,
    resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(RESOURCE),
  })
);
app.use(express.json());

// A stateless transport serves one request, so create the server and transport per request.
// requireBearerAuth sets req.auth, which the transport passes to your tool handlers.
app.post('/mcp', async (req, res) => {
  const server = new McpServer({ name: 'reports', version: '1.0.0' });
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });
  res.on('close', () => {
    transport.close();
    server.close();
  });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000);
```

### Client ID Metadata Documents

With Client ID Metadata Documents (CIMD), an MCP client uses an `https` URL as its `client_id`. The URL serves a JSON document that describes the client, including its `client_name` and `redirect_uris`. Managed Better Auth fetches the document the first time the client is used, so you don't create clients for MCP clients that support CIMD. CIMD is on by default once you set an MCP server, and the authorization server metadata advertises `client_id_metadata_document_supported`. If you build an MCP client, `createClientMetadataDocument` from `@neon/oauth` produces a valid document.

A CIMD client:

- Is a public client that uses PKCE, or a confidential client that authenticates with `private_key_jwt` and publishes its public keys in the document (`jwks` or `jwks_uri`). Symmetric methods such as `client_secret_basic` are rejected.
- Can request tokens for the MCP server resource only. The document can't link the client to other resources.
- Can't skip the consent screen. A document that sets `skip_consent` is rejected with `invalid_client`.
- Must use redirect URIs that follow the [redirect URI rules](https://neon.com/docs/auth/guides/plugins/oauth-provider#redirect-uri-rules). A loopback `http` redirect URI matches on any port. All other redirect URIs must match the document exactly.

Clear **Client ID Metadata Documents** in the Console, or set `mcp.client_id_metadata_documents` to `false` in the API, if you want to control which clients can request tokens. New CIMD clients are then rejected and existing ones stop working. Clients you create yourself keep working.

**Warning: Consent screens for self-onboarded clients**

A client's name comes from a document the client controls (or, with DCR, from anyone who registers), so don't treat it as proof of identity. Follow [Build your consent page](https://neon.com/docs/auth/guides/plugins/oauth-provider#build-your-consent-page) so users can tell what they're approving.

### Dynamic client registration (legacy)

Dynamic client registration (DCR, [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) is the older way for MCP clients to register themselves, at the issuer's `/oauth2/register` endpoint. Prefer [Client ID Metadata Documents](https://neon.com/docs/auth/guides/plugins/oauth-provider#client-id-metadata-documents). DCR is off by default. To accept clients that only support DCR, turn on **Dynamic client registration (legacy)** (`mcp.dynamic_registration: true`), which requires an MCP server URL. It applies only to your MCP server resource. A client registered this way can request tokens for the MCP server only, and it can't skip the consent screen on first use. While DCR is on, anyone can register a client with any name and redirect URI, so the consent-screen warning above applies in full.

Branches configured before October 2026 may have relied on DCR being on by default. If yours did, set `mcp.dynamic_registration` to `true` explicitly to keep it.

While DCR is off, `/oauth2/register` returns `403`, and the authorization server metadata omits `registration_endpoint`. Turning DCR off stops new registrations only. Existing clients are unaffected: to stop one, disable or delete it.

### Build your consent page

You host the consent page, so you control what users see before they approve a client. Show:

- The client name.
- The client's host, if the client registered a client URI.
- The host of each redirect URI, because that's where the authorization code is sent.
- The scopes the client requests and the resource it wants a token for. Both are in the `scope` and `resource` parameters of the authorization request your page receives.

Warn the user when the only redirect URIs are `localhost` or loopback addresses. The client then runs on the user's own machine, and a self-asserted name gives no assurance about who built it.

Users approve a client once. Later authorizations for the same client, scopes, and resource reuse the stored consent, and your consent page is shown again when a client asks for scopes or a resource the user hasn't approved.

### How the pages complete the flow

Both pages receive the authorization request as query parameters. The query is signed and expires, so pass it back to Managed Better Auth exactly as received, as the `oauth_query` value.

- **Login page.** The authorization request redirects here when the user has no session. Send `oauth_query` in the body of the sign-in request. This works for email and password sign-in and for social sign-in, such as Google or GitHub. Managed Better Auth verifies the signature, signs the user in, and resumes the authorization request. With email and password, the sign-in response tells your page where to go next, usually your consent page. With social sign-in, the provider returns the user to your login page, signed in, with the same query. When your login page loads with a session, send `POST <issuer>/oauth2/continue` with `{ "selected": true, "oauth_query": "<query>" }` and navigate to the returned `url`. Do the same when a signed-in user reaches the login page.
- **Consent page.** Show what the user is approving, then send `POST <issuer>/oauth2/consent` with a JSON body of `{ "accept": true, "oauth_query": "<query>" }`, or `"accept": false` to deny. The response is JSON with a `redirect` flag and the `url` to navigate the browser to. That URL is the client's redirect URI with the authorization code, or an error.
- **Client details.** To display the client name, call `GET <issuer>/oauth2/public-client?client_id=<client_id>` with the user's session. It returns `client_id` and `client_name` for every client. Clients that identify with a Client ID Metadata Document also return the `client_uri` and `logo_uri` from their document when it sets them. Managed clients don't have these fields.

For example, the buttons on your consent page can call:

```ts filename="consent.ts"
const ISSUER = 'https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth'; // the Auth URL of your branch

async function respond(accept: boolean) {
  const res = await fetch(`${ISSUER}/oauth2/consent`, {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      accept,
      oauth_query: window.location.search.slice(1), // the query exactly as received
    }),
  });
  if (!res.ok) throw new Error(`Consent failed with status ${res.status}`);
  const { url } = await res.json();
  window.location.assign(url); // the client's redirect URI, with the code or an error
}
```

Calls from your pages carry the user's session cookie, so make them with `credentials: 'include'` and add your pages' origins as [trusted domains](https://neon.com/docs/auth/guides/configure-domains). Navigate the browser to the returned `url`. Neither the sign-in nor the consent response is an HTTP redirect.

**Tip: Use the Neon Auth client**

If your pages use [`@neon/auth`](https://neon.com/docs/auth/overview) 0.8.0 or later (or `@neon/neon-js` 0.10.0 or later), the client handles `oauth_query` for you. Sign-in requests on your login page attach it automatically. When your login page loads with a session, call `authClient.oauth2.continue({ selected: true })`. On your consent page, `authClient.oauth2.consent({ accept })` replaces the `fetch` call above. The client navigates to the returned `url` itself, so don't navigate again.

## Sign in users to your own apps and APIs

To let an app call your API on behalf of your users, add the API as a protected resource and create a managed OAuth client for the app.

1. Add the API identifier under **Resource URLs**, or in the `resources` list of the API request.
2. [Create an OAuth client](https://neon.com/docs/auth/guides/plugins/oauth-provider#create-and-manage-oauth-clients) linked to that resource.
3. In the app, run the authorization code flow with PKCE. Send the API identifier as the `resource` parameter on both the authorize and token requests.
4. The API verifies the access token the same way as the MCP example above, with its own identifier as the expected `aud`.

Send the user to the authorize endpoint of the issuer with the PKCE challenge, the `resource`, and the scopes you need (see [Scopes and refresh tokens](https://neon.com/docs/auth/guides/plugins/oauth-provider#scopes-and-refresh-tokens)):

```text
https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth/oauth2/authorize
  ?response_type=code
  &client_id=<CLIENT_ID>
  &redirect_uri=https%3A%2F%2Freports.example.com%2Fcallback
  &scope=openid%20offline_access
  &state=<STATE>
  &code_challenge=<CODE_CHALLENGE>
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.example.com%2Freports
```

The authorize endpoint is `authorization_endpoint` in the issuer's metadata. After the user signs in and approves the client on your [pages](https://neon.com/docs/auth/guides/plugins/oauth-provider#how-the-pages-complete-the-flow), the browser returns to `redirect_uri` with `code` and `state`.

A confidential client exchanges the code on the server and authenticates with `client_secret_basic`:

```bash
curl -X POST "$ISSUER/oauth2/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d code_verifier="$CODE_VERIFIER" \
  -d redirect_uri="https://reports.example.com/callback" \
  -d resource="https://api.example.com/reports"
```

A token is issued for the `resource` requested in that call. A token for your API isn't valid at your MCP server, and the reverse.

The `@neon/oauth` SDK (beta) implements this flow for you. `createOAuth()` from `@neon/oauth` handles discovery, PKCE sign-in with encrypted session cookies, token refresh, and token verification for your API. It has adapters for Hono, Express, Next.js, and `node:http`. The sign-in client uses `node:crypto` for cookie encryption, so it doesn't run on the Edge runtime. Token verification doesn't have that limit.

## Create and manage OAuth clients

Managed clients are for resources that clients can't register for themselves. You can also link a managed client to your MCP server resource, which is how you onboard known clients when you turn off CIMD and DCR.

If you work with an AI assistant, the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server) can also manage the provider and its clients with the `*_auth_oauth_server` and `*_auth_oauth_client` tools.

**Warning: Keep the MCP server URL out of the resources list**

For an MCP server, set the URL in `mcp.resource` (the **Server URL** field) and turn off `client_id_metadata_documents` and `dynamic_registration` so that only managed clients can connect. Don't list the MCP server URL under `resources` instead. The refresh-token reuse window (30 seconds) is configured only when `mcp.resource` is set. Without it, an MCP client that refreshes concurrently presents an already-rotated refresh token, and Managed Better Auth revokes that user's refresh tokens for the client.

| Type           | Secret                    | Token endpoint auth   | Typical use                                |
| -------------- | ------------------------- | --------------------- | ------------------------------------------ |
| `confidential` | Client secret, shown once | `client_secret_basic` | Server-side web apps and backends          |
| `public`       | None                      | `none`, with PKCE     | Single-page, mobile, desktop, and CLI apps |

The type can't be changed after creation. Redirect URIs must match exactly.

**Console**

Under the OAuth provider settings, use the **OAuth clients** list:

- **Create OAuth client**: set a name, client type, redirect URIs, and the protected resources the client can request tokens for. For a confidential client, the console shows the client secret once. Copy it before you close the dialog.
- **Edit**: change the name, redirect URIs, resources, **Skip consent**, or **Disabled**. A disabled client can't obtain new tokens.
- **Rotate secret**: generates a new secret for a confidential client. The previous secret stops working immediately.
- **Delete**: removes the client.

**CLI**

Use [`neon neon-auth oauth-client`](https://neon.com/docs/cli/neon-auth#oauth-client). Every resource you link must already be configured on the OAuth provider:

```bash
neon neon-auth oauth-client create --name "Reports" --type confidential --redirect-uris https://reports.example.com/callback --resources https://api.example.com/reports
```

For a confidential client, the command prints the client secret only once. Store it before you continue. The `list`, `get`, `update`, `rotate-secret`, and `delete` subcommands manage existing clients.

**API**

Create a client with the [create OAuth client](https://neon.com/docs/reference/api/auth/create-neon-auth-o-auth-client) endpoint. Every entry in `resources` must already be configured on the OAuth provider.

```bash
curl -X POST \
  "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/oauth-provider/clients" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reports",
    "type": "confidential",
    "redirect_uris": ["https://reports.example.com/callback"],
    "resources": ["https://api.example.com/reports"]
  }'
```

The response includes the `client_secret` for confidential clients. It's returned only in this response.

```json
{
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>",
  "name": "Reports",
  "type": "confidential",
  "redirect_uris": ["https://reports.example.com/callback"],
  "resources": ["https://api.example.com/reports"],
  "skip_consent": false,
  "disabled": false,
  "created_at": "2026-01-01T00:00:00Z"
}
```

| Field           | Description                                                                                                                         |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `name`          | Display name, 1-100 characters                                                                                                      |
| `type`          | `confidential` or `public`                                                                                                          |
| `redirect_uris` | 1-10 redirect URIs, following the [redirect URI rules](https://neon.com/docs/auth/guides/plugins/oauth-provider#redirect-uri-rules) |
| `resources`     | 1-11 protected resource identifiers (up to 10 configured resources plus the MCP server resource)                                    |
| `skip_consent`  | Optional. Skip the consent screen for this client. Defaults to `false`                                                              |

The other client operations are under the same path:

| Operation                                                                                       | Request                                                          |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| [List](https://neon.com/docs/reference/api/auth/list-neon-auth-o-auth-clients)                  | `GET .../auth/oauth-provider/clients`                            |
| [Retrieve](https://neon.com/docs/reference/api/auth/get-neon-auth-o-auth-client)                | `GET .../auth/oauth-provider/clients/{client_id}`                |
| [Update](https://neon.com/docs/reference/api/auth/update-neon-auth-o-auth-client)               | `PATCH .../auth/oauth-provider/clients/{client_id}`              |
| [Delete](https://neon.com/docs/reference/api/auth/delete-neon-auth-o-auth-client)               | `DELETE .../auth/oauth-provider/clients/{client_id}`             |
| [Rotate secret](https://neon.com/docs/reference/api/auth/rotate-neon-auth-o-auth-client-secret) | `POST .../auth/oauth-provider/clients/{client_id}/rotate_secret` |

Update accepts `name`, `redirect_uris`, `resources`, `skip_consent`, and `disabled`. At least one field is required, and a provided `redirect_uris` or `resources` list replaces the stored list. Rotating the secret of a public client fails because it has no secret. Deleting a client doesn't revoke tokens that were already issued to it.

### Redirect URI rules

Redirect URIs can't contain a fragment or credentials, and they must match exactly (except for the loopback port rule for CIMD clients). Register only the redirect URIs the app uses: a broad redirect URI lets another app receive the authorization code. What else is accepted depends on how the client is created:

- **Managed clients.** `https`, or `http` on a loopback host (`localhost`, `127.0.0.1`, or `[::1]`) when [localhost access](https://neon.com/docs/auth/guides/manage-auth-api#related-auth-endpoints) is enabled for the branch. Any other URI, including custom schemes such as `myapp://`, makes the request fail.
- **Dynamic client registration.** `https`, `http` on the same loopback hosts, and reverse-domain private-use schemes for native clients (for example, `com.example.app:/callback`). When the registration doesn't set `application_type`, Managed Better Auth drops the redirect URIs that aren't accepted (custom schemes such as `cursor://` among them), and the registration fails only if none remain. A client that relies on a custom scheme can only connect through an `https` or loopback redirect URI.
- **Client ID Metadata Documents.** `https`, `http` on a loopback host, and reverse-domain private-use schemes, as listed in the document. A loopback `http` redirect URI matches on any port.

### Skip consent

**Skip consent** hides the consent screen for a client. Use it only for first-party apps you control. Don't use it for third-party clients, or for public clients: a public client's ID isn't secret, so any app that can receive a registered redirect URI could complete sign-in without the user seeing a consent screen.

## Token details

- **Send `resource`.** If the authorize and token requests don't include the `resource` parameter, Managed Better Auth issues an opaque token instead of a JWT, and your resource server can't verify it.
- **Access tokens** are JWTs signed with EdDSA and expire after one hour. The `aud` claim contains the requested resource. The `client_id` claim identifies the client, and `scope` lists the granted scopes.
- **JWKS** is at `<issuer>/.well-known/jwks.json`.
- **ID tokens** don't include `name` or `email`. Call the issuer's userinfo endpoint (`<issuer>/oauth2/userinfo`) with the access token to get them.
- **Disabling a resource** (removing it from the configuration) stops new tokens from being issued for it. Clients stop listing it until you add it back. Access tokens that were already issued stay valid until they expire.

### Scopes and refresh tokens

The scopes are fixed. A client can request any of these:

| Scope            | Grants                                                           |
| ---------------- | ---------------------------------------------------------------- |
| `openid`         | An ID token, and access to the userinfo endpoint                 |
| `profile`        | `name`, `given_name`, `family_name`, and `picture` from userinfo |
| `email`          | `email` and `email_verified` from userinfo                       |
| `offline_access` | A refresh token, so the client can renew access without the user |

The supported grant types are `authorization_code` and `refresh_token`. Managed clients are created with both. To get a refresh token, request `offline_access` on the authorize request, with PKCE. Refresh tokens expire after 30 days and rotate on every use: each refresh returns a new refresh token. When you [protect an MCP server](https://neon.com/docs/auth/guides/plugins/oauth-provider#protect-an-mcp-server) with `mcp.resource`, Managed Better Auth sets a 30-second refresh-token reuse window for every client on the branch, not only MCP clients: a client can repeat the same refresh request for 30 seconds after the token rotates and gets the same response, so concurrent refreshes from one client succeed.

```bash
curl -X POST "$ISSUER/oauth2/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token="$REFRESH_TOKEN"
```

A refreshed access token keeps the resource of the original authorization unless you send a `resource` that is one of those resources.

## Limitations

- You must host both the login page and the consent page. There's no default UI.
- Self-onboarding (CIMD or DCR) is available for the MCP server resource only. Other resources need managed clients.
- No `client_credentials` grant. Tokens are always issued on behalf of a signed-in user, so machine-to-machine access isn't supported. The authorization server metadata can still list `client_credentials` in `grant_types_supported`, but token requests that use it are rejected.
- CIMD `client_id` URLs must use `https` on the default port (443) and a hostname, not an IP address. They can't point at a Neon domain (such as `neon.tech` or `neon.com`, including subdomains), so a Neon Function URL doesn't work. The document must be served as JSON without redirects and be at most 5 KiB. If the fetch fails for any of these reasons, the client sees a generic "Failed to fetch metadata document" error. See the [redirect URI rules](https://neon.com/docs/auth/guides/plugins/oauth-provider#redirect-uri-rules) for what each kind of client can register.
- Managed clients: up to 100 per branch, 10 redirect URIs each, and links to up to 11 resources: up to 10 configured resources plus the MCP server resource.
- Scopes, token lifetimes, and other provider options aren't configurable.
- Authorization requests with `prompt=login` or `max_age=0` loop back to the login page after sign-in, because continuing the flow doesn't clear these parameters.

--- [Document source](https://neon.com/docs/auth/guides/plugins/openapi.md) ---

> Summary: The OpenAPI plugin for Managed Better Auth ships enabled by default and exposes a Scalar-powered interactive API reference UI at /reference and an OpenAPI 3.x JSON schema endpoint at /open-api/generate-schema. Use it to browse and live-test auth endpoints (session, user, organization, admin) directly against your database, or to import the spec into Postman, Insomnia, or a Scalar SDK generator for type-safe clients in languages without a dedicated Managed Better Auth SDK.

# Open API

Interactive API documentation and client generation

Last updated: 2026-09-16

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/) and comes with the Open API plugin enabled by default. You do not need to manually install or configure it.

The OpenAPI plugin provides two main features:

1. An interactive **API reference UI** (powered by [Scalar](https://scalar.com/)) to explore and test all available Managed Better Auth endpoints.
2. A **JSON Schema endpoint** that you can use to generate type-safe clients for your application.

## Prerequisites

- A Neon project with **Auth enabled**.

## Accessing the API reference

You can view the interactive documentation for your specific project by appending `/reference` to your Managed Better Auth URL.

**URL Format:**

```
<YOUR_NEON_AUTH_URL>/reference
```

**Example:**
`https://ep-xxx.aws.neon.tech/neondb/auth/reference`

This interface allows you to:

- Browse all available endpoints (grouped by Core, Session, User, Plugins, etc).
- View request and response schemas.
- **"Try it out"**: Make real API requests against your database directly from the browser.

![Managed Better Auth Open API Reference](https://neon.com/docs/auth/openapi-reference.png)

**Note: Testing endpoints**

When using the "Try it out" feature, you are interacting with your live database. Be careful when testing endpoints that modify or delete data (like `admin.banUser` or `organization.delete`).

## JSON schema

If you need the raw OpenAPI 3.x specification (for example, to import into Postman or Insomnia), it is available at the `/open-api/generate-schema` endpoint.

**URL format:**

```
<YOUR_NEON_AUTH_URL>/open-api/generate-schema
```

This endpoint returns a standard JSON object describing your authentication API.

## Generating API clients

One of the most powerful use cases for the OpenAPI plugin is generating type-safe API clients for languages that do not yet have a dedicated Managed Better Auth SDK, or for server-side integration where you prefer raw fetch calls.

### Using Scalar SDK generator

If you're using Next.js, you can access the OpenAPI reference page at `/api/auth/reference` in your application, once Managed Better Auth is set up according to the [Next.js quick start](https://neon.com/docs/auth/quick-start/nextjs-api-only). Unlike the default Managed Better Auth reference page, this version can be fully customized to match your application's theme. It also provides additional options, such as generating SDK clients in multiple languages using Scalar's [built‑in tools](https://guides.scalar.com/scalar/scalar-sdks/getting-started).

## Limitations

Because Managed Better Auth is a managed service, the OpenAPI configuration is preset:

- **Path:** The reference UI is always served at `/reference`.
- **Theme:** The UI uses the default Scalar theme and cannot be customized.
- **Discovery:** The reference doc automatically reflects the plugins enabled in your Managed Better Auth instance.

--- [Document source](https://neon.com/docs/auth/guides/plugins/organization.md) ---

> Summary: The Managed Better Auth Organization plugin adds multi-tenancy to apps built on Better Auth, letting each tenant share a Neon branch with role-based access (owner, admin, and member roles). Use it when your app needs workspaces or tenant isolation with invitation workflows, configurable membership limits, and per-branch enable/disable control via the Neon Console or API. The plugin exposes authClient.organization methods for creating, listing, and deleting organizations, inviting and removing members, and checking role permissions client-side.

# Organization

Manage multi-tenant organizations, members, and invitations

Last updated: 2026-10-14

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/) and comes with a pre-configured Organization plugin, so your app can support multi-tenancy without additional setup.

**Note: Beta**

The Organization plugin is currently in **beta**. Support for JWT token claims is available.

## Why use this plugin?

Use the Organization plugin when you need multi-tenancy in your app. It supports:

- Multi-tenant apps where each tenant is an organization
- Workspaces or groups that share a Neon branch (same database)
- Inviting users and assigning roles: owner, admin, or member
- Role-based access: owners and admins can manage the org; the member role has read-only access

Better Auth also has a **Teams** feature (sub-groups within an org); that feature is not currently enabled in Managed Better Auth.

## Prerequisites

- A Neon project with **Auth enabled**
- A signed-in user (organizations are associated with users)

## Example application

**[neon-auth-orgs-example](https://github.com/neondatabase/neon-js/tree/main/examples/neon-auth-orgs-example)** is a multi-tenant sample that uses the Organization plugin with **Drizzle** and **`@neon/auth`** (see that folder's README for **bun** setup from the monorepo root). For other runnable Managed Better Auth apps, see [Example applications](https://neon.com/docs/auth/about#example-applications).

## Configure the organization plugin

The Organization plugin is enabled by default for each branch; you can disable it or change settings in the Console or via the API. If the plugin is disabled, your application users and admins cannot create or manage organizations, and any organization-related API calls will return an error.

**Console**

Open your project in the Neon Console, then go to **Settings** > **Better Auth** and use the **Organizations** section (per branch). This section is available when your project uses **Managed Better Auth**. From there you can customize:

- **Enable Organizations** (toggle): Turn the Organization plugin on or off for the branch. When off, all organization API calls are disabled and return an error.
- **Limit:** Maximum total organization memberships (created + joined) per user. Once reached, the user cannot create new organizations. Default: 10.
- **Membership Limit:** Maximum number of members per organization (default: 100).
- **Creator role:** Role assigned to the user who creates an organization: **Owner** or **Admin**. Choose Admin if you want the org creator to have fewer privileges than Owner (for example, they cannot delete the org or change the owner).
- **Send Invitation Email** (toggle): When on, invited users receive an email with an accept link. This requires **Verify email at signup** to be enabled in the Authentication configuration. Accepting the invitation requires Better Auth UI's organization components (`npx shadcn@latest add @better-auth-ui/organization`, with its `accept-invitation` view) or a custom route that handles `/auth/accept-invitation?invitationId=<INV_ID>` in your application. When off, no email is sent and you handle invitations in your app (for example, via the [invitation ID](https://neon.com/docs/auth/guides/plugins/organization#accept-invitation) or the [user invitation list](https://neon.com/docs/auth/guides/plugins/organization#list-user-invitations)).

**API**

You can also configure the plugin via the [Neon API](https://neon.com/docs/reference/api). Use your API key in the `Authorization` header.

**Get current plugin config (including organization):**

```bash
curl -X GET \
  'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/plugins' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $NEON_API_KEY'
```

Example response (excerpt showing the `organization` object):

```json
{
  "organization": {
    "enabled": true,
    "organization_limit": 10,
    "membership_limit": 100,
    "creator_role": "owner",
    "send_invitation_email": false
  }
}
```

The full response includes other plugin configs (email provider, OAuth, etc.). `creator_role` is either `owner` or `admin`.

**Update the organization plugin:**

Send only the fields you want to change; all request body fields are optional.

```bash
curl -X PATCH \
  'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/plugins/organization' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "enabled": true,
    "organization_limit": 10,
    "membership_limit": 100,
    "creator_role": "owner",
    "send_invitation_email": false
  }'
```

Example response:

```json
{
  "enabled": true,
  "organization_limit": 10,
  "membership_limit": 100,
  "creator_role": "owner",
  "send_invitation_email": false
}
```

### API fields reference

| Field                   | Type                        | Description                                                                                                                          |
| :---------------------- | :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`               | boolean                     | Turn the Organization plugin on or off for the branch. When false, all organization API calls return an error.                       |
| `organization_limit`    | number (≥ 1)                | Max total organization memberships (created + joined) per user. Once reached, the user cannot create new organizations. Default: 10. |
| `membership_limit`      | number (≥ 1)                | Max members per organization. Default: 100.                                                                                          |
| `creator_role`          | string (`owner` \| `admin`) | Role for the user who creates an org. Owner has full control; Admin cannot delete the org or change the owner.                       |
| `send_invitation_email` | boolean                     | When true, invited users receive an email with an accept link. Requires verified email at signup. Default: false.                    |

### API Documentation

- [Get all plugin configurations](https://neon.com/docs/reference/api/auth/get-neon-auth-plugin-configs)
- [Update organization plugin configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-organization-plugin)

## Organizations

Use the following methods to manage the organization lifecycle.

### Create an organization

Creates a new organization. The user creating it automatically becomes the **Owner**.

<details>

<summary>View parameters</summary>

| Parameter                     | Type                               | Required | Notes                                                                 |
| :---------------------------- | :--------------------------------- | :------: | :-------------------------------------------------------------------- |
| name                          | string                             |     ✓    | The display name of the organization                                  |
| slug                          | string                             |     ✓    | A URL-friendly identifier                                             |
| logo                          | string \| undefined                |          | Optional URL to a logo image for the organization                     |
| metadata                      | `Record<string, any>` \| undefined |          | Optional JSON metadata for the organization                           |
| userId                        | string \| undefined                |          | The user ID of the organization creator                               |
| keepCurrentActiveOrganization | boolean \| undefined               |          | If `true`, does not switch the active session to the new organization |

</details>

```ts
const { data, error } = await authClient.organization.create({
  name: 'My Organization',
  slug: 'my-org',
  logo: 'https://example.com/logo.png',
  metadata: { plan: 'pro' },
  keepCurrentActiveOrganization: false,
});
```

### Check organization slug

Checks if an organization slug is available.

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required | Notes             |
| :-------- | :----- | :------: | :---------------- |
| slug      | string |     ✓    | The slug to check |

</details>

```ts
const { data, error } = await authClient.organization.checkSlug({
  slug: 'my-org',
});
```

### List organizations

Lists all organizations the current user is a member of.

<details>

<summary>View parameters</summary>

This method does not take any parameters.

</details>

```ts
const { data, error } = await authClient.organization.list();
```

In a React component, you can use the `useListOrganizations` hook to fetch and display organizations:

```tsx
import { authClient } from './auth';

export default function OrganizationList() {
  const { data: organizations } = authClient.useListOrganizations();
  return (
    <div>
      {organizations?.map((org) => (
        <p>{org.name}</p>
      ))}
    </div>
  );
}
```

### Set active organization

Switches the user's active context to a specific organization.

<details>

<summary>View parameters</summary>

| Parameter        | Type                | Required | Notes                                          |
| :--------------- | :------------------ | :------: | :--------------------------------------------- |
| organizationId   | string \| null      |          | The ID to set as active. Pass `null` to unset. |
| organizationSlug | string \| undefined |          | Alternatively, pass the slug to set as active. |

</details>

```ts
const { data, error } = await authClient.organization.setActive({
  organizationId: 'org_12345678',
});
```

### Get active organization

Retrieves full details of the currently active organization.

<details>

<summary>View parameters</summary>

| Parameter        | Type                | Required | Notes                                                   |
| :--------------- | :------------------ | :------: | :------------------------------------------------------ |
| organizationId   | string \| undefined |          | Optional ID to get details for (defaults to active org) |
| organizationSlug | string \| undefined |          | Optional slug to get details for                        |
| membersLimit     | number \| undefined |          | Limit members returned in the response (default: 100)   |

</details>

```ts
const { data, error } = await authClient.organization.getFullOrganization({
  query: {
    organizationId: 'org-id',
    organizationSlug: 'org-slug',
    membersLimit: 10,
  },
});
```

In a React component, you can use the `useActiveOrganization` hook to fetch and display the active organization:

```tsx
import { authClient } from './auth';

export default function ActiveOrganization() {
  const { data: organization } = authClient.useActiveOrganization();
  return (
    <div>
      <h1>{organization?.name}</h1>
      <p>Members: {organization?.members.length}</p>
    </div>
  );
}
```

### Update organization

Updates organization details. Requires **Owner** or **Admin** permissions.

<details>

<summary>View parameters</summary>

| Parameter      | Type   | Required | Notes                                                                   |
| :------------- | :----- | :------: | :---------------------------------------------------------------------- |
| data           | object |     ✓    | Object containing fields to update (`name`, `slug`, `logo`, `metadata`) |
| organizationId | string |          | The ID of the organization to update                                    |

</details>

```ts
await authClient.organization.update({
  data: {
    name: 'New Name',
    metadata: { plan: 'enterprise' },
  },
  organizationId: 'org-id',
});
```

### Delete organization

Deletes the organization and all associated data. Requires **Owner** permission.

<details>

<summary>View parameters</summary>

| Parameter      | Type   | Required | Notes                                |
| :------------- | :----- | :------: | :----------------------------------- |
| organizationId | string |     ✓    | The ID of the organization to delete |

</details>

```ts
const { data, error } = await authClient.organization.delete({
  organizationId: 'org-id',
});
```

## Invitations

Manage invitations to join an organization.

**Note: Invitation Emails**

Invitation emails are supported when [**Send Invitation Email**](https://neon.com/docs/auth/guides/plugins/organization#configure-the-organization-plugin) is enabled in the organization config. This also requires **Verify email at signup** in the Authentication configuration. Accepting an email invitation requires Better Auth UI's organization components (`npx shadcn@latest add @better-auth-ui/organization`, with its `accept-invitation` view) or a custom route handling `/auth/accept-invitation?invitationId=<INV_ID>` in your app.

When the email toggle is off, handle invitations in your app using the [invitation ID](https://neon.com/docs/auth/guides/plugins/organization#accept-invitation) or the [user invitation list](https://neon.com/docs/auth/guides/plugins/organization#list-user-invitations).

### Invite member

Sends an invitation to a user.

<details>

<summary>View parameters</summary>

| Parameter      | Type                 | Required | Notes                                               |
| :------------- | :------------------- | :------: | :-------------------------------------------------- |
| email          | string               |     ✓    | Email address to invite                             |
| role           | string               |     ✓    | Role to assign (`owner`, `admin`, `member`)         |
| organizationId | string \| undefined  |          | ID of the organization (defaults to active org)     |
| resend         | boolean \| undefined |          | If true, resends email if invitation already exists |

</details>

```ts
const { data, error } = await authClient.organization.inviteMember({
  email: 'new-user@example.com',
  role: 'member',
  resend: true,
});
```

### Accept invitation

Accepts an invitation using the invitation ID.

<details>

<summary>View parameters</summary>

| Parameter    | Type   | Required | Notes                           |
| :----------- | :----- | :------: | :------------------------------ |
| invitationId | string |     ✓    | The ID from the invitation link |

</details>

```ts
const { data, error } = await authClient.organization.acceptInvitation({
  invitationId: 'invitation-id',
});
```

### Reject invitation

Declines an invitation that the user has received and chooses not to accept.

<details>

<summary>View parameters</summary>

| Parameter    | Type   | Required | Notes                              |
| :----------- | :----- | :------: | :--------------------------------- |
| invitationId | string |     ✓    | The ID of the invitation to reject |

</details>

```ts
const { data, error } = await authClient.organization.rejectInvitation({
  invitationId: 'invitation-id',
});
```

### Cancel invitation

Cancel a pending invitation that has been sent to a user.

<details>

<summary>View parameters</summary>

| Parameter    | Type   | Required | Notes                              |
| :----------- | :----- | :------: | :--------------------------------- |
| invitationId | string |     ✓    | The ID of the invitation to cancel |

</details>

```ts
const { data, error } = await authClient.organization.cancelInvitation({
  invitationId: 'invitation-id',
});
```

### Get invitation

Retrieves details of a specific invitation.

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required | Notes                                |
| :-------- | :----- | :------: | :----------------------------------- |
| query.id  | string |     ✓    | The ID of the invitation to retrieve |

</details>

```ts
const { data, error } = await authClient.organization.getInvitation({
  query: {
    id: 'invitation-id',
  },
});
```

### List invitations

Lists all pending invitations for an organization.

<details>

<summary>View parameters</summary>

| Parameter            | Type                | Required | Notes                               |
| :------------------- | :------------------ | :------: | :---------------------------------- |
| query.organizationId | string \| undefined |          | Defaults to the active organization |

</details>

```ts
const { data, error } = await authClient.organization.listInvitations({
  query: {
    organizationId: 'org-id',
  },
});
```

### List user invitations

Lists all invitations received by the current user.

<details>

<summary>View parameters</summary>

This method does not take any parameters.

</details>

```ts
const { data, error } = await authClient.organization.listUserInvitations();
```

## Members

Manage users within the organization.

### List members

Lists members with support for pagination, sorting, and filtering.

<details>

<summary>View parameters</summary>

| Parameter            | Type                                    | Required | Notes                                       |
| :------------------- | :-------------------------------------- | :------: | :------------------------------------------ |
| query.organizationId | string \| undefined                     |          | Defaults to the active organization         |
| query.limit          | number \| undefined                     |          | Items per page (default: 100)               |
| query.offset         | number \| undefined                     |          | Items to skip                               |
| query.sortBy         | string \| undefined                     |          | Field to sort by (for example, `createdAt`) |
| query.sortDirection  | "asc" \| "desc" \| undefined            |          | Sort direction                              |
| query.filterField    | string \| undefined                     |          | Field to filter by                          |
| query.filterOperator | "eq" \| "ne" \| "gt" \| "contains" etc. |          | Operator for filtering                      |
| query.filterValue    | string \| undefined                     |          | Value to filter for                         |

</details>

```ts
const { data, error } = await authClient.organization.listMembers({
  query: {
    limit: 20,
    offset: 0,
    sortBy: 'createdAt',
    sortDirection: 'desc',
    filterField: 'role',
    filterOperator: 'eq',
    filterValue: 'admin',
  },
});
```

### Update member role

Updates a member's role.

<details>

<summary>View parameters</summary>

| Parameter      | Type                | Required | Notes                                              |
| :------------- | :------------------ | :------: | :------------------------------------------------- |
| memberId       | string              |     ✓    | The ID of the member to update                     |
| role           | string\| string\[]  |     ✓    | New role(s) to assign (`owner`, `admin`, `member`) |
| organizationId | string \| undefined |          | Defaults to active organization                    |

</details>

```ts
const { data, error } = await authClient.organization.updateMemberRole({
  memberId: 'member-id',
  role: 'admin',
});
```

### Remove member

Removes a member from the organization.

<details>

<summary>View parameters</summary>

| Parameter       | Type                | Required | Notes                           |
| :-------------- | :------------------ | :------: | :------------------------------ |
| memberIdOrEmail | string              |     ✓    | Member ID or Email address      |
| organizationId  | string \| undefined |          | Defaults to active organization |

</details>

```ts
const { data, error } = await authClient.organization.removeMember({
  memberIdOrEmail: 'member-id-or-email',
});
```

### Get active member

Gets the current user's membership details for the active organization.

<details>

<summary>View parameters</summary>

This method does not take any parameters.

</details>

```ts
const { data, error } = await authClient.organization.getActiveMember();
```

### Get Active Member Role

Gets the current user's role(s) in the active organization.

<details>

<summary>View parameters</summary>

This method does not take any parameters.

</details>

```ts
const { data, error } = await authClient.organization.getActiveMemberRole();
```

### Leave organization

Removes the current user from an organization.

<details>

<summary>View parameters</summary>

| Parameter      | Type   | Required | Notes                               |
| :------------- | :----- | :------: | :---------------------------------- |
| organizationId | string |     ✓    | The ID of the organization to leave |

</details>

```ts
const { data, error } = await authClient.organization.leave({
  organizationId: 'org-id',
});
```

## Access Control

The Organization plugin includes a Role-Based Access Control (RBAC) system.

| Role       | Permissions                                                                                                                                |
| :--------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**  | Full control. Can delete the organization and manage all roles. The user who creates the organization is automatically assigned this role. |
| **Admin**  | Can invite members, update roles, and manage organization settings. Cannot delete the organization.                                        |
| **Member** | Read-only access to organization data. Cannot manage other members.                                                                        |

You can check permissions on the client side using `checkRolePermission`:

```ts
const canDelete = authClient.organization.checkRolePermission({
  permission: {
    organization: ['delete'],
  },
  role: 'admin', // returns false, admins cannot delete orgs
});
// console.log(canDelete); // false
```

## Limitations

Because Managed Better Auth is a managed service, some Better Auth features are not currently supported:

- **Teams:** The Teams sub-feature is not currently enabled.
- **Hooks:** Server-side hooks (for example, `beforeCreateOrganization`) are not supported.
- **Custom Permissions:** You cannot currently define custom roles or modify default permissions.
- **Dynamic Access Control:** Dynamic creation of roles via API is not enabled.

Check the [Managed Better Auth roadmap](https://neon.com/docs/auth/roadmap) for updates on these features.

--- [Document source](https://neon.com/docs/auth/guides/plugins/phone-number.md) ---

> Summary: The Phone Number plugin for Managed Better Auth adds SMS OTP sign-in for existing users: when a user submits their E.164 phone number, Managed Better Auth fires a `send.otp` webhook carrying a numeric code that your handler forwards to your SMS provider (Twilio, Vonage, MessageBird, etc.). Use this page when you need phone OTP sign-in for users who already have a verified phone number linked to their account; phone-first sign-up is not supported. OTP expiry is configurable, requests are rate-limited per IP, and an OTP is invalidated after too many incorrect attempts.

# Phone Number

Sign in existing users with phone OTP codes delivered via your SMS provider

Last updated: 2026-10-09

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/) and supports the [Phone Number](https://www.better-auth.com/docs/plugins/phone-number) plugin through the Neon SDK.

Phone Number lets an existing user sign in with a one-time password (OTP) delivered to their phone. The flow works like this:

1. The user enters their phone number in E.164 format (for example, `+15551234567`).
2. Managed Better Auth generates a 6-digit OTP and fires the `send.otp` webhook with `delivery_preference: "sms"`. Your webhook handler delivers the code via your SMS provider.
3. The user enters the code. Managed Better Auth verifies it, creates a session, and signs them in.

**Important:** The Phone Number plugin is **sign-in only**. Users must already exist in your project with a phone number linked to their account. There is no phone-first sign-up path.

Managed Better Auth does **not** deliver SMS for you. The plugin requires a `send.otp` webhook that forwards codes to your SMS provider (Twilio, MessageBird, Vonage, etc.).

## Prerequisites

- A Neon project with **Auth enabled**
- An existing user with a phone number linked to their account
- A webhook subscribed to the `send.otp` event that forwards the code to your SMS provider (see the [Webhooks guide](https://neon.com/docs/auth/guides/webhooks))

## Enable Phone Number

**Console**

1. Open the [Neon Console](https://console.neon.tech).
2. Select your project and go to **Settings** > **Better Auth**.
3. In the **Phone Authentication** section, toggle **Enable Phone Authentication** on.
4. Configure the options:
   - **OTP Expiry** (60-600 seconds, default: 300) controls how long a generated OTP stays valid.

**API**

Configure the Phone Number plugin with a `PATCH` request. All request body fields are optional; send only the fields you want to change. A `GET` on the same endpoint returns the current configuration.

```bash
curl -X PATCH \
  "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/plugins/phone-number" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "otp_expires_in": 300
  }'
```

Both `PATCH` and `GET` return the configuration:

```json
{
  "enabled": true,
  "otp_expires_in": 300
}
```

| Field            | Type    | Default | Description                               |
| ---------------- | ------- | ------- | ----------------------------------------- |
| `enabled`        | boolean | `false` | Whether the Phone Number plugin is active |
| `otp_expires_in` | integer | `300`   | Seconds before the OTP expires (60-600)   |

## Deliver OTPs via your SMS provider

Managed Better Auth fires the `send.otp` webhook with `delivery_preference: "sms"` when an OTP needs delivery. Your handler must deliver the code through your SMS provider (Twilio, MessageBird, Vonage, etc.). Without a `send.otp` webhook, `authClient.phoneNumber.sendOtp()` fails.

Configure a webhook subscribed to `send.otp` (see the [Webhooks guide](https://neon.com/docs/auth/guides/webhooks) for full setup and signature verification), then branch on `delivery_preference` in your handler:

```ts filename="app/api/webhooks/neon-auth/route.ts"
import { NextResponse } from 'next/server';
import twilio from 'twilio';

const twilioClient = twilio(
  process.env.TWILIO_ACCOUNT_SID!,
  process.env.TWILIO_AUTH_TOKEN!
);

export async function POST(request: Request) {
  const payload = await request.json(); // verify the signature first in production

  if (payload.event_type === 'send.otp' && payload.event_data.delivery_preference === 'sms') {
    const toNumber = payload.user?.phone_number;
    if (!toNumber) {
      return NextResponse.json({ error: 'missing phone number' }, { status: 400 });
    }

    await twilioClient.messages.create({
      from: process.env.TWILIO_FROM_NUMBER!,
      to: toNumber,
      body: `Your code is ${payload.event_data.otp_code}.`,
    });
  }

  return NextResponse.json({ ok: true });
}
```

**Note: User context for first OTPs**

When an unauthenticated user requests their first phone OTP (no prior account linked to that phone number), the webhook `user` object contains the `phone_number` only. Do not rely on `user.name`, `user.email`, or other profile fields when templating the SMS for first-time sends.

For a runnable Next.js handler, signature verification, and a local tunneling setup, see the [nextjs-phone-login example](https://github.com/neondatabase/neon-js/tree/main/examples/nextjs-phone-login).

## Link a phone number to a user

Link a phone to an existing user from an authenticated session by calling `authClient.phoneNumber.verify()` with `updatePhoneNumber: true`:

```ts filename="src/link-phone-number.ts"
import { authClient } from '@/lib/auth/client';

export async function sendLinkingOtp(phoneNumber: string) {
  const { error } = await authClient.phoneNumber.sendOtp({ phoneNumber });
  if (error) throw error;
}

export async function linkPhoneNumber(phoneNumber: string, code: string) {
  const { data, error } = await authClient.phoneNumber.verify({
    phoneNumber,
    code,
    updatePhoneNumber: true,
  });

  if (error) throw error;
  return data;
}
```

For a complete "Add phone number" form with session-aware state (no number, unverified, verified), see the `AddPhoneForm` component in the [nextjs-phone-login example](https://github.com/neondatabase/neon-js/tree/main/examples/nextjs-phone-login).

## Sign in an existing user with phone OTP

Build a two-step phone sign-in form: send the OTP, then verify it. Do **not** pass `updatePhoneNumber`. Omitting it tells Better Auth to sign in the existing user rather than link a phone number:

```ts filename="src/phone-otp.ts"
import { authClient } from '@/lib/auth/client';

export async function sendPhoneOtp(phoneNumber: string) {
  const { error } = await authClient.phoneNumber.sendOtp({ phoneNumber });
  if (error) throw error;
}

export async function signInWithPhoneOtp(phoneNumber: string, code: string) {
  const { data, error } = await authClient.phoneNumber.verify({
    phoneNumber,
    code,
  });

  if (error) throw error;
  return data;
}
```

For a complete working form with resend, error handling, and attempt-budget awareness, see the [nextjs-phone-login example](https://github.com/neondatabase/neon-js/tree/main/examples/nextjs-phone-login).

## Use Phone Number alongside UI components

If you're using [Better Auth UI](https://neon.com/docs/auth/reference/ui-components), render your own phone sign-in form next to `<Auth>` on the sign-in route:

```tsx filename="app/auth/[path]/page.tsx"
import { viewPaths } from '@better-auth-ui/core';
import { Auth } from '@/components/auth/auth';
import { PhoneSignInSection } from './phone-sign-in-section'; // your own component

export default async function AuthPage({ params }: { params: Promise<{ path: string }> }) {
  const { path } = await params;
  const isSignIn = path === viewPaths.auth.signIn;

  return (
    <>
      <Auth path={path} />
      {isSignIn && <PhoneSignInSection />}
    </>
  );
}
```

`PhoneSignInSection` is a component you write that wraps your phone sign-in form. See the [nextjs-phone-login example](https://github.com/neondatabase/neon-js/tree/main/examples/nextjs-phone-login) for a complete implementation.

**Info:** If you haven't set up Better Auth UI yet, see the [UI components reference](https://neon.com/docs/auth/reference/ui-components) for setup, or the [Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only) or [React](https://neon.com/docs/auth/quick-start/react) quick start for building custom forms instead.

## Webhook events

The Phone Number plugin uses two webhook events:

- `send.otp` (blocking). See [Deliver OTPs via your SMS provider](https://neon.com/docs/auth/guides/plugins/phone-number#deliver-otps-via-your-sms-provider).
- `phone_number.verified` (non-blocking). Fires after a user successfully verifies a phone number.

See the [Webhooks guide](https://neon.com/docs/auth/guides/webhooks) for payload structure, signature verification, and retry behavior.

## Limitations

- **Sign-in only.** Users must already exist with a linked, verified phone number. No phone-first sign-up.
- **Bring your own SMS provider.** No built-in SMS delivery. Requires a `send.otp` webhook forwarding to your SMS provider.
- **E.164 format required.** Phone numbers must match `^\+[1-9]\d{1,14}$` (for example, `+15551234567`). Numbers with spaces, dashes, or parentheses are rejected.
- **OTP length is fixed at 6 digits.** Not configurable.
- **Rate limit.** Calls to `/phone-number/*` endpoints are limited to 10 requests per 60 seconds per IP, in addition to Managed Better Auth's global rate limits.
- **Attempt lockout.** After 3 incorrect codes, the OTP is invalidated. Request a new one to try again.

--- [Document source](https://neon.com/docs/auth/guides/setup-oauth.md) ---

> Summary: Managed Better Auth OAuth setup adds Google, GitHub, Vercel, Microsoft, and Apple social sign-in to an application using `signIn.social()`, with Google enabled in development via shared credentials and the other providers requiring custom OAuth app credentials. For production, register the provider's authorized redirect URI as `{NEON_AUTH_BASE_URL}/callback/{provider}` in each provider's console (not the app's callbackURL), and add every callbackURL origin to Managed Better Auth's trusted domains allowlist. Because each Neon branch has its own Auth base URL, OAuth credentials and redirect URIs must be configured per branch; preview deployments can use wildcard trusted domain patterns to cover multiple hosts.

# Set up OAuth

Add Google, GitHub, Vercel, Microsoft, or Apple sign-in to your application

Last updated: 2026-09-17

OAuth lets users sign in with their Google, GitHub, Vercel, Microsoft, or Apple account. Managed Better Auth handles the OAuth flow and creates a session after authorization.

## Development mode

Google OAuth is enabled by default with shared credentials for development and testing. You can start using Google sign-in immediately without any configuration.

### About shared credentials

Shared credentials let you add Google sign-in with no setup, using a Google OAuth app that Neon owns. That one app is shared by every project that uses shared credentials, including projects belonging to other Neon users. It isn't unique to you.

When someone signs in, Google shows them Neon's name and logo, not your app's, because the sign-in runs through Neon's app rather than one you own. Your users are effectively trusting Neon, and you don't control the app's branding, its permission scopes, or the credentials.

This is safe for development and testing. An outside website can't use the shared app to capture your users, because Google only ever redirects sign-ins back to Neon, and Neon keeps each project's sign-ins separate. The reason not to use it in production is trust and control. Real users should see your app on the consent screen, and you should own the credentials.

For production, add your own Google Client ID and secret. See [Production setup](https://neon.com/docs/auth/guides/setup-oauth#production-setup).

**Note:** GitHub, Vercel, Microsoft, and Apple OAuth require custom credentials and are not available with shared credentials. See [Production setup](https://neon.com/docs/auth/guides/setup-oauth#production-setup) to configure your own OAuth apps.

## Sign in with OAuth

Call `signIn.social()` with your provider (`"google"`, `"github"`, `"vercel"`, `"microsoft"`, or `"apple"`). The SDK sends the user to the provider's sign-in page. After the user authorizes, the provider redirects to Managed Better Auth's OAuth callback route (see [Production setup](https://neon.com/docs/auth/guides/setup-oauth#production-setup)), then Managed Better Auth redirects the browser to your **`callbackURL`** (must use a [trusted domain](https://neon.com/docs/auth/guides/configure-domains) in production).

**Google**

```jsx {6} filename="src/App.jsx"
import { authClient } from './auth';

const handleGoogleSignIn = async () => {
  try {
    await authClient.signIn.social({
      provider: "google",
      callbackURL: window.location.origin,
    });
  } catch (error) {
    console.error("Google sign-in error:", error);
  }
};
```

**GitHub**

```jsx {6} filename="src/App.jsx"
import { authClient } from './auth';

const handleGitHubSignIn = async () => {
  try {
    await authClient.signIn.social({
      provider: "github",
      callbackURL: window.location.origin,
    });
  } catch (error) {
    console.error("GitHub sign-in error:", error);
  }
};
```

**Vercel**

```jsx {6} filename="src/App.jsx"
import { authClient } from './auth';

const handleVercelSignIn = async () => {
  try {
    await authClient.signIn.social({
      provider: "vercel",
      callbackURL: window.location.origin,
    });
  } catch (error) {
    console.error("Vercel sign-in error:", error);
  }
};
```

**Microsoft**

```jsx {6} filename="src/App.jsx"
import { authClient } from './auth';

const handleMicrosoftSignIn = async () => {
  try {
    await authClient.signIn.social({
      provider: "microsoft",
      callbackURL: window.location.origin,
    });
  } catch (error) {
    console.error("Microsoft sign-in error:", error);
  }
};
```

**Apple**

```jsx {6} filename="src/App.jsx"
import { authClient } from './auth';

const handleAppleSignIn = async () => {
  try {
    await authClient.signIn.social({
      provider: "apple",
      callbackURL: window.location.origin,
    });
  } catch (error) {
    console.error("Apple sign-in error:", error);
  }
};
```

## Handle the callback

After the OAuth exchange completes, Managed Better Auth redirects the browser to your **`callbackURL`**. Then load or refresh session state in your client:

```jsx {4-9} filename="src/App.jsx"
import { authClient } from './auth';

useEffect(() => {
  authClient.getSession().then(({ data }) => {
    if (data?.session) {
      setUser(data.session.user);
    }
    setLoading(false);
  });
}, []);
```

## Custom redirect URLs

Specify different URLs for new users or errors:

```jsx {3-5} filename="src/App.jsx"
await authClient.signIn.social({
  provider: "google", // or "github", "vercel", "microsoft", "apple"
  callbackURL: "/dashboard",
  newUserCallbackURL: "/welcome",
  errorCallbackURL: "/error",
});
```

## Production setup

For production, configure your own OAuth app credentials. GitHub, Vercel, Microsoft, and Apple OAuth require custom credentials, while Google OAuth works with shared credentials for development but should use custom credentials in production.

### 1. Register redirect URIs with each provider

Managed Better Auth uses [Better Auth](https://www.better-auth.com/) callback routes. For each OAuth provider you enable, register a redirect URI with this shape:

```text
{NEON_AUTH_BASE_URL}/callback/{provider}
```

Use the **Auth base URL** from the Neon Console for that branch. In your app it is usually the `NEON_AUTH_BASE_URL` or `VITE_NEON_AUTH_URL` value, or the URL you pass to `createAuthClient`. Do not add a trailing slash before `/callback`.

Replace `{provider}` with `google`, `github`, `vercel`, `microsoft`, or `apple`.

Example authorized redirect URI for Google:

```text
https://ep-example.neonauth.us-east-2.aws.neon.tech/neondb/auth/callback/google
```

Whether you use the [Next.js auth proxy](https://neon.com/docs/auth/reference/nextjs-server#auth-handler) (`app/api/auth/[...path]/route.ts`) or call Managed Better Auth from the browser, the provider redirects to **`{NEON_AUTH_BASE_URL}/callback/{provider}`** for that branch.

**Important: Do not confuse two different URLs**

The **`callbackURL`** argument in `signIn.social()` is where users land **after** Managed Better Auth finishes the flow. That URL must live on an origin you add under [trusted domains](https://neon.com/docs/auth/guides/configure-domains).

The provider's **authorized redirect URI** is where Google (or GitHub, and so on) sends the browser **during** the OAuth handshake. It must be **`{NEON_AUTH_BASE_URL}/callback/{provider}`**, not your app's homepage or only the `callbackURL`.

Using only your marketing site's URL in Google Cloud Console, or only the `callbackURL`, is a common cause of `redirect_uri_mismatch`.

**Google Cloud Console**

Create an OAuth client with application type **Web application**. Under **Authorized redirect URIs**, add **`{NEON_AUTH_BASE_URL}/callback/google`** for each branch or environment (production, local testing against a branch, previews). Under **Authorized JavaScript origins**, include origins where your UI runs (for example `http://localhost:5173`, `https://myapp.com`) when Google asks for them, and include your Managed Better Auth origin (the scheme and host of `NEON_AUTH_BASE_URL`) if required.

**GitHub**

Set **Authorization callback URL** to **`{NEON_AUTH_BASE_URL}/callback/github`**.

**Vercel**

Set the authorization callback URL to **`{NEON_AUTH_BASE_URL}/callback/vercel`**. In the Vercel app's permissions, enable the **`openid`**, **`email`**, and **`profile`** scopes, which Managed Better Auth requires to create a session. See [Vercel's OAuth app docs](https://vercel.com/docs/sign-in-with-vercel/manage-from-dashboard#create-an-app).

**Microsoft**

See [Microsoft setup](https://neon.com/docs/auth/guides/setup-oauth#microsoft-setup) for the redirect URI, tenant, and email verification settings.

**Apple**

See [Apple setup](https://neon.com/docs/auth/guides/setup-oauth#apple-setup). Apple requires an HTTPS redirect URI, so it can't be used with `localhost`.

### 2. Add trusted domains for your app

Before testing production OAuth, add every origin you pass as **`callbackURL`** (and related URLs) to Managed Better Auth's allowlist. See [Configure trusted domains](https://neon.com/docs/auth/guides/configure-domains).

### 3. Create OAuth apps and paste credentials into Neon

Create OAuth apps with your providers:

- [Google OAuth setup](https://developers.google.com/identity/protocols/oauth2/web-server) (see [Google OAuth branding](https://neon.com/docs/auth/guides/setup-oauth#google-oauth-branding) below before going live)
- [GitHub OAuth setup](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
- [Vercel OAuth setup](https://vercel.com/docs/sign-in-with-vercel/manage-from-dashboard#create-an-app)
- [Microsoft setup](https://neon.com/docs/auth/guides/setup-oauth#microsoft-setup)
- [Apple setup](https://neon.com/docs/auth/guides/setup-oauth#apple-setup)

Then give the **Client ID** and **Client Secret** to Managed Better Auth for that branch. Apple and Microsoft take a few extra fields, described in their sections below.

**Console**

In the Neon Console, open your **project** and select the **branch**, then go to **Settings → Auth**. Under **OAuth providers**, click **Add OAuth provider** (or open an existing provider's **⋮** menu and choose **Configure**).

The dialog shows the exact **authorization callback URL** to register with the provider (for example, `{NEON_AUTH_BASE_URL}/callback/github`). Copy it from the dialog rather than assembling it by hand, then enter your **Client ID** and **Client Secret**.

Click **Add** (or **Update** when editing an existing provider) to save. Neon applies the change to the branch and confirms with a success message. Your app uses the new credentials on the next sign-in. A provider using Neon's shared credentials shows a **Shared credentials** badge until you add your own.

To disable a provider, open its **⋮** menu and choose **Remove**. Its sign-in button no longer appears in your app.

**CLI**

Add a provider with [`neon neon-auth oauth-provider add`](https://neon.com/docs/cli/neon-auth#oauth-provider-add):

```bash
neon neon-auth oauth-provider add --provider-id google --oauth-client-id <client-id> --oauth-client-secret <client-secret>
```

For Apple, pass the `.p8` key file, your Team ID, and the Key ID. For Microsoft, `--microsoft-tenant-id` is optional:

```bash
neon neon-auth oauth-provider add --provider-id apple --oauth-client-id <services-id> --oauth-client-secret-file AuthKey_XXXXXXXXXX.p8 --apple-team-id <team-id> --apple-key-id <key-id>

neon neon-auth oauth-provider add --provider-id microsoft --oauth-client-id <client-id> --oauth-client-secret <client-secret> --microsoft-tenant-id <tenant>
```

**API**

Send a `POST` request to the [add OAuth provider](https://neon.com/docs/reference/api/auth/add-branch-neon-auth-oauth-provider) endpoint. Replace `{project_id}` and `{branch_id}` with your project and branch IDs.

```bash
curl -X POST 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/oauth_providers' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"id": "google", "client_id": "<client-id>", "client_secret": "<client-secret>"}'
```

Apple and Microsoft accept additional fields. For Apple, `client_secret` is the full contents of the `.p8` file, including the `BEGIN` and `END` lines, with newlines encoded as `\n` in JSON:

```json
{
  "id": "apple",
  "client_id": "<services-id>",
  "client_secret": "<contents-of-p8-file>",
  "apple_team_id": "<team-id>",
  "apple_key_id": "<key-id>"
}
```

```json
{
  "id": "microsoft",
  "client_id": "<client-id>",
  "client_secret": "<client-secret>",
  "microsoft_tenant_id": "<tenant>"
}
```

Managed Better Auth will use your configured credentials for that branch.

### Branches and preview deployments

Each branch has its own **`NEON_AUTH_BASE_URL`**. Register **`{NEON_AUTH_BASE_URL}/callback/google`** (and other providers you use) for every branch you test against (for example preview databases).

For preview deployments, trusted domains support **wildcard patterns** (for example `https://*.my-app-preview.vercel.app`), so you can cover many preview hosts without listing each one. See [Configure trusted domains](https://neon.com/docs/auth/guides/configure-domains), [Branching authentication](https://neon.com/docs/auth/branching-authentication), and the API for [trusted domains](https://neon.com/docs/reference/api/auth/add-branch-neon-auth-trusted-domain).

## Microsoft setup

Register an app in the [Microsoft Entra admin center](https://entra.microsoft.com) and give its credentials to Managed Better Auth.

1. Go to **Entra ID** > **App registrations** and select **New registration**.
2. Choose the **Supported account types** that match who should be able to sign in. This setting should agree with the tenant value you set in Neon (see below).
3. Under **Redirect URI**, select the **Web** platform and enter **`{NEON_AUTH_BASE_URL}/callback/microsoft`**.
4. After you register the app, copy the **Application (client) ID**.
5. Go to **Certificates & secrets**, create a **New client secret**, and copy its **Value**. Microsoft shows the value only once.
6. Add the Client ID and Client Secret to the branch, as described in [Create OAuth apps and paste credentials into Neon](https://neon.com/docs/auth/guides/setup-oauth#3-create-oauth-apps-and-paste-credentials-into-neon).

Microsoft client secrets expire. Create a new secret and update the provider in Neon before the old one expires.

### Tenant

By default, Managed Better Auth signs users in against the `common` Microsoft endpoint. To restrict sign-in, set the optional **`microsoft_tenant_id`** (`--microsoft-tenant-id` in the CLI) to one of:

| Value           | Who can sign in                                                  |
| --------------- | ---------------------------------------------------------------- |
| `common`        | Work or school accounts from any tenant, and personal accounts   |
| `organizations` | Work or school accounts from any tenant                          |
| `consumers`     | Personal Microsoft accounts only                                 |
| A tenant ID     | Accounts in that tenant (a GUID)                                 |
| A tenant domain | Accounts in that tenant (for example, `contoso.onmicrosoft.com`) |

The tenant value must be compatible with the **Supported account types** you chose for the app registration. The tenant ID is returned in API responses.

### Email verification

Managed Better Auth treats a Microsoft email as verified only when Microsoft says the user's home tenant owns the email domain. Microsoft sends this in two optional ID token claims, `xms_edov` and `acct`. They aren't in the token by default, so you add them to your app registration.

Without these claims, Microsoft sign-in still works, but the email is treated as unverified:

- If a user with the same email already exists (for example, from Google, GitHub, or email and password), Microsoft sign-in fails with `account_not_linked` and no account is created.
- A new user who signs in with Microsoft is created with an unverified email.
- A signed-in user can't link a Microsoft account, and the attempt fails with `unable_to_link_account`.

To add the claims:

1. In the Entra admin center, go to **Entra ID** > **App registrations** and select your app.
2. Under **Manage**, select **Token configuration**.
3. Select **Add optional claim**, choose the **ID** token type, select `acct` and `xms_edov`, then select **Add**.
4. If you're asked to turn on the Microsoft Graph `email` permission, accept. `xms_edov` is sent only when the token also has the `email` claim.

You can also edit the app manifest (**Manage** > **Manifest**). Keep any optional claims you already have:

```json
"optionalClaims": {
  "idToken": [
    { "name": "acct", "essential": false },
    { "name": "xms_edov", "essential": false },
    { "name": "email", "essential": false }
  ]
}
```

Managed Better Auth marks the email verified only when `xms_edov` is `true` and `acct` is `0`:

- `xms_edov` is `true` when the email belongs to a domain that the user's tenant has verified.
- `acct` is `0` for a member of the tenant and `1` for a guest.

Users who sign in as guests or with a personal Microsoft account don't meet both conditions, so their emails stay unverified. See Microsoft's [optional claims reference](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims-reference) and [Configure optional claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims).

## Apple setup

Sign in with Apple needs four values from your [Apple Developer account](https://developer.apple.com/account):

| Apple value                    | Managed Better Auth field                                         |
| ------------------------------ | ----------------------------------------------------------------- |
| Services ID                    | Client ID (`client_id`)                                           |
| Sign in with Apple key (`.p8`) | Client secret (`client_secret`), the full multi-line PEM contents |
| Team ID                        | `apple_team_id`                                                   |
| Key ID (10 characters)         | `apple_key_id`                                                    |

To get them:

1. Under **Certificates, Identifiers & Profiles** > **Identifiers**, create an **App ID** with the **Sign in with Apple** capability enabled if you don't have one.

2. Create a **Services ID**. Enable **Sign in with Apple** for it and select **Configure**.

3. Set the primary App ID. Add your Auth base URL's host as a **Domain**, and add **`{NEON_AUTH_BASE_URL}/callback/apple`** as a **Return URL**. For example:

   ```text
   https://ep-example.neonauth.us-east-2.aws.neon.tech/neondb/auth/callback/apple
   ```

4. Under **Keys**, create a key with **Sign in with Apple** enabled, associated with your App ID. Download the `.p8` file (Apple lets you download it once) and note the **Key ID**.

5. Copy your **Team ID** from the Membership details page.

Apple requires an HTTPS return URL, so `localhost` URLs aren't accepted.

Managed Better Auth signs the client secret JWT that Apple expects, using your private key, so you don't generate or rotate a client secret yourself. API responses show a masked fingerprint of the key and never return the key itself.

To rotate the key, create a new key in Apple Developer and update the provider with the new `.p8` contents. The request must include the new key's `apple_key_id` (`--apple-key-id`) in the same request.

## Google OAuth branding

When using your own Google OAuth credentials, users will see a consent screen before signing in. Google shows a **Continue to** label that uses the hostname from your OAuth redirect URI (see [Production setup](https://neon.com/docs/auth/guides/setup-oauth#production-setup)), typically the Neon-managed host from your **`NEON_AUTH_BASE_URL`**.

Without completing the OAuth consent screen branding (app name, support email, and authorized domains in Google Cloud Console), the consent UI can look generic or confusing even when your Client ID and Client Secret are correct.

To show your app's name on the consent screen:

1. Go to [Google Cloud Console → OAuth consent screen](https://console.cloud.google.com/auth/branding)
2. Fill in the required app information:
   - **App name**: the name users will see on the consent screen
   - **User support email**: a contact email for users with auth questions
   - **Developer contact information**: your email address (not shown to users)
3. Under **Authorized domains**, add your app's domain (for example, `myapp.com`)
4. Save your changes

**Important: Verification required for public apps**

Apps in **Testing** status only allow Google accounts you list as **test users**. Everyone else sees errors or a blocked consent flow regardless of branding. To show your production branding and allow all users, publish the OAuth consent screen and complete Google verification when required. Verification typically takes a few business days but can take longer depending on the scopes you request.

- [Email Verification](https://neon.com/docs/auth/guides/email-verification): Add email verification

--- [Document source](https://neon.com/docs/auth/guides/user-management.md) ---

> Summary: Managed Better Auth user management exposes `updateUser()` to edit profile fields such as display name, and `changePassword()` to change passwords for signed-in users while requiring the current password for verification. Use this page when you need to update account settings or change credentials after sign-in, not for password reset flows or email verification, which are covered in separate guides. The `revokeOtherSessions` flag in `changePassword()` lets you sign out all other devices in the same call.

# User management

Update profiles, change passwords, and manage account settings

Last updated: 2026-11-05

Manage user profiles and account settings after users sign in. This guide covers:

- Updating profile information (name, image, phone number)
- Changing passwords securely
- Changing email addresses with verification
- Deleting user accounts

## Update user profile

Update user profile fields like name, image, or phone number using `updateUser()`:

```jsx filename="src/App.jsx"
import { authClient } from './auth';

const handleUpdateProfile = async (e) => {
  e.preventDefault();
  setMessage('');

  try {
    const { data, error } = await authClient.updateUser({
      name: 'New Name',
    });

    if (error) throw error;

    // Refresh session to get updated user data
    const sessionResult = await authClient.getSession();
    if (sessionResult.data?.session) {
      setUser(sessionResult.data.session.user);
      setMessage('Profile updated successfully!');
    }
  } catch (error) {
    setMessage(error?.message || 'Update failed');
  }
};
```

### Available profile fields

You can update these fields with `updateUser()`:

- `name` (string) - User's display name

**Note:** Email address changes are not currently supported. To reset a forgotten password, see [Password Reset](https://neon.com/docs/auth/guides/password-reset).

## Change password

Passwords can be up to 128 characters. Sign-up and sign-in reject longer passwords with a `400` `PASSWORD_TOO_LONG` error.

Change a user's password while they are logged in using `changePassword()`. This requires the current password for security:

```jsx filename="src/App.jsx"
import { authClient } from './auth';

const handleChangePassword = async (e) => {
  e.preventDefault();
  setMessage('');

  try {
    const { data, error } = await authClient.changePassword({
      newPassword: 'new-secure-password',
      currentPassword: 'current-password',
    });

    if (error) throw error;
    setMessage('Password changed successfully!');
  } catch (error) {
    setMessage(error?.message || 'Password change failed');
  }
};
```

### Revoke other sessions

Optionally sign out from all other devices when changing the password:

```jsx filename="src/App.jsx"
const { data, error } = await authClient.changePassword({
  newPassword: 'new-secure-password',
  currentPassword: 'current-password',
  revokeOtherSessions: true, // Signs out all other devices
});
```

**Note:** If a user forgot their password, use the password reset flow (`requestPasswordReset()` and `resetPassword()`) instead. See [Password Reset](https://neon.com/docs/auth/guides/password-reset). To sign users out of every session after a reset, turn on [Revoke sessions on password reset](https://neon.com/docs/auth/guides/password-reset#sign-users-out-after-a-reset).

## Refresh user data

After updating profile information, refresh the session to get the latest user data:

```jsx filename="src/App.jsx"
import { authClient } from './auth';

const refreshUser = async () => {
  const { data } = await authClient.getSession();
  if (data?.session) {
    setUser(data.session.user);
  }
};
```

Call `refreshUser()` after successful `updateUser()` calls to ensure your UI displays the latest information.

- [Password Reset](https://neon.com/docs/auth/guides/password-reset): Reset forgotten passwords
- [Email Verification](https://neon.com/docs/auth/guides/email-verification): Verify email addresses
- [Authentication Flow](https://neon.com/docs/auth/authentication-flow): Understand the auth flow

--- [Document source](https://neon.com/docs/auth/guides/webhooks.md) ---

> Summary: Managed Better Auth webhooks send HTTP POST requests to your server when authentication events occur, letting you replace the built-in email provider with custom delivery channels (SMS, WhatsApp, custom email) and intercept user signups before they are written to the database. Use this page when you need to override OTP or magic link delivery, block signups by domain, or sync new users to external systems. Webhooks support events including send.otp, send.magic_link, user.before_create, user.created, organization.invitation.created, organization.invitation.accepted, and phone_number.verified, use EdDSA Ed25519 detached JWS signatures for verification, and retry blocking events within a global timeout.

# Webhooks

Handle authentication events with custom server logic

Last updated: 2026-09-16

Managed Better Auth webhooks send HTTP POST requests to your server when authentication events occur.

By default, Managed Better Auth handles OTP and magic link delivery through its built-in email provider. Webhooks let you replace this with your own delivery channels (SMS, custom email templates, WhatsApp) so you control how verification messages reach your users. Webhooks also let you hook into the user creation lifecycle to validate signups before they happen or sync new user data to external systems like CRMs and analytics platforms.

For a quick overview of available email customization options, check out [Customize emails](https://neon.com/docs/auth/guides/customize-emails).

For a step-by-step Next.js walkthrough that implements signature verification, custom OTP and magic link emails with Resend, blocking signups by email domain, optional SMS delivery, and local testing with ngrok, see [Customizing Managed Better Auth with Webhooks](https://neon.com/guides/neon-auth-webhooks-nextjs).

## Supported events

| Event                              | Type         | Trigger                                                        | Use case                                                                  |
| ---------------------------------- | ------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `send.otp`                         | Blocking     | OTP code needs delivery                                        | Custom OTP delivery via SMS or email service                              |
| `send.magic_link`                  | Blocking     | Magic link needs delivery                                      | Custom link delivery via any channel                                      |
| `user.before_create`               | Blocking     | User attempts to sign up (before database write)               | Signup validation, allowlists, user data enrichment                       |
| `user.created`                     | Non-blocking | User created in the database                                   | Sync to CRM, analytics, post-signup workflows                             |
| `phone_number.verified`            | Non-blocking | User successfully verified a phone number                      | Post-verification workflows for phone OTP sign-in or phone number linking |
| `organization.invitation.created`  | Non-blocking | An organization invitation is created                          | Custom invitation emails, audit logging, sync with external systems       |
| `organization.invitation.accepted` | Non-blocking | A user accepts an organization invitation and becomes a member | Provision resources, update permissions, post-acceptance workflows        |

**Blocking** events pause the auth flow until your server responds (or the timeout expires). **Non-blocking** events are fire-and-forget; failures do not affect the user.

When you subscribe to `send.otp` or `send.magic_link`, Managed Better Auth skips its built-in email delivery for that event. Your webhook handler is responsible for delivering the code or link.

## Configure webhooks

Configure webhooks per project and branch using the Neon Console, CLI, or API. Your webhook URL must use HTTPS protocol. See the API reference for [Get webhook configuration](https://neon.com/docs/reference/api/auth/get-neon-auth-webhook-config) and [Update webhook configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-webhook-config).

```bash
PUT /projects/{project_id}/branches/{branch_id}/auth/webhooks
GET /projects/{project_id}/branches/{branch_id}/auth/webhooks
```

Both endpoints use the following fields:

| Field             | Type               | Description                                                                                                                                                                                      |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`         | boolean (required) | Enable or disable webhook delivery                                                                                                                                                               |
| `webhook_url`     | string             | HTTPS endpoint to receive webhook POST requests                                                                                                                                                  |
| `enabled_events`  | string\[]          | Event types to subscribe to: `send.otp`, `send.magic_link`, `user.before_create`, `user.created`, `phone_number.verified`, `organization.invitation.created`, `organization.invitation.accepted` |
| `timeout_seconds` | integer (1-10)     | Per-attempt timeout in seconds. Default: 5. Total delivery time across all attempts is capped at 15 seconds. See [Retry behavior](https://neon.com/docs/auth/guides/webhooks#retry-behavior).    |

### Webhook URL requirements

Managed Better Auth validates `webhook_url` when you configure webhooks to reduce SSRF risk. Your URL must meet these rules:

- **HTTPS only** — HTTP URLs are rejected.
- **Hostname required** — Use a domain name (for example `https://your-app.com/webhooks/neon-auth`). Raw IP addresses (for example `https://93.184.216.34/webhook`) are rejected, including public IPs.
- **No internal targets** — Localhost, private IP addresses, link-local addresses (including cloud metadata endpoints), and encoded IP bypass formats (octal, decimal, hex) are blocked.
- **No redirects** — Webhook delivery does not follow HTTP `3xx` redirects. Configure the final HTTPS endpoint directly.
- **DNS pinning during delivery** — Managed Better Auth validates the hostname's resolved IP addresses and only connects to that validated set. If DNS later resolves the same hostname to a different IP during delivery, the delivery is blocked as a DNS rebinding attempt.

Digit-prefixed domains such as `1password.com` are allowed. If configuration fails validation, the API returns an error with code `INVALID_WEBHOOK_URL_FORMAT`.

**Warning: Internal webhook targets are not supported**

Webhook endpoints that point at private networks, localhost, cloud metadata services, raw IP literals, or endpoints reached only after a redirect are rejected or blocked during delivery. If an existing webhook depended on an internal target, move it behind a public HTTPS hostname before enabling Managed Better Auth webhooks.

### Set or update configuration

**Console**

In the Neon Console, go to **Auth → Configuration → Webhooks** to enable webhook delivery, set the **Webhook URL** (an HTTPS endpoint; see [Webhook URL requirements](https://neon.com/docs/auth/guides/webhooks#webhook-url-requirements)), choose which events to send, and set the per-attempt timeout in seconds (1-10, default 5). Save to apply.

**CLI**

```bash
neon neon-auth config webhook update --enabled --url https://your-app.com/webhooks/neon-auth --enabled-events user.created --timeout 5
```

**API**

```bash
curl -X PUT "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -d '{
    "enabled": true,
    "webhook_url": "https://your-app.com/webhooks/neon-auth",
    "enabled_events": ["send.otp", "send.magic_link", "user.before_create", "user.created", "phone_number.verified", "organization.invitation.created", "organization.invitation.accepted"],
    "timeout_seconds": 5
  }'
```

### Get current configuration

**Console**

View the current webhook configuration under **Auth → Configuration → Webhooks** in the Neon Console.

**CLI**

```bash
neon neon-auth config webhook get
```

**API**

```bash
curl "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/webhooks" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Both endpoints return the configuration in the same format:

```json
{
  "enabled": true,
  "webhook_url": "https://your-app.com/webhooks/neon-auth",
  "enabled_events": [
    "send.otp",
    "send.magic_link",
    "user.before_create",
    "user.created",
    "phone_number.verified",
    "organization.invitation.created",
    "organization.invitation.accepted"
  ],
  "timeout_seconds": 5
}
```

### Delete a webhook

To delete a webhook and stop receiving authentication events, update your configuration by setting the `enabled` field to `false` using the update endpoint. This disables the webhook and resumes Managed Better Auth's default delivery behavior for all events.

```bash
curl -X PUT "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/webhooks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -d '{
    "enabled": false
  }'
```

## Payload structure

All events share a common JSON envelope:

```json
{
  "event_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "send.otp",
  "timestamp": "2026-02-23T12:00:00.000Z",
  "context": {
    "endpoint_id": "ep-cool-sound-12345678",
    "project_name": "My SaaS App"
  },
  "user": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "email": "user@example.com",
    "name": "Jane Smith",
    "email_verified": false,
    "created_at": "2026-02-23T12:00:00.000Z"
  },
  "event_data": {
    "otp_code": "123456",
    "otp_type": "sign-in",
    "expires_at": "2026-02-23T12:10:00.000Z",
    "ip_address": "192.0.2.1",
    "user_agent": "Mozilla/5.0"
  }
}
```

The `user` object uses a fixed allowlist. Fields are optional and vary by event; fields that are not present are omitted. Available fields: `id`, `name`, `email`, `image`, `role`, `banned`, `email_verified`, `phone_number`, `phone_number_verified`, `created_at`, `updated_at`, `ban_reason`, `ban_expires`, `two_factor_enabled`, `is_anonymous`. Managed Better Auth drops any user fields outside this allowlist, including new Better Auth or plugin fields that have not been explicitly added to the webhook contract.

### `send.otp` event data

| Field                 | Type              | Description                                                 |
| --------------------- | ----------------- | ----------------------------------------------------------- |
| `otp_code`            | string            | 6-digit OTP code                                            |
| `otp_type`            | string            | `"sign-in"`, `"email-verification"`, or `"forget-password"` |
| `delivery_preference` | string (optional) | `"email"` or `"sms"`                                        |
| `expires_at`          | ISO datetime      | Expiry time                                                 |
| `ip_address`          | string            | Requester's IP address                                      |
| `user_agent`          | string            | Requester's user agent                                      |

When `delivery_preference` is `"sms"`, the event is fired by the [Phone Number plugin](https://neon.com/docs/auth/guides/plugins/phone-number). Your handler is responsible for delivering the OTP through your SMS provider. Because Managed Better Auth does not deliver SMS, a subscribed `send.otp` webhook is a hard requirement for the Phone Number plugin.

### `send.magic_link` event data

| Field        | Type         | Description                                                 |
| ------------ | ------------ | ----------------------------------------------------------- |
| `link_type`  | string       | `"sign-in"`, `"email-verification"`, or `"forget-password"` |
| `link_url`   | string       | Full verification URL with embedded token                   |
| `token`      | string       | Raw token for building custom redirect URLs                 |
| `expires_at` | ISO datetime | Expiry time                                                 |
| `ip_address` | string       | Requester's IP address                                      |
| `user_agent` | string       | Requester's user agent                                      |

The `"sign-in"` link type is sent when a user signs in via the [Magic Link plugin](https://neon.com/docs/auth/guides/plugins/magic-link). Magic links do not include a `delivery_preference` field. Your webhook handler determines the delivery channel.

### `user.before_create` and `user.created` event data

These events fire only when a new user record is created in the database. They do not fire on subsequent sign-ins, including returning OAuth users.

| Field           | Type   | Description                                                                     |
| --------------- | ------ | ------------------------------------------------------------------------------- |
| `auth_provider` | string | `"credential"`, `"google"`, `"github"`, `"vercel"`, `"microsoft"`, or `"apple"` |
| `ip_address`    | string | Requester's IP address                                                          |
| `user_agent`    | string | Requester's user agent                                                          |

If sign-up metadata is present and passes validation, it is included as `event_data.signup_metadata`. To limit payload size and prevent oversized egress, Managed Better Auth only includes `signup_metadata` when it is a plain object, serializes to at most 10 KiB of UTF-8 JSON, and is nested no more than 5 levels deep. Oversized, too-deep, array, or primitive metadata is dropped from the webhook payload.

### `phone_number.verified` event data

Fires non-blocking after a user successfully verifies a phone number via the [Phone Number plugin](https://neon.com/docs/auth/guides/plugins/phone-number). The `user` object includes the full user context, including `phone_number` and `phone_number_verified`.

| Field             | Type    | Description                                                                       |
| ----------------- | ------- | --------------------------------------------------------------------------------- |
| `phone_number`    | string  | The phone number that was verified, in E.164 format (for example, `+15551234567`) |
| `is_phone_update` | boolean | Reserved for future use; currently always `false`                                 |
| `ip_address`      | string  | Requester's IP address                                                            |
| `user_agent`      | string  | Requester's user agent                                                            |

### `organization.invitation.created` event data

Fires non-blocking when an organization invitation is created, via the [Organization plugin](https://neon.com/docs/auth/guides/plugins/organization).

The top-level `user` object contains the **inviter**, not the invitee. Because the inviter isn't the subject of the event, this object is limited to `id`, `name`, and `email` rather than the full user allowlist described above. The same reduced object is repeated at `event_data.inviter` for convenience. The invitee's email is available in `event_data.invitee_email`.

| Field               | Type         | Description                                                   |
| ------------------- | ------------ | ------------------------------------------------------------- |
| `invitation_id`     | string       | Unique ID of the invitation                                   |
| `organization_id`   | string       | ID of the organization the invitation is for                  |
| `organization_name` | string       | Name of the organization                                      |
| `organization_slug` | string       | Slug of the organization                                      |
| `invitee_email`     | string       | Email address of the invited user                             |
| `role`              | string       | Role assigned to the invitee                                  |
| `expires_at`        | ISO datetime | Invitation expiry time                                        |
| `inviter`           | object       | `id`, `name`, and `email` of the user who sent the invitation |
| `invitee`           | object       | `email` of the invited user                                   |

### `organization.invitation.accepted` event data

Fires non-blocking after a user accepts an organization invitation and becomes a member, via the [Organization plugin](https://neon.com/docs/auth/guides/plugins/organization). The `user` object contains the full user context for the person who accepted the invitation. `event_data.invitee` repeats the same person as a reduced `id`, `name`, `email` object.

| Field               | Type   | Description                                                       |
| ------------------- | ------ | ----------------------------------------------------------------- |
| `invitation_id`     | string | Unique ID of the invitation                                       |
| `organization_id`   | string | ID of the organization the user joined                            |
| `organization_name` | string | Name of the organization                                          |
| `organization_slug` | string | Slug of the organization                                          |
| `role`              | string | Role assigned to the new member                                   |
| `member_id`         | string | ID of the new organization membership record                      |
| `invitee`           | object | `id`, `name`, and `email` of the user who accepted the invitation |

## Signature verification

Managed Better Auth uses asymmetric EdDSA (Ed25519) signatures with detached JWS, so key rotation does not require reconfiguring your endpoint. Verify signatures before processing webhooks.

### Request headers

Each webhook request includes the following headers:

| Header                    | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `X-Neon-Signature`        | Detached JWS signature (`header..signature`)   |
| `X-Neon-Signature-Kid`    | Key ID for looking up the public key from JWKS |
| `X-Neon-Timestamp`        | Unix timestamp in milliseconds                 |
| `X-Neon-Event-Type`       | Event type (for example, `user.created`)       |
| `X-Neon-Event-Id`         | Unique event UUID                              |
| `X-Neon-Delivery-Attempt` | Attempt number: 1, 2, or 3                     |

Example incoming webhook request:

```http
POST /webhooks/neon-auth HTTP/1.1
Content-Type: application/json
X-Neon-Signature: eyJhbGciOiJFZERTQSIsInR5cCI6IkpXUyIsImtpZCI6IjAxZGVjNTJiIn0..MEUCIQDZ8Qs
X-Neon-Signature-Kid: 01dec52b-4666-40f7-87ed-6423552eecaf
X-Neon-Timestamp: 1740312000000
X-Neon-Event-Type: send.otp
X-Neon-Event-Id: 550e8400-e29b-41d4-a716-446655440000
X-Neon-Delivery-Attempt: 1

{"event_id":"550e8400-e29b-41d4-a716-446655440000","event_type":"send.otp",...}
```

### Verification steps

1. Fetch your JWKS from `<NEON_AUTH_URL>/.well-known/jwks.json`. Find the key where `kid` matches the `X-Neon-Signature-Kid` header.
2. Parse the detached JWS from `X-Neon-Signature`. The format is `header..signature` (empty middle section).
3. Reconstruct the signing input using standard JWS with double base64url encoding:
   - `payloadB64 = base64url(rawRequestBody)`
   - `signaturePayload = timestamp + "." + payloadB64`
   - `signaturePayloadB64 = base64url(signaturePayload)`
   - `signingInput = header + "." + signaturePayloadB64`
4. Verify the Ed25519 signature against the signing input using the public key.

The double base64url encoding occurs because the timestamp is bound into the JWS payload per RFC 7515 Compact Serialization.

### Idempotency and additional checks

Retries send the same `X-Neon-Event-Id`. Your endpoint should track this value and return the same response for duplicate deliveries. This is especially important for `user.before_create`, where a lost response triggers a retry with the same event.

Consider rejecting requests where `X-Neon-Timestamp` is more than 5 minutes old to prevent replay attacks.

### Node.js example

```javascript
import crypto from 'node:crypto';

async function verifyWebhook(rawBody, headers) {
  const signature = headers['x-neon-signature'];
  const kid = headers['x-neon-signature-kid'];
  const timestamp = headers['x-neon-timestamp'];

  // 1. Fetch JWKS and find the matching key
  const res = await fetch(`${process.env.NEON_AUTH_URL}/.well-known/jwks.json`);
  const jwks = await res.json();
  const jwk = jwks.keys.find((k) => k.kid === kid);
  if (!jwk) throw new Error(`Key ${kid} not found in JWKS`);

  // 2. Import the Ed25519 public key
  const publicKey = crypto.createPublicKey({ key: jwk, format: 'jwk' });

  // 3. Parse detached JWS (header..signature)
  const [headerB64, emptyPayload, signatureB64] = signature.split('.');
  if (emptyPayload !== '') throw new Error('Expected detached JWS format');

  // 4. Reconstruct signing input (standard JWS, double base64url encoding)
  const payloadB64 = Buffer.from(rawBody, 'utf8').toString('base64url');
  const signaturePayload = `${timestamp}.${payloadB64}`;
  const signaturePayloadB64 = Buffer.from(signaturePayload, 'utf8').toString('base64url');
  const signingInput = `${headerB64}.${signaturePayloadB64}`;

  // 5. Verify Ed25519 signature
  const isValid = crypto.verify(
    null,
    Buffer.from(signingInput),
    publicKey,
    Buffer.from(signatureB64, 'base64url')
  );

  if (!isValid) throw new Error('Invalid webhook signature');

  // 6. Check timestamp freshness (recommended)
  const ageMs = Date.now() - parseInt(timestamp, 10);
  if (ageMs > 5 * 60 * 1000) throw new Error('Webhook timestamp too old');

  return JSON.parse(rawBody);
}
```

**Important:** Preserve the raw request body before JSON parsing. If your framework parses the body automatically, save the raw bytes first. Re-serialized JSON may differ from the original bytes and cause signature verification to fail.

**Next.js App Router example:**

```javascript
// app/webhooks/neon-auth/route.js
export async function POST(request) {
  const rawBody = await request.text();
  const payload = await verifyWebhook(
    rawBody,
    Object.fromEntries(request.headers)
  );
  // process payload
  return Response.json({ allowed: true });
}
```

**Tip:** In production, cache the JWKS response and refresh it when you encounter an unknown key ID. Rate-limit refresh attempts to avoid excessive requests to the JWKS endpoint.

## Expected responses

Webhook responses must not exceed 10KB.

### `send.otp` and `send.magic_link`

Return any 2xx status code. The response body is ignored.

If all 3 delivery attempts fail or the 15-second global timeout expires, the auth flow fails and the user sees an error.

### `user.before_create`

Return a 2xx status code with a JSON body.

**Allow signup:**

```json
{
  "allowed": true
}
```

**Reject signup:**

```json
{
  "allowed": false,
  "error_message": "Signups from this domain are not allowed.",
  "error_code": "DOMAIN_BLOCKED"
}
```

| Field           | Type               | Description                                        |
| --------------- | ------------------ | -------------------------------------------------- |
| `allowed`       | boolean (required) | Whether to permit user creation                    |
| `error_message` | string (optional)  | User-facing rejection message (max 500 characters) |
| `error_code`    | string (optional)  | Machine-readable code for client-side handling     |

If the webhook fails or returns an invalid response, signup is rejected. This fail-closed behavior prevents bypassing your validation logic.

**Important:** If your webhook endpoint is unreachable, all signups fail. Monitor your endpoint availability and keep response times well under the configured timeout to leave room for network latency and retries.

### `user.created`

Return any 2xx status code. The response body is ignored.

This event is non-blocking. Failures are logged but do not affect the user creation. Return 200 immediately and process the event asynchronously (for example, via a job queue). This prevents timeouts under load.

## Retry behavior

Because blocking events pause the user's auth flow, retries happen immediately rather than using exponential backoff. The user cannot wait minutes for a retry.

The 15-second global timeout runs from the start of the first attempt. Each attempt uses the lesser of `timeout_seconds` or the remaining global time. If earlier attempts consume the budget, later attempts get reduced timeouts or are skipped.

| Property       | Value                                                                                        |
| -------------- | -------------------------------------------------------------------------------------------- |
| Max attempts   | 3 (1 initial + 2 retries, no backoff)                                                        |
| Global timeout | 15 seconds across all attempts                                                               |
| Retryable      | 5xx, 429, 408, network errors (ECONNREFUSED, ETIMEDOUT, ECONNRESET, ENOTFOUND, ECONNABORTED) |
| Non-retryable  | 4xx (except 408 and 429)                                                                     |

## Testing and debugging

Managed Better Auth does not currently support test events, event logs, or redelivery. To test webhooks during development, expose a local server using a tunneling tool (for example, ngrok) and configure the tunnel's **HTTPS hostname** as your webhook URL. Managed Better Auth rejects localhost, private IP addresses, and raw IP literals. See [Webhook URL requirements](https://neon.com/docs/auth/guides/webhooks#webhook-url-requirements).

--- [Document source](https://neon.com/docs/auth/migrate/from-legacy-auth.md) ---

> Summary: Migration guide for upgrading from legacy Neon Auth (Stack Auth) to Managed Better Auth. Replace Stack Auth environment variables with a single `NEON_AUTH_BASE_URL` and swap the `@stackframe/stack` SDK for `@neon/auth`. Use this page when moving an existing Next.js or React SPA project off Stack Auth, or when ejecting to a self-managed Stack Auth project.

# Migrate to Managed Better Auth

Update from the legacy Stack Auth-based implementation

Last updated: 2026-10-09

This guide shows you the code differences between legacy Neon Auth (Stack Auth) and Managed Better Auth. Use it as a reference to understand what changes if you decide to upgrade.

**Important: Legacy Neon Auth (Stack Auth) is no longer accepting new users**

If you're using legacy Neon Auth with Stack Auth, you can continue using it. We'll keep supporting it for existing users. But we encourage you to try Managed Better Auth instead.

## Why Managed Better Auth?

- **Native Branching Support**

  Authentication branches automatically with your database. Each branch gets isolated users, sessions, and auth configuration, perfect for preview environments and testing.

- **Database as Source of Truth**

  Your Neon database is the single source of truth for authentication data. No webhooks, no sync delays, no external dependencies. Query users directly with SQL.

- **Simplified Configuration**

  One environment variable instead of four. Easier setup, fewer moving parts.

- **Open-Source Foundation**

  Built on Better Auth, enabling faster development of new features and better community support.

## Environment variables

Update your environment variables to use Better Auth's configuration.

```env filename=".env (before - Stack Auth)"
NEXT_PUBLIC_STACK_PROJECT_ID=your-project-id
NEXT_PUBLIC_STACK_PUBLISHABLE_CLIENT_KEY=your-client-key
STACK_SECRET_SERVER_KEY=your-server-secret
```

```env filename=".env (after - Better Auth)"
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth
NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
```

**Note:** For React SPAs, use <code>VITE_NEON_AUTH_URL</code> instead. The <code>NEON_AUTH_COOKIE_SECRET</code> is only needed for Next.js (generate with <code>openssl rand -base64 32</code>).

You can find your Auth URL in the Neon Console under **Settings** > **Better Auth** > **Project Info**.

**What changed**  
You replace multiple Stack Auth-specific keys with a single Better Auth URL that points at your Neon project. For Next.js, you also need a cookie secret for session caching.

## Next.js migration

### Install packages

Uninstall Stack Auth packages, install `@neon/auth`, and add [Better Auth UI](https://neon.com/docs/auth/reference/ui-components)'s components with the shadcn CLI.

```bash filename="Terminal"
npm uninstall @stackframe/stack
npm install @neon/auth@latest
npx shadcn@latest init
npx shadcn@latest add @better-auth-ui/auth @better-auth-ui/user-button
npm i better-auth@~1.7.12
```

The last command realigns `better-auth` with the version `@neon/auth` uses, because `shadcn add` installs the npm `latest` tag.

**What changed**  
Your app now depends on Managed Better Auth's Next.js SDK instead of the Stack Auth SDK, and the auth UI components are copied into `components/auth/`.

### Update SDK initialization

**Before (Stack Auth)**

```tsx
// stack.ts
import { StackServerApp } from '@stackframe/stack';

export const stackServerApp = new StackServerApp({
  tokenStore: 'nextjs-cookie',
});
```

**After (Better Auth)**

```tsx
// ./lib/auth/client.ts
'use client';
import { createAuthClient } from '@neon/auth/next';

// to use in react client components
export const authClient = createAuthClient();

// ./lib/auth/server.ts
import { createNeonAuth } from '@neon/auth/next/server';

// to use in react server components, server actions, and API routes
export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: {
    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
  },
});
```

**What changed**  
You initialize the Managed Better Auth client with `createAuthClient` for client components and with `createNeonAuth()` for server-side auth. The unified `auth` instance provides `.handler()`, `.middleware()`, `.getSession()`, and all Better Auth server methods.

### Replace components

#### Sign in page

**Before (Stack Auth)**

```tsx
import { SignIn } from '@stackframe/stack';

export default function SignInPage() {
  return <SignIn />;
}
```

**After (Better Auth)**

```tsx
import { Auth } from '@/components/auth/auth';

export default function SignInPage() {
  return <Auth view="signIn" />;
}
```

**What changed**  
You render Better Auth UI's `Auth` component and tell it which flow to show with the `view` prop. Also add the shared `app/auth/[path]/page.tsx` route with `<Auth path={path} />`, as in the [UI components reference](https://neon.com/docs/auth/reference/ui-components#nextjs-app-router): the user menu's **Sign Out** and the password reset links open `/auth/*` paths.

#### Sign up page

**Before (Stack Auth)**

```tsx
import { SignUp } from '@stackframe/stack';

export default function SignUpPage() {
  return <SignUp />;
}
```

**After (Better Auth)**

```tsx
import { Auth } from '@/components/auth/auth';

export default function SignUpPage() {
  return <Auth view="signUp" />;
}
```

**What changed**  
You swap the dedicated `<SignUp />` component for the same `Auth` component, configured with the `signUp` view.

#### User button

**Before (Stack Auth)**

```tsx
import { UserButton } from '@stackframe/stack';

export function Header() {
  return <UserButton />;
}
```

**After (Better Auth)**

```tsx
import { UserButton } from '@/components/auth/user/user-button';

export function Header() {
  return <UserButton hideSettings />;
}
```

**What changed**  
You keep a `UserButton`, now the one the shadcn CLI copied into `components/auth/user/`. `hideSettings` drops its link to `/settings/account`; to keep it, add `@better-auth-ui/settings` and a `settings/[path]` route.

### Replace hooks

**Before (Stack Auth)**

```tsx
'use client';
import { useUser } from '@stackframe/stack';

export function MyComponent() {
  const user = useUser();
  return <div>{user ? `Hello, ${user.displayName}` : 'Not logged in'}</div>;
}
```

**After (Better Auth)**

```tsx
'use client';
import { useSession } from '@/lib/auth/client';

export function MyComponent() {
  const { data } = useSession();
  const user = data?.user;

  return <div>{user ? `Hello, ${user.name || user.email}` : 'Not logged in'}</div>;
}
```

**What changed**  
Instead of `useUser()`, you call `useSession()` hook from `authClient` and read the user & session data from response.

### Update provider setup

**Before (Stack Auth)**

```tsx
import { StackProvider, StackTheme } from '@stackframe/stack';
import { stackServerApp } from './stack';

export default function RootLayout({ children }) {
  return (
    <StackProvider app={stackServerApp}>
      <StackTheme>{children}</StackTheme>
    </StackProvider>
  );
}
```

**After (Better Auth)**

```tsx
// components/providers.tsx, rendered by app/layout.tsx around {children}
'use client';
import { getSafeRedirectTo } from '@better-auth-ui/core';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import Link from 'next/link';
import { useRouter } from 'next/navigation';
import { useState } from 'react';
import { AuthProvider } from '@/components/auth/auth-provider';
import { Toaster } from '@/components/ui/sonner';
import { authClient } from '@/lib/auth/client';

export function Providers({ children }) {
  const router = useRouter();
  const [queryClient] = useState(() => new QueryClient());

  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider
        authClient={authClient}
        emailAndPassword={{ requireEmailVerification: false }} // match your branch's setting
        navigate={({ to, replace }) => {
          const path = getSafeRedirectTo(to, window.location.origin);
          const target = path.startsWith('//') ? '/' : path;
          if (replace) router.replace(target);
          else router.push(target);
        }}
        Link={Link}
        redirectTo="/"
      >
        {children}
        <Toaster />
      </AuthProvider>
    </QueryClientProvider>
  );
}
```

**What changed**  
You wrap your app in a TanStack Query provider and Better Auth UI's `AuthProvider`, and pass it the `authClient`. `navigate` validates the `?redirectTo=` target the components pass it after sign-in. There's no stylesheet to import: your Tailwind build compiles the copied components.

**Tip: Styling options**

To change how the auth UI looks, edit the shadcn/ui theme or the copied components. See [Styling](https://neon.com/docs/auth/reference/ui-components#styling).

### Replace auth handler route

**Before (Stack Auth)**

```tsx
// app/handler/[...stack]/page.tsx
import { StackHandler } from '@stackframe/stack';
import { stackServerApp } from '@/stack';

export default function Handler(props: any) {
  return <StackHandler fullPage app={stackServerApp} {...props} />;
}
```

**After (Better Auth)**

```tsx
// app/api/auth/[...path]/route.ts
import { auth } from '@/lib/auth/server';

export const { GET, POST, PUT, PATCH, DELETE } = auth.handler();
```

**What changed**  
You proxy Managed Better Auth APIs from your Next.js application. The `auth.handler()` method forwards all API requests to the Managed Better Auth server.

### Protect routes

#### Component-level protection

**Before (Stack Auth)**

```tsx
'use client';
import { useUser } from '@stackframe/stack';

export default function ProtectedPage() {
  const user = useUser({ or: 'redirect' });
  return <div>Protected content</div>;
}
```

**After (Better Auth)**

```tsx
'use client';
import { useSession } from '@better-auth-ui/react';
import { useRouter } from 'next/navigation';
import { useEffect } from 'react';
import { authClient } from '@/lib/auth/client';

export default function ProtectedPage() {
  const router = useRouter();
  const { data, isFetching } = useSession(authClient);
  const signedOut = !data && !isFetching;

  useEffect(() => {
    if (signedOut) router.replace('/auth/sign-in');
  }, [signedOut, router]);

  if (!data) return null;
  return <div>Protected content</div>;
}
```

**What changed**  
You read the session with `useSession()` and redirect once it has loaded without a user. For page loads, prefer the middleware below, which redirects on the server.

#### Middleware-based protection

**Note: Next.js version compatibility**

`proxy.ts` replaces `middleware.ts` in Next.js 16. On earlier versions, name the file `middleware.ts` and export `default function middleware` instead of `proxy`. The auth logic is identical.

```tsx filename="proxy.ts (new)"
import { auth } from '@/lib/auth/server';

export default auth.middleware({
  // Redirects unauthenticated users to sign-in page
  loginUrl: '/auth/sign-in',
  // Pages that don't require a session
  publicRoutes: ['/'],
});

export const config = {
  // Run on all paths except static files
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

**What changed**  
You can optionally add middleware to enforce auth at the edge. It protects every matched route except `/api/auth`, Better Auth UI's signed-out views, and the `publicRoutes` you list.

### Server-side user access

**Before (Stack Auth)**

```tsx
import { stackServerApp } from '@/stack';

export default async function ServerComponent() {
  const user = await stackServerApp.getUser();
  return <div>{user?.displayName}</div>;
}
```

**After (Better Auth)**

```tsx
import { auth } from '@/lib/auth/server';

// Server components using auth methods must be rendered dynamically
export const dynamic = 'force-dynamic';

export default async function ServerComponent() {
  const { data: session } = await auth.getSession();
  return <div>{session?.user?.name || session?.user?.email}</div>;
}
```

**What changed**  
Server components now call `auth.getSession()` and read the user from the returned session. Components using auth methods must set `dynamic = 'force-dynamic'`.

## React SPA migration

### Install packages

Uninstall Stack Auth packages, install `@neon/auth`, and add [Better Auth UI](https://neon.com/docs/auth/reference/ui-components)'s components with the shadcn CLI.

```bash filename="Terminal"
npm uninstall @stackframe/stack
npm install @neon/auth@latest
npx shadcn@latest init
npx shadcn@latest add @better-auth-ui/auth @better-auth-ui/user-button
npm i better-auth@~1.7.12
```

The last command realigns `better-auth` with the version `@neon/auth` uses, because `shadcn add` installs the npm `latest` tag.

**What changed**  
You use the Managed Better Auth SDK and Better Auth UI's components instead of the Stack Auth client SDK.

### Update SDK initialization

**Before (Stack Auth)**

```tsx
// src/stack.ts
import { StackClientApp } from '@stackframe/stack';

export const stackClientApp = new StackClientApp({
  urls: {
    signIn: '/sign-in',
    signUp: '/sign-up',
  },
});
```

**After (Better Auth)**

```tsx
// src/auth.ts
import { createAuthClient } from '@neon/auth';
import { BetterAuthReactAdapter } from '@neon/auth/react/adapters';

export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL, {
  adapter: BetterAuthReactAdapter(),
});
const { useSession } = authClient;
```

**What changed**  
You replace the Stack Auth client app with a Managed Better Auth `authClient` wired to your Managed Better Auth URL.

### Replace components

Components are the same as Next.js. Use `<Auth>` and `<UserButton>` from `components/auth/`, and `useSession()` from `@better-auth-ui/react` for signed-in checks.

**What changed**  
The UI building blocks are shared across frameworks, so you can reuse the same auth components in SPAs.

### Replace hooks

**Before (Stack Auth)**

```tsx
import { useUser } from '@stackframe/stack';

export function MyComponent() {
  const user = useUser();
  return <div>{user ? `Hello, ${user.displayName}` : 'Not logged in'}</div>;
}
```

**After (Better Auth)**

```tsx
import { useSession } from './auth';

export function MyComponent() {
  const { data } = useSession();
  const user = data?.user;

  return <div>{user ? `Hello, ${user.name || user.email}` : 'Not logged in'}</div>;
}
```

**What changed**  
Instead of a React hook from Stack Auth, you call the `useSession()` hook from `authClient` and read the user from its response.

### Update provider setup

**Before (Stack Auth)**

```tsx
import { StackProvider, StackTheme } from '@stackframe/stack';
import { stackClientApp } from './stack';

function App() {
  return (
    <StackProvider app={stackClientApp}>
      <StackTheme>{/* Your app */}</StackTheme>
    </StackProvider>
  );
}
```

**After (Better Auth)**

```tsx
import { getSafeRedirectTo } from '@better-auth-ui/core';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { AuthProvider } from '@/components/auth/auth-provider';
import { Toaster } from '@/components/ui/sonner';
import { authClient } from './auth';

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider
        authClient={authClient}
        emailAndPassword={{ requireEmailVerification: false }} // match your branch's setting
        navigate={({ to }) => {
          const path = getSafeRedirectTo(to, window.location.origin);
          window.location.assign(path.startsWith('//') ? '/' : path);
        }}
        Link={({ to: _to, ...props }) => <a {...props} />}
      >
        {/* Your app */}
        <Toaster />
      </AuthProvider>
    </QueryClientProvider>
  );
}
```

**What changed**  
You drop the Stack Auth provider/theme and wrap your app in a TanStack Query provider and Better Auth UI's `AuthProvider`. `navigate` validates the `?redirectTo=` target the components pass it after sign-in.

**Tip: Styling options**

To change how the auth UI looks, edit the shadcn/ui theme or the copied components. See [Styling](https://neon.com/docs/auth/reference/ui-components#styling).

### Remove auth handler route

Delete any `StackHandler` routes. Add one route for every auth path, for example `/auth/:path`, that renders `<Auth>`. The user menu's **Sign Out** and the password reset links open `/auth/*` paths.

```tsx filename="src/pages/AuthPage.tsx"
import { useParams } from 'react-router-dom';
import { Auth } from '@/components/auth/auth';

export default function AuthPage() {
  const { path } = useParams();
  return <Auth path={path} />;
}
```

**What changed**  
Routing is fully controlled by your SPA, and the `Auth` component renders the view for each path.

### React Router integration

If you're using React Router, pass navigation helpers to the provider.

```tsx filename="src/App.tsx (React Router)"
import { getSafeRedirectTo } from '@better-auth-ui/core';
import { useNavigate, Link } from 'react-router-dom';
import { AuthProvider } from '@/components/auth/auth-provider';
import { authClient } from './auth';

function App() {
  const navigate = useNavigate();

  return (
    <AuthProvider
      authClient={authClient}
      emailAndPassword={{ requireEmailVerification: false }} // match your branch's setting
      navigate={({ to, replace }) => {
        const path = getSafeRedirectTo(to, window.location.origin);
        navigate(path.startsWith('//') ? '/' : path, { replace });
      }}
      Link={({ href, to: _to, ...props }) => <Link to={href} {...props} />}
    >
      {/* Your app */}
    </AuthProvider>
  );
}
```

**What changed**  
You let Better Auth reuse your router's navigation and Link components so redirects and links stay in sync with your SPA.

## Eject to Stack Auth

If you prefer to continue using Stack Auth independently instead of migrating to Better Auth, you can claim your Stack Auth project and manage it directly.

## Claim your project via the Neon Console

1. Go to your project's **Auth** page, **Configuration** tab in the Neon Console.
2. Click **Claim project** in the Claim project section.
3. Follow the prompts to select the Stack Auth account that should receive ownership.

After claiming, you'll have direct access to manage your project in the Stack Auth dashboard.

## Update your environment variables

Once claimed, update your environment variables to use Stack Auth's direct configuration. Your existing code will continue to work without changes since you're already using the Stack Auth SDK (`@stackframe/stack`).

## Manage independently

After claiming, you can:

- Manage OAuth providers directly in Stack Auth.
- Configure production security settings.
- Access Stack Auth's dashboard and features.

**Important:** Ejecting to Stack Auth means you'll manage authentication independently from Neon. You'll need to handle updates, support, and infrastructure yourself. Your authentication data will no longer be managed through the Neon Console.

--- [Document source](https://neon.com/docs/auth/migrate/from-supabase.md) ---

> Summary: Step-by-step migration from Supabase Auth and Supabase database to Managed Better Auth and Neon Data API. Replace `@supabase/supabase-js` with `@neon/neon-js`, swap environment variables, and update client initialization while keeping existing auth method calls and `from()` database queries code-compatible. Existing password-based users cannot transfer due to incompatible password hashing algorithms, so this guide targets new projects, early development, or OAuth-only apps. Managed Better Auth does not support phone authentication (SMS/WhatsApp), SAML SSO, or Web3 wallet sign-in.

# Migrate from Supabase to Neon

Switch from Supabase Auth and Database to Neon in a few steps

Last updated: 2026-09-16

Managed Better Auth provides a Supabase-compatible API, and Neon Data API provides PostgreSQL database access. This guide shows how to migrate from Supabase to Neon.

**about user migration:** Existing password-based users cannot migrate due to different hashing algorithms. They'll need to create new accounts or re-authenticate via OAuth. This guide works best for new projects, early development, or rebuilding your app.

## Prerequisites

- A Neon project ([create one here](https://console.neon.tech))
- Data API enabled (Managed Better Auth is enabled by default when you enable Data API):
  - Go to **Postgres database** > **Data API** in the Neon Console and enable it
  - In **Data API → Configuration**, verify it's configured with **Managed Better Auth**
  - Copy your Neon connection host and database name from **Connect** in the Console. The SDK derives both the Auth and Data API URLs from this single base URL. See [Initialize the client](https://neon.com/docs/reference/javascript-sdk#initializing) for the derivation rules, or use the separate Auth and Data API base URLs instead if you'd rather configure them explicitly

## Install Neon SDK

Replace the Supabase SDK with Neon's:

```bash filename="Terminal"
npm uninstall @supabase/supabase-js
npm install @neon/neon-js@latest
```

## Update environment variables

Replace your Supabase credentials with a single Neon base URL. `createClient()` derives both the Auth and Data API URLs from it automatically:

```env filename=".env"
# Remove these:
# VITE_SUPABASE_URL=https://your-project.supabase.co
# VITE_SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

# Add this:
VITE_NEON_URL=https://ep-xxx.c-2.us-east-2.aws.neon.build/dbname
```

**Get your URL:**

Your Neon base URL is the host and database name from your Neon connection string, served over `https://`. Find these values under **Connect** in the Neon Console.

**Note:** The `VITE_` prefix is for Vite. Use `NEXT_PUBLIC_` for Next.js, or no prefix for Node.js.

**Tip:** If you already copied separate Auth and Data API base URLs from the Console (for example, from an earlier setup), you can still pass them explicitly with the object form. See [Initialize the client](https://neon.com/docs/reference/javascript-sdk#initializing) for both forms.

## Update client initialization

Find your Supabase client file, typically `src/supabase.ts` or `src/lib/supabase.ts`, and update it:

**Before (Supabase):**

```typescript filename="src/supabase.ts"
import { createClient } from '@supabase/supabase-js';

export const supabase = createClient(
  process.env.VITE_SUPABASE_URL!,
  process.env.VITE_SUPABASE_ANON_KEY!
);
```

**After (Neon):**

```typescript filename="src/auth.ts"
import { createClient } from '@neon/neon-js/supabase';

export const client = createClient(import.meta.env.VITE_NEON_URL);
```

This example renames the file to `auth.ts` and the variable to `client` for a provider-agnostic setup. You can use any naming, just stay consistent throughout your codebase.

Find **all files that import this client** and update them:

```typescript
// Before
import { supabase } from './supabase';

// After
import { client } from './auth';
```

## Your auth code stays the same

After updating imports, use find/replace to change all instances throughout your codebase:

**`supabase.` → `client.`**

Your authentication methods, parameters, and responses work identically. Your components, hooks, and auth flows don't change.

```typescript filename="Auth methods"
// Sign up
await client.auth.signUp({ email, password });

// Sign in with password
await client.auth.signInWithPassword({ email, password });

// OAuth sign in
await client.auth.signInWithOAuth({ provider: 'google' });

// Get current user
const {
  data: { user },
} = await client.auth.getUser();

// Get session
const {
  data: { session },
} = await client.auth.getSession();

// Sign out
await client.auth.signOut();
```

## Your database queries stay the same

Your existing `client.from()` queries work without any code changes:

```typescript
// Same as Supabase - no changes needed
const { data: posts } = await client.from('posts').select('*');
const { data: user } = await client.from('users').select('*').eq('id', userId).single();
```

**Note:** For production apps, use Row Level Security (RLS) to secure your data. See our [RLS with Drizzle guide](https://neon.com/docs/guides/rls-drizzle) for the recommended setup.

## Test the migration

Run your app:

```bash filename="Terminal"
npm run dev
```

**Test your app:**

1. Sign up a new user
2. Sign in with that user
3. Verify the session persists across page reloads
4. If you enabled Data API: Test user actions that involve database queries (creating posts, loading lists, etc.)

Your authentication and database queries should work the same as they did with Supabase.

**Verify users in Neon Console:**

Go to **Auth → Users** in the Neon Console to see your newly created users, or query directly:

```sql filename="SQL Editor"
SELECT id, email, "createdAt"
FROM neon_auth.user
ORDER BY "createdAt" DESC;
```

## What changed?

| Feature                   | Supabase                            | Neon                                                |
| ------------------------- | ----------------------------------- | --------------------------------------------------- |
| **User ID type**          | `UUID`                              | `UUID`                                              |
| **Client config**         | URL + anon key                      | Single base URL (auto-derives Auth + Data API URLs) |
| **Environment variables** | `SUPABASE_URL`, `SUPABASE_ANON_KEY` | `NEON_URL`                                          |
| **SDK package**           | `@supabase/supabase-js`             | `@neon/neon-js`                                     |

## API compatibility

Managed Better Auth supports most Supabase Auth methods including sign up, sign in (password and OAuth), session management, user updates, and email verification. See the [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk) for the complete API.

**Not supported:**

| Method              | Details                             |
| ------------------- | ----------------------------------- |
| `signInWithPhone()` | Phone authentication (SMS/WhatsApp) |
| SAML SSO methods    | Enterprise SAML authentication      |
| Web3 authentication | Blockchain wallet sign-in           |

**Different behavior:**

| Method             | Notes                                                                                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `updateUser()`     | Does not support `password` or `email` parameters                                                                                                                                                                                    |
| Email verification | Unlike Supabase's automatic verification flow, Managed Better Auth requires you to build the verification UI in your app. See [Email Verification](https://neon.com/docs/auth/guides/email-verification) for implementation details. |

If you're using any unsupported methods or verification flows, you'll need to adjust your implementation.

--- [Document source](https://neon.com/docs/auth/overview.md) ---

> Summary: Managed Better Auth is a managed authentication service built on Better Auth. It stores users, sessions, and OAuth configuration in your database under the neon_auth schema, compatible with Row Level Security. Every database branch gets its own isolated auth environment, so you can test sign-up, login, and OAuth flows in preview or CI branches without touching production.

# Managed Better Auth

Managed authentication that branches with your database

Last updated: 2026-09-29

Neon's managed Better Auth keeps your users and sessions in your own Postgres database, so your auth state branches with your data.

[View prompt](https://neon.com/prompts/auth-landing.md)

## Quick start guides

Choose your framework to get started:

- [Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only): Quick start with API methods
- [React](https://neon.com/docs/auth/quick-start/react): Quick start with API methods
- [TanStack Router](https://neon.com/docs/auth/quick-start/tanstack-router): With UI components

## Explore Managed Better Auth

- [About Managed Better Auth](https://neon.com/docs/auth/about): How Neon's managed Better Auth works, when to use it instead of self-hosting, pricing, and availability.
- [Branching authentication](https://neon.com/docs/auth/branching-authentication): Every database branch gets its own isolated users, sessions, and auth configuration.
- [Authentication flow](https://neon.com/docs/auth/authentication-flow): Follow a request from sign-in to session through the SDK and the auth service.
- [Set up OAuth](https://neon.com/docs/auth/guides/setup-oauth): Add Google, GitHub, and other OAuth providers to your app.
- [Production checklist](https://neon.com/docs/auth/production-checklist): Check domains, email, and OAuth credentials before you go live.
- [Roadmap](https://neon.com/docs/auth/roadmap): See which frameworks and Better Auth plugins are supported today.

--- [Document source](https://neon.com/docs/auth/production-checklist.md) ---

> Summary: Required steps before going live with Managed Better Auth: trusted domains, custom SMTP provider, application name, OAuth credentials, email verification, and disabling localhost access. Use this page when Managed Better Auth is already configured for development and you need to confirm every production-blocking setting before launch. The default shared SMTP provider (`auth@mail.myneon.app`) is rate-limited and does not support verification links. A custom SMTP provider is required for both.

# Auth production checklist

Required configuration before launching with Managed Better Auth

Last updated: 2026-10-09

Complete these steps before taking your application to production with Managed Better Auth.

## Auth production checklist

- [ ] [1. Configure trusted domains](https://neon.com/docs/auth/guides/configure-domains)
    Add your production domain(s) to enable OAuth and email verification redirects.
- [ ] [2. Set up custom email provider](https://neon.com/docs/auth/production-checklist#email-provider)
    Replace shared SMTP (`auth@mail.myneon.app`) with your own email service for reliable delivery and higher limits. A custom email provider is also required if you want to use verification links instead of verification codes.
- [ ] [3. Customize application name](https://neon.com/docs/auth/production-checklist#application-name)
    Set the name your users see in user-facing auth messages. Applies to Managed Better Auth integrations. Defaults to the Neon project name.
- [ ] [4. Configure OAuth credentials (if using OAuth)](https://neon.com/docs/auth/guides/setup-oauth#production-setup)
    Set up your own OAuth apps (Google, GitHub, Vercel, Microsoft, or Apple). Google is the only provider with shared development credentials, so replace those with your own before launch.
- [ ] [5. Enable email verification (recommended)](https://neon.com/docs/auth/guides/email-verification)
    **Email verification is not enabled by default.** Since anyone can sign up for your application, enabling email verification adds an important verification step to ensure users own their email address.
- [ ] [6. Disable localhost access](https://neon.com/docs/auth/production-checklist#localhost-access)
    Disable the "Allow Localhost" setting in your project's **Settings** → **Better Auth** page. This setting is enabled by default for development but should be disabled in production to improve security.

## Email provider

Managed Better Auth uses a shared SMTP provider (`auth@mail.myneon.app`) by default for development and testing. For production, configure your own email provider for better deliverability and higher sending limits.

A custom SMTP provider uses your sender address but still sends Neon's default email templates. For full control over email branding, content, and HTML templates, use webhooks to intercept email events and send through your own email service. See [Customize emails](https://neon.com/docs/auth/guides/customize-emails).

### Configure custom SMTP

**Console**

In your project's **Settings** → **Better Auth** page, configure your email provider:

1. Select **Custom SMTP provider**
2. Enter your SMTP credentials:
   - **Host**: Your SMTP server hostname (for example, `smtp.gmail.com`)
   - **Port**: SMTP port (typically `465` for SSL or `587` for TLS)
   - **Username**: Your SMTP username
   - **Password**: Your SMTP password or app-specific password
   - **Sender email**: Email address to send from
   - **Sender name**: Display name for sent emails
3. Click **Save**

**CLI**

Configure a standard SMTP provider with [`neon neon-auth config email-provider update`](https://neon.com/docs/cli/neon-auth#config-email-provider-update):

```bash
neon neon-auth config email-provider update --type standard --host smtp.example.com --port 587 --username example_username --password AbC123dEf --sender-email noreply@example.com --sender-name "Example App"
```

**API**

Update the provider with the [Update email provider configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-email-provider) endpoint. Replace `{project_id}` and `{branch_id}` with your project and branch IDs:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/auth/email_provider' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"type": "standard", "host": "smtp.example.com", "port": 587, "username": "example_username", "password": "AbC123dEf", "sender_email": "noreply@example.com", "sender_name": "Example App"}'
```

### Email provider requirements

- **Verification links**: Require a custom email provider
- **Verification codes**: Work with shared or custom email providers
- **Password reset**: Works with shared or custom email providers

**Note:** The shared email provider (`auth@mail.myneon.app`) is suitable for development and testing. For production applications, use a custom email provider for better deliverability and to avoid rate limits.

## Application name

Managed Better Auth uses the application name in user-facing auth messages, such as verification emails and password resets. By default, this is set to the Neon project name. This setting is available for Managed Better Auth integrations only.

To set a custom application name:

1. Go to **Settings** → **Better Auth** in your Neon project
2. In the **Project Info** section, edit the **Application Name** field

Each branch manages its own application name independently, so preview and development branches can use different names than production.

You can also update the application name via the API. See [Update auth configuration](https://neon.com/docs/auth/guides/manage-auth-api#update-auth-configuration).

## Localhost access

The "Allow Localhost" setting in your project's **Settings** → **Better Auth** page is enabled by default to allow authentication requests from localhost during development.

### Disable for production

For production environments, disable this setting to improve security:

1. Go to **Settings** → **Better Auth** in your Neon project
2. Find the **Allow Localhost** toggle
3. Disable the toggle

**Important:** Only enable "Allow Localhost" for local development. Disabling this setting in production prevents unauthorized authentication requests from localhost, improving your application's security posture.

--- [Document source](https://neon.com/docs/auth/quick-start/nextjs-api-only.md) ---

> Summary: Managed Better Auth SDK integration for Next.js App Router using raw API methods. Call `createNeonAuth`, `auth.signUp.email()`, `auth.signIn.email()`, and `auth.middleware()` directly from the `@neon/auth` package for full control over your auth UI. Use this guide instead of the UI components reference when you need custom sign-up and sign-in forms. Requires Next.js App Router.

# Use Managed Better Auth with Next.js (API methods)

Build your own auth UI using SDK methods

Last updated: 2026-11-06

**Tip: Using an AI coding tool?**

Run `npx neon@latest init` to connect the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server) and [Agent Skills](https://neon.com/docs/ai/agent-skills) for Managed Better Auth. See [Set up with your AI editor](https://neon.com/docs/auth/about#set-up-with-your-ai-editor) for MCP tools, example prompts, and how skills help wire auth into your app.

This guide shows you how to integrate Managed Better Auth into a [Next.js](https://nextjs.org) (App Router) project using SDK methods directly. For pre-built UI components, see the [UI components reference](https://neon.com/docs/auth/reference/ui-components) and the [neon-js examples](https://github.com/neondatabase/neon-js/tree/main/examples). Upgrading from v0.1? See the [migration guide](https://neon.com/docs/auth/migrate/from-auth-v0.1).

## Enable Auth in your Neon project

If you don't have a Neon project yet, create one at [console.neon.tech](https://console.neon.tech).

In the Neon Console, open the **Better Auth** page and click **Enable Auth**, then copy your Auth URL from **Settings** > **Better Auth** > **Project Info**.

**Console path:** Project → Branch → Auth → Configuration

## Install the Neon SDK

Install the Neon SDK into your Next.js app.

<details>

<summary>_If you don't have a Next.js project_</summary>

```bash
npx create-next-app@latest my-app --yes
cd my-app
```

</details>

```bash filename="Terminal"
npm install @neon/auth@latest
```

## Set up environment variables

Create a `.env.local` file in your project root and add your Auth URL and a cookie secret:

**Note:** Replace the Auth URL with your actual Auth URL from the Neon Console. Generate a secure cookie secret with `openssl rand -base64 32`.

```bash filename=".env.local"
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
```

## Create auth server instance

Create a unified auth instance in `lib/auth/server.ts`. This single instance provides all server-side auth functionality:

- `.handler()` for API routes
- `.middleware()` for route protection
- `.getSession()` and all Better Auth server methods

See the [Next.js Server SDK reference](https://neon.com/docs/auth/reference/nextjs-server) for complete API documentation (logging, cookies, upstream errors).

**Note: Server logging**

The SDK logs structured **`error`** and **`warn`** messages to **`console`** by default (`logLevel: 'warn'`). This helps when the auth proxy or upstream Auth URL is misconfigured. Set **`logLevel: 'silent'`** to disable Managed Better Auth logging, or **`logLevel: 'debug'`** for more detail. See [Server logging](https://neon.com/docs/auth/reference/nextjs-server#server-logging) in the reference.

```typescript filename="lib/auth/server.ts"
import { createNeonAuth } from '@neon/auth/next/server';

export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: {
    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
    // sessionDataTtl: 300, // optional session_data cache TTL in seconds (default: 300)
  },
  // logLevel: 'silent', // disable Managed Better Auth logging
  // logLevel: 'debug',  // verbose proxy/upstream logging
});
```

## Set up auth API routes

Create an API route handler that proxies auth requests. All Managed Better Auth APIs will be routed through this handler. Create a route file inside `/api/auth/[...path]` directory:

In `app/api/auth/[...path]/route.ts`:

```typescript filename="app/api/auth/[...path]/route.ts"
import { auth } from '@/lib/auth/server';

export const { GET, POST, PUT, PATCH, DELETE } = auth.handler();
```

## Add authentication middleware

The middleware ensures users are authenticated before accessing protected routes. Create `proxy.ts` file in your project root:

**Note: Next.js version compatibility**

`proxy.ts` replaces `middleware.ts` in Next.js 16. On earlier versions, name the file `middleware.ts` and export `default function middleware` instead of `proxy`. The auth logic is identical.

```typescript filename="proxy.ts"
import { auth } from '@/lib/auth/server';

export default auth.middleware({
  // Redirects unauthenticated users to sign-in page
  loginUrl: '/auth/sign-in',
});

export const config = {
  matcher: [
    // Protected routes requiring authentication
    '/account/:path*',
  ],
};
```

**Note:** Your Next.js project is now fully configured to use Managed Better Auth. Now, lets proceed with setting up the auth clients.

## Configure the auth client

Create the auth client in `lib/auth/client.ts` for client-side auth operations (form submissions, hooks, etc.).

**Note:** The server-side `auth` instance was already created in a previous step. The client is separate and handles browser-side auth operations.

```tsx filename="lib/auth/client.ts"
'use client';

import { createAuthClient } from '@neon/auth/next';

export const authClient = createAuthClient();
```

## Create Sign up form

Lets create a sign-up form and action in `app/auth/sign-up/page.tsx` and `app/auth/sign-up/actions.ts` files respectively using the auth instance we created in previous step

- To create user with email and password, we will use `auth.signUp.email()` with user name, email address, and password
- You can optionally add business logic before invoking the API, for example restrict signups to emails ending with `@my-company.com`

**Signup action**

Copy and paste following code in `app/auth/sign-up/actions.ts` file:

```ts
'use server';

import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';

export async function signUpWithEmail(
  _prevState: { error: string } | null,
  formData: FormData
) {
  const email = formData.get('email') as string;

  if (!email) {
    return { error: "Email address must be provided." }
  }

  // Optionally restrict sign ups based on email address
  // if (!email.trim().endsWith("@my-company.com")) {
  //  return { error: 'Email must be from my-company.com' };
  // }

  const { error } = await auth.signUp.email({
    email,
    name: formData.get('name') as string,
    password: formData.get('password') as string,
  });

  if (error) {
    return { error: error.message || 'Failed to create account' };
  }

  redirect('/');
}
```

**Signup form**

Copy and paste following code in `app/auth/sign-up/page.tsx` file:

```tsx
'use client';

import { useActionState } from 'react';
import { signUpWithEmail } from './actions';

export default function SignUpForm() {
  const [state, formAction, isPending] = useActionState(signUpWithEmail, null);

  return (
    <form action={formAction}
      className="flex flex-col gap-5 min-h-screen items-center justify-center bg-gray-900">

      <div className="w-sm">
        <h1 className="mt-10 text-center text-2xl/9 font-bold text-white">Create new account</h1>
      </div>

      <div className='flex flex-col gap-1.5 w-sm'>
        <label htmlFor="name" className="block text-sm font-medium text-gray-100">Name</label>
        <input id="name" name="name" type="text" required placeholder="John Doe"
          className="block rounded-md w-full bg-white/5 px-2 py-1.5 placeholder:text-gray-500 text-white outline-1 outline-white/10 focus:outline-indigo-500"
        />
      </div>

      <div className='flex flex-col gap-1.5 w-sm'>
        <label htmlFor="email" className="block text-sm font-medium text-gray-100">Email address</label>
        <input id="email" name="email" type="email" required placeholder="john@my-company.com"
          className="block rounded-md w-full bg-white/5 px-2 py-1.5 placeholder:text-gray-500 text-white outline-1 outline-white/10  focus:outline-indigo-500"/>
      </div>

      <div className='flex flex-col gap-1.5 w-sm'>
        <label htmlFor="password" className="block text-sm font-medium text-gray-100">Password</label>
        <input id="password" name="password" type="password" required placeholder="*****"
          className="block rounded-md w-full bg-white/5 px-2 py-1.5 placeholder:text-gray-500 text-white outline-1 outline-white/10  focus:outline-indigo-500"/>
      </div>

      {state?.error && (
        <div className="rounded-md px-3 py-2 text-sm text-red-500">
          {state.error}
        </div>
      )}

      <button type="submit" disabled={isPending}
        className="flex w-sm justify-center rounded-md bg-indigo-500 px-3 py-1.5 text-sm/6 font-semibold text-white hover:bg-indigo-400">
        {isPending ? 'Creating account...' : 'Create Account'}
      </button>
    </form>
  );
}
```

## Create Sign in form

Lets create a sign-in form and action in `app/auth/sign-in/page.tsx` and `app/auth/sign-in/actions.ts` files respectively.

- To sign-in the user we will use `auth.signIn.email()` with user's email address and password.

**Sign In:**

**Sign-in action**

```ts
'use server';

import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';

export async function signInWithEmail(
  _prevState: { error: string } | null,
  formData: FormData
) {
  const { error } = await auth.signIn.email({
    email: formData.get('email') as string,
    password: formData.get('password') as string,
  });

  if (error) {
    return { error: error.message || 'Failed to sign in. Try again' };
  }

  redirect('/');
}
```

**Sign-in form**

```tsx
'use client';

import { useActionState } from 'react';
import { signInWithEmail } from './actions';

export default function SignInForm() {
  const [state, formAction, isPending] = useActionState(signInWithEmail, null);

  return (
    <form action={formAction}
      className="flex flex-col gap-5 min-h-screen items-center justify-center bg-gray-900">

      <div className="w-sm">
       <h1 className="mt-10 text-center text-2xl/9 font-bold text-white">Sign in to your account</h1>
      </div>

      <div className='flex flex-col gap-1.5 w-sm'>
        <label htmlFor="email" className="block text-sm font-medium text-gray-100">Email address</label>
        <input id="email" name="email" type="email" required placeholder="john@my-company.com"
          className="block rounded-md w-full bg-white/5 px-2 py-1.5 placeholder:text-gray-500 text-white outline-1 outline-white/10  focus:outline-indigo-500"/>
      </div>

      <div className='flex flex-col gap-1.5 w-sm'>
        <label htmlFor="password" className="block text-sm font-medium text-gray-100">Password</label>
        <input id="password" name="password" type="password" required placeholder="*****"
          className="block rounded-md w-full bg-white/5 px-2 py-1.5 placeholder:text-gray-500 text-white outline-1 outline-white/10  focus:outline-indigo-500"/>
      </div>

      {state?.error && (
        <div className="rounded-md px-3 py-2 text-sm text-red-500">
          {state.error}
        </div>
      )}

      <button type="submit" disabled={isPending}
        className="flex w-sm justify-center rounded-md bg-indigo-500 px-3 py-1.5 text-sm/6 font-semibold text-white hover:bg-indigo-400">
        Sign in
      </button>
    </form>
  );
}
```

## Create home page

In last step, lets create the home page and display authenticated user status:

```typescript filename="app/page.tsx"
import { auth } from '@/lib/auth/server';
import Link from 'next/link';

// Server components using auth methods must be rendered dynamically
export const dynamic = 'force-dynamic';

export default async function Home() {
  const { data: session } = await auth.getSession();

  if (session?.user) {
    return (
      <div className="flex flex-col gap-2 min-h-screen items-center justify-center bg-gray-900">
        <h1 className="mb-4 text-4xl">
          Logged in as <span className="font-bold underline">{session.user.name}</span>
        </h1>
      </div>
    );
  }

  return (
    <div className="flex flex-col gap-2 min-h-screen items-center justify-center bg-gray-900">
      <h1 className="mb-4 text-4xl font-bold">Not logged in</h1>
      <div className="flex item-center gap-2">
        <Link
          href="/auth/sign-up"
          className="inline-flex text-lg text-indigo-400 hover:underline"
        >
          Sign-up
        </Link>
        <Link
          href="/auth/sign-in"
          className="inline-flex text-lg text-indigo-400 hover:underline"
        >
          Sign-in
        </Link>
      </div>
    </div>
  );
}
```

## Start your app

Start the development server:

Open your browser to [http://localhost:3000](http://localhost:3000) and test sign-up and sign-in.

**Note: Safari users**

Safari blocks third-party cookies on non-HTTPS connections. Use `npm run dev -- --experimental-https` and open `https://localhost:3000` instead.

```bash filename="Terminal"
npm run dev
```

## Available SDK methods

Both `authClient` and `auth` expose similar API methods. Use `authClient` for client components and `auth` for server components, server actions, and API routes.

- [authClient.signUp.email()](https://neon.com/docs/reference/javascript-sdk#auth-signup) / `auth.signUp.email()` - Create a new user account
- [authClient.signIn.email()](https://neon.com/docs/reference/javascript-sdk#auth-signinwithpassword) / `auth.signIn.email()` - Sign in with email and password
- [authClient.signOut()](https://neon.com/docs/reference/javascript-sdk#auth-signout) / `auth.signOut()` - Sign out the current user
- [authClient.getSession()](https://neon.com/docs/reference/javascript-sdk#auth-getsession) / `auth.getSession()` - Get the current session
- `authClient.updateUser()` / `auth.updateUser()` - Update user details

The `auth` instance also includes `.handler()` for API routes and `.middleware()` for route protection.

## Next steps

- [Next.js Server SDK reference](https://neon.com/docs/auth/reference/nextjs-server) — logging, cookie options, and upstream error codes
- [Auth troubleshooting](https://neon.com/docs/auth/troubleshooting#neon-auth-server-logging-in-the-terminal) — server logging, `NETWORK_*` errors, iframe cookies
- [Add email verification](https://neon.com/docs/auth/guides/email-verification)
- [Branching authentication](https://neon.com/docs/auth/branching-authentication)
- [Getting started with Managed Better Auth and Next.js](https://neon.com/guides/neon-auth-nextjs), a step-by-step tutorial
- [More example apps](https://neon.com/docs/auth/about#example-applications) in the **neon-js** `examples/` directory

--- [Document source](https://neon.com/docs/auth/quick-start/react.md) ---

> Summary: Managed Better Auth with React for Vite apps, using the `@neon/neon-js` SDK's programmatic API methods (`signUp()`, `signIn.email()`, `getSession()`) instead of pre-built UI components. Use this page when you need full control over your own auth UI rather than dropping in ready-made components. Registered users are automatically synced to the `neon_auth.user` table in your database.

# Use Managed Better Auth with React (API methods)

Build your own auth UI

Last updated: 2026-10-09

**Tip: Using an AI coding tool?**

Run `npx neon@latest init` to connect the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server) and [Agent Skills](https://neon.com/docs/ai/agent-skills) for Managed Better Auth. See [Set up with your AI editor](https://neon.com/docs/auth/about#set-up-with-your-ai-editor) for MCP tools, example prompts, and how skills help wire auth into your app.

## Create a Neon project with Auth enabled

If you don't have a Neon project yet, create one at [console.neon.tech](https://console.neon.tech).

In the Neon Console, open the **Better Auth** page and click **Enable Auth**.

You can then find your Auth **Base URL** on the Configuration tab. Copy this URL - you'll need it in the next step.

## Create a React app

Create a React app using Vite.

```bash filename="Terminal"
npm create vite@latest my-app -- --template react
```

## Install the Neon SDK

The Neon SDK provides authentication methods like `signUp()`, `getSession()`, and `signOut()` for your React app.

```bash filename="Terminal"
cd my-app
npm install @neon/neon-js@latest
```

## Set up environment variables

Create a `.env` file in your project root and add your Auth Base URL:

**Note:** Replace the URL with your actual Auth Base URL from the Neon Console.

```bash filename=".env"
VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth
```

## Configure the Neon client

Create a `src/auth.js` file to configure your auth client:

**Tip: Using Auth and Data API together?**

This quick start uses the standalone Auth client. For one `createClient()` instance that derives both Auth and Data API URLs from a single Neon URL, see [`createClient()` initialization](https://neon.com/docs/reference/javascript-sdk#initializing).

```javascript filename="src/auth.js"
import { createAuthClient } from '@neon/neon-js/auth';

export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL);
```

## Build your authentication UI

Neon JS uses a programmatic approach for managing auth state. You'll use React hooks like `useEffect` to check the session and handle auth changes.

Replace the contents of `src/App.jsx` with the following code to implement [sign-up](https://neon.com/docs/reference/javascript-sdk#auth-signup), [sign-in](https://neon.com/docs/reference/javascript-sdk#auth-signinwithpassword), and [sign-out](https://neon.com/docs/reference/javascript-sdk#auth-signout):

```jsx filename="src/App.jsx"
import { useState, useEffect } from 'react';
import { authClient } from './auth';
import './App.css';

export default function App() {
  const [session, setSession] = useState(null);
  const [user, setUser] = useState(null);
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [isSignUp, setIsSignUp] = useState(true);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    authClient.getSession().then((result) => {
      if (result.data?.session && result.data?.user) {
        setSession(result.data.session);
        setUser(result.data.user);
      }
      setLoading(false);
    });
  }, []);

  const handleSubmit = async (e) => {
    e.preventDefault();
    const result = isSignUp
      ? await authClient.signUp.email({ name: email.split('@')[0] || 'User', email, password })
      : await authClient.signIn.email({ email, password });

    if (result.error) {
      alert(result.error.message);
      return;
    }

    const sessionResult = await authClient.getSession();
    if (sessionResult.data?.session && sessionResult.data?.user) {
      setSession(sessionResult.data.session);
      setUser(sessionResult.data.user);
    }
  };

  const handleSignOut = async () => {
    await authClient.signOut();
    setSession(null);
    setUser(null);
  };

  if (loading) return <div>Loading...</div>;

  if (session && user) {
    return (
      <div>
        <h1>Logged in as {user.email}</h1>
        <button onClick={handleSignOut}>Sign Out</button>
      </div>
    );
  }

  return (
    <form onSubmit={handleSubmit}>
      <h1>{isSignUp ? 'Sign Up' : 'Sign In'}</h1>
      <input
        type="email"
        placeholder="Email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        required
      />
      <input
        type="password"
        placeholder="Password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        required
      />
      <button type="submit">{isSignUp ? 'Sign Up' : 'Sign In'}</button>
      <p>
        {isSignUp ? (
          <>
            Already have an account?{' '}
            <a
              href="#"
              onClick={(e) => {
                e.preventDefault();
                setIsSignUp(false);
              }}
            >
              Sign in
            </a>
          </>
        ) : (
          <>
            Don't have an account?{' '}
            <a
              href="#"
              onClick={(e) => {
                e.preventDefault();
                setIsSignUp(true);
              }}
            >
              Sign up
            </a>
          </>
        )}
      </p>
    </form>
  );
}
```

## Start your app

Start the development server:

Open your browser to `http://localhost:5173` and create a test user.

```bash filename="Terminal"
npm run dev
```

## See your users in the database

As users sign up, their profiles are synced to your Neon database in the `neon_auth.user` table.

Query your users table in the SQL Editor to see your new users:

```sql filename="SQL Editor"
SELECT * FROM neon_auth.user;
```

## Next steps

- [Learn about Managed Better Auth concepts](https://neon.com/docs/auth/overview)
- [More example apps](https://neon.com/docs/auth/about#example-applications) in the **neon-js** `examples/` directory
- [Explore the Neon Data API](https://neon.com/docs/data-api/get-started) to build a REST API for your data
- [View complete SDK reference](https://neon.com/docs/reference/javascript-sdk)

--- [Document source](https://neon.com/docs/auth/quick-start/tanstack-router.md) ---

> Summary: Managed Better Auth quick start for TanStack Router (file-router) using the `@neon/auth` SDK and Better Auth UI's shadcn/ui components (`<Auth>`, `<UserButton>`, `<Settings>`). Use this page when you need sign-in, sign-up, account settings, and route protection without writing custom auth UI. User profiles are stored automatically in the `neon_auth.user` table in your database.

# Use Managed Better Auth with TanStack Router

Set up authentication using pre-built UI components

Last updated: 2026-11-05

**Tip: Using an AI coding tool?**

Run `npx neon@latest init` to connect the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server) and [Agent Skills](https://neon.com/docs/ai/agent-skills) for Managed Better Auth. See [Set up with your AI editor](https://neon.com/docs/auth/about#set-up-with-your-ai-editor) for MCP tools, example prompts, and how skills help wire auth into your app.

## Create a Neon project with Auth enabled

If you don't have a Neon project yet, create one at [console.neon.tech](https://console.neon.tech).

In the Neon Console, open the **Better Auth** page and click **Enable Auth**.

You can then find your Auth URL on the Configuration tab. Copy this URL - you'll need it in the next step.

## Create a TanStack Router app

Create a new TanStack Router app using the file-router template.

```bash filename="Terminal"
npx create-tsrouter-app@latest my-app --template file-router --tailwind
```

## Install the Managed Better Auth SDK and UI

Install the Managed Better Auth SDK, initialize [shadcn/ui](https://ui.shadcn.com), and add [Better Auth UI](https://better-auth-ui.com)'s auth views, user menu, and settings pages. The shadcn CLI copies the components into `src/components/`.

The shadcn CLI installs the npm `latest` tag of `better-auth`, so run `npm i better-auth@~1.7.12` after the last `shadcn add` to match the version `@neon/auth` uses and keep one copy.

To use the examples below, choose TypeScript, `src/styles.css` as the global CSS file, `@/components` as the component alias, and no React Server Components. You can use the defaults for the other prompts.

```bash filename="Terminal"
cd my-app
npm install @neon/auth@latest
npx shadcn@latest init
npx shadcn@latest add @better-auth-ui/auth @better-auth-ui/user-button @better-auth-ui/settings
npm i better-auth@~1.7.12
```

## Set up environment variables

Create a `.env` file in your project root and add your Auth URL:

**Note:** Replace the URL with your actual Auth URL from the Neon Console.

```bash filename=".env"
VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
```

## Add trusted origins

Managed Better Auth only redirects to [trusted domains](https://neon.com/docs/auth/guides/configure-domains). Add the origin your app runs on, `http://localhost:3000` for local development, and your production origin when you deploy. Otherwise sign-in redirects and email verification links fail.

```bash filename="Terminal"
neon neon-auth domain add http://localhost:3000
neon neon-auth domain add https://myapp.com
```

## Configure the auth client

Create a `src/auth.ts` file to initialize the auth client:

**Tip: Using Auth and Data API together?**

This quick start uses the standalone Auth client. For one `createClient()` instance that derives both Auth and Data API URLs from a single Neon URL, see [`createClient()` initialization](https://neon.com/docs/reference/javascript-sdk#initializing).

```typescript filename="src/auth.ts"
import { createAuthClient } from '@neon/auth';
import { BetterAuthReactAdapter } from '@neon/auth/react/adapters';

export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL, {
  adapter: BetterAuthReactAdapter({ fetchOptions: { credentials: 'include' } }),
});
```

## Create the Auth Provider

Wrap your application in a TanStack Query `QueryClientProvider` and the `AuthProvider` the shadcn CLI copied into `src/components/auth/`. This makes the auth state available to the UI components used throughout your app.

`navigate` receives the URL's `?redirectTo=` value after sign-in, so it checks the target before navigating. See [Validate redirect targets](https://neon.com/docs/auth/reference/ui-components#validate-redirect-targets). For the other props, see the [UI components reference](https://neon.com/docs/auth/reference/ui-components#provider-setup).

```tsx filename="src/routes/__root.tsx"
import { getSafeRedirectTo } from '@better-auth-ui/core';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { Link, Outlet, createRootRoute, useRouter } from '@tanstack/react-router';
import type { ComponentProps } from 'react';
import { AuthProvider } from '@/components/auth/auth-provider';
import { Toaster } from '@/components/ui/sonner';
import { TooltipProvider } from '@/components/ui/tooltip';
import { authClient } from '../auth';
import '../styles.css';

const queryClient = new QueryClient();

export const Route = createRootRoute({
  component: Root,
});

function Root() {
  const router = useRouter();
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider
        authClient={authClient}
        emailAndPassword={{ requireEmailVerification: false }} // match your branch's setting
        navigate={({ to, replace }) => {
          const path = getSafeRedirectTo(to, window.location.origin);
          const target = path.startsWith('//') ? '/' : path;
          void router.navigate({ href: target, replace });
        }}
        Link={RouterLink}
        redirectTo="/"
      >
        <TooltipProvider>
          <Outlet />
        </TooltipProvider>
        <Toaster />
      </AuthProvider>
    </QueryClientProvider>
  );
}

// Better Auth UI passes an href with a query string, which `to` doesn't parse.
function RouterLink({
  href,
  to: _to,
  ...props
}: { href: string; to?: string } & Omit<ComponentProps<'a'>, 'href'>) {
  const url = new URL(href, window.location.origin);
  return (
    <Link
      to={url.pathname}
      search={Object.fromEntries(url.searchParams)}
      hash={url.hash.slice(1)}
      {...props}
    />
  );
}
```

## Create the Auth page

Create a route to handle authentication views (sign in, sign up, etc.). Create `src/routes/auth.$path.tsx`.

This route also serves `/auth/redirect`, which navigates on its own. Add the redirect check from [Validate redirect targets](https://neon.com/docs/auth/reference/ui-components#validate-redirect-targets) to `src/components/auth/auth-redirect.tsx`.

```tsx filename="src/routes/auth.$path.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { Auth } from '@/components/auth/auth';

export const Route = createFileRoute('/auth/$path')({
  component: AuthPage,
});

function AuthPage() {
  const { path } = Route.useParams();
  return (
    <main className="flex min-h-screen items-center justify-center p-4">
      <Auth path={path} />
    </main>
  );
}
```

## Create the Settings page

Create a route for the account and security settings. The user menu links to it. Create `src/routes/settings.$path.tsx`:

```tsx filename="src/routes/settings.$path.tsx"
import { createFileRoute } from '@tanstack/react-router';
import { Settings } from '@/components/auth/settings/settings';

export const Route = createFileRoute('/settings/$path')({
  component: SettingsPage,
});

function SettingsPage() {
  const { path } = Route.useParams();
  return (
    <main className="mx-auto w-full max-w-3xl p-4">
      <Settings path={path} />
    </main>
  );
}
```

## Protect your routes

Read the session with `useSession`, and send signed-out visitors to the sign-in page. Wait until the session query has finished fetching: right after sign-up, the cached result is still signed out while the new session loads.

Update `src/routes/index.tsx` to protect the home page:

```tsx filename="src/routes/index.tsx"
import { useSession } from '@better-auth-ui/react';
import { createFileRoute, useNavigate } from '@tanstack/react-router';
import { useEffect } from 'react';
import { UserButton } from '@/components/auth/user/user-button';
import { authClient } from '@/auth';

export const Route = createFileRoute('/')({
  component: Home,
});

function Home() {
  const navigate = useNavigate();
  const { data, isFetching } = useSession(authClient);
  const signedOut = !data && !isFetching;

  useEffect(() => {
    if (signedOut) void navigate({ to: '/auth/$path', params: { path: 'sign-in' } });
  }, [signedOut, navigate]);

  if (!data) return null;

  return (
    <main className="flex min-h-screen flex-col items-center justify-center gap-8 p-4">
      <div className="text-center">
        <h1>Welcome!</h1>
        <p>You're successfully authenticated.</p>
        <UserButton />
        <p className="mt-4 font-medium text-gray-700 dark:text-gray-200">Session and User Data:</p>
        <pre className="mx-auto w-full max-w-full overflow-x-auto rounded-lg bg-gray-900 p-4 text-left text-sm break-words whitespace-pre-wrap text-gray-100 sm:max-w-2xl">
          <code>{JSON.stringify({ session: data.session, user: data.user }, null, 2)}</code>
        </pre>
      </div>
    </main>
  );
}
```

## Start your app

Start the development server, then open [http://localhost:3000](http://localhost:3000). You'll be redirected to the sign-in page.

```bash filename="Terminal"
npm run dev
```

## See your users in the database

As users sign up, their profiles are stored in your Neon database in the `neon_auth.user` table.

Query your users table in the SQL Editor to see your new users:

```sql filename="SQL Editor"
SELECT * FROM neon_auth.user;
```

## Next steps

- [Add email verification](https://neon.com/docs/auth/guides/email-verification)
- [Learn how to branch your auth](https://neon.com/docs/auth/branching-authentication)
- [More example apps](https://neon.com/docs/auth/about#example-applications)

--- [Document source](https://neon.com/docs/auth/reference/nextjs-server.md) ---

> Summary: Managed Better Auth Next.js Server SDK (`@neon/auth/next/server`) provides server-side authentication for Next.js apps via React Server Components, API routes, middleware, and server actions. Session caching uses a signed HTTP-only cookie to reduce Auth Server calls. Use this page to implement or debug server-side sign-in, sign-up, route protection, and admin user management in Next.js. Covers `createNeonAuth()` configuration, `auth.middleware()`, `auth.getSession()`, email/OTP/OAuth sign-in, organization and admin APIs, structured upstream error codes, and migration from v0.1.

# Next.js Server SDK Reference

Server-side authentication API for Next.js with Managed Better Auth

Last updated: 2026-07-15

Reference documentation for the Managed Better Auth Next.js server SDK (`@neon/auth/next/server`). This package provides server-side authentication for Next.js applications using React Server Components, API routes, middleware, and server actions.

For client-side authentication, see the [Client SDK reference](https://neon.com/docs/reference/javascript-sdk). For UI components, see the [UI Components reference](https://neon.com/docs/auth/reference/ui-components).

## Installation

Install the Managed Better Auth package in your Next.js project using npm, yarn, pnpm, or bun.

```bash
npm install @neon/auth@latest
```

## Environment variables

Configure these environment variables in your `.env.local` file:

- **NEON_AUTH_BASE_URL** (required): Your Managed Better Auth server URL from the Neon Console
- **NEON_AUTH_COOKIE_SECRET** (required): Secret for signing session cookies (must be 32+ characters for HMAC-SHA256 security)

Generate a secure secret with: `openssl rand -base64 32`

```bash
# Required: Your Managed Better Auth server URL
NEON_AUTH_BASE_URL=https://your-neon-auth-url.neon.tech

# Required: Cookie secret for session data signing (32+ characters)
NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
```

## createNeonAuth()

Method: `createNeonAuth(config)`

Creates a unified auth instance that provides all server-side authentication functionality.

Returns an `auth` object with:

- `handler()` - Creates API route handlers
- `middleware()` - Creates Next.js middleware for route protection
- `getSession()` - Retrieves current session
- All Better Auth server methods (signIn, signUp, signOut, etc.)

### Parameters

| Parameter              | Type   | Required | Default               |
| ---------------------- | ------ | -------- | --------------------- |
| baseUrl                | string | ✓        | -                     |
| cookies.secret         | string | ✓        | -                     |
| cookies.sessionDataTtl | number |          | 300                   |
| cookies.domain         | string |          | -                     |
| cookies.sameSite       | string |          | `strict`              |
| logLevel               | string |          | `warn`                |
| logger                 | object |          | `console` (per level) |

See [Server logging](https://neon.com/docs/auth/reference/nextjs-server#server-logging) and [Upstream fetch errors](https://neon.com/docs/auth/reference/nextjs-server#upstream-fetch-errors).

```typescript
// lib/auth/server.ts
import { createNeonAuth } from '@neon/auth/next/server';

export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: {
    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
  },
  // logLevel: 'silent',
});
```

## Server logging

Managed Better Auth emits structured logs from the API proxy, middleware, and Better Auth server `fetch` for upstream failures and session issues.

**Defaults:** `logLevel: 'warn'` writes **`error`** and **`warn`** to **`console`**. Set **`logLevel: 'silent'`** to disable all Managed Better Auth `console` output (`'silent'` ignores any custom **`logger`**). Use **`info`** or **`debug`** for more detail during local troubleshooting.

**Custom sink:** Pass a partial **`logger`** object with `error`, `warn`, `info`, and/or `debug` methods. Omitted methods still use `console`. Metadata may include `err` and `detail` for observability tools.

`auth.middleware()` inherits the same resolved logging configuration from `createNeonAuth` (no per-request reconfiguration).

```typescript
import { createNeonAuth } from '@neon/auth/next/server';

export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: { secret: process.env.NEON_AUTH_COOKIE_SECRET! },
  logLevel: 'debug',
  logger: {
    warn(message, meta) {
      myLogger.warn({ message, ...meta });
    },
  },
});
```

| logLevel         | Console output          |
| ---------------- | ----------------------- |
| `silent`         | None                    |
| `error`          | `error` only            |
| `warn` (default) | `error`, `warn`         |
| `info`           | `error`, `warn`, `info` |
| `debug`          | all levels              |

## auth.handler()

Method: `auth.handler()`

Creates GET and POST route handlers for the Managed Better Auth API proxy.

Create a catch-all route at `app/api/auth/[...path]/route.ts`. This handles all authentication API calls from your client, including:

- Sign in/sign up requests
- OAuth callbacks
- Session management
- Email verification
- Password reset

### Returns

Object with `GET`, `POST`, `PUT`, `PATCH`, and `DELETE` Next.js route handlers.

```typescript
// app/api/auth/[...path]/route.ts
import { auth } from '@/lib/auth/server';

export const { GET, POST, PUT, PATCH, DELETE } = auth.handler();
```

## auth.middleware()

Method: `auth.middleware(options)`

Creates Next.js middleware for session validation and route protection.

The middleware automatically:

- Validates session cookies on each request
- Provides session data to server components
- Redirects unauthenticated users to the login page
- Refreshes session tokens when needed

### Parameters

<details>

<summary>View parameters</summary>

| Parameter    | Type      | Required | Default                                             |
| ------------ | --------- | -------- | --------------------------------------------------- |
| loginUrl     | string    |          | `/auth/sign-in`                                     |
| publicRoutes | string\[] |          | `/api/auth` and the Better Auth UI signed-out views |

`publicRoutes` adds routes that don't require a session, on top of the defaults. An entry matches the exact path and its subpaths, so `/pricing` also matches `/pricing/enterprise`. `"/"` matches only `/`. An invalid entry throws. `/auth` itself and `/settings/*` stay protected.

</details>

**Note: Next.js version compatibility**

`proxy.ts` replaces `middleware.ts` in Next.js 16. On earlier versions, name the file `middleware.ts` and export `default function middleware` instead of `proxy`. The auth logic is identical.

```typescript filename="proxy.ts"
import { auth } from '@/lib/auth/server';

export default auth.middleware({
  loginUrl: '/auth/sign-in',
  publicRoutes: ['/']
});

export const config = {
  matcher: [
    // Match all paths except static files
    "/((?!_next/static|_next/image|favicon.ico).*)",
  ],
};
```

## auth.getSession()

Method: `auth.getSession()`

Retrieves the current session in Server Components, Server Actions, and API Routes.

- Returns cached session if available (fast)
- Automatically refreshes expired tokens
- Returns null if no active session

Server Components that use `auth.getSession()` must export `dynamic = 'force-dynamic'` because session data depends on cookies.

### Returns

| Field   | Type            | Description                                          |
| ------- | --------------- | ---------------------------------------------------- |
| `data`  | Session \| null | Session with user data, or null if not authenticated |
| `error` | Error \| null   | Error object if session retrieval failed             |

**Server Component**

```typescript
// app/dashboard/page.tsx
import { auth } from '@/lib/auth/server';

export const dynamic = 'force-dynamic';

export default async function DashboardPage() {
  const { data: session } = await auth.getSession();

  if (!session?.user) {
    return <div>Not authenticated</div>;
  }

  return <h1>Welcome, {session.user.name}</h1>;
}
```

**Server Action**

```typescript
// app/actions.ts
'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';

export async function updateProfile(formData: FormData) {
  const { data: session } = await auth.getSession();

  if (!session?.user) {
    redirect('/auth/sign-in');
  }

  // Update user profile...
}
```

**API Route**

```typescript
// app/api/user/route.ts
import { auth } from '@/lib/auth/server';

export async function GET() {
  const { data: session } = await auth.getSession();

  if (!session?.user) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return Response.json({ user: session.user });
}
```

## auth.signIn.email()

Method: `auth.signIn.email(credentials)`

Sign in with email and password. Use in Server Actions for form-based authentication.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| email     | string | ✓        |
| password  | string | ✓        |

</details>

```typescript
'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';

export async function signIn(formData: FormData) {
  const { data, error } = await auth.signIn.email({
    email: formData.get('email') as string,
    password: formData.get('password') as string,
  });

  if (error) return { error: error.message };
  redirect('/dashboard');
}
```

## auth.signIn.social()

Method: `auth.signIn.social(options)`

Sign in with OAuth provider like Google, GitHub, etc.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter   | Type   | Required |
| ----------- | ------ | -------- |
| provider    | string | ✓        |
| callbackURL | string |          |

</details>

```typescript
const { data, error } = await auth.signIn.social({
  provider: 'google',
  callbackURL: '/dashboard',
});
```

## auth.signIn.emailOtp()

Method: `auth.signIn.emailOtp(credentials)`

Sign in with email OTP (one-time password). First call `emailOtp.sendVerificationOtp()` to send the code.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| email     | string | ✓        |
| otp       | string | ✓        |

</details>

```typescript
const { data, error } = await auth.signIn.emailOtp({
  email: 'user@example.com',
  otp: '123456',
});
```

## auth.signUp.email()

Method: `auth.signUp.email(credentials)`

Create a new user account with email and password.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| email     | string | ✓        |
| password  | string | ✓        |
| name      | string | ✓        |

</details>

```typescript
const { data, error } = await auth.signUp.email({
  email: 'user@example.com',
  password: 'secure-password',
  name: 'John Doe',
});
```

## auth.signOut()

Method: `auth.signOut()`

Sign out the current user. Clears session and authentication tokens.

```typescript
'use server';
import { auth } from '@/lib/auth/server';
import { redirect } from 'next/navigation';

export async function signOut() {
  await auth.signOut();
  redirect('/auth/sign-in');
}
```

## auth.updateUser()

Method: `auth.updateUser(data)`

Update the current user's profile. Password updates require the password reset flow for security.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type                | Required |
| --------- | ------------------- | -------- |
| name      | string \| undefined |          |
| image     | string \| undefined |          |

</details>

```typescript
const { data, error } = await auth.updateUser({
  name: 'Jane Doe',
  image: 'https://example.com/avatar.jpg',
});
```

## auth.changePassword()

Method: `auth.changePassword(passwords)`

Change the current user's password.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter           | Type    | Required |
| ------------------- | ------- | -------- |
| currentPassword     | string  | ✓        |
| newPassword         | string  | ✓        |
| revokeOtherSessions | boolean |          |

</details>

```typescript
const { data, error } = await auth.changePassword({
  currentPassword: 'old-password',
  newPassword: 'new-password',
  revokeOtherSessions: true,
});
```

## auth.sendVerificationEmail()

Method: `auth.sendVerificationEmail(options)`

Send email verification to the current user.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter   | Type   | Required |
| ----------- | ------ | -------- |
| callbackURL | string |          |

</details>

```typescript
const { data, error } = await auth.sendVerificationEmail({
  callbackURL: '/dashboard',
});
```

## auth.deleteUser()

Method: `auth.deleteUser()`

Delete the current user account. This action is irreversible.

```typescript
const { data, error } = await auth.deleteUser();
```

## auth.emailOtp.sendVerificationOtp()

Method: `auth.emailOtp.sendVerificationOtp(options)`

Send a one-time password via email. Available when Email OTP authentication is enabled.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| email     | string | ✓        |

</details>

```typescript
const { data, error } = await auth.emailOtp.sendVerificationOtp({
  email: 'user@example.com',
});
```

## auth.emailOtp.verifyEmail()

Method: `auth.emailOtp.verifyEmail(credentials)`

Verify email with OTP code.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| email     | string | ✓        |
| otp       | string | ✓        |

</details>

```typescript
const { data, error } = await auth.emailOtp.verifyEmail({
  email: 'user@example.com',
  otp: '123456',
});
```

## auth.listSessions()

Method: `auth.listSessions()`

List all active sessions for the current user.

```typescript
const { data, error } = await auth.listSessions();
```

## auth.revokeSession()

Method: `auth.revokeSession(options)`

Revoke a specific session by ID.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| sessionId | string | ✓        |

</details>

```typescript
const { data, error } = await auth.revokeSession({
  sessionId: 'session-id',
});
```

## auth.revokeOtherSessions()

Method: `auth.revokeOtherSessions()`

Revoke all sessions except the current one.

```typescript
const { data, error } = await auth.revokeOtherSessions();
```

## auth.organization.create()

Method: `auth.organization.create(data)`

Create a new organization. Available when the organizations plugin is enabled.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| name      | string | ✓        |
| slug      | string |          |

</details>

```typescript
const { data, error } = await auth.organization.create({
  name: 'My Organization',
  slug: 'my-org',
});
```

## auth.organization.list()

Method: `auth.organization.list()`

List the current user's organizations.

```typescript
const { data, error } = await auth.organization.list();
```

## auth.organization.inviteMember()

Method: `auth.organization.inviteMember(options)`

Invite a member to an organization.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter      | Type   | Required |
| -------------- | ------ | -------- |
| organizationId | string | ✓        |
| email          | string | ✓        |
| role           | string |          |

</details>

```typescript
const { data, error } = await auth.organization.inviteMember({
  organizationId: 'org-id',
  email: 'member@example.com',
  role: 'member',
});
```

## auth.admin.listUsers()

Method: `auth.admin.listUsers(options)`

List all users. Available for users with admin role.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| limit     | number |          |
| offset    | number |          |

</details>

```typescript
const { data, error } = await auth.admin.listUsers({
  limit: 100,
  offset: 0,
});
```

## auth.admin.banUser()

Method: `auth.admin.banUser(options)`

Ban a user. Available for users with admin role.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| userId    | string | ✓        |
| reason    | string |          |

</details>

```typescript
const { data, error } = await auth.admin.banUser({
  userId: 'user-id',
  reason: 'Violation of terms',
});
```

## auth.admin.setRole()

Method: `auth.admin.setRole(options)`

Set a user's role. Available for users with admin role.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| userId    | string | ✓        |
| role      | string | ✓        |

</details>

```typescript
const { data, error } = await auth.admin.setRole({
  userId: 'user-id',
  role: 'admin',
});
```

## Upstream fetch errors

When the SDK cannot reach your Managed Better Auth server (wrong `baseUrl`, DNS, TLS, timeout), the API proxy returns a synthetic **502** JSON body with a stable **`code`**. Server methods such as `auth.signIn.email()` surface the same codes on **`error.code`** when the failure is transport-related.

| Code              | Typical cause             |
| ----------------- | ------------------------- |
| `NETWORK_DNS`     | Hostname does not resolve |
| `NETWORK_REFUSED` | Connection refused        |
| `NETWORK_TIMEOUT` | Request timed out         |
| `NETWORK_TLS`     | TLS / certificate error   |
| `NETWORK_RESET`   | Connection reset          |
| `NETWORK_ABORT`   | Request aborted           |
| `NETWORK_ERROR`   | Other transport failure   |

Client-visible messages are generic (for example, "Could not resolve authentication server hostname"). Check server logs (set `logLevel: 'debug'`) for `detail` and the raw error.

**Non-transport failures** (unexpected exceptions while handling a response) are **re-thrown** so Next.js error boundaries still receive the original error. HTTP **4xx** upstream responses are logged at **`info`**; **5xx** at **`warn`**.

```typescript
'use server';

import { auth } from '@/lib/auth/server';

export async function signIn(formData: FormData) {
  const { error } = await auth.signIn.email({
    email: formData.get('email') as string,
    password: formData.get('password') as string,
  });

  if (error?.code === 'NETWORK_DNS') {
    return { error: 'Check NEON_AUTH_BASE_URL in .env.local' };
  }

  if (error) {
    return { error: error.message };
  }
}
```

## Performance features

### Session caching

Session data is automatically cached in a signed, HTTP-only cookie to reduce API calls to the Auth Server by 95-99%.

- Default cache TTL: 5 minutes (300 seconds)
- Configurable via `cookies.sessionDataTtl`
- Automatic expiration based on JWT `exp` claim
- Synchronous cache clearing on sign-out
- Secure HMAC-SHA256 signing

### Request deduplication

Multiple concurrent `getSession()` calls are automatically deduplicated:

- Single network request for concurrent calls
- 10x faster cold starts
- Reduces server load

```typescript
// First call: Fetches from Auth Server
const { data: session } = await auth.getSession();

// Subsequent calls within TTL: Uses cached data (no API call)
const { data: session2 } = await auth.getSession();
```

## Configuration reference

Complete configuration options for `createNeonAuth()`:

| Option                   | Type   | Required | Default   |
| ------------------------ | ------ | -------- | --------- |
| `baseUrl`                | string | Yes      | -         |
| `cookies.secret`         | string | Yes      | -         |
| `cookies.sessionDataTtl` | number | No       | 300       |
| `cookies.domain`         | string | No       | undefined |
| `cookies.sameSite`       | string | No       | `strict`  |
| `logLevel`               | string | No       | `warn`    |
| `logger`                 | object | No       | `console` |

- **baseUrl**: Your Managed Better Auth server URL from the Neon Console
- **cookies.secret**: Secret for HMAC-SHA256 signing (32+ characters)
- **cookies.sessionDataTtl**: Cache TTL in seconds for the signed `session_data` cookie
- **cookies.domain**: For cross-subdomain sessions (for example, ".example.com")
- **cookies.sameSite**: `strict` (default), `lax`, or `none`. Use `lax` or `none` if you embed the app in a third-party iframe or need cookies on cross-site navigations
- **logLevel**: `silent`, `error`, `warn`, `info`, or `debug` — see [Server logging](https://neon.com/docs/auth/reference/nextjs-server#server-logging)
- **logger**: Optional custom logger; see [Server logging](https://neon.com/docs/auth/reference/nextjs-server#server-logging)

```typescript
import { createNeonAuth } from '@neon/auth/next/server';

export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: {
    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
  },
});
```

## Project structure

Recommended file structure for Next.js with Managed Better Auth:

- `app/api/auth/[...path]/route.ts` - Auth API handlers
- `app/auth/[path]/page.tsx` - Auth views (sign-in, sign-up)
- `app/dashboard/page.tsx` - Protected pages
- `lib/auth/server.ts` - Server auth instance
- `lib/auth/client.ts` - Client auth instance
- `proxy.ts` (Next.js 16+) or `middleware.ts` (earlier versions) - Route protection

**Note: Next.js version compatibility**

`proxy.ts` replaces `middleware.ts` in Next.js 16. On earlier versions, name the file `middleware.ts` and export `default function middleware` instead of `proxy`. The auth logic is identical.

```
app/
├── api/
│   └── auth/
│       └── [...path]/
│           └── route.ts
├── auth/
│   └── [path]/
│       └── page.tsx
├── dashboard/
│   └── page.tsx
├── actions.ts
└── layout.tsx

lib/
└── auth/
    ├── server.ts
    └── client.ts

proxy.ts          # or middleware.ts on Next.js < 16
.env.local
```

## Migration from v0.1

If you're upgrading from Managed Better Auth SDK v0.1, see the [migration guide](https://neon.com/docs/auth/migrate/from-auth-v0.1) for step-by-step instructions.

## Related documentation

- [Client SDK Reference](https://neon.com/docs/reference/javascript-sdk) - Client-side authentication
- [UI Components Reference](https://neon.com/docs/auth/reference/ui-components) - Pre-built auth UI
- [Next.js quick start](https://neon.com/docs/auth/quick-start/nextjs-api-only) - Getting started guide
- [Migration Guide](https://neon.com/docs/auth/migrate/from-auth-v0.1) - Upgrading from v0.1

--- [Document source](https://neon.com/docs/auth/reference/ui-components.md) ---

> Summary: How to add Better Auth UI's shadcn/ui components to an app on Managed Better Auth: install them with the shadcn CLI, wrap the app in `AuthProvider` with the `@neon/auth` client, and render `<Auth>` on `/auth/[path]` and `<UserButton>` in the header. Use this page for the provider props, redirect validation, and route protection.

# UI Components Reference

Sign-in, sign-up, and user menu components for Managed Better Auth

Last updated: 2026-09-16

Managed Better Auth works with [Better Auth UI](https://better-auth-ui.com): sign-in, sign-up, password reset, and user menu components for Better Auth. The shadcn CLI copies the components into your app, so you can edit them. `@better-auth-ui/react` provides the hooks and data layer they use.

**Note: Coming from @neondatabase/auth-ui**

`@neondatabase/auth-ui` is deprecated. Existing apps keep working; new apps use Better Auth UI. `NeonAuthUIProvider` becomes `AuthProvider`, `<AuthView path>` becomes `<Auth path>`, and the CSS imports go away because your app's Tailwind compiles the copied components.

## Installation

Better Auth UI needs React 19.2.6 or later and Tailwind CSS 4.3.2 or later. If the project doesn't use shadcn/ui yet, initialize it first:

```bash
npx shadcn@latest init
```

### Add the components

Add the auth views, and the user menu if you want one:

```bash
npx shadcn@latest add @better-auth-ui/auth
npx shadcn@latest add @better-auth-ui/user-button
```

The CLI writes the components to `components/auth/` and their shadcn/ui primitives to `components/ui/`, and installs `@better-auth-ui/react`, `@better-auth-ui/core`, and TanStack Query.

The components list `better-auth` without a version, so the CLI installs the npm `latest` tag, which can be a newer pre-release than the version `@neon/auth` uses. After your last `shadcn add`, align it with `@neon/auth` so the app has one copy of Better Auth:

```bash
npm i better-auth@~1.7.12
```

## Provider setup

Wrap the app in a TanStack Query `QueryClientProvider` and the copied `AuthProvider`. Pass the client from `createAuthClient()` in `@neon/auth` as `authClient`; it needs no adapter or type cast.

```tsx
'use client';

import { getSafeRedirectTo } from '@better-auth-ui/core';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import Link from 'next/link';
import { useRouter } from 'next/navigation';
import { useState } from 'react';
import { AuthProvider } from '@/components/auth/auth-provider';
import { Toaster } from '@/components/ui/sonner';
import { TooltipProvider } from '@/components/ui/tooltip';
import { authClient } from '@/lib/auth/client';

export function Providers({ children }: { children: React.ReactNode }) {
  const router = useRouter();
  const [queryClient] = useState(() => new QueryClient());
  return (
    <QueryClientProvider client={queryClient}>
      <AuthProvider
        authClient={authClient}
        emailAndPassword={{ requireEmailVerification: false }} // match your branch's setting
        navigate={({ to, replace }) => {
          const path = getSafeRedirectTo(to, window.location.origin);
          const target = path.startsWith('//') ? '/' : path;
          if (replace) router.replace(target);
          else router.push(target);
        }}
        Link={Link}
        redirectTo="/"
      >
        <TooltipProvider>{children}</TooltipProvider>
        <Toaster />
      </AuthProvider>
    </QueryClientProvider>
  );
}
```

Render `<Toaster />` once: the components report errors as toasts. In a single-page app, you can create the `QueryClient` once at module level instead.

| Prop               | Description                                                                                                                 |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `authClient`       | **Required.** The client from `createAuthClient()` in `@neon/auth`.                                                         |
| `navigate`         | **Required.** Called with `{ to, replace }` for every navigation the components make.                                       |
| `Link`             | **Required.** The router's link component, for example `next/link` or a TanStack Router `Link` adapter.                     |
| `redirectTo`       | Where to go after sign-in when the URL has no `?redirectTo=`.                                                               |
| `emailAndPassword` | Email and password options. Set `requireEmailVerification` to match your branch's **Verify email at signup** setting.       |
| `socialProviders`  | OAuth provider buttons to show, for example `['google', 'github']`. Configure the providers for your branch first.          |
| `plugins`          | Better Auth UI plugins, for example `emailOtpPlugin()`. A UI plugin doesn't enable the matching Managed Better Auth plugin. |

### Validate redirect targets

After sign-in, the components call `navigate` with the `?redirectTo=` value from the URL. Check it before you navigate, as in the example above, so a link like `/auth/sign-in?redirectTo=https://example.com` can't send a signed-in user to another site. `getSafeRedirectTo` returns `/` for other origins, but it can return a protocol-relative path such as `//example.com` for `/a/..//example.com`, so also reject a result that starts with `//`.

The `/auth/redirect` view navigates without `navigate`. Add the same check to the copied `components/auth/auth-redirect.tsx`:

```tsx filename="components/auth/auth-redirect.tsx"
window.location.replace(action.to);
window.location.replace(action.to.startsWith('//') ? '/' : action.to);
```

## Components

| Component      | Purpose                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `<Auth>`       | Renders the auth view for a path: `sign-in`, `sign-up`, `forgot-password`, `reset-password`, `sign-out`, ... |
| `<UserButton>` | Avatar and menu with the signed-in user and Sign Out. `hideSettings` hides the Settings link.                |

Hooks from `@better-auth-ui/react`:

| Hook                          | Purpose                                                                                                                                                 |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useSession(authClient)`      | The session as a TanStack Query result (`data`, `isPending`, `isFetching`).                                                                             |
| `useAuthenticate(authClient)` | The session, and a redirect to sign-in when there is none. See [Protected routes](https://neon.com/docs/auth/reference/ui-components#protected-routes). |

## Next.js App Router

Create `app/auth/[path]/page.tsx`. The valid paths come from `viewPaths.auth` in `@better-auth-ui/core`:

```tsx
import { viewPaths } from '@better-auth-ui/core';
import { Auth } from '@/components/auth/auth';

export const dynamicParams = false;

export function generateStaticParams() {
  return Object.values(viewPaths.auth).map((path) => ({ path }));
}

export default async function AuthPage({ params }: { params: Promise<{ path: string }> }) {
  const { path } = await params;
  return (
    <main className="flex min-h-screen items-center justify-center p-4">
      <Auth path={path} />
    </main>
  );
}
```

The `/auth/[path]` route also serves `/auth/sign-out`, which the user menu's **Sign Out** opens.

Add the user menu to a header. Its **Settings** link opens `/settings/account`: add `npx shadcn@latest add @better-auth-ui/settings` and a `settings/[path]` route that renders `<Settings path={path} />`, or pass `hideSettings`.

```tsx
import { UserButton } from '@/components/auth/user/user-button';

export function Header() {
  return (
    <header>
      <UserButton size="icon" hideSettings />
    </header>
  );
}
```

## Protected routes

Redirect signed-out requests on the server, with `auth.middleware()` in `proxy.ts` (see the [Next.js server reference](https://neon.com/docs/auth/reference/nextjs-server)) or your router's guard.

```typescript filename="proxy.ts"
import { auth } from '@/lib/auth/server';

export default auth.middleware({ loginUrl: '/auth/sign-in', publicRoutes: ['/'] });
```

Better Auth UI's signed-out views, such as reset password, verify email, and magic link, and `/api/auth` are public by default, so you don't need a custom `proxy.ts` for them. `/auth` itself and `/settings/*` stay protected. Use `publicRoutes` for your own public pages, such as a landing page.

On the page, read the session with `useSession()` and wait for it to load.

`useAuthenticate()` redirects whenever it has no session and the query isn't pending, including while a stale signed-out result refetches. Right after sign-up, that sends the new user back to sign-in. If you redirect on the client, wait until `isFetching` is `false`:

```tsx
const { data: session, isFetching } = useSession(authClient);
const signedOut = !session && !isFetching;
```

## Styling

The copied components use your app's Tailwind build and shadcn/ui theme variables. `shadcn init` adds the theme to your global CSS, including:

```css
@import 'tailwindcss';
@import 'tw-animate-css';
@import 'shadcn/tailwind.css';
```

To change colors, radius, or dark mode, edit the theme variables in that file or the component files in `components/auth/`.

## Next steps

- See the [Neon examples](https://github.com/neondatabase/examples/tree/main/realtime) for apps that use these components with Next.js, TanStack Start, and Vite
- Read the [Better Auth UI docs](https://better-auth-ui.com/docs) for every component, plugin, and hook
- Check the [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk) for programmatic auth methods

--- [Document source](https://neon.com/docs/auth/roadmap.md) ---

> Summary: Managed Better Auth roadmap showing supported frameworks (Next.js, Vite+React, TanStack Router) and Better Auth plugins (email OTP, magic link, JWT, organization) alongside features still in progress. Check here to confirm whether MFA, admin plugin customization, or standalone frontend/backend architectures are available yet. Migration guides from Supabase and legacy Stack Auth, plus SDK references for the TypeScript client and Next.js server SDK, are also indexed here.

# Managed Better Auth roadmap

What's supported today and what's coming next

Last updated: 2026-09-17

Managed Better Auth is in active development. This page shows what's currently supported and what we're working on next.

## General availability

Managed Better Auth is generally available. We're actively working on additional plugins and features.

## Frameworks

### Supported

| Framework               | Status      | Quick start                                                           |
| ----------------------- | ----------- | --------------------------------------------------------------------- |
| Next.js                 | ✅ Supported | [Get started](https://neon.com/docs/auth/quick-start/nextjs-api-only) |
| Vite + React            | ✅ Supported | [Get started](https://neon.com/docs/auth/quick-start/react)           |
| React + React Router    | ✅ Supported | [Get started](https://neon.com/docs/auth/quick-start/react)           |
| React + TanStack Router | ✅ Supported | [Get started](https://neon.com/docs/auth/quick-start/tanstack-router) |

The [React quick start](https://neon.com/docs/auth/quick-start/react) steps through a **Vite** + React app. If you use **React Router** for URLs and layouts, use the same Managed Better Auth URL, `@neon/neon-js` client, and SDK calls from that guide, then integrate them into your router and route components. For file-based routing with TanStack, use the TanStack Router quick start instead.

### On the roadmap

| Framework                     | Status          |
| ----------------------------- | --------------- |
| Standalone frontend + backend | 🔜 Coming soon  |
| Other frameworks              | Based on demand |

**Note: Standalone architectures**

Architectures where frontend and backend are separate deployments (for example, Create-React-App with a separate Node/Express backend) are not yet supported. Managed Better Auth uses HTTP-only cookies for secure session management, and these cookies cannot be securely shared between frontend and backend applications on different domains. We're actively working on this.

## Better Auth plugins

Managed Better Auth is built on [Better Auth](https://www.better-auth.com/). Not all Better Auth plugins are currently supported.

### Supported

| Plugin                                                                             | Status      |
| ---------------------------------------------------------------------------------- | ----------- |
| [Email & password](https://www.better-auth.com/docs/authentication/email-password) | ✅ Supported |
| Social OAuth (Google, GitHub, Vercel, Microsoft, Apple)                            | ✅ Supported |
| [Email OTP](https://neon.com/docs/auth/guides/plugins/email-otp)                   | ✅ Supported |
| [Admin](https://neon.com/docs/auth/guides/plugins/admin)                           | ✅ Supported |
| [Organization](https://neon.com/docs/auth/guides/plugins/organization)             | ⚠️ Partial  |
| [JWT](https://neon.com/docs/auth/guides/plugins/jwt)                               | ✅ Supported |
| [Magic Link](https://neon.com/docs/auth/guides/plugins/magic-link)                 | ✅ Supported |
| [Open API](https://neon.com/docs/auth/guides/plugins/openapi)                      | ✅ Supported |
| [Phone Number](https://neon.com/docs/auth/guides/plugins/phone-number)             | ✅ Supported |

See [Set up OAuth](https://neon.com/docs/auth/guides/setup-oauth) for Neon-specific OAuth configuration (including Vercel). Email flows such as verification and password reset are covered in [Email verification](https://neon.com/docs/auth/guides/email-verification), [Password reset](https://neon.com/docs/auth/guides/password-reset), and [User management](https://neon.com/docs/auth/guides/user-management).

### Platform (Console, API, webhooks)

These capabilities are documented in Managed Better Auth guides but are not Better Auth plugins you enable through the SDK.

| Capability                           | Status    | Documentation                                                                             |
| ------------------------------------ | --------- | ----------------------------------------------------------------------------------------- |
| Trusted domains (redirect allowlist) | Supported | [Configure trusted domains](https://neon.com/docs/auth/guides/configure-domains)          |
| Webhooks (auth events)               | Supported | [Webhooks](https://neon.com/docs/auth/guides/webhooks)                                    |
| Manage Auth via Neon API             | Supported | [Manage Auth in the Neon API](https://neon.com/docs/auth/guides/manage-auth-api)          |
| Manage Auth via Neon MCP (AI editor) | Supported | [Set up with your AI editor](https://neon.com/docs/auth/about#set-up-with-your-ai-editor) |

Branch-aware auth (separate auth state per Neon branch) is supported; see [Branching authentication](https://neon.com/docs/auth/branching-authentication) and [Authentication flow](https://neon.com/docs/auth/authentication-flow).

### On the roadmap

| Plugin                                                                        | Status          |
| ----------------------------------------------------------------------------- | --------------- |
| MFA support                                                                   | 🔜 Coming soon  |
| [Admin](https://neon.com/docs/auth/guides/plugins/admin) plugin customization | 🔜 Coming soon  |
| Other plugins                                                                 | Based on demand |

## SDK and UI references

| Surface                           | Documentation                                                            |
| --------------------------------- | ------------------------------------------------------------------------ |
| TypeScript client SDK (`neon-js`) | [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk)    |
| Next.js server SDK                | [Next.js Server SDK](https://neon.com/docs/auth/reference/nextjs-server) |
| Pre-built UI components           | [UI components](https://neon.com/docs/auth/reference/ui-components)      |

## Migration guides

- [From Managed Better Auth SDK v0.1](https://neon.com/docs/auth/migrate/from-auth-v0.1)
- [From Stack Auth (legacy)](https://neon.com/docs/auth/migrate/from-legacy-auth)
- [From Supabase](https://neon.com/docs/auth/migrate/from-supabase)

## Production and checklist

For launch readiness, see the [production checklist](https://neon.com/docs/auth/production-checklist).

## Let us know

We prioritize based on demand. If you need a specific framework or plugin, let us know on our [Discord](https://neon.com/discord).

--- [Document source](https://neon.com/docs/auth/troubleshooting.md) ---

> Summary: Troubleshooting for common Managed Better Auth errors in `@neon/auth` (Next.js and React SPA). Covers missing `NEON_AUTH_COOKIE_SECRET`, missing `force-dynamic` on server components, `NETWORK_DNS` / `NETWORK_TIMEOUT` upstream errors, `Origin` errors when scripts call the Auth API directly, and OAuth `redirect_uri_mismatch` from misconfigured callback URIs. Use this page when Managed Better Auth fails at startup, sessions do not persist, or OAuth logins loop back to the provider instead of the app.

# Auth troubleshooting

Common issues when implementing Managed Better Auth and how to fix them

Last updated: 2026-11-05

This page covers common issues when integrating [Managed Better Auth](https://neon.com/docs/auth/overview) with `@neon/auth` in Next.js apps and React SPAs.

## Missing NEON_AUTH_COOKIE_SECRET

If your Next.js app throws an error about a missing or invalid cookie secret at startup, the `NEON_AUTH_COOKIE_SECRET` environment variable is either unset or too short. The secret must be at least 32 characters for HMAC-SHA256. Generate one with:

```bash
openssl rand -base64 32
```

See the [Next.js Server SDK reference](https://neon.com/docs/auth/reference/nextjs-server) for the full list of required environment variables.

## Missing force-dynamic on server components

If `next build` fails with a "Dynamic server usage" error on a page that calls `auth.getSession()`, the server component needs to opt out of static rendering:

```typescript
export const dynamic = 'force-dynamic';

export default async function Page() {
  const { data: session } = await auth.getSession();
  // ...
}
```

This is required because `getSession()` reads cookies, which are only available at request time. See [getSession](https://neon.com/docs/auth/reference/nextjs-server#get-session) in the Next.js Server SDK reference.

## Managed Better Auth server logging in the terminal

You may see structured **`warn`** or **`error`** lines in the Next.js server console when the auth proxy cannot reach Managed Better Auth or when session cookies fail validation. This is expected: the SDK defaults to **`logLevel: 'warn'`** (opt-out).

To mute Managed Better Auth console output:

```typescript
export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: { secret: process.env.NEON_AUTH_COOKIE_SECRET! },
  logLevel: 'silent',
});
```

To investigate further, use **`logLevel: 'debug'`** or a custom **`logger`**. See [Server logging](https://neon.com/docs/auth/reference/nextjs-server#server-logging).

## Upstream NETWORK_* errors

Server actions or API routes may return errors with **`code`** values such as **`NETWORK_DNS`**, **`NETWORK_REFUSED`**, or **`NETWORK_TIMEOUT`**. These mean your app could not reach the Auth server at **`NEON_AUTH_BASE_URL`** (typo, wrong branch URL, offline network, or TLS issue).

1. Confirm **`NEON_AUTH_BASE_URL`** in `.env.local` matches the Auth URL in the Neon Console (Project → Branch → Auth → Configuration).
2. Restart the dev server after changing env vars.
3. Enable **`logLevel: 'debug'`** and retry; logs include a safe **`detail`** field.

See [Upstream fetch errors](https://neon.com/docs/auth/reference/nextjs-server#upstream-fetch-errors) for the full code list.

## Origin errors from scripts and server-side calls

Managed Better Auth checks the `Origin` header on `POST` requests such as sign-up, sign-in, and sign-out. Browsers send it for you, and so does the `@neon/auth` Next.js handler. Seed scripts, tests, and server code that call `NEON_AUTH_BASE_URL` directly have to send it themselves. Without a trusted `Origin`, the request fails:

| Response                       | Cause                                                         |
| ------------------------------ | ------------------------------------------------------------- |
| `403` `MISSING_OR_NULL_ORIGIN` | No `Origin` header (or `Origin: null`) on sign-in or sign-out |
| `400` `MISSING_ORIGIN`         | No `Origin` header on sign-up                                 |
| `403` `INVALID_ORIGIN`         | The `Origin` isn't a trusted domain                           |

Set `Origin` to a trusted domain:

```typescript
const res = await fetch(`${process.env.NEON_AUTH_BASE_URL}/sign-in/email`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Origin: 'http://localhost:3000',
  },
  body: JSON.stringify({ email: 'alex@example.com', password: 'AbC123dEf' }),
});
```

Any `localhost` origin is trusted while [localhost access](https://neon.com/docs/auth/production-checklist#localhost-access) is on, which it is by default. Add any other origin as a [trusted domain](https://neon.com/docs/auth/guides/configure-domains), for example with `neon neon-auth domain add https://myapp.com`.

## Cookies blocked in iframe or cross-site embeds

Managed Better Auth cookies default to **`SameSite=Strict`**. If your app runs inside another site's **iframe**, or needs cookies on top-level cross-site navigations, sessions may not persist.

Set an explicit SameSite mode when creating the auth instance:

```typescript
export const auth = createNeonAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookies: {
    secret: process.env.NEON_AUTH_COOKIE_SECRET!,
    sameSite: 'lax', // or 'none' for third-party iframe contexts (requires HTTPS)
  },
});
```

See [Configuration reference](https://neon.com/docs/auth/reference/nextjs-server#configuration-reference) and the [Next.js quick start](https://neon.com/docs/auth/quick-start/nextjs-api-only).

## Using v0.1 API patterns

If you are upgrading from v0.1, use `createNeonAuth()` + `auth.handler()` instead of the old standalone `authApiHandler()`. See the [migration guide](https://neon.com/docs/auth/migrate/from-auth-v0.1) for details.

## Using useSession() without adapter in React SPA

In a React SPA, `createAuthClient(url)` without an adapter returns a vanilla client with no React hooks. Calling `useSession()` on this client will fail. Either pass `BetterAuthReactAdapter()`, or read the session with `useSession(authClient)` from `@better-auth-ui/react`, which takes any Managed Better Auth client. It reads the session through TanStack Query, so wrap your app in a `QueryClientProvider` (or pass a `queryClient` as the third argument).

```typescript
import { createAuthClient } from '@neon/auth';
import { BetterAuthReactAdapter } from '@neon/auth/react/adapters';

const authClient = createAuthClient(url, {
  adapter: BetterAuthReactAdapter(),
});
```

The [TanStack Router quick start](https://neon.com/docs/auth/quick-start/tanstack-router) shows a complete setup with the React adapter.

## Wrong BetterAuthReactAdapter import

The adapter must be imported from a subpath and called as a function:

```typescript
// Wrong
import { BetterAuthReactAdapter } from '@neon/auth';

// Correct
import { BetterAuthReactAdapter } from '@neon/auth/react/adapters';
const client = createAuthClient(url, { adapter: BetterAuthReactAdapter() });
```

## Auth UI components are unstyled

Better Auth UI's components are compiled by your app's Tailwind build. If they render without styles, check that your global CSS imports the shadcn/ui theme that `npx shadcn@latest init` adds (`tw-animate-css` and `shadcn/tailwind.css`, plus the theme variables), and that Tailwind scans the folder the components were copied to.

See the [UI Components reference](https://neon.com/docs/auth/reference/ui-components) for complete setup instructions.

## Missing "use client" directive

In Next.js, any component that uses `useSession()` or other React hooks must include `"use client"` at the top of the file. Without it, Next.js treats the file as a server component where React hooks are not available.

## Wrong createAuthClient signature

The `createAuthClient` function has different signatures depending on the import path:

```typescript
// React SPA — import from @neon/auth
import { createAuthClient } from '@neon/auth';
createAuthClient(url);
createAuthClient(url, { adapter: BetterAuthReactAdapter() });

// Next.js — import from @neon/auth/next (no arguments, uses proxy)
import { createAuthClient } from '@neon/auth/next';
createAuthClient();
```

See the [Next.js quick start](https://neon.com/docs/auth/quick-start/nextjs-api-only) and the [React quick start](https://neon.com/docs/auth/quick-start/react) for complete client setup examples.

## OAuth errors (`redirect_uri_mismatch`, blocked consent, redirect loops)

**`redirect_uri_mismatch` from Google (or another provider)**

The authorized redirect URI in the provider's dashboard must match Managed Better Auth's callback route exactly: **`{NEON_AUTH_BASE_URL}/callback/{provider}`** (for example `.../callback/google`). See [Production setup](https://neon.com/docs/auth/guides/setup-oauth#production-setup).

Common mistakes:

- Registering only your marketing site or only the `callbackURL` from `signIn.social()`, instead of **`{NEON_AUTH_BASE_URL}/callback/{provider}`**.
- Using a branch's **`NEON_AUTH_BASE_URL`** in your app while Google still lists redirect URIs for a different branch's Auth base URL.

**OAuth succeeds but the user never reaches your app**

Managed Better Auth only redirects to [trusted domains](https://neon.com/docs/auth/guides/configure-domains). Add every origin you use in **`callbackURL`** (including `https://www.example.com` separately if you use www).

**Google consent screen shows an unexpected hostname**

That hostname comes from the OAuth redirect URI (your app vs Managed Better Auth). See [Google OAuth branding](https://neon.com/docs/auth/guides/setup-oauth#google-oauth-branding).

**Google says the app is in Testing / users outside test accounts cannot sign in**

Add testers in Google Cloud Console or publish the OAuth consent screen for production use. See [Google OAuth branding](https://neon.com/docs/auth/guides/setup-oauth#google-oauth-branding).

--- [Document source](https://neon.com/docs/cli.md) ---

> Summary: Neon CLI (neon) is the terminal tool for managing Neon projects, branches, databases, roles, connection strings, functions, buckets, and the Data API without using the web console. This page indexes every command with its subcommands and documents the global options, including --output (json, yaml, table), --api-key (NEON_API_KEY), and --context-file. Built for terminal workflows, CI/CD automation, scripts, and AI agents.

# Neon CLI

The Neon command-line interface: every command, with options and examples

Last updated: 2026-11-02

One CLI for every Neon surface: manage Postgres, Functions, Storage, the Data API, and Managed Better Auth from the terminal, with branch-scoped workflows built in.

```bash filename="Install"
npm i -g neon
```

## Get started

- [Install and connect](https://neon.com/docs/cli/install): Install the Neon CLI, authenticate, and connect your first Neon project in minutes.
- [Quickstart](https://neon.com/docs/cli/quickstart): Create a project, manage branches, and run your first Neon CLI commands.

## Agent mode

Use Neon CLI with Claude Code, Cursor, Codex, and other AI development tools.

**Note:** Every command supports `--output json` for machine-readable results, and setting the `NEON_API_KEY` environment variable authenticates non-interactively. Agents bind a directory to a project with [`neon link`](https://neon.com/docs/cli/link)'s non-interactive flags, the same ones used for CI and scripts.

## Commands reference

Browse every Neon CLI command, organized by category. The CLI is invoked as `neon`. `neonctl` is an alias for `neon`, so any command works with either name.

### api

Call any Neon API route directly (authenticated passthrough).

Usage: `neon api [path] [options]`

### api-keys (alias: `api-key`)

Manage API keys.

| Subcommand                  | Description                                                            |
| --------------------------- | ---------------------------------------------------------------------- |
| `neon api-keys create`      | Create an API key. The key is shown once and cannot be retrieved again |
| `neon api-keys list`        | List API keys for your account, or for an organization                 |
| `neon api-keys revoke <id>` | Revoke an API key. Anything using it stops working immediately         |

### ask

Ask a question about Neon.

Usage: `neon ask [options]`

### bootstrap

Scaffold a new project from a Neon starter template, then install agent tooling and link a Neon project.

Usage: `neon bootstrap [directory] [options]`

### branches (alias: `branch`)

Manage branches.

| Subcommand                                                                    | Description                                                                                                  |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `neon branches add-compute <id\|name>`                                        | Add a compute to a branch                                                                                    |
| `neon branches create`                                                        | Create a branch                                                                                              |
| `neon branches delete <id\|name>`                                             | Delete a branch                                                                                              |
| `neon branches get <id\|name>`                                                | Get a branch                                                                                                 |
| `neon branches list`                                                          | List branches                                                                                                |
| `neon branches rename <id\|name> <new-name>`                                  | Rename a branch                                                                                              |
| `neon branches reset <id\|name>`                                              | Reset a branch                                                                                               |
| `neon branches restore <target-id\|name> <source>[@(timestamp\|lsn)>`         | Restores a branch to a specific point in time \<source> can be: ^self, ^parent, or \<source-branch-id\|name> |
| `neon branches schema-diff [base-branch] [compare-source[@(timestamp\|lsn)]]` | Compare the latest schemas of any two branches, or compare a branch to its own or another branch's history.  |
| `neon branches set-default <id\|name>`                                        | Set a branch as default                                                                                      |
| `neon branches set-expiration <id\|name>`                                     | Set an expiration date for the branch                                                                        |

### buckets (alias: `bucket`)

Manage branch object-storage buckets and their objects.

| Subcommand                            | Description                                                                                                                     |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `neon buckets create <name>`          | Create a bucket on a branch                                                                                                     |
| `neon buckets delete <name>`          | Delete a bucket from a branch                                                                                                   |
| `neon buckets list`                   | List the buckets on a branch                                                                                                    |
| `neon buckets object delete <target>` | Delete an object, or every object under a prefix                                                                                |
| `neon buckets object get <target>`    | Download an object from a bucket to a local file                                                                                |
| `neon buckets object list <target>`   | List objects in a bucket. By default folders are collapsed (like "aws s3 ls"); pass --recursive for a flat listing of every key |
| `neon buckets object put <target>`    | Upload a local file to a bucket as an object                                                                                    |

### checkout

Pin a branch in the local context (.neon) so subsequent commands target it.

Usage: `neon checkout [id|name] [options]`

### claim (alias: `claimable`)

Create and claim temporary Neon projects.

| Subcommand                       | Description                                                                                          |
| -------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `neon claim accept [project-id]` | Create a claim code and open the URL where a human signs in and takes the project                    |
| `neon claim create`              | Create a temporary Neon project without an account                                                   |
| `neon claim delete [project-id]` | Permanently delete an unclaimed project, or drop a local record that can no longer reach the service |
| `neon claim list`                | List claimable projects saved on this machine                                                        |
| `neon claim status [project-id]` | Show a claimable project's lifecycle and claim status                                                |

### config

Manage a branch with a neon.ts policy.

| Subcommand                        | Description                                                                                                                                                               |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `neon config add ai-gateway`      | Enable the AI Gateway (aiGateway: true)                                                                                                                                   |
| `neon config add auth`            | Enable Neon Auth (auth: true)                                                                                                                                             |
| `neon config add bucket <name>`   | Declare an Object Storage bucket                                                                                                                                          |
| `neon config add data-api`        | Enable the Data API (dataApi: true) and Neon Auth, which the default provider requires. For an external identity provider, set dataApi.authProvider to "external" instead |
| `neon config add function <slug>` | Declare a Neon Function and create its handler file                                                                                                                       |
| `neon config add realtime`        | Enable Realtime (preview\.realtime: true)                                                                                                                                 |
| `neon config apply`               | Apply a neon.ts policy to the branch                                                                                                                                      |
| `neon config init`                | Scaffold a neon.ts policy and install the Neon config packages                                                                                                            |
| `neon config plan`                | Show what `config apply` would change (dry run)                                                                                                                           |
| `neon config status`              | Show the branch's live Neon state                                                                                                                                         |

### connection-string (alias: `cs`)

Get connection string.

Usage: `neon connection-string [branch] [options]`

### credentials (alias: `credential`)

Manage branch credentials.

| Subcommand                          | Description                                                         |
| ----------------------------------- | ------------------------------------------------------------------- |
| `neon credentials create`           | Issue a scoped credential on the branch                             |
| `neon credentials list`             | List credentials on the branch                                      |
| `neon credentials reveal <tokenId>` | Show a credential's api\_token and s3\_secret\_access\_key          |
| `neon credentials revoke <tokenId>` | Revoke a credential                                                 |
| `neon credentials rotate <tokenId>` | Replace a credential's secrets in place. The token id is unchanged. |

### data-api

Manage the Neon Data API for a database.

| Subcommand                     | Description                                                             |
| ------------------------------ | ----------------------------------------------------------------------- |
| `neon data-api create`         | Provision the Neon Data API for a database                              |
| `neon data-api delete`         | Tear down the Neon Data API for a database                              |
| `neon data-api get`            | Show the Neon Data API status and settings                              |
| `neon data-api refresh-schema` | Refresh the Data API schema cache without changing settings             |
| `neon data-api update`         | Update Neon Data API settings (merges with current settings by default) |

### databases (alias: `database`, `db`)

Manage databases.

| Subcommand                         | Description       |
| ---------------------------------- | ----------------- |
| `neon databases create`            | Create a database |
| `neon databases delete <database>` | Delete a database |
| `neon databases list`              | List databases    |

### deploy

Apply a neon.ts policy to a branch (alias for `config apply`).

Usage: `neon deploy [options]`

### dev

Run Neon Functions locally with a dev server.

Usage: `neon dev [options]`

### diff

Show a git-style schema diff between the current branch and another branch.

Usage: `neon diff [compare-branch] [options]`

### docs

Search neon.com docs, guides, and more.

| Subcommand                 | Description                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| `neon docs search <query>` | Search neon.com: docs, API reference, PostgreSQL tutorial, guides, FAQs, changelog, and blog |

### env

Manage a branch's Neon env variables locally.

| Subcommand      | Description                                                |
| --------------- | ---------------------------------------------------------- |
| `neon env pull` | Write the branch's Neon env variables to a local .env file |

### feedback

Send feedback to Neon.

Usage: `neon feedback [options]`

### functions (alias: `function`)

Manage Neon Functions.

| Subcommand                                 | Description                                                |
| ------------------------------------------ | ---------------------------------------------------------- |
| `neon functions delete <slug>`             | Delete a function on the branch                            |
| `neon functions deploy <slug>`             | Deploy a function from a local directory                   |
| `neon functions domains delete <domain>`   | Delete a custom domain from the branch                     |
| `neon functions domains list`              | List custom domains on the branch                          |
| `neon functions domains register <domain>` | Point a domain you already own at a function on the branch |
| `neon functions get <slug>`                | Show a function's details                                  |
| `neon functions list`                      | List functions on the branch                               |
| `neon functions new [template]`            | Create a function from a Function Registry template        |
| `neon functions templates list`            | List function templates                                    |

### git

Sync the checked-out Neon branch to your git branch (Preview).

| Subcommand           | Description                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------ |
| `neon git cleanup`   | Prune git → Neon mappings whose local git branch is gone; optionally delete the orphaned Neon branches |
| `neon git install`   | Install a git post-checkout hook that syncs the Neon branch on `git checkout`                          |
| `neon git status`    | Show the git context, hook state, and current git → Neon mapping                                       |
| `neon git sync`      | Check out the Neon branch mapped to the current git branch (run by the hook)                           |
| `neon git uninstall` | Remove the git post-checkout hook installed by `git install`                                           |

### init

Set up coding agents and this directory for Neon. -y is Recommended. -y with Custom flags applies those answers without prompts.

Usage: `neon init [options]`

### inspect (alias: `inspection`)

Inspect a branch's Postgres health and configuration.

| Subcommand                             | Description                                                                                                                                    |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `neon inspect db bloat`                | Estimated table/index bloat (statistical estimate, no extension needed)                                                                        |
| `neon inspect db calls`                | Most frequently called queries (needs pg\_stat\_statements)                                                                                    |
| `neon inspect db index-sizes`          | Size of each index, largest first (pg\_relation\_size)                                                                                         |
| `neon inspect db lfc-hit-rate`         | Local File Cache hit rate (compute-wide, needs neon extension)                                                                                 |
| `neon inspect db locks`                | Locks held with the acquiring query and its age (pg\_locks + pg\_stat\_activity)                                                               |
| `neon inspect db long-running-queries` | Queries running longer than 5 minutes (pg\_stat\_activity)                                                                                     |
| `neon inspect db outliers`             | Queries taking the most cumulative execution time (needs pg\_stat\_statements)                                                                 |
| `neon inspect db replication-slots`    | Replication slots (compute-wide): kind, status, client, restart/confirmed-flush LSNs, and lag (pg\_replication\_slots + pg\_stat\_replication) |
| `neon inspect db seq-scans`            | Number of sequential scans recorded against each table (pg\_stat\_user\_tables)                                                                |
| `neon inspect db stalled-queries`      | Active queries running longer than 30 seconds with parallel workers, waits, and blockers, oldest group first (compute-wide)                    |
| `neon inspect db subscriptions`        | Per-table logical replication progress on this subscriber (pg\_subscription\_rel)                                                              |
| `neon inspect db table-sizes`          | Size of each table (including TOAST), largest first (pg\_table\_size)                                                                          |
| `neon inspect db unused-indexes`       | Non-unique indexes with few scans — candidates for removal (pg\_stat\_user\_indexes)                                                           |
| `neon inspect db vacuum-stats`         | Autovacuum status per table: last (auto)vacuum, dead tuples, threshold                                                                         |
| `neon inspect db working-set`          | Estimated working set vs LFC size (compute-wide, needs neon extension)                                                                         |

### ip-allow

Manage IP Allow.

| Subcommand                      | Description                               |
| ------------------------------- | ----------------------------------------- |
| `neon ip-allow add [ips...]`    | Add IP addresses to the IP allowlist      |
| `neon ip-allow list`            | List the IP allowlist                     |
| `neon ip-allow remove [ips...]` | Remove IP addresses from the IP allowlist |
| `neon ip-allow reset [ips...]`  | Reset the IP allowlist                    |

### link

Link the current directory to a Neon project.

Usage: `neon link [options]`

### login (alias: `auth`)

Sign in with a browser. See --help for API keys and profiles.

Usage: `neon login [options]`

### logs

Query branch logs with structured filters, LogQL, or the Loki API.

| Subcommand                       | Description                                                    |
| -------------------------------- | -------------------------------------------------------------- |
| `neon logs field-values <field>` | List the distinct values observed for a log field              |
| `neon logs fields`               | List the log fields whose values can be discovered on a branch |
| `neon logs loki [query]`         | Call the branch's Loki read API and return its JSON response   |
| `neon logs query`                | Query log records with structured filters or LogQL             |

### mcp

Install the Neon MCP server into coding agents.

Usage: `neon mcp [options]`

### me

Show current user.

Usage: `neon me [options]`

### neon-auth

Manage Neon Auth.

| Subcommand                                                    | Description                                                                                                                       |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `neon neon-auth config email-password get`                    | Get email and password config                                                                                                     |
| `neon neon-auth config email-password update`                 | Update email and password config                                                                                                  |
| `neon neon-auth config email-provider get`                    | Get email provider config                                                                                                         |
| `neon neon-auth config email-provider test`                   | Send a test message through the saved custom SMTP provider                                                                        |
| `neon neon-auth config email-provider update`                 | Update email provider config                                                                                                      |
| `neon neon-auth config oauth-server get`                      | Get OAuth server config                                                                                                           |
| `neon neon-auth config oauth-server resource add <url...>`    | Add protected resources (reads the stored list and writes back the full list; concurrent changes by others can be overwritten)    |
| `neon neon-auth config oauth-server resource list`            | List protected resources                                                                                                          |
| `neon neon-auth config oauth-server resource remove <url...>` | Remove protected resources (reads the stored list and writes back the full list; concurrent changes by others can be overwritten) |
| `neon neon-auth config oauth-server update`                   | Update OAuth server config                                                                                                        |
| `neon neon-auth config organization get`                      | Get organization plugin config                                                                                                    |
| `neon neon-auth config organization update`                   | Update organization plugin config                                                                                                 |
| `neon neon-auth config webhook get`                           | Get webhook config                                                                                                                |
| `neon neon-auth config webhook update`                        | Update webhook config                                                                                                             |
| `neon neon-auth disable`                                      | Disable Neon Auth on a branch                                                                                                     |
| `neon neon-auth domain add <domain>`                          | Add a trusted domain                                                                                                              |
| `neon neon-auth domain allow-localhost disable`               | Restrict localhost connections                                                                                                    |
| `neon neon-auth domain allow-localhost enable`                | Allow localhost connections                                                                                                       |
| `neon neon-auth domain allow-localhost get`                   | Get localhost connection setting                                                                                                  |
| `neon neon-auth domain delete <domain>`                       | Delete a trusted domain                                                                                                           |
| `neon neon-auth domain list`                                  | List trusted domains                                                                                                              |
| `neon neon-auth enable`                                       | Enable Neon Auth on a branch                                                                                                      |
| `neon neon-auth oauth-client create`                          | Create an OAuth client                                                                                                            |
| `neon neon-auth oauth-client delete <client-id>`              | Delete an OAuth client                                                                                                            |
| `neon neon-auth oauth-client get <client-id>`                 | Get an OAuth client                                                                                                               |
| `neon neon-auth oauth-client list`                            | List OAuth clients                                                                                                                |
| `neon neon-auth oauth-client rotate-secret <client-id>`       | Rotate the secret of a confidential client; the old secret stops working immediately                                              |
| `neon neon-auth oauth-client update <client-id>`              | Update an OAuth client (the type cannot be changed)                                                                               |
| `neon neon-auth oauth-provider add`                           | Add an OAuth provider                                                                                                             |
| `neon neon-auth oauth-provider delete`                        | Delete an OAuth provider                                                                                                          |
| `neon neon-auth oauth-provider list`                          | List OAuth providers                                                                                                              |
| `neon neon-auth oauth-provider update`                        | Update an OAuth provider                                                                                                          |
| `neon neon-auth plugins get <plugin-name>`                    | Get a specific plugin configuration                                                                                               |
| `neon neon-auth plugins list`                                 | List all plugin configurations                                                                                                    |
| `neon neon-auth status`                                       | Get Neon Auth status for a branch                                                                                                 |
| `neon neon-auth user create`                                  | Create an auth user                                                                                                               |
| `neon neon-auth user delete <user-id>`                        | Delete an auth user                                                                                                               |
| `neon neon-auth user set-role <user-id>`                      | Set roles for an auth user                                                                                                        |

### open

Open the linked project in the Neon Console.

Usage: `neon open [options]`

### operations (alias: `operation`)

Manage operations.

| Subcommand                 | Description      |
| -------------------------- | ---------------- |
| `neon operations get <id>` | Get an operation |
| `neon operations list`     | List operations  |

### orgs (alias: `org`)

Manage organizations.

| Subcommand                             | Description                                                                                        |
| -------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `neon orgs get [id]`                   | Show an organization                                                                               |
| `neon orgs invitations create`         | Invite people by email. Each one is emailed, and anyone with a Neon account joins immediately      |
| `neon orgs invitations list`           | List invitations                                                                                   |
| `neon orgs list`                       | List organizations                                                                                 |
| `neon orgs members get <member-id>`    | Show a member                                                                                      |
| `neon orgs members list`               | List members and their organization role                                                           |
| `neon orgs members remove <member-id>` | Remove a member from the organization. Admin only                                                  |
| `neon orgs members update <member-id>` | Change a member's organization role. Admin only                                                    |
| `neon orgs spending-limit delete`      | Remove the monthly spending limit. Admin only                                                      |
| `neon orgs spending-limit get`         | Show the monthly spending limit                                                                    |
| `neon orgs spending-limit set <usd>`   | Set the monthly spending limit. Neon emails at 80% and 100% and keeps computes running. Admin only |

### plugins (alias: `plugin`)

Install the Neon plugin into coding agents.

Usage: `neon plugins [options]`

### postgres (alias: `pg`, `lakebase`)

Manage Postgres computes, databases, and roles, and connect with psql or a connection string.

| Subcommand                                  | Description                                                                                                                             |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `neon postgres computes delete <id>`        | Delete a compute                                                                                                                        |
| `neon postgres computes get <id>`           | Get a compute                                                                                                                           |
| `neon postgres computes list`               | List computes. Lists the branch's computes when --branch is passed or .neon pins one, otherwise every compute in the project            |
| `neon postgres computes restart <id>`       | Restart a compute                                                                                                                       |
| `neon postgres computes start <id>`         | Start a compute                                                                                                                         |
| `neon postgres computes suspend <id>`       | Suspend a compute                                                                                                                       |
| `neon postgres computes update <id>`        | Update a compute's size, scale-to-zero timeout, name, or connection access                                                              |
| `neon postgres connection-string [branch]`  | Get connection string                                                                                                                   |
| `neon postgres databases create`            | Create a database                                                                                                                       |
| `neon postgres databases delete <database>` | Delete a database                                                                                                                       |
| `neon postgres databases list`              | List databases                                                                                                                          |
| `neon postgres psql [branch]`               | Connect to a database via psql                                                                                                          |
| `neon postgres roles create`                | Create a role. By default it joins neon\_superuser (admin on every database); pass --access read\_only or read\_write for a scoped role |
| `neon postgres roles delete <role>`         | Delete a role                                                                                                                           |
| `neon postgres roles get <role>`            | Get a role                                                                                                                              |
| `neon postgres roles list`                  | List roles                                                                                                                              |
| `neon postgres roles reset-password <role>` | Reset a role's password and print the new one                                                                                           |

### profile (alias: `profiles`)

Manage named sets of Neon credentials.

| Subcommand                       | Description                                                                           |
| -------------------------------- | ------------------------------------------------------------------------------------- |
| `neon profile create <name>`     | Create a profile. It holds either a browser sign-in or an API key, never both         |
| `neon profile list`              | List profiles, the account each holds, and where its credentials live                 |
| `neon profile remove <name>`     | Revoke a profile's credential where possible, and remove it                           |
| `neon profile rotate-key <name>` | Mint a fresh API key for a profile, at the same scope, and revoke the one it replaces |

### projects (alias: `project`)

Manage projects.

| Subcommand                   | Description                                                 |
| ---------------------------- | ----------------------------------------------------------- |
| `neon projects create`       | Create a project                                            |
| `neon projects delete <id>`  | Delete a project                                            |
| `neon projects get <id>`     | Get a project                                               |
| `neon projects list`         | List projects                                               |
| `neon projects recover <id>` | Recovers a deleted project during the deletion grace period |
| `neon projects update <id>`  | Update a project                                            |

### psql

Connect to a database via psql.

Usage: `neon psql [branch] [options]`

### realtime

Manage Neon Realtime for a branch.

| Subcommand                        | Description                                      |
| --------------------------------- | ------------------------------------------------ |
| `neon realtime disable`           | Disable Realtime on a branch                     |
| `neon realtime enable`            | Enable Realtime on a branch                      |
| `neon realtime rotate-secret`     | Replace a branch's Realtime shared secret        |
| `neon realtime subscribe <query>` | Subscribe to a live SQL query with Neon Realtime |

### roles (alias: `role`)

Manage roles.

| Subcommand                         | Description                                                                                                                             |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `neon roles create`                | Create a role. By default it joins neon\_superuser (admin on every database); pass --access read\_only or read\_write for a scoped role |
| `neon roles delete <role>`         | Delete a role                                                                                                                           |
| `neon roles get <role>`            | Get a role                                                                                                                              |
| `neon roles list`                  | List roles                                                                                                                              |
| `neon roles reset-password <role>` | Reset a role's password and print the new one                                                                                           |

### set-context

Deprecated: use `neon link`. Set the .neon context (raw write).

Usage: `neon set-context [options]`

### skills (alias: `skill`)

Install Neon agent skills into coding agents.

| Subcommand           | Description                                            |
| -------------------- | ------------------------------------------------------ |
| `neon skills status` | Check whether installed Neon skills match their source |
| `neon skills update` | Update installed skills to the latest versions         |

### snapshots (alias: `snapshot`)

Manage snapshots.

| Subcommand                         | Description                                                         |
| ---------------------------------- | ------------------------------------------------------------------- |
| `neon snapshots create`            | Create a snapshot from a branch                                     |
| `neon snapshots delete <id>`       | Delete a snapshot by id or name                                     |
| `neon snapshots finalize <branch>` | Finalize a previewed snapshot restore (swap the restored branch in) |
| `neon snapshots get <id>`          | Get a snapshot by id or name                                        |
| `neon snapshots list`              | List snapshots in the project                                       |
| `neon snapshots restore <id>`      | Restore a snapshot into a branch                                    |
| `neon snapshots schedule get`      | Get a branch's automatic snapshot schedule                          |
| `neon snapshots schedule set`      | Set a branch's automatic snapshot schedule                          |
| `neon snapshots update <id>`       | Update a snapshot's name or expiration                              |

### status

Show the branch's live Neon state (alias of `config status`).

Usage: `neon status [options]`

### triggers (alias: `trigger`)

Manage function triggers.

| Subcommand                   | Description                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------- |
| `neon triggers create`       | Create a trigger that invokes a function on a cron schedule or when an object is created |
| `neon triggers delete <id>`  | Delete a trigger                                                                         |
| `neon triggers disable <id>` | Disable a trigger without deleting it                                                    |
| `neon triggers enable <id>`  | Enable a trigger                                                                         |
| `neon triggers get <id>`     | Show a trigger                                                                           |
| `neon triggers list`         | List triggers on the branch                                                              |
| `neon triggers update <id>`  | Update a trigger                                                                         |

### vpc

Manage VPC endpoints and project VPC restrictions.

| Subcommand                       | Description                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------- |
| `neon vpc endpoint assign <id>`  | Add or update a VPC endpoint for this organization. Note: Azure regions are not yet supported. |
| `neon vpc endpoint list`         | List configured VPC endpoints for this organization.                                           |
| `neon vpc endpoint remove <id>`  | Remove a VPC endpoint from this organization.                                                  |
| `neon vpc endpoint status <id>`  | Get the status of a VPC endpoint for this organization.                                        |
| `neon vpc project list`          | List VPC endpoint restrictions for this project.                                               |
| `neon vpc project remove <id>`   | Remove a VPC endpoint restriction from this project.                                           |
| `neon vpc project restrict <id>` | Configure or update a VPC endpoint restriction for this project.                               |

## Global options

Global options are optional and work with any Neon CLI command.

| Option            | Description                                                                         | Type    | Default                                                         | Required |
| ----------------- | ----------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------- | :------: |
| `--analytics`     | Manage analytics. Example: --no-analytics, --analytics false                        | boolean | `true`                                                          |    No    |
| `--api-key`       | Neon API key, authenticates without `neon login`                                    | string  | `""`                                                            |    No    |
| `--color`         | Colorize the output. Example: --no-color, --color false                             | boolean | `true`                                                          |    No    |
| `--config-dir`    | Path to config directory                                                            | string  | \~/.config/neon (or $XDG\_CONFIG\_HOME/neon)                    |    No    |
| `--context-file`  | Context file with default org, project, and branch IDs, created by `neon link`      | string  | nearest .neon file, searching upward from the current directory |    No    |
| `--help`, `-h`    | Show help for a command or subcommand                                               | boolean | —                                                               |    No    |
| `--output`, `-o`  | Set output format Possible values: `json`, `yaml`, `table`                          | string  | `table`                                                         |    No    |
| `--profile`       | Named credentials to use, from profiles.json (default: NEON\_PROFILE, else DEFAULT) | string  | —                                                               |    No    |
| `--version`, `-v` | Show version number                                                                 | boolean | —                                                               |    No    |

More about global options:

- **Output:** table output may omit fields. Use `--output json` or `--output yaml` to see all data.
- **Authentication:** the CLI checks credentials in this order: the `--api-key` option, the `NEON_API_KEY` environment variable (`export NEON_API_KEY=<neon_api_key>`), the `credentials.json` file that `neon login` creates in the config directory (override its location with `--config-dir`), then interactive web authentication. To get a key, see [Create an API key](https://neon.com/docs/manage/api-keys#creating-api-keys).
- **Context file:** sets a default organization, project, or branch so you don't repeat IDs in every command. Create one with [`neon link`](https://neon.com/docs/cli/link) (preferred) or [`set-context`](https://neon.com/docs/cli/set-context).
- **Analytics:** Neon collects anonymous data about which commands and options are used, plus context such as the CLI version, whether it ran in CI or a terminal, and which coding agent ran it, never user-defined data such as project IDs or command payloads. Each installation gets a random ID, stored as `anonymous_id` in the config directory, and once you sign in, your events are linked to your account. The ID isn't created in CI or when you pass `--no-analytics`. If the CLI crashes on an internal bug, it also sends an error report with the error type and a sanitized stack trace, without your arguments, environment variables, or file contents. Opt out of both with `--no-analytics`, which also asks the docs search service not to record your `neon docs search` and `neon ask` queries.
- **Help:** `--help` works at every level: `neon --help`, `neon branches --help`, `neon branches create --help`.

## GitHub repository

The Neon CLI is open source. See the [neondatabase/neon-pkgs](https://github.com/neondatabase/neon-pkgs/tree/main/packages/cli) repository.

--- [Document source](https://neon.com/docs/cli/api-keys.md) ---

> Summary: The `neon api-keys` CLI command manages API keys for your account, an organization, or a single project. Use it to create a key for scripts and CI, list existing keys and when they were last used, and revoke a key you no longer trust.

# Neon CLI command: api-keys

Create, list, and revoke Neon API keys

Last updated: 2026-10-09

The `api-keys` command creates, lists, and revokes the API keys that authenticate requests to the Neon API. Keys belong to your account unless you pass `--org-id` or `--project-id`.

A key is shown once, at creation. There is no way to retrieve it later.

For key types, revocation permissions, and rotation, see [Manage API keys](https://neon.com/docs/manage/api-keys).

Subcommands: [create](https://neon.com/docs/cli/api-keys#create), [list](https://neon.com/docs/cli/api-keys#list), [revoke](https://neon.com/docs/cli/api-keys#revoke)

## neon api-keys list

Lists key metadata, never the keys themselves.

```bash
neon api-keys list [options]
```

| Option     | Description                                            | Type   | Default | Required |
| ---------- | ------------------------------------------------------ | ------ | ------- | :------: |
| `--org-id` | List the organization's keys instead of your account's | string | —       |    No    |

List your account keys:

```bash
neon api-keys list
```

```text filename="Output"
Account API keys
ID       Name       Created At            Last Used At          Last Used From Addr
3225782  ci-deploy  2026-07-29T00:50:26Z  2026-07-29T18:06:55Z  192.0.2.10
```

Organization keys are invisible to your account, so listing them needs `--org-id`:

```bash
neon api-keys list --org-id org-example-12345678
```

This covers both scopes, since a project-scoped key is owned by the project's organization. The `Project` column tells them apart:

```text filename="Output"
API keys in org-example-12345678
ID       Name         Project                Created At            Last Used At          Last Used From Addr
3243240  preview-bot  green-breeze-12345678  2026-08-04T18:51:36Z  2026-08-05T18:51:36Z  192.0.2.10
3177950  org-key      (all projects)         2026-07-08T01:28:49Z  2026-07-08T01:31:20Z  192.0.2.10
```

`(all projects)` is a table label only. In JSON and YAML the field is `project_id`, and it is `null` for an organization-wide key:

```bash
neon api-keys list --org-id org-example-12345678 -o json
```

```json
[
  { "id": 3243240, "name": "preview-bot", "project_id": "green-breeze-12345678" },
  { "id": 3177950, "name": "org-key", "project_id": null }
]
```

## neon api-keys create

Creates a key and prints it once. `--name` is required.

By default the key reaches everything your account can, in every organization. Two mutually exclusive flags change that:

- `--project-id` limits the key to one project. Use this for anything deployed, so a leaked key cannot reach your other projects.
- `--org-id` transfers ownership to an organization. This is not a restriction: the key reaches every project in that organization, including ones created later.

Both organization forms need organization admin permissions. Each form prints a notice describing what the key can reach.

```bash
neon api-keys create [options]
```

| Option         | Description                                                                                    | Type   | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--name`       | A name to identify the key later                                                               | string | —       |    Yes   |
| `--org-id`     | Create a key for this organization instead of your account                                     | string | —       |    No    |
| `--project-id` | Create a key that can access only this project. Its organization is looked up from the project | string | —       |    No    |

Create an account key:

```bash
neon api-keys create --name ci-deploy
```

```text filename="Output"
API key
ID    3225782
Name  ci-deploy

napi_examplekey1234567890abcdefghijklmnopqrstuvwxyz
WARNING: Store this key now: it is not shown again.
WARNING: This key reaches everything your account can, in every organization. Pass --org-id or --project-id to narrow it.
```

Create a key owned by an organization:

```bash
neon api-keys create --name org-key --org-id org-example-12345678
```

```text filename="Output"
API key
ID    3177950
Name  org-key

napi_examplekey1234567890abcdefghijklmnopqrstuvwxyz
WARNING: Store this key now: it is not shown again.
WARNING: This key reaches every project in org-example-12345678, including ones created later. Pass --project-id instead to restrict it to one.
```

Create a key limited to one project. The output adds a `Project` column:

```bash
neon api-keys create --name preview-bot --project-id green-breeze-12345678
```

```text filename="Output"
API key
ID       3243240
Name     preview-bot
Project  green-breeze-12345678

napi_examplekey1234567890abcdefghijklmnopqrstuvwxyz
WARNING: Store this key now: it is not shown again.
Limited to green-breeze-12345678: it cannot create projects, mint API keys, or read any other project. It can still change and delete everything inside that project.
```

**Important:** A project-scoped key is owned by the project's organization, so it needs `--org-id` to list or revoke.

The key is the last line of stdout, and the notices go to stderr, so you can capture it directly:

```bash
echo "NEON_API_KEY=$(neon api-keys create --name local-dev -o json | jq -r .key)" >> .env
```

## neon api-keys revoke

Revokes a key immediately and permanently. Anything using it starts failing, so confirm the ID with `api-keys list` first.

Takes the numeric key ID, not the name. Organization and project-scoped keys need organization admin permissions. See [who can revoke keys](https://neon.com/docs/manage/api-keys#who-can-revoke-keys).

```bash
neon api-keys revoke <id> [options]
```

| Option     | Description                                          | Type   | Default | Required |
| ---------- | ---------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Revoke an organization key instead of an account key | string | —       |    No    |

Revoke an account key:

```bash
neon api-keys revoke 3225782
```

```text filename="Output"
API key
ID            3225782
Name          ci-deploy
Revoked       true
Last Used At  2026-07-29T18:06:55Z
```

`Last Used At` is empty for a key that was never used.

Revoke an organization or project-scoped key:

```bash
neon api-keys revoke 3243240 --org-id org-example-12345678
```

Without `--org-id`, the same command fails:

```text filename="Output"
ERROR: No account API key with id 3243240. If it belongs to an organization, pass --org-id. Organization keys are not visible to your account.
```

--- [Document source](https://neon.com/docs/cli/api.md) ---

> Summary: The Neon CLI `api` command sends an authenticated request to any Neon API route and prints the response. Pass a path like `/projects`, set the method with `--method`, build a body from `--field` or `--data`, and add query parameters and headers. Run `neon api --list` to browse every endpoint.

# Neon CLI command: api

Call any Neon API route directly as an authenticated passthrough

Last updated: 2026-09-18

The `api` command sends an authenticated request to any [Neon API](https://neon.com/docs/reference/api) route and prints the response. Pass an API path as the first argument. The method defaults to `GET`, or `POST` when you supply a body.

By default the request uses your [`neon login`](https://neon.com/docs/cli/login) credentials. To use a specific key, pass `--api-key` or set `NEON_API_KEY`. The [key's permissions](https://neon.com/docs/manage/api-keys#types-of-api-keys) determine what the request can do.

**Note:** `api` is a raw passthrough: it does not read your [context file](https://neon.com/docs/cli/link) or auto-fill parameters. Pass what each route needs explicitly. For example, `neon api /projects` returns `ERROR: org_id is required` unless you add `-Q org_id=<org_id>` or authenticate with an organization API key. Get your organization ID from [`neon orgs list`](https://neon.com/docs/cli/orgs).

## Usage

```bash
neon api <path> [options]
```

## Options

| Option              | Description                                                                                                                                | Type    | Default | Required |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | :------: |
| `--data`, `-d`      | Raw request body: a JSON string, @file, or - for stdin. Overrides --field.                                                                 | string  | —       |    No    |
| `--describe`        | Print path, query, and body fields from the OpenAPI spec without calling the API. Body names are dotted for -F.                            | boolean | `false` |    No    |
| `--field`, `-F`     | Body field key=value (repeatable). Dot-notation nests objects (e.g. -F branch.name=dev); values are typed (numbers, booleans, null, JSON). | array   | —       |    No    |
| `--header`, `-H`    | Extra request header key:value (repeatable).                                                                                               | array   | —       |    No    |
| `--include`, `-i`   | Print the response status and headers before the body.                                                                                     | boolean | `false` |    No    |
| `--list`            | List available API endpoints from the OpenAPI spec.                                                                                        | boolean | `false` |    No    |
| `--method`, `-X`    | HTTP method (GET, POST, PUT, PATCH, DELETE). Defaults to GET, or POST when a body is provided.                                             | string  | —       |    No    |
| `--query`, `-Q`     | Query parameter key=value (repeatable).                                                                                                    | array   | —       |    No    |
| `--raw-field`, `-f` | Body field key=value with the value kept as a raw string.                                                                                  | array   | —       |    No    |
| `--refresh`         | Refresh the cached OpenAPI spec (used with --list and --describe).                                                                         | boolean | `false` |    No    |

## Examples

### GET request

Pass required parameters with `--query` (`-Q`); add `--include` (`-i`) to print the status and headers before the body:

```bash
neon api /projects -Q org_id=org-cool-darkness-12345678 -i
```

The response is the route's raw JSON. For the fields each route returns, see the [Neon API Reference](https://neon.com/docs/reference/api).

### Request body

Set body fields with `--field` (`-F`) as `key=value`. Values are typed automatically (numbers, booleans, `null`, and JSON), and dot-notation nests objects. A body switches the default method to `POST`:

```bash
neon api /projects/{project_id}/branches -F branch.name=dev
```

This sends `{ "branch": { "name": "dev" } }`. Use `--raw-field` (`-f`) to keep a value as a literal string. For a full JSON body, use `--data` (`-d`) with a string, `@file`, or `-` (stdin).

### Create a project

`POST /projects` takes a `project` object. To create it under an organization, set `project.org_id` in the body (unlike `GET /projects`, which takes `org_id` as a query parameter):

```bash
neon api /projects -X POST -F project.name=my-project -F project.org_id=org-cool-darkness-12345678
```

For a larger body, put the JSON in a file and pass it with `-d @<file>`:

```json filename="project.json"
{
  "project": {
    "name": "my-project",
    "org_id": "org-cool-darkness-12345678"
  }
}
```

```bash
neon api /projects -X POST -d @project.json
```

### List endpoints

`--list` prints every route from the Neon OpenAPI spec; `--refresh` refetches the cached spec:

```bash
neon api --list
```

### YAML output

Responses print as JSON. Use the global `--output yaml` (`-o yaml`) for YAML:

```bash
neon api /projects -Q org_id=org-cool-darkness-12345678 -o yaml
```

--- [Document source](https://neon.com/docs/cli/ask.md) ---

> Summary: The Neon CLI `ask` command sends a question to the Neon assistant and prints the answer in your terminal. It answers from Neon's documentation and needs no login; use `--output json` for machine-readable output when scripting or calling it from an agent.

# Neon CLI command: ask

Ask the Neon assistant a question from the terminal

Last updated: 2026-11-01

The `ask` command sends a question to the Neon assistant and prints the answer to your terminal: `neon ask --prompt "<question>"`. The assistant answers from Neon's documentation, so keep questions scoped to Neon and Lakebase Postgres rather than general chat. No login is required, and it doesn't touch your projects or account. To find docs pages on a topic, use [`neon docs search`](https://neon.com/docs/cli/docs). To send feedback to the Neon team instead, use [`neon feedback`](https://neon.com/docs/cli/feedback).

The answer is natural-language text, not structured data. By default it streams as markdown, use `--output json` to get the answer back as a single `text` field you can parse.

## Usage

```bash
neon ask --prompt <question>
```

Pass your question with `--prompt`. It's the only required option.

## Options

| Option     | Description         | Type   | Default | Required |
| ---------- | ------------------- | ------ | ------- | :------: |
| `--prompt` | The question to ask | string | —       |    Yes   |

`--output json` and `--output yaml` both return the full answer at once as a single `text` field, instead of streaming markdown.

## Examples

Ask a question:

```bash
neon ask --prompt "How do schema-only branches work?"
```

Get the answer as JSON so you can process it in a script:

```bash
neon ask --prompt "What is a Neon project?" --output json
```

--- [Document source](https://neon.com/docs/cli/bootstrap.md) ---

> Summary: Covers the usage of the `bootstrap` command in the Neon CLI to scaffold a new application from a Neon starter template, including the interactive template picker, the `--default` quick start, and post-scaffold setup steps (dependency install, git init, agent tooling, and project linking).

# Neon CLI command: bootstrap

Scaffold a new project from a Neon starter template

Last updated: 2026-11-05

The `bootstrap` command scaffolds a new application from a Neon starter template. By default it runs interactively: it prompts you to pick a template, scaffolds it into the target directory, then offers the usual setup steps (install dependencies, initialize git, install agent tooling, and link the directory to a Neon project). To add a single function to an existing project from a template, use a [Function Registry template](https://neon.com/functions/templates) and [`neon functions new`](https://neon.com/docs/cli/functions#new) instead.

## Usage

```bash
neon bootstrap [directory] [options]
```

The directory argument is optional. Use `.` to scaffold into the current directory, or leave it out and bootstrap prompts you for one. The target directory must be empty unless you pass `--force`.

## Options

| Option                               | Description                                                                                                                                                                                                                                                                                   | Type    | Default | Required |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--agent`, `-a`                      | Coding agent to install into (repeatable). Forwarded to plugins, or to skills and mcp. Skips agent selection. Values listed below                                                                                                                                                             | array   | —       |    No    |
| `--agent-setup`                      | After scaffolding, install the Neon plugin or skills and MCP. Use --no-agent-setup to skip                                                                                                                                                                                                    | boolean | `true`  |    No    |
| `--default`, `-y`                    | Quick start: scaffold the default template (or --template), then install, git, agent tooling (project folders, else the host CLI agent; if none, pass --agent or omit --default in a terminal), and link with defaults. If several organizations or projects exist, link prints IDs and exits | boolean | `false` |    No    |
| `--deploy`                           | Run `neon deploy` once dependencies are installed and the project is linked, without asking. Fails if neon.ts reads an env var that is not set yet                                                                                                                                            | boolean | `false` |    No    |
| `--force`                            | Scaffold into the target directory even if it is not empty (colliding files are overwritten).                                                                                                                                                                                                 | boolean | `false` |    No    |
| `--git`                              | Initialize a git repository after scaffolding. In interactive mode this is offered as a prompt; use --no-git to skip without being asked.                                                                                                                                                     | boolean | `true`  |    No    |
| `--install`                          | Install dependencies after scaffolding. In interactive mode this is offered as a prompt; use --no-install to skip without being asked.                                                                                                                                                        | boolean | `true`  |    No    |
| `--link`                             | Link a Neon project after scaffolding. Templates with neon.ts link after install so env pull works; otherwise linking happens before install. In interactive mode this is offered as a prompt; use --no-link to skip without being asked.                                                     | boolean | `true`  |    No    |
| `--list-templates`, `--list`, `--ls` | List available templates and exit. --output json and --output yaml print a machine-readable catalog.                                                                                                                                                                                          | boolean | `false` |    No    |
| `--template`                         | Template to use (skips the interactive picker). Run with --list-templates to see available templates.                                                                                                                                                                                         | string  | —       |    No    |

Run with `--list-templates` to see the available templates (add `--output json` for a machine-readable catalog), and pass one with `--template` to skip the interactive picker.

The post-scaffold steps all default to on. In interactive mode, bootstrap asks about each one; pass the negated flag to skip it without being asked:

- `--install` / `--no-install`: install dependencies.
- `--git` / `--no-git`: initialize a git repository.
- `--agent-setup` / `--no-agent-setup`: install agent tooling, either the Neon plugin, or agent skills and the MCP server. Pass `--agent` (alias `-a`, repeatable) to name the agents and skip the picker, for example `neon bootstrap my-app --agent cursor`.
- `--link` / `--no-link`: run [`neon link`](https://neon.com/docs/cli/link) in the scaffolded directory.

Use `--default` (alias `-y`) for a quick start: it scaffolds the default template (or the one you pass with `--template`), then runs git init, agent tooling, dependency install, and `neon link --yes` without prompting.

`link --yes` picks your only organization and project and writes a `.neon` context file. If you have several, the other steps still finish, then the command lists the IDs and exits with an error. Bootstrap doesn't accept `--org-id` or `--project-id`, so link from the new directory:

```bash
neon link --yes --org-id <org-id> --project-id <project-id>
```

Outside an interactive terminal (no TTY, or in CI), bootstrap only scaffolds the template. It skips every post-scaffold step, even one you pass explicitly like `--install`, and its summary lists the commands to run next. Use `--default` to run the steps unattended.

When the template has a [`neon.ts`](https://neon.com/docs/reference/neon-ts), bootstrap can also deploy it once dependencies are installed and the project is linked. It checks the environment variables your functions read against the env file that `neon link` pulled (`.env` if the directory has one, otherwise `.env.local`). If they're all set, bootstrap asks in an interactive terminal whether to deploy now and runs [`neon deploy --env <file>`](https://neon.com/docs/cli/deploy) with that file. With `--default`, it skips the question and lists that command under `Next:`. If any are unset, `Next:` names them.

Pass `--deploy` to install, link, and deploy without asking. It fails with `neon deploy`'s error if an environment variable is unset. `--deploy` can't be combined with `--no-install` or `--no-link`, and needs `--default` outside an interactive terminal:

```bash
neon bootstrap my-app --template hono --default --deploy
```

## Examples

Create `./my-app` from an interactively chosen template:

```bash
neon bootstrap my-app
```

When the steps finish, bootstrap prints a summary. This run linked a project and skipped agent tooling:

```text
Project scaffolded.
-------------------

  Template      REST API
  Directory     my-app
  Dependencies  installed with npm
  Git           initialized
  Agents        skipped
  Project       linked

Next:
  cd my-app
  See the README to run it.
```

Scaffold a specific template into the current directory:

```bash
neon bootstrap . --template hono
```

Scaffold the [Realtime](https://neon.com/docs/realtime/overview) React starter, a todo app with live queries and optimistic updates. Its `neon.ts` declares Realtime, so run `neon deploy` in the new directory to enable it:

```bash
neon bootstrap my-app --template realtime-react
```

Quick start: scaffold the default template and run setup without prompting:

```bash
neon bootstrap my-app --default
```

List the template catalog as JSON, for scripting or driving `bootstrap` from an agent. Each entry's `id` is what you pass to `--template`:

```bash
neon bootstrap --list-templates --output json
```

The command prints an array of template objects, each shaped like:

```json
{
  "id": "hono",
  "title": "REST API",
  "description": "A Hono REST API on Neon Functions, backed by Lakebase Postgres via Drizzle.",
  "services": ["Postgres", "Functions"]
}
```

--- [Document source](https://neon.com/docs/cli/branches.md) ---

> Summary: The Neon CLI `branches` command provides subcommands (list, create, reset, restore, rename, schema-diff, set-default, set-expiration, add-compute, delete, get) to manage Neon project branches from the terminal. Use this reference when you need exact flags and syntax for branch operations: point-in-time restore via RFC 3339 timestamp or LSN, schema diff between any two branches or historical states, expiration timestamps, or adding read replica computes.

# Neon CLI command: branches

List, create, rename, and delete branches; set default; run schema diff

Last updated: 2026-10-09

The `branches` command lists, creates, renames, deletes, and retrieves details about branches in your Neon project. It also sets the default branch, adds a compute or [read replica](https://neon.com/docs/introduction/read-replicas) to a branch, restores a branch to an earlier point in time, and runs a [schema diff](https://neon.com/docs/guides/schema-diff) between branches. For information about branches in Neon, see [Manage branches](https://neon.com/docs/manage/branches). If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

**Tip: Switch the active branch**

To pin a branch in your local `.neon` context file so subsequent commands target it, use [`neon checkout`](https://neon.com/docs/cli/checkout).

Subcommands: [add-compute](https://neon.com/docs/cli/branches#add-compute), [create](https://neon.com/docs/cli/branches#create), [delete](https://neon.com/docs/cli/branches#delete), [get](https://neon.com/docs/cli/branches#get), [list](https://neon.com/docs/cli/branches#list), [rename](https://neon.com/docs/cli/branches#rename), [reset](https://neon.com/docs/cli/branches#reset), [restore](https://neon.com/docs/cli/branches#restore), [schema-diff](https://neon.com/docs/cli/branches#schema-diff), [set-default](https://neon.com/docs/cli/branches#set-default), [set-expiration](https://neon.com/docs/cli/branches#set-expiration)

## neon branches list

Lists branches in a Neon project.

```bash
neon branches list [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

List branches with the default `table` output format:

```bash
neon branches list --project-id solitary-leaf-288182
```

```text filename="Output"
Name                   ID                     Current State  Expires At  Created At
[default] production   br-wispy-cloud-123456  ready          never       2026-09-30T13:15:12Z
[current] development  br-cool-forest-123456  ready          never       2026-09-30T14:45:50Z
```

Branch names include text labels that indicate status: `[default]` marks the project's default branch, `[protected]` marks a protected branch, `[anon]` marks an anonymized branch, and `[current]` marks the branch pinned in your local `.neon` context file.

List branches with `--output json`, which returns more information than the `table` format:

```bash
neon branches list --project-id solitary-leaf-288182 --output json
```

<details>

<summary>Show output</summary>

```json
[
  {
    "id": "br-wild-boat-123456",
    "project_id": "solitary-leaf-288182",
    "name": "production",
    "current_state": "ready",
    "logical_size": 29515776,
    "creation_source": "console",
    "default": true,
    "cpu_used_sec": 78,
    "compute_time_seconds": 78,
    "active_time_seconds": 312,
    "written_data_bytes": 107816,
    "data_transfer_bytes": 0,
    "created_at": "2026-07-09T17:01:34Z",
    "updated_at": "2026-07-09T17:15:13Z"
  },
  {
    "id": "br-shy-cake-123456",
    "project_id": "solitary-leaf-288182",
    "parent_id": "br-wild-boat-123456",
    "parent_lsn": "0/1E88838",
    "name": "development",
    "current_state": "ready",
    "creation_source": "console",
    "default": false,
    "cpu_used_sec": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "written_data_bytes": 0,
    "data_transfer_bytes": 0,
    "created_at": "2026-07-09T17:37:10Z",
    "updated_at": "2026-07-09T17:37:10Z"
  }
]
```

</details>

## neon branches create

Creates a branch in a Neon project.

```bash
neon branches create [options]
```

| Option              | Description                                                                                                                                                                                                                                                                    | Type    | Default         | Required |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | --------------- | :------: |
| `--compute`         | Create a branch with or without a compute. By default branch is created with a read-write compute. To create a branch without compute use --no-compute                                                                                                                         | boolean | `true`          |    No    |
| `--cu`              | The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").                                                                                                                                                                   | string  | project default |    No    |
| `--expires-at`      | Set an expiration date for the branch. Accepts a date string (e.g., 2024-12-31T23:59:59Z).                                                                                                                                                                                     | string  | never expires   |    No    |
| `--name`            | The branch name                                                                                                                                                                                                                                                                | string  | branch id       |    No    |
| `--parent`          | Parent branch name or id or timestamp or LSN. Defaults to the default branch                                                                                                                                                                                                   | string  | —               |    No    |
| `--protected`       | Whether the branch is protected. Protected branches (and their computes) cannot be deleted, archived, or reset, and block deletion of the project. Can be gated by `protected_branches_only` in the IP allowlist. Paid plans only.                                             | boolean | —               |    No    |
| `--psql`            | Connect to a new branch via psql                                                                                                                                                                                                                                               | boolean | `false`         |    No    |
| `--schema-only`     | Create a schema-only branch. Requires exactly one read-write compute.                                                                                                                                                                                                          | boolean | `false`         |    No    |
| `--secrets`         | Include connection credentials in command output. Use --no-secrets to omit them                                                                                                                                                                                                | boolean | `true`          |    No    |
| `--suspend-timeout` | Duration of inactivity in seconds after which the compute endpoint is automatically suspended. The value `0` means use the global default. The value `-1` means never suspend. The default value is `300` seconds (5 minutes). The maximum value is `604800` seconds (1 week). | number  | `0`             |    No    |
| `--type`            | Type of compute to add                                                                                                                                                                                                                                                         | string  | `read_write`    |    No    |
| `--project-id`      | Project ID                                                                                                                                                                                                                                                                     | string  | —               |    No    |

The `--name` value must be unique within the project and can be up to 256 characters; see [Branch naming requirements](https://neon.com/docs/manage/branches#branch-naming-requirements). A `read_only` compute is a [read replica](https://neon.com/docs/introduction/read-replicas).

**Note:** When creating a branch from a protected parent branch, role passwords on the child branch are changed. For more information about this Protected Branches feature, see [New passwords generated for Postgres roles on child branches](https://neon.com/docs/guides/protected-branches#new-passwords-generated-for-postgres-roles-on-child-branches).

```bash
neon branches create
```

```text filename="Output"
Branch
Name           br-mute-sunset-123456
ID             br-mute-sunset-123456
Current State  ready
Created At     2026-09-30T20:07:27Z

Compute
ID                       Created At
ep-floral-violet-123456  2026-09-30T20:07:27Z

Connection string
Connection URI
postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

**Note:** If the parent branch has more than one role or database, the `branches create` command does not output a connection URI. As an alternative, you can use the `connection-string` command to retrieve the connection URI for a branch. This command includes options for specifying the role and database. See [the connection-string command](https://neon.com/docs/cli/connection-string).

Omit the connection string from the output, keeping it out of terminal scrollback and CI logs:

```bash
neon branches create --no-secrets
```

Needs Neon CLI 4.9.0+; older versions ignore `--no-secrets` and still print the connection string.

Create a branch with `--output json`, which returns the full branch response data:

```bash
neon branches create --output json
```

<details>

<summary>Show output</summary>

```json
{
  "branch": {
    "id": "br-frosty-art-123456",
    "project_id": "polished-shape-60485499",
    "parent_id": "br-polished-fire-123456",
    "parent_lsn": "0/1E887C8",
    "name": "br-frosty-art-123456",
    "current_state": "init",
    "pending_state": "ready",
    "creation_source": "neon",
    "default": false,
    "cpu_used_sec": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "written_data_bytes": 0,
    "data_transfer_bytes": 0,
    "created_at": "2026-08-03T20:12:24Z",
    "updated_at": "2026-08-03T20:12:24Z"
  },
  "endpoints": [
    {
      "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
      "id": "ep-cool-darkness-123456",
      "project_id": "polished-shape-60485499",
      "branch_id": "br-frosty-art-123456",
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 1,
      "region_id": "aws-us-east-2",
      "type": "read_write",
      "current_state": "init",
      "pending_state": "active",
      "settings": {},
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "creation_source": "neon",
      "created_at": "2026-08-03T20:12:24Z",
      "updated_at": "2026-08-03T20:12:24Z",
      "proxy_host": "us-east-2.aws.neon.tech",
      "suspend_timeout_seconds": 0,
      "provisioner": "k8s-pod"
    }
  ],
  "connection_uris": [
    {
      "connection_uri": "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require",
      "connection_parameters": {
        "database": "dbname",
        "password": "AbC123dEf",
        "role": "alex",
        "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
        "pooler_host": "ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech"
      }
    }
  ]
}
```

</details>

Create a branch with a user-defined name:

```bash
neon branches create --name feature/user-auth
```

Set the compute size when creating a branch:

```bash
neon branches create --name mybranch --cu 2
```

Set the compute's autoscaling range when creating a branch:

```bash
neon branches create --name mybranch --cu 0.5-3
```

Create a branch with a read replica compute:

```bash
neon branches create --name my_read_replica_branch --type read_only
```

Create a branch from a parent branch other than your `main` branch:

```bash
neon branches create --name feature/payment-api --parent development
```

Create an instant restore branch by specifying the `--parent` option with a timestamp:

```bash
neon branches create --name data_recovery --parent 2023-07-11T10:00:00Z
```

The timestamp must be in RFC 3339 format (this [timestamp converter](https://it-tools.tech/date-converter) can help). For more about instant restore, see [Instant restore](https://neon.com/docs/guides/branch-restore).

Create a branch and connect to it with `psql` immediately. Arguments after `--` are passed through to psql, so you can run an `.sql` file or a query on creation:

```bash
neon branches create --psql
neon branches create --psql -- -f dump.sql
neon branches create --psql -- -c "SELECT version()"
```

Create a schema-only branch:

```bash
neon branches create --schema-only
```

Create a [protected branch](https://neon.com/docs/guides/protected-branches):

```bash
neon branches create --name production --protected
```

## neon branches reset

Resets a child branch to the latest data from its parent. The `<id|name>` is the branch ID or branch name; either works.

```bash
neon branches reset <id|name> [options]
```

| Option                  | Description                                 | Type    | Default | Required |
| ----------------------- | ------------------------------------------- | ------- | ------- | :------: |
| `--parent`              | Reset to a parent branch                    | boolean | `false` |    No    |
| `--preserve-under-name` | Name under which to preserve the old branch |         | —       |    No    |
| `--project-id`          | Project ID                                  | string  | —       |    No    |

The `--parent` option is required; resetting from the parent branch is currently the only supported reset operation. To rewind a branch to an earlier point in time, see [restore](https://neon.com/docs/cli/branches#restore).

```bash
neon branches reset development --parent
```

```text filename="Output"
Name           development
ID             br-cool-forest-123456
Current State  ready
Created At     2026-09-30T14:45:50Z
Last Reset At  2026-09-30T15:36:32Z
```

## neon branches restore

Restores a branch to a specified point in time in its own or another branch's history. The `<target-id|name>` is the ID or name of the branch you want to restore, and `<source>` is the source branch you want to restore from. Source options are:

- `^self`: restores the selected branch to an earlier point in its own history. You must specify a timestamp or LSN (restoring to head is not supported).
- `^parent`: restores the target branch to its parent. By default the target is restored to the latest (head) of its parent. Append `@timestamp` or `@lsn` to restore to an earlier point in the parent's history.
- A source branch ID or name: restores the target branch to the selected source branch. It restores the latest (head) by default. Append `@timestamp` or `@lsn` to restore to an earlier point in the source branch's history.

```bash
neon branches restore <target-id|name> <source>[@(timestamp|lsn)]
```

| Option                  | Description                                 | Type   | Default | Required |
| ----------------------- | ------------------------------------------- | ------ | ------- | :------: |
| `--preserve-under-name` | Name under which to preserve the old branch |        | —       |    No    |
| `--project-id`          | Project ID                                  | string | —       |    No    |

The `--preserve-under-name` option is required when restoring to `^self`.

Restore `main` to an earlier point in its own history, saving the previous state to a backup branch named `main_restore_backup_2026-09-29`:

```bash
neon branches restore main ^self@2026-09-29T10:00:00.000Z --preserve-under-name main_restore_backup_2026-09-29
```

```text filename="Output"
Restoring main to main at timestamp 2026-09-29T10:00:00.000Z
Restored branch
ID             br-purple-dust-123456
Name           main
Last Reset At  2026-09-30T09:45:21Z

Backup branch
ID    br-flat-forest-123456
Name  main_restore_backup_2026-09-29
```

Restore the target branch `feature/user-auth` to the head of the source branch `main`:

```bash
neon branches restore feature/user-auth main
```

```text filename="Output"
Restoring feature/user-auth to the head of main
Restored branch
ID             br-restless-frost-123456
Name           feature/user-auth
Last Reset At  2026-09-30T15:42:34Z
```

Restore `feature/user-auth` to an earlier point in time from its parent branch:

```bash
neon branches restore feature/user-auth ^parent@2026-09-29T10:30:00.000Z
```

```text filename="Output"
Restoring feature/user-auth to main at timestamp 2026-09-29T10:30:00.000Z
Restored branch
ID             br-restless-frost-123456
Name           feature/user-auth
Last Reset At  2026-09-30T15:55:04Z
```

## neon branches rename

Renames a branch.

```bash
neon branches rename <id|name> <new-name> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

The new name follows the same rules as `--name` on [branches create](https://neon.com/docs/cli/branches#create); see [Branch naming requirements](https://neon.com/docs/manage/branches#branch-naming-requirements).

```bash
neon branches rename mybranch teambranch
```

```text filename="Output"
Name           teambranch
ID             br-rough-sound-123456
Current State  ready
Created At     2026-09-30T20:46:58Z
```

## neon branches schema-diff

Compares the latest schemas of any two branches, or compares against a specific point in a branch's own or another branch's history.

For a git-style shortcut that defaults to comparing a branch against its parent, see [`neon diff`](https://neon.com/docs/cli/diff).

The `[base-branch]` is the branch to compare against. It's optional; if omitted, the command uses the branch from your `set-context` file, or the project's default branch if no context is configured.

The `[compare-source]` specifies the branch or state to compare against. Options are:

- `^self`: compares the selected branch to an earlier point in its own history. You must specify a timestamp or LSN.
- `^parent`: compares the selected branch to the head of its parent branch. You can append `@timestamp` or `@lsn` to compare to an earlier point in the parent's history.
- A branch ID or name: compares the selected branch to the head of another specified branch. Append `@timestamp` or `@lsn` to compare to an earlier point in the specified branch's history.

```bash
neon branches schema-diff [base-branch] [compare-source[@(timestamp|lsn)]] [options]
```

| Option               | Description                                                       | Type   | Default | Required |
| -------------------- | ----------------------------------------------------------------- | ------ | ------- | :------: |
| `--database`, `--db` | Name of the database for which the schema comparison is performed | string | —       |    No    |
| `--project-id`       | Project ID                                                        | string | —       |    No    |

**Note:** Use the `--no-color` or `--color false` [global option](https://neon.com/docs/cli#global-options) to decolorize command output in CI/CD pipelines.

Compare the schema of the `production` branch to the head of the `development` branch:

```bash
neon branches schema-diff production development
```

The output indicates that in the table `public.playing_with_neon`, a new column `description character varying(255)` has been added in the `development` branch that is not present in the `production` branch.

```text filename="Output"
--- Database: neondb	(Branch: br-wandering-firefly-a50un462)
+++ Database: neondb	(Branch: br-fancy-sky-a5cydw8p)
@@ -26,9 +26,10 @@

 CREATE TABLE public.playing_with_neon (
     id integer NOT NULL,
     name text NOT NULL,
-    value real
+    value real,
+    description character varying(255)
 );
```

Compare the schema of `feature/user-auth` to an earlier point in its own history at LSN `0/123456`:

```bash
neon branches schema-diff feature/user-auth ^self@0/123456
```

Compare the schema of `feature/user-auth` to the head of its parent branch:

```bash
neon branches schema-diff feature/user-auth ^parent
```

Compare the schema of the `production` branch to the state of `feature/payment-api` at timestamp `2024-06-01T00:00:00.000Z`:

```bash
neon branches schema-diff production feature/payment-api@2024-06-01T00:00:00.000Z
```

## neon branches set-default

Sets a branch as the default branch in your Neon project.

```bash
neon branches set-default <id|name> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon branches set-default mybranch
```

```text filename="Output"
Name           [default] mybranch
ID             br-odd-frog-123456
Current State  ready
Created At     2026-09-30T12:22:12Z
```

## neon branches set-expiration

Sets or updates the expiration date for a branch. When the expiration time is reached, the branch and its compute endpoints are permanently deleted.

```bash
neon branches set-expiration <id|name> [options]
```

| Option         | Description                                                                                                           | Type   | Default | Required |
| -------------- | --------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--expires-at` | Set a expiration date for the branch. If omitted, expiration will be removed. Format \[RFC3339]: 2024-12-31T23:59:59Z | string | —       |    No    |
| `--project-id` | Project ID                                                                                                            | string | —       |    No    |

Set an expiration date for a branch:

```bash
neon branches set-expiration mybranch --expires-at 2025-08-15T18:00:00Z
```

Remove expiration from a branch (omit the parameter):

```bash
neon branches set-expiration mybranch
```

## neon branches add-compute

Adds a compute to an existing branch in your Neon project.

```bash
neon branches add-compute <id|name> [options]
```

| Option         | Description                                                                                                  | Type   | Default     | Required |
| -------------- | ------------------------------------------------------------------------------------------------------------ | ------ | ----------- | :------: |
| `--cu`         | The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3"). | string | —           |    No    |
| `--name`       | Optional name of the compute                                                                                 | string | —           |    No    |
| `--type`       | Type of compute to add                                                                                       | string | `read_only` |    No    |
| `--project-id` | Project ID                                                                                                   | string | —           |    No    |

A `read_only` compute is a [read replica](https://neon.com/docs/introduction/read-replicas). A branch can have a single primary read-write compute and multiple read replica computes.

Add a read replica compute to a branch:

```bash
neon branches add-compute mybranch --type read_only
```

```text filename="Output"
ID    ep-rough-lab-123456
Host  ep-rough-lab-123456.us-east-2.aws.neon.tech
```

Set the compute size when adding a compute to a branch:

```bash
neon branches add-compute main --cu 2
```

Set the compute's autoscaling range when adding a compute to a branch:

```bash
neon branches add-compute main --cu 0.5-3
```

## neon branches delete

Deletes a branch in a Neon project.

```bash
neon branches delete <id|name> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon branches delete br-rough-sky-123456
```

```text filename="Output"
Name           my_child_branch
ID             br-rough-sky-123456
Current State  ready
Created At     2026-09-30T20:57:39Z
```

## neon branches get

Retrieves details about a branch.

```bash
neon branches get <id|name> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

Get a branch with the default `table` output format:

```bash
neon branches get production
```

```text filename="Output"
Name           [default] production
ID             br-wispy-cloud-123456
Current State  ready
Created At     2026-09-30T13:15:12Z
Logical Size   30.6 MiB
```

Get a branch with the `--output` format option set to `json`:

```bash
neon branches get production --output json
```

<details>

<summary>Show output</summary>

```json
{
  "id": "br-lingering-bread-123456",
  "project_id": "noisy-rain-039137",
  "name": "production",
  "current_state": "ready",
  "logical_size": 29769728,
  "creation_source": "console",
  "default": false,
  "cpu_used_sec": 522,
  "compute_time_seconds": 522,
  "active_time_seconds": 2088,
  "written_data_bytes": 174433,
  "data_transfer_bytes": 20715,
  "created_at": "2026-06-28T10:17:28Z",
  "updated_at": "2026-07-11T12:22:59Z"
}
```

</details>

--- [Document source](https://neon.com/docs/cli/buckets.md) ---

> Summary: The Neon CLI `neon buckets` command manages branch object-storage buckets and their contents: create, list, and delete buckets, and use the `neon buckets object` subcommands to list, download, upload, and delete objects. Object listing supports prefixes, a --delimiter to collapse keys into folders, and cursor-based pagination; `buckets object delete --recursive` removes every object under a prefix.

# Neon CLI command: buckets

Manage branch object-storage buckets and their objects

Last updated: 2026-09-17

The `buckets` command manages branch object-storage buckets and their objects. Buckets belong to a branch; the `object` subcommands work with the objects inside a bucket.

Subcommands: [create](https://neon.com/docs/cli/buckets#create), [delete](https://neon.com/docs/cli/buckets#delete), [list](https://neon.com/docs/cli/buckets#list), [object](https://neon.com/docs/cli/buckets#object)

## neon buckets create

Creates a bucket on a branch.

```bash
neon bucket create <name> [options]
```

| Option           | Description                                                            | Type   | Default   | Required |
| ---------------- | ---------------------------------------------------------------------- | ------ | --------- | :------: |
| `--access-level` | The visibility of the bucket Possible values: `private`, `public_read` | string | `private` |    No    |
| `--branch`       | Branch ID or name                                                      | string | —         |    No    |
| `--project-id`   | Project ID                                                             | string | —         |    No    |

Create a private bucket on a branch:

```bash
neon buckets create my-bucket --access-level private
```

## neon buckets list

Lists the buckets on a branch.

```bash
neon bucket list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

List the buckets on a branch with `json` output:

```bash
neon buckets list --output json
```

## neon buckets delete

Deletes a bucket from a branch.

```bash
neon bucket delete <name> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon buckets delete my-bucket
```

## Bucket objects

Lists, downloads, uploads, or deletes objects in a bucket.

Subcommands: [delete](https://neon.com/docs/cli/buckets#object-delete), [get](https://neon.com/docs/cli/buckets#object-get), [list](https://neon.com/docs/cli/buckets#object-list), [put](https://neon.com/docs/cli/buckets#object-put)

### neon buckets object list

Lists objects in a bucket.

```bash
neon bucket object list <bucket>[/<prefix>] [options]
```

| Option         | Description                                                                                                                              | Type    | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--branch`     | Branch ID or name                                                                                                                        | string  | —       |    No    |
| `--cursor`     | Pagination cursor returned as next\_cursor by a previous call                                                                            | string  | —       |    No    |
| `--delimiter`  | Collapse keys sharing this prefix separator into folders. Defaults to "/" (folder view); ignored when --recursive is set                 | string  | —       |    No    |
| `--limit`      | Maximum number of items (objects + folders) to return                                                                                    | number  | —       |    No    |
| `--project-id` | Project ID                                                                                                                               | string  | —       |    No    |
| `--recursive`  | List every key flat, descending into nested folders (no delimiter). Mutually exclusive with --delimiter. Mirrors "aws s3 ls --recursive" | boolean | `false` |    No    |

List the objects under a prefix, collapsing keys into folders:

```bash
neon buckets object list my-bucket/images --delimiter /
```

### neon buckets object get

Downloads an object from a bucket to a local file.

```bash
neon bucket object get <bucket>/<key> [options]
```

| Option         | Description                                                                                       | Type   | Default | Required |
| -------------- | ------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name                                                                                 | string | —       |    No    |
| `--file`       | Path to write the downloaded object to (defaults to the object filename in the current directory) | string | —       |    No    |
| `--project-id` | Project ID                                                                                        | string | —       |    No    |

```bash
neon buckets object get my-bucket/images/logo.png --file ./logo.png
```

### neon buckets object put

Uploads a local file to a bucket as an object.

```bash
neon bucket object put <bucket>/<key> [options]
```

| Option           | Description                                             | Type   | Default | Required |
| ---------------- | ------------------------------------------------------- | ------ | ------- | :------: |
| `--branch`       | Branch ID or name                                       | string | —       |    No    |
| `--content-type` | Content-Type to store the object with (e.g. text/plain) | string | —       |    No    |
| `--file`         | Path to the local file to upload                        | string | —       |    Yes   |
| `--project-id`   | Project ID                                              | string | —       |    No    |

Upload a file, optionally setting the Content-Type to store it with:

```bash
neon buckets object put my-bucket/images/logo.png --file ./logo.png
neon buckets object put my-bucket/notes/readme.txt --file ./readme.txt --content-type text/plain
```

### neon buckets object delete

Deletes an object, or every object under a prefix.

```bash
neon bucket object delete <bucket>/<key> [options]
```

| Option         | Description                                                              | Type    | Default | Required |
| -------------- | ------------------------------------------------------------------------ | ------- | ------- | :------: |
| `--branch`     | Branch ID or name                                                        | string  | —       |    No    |
| `--project-id` | Project ID                                                               | string  | —       |    No    |
| `--recursive`  | Delete every object under the given prefix. The prefix must end with "/" | boolean | `false` |    No    |

With `--recursive`, the target is treated as a prefix, which must end with `/`.

Delete a single object, or every object under a prefix:

```bash
neon buckets object delete my-bucket/images/logo.png
neon buckets object delete my-bucket/images/ --recursive
```

--- [Document source](https://neon.com/docs/cli/checkout.md) ---

> Summary: Covers the usage of the `checkout` command in the Neon CLI to switch the active branch in your local context, so subsequent commands target that branch without specifying `--branch` on every command.

# Neon CLI command: checkout

Pin a branch in your local .neon context file

Last updated: 2026-10-09

The `checkout` command pins a branch in the local context so subsequent commands target it. It's a focused helper over [`set-context`](https://neon.com/docs/cli/set-context) for the common "switch the branch I'm working on" case.

`checkout` resolves the branch (by name or ID) against the project, then heals the `.neon` file: it always (re)writes `projectId`, `branch`, and `orgId` (when the project has one), so a `.neon` that was missing fields or drifted ends up complete and consistent.

## Usage

```bash
neon checkout [id|name] [options]
```

The branch argument is optional. Run `neon checkout` with no branch in an interactive terminal to fetch the project's branches and pick one from a list. In a non-interactive context (CI or no TTY), you must pass a branch explicitly.

## Options

| Option         | Description                                                                                                                                                                                                                                                                                                                            | Type    | Default | Required |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--create`     | Create the named branch if it does not exist, then check it out                                                                                                                                                                                                                                                                        | boolean | `false` |    No    |
| `--env`        | Path to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Function env values that read process.env must be set in this file or the environment. Used when this checkout creates a branch from neon.ts; ignored for an existing branch. | string  | —       |    No    |
| `--env-pull`   | Pull the branch's Neon env vars (DATABASE\_URL, ...) into a local .env after checkout. On by default; use --no-env-pull to skip, for example when injecting env at runtime with `neon-env run` (from `@neon/env`) or `neon dev`.                                                                                                       | boolean | `true`  |    No    |
| `--project-id` | Project ID                                                                                                                                                                                                                                                                                                                             | string  | —       |    No    |

By default, `checkout` pulls environment variables into a `.env` file after checking out the branch; use `--no-env-pull` to skip this.

Creating a branch from a [`neon.ts`](https://neon.com/docs/reference/neon-ts) policy evaluates that policy, resolving any `process.env` values it references (such as a function's secrets) from your environment. Pass `--env <file>` to load those values from `<file>` first, so they resolve during the checkout. Checking out an existing branch doesn't re-evaluate the policy, so `--env` is ignored there.

## Branch ID vs name

Branch ID vs name is detected automatically (a `br-…` value is treated as an ID):

- **ID:** Matched strictly by ID. A non-existent ID is a hard "not found" error (IDs are server-assigned, so `checkout` never creates one).
- **Name:** Matched by name. If the name doesn't exist, pass `--create` to create it (equivalent to `neon branches create --name <name>`: branched from the project's default branch with a read-write compute), then check it out. Without `--create`, an interactive terminal offers to create it, while a non-interactive context (CI or no TTY) exits with a "not found" error that tells you to pass `--create`. `--create` needs a branch name, so `neon checkout --create` on its own is an error. `--create` requires neon 4.15.0 or later.

## Project resolution

The project is resolved through the standard Neon CLI chain, each entry winning over the next:

1. `--project-id <id>` flag
2. `projectId` from the closest `.neon` file (found by walking up from the current directory)
3. If still unresolved and the API key maps to exactly one project, that project is auto-detected (same behavior as `branches` and `connection-string`)

If none of those resolve a project, `checkout` prints an error explaining the chain above. In an interactive terminal it then offers to run [`neon link`](https://neon.com/docs/cli/link) in the current folder so you can pick (or create) a project on the spot. In non-interactive contexts, it exits with a non-zero code instead of prompting.

## Examples

Pin a branch by name. Projects created with the CLI or API get a default branch named `main`; Console-created projects use `production`. Run `neon branches list` if you're unsure:

```bash
neon checkout main --project-id polished-snowflake-12345678
```

```text filename="Output"
Checked out branch br-steep-math-aiu3vve7 on project polished-snowflake-12345678 (org org-example-12345678). Updated /path/to/cwd/.neon.
Pulled 5 Neon variables into .env.local
  Postgres        DATABASE_URL, DATABASE_URL_UNPOOLED
  Branch          NEON_BRANCH, NEON_BRANCH_ID
  Functions       NEON_FUNCTION_HOST_SUFFIX
```

The updated `.neon` file:

```json
{
  "projectId": "polished-snowflake-12345678",
  "orgId": "org-example-12345678",
  "branch": "main"
}
```

Pick a branch interactively (requires a linked project or `--project-id`):

```bash
neon checkout
```

Pin a branch by ID:

```bash
neon checkout br-cool-snow-12345678 --project-id polished-snowflake-12345678
```

Create a branch by name if it doesn't exist yet, then pin it:

```bash
neon checkout dev --create --project-id polished-snowflake-12345678
```

After checking out a branch, commands such as [`connection-string`](https://neon.com/docs/cli/connection-string) and [`psql`](https://neon.com/docs/cli/psql) use the pinned branch by default.

To run this checkout automatically whenever you switch git branches, see [`neon git`](https://neon.com/docs/cli/git) (Preview), which installs a git hook that checks out the mapped Neon branch on `git checkout`.

--- [Document source](https://neon.com/docs/cli/claim.md) ---

> Summary: The Neon CLI `claim` command (`neon claimable` is an alias) creates a temporary Neon project before anyone signs in. The CLI stores an identity assertion, writes credentials to `.env`, and later opens a claim URL so a human can take the project. See [Claimable Neon](/docs/reference/claimable-neon).

# Neon CLI command: claim

Create and claim a temporary Neon project without an account

Last updated: 2026-11-05

The `claim` command creates a temporary Neon project when there is no Neon account yet. `neon claimable` is an alias. The CLI stores an identity assertion on the machine, writes provisioned variables to `.env` (or `.env.local`), and later opens a claim URL so a human can take the project into their organization.

If `neon claim` is not a command, or `neon claim --help` does not list `create`, install the latest CLI (`npm i -g neon@latest`) or use the HTTP flow in [Claimable Neon](https://neon.com/docs/reference/claimable-neon).

Do not pass `--api-key` or `--profile`. Those are refused. `neon login` and `neon init` need a Neon account; use this command instead when there is none.

Start in the browser at [neon.com/claimable-neon](https://neon.com/claimable-neon), or give an agent [`auth.md`](https://neon.com/auth.md).

Subcommands: [accept](https://neon.com/docs/cli/claim#accept), [create](https://neon.com/docs/cli/claim#create), [delete](https://neon.com/docs/cli/claim#delete), [list](https://neon.com/docs/cli/claim#list), [status](https://neon.com/docs/cli/claim#status)

## neon claim create

Creates a temporary project and saves its identity assertion. Postgres is always requested. Pass `--service` for Data API, Managed Better Auth, or other services. If a [`neon.ts`](https://neon.com/docs/reference/neon-ts) file is present, declared services are requested automatically. [Realtime](https://neon.com/docs/cli/realtime) isn't available until the project is claimed, so `--service` doesn't accept it and a `neon.ts` Realtime declaration isn't requested.

```bash
neon claim create [options]
```

| Option                          | Description                                                                                                                                                                                                                                  | Type    | Default | Required |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--config`                      | Path to neon.ts for registration and the bundled env pull. Defaults to the neon.ts in the project directory (next to .neon, or cwd without one)                                                                                              | string  | —       |    No    |
| `--env-pull`                    | Write the same Neon env vars `env pull` would                                                                                                                                                                                                | boolean | `true`  |    No    |
| `--file`                        | Target dotenv file. Defaults to an existing .env, otherwise .env.local                                                                                                                                                                       | string  | —       |    No    |
| `--project-name`                | Name for the new project. The project keeps it when claimed                                                                                                                                                                                  | string  | —       |    No    |
| `--region-id`                   | Region ID for the new project (e.g. aws-eu-central-1). Defaults to aws-us-east-2                                                                                                                                                             | string  | —       |    No    |
| `--service`, `-s`, `--services` | Services to request for the claimable project: postgres, auth, data-api, functions, object-storage, ai-gateway. Repeat the flag or comma-separate. Postgres is always included. Services unavailable before claim are recorded and reported. | array   | —       |    No    |

```bash
neon claim create --env-pull
```

```bash
neon claim create \
  --service data-api \
  --service auth \
  --env-pull
```

`claim create` uses `aws-us-east-2` unless you pass `--region-id` with another AWS [region](https://neon.com/docs/introduction/regions) that accepts new projects. The output includes the project's `region_id`.

```bash
neon claim create --region-id aws-eu-central-1
```

The project gets a generated name unless you pass `--project-name`. It keeps the name when you claim it:

```bash
neon claim create --project-name my-app
```

`--env-pull` is on by default. It writes provisioned vars to an existing `.env`, otherwise `.env.local`, and gitignores that file. If `.env` or `.env.local` already has a `DATABASE_URL` (or other Neon-managed keys), pass `--file <path>` or `--no-env-pull`.

After create, regular Neon CLI commands use the saved assertion. Explicit Neon account credentials take precedence when you pass them.

## neon claim status

Shows a claimable project's lifecycle and claim status. Pass a project ID from `neon claim list`, or omit it to use the project linked in the current directory.

```bash
neon claim status [project-id] [options]
```

```bash
neon claim status
```

## neon claim accept

Creates a claim code and opens the URL where a human signs in and takes the project. `--open` is on by default. `--no-open` prints the URL.

```bash
neon claim accept [project-id] [options]
```

| Option   | Description                            | Type    | Default | Required |
| -------- | -------------------------------------- | ------- | ------- | :------: |
| `--open` | Open the verification URL in a browser | boolean | `true`  |    No    |

```bash
neon claim accept --no-open
```

Opening the URL does not freeze access. Continuing to Neon from that URL starts the transfer and rotates `DATABASE_URL` before the console org picker.

## neon claim list

Lists claimable projects saved on this machine.

```bash
neon claim list [options]
```

```bash
neon claim list
```

## neon claim delete

Permanently deletes an unclaimed project, or drops a local record that can no longer reach the service. Pass a project ID from `neon claim list`, or omit it to use the linked project. Pass `--yes` to skip the confirmation prompt.

```bash
neon claim delete [project-id] [options]
```

| Option        | Description                  | Type    | Default | Required |
| ------------- | ---------------------------- | ------- | ------- | :------: |
| `--yes`, `-y` | Skip the confirmation prompt | boolean | `false` |    No    |

```bash
neon claim delete --yes
```

--- [Document source](https://neon.com/docs/cli/completion.md) ---

> Summary: The `neon completion` command generates a yargs-based shell tab-completion script for `neon` that surfaces available commands and options when you press Tab. Use this page when you want to enable autocomplete for the Neon CLI in your terminal, so you can stop typing full command names from memory. Installation targets include `.bashrc`, `.bash_profile`, `.profile`, and `.zshrc` on Linux and macOS.

# Neon CLI command: completion

Generate shell completion scripts for neon commands and options

Last updated: 2026-07-01

The `completion` command generates a shell completion script for `neon`. Once installed, the script presents the possible commands and options when you press the **tab** key after typing or partially typing a command or option.

## Usage

```bash
neon completion
```

**Important:** Generate the completion script in your own terminal, as the script may differ depending on your operating environment.

<details>

<summary>Show output</summary>

```text filename="Output"
###-begin-neon-completions-###
#
# yargs command completion script
#
# Installation: neon completion >> ~/.bashrc
#    or neon completion >> ~/.bash_profile on OSX.
#
_neon_yargs_completions()
{
    local cur_word args type_list

    cur_word="${COMP_WORDS[COMP_CWORD]}"
    args=("${COMP_WORDS[@]}")

    # ask yargs to generate completions.
    type_list=$(neon --get-yargs-completions "${args[@]}")

    COMPREPLY=( $(compgen -W "${type_list}" -- ${cur_word}) )

    # if no match was found, fall back to filename completion
    if [ ${#COMPREPLY[@]} -eq 0 ]; then
      COMPREPLY=()
    fi

    return 0
}
complete -o bashdefault -o default -F _neon_yargs_completions neon
###-end-neon-completions-###
```

</details>

## Examples

Add the completion script to your shell configuration file in your home directory. The file differs by platform: Ubuntu typically uses `.bashrc`, while macOS uses `.bash_profile` or `.zshrc`. The `source` command applies the change to the current shell session.

Add the completion script to `.bashrc`:

```bash
neon completion >> ~/.bashrc
source ~/.bashrc
```

Add the completion script to `.bash_profile`:

```bash
neon completion >> ~/.bash_profile
source ~/.bash_profile
```

Add the completion script to `.profile`:

```bash
neon completion >> ~/.profile
source ~/.profile
```

Add the completion script to `.zshrc`:

```bash
neon completion >> ~/.zshrc
source ~/.zshrc
```

--- [Document source](https://neon.com/docs/cli/config.md) ---

> Summary: The Neon CLI `neon config` command manages a branch declaratively with a neon.ts policy file. Use `neon config init` to scaffold a starter neon.ts and install the config packages, `neon config add` to declare a service, function, or bucket in an existing neon.ts, `neon config status` to show the branch's live Neon state (`neon status --current-branch` prints the pinned branch offline for shell prompts), `neon config plan` for a dry run of what an apply would change, and `neon config apply` (or its top-level alias `neon deploy`) to apply the policy to the branch. Supports --config to point at a neon.ts file, --env to load environment variables before evaluating it, and --allow-protected, --update-existing, or -y to answer the apply confirmation prompts in non-interactive use.

# Neon CLI command: config

Manage a branch with a neon.ts policy: init, add, status, plan, and apply

Last updated: 2026-10-31

The `config` command manages a branch declaratively with a `neon.ts` policy file: scaffold a starter config, inspect the branch's live state, preview what an apply would change, and apply the policy. For the `neon.ts` file format, see the [neon.ts reference](https://neon.com/docs/reference/neon-ts).

Subcommands: [add](https://neon.com/docs/cli/config#add), [apply](https://neon.com/docs/cli/config#apply), [init](https://neon.com/docs/cli/config#init), [plan](https://neon.com/docs/cli/config#plan), [status](https://neon.com/docs/cli/config#status)

The top-level [`neon deploy`](https://neon.com/docs/cli/deploy) command is an alias for `config apply`, and [`neon status`](https://neon.com/docs/cli/status) is an alias for `config status`.

## neon config init

Scaffolds a starter `neon.ts` policy file in the current project and installs the `@neon/config` and `@neon/env` packages, so you can start managing a branch declaratively. The generated file uses the standard named `defineConfig` import from `@neon/config/v1` and exports the result as the module default, for example:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  // Declare your Neon services here
  auth: false,
  // Branch policy: per-branch tuning
  branch: (branch) => {
    if (branch.isDefault) {
      // Default branch: no overrides, uses project defaults
      return {};
    }
    if (!branch.exists) {
      // New non-default branches: auto-expire
      // Run `neon checkout <name>` to create a new branch with these settings
      return { ttl: "7d" };
    }
    // Existing branch: no changes
    return {};
  },
});
```

If a `neon.ts`, `neon.mts`, `neon.js`, or `neon.mjs` file already exists, `config init` is idempotent: it leaves that file untouched instead of overwriting hand-written policy.

By default, `config init` runs locally and does not call the Neon API. With `--from-branch`, it reads the branch's live state through the Neon API, so it needs your Neon credentials and a project. It picks your package manager (npm, pnpm, yarn, or bun) from the project's lockfile, or from how the command was invoked if there's no lockfile. Before installing, it makes sure `node_modules/` is listed in your `.gitignore`, appending it if it's missing. Pass `--no-install` to skip installation and just print the command to run.

```bash
neon config init [options]
```

| Option                          | Description                                                                                                                                                                                                                                                                                                    | Type    | Default | Required |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--from-branch`                 | Seed neon.ts from a branch's live Neon state instead of asking. Uses the branch pinned in .neon, or --branch \<name\|id>, or the project's default branch. Needs credentials and a project.                                                                                                                    | boolean | —       |    No    |
| `--install`                     | Install @neon/config and @neon/env if they're missing. On by default; use --no-install to just print the command.                                                                                                                                                                                              | boolean | `true`  |    No    |
| `--services`, `-s`, `--service` | Services the scaffolded neon.ts declares: postgres, auth, data-api, functions, object-storage, ai-gateway, realtime. Repeat the flag or comma-separate. postgres alone writes the starter policy; every branch has Postgres. Omitted: pick interactively on a terminal, starter policy in CI or without a TTY. | array   | —       |    No    |
| `--branch`                      | Branch ID or name                                                                                                                                                                                                                                                                                              | string  | —       |    No    |
| `--project-id`                  | Project ID                                                                                                                                                                                                                                                                                                     | string  | —       |    No    |

```bash
neon config init
```

Pass `--services` to declare services in the file it scaffolds, for example `neon config init --services auth,functions,realtime`. This applies only when creating a new `neon.ts`; to add services to a file that already exists, use [`config add`](https://neon.com/docs/cli/config#add).

In a linked project, declaring the Data API makes `config init` check the branch's Data API and pick `dataApi: true` or the external form, [as `init` does](https://neon.com/docs/cli/init). If the check fails, it declares `dataApi: true` with `auth: true` and prints a warning.

For non-interactive setup, run it with package installation disabled, then install the printed dependencies yourself (or add them to your lockfile in a separate step):

```bash
neon config init --no-install
npm install @neon/config @neon/env
```

Use `config init` when you want a trusted starter artifact and package list. Hand-write `neon.ts` instead when you need a different filename/module format or want to avoid modifying files in the current directory.

**Tip:** After running an interactive [`neon link`](https://neon.com/docs/cli/link), the CLI prompts you to run `config init` as its final step, unless the project already has a `neon.ts` file.

## neon config add

Declares a service, function, or bucket in your `neon.ts`, creating the file if there isn't one. Where [`config init`](https://neon.com/docs/cli/config#init) scaffolds a starter policy and leaves an existing file alone, `config add` edits an existing policy for you, including creating and registering a handler for a function. To declare services while first scaffolding the file, use [`config init --services`](https://neon.com/docs/cli/config#init) instead.

```bash
neon config add <sub-command> [options]
```

Subcommands: [ai-gateway](https://neon.com/docs/cli/config#add-ai-gateway), [auth](https://neon.com/docs/cli/config#add-auth), [bucket](https://neon.com/docs/cli/config#add-bucket), [data-api](https://neon.com/docs/cli/config#add-data-api), [function](https://neon.com/docs/cli/config#add-function), [realtime](https://neon.com/docs/cli/config#add-realtime)

`config add` runs entirely locally: it edits files, and never authenticates or resolves a project. Provisioning stays a separate [`neon config apply`](https://neon.com/docs/cli/config#apply) step.

It looks for your config in the project directory: the directory holding the nearest `.neon` file (found by searching up from the current directory), or the current directory when there's no `.neon`. A `neon.ts` in a parent directory no longer applies. When it finds none, it creates `neon.ts` there and installs the `@neon/config` and `@neon/env` packages; pass `--no-install` to print the install command instead. Editing an existing file never installs packages. Pass `--config <path>` to target a specific file; a path that doesn't exist is an error.

It edits the file in place, keeping your comments and formatting. It refuses edits it can't make safely, such as a graduated service still declared under the `preview` block, where it's a deprecated alias, and prints the lines to add by hand instead. Re-adding an already-enabled service exits `0` with "nothing to change"; a duplicate function slug or bucket name exits `1`; a bare `neon config add` exits `1` and lists what you can add.

### neon config add auth

Enables Managed Better Auth by setting `auth: true`.

```bash
neon config add auth [options]
```

| Option         | Description                                                                                                            | Type    | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--config`     | Path to the neon.ts to edit (defaults to the neon.ts next to .neon, or in cwd without one; created there when missing) | string  | —       |    No    |
| `--install`    | Install @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command.   | boolean | `true`  |    No    |
| `--branch`     | Branch ID or name                                                                                                      | string  | —       |    No    |
| `--project-id` | Project ID                                                                                                             | string  | —       |    No    |

```bash
neon config add auth
```

### neon config add data-api

Enables the Data API by setting `dataApi: true`, and enables Managed Better Auth, which the default provider requires (it flips `auth: false` to `true`). An existing external auth provider is left unchanged.

```bash
neon config add data-api [options]
```

| Option         | Description                                                                                                            | Type    | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--config`     | Path to the neon.ts to edit (defaults to the neon.ts next to .neon, or in cwd without one; created there when missing) | string  | —       |    No    |
| `--install`    | Install @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command.   | boolean | `true`  |    No    |
| `--branch`     | Branch ID or name                                                                                                      | string  | —       |    No    |
| `--project-id` | Project ID                                                                                                             | string  | —       |    No    |

```bash
neon config add data-api
```

### neon config add ai-gateway

Enables the AI Gateway by setting `aiGateway: true`.

```bash
neon config add ai-gateway [options]
```

| Option         | Description                                                                                                            | Type    | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--config`     | Path to the neon.ts to edit (defaults to the neon.ts next to .neon, or in cwd without one; created there when missing) | string  | —       |    No    |
| `--install`    | Install @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command.   | boolean | `true`  |    No    |
| `--branch`     | Branch ID or name                                                                                                      | string  | —       |    No    |
| `--project-id` | Project ID                                                                                                             | string  | —       |    No    |

```bash
neon config add ai-gateway
```

### neon config add realtime

Enables [Neon Realtime](https://neon.com/docs/realtime/overview) by setting `preview.realtime: true`. Pass `--allowed-origin` (repeatable) to set the browser origins allowed to connect instead, which writes `preview.realtime: { allowedOrigins: [...] }`. Each origin must be `*` or an `http` or `https` origin with no path, query, or fragment, and the command checks them before editing the file. See [`neon realtime enable`](https://neon.com/docs/cli/realtime#enable) for the full rules.

```bash
neon config add realtime [options]
```

| Option             | Description                                                   | Type   | Default | Required |
| ------------------ | ------------------------------------------------------------- | ------ | ------- | :------: |
| `--allowed-origin` | Allowed browser origin (repeatable). "\*" allows every origin | array  | —       |    No    |
| `--branch`         | Branch ID or name                                             | string | —       |    No    |
| `--project-id`     | Project ID                                                    | string | —       |    No    |

With an existing `neon.ts`, setting an allowed origin updates it in place:

```bash
neon config add realtime --allowed-origin https://app.example.com
```

```text
Updated neon.ts: set preview.realtime to { allowedOrigins: ["https://app.example.com"] }.
Next: `neon config plan` to preview, `neon config apply` to provision.
```

### neon config add function

Declares a [Neon Function](https://neon.com/docs/cli/functions) and creates its handler file. The handler defaults to `functions/<slug>.ts` (`.js` for a JavaScript config). A slug is 1 to 20 lowercase letters and digits, with no hyphens. Pass `--name` to set a display name (it defaults to the slug), or `--source` to register an existing handler relative to `neon.ts` without overwriting it. To start from a [Function Registry template](https://neon.com/functions/templates) instead of the starter handler, use [`neon functions new`](https://neon.com/docs/cli/functions#new).

```bash
neon config add function <slug> [options]
```

| Option         | Description                                                                                                          | Type   | Default | Required |
| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--name`       | Display name. Defaults to the slug                                                                                   | string | —       |    No    |
| `--source`     | Handler file, relative to neon.ts. Defaults to functions/\<slug>.ts. Created when missing, left alone when it exists | string | —       |    No    |
| `--branch`     | Branch ID or name                                                                                                    | string | —       |    No    |
| `--project-id` | Project ID                                                                                                           | string | —       |    No    |

Adding a function to a directory with no `neon.ts` creates both the config and the handler:

```bash
neon config add function sendemail
```

```text
Created functions/sendemail.ts.
Created neon.ts: added functions.sendemail.
Created package.json.
Installing @neon/config, @neon/env with npm…
Next: `neon dev` to run it locally, `neon config apply` to deploy.
```

### neon config add bucket

Declares a [Neon Object Storage](https://neon.com/docs/cli/buckets) bucket. Pass `--access public_read` to allow anonymous reads; the default is `private`.

```bash
neon config add bucket <name> [options]
```

| Option         | Description                                                                                                                   | Type   | Default   | Required |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | --------- | :------: |
| `--access`     | Anonymous access: private requires credentials, public\_read allows anonymous reads Possible values: `private`, `public_read` | string | `private` |    No    |
| `--branch`     | Branch ID or name                                                                                                             | string | —         |    No    |
| `--project-id` | Project ID                                                                                                                    | string | —         |    No    |

```bash
neon config add bucket assets --access public_read
```

## neon config status

Shows the branch's live Neon state.

```bash
neon config status [options]
```

| Option             | Description                                                                                                                                                 | Type    | Default | Required |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--config-json`    | Print only the branch's live config as neon.ts-shaped JSON (services + branch tuning + preview), to stdout. Useful for scripting or copying into a neon.ts. | boolean | `false` |    No    |
| `--current-branch` | Print only the linked branch name from the local .neon file (no network). Exits non-zero when no branch is pinned.                                          | boolean | `false` |    No    |
| `--branch`         | Branch ID or name                                                                                                                                           | string  | —       |    No    |
| `--project-id`     | Project ID                                                                                                                                                  | string  | —       |    No    |

```bash
neon config status
```

The top-level `neon status` command is an alias for `config status` and accepts the same options.

### Print the current branch offline

Pass `--current-branch` to print _only_ the branch pinned in the local `.neon` file. This variant makes no network request and requires no login or analytics, so it is cheap enough to drive a shell prompt.

It prints the branch name to stdout and exits `0`. When no branch is pinned, it prints nothing to stdout, writes a `neon checkout <branch>` hint to stderr, and exits with a non-zero status, so a prompt can guard on the command directly.

```bash
neon status --current-branch
```

For example, add your current Neon branch to a [starship](https://starship.rs) prompt. Append this `[custom.neon]` module to `~/.config/starship.toml`. The `command` prints the pinned branch, and `when` hides the segment (exits non-zero) whenever you are not in a Neon project:

```toml
# ~/.config/starship.toml
[custom.neon]
description = "Current Neon branch"
command = "neon status --current-branch"   # prints the branch pinned in .neon (no network)
when = "neon status --current-branch"       # exits non-zero when no branch -> segment is hidden
symbol = "🌿 "
style = "bold green"
format = "[$symbol$output]($style) "
```

**Tip: Faster outside Neon projects**

The `when` above runs the CLI on every prompt everywhere. To skip it unless a `.neon` file exists somewhere up the tree, replace `when` with a pure-shell walk-up and add `shell = ["sh"]` so it runs under `sh` even if your interactive shell is fish or PowerShell:

```toml
shell = ["sh"]
when = '''
d="$PWD"
while [ "$d" != "$HOME" ] && [ "$d" != / ]; do
  if [ -e "$d/.neon" ]; then
    neon status --current-branch >/dev/null 2>&1
    exit $?
  fi
  d=$(dirname "$d")
done
exit 1
'''
```

For a full copy-paste (and agent-ready) walkthrough, including prerequisites and troubleshooting, see this [Starship + Neon branch setup gist](https://gist.github.com/thisistonydang/0b6c03ec9aa9b619ffecd48f58fd40c7).

## neon config plan

Shows what `config apply` would change, as a dry run. Nothing is modified.

```bash
neon config plan [options]
```

| Option         | Description                                                                                                                                                                                                                                     | Type   | Default | Required |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--config`     | Path to a neon.ts policy (defaults to the neon.ts next to .neon, or in cwd without one)                                                                                                                                                         | string | —       |    No    |
| `--env`        | Path to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Function env values that read process.env must be set in this file or the environment. | string | —       |    No    |
| `--branch`     | Branch ID or name                                                                                                                                                                                                                               | string | —       |    No    |
| `--project-id` | Project ID                                                                                                                                                                                                                                      | string | —       |    No    |

```bash
neon config plan --config ./neon.ts --env .env.local
```

## neon config apply

Applies a `neon.ts` policy to the branch.

```bash
neon config apply [options]
```

| Option              | Description                                                                                                                                                                                                                                     | Type    | Default | Required |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--allow-protected` | Apply to a branch marked protected on Neon without asking                                                                                                                                                                                       | boolean | `false` |    No    |
| `--config`          | Path to a neon.ts policy (defaults to the neon.ts next to .neon, or in cwd without one)                                                                                                                                                         | string  | —       |    No    |
| `--env`             | Path to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Function env values that read process.env must be set in this file or the environment. | string  | —       |    No    |
| `--env-pull`        | Pull the branch's Neon env vars (DATABASE\_URL, …) into a local .env after a successful apply. On by default; use --no-env-pull to skip (e.g. when injecting env at runtime with `neon-env run` / `neon dev`).                                  | boolean | `true`  |    No    |
| `--update-existing` | Override branch settings that differ from neon.ts without asking                                                                                                                                                                                | boolean | `false` |    No    |
| `--yes`, `-y`       | Answer yes to every confirmation: --update-existing and --allow-protected                                                                                                                                                                       | boolean | `false` |    No    |
| `--branch`          | Branch ID or name                                                                                                                                                                                                                               | string  | —       |    No    |
| `--project-id`      | Project ID                                                                                                                                                                                                                                      | string  | —       |    No    |

In a terminal, `apply` asks before it overrides branch settings that differ from `neon.ts` or applies to a branch marked protected on Neon. Declining applies nothing.

Without a terminal, there's no prompt. This covers CI, runs with no TTY, and `-o json` or `-o yaml` output. In those cases, `apply` stops before changing anything and names the flag to re-run with. For scripts, CI, and agents, pass `--update-existing` to allow the overrides, `--allow-protected` to allow a protected branch, or `-y` for both:

```bash
neon config apply --branch feature/auth -y
```

--- [Document source](https://neon.com/docs/cli/connection-string.md) ---

> Summary: The Neon connection string command (`neon connection-string`) outputs a PostgreSQL connection URL for a specified branch, role, and database, including the role password. Use it to get connection strings for psql, Prisma (--prisma), connection pooling (--pooled), read-only replicas (--endpoint-type read_only), or time-travel queries targeting a specific timestamp or LSN.

# Neon CLI command: connection-string

Get Postgres connection strings for branches and databases

Last updated: 2026-11-05

The `connection-string` command gets a Postgres connection string for any database on any branch in your Neon project. The connection string includes the password for the specified role. It's also available as [`neon postgres connection-string`](https://neon.com/docs/cli/postgres#connection-string). For information about connecting to Neon, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app). If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`. `--database-name` is needed only when the branch has more than one database. Without `--role-name`, the command uses the branch's only role, or `neondb_owner` when there are several. The roles that the [Data API](https://neon.com/docs/data-api/get-started) and [Managed Better Auth](https://neon.com/docs/auth/overview) add (`authenticator`, `anonymous`, and `authenticated`) don't count, so you don't need `--role-name` on those branches either. This is the same role [`neon env pull`](https://neon.com/docs/cli/env) writes into `DATABASE_URL`. If the command still can't pick a role, it asks you to pass `--role-name`.

**Tip: Connect with psql**

To open a `psql` session directly, use the dedicated [`neon psql`](https://neon.com/docs/cli/psql) command. You can also pass `--psql` to `connection-string` to achieve the same result.

## Usage

```bash
neon connection-string [branch] [options]
```

The `[branch]` is the branch name or ID. If omitted, the default branch is used. To connect to a specific point in the branch's history, use the point-in-time format `branch@timestamp` or `branch@lsn`. If no timestamp or LSN is appended, the current state (HEAD) is used.

## Options

| Option            | Description                                                                                       | Type    | Default   | Required |
| ----------------- | ------------------------------------------------------------------------------------------------- | ------- | --------- | :------: |
| `--database-name` | Database name                                                                                     | string  | —         |    No    |
| `--endpoint-type` | Endpoint type                                                                                     | string  | —         |    No    |
| `--extended`      | Show extended information                                                                         | boolean | —         |    No    |
| `--pooled`        | Use pooled connection                                                                             | boolean | `false`   |    No    |
| `--prisma`        | Use connection string for Prisma setup                                                            | boolean | `false`   |    No    |
| `--project-id`    | Project ID                                                                                        | string  | —         |    No    |
| `--psql`          | Connect to a database via psql using connection string                                            | boolean | `false`   |    No    |
| `--role-name`     | Role name. Defaults to neondb\_owner, else the only role besides the Data API and Neon Auth roles | string  | —         |    No    |
| `--ssl`           | SSL mode Possible values: `require`, `verify-ca`, `verify-full`, `omit`                           | string  | `require` |    No    |

The `--endpoint-type` value can be `read_write` (the default) or `read_only`. The `--psql` option doesn't require a psql installation: if `psql` isn't on your `$PATH`, the CLI uses a built-in TypeScript implementation. To save your project context to a file and avoid repeating `--project-id`, see [Using a named context file](https://neon.com/docs/cli/set-context#using-a-named-context-file).

## Examples

Get a connection string for a branch:

```bash
neon connection-string mybranch
```

```text filename="Output"
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

- Get a pooled connection string. The `--pooled` option adds a `-pooler` suffix to the host name, which enables connection pooling for clients that use this connection string.

  ```bash
  neon connection-string --pooled
  ```

  ```text
  postgresql://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
  ```

- Get a connection string for use with Prisma. The `--prisma` option adds `connect_timeout=30` to the connection string so that connections from Prisma Client don't time out.

  ```bash
  neon connection-string --prisma
  ```

  ```text
  postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require&connect_timeout=30
  ```

- Get a connection string to a specific point in a branch's history by appending `@timestamp` or `@lsn`. Availability depends on your configured [history window](https://neon.com/docs/introduction/history-window). For additional examples, see [How to use Time Travel](https://neon.com/docs/guides/time-travel-assist#how-to-use-time-travel).

  ```bash
  neon connection-string @2024-04-21T00:00:00Z
  ```

Get a connection string and connect with `psql`:

```bash
neon connection-string --psql
```

Get a connection string, connect with `psql`, and run an `.sql` file:

```bash
neon connection-string --psql -- -f dump.sql
```

Get a connection string, connect with `psql`, and run a query:

```bash
neon connection-string --psql -- -c "SELECT version()"
```

--- [Document source](https://neon.com/docs/cli/credentials.md) ---

> Summary: The Neon CLI `neon credentials` command manages branch-scoped credentials: issue a credential with storage, AI gateway, or function-invoke scopes, list the credentials on a branch, reveal a credential's secrets, rotate its secrets in place, and revoke it.

# Neon CLI command: credentials

Issue, list, reveal, rotate, and revoke scoped credentials on a branch

Last updated: 2026-10-21

The `credentials` command manages scoped credentials on a branch. A credential grants an application or agent direct access to a branch's surfaces without an account API key. Each credential carries one or more scopes and, when issued, a pair of secrets: an `api_token` and an `s3_secret_access_key`.

The available scopes are:

- `storage:read` and `storage:write` for [Neon Object Storage](https://neon.com/docs/storage/overview)
- `ai_gateway:invoke` for the [Neon AI Gateway](https://neon.com/docs/ai-gateway/overview)
- `functions:invoke` for invoking [Neon Functions](https://neon.com/docs/compute/functions/overview)

Credentials are branch-scoped. Pass `--project-id` and `--branch` to target a branch, or let the CLI resolve them from your [context file](https://neon.com/docs/cli/link). A credential's `token_id` has the form `nak_live_<hex>` and is stable across a rotation.

**Important: Store secrets when they're issued**

The `api_token` and `s3_secret_access_key` are returned only when you create or rotate a credential, or when you explicitly run `neon credentials reveal`. Store them securely as soon as they're issued.

Subcommands: [create](https://neon.com/docs/cli/credentials#create), [list](https://neon.com/docs/cli/credentials#list), [reveal](https://neon.com/docs/cli/credentials#reveal), [revoke](https://neon.com/docs/cli/credentials#revoke), [rotate](https://neon.com/docs/cli/credentials#rotate)

## neon credentials list

Lists the credentials on the branch. Secrets are never included; use [`neon credentials reveal`](https://neon.com/docs/cli/credentials#reveal) to see them.

```bash
neon credentials list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon credentials list --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Token ID                                   Name                               Principal Type  Scopes                       Created At
nak_live_aaaa1111bbbb2222cccc3333dddd4444  Default AI gateway credential      user            ai_gateway:invoke            2026-09-10T20:02:49Z
nak_live_eeee5555ffff6666aaaa7777bbbb8888  Default object storage credential  user            storage:read, storage:write  2026-09-10T20:02:50Z
```

## neon credentials create

Issues a new credential. `--scope` is required and repeatable; pass one for each capability you want to grant. `--name` is an optional label.

```bash
neon credentials create [options]
```

| Option         | Description                                                                                                                                                                                          | Type   | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--name`       | Label for the credential                                                                                                                                                                             | string | —       |    No    |
| `--scope`      | Capability to grant. Repeatable. Values: storage:read, storage:write, ai\_gateway:invoke, functions:invoke Possible values: `storage:read`, `storage:write`, `ai_gateway:invoke`, `functions:invoke` | array  | —       |    Yes   |
| `--branch`     | Branch ID or name                                                                                                                                                                                    | string | —       |    No    |
| `--project-id` | Project ID                                                                                                                                                                                           | string | —       |    No    |

```bash
neon credentials create --name uploads --scope storage:read --scope storage:write --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Token ID  nak_live_0123456789abcdef0123456789abcdef
Name      uploads
Scopes    storage:read, storage:write
api_token: <api_token>
s3_secret_access_key: <s3_secret_access_key>
WARNING: Store these secrets now: they are not shown again unless you run neon credentials reveal.
```

With `--output json`, the secrets stay on the object so scripts can read them:

<details>

<summary>Show output</summary>

```json
{
  "token_id": "nak_live_0123456789abcdef0123456789abcdef",
  "token_id_short": "0123456789ab",
  "name": "uploads",
  "api_token": "<api_token>",
  "s3_secret_access_key": "<s3_secret_access_key>",
  "scopes": ["storage:read", "storage:write"],
  "branch_id": "br-morning-frost-a1b2c3d4",
  "created_at": "2026-09-10T20:02:49Z"
}
```

</details>

## neon credentials reveal

Shows a credential's `api_token` and `s3_secret_access_key` again, looked up by `token_id`.

```bash
neon credentials reveal <tokenId> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon credentials reveal nak_live_0123456789abcdef0123456789abcdef --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Token ID  nak_live_0123456789abcdef0123456789abcdef
api_token: <api_token>
s3_secret_access_key: <s3_secret_access_key>
WARNING: These are live secrets. Treat them like a password.
```

## neon credentials rotate

Replaces a credential's secrets in place. The `token_id` is unchanged, so anything that references the credential by ID keeps working once you update the stored secrets.

```bash
neon credentials rotate <tokenId> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon credentials rotate nak_live_0123456789abcdef0123456789abcdef --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Token ID  nak_live_0123456789abcdef0123456789abcdef
Name      uploads
Scopes    storage:read, storage:write
api_token: <new api_token>
s3_secret_access_key: <new s3_secret_access_key>
WARNING: Store the new secrets now: a retry mints another pair and does not recover a lost response. A replica may briefly accept the previous secret.
```

## neon credentials revoke

Revokes a credential. Its secrets stop working and the `token_id` can no longer be revealed or rotated.

```bash
neon credentials revoke <tokenId> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon credentials revoke nak_live_0123456789abcdef0123456789abcdef --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Credential nak_live_0123456789abcdef0123456789abcdef revoked
```

--- [Document source](https://neon.com/docs/cli/data-api.md) ---

> Summary: Covers the usage of the `data-api` command in the Neon CLI to create, inspect, update, refresh, and delete the Neon Data API for a database.

# Neon CLI command: data-api

Provision and manage the Neon Data API from the CLI

Last updated: 2026-09-18

The `data-api` command provisions and manages the [Neon Data API](https://neon.com/docs/data-api/overview) for a database. For Console-based management, see [Manage Data API](https://neon.com/docs/data-api/manage).

Subcommands: [create](https://neon.com/docs/cli/data-api#create), [delete](https://neon.com/docs/cli/data-api#delete), [get](https://neon.com/docs/cli/data-api#get), [refresh-schema](https://neon.com/docs/cli/data-api#refresh-schema), [update](https://neon.com/docs/cli/data-api#update)

If `--project-id`, `--branch`, or `--database` are omitted, the CLI resolves them from your [context file](https://neon.com/docs/cli/link), auto-selects when there is only one option, and otherwise asks you to pass the flag.

## Settings flags

The `create` and `update` subcommands share a set of settings flags that configure how the Data API serves your database:

| Flag                            | Description                                                 | Type    |
| ------------------------------- | ----------------------------------------------------------- | ------- |
| `--db-aggregates-enabled`       | Enable aggregate functions in queries                       | boolean |
| `--db-anon-role`                | Database role used for anonymous (unauthenticated) requests | string  |
| `--db-extra-search-path`        | Extra schemas appended to the search path                   | string  |
| `--db-max-rows`                 | Maximum number of rows returned by a single request         | number  |
| `--db-schemas`                  | Comma-separated list of schemas exposed via the Data API    | string  |
| `--jwt-role-claim-key`          | JWT claim path used to extract the role                     | string  |
| `--jwt-cache-max-lifetime`      | Maximum JWT cache lifetime in seconds                       | number  |
| `--openapi-mode`                | OpenAPI mode. Choices: `ignore-privileges`, `disabled`      | string  |
| `--server-cors-allowed-origins` | CORS allowed origins                                        | string  |
| `--server-timing-enabled`       | Enable Server-Timing response headers                       | boolean |

## neon data-api create

Provisions the Neon Data API for a database.

```bash
neon data-api create [options]
```

| Option                          | Description                                                                 | Type    | Default | Required |
| ------------------------------- | --------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--add-default-grants`          | Grant all permissions on tables in the public schema to authenticated users | boolean | —       |    No    |
| `--auth-provider`               | Authentication provider Possible values: `neon_auth`, `external`            | string  | —       |    No    |
| `--db-aggregates-enabled`       | Enable aggregate functions in queries                                       | boolean | —       |    No    |
| `--db-anon-role`                | Database role used for anonymous (unauthenticated) requests                 | string  | —       |    No    |
| `--db-extra-search-path`        | Extra schemas appended to the search path                                   | string  | —       |    No    |
| `--db-max-rows`                 | Maximum number of rows returned by a single request                         | number  | —       |    No    |
| `--db-schemas`                  | Comma-separated list of schemas exposed via the Data API                    | string  | —       |    No    |
| `--jwks-url`                    | URL that lists the JWKS (used with external auth)                           | string  | —       |    No    |
| `--jwt-audience`                | Expected JWT audience claim                                                 | string  | —       |    No    |
| `--jwt-cache-max-lifetime`      | Maximum JWT cache lifetime in seconds                                       | number  | —       |    No    |
| `--jwt-role-claim-key`          | JWT claim path used to extract the role                                     | string  | —       |    No    |
| `--openapi-mode`                | OpenAPI mode Possible values: `ignore-privileges`, `disabled`               | string  | —       |    No    |
| `--provider-name`               | Name of the auth provider (e.g. Clerk, Stytch, Auth0)                       | string  | —       |    No    |
| `--server-cors-allowed-origins` | CORS allowed origins                                                        | string  | —       |    No    |
| `--server-timing-enabled`       | Enable Server-Timing response headers                                       | boolean | —       |    No    |
| `--skip-auth-schema`            | Skip creating the auth schema and RLS functions                             | boolean | —       |    No    |
| `--branch`                      | Branch ID or name                                                           | string  | —       |    No    |
| `--database`                    | Database name                                                               | string  | —       |    No    |
| `--project-id`                  | Project ID                                                                  | string  | —       |    No    |

`create` also accepts [settings flags](https://neon.com/docs/cli/data-api#settings-flags) to configure the Data API at provision time.

Provision the Data API with Managed Better Auth:

```bash
neon data-api create --database neondb --auth-provider neon_auth
```

## neon data-api get

Shows the Neon Data API status and settings.

```bash
neon data-api get [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--database`   | Database name     | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon data-api get --database neondb
```

## neon data-api update

Updates Neon Data API settings. By default, the flags you provide are merged with the current settings. Pass `--replace` to overwrite all settings with only the flags you provide.

```bash
neon data-api update [options]
```

| Option                          | Description                                                                                | Type    | Default | Required |
| ------------------------------- | ------------------------------------------------------------------------------------------ | ------- | ------- | :------: |
| `--db-aggregates-enabled`       | Enable aggregate functions in queries                                                      | boolean | —       |    No    |
| `--db-anon-role`                | Database role used for anonymous (unauthenticated) requests                                | string  | —       |    No    |
| `--db-extra-search-path`        | Extra schemas appended to the search path                                                  | string  | —       |    No    |
| `--db-max-rows`                 | Maximum number of rows returned by a single request                                        | number  | —       |    No    |
| `--db-schemas`                  | Comma-separated list of schemas exposed via the Data API                                   | string  | —       |    No    |
| `--jwt-cache-max-lifetime`      | Maximum JWT cache lifetime in seconds                                                      | number  | —       |    No    |
| `--jwt-role-claim-key`          | JWT claim path used to extract the role                                                    | string  | —       |    No    |
| `--openapi-mode`                | OpenAPI mode Possible values: `ignore-privileges`, `disabled`                              | string  | —       |    No    |
| `--replace`                     | Replace settings with only the flags provided. Omitted settings revert to server defaults. | boolean | `false` |    No    |
| `--server-cors-allowed-origins` | CORS allowed origins                                                                       | string  | —       |    No    |
| `--server-timing-enabled`       | Enable Server-Timing response headers                                                      | boolean | —       |    No    |
| `--branch`                      | Branch ID or name                                                                          | string  | —       |    No    |
| `--database`                    | Database name                                                                              | string  | —       |    No    |
| `--project-id`                  | Project ID                                                                                 | string  | —       |    No    |

`update` requires at least one [settings flag](https://neon.com/docs/cli/data-api#settings-flags). To refresh the schema cache without changing settings, use [`refresh-schema`](https://neon.com/docs/cli/data-api#refresh-schema) instead.

```bash
neon data-api update --database neondb --db-max-rows 1000
```

## neon data-api refresh-schema

Refreshes the Data API schema cache without changing settings.

```bash
neon data-api refresh-schema [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--database`   | Database name     | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon data-api refresh-schema --database neondb
```

## neon data-api delete

Deletes the Neon Data API for a database.

```bash
neon data-api delete [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--database`   | Database name     | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon data-api delete --database neondb
```

--- [Document source](https://neon.com/docs/cli/databases.md) ---

> Summary: The Neon CLI `databases` command lists, creates, and deletes Postgres databases within a Neon project branch directly from the terminal. Use `neon databases create --name <db> --owner-name <role>` to provision a database on a named branch, or omit `--branch` to target the project's default branch. Each subcommand accepts `--project-id` (required only for accounts with multiple projects) and `--context-file` for reusable context.

# Neon CLI command: databases

List, create, and delete databases in a Neon project

Last updated: 2026-11-05

The `databases` command lists, creates, and deletes databases in a Neon project from the terminal. It's also available as [`neon postgres databases`](https://neon.com/docs/cli/postgres#databases). For information about databases in Neon, see [Manage databases](https://neon.com/docs/manage/databases). If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

Subcommands: [create](https://neon.com/docs/cli/databases#create), [delete](https://neon.com/docs/cli/databases#delete), [list](https://neon.com/docs/cli/databases#list)

## neon databases list

Lists databases. If you don't specify a branch ID or name with `--branch`, the command targets the project's default branch. This applies to all `databases` subcommands.

```bash
neon databases list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon databases list
```

```text filename="Output"
Databases on main
Name    Owner Name    Created At
neondb  neondb_owner  2026-06-19T18:27:19Z
```

The table is titled with the branch the databases belong to. Pass `--branch <id-or-name>` to list another branch's databases.

## neon databases create

Creates a database. If you don't specify `--owner-name`, the current user becomes the database owner.

```bash
neon databases create [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--name`       | Database name     | string | —       |    Yes   |
| `--owner-name` | Owner name        | string | —       |    No    |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon databases create --name mynewdb --owner-name alex
```

```text filename="Output"
Database created on main
Name        mynewdb
Owner Name  alex
Created At  2026-06-19T23:45:45Z
```

## neon databases delete

Deletes a database. The `<database>` is the database name.

```bash
neon databases delete <database> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon databases delete mydb
```

```text filename="Output"
Database deleted from main
Name        mydb
Owner Name  neondb_owner
Created At  2026-06-19T23:45:45Z
```

--- [Document source](https://neon.com/docs/cli/deploy.md) ---

> Summary: The Neon CLI `neon deploy` command applies a neon.ts policy to a branch. It is a top-level alias of `neon config apply` with the same options, so you can reconcile a branch without the `config` prefix.

# Neon CLI command: deploy

Apply a neon.ts policy to a branch

Last updated: 2026-10-15

The `deploy` command applies a `neon.ts` policy to a branch. It is a top-level alias of [`neon config apply`](https://neon.com/docs/cli/config#apply), with the same options.

```bash
neon deploy [options]
```

| Option              | Description                                                                                                                                                                                                                                     | Type    | Default | Required |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--allow-protected` | Apply to a branch marked protected on Neon without asking                                                                                                                                                                                       | boolean | `false` |    No    |
| `--branch`          | Branch ID or name                                                                                                                                                                                                                               | string  | —       |    No    |
| `--config`          | Path to a neon.ts policy (defaults to the neon.ts next to .neon, or in cwd without one)                                                                                                                                                         | string  | —       |    No    |
| `--env`             | Path to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Function env values that read process.env must be set in this file or the environment. | string  | —       |    No    |
| `--env-pull`        | Pull the branch's Neon env vars (DATABASE\_URL, …) into a local .env after a successful apply. On by default; use --no-env-pull to skip (e.g. when injecting env at runtime with `neon-env run` / `neon dev`).                                  | boolean | `true`  |    No    |
| `--project-id`      | Project ID                                                                                                                                                                                                                                      | string  | —       |    No    |
| `--update-existing` | Override branch settings that differ from neon.ts without asking                                                                                                                                                                                | boolean | `false` |    No    |
| `--yes`, `-y`       | Answer yes to every confirmation: --update-existing and --allow-protected                                                                                                                                                                       | boolean | `false` |    No    |

In a terminal, `deploy` asks before it overrides branch settings that differ from `neon.ts` or applies to a branch marked protected on Neon. Declining applies nothing.

If `neon.ts` declares [Realtime](https://neon.com/docs/cli/realtime) under `preview.realtime`, `neon deploy` enables it on the branch, and the default env pull waits until it's ready and writes `NEON_REALTIME_URL` and `NEON_REALTIME_SECRET`.

Without a terminal, there's no prompt. This covers CI, runs with no TTY, and `-o json` or `-o yaml` output. In those cases, `deploy` stops before changing anything and names the flag to re-run with. For scripts, CI, and agents, pass `--update-existing` to allow the overrides, `--allow-protected` to allow a protected branch, or `-y` for both:

```bash
neon deploy --branch feature/auth -y
```

--- [Document source](https://neon.com/docs/cli/dev.md) ---

> Summary: The Neon CLI `neon dev` command runs Neon Functions locally with a dev server and hot reload. Pass --source to serve a single function entry module (optionally with --port for an explicit port), or omit --source to serve every function declared in neon.ts, each on its own dev server.

# Neon CLI command: dev

Run Neon Functions locally with a dev server

Last updated: 2026-10-15

The `dev` command runs [Neon Functions](https://neon.com/docs/compute/functions/overview) locally with a dev server and hot reload. Serve one function from its entry module, or every function declared in your `neon.ts` policy.

## Usage

```bash
neon dev [--source <path>] [options]
```

## Options

| Option     | Description                                                                                                                                                                                                                                     | Type   | Default | Required |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--env`    | Path to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Function env values that read process.env must be set in this file or the environment. | string | —       |    No    |
| `--port`   | Port to listen on (single-function mode only, with --source). Fails if taken. Without it (and without a PORT env var) a free port is chosen automatically.                                                                                      | number | —       |    No    |
| `--source` | Path to a single function entry module. Omit to serve every function declared in neon.ts.                                                                                                                                                       | string | —       |    No    |

## Examples

Serve one function on a free port with hot reload:

```bash
neon dev --source ./functions/hello.ts
```

Serve every function declared in `neon.ts` (one dev server each):

```bash
neon dev
```

Serve one function on an explicit port (fails if the port is taken):

```bash
neon dev --source ./functions/hello.ts --port 3000
```

## Environment variables

Before evaluating `neon.ts`, `neon dev` loads your project's `.env` and then `.env.local` into the environment. Values in `.env.local` override `.env`, and a variable already set in your shell wins over both. This lets function `env` values that read `process.env` resolve locally the same way they do for [`neon deploy --env`](https://neon.com/docs/cli/deploy). Pass `--env` to load only one file instead, resolved from the current directory:

```bash
neon dev --env .env.staging
```

Local functions inherit every loaded variable, including ones `neon.ts` doesn't declare. A deployed function only gets the variables `neon.ts` declares plus the ones Neon injects, so check that anything your code needs is declared before you deploy. The dev server's startup banner lists which env files it loaded and how many variables each one set.

`neon dev` never writes to these files. To reuse the branch credential behind the AI Gateway and Object Storage, it reads the file [`neon env pull`](https://neon.com/docs/cli/env) writes. Without that file, it resolves the credential again on every start, so run `neon env pull` once if you restart often.

## WebSockets

`neon dev` serves WebSocket upgrades locally, so you can test real-time functions before you deploy. Connect a client to the dev server's `ws://localhost:<port>` URL. See [WebSockets and SSE](https://neon.com/docs/compute/functions/websockets) for the function-side code.

--- [Document source](https://neon.com/docs/cli/diff.md) ---

> Summary: The Neon CLI `diff` command prints a git-style schema diff between two branches: the branch under review (the `+++` side) and the branch you compare against (the `---` side). Use this reference for the exact positional argument and flags: set the branch under review with `--branch`, the branch to compare against with the `compare-branch` positional, limit output to one database with `--database`, and target a project with `--project-id`.

# Neon CLI command: diff

Show a git-style schema diff between two branches

Last updated: 2026-10-09

The `diff` command shows a git-style schema diff between two branches, in the same unified diff format `git diff` produces. The branch under review is the `+++` side; the branch you compare against is the `---` side. Omit the `compare-branch` argument to diff against the reviewed branch's parent, which answers "what did I change since branching?". See [Schema diff](https://neon.com/docs/guides/schema-diff) for more on comparing schemas in Neon.

The `+++` branch comes from `--branch`, or the branch pinned in your [`.neon` context file](https://neon.com/docs/cli/link), or the project's default branch, in that order. `diff` covers every database on that branch unless you pass `--database`. Use `--output json` or `--output yaml` for a machine-readable diff, one entry per database.

`neon diff` is a shortcut for comparing branch schemas. To compare against a historical point in time (by timestamp or LSN), use the [`neon branches schema-diff`](https://neon.com/docs/cli/branches#schema-diff) subcommand.

## Usage

```bash
neon diff [compare-branch] [options]
```

## Options

| Option               | Description                                                                                        | Type   | Default | Required |
| -------------------- | -------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--branch`, `-b`     | The branch to review (the '+++' side). Defaults to the branch pinned in the local context (.neon). | string | —       |    No    |
| `--database`, `--db` | Limit the diff to a single database. Defaults to every database on the current branch.             | string | —       |    No    |
| `--project-id`       | Project ID                                                                                         | string | —       |    No    |

## Examples

Diff the branch pinned in your `.neon` context against its parent. This works only when the pinned branch has a parent; against the project's default branch it errors, since there's nothing above it to compare:

```bash
neon diff
```

Diff the reviewed branch's schema against the `main` branch:

```bash
neon diff main
```

## Example output

Say your `feature/checkout` branch adds a `discount_code` column to the `orders` table and a new `coupons` table on top of `main`. Diff it against `main` with `--branch`, which reviews an explicit branch regardless of your `.neon` context:

```bash
neon diff main --branch feature/checkout
```

```diff filename="Output"
→ Comparing schema main → feature/checkout
diff --neon database neondb
--- main (br-solitary-block-atxzqx8a)
+++ feature/checkout (br-wandering-bar-atq2lw6c)
@@ -22,6 +22,19 @@
 SET default_table_access_method = heap;

 --
+-- Name: coupons; Type: TABLE; Schema: public; Owner: neondb_owner
+--
+
+CREATE TABLE public.coupons (
+    code text NOT NULL,
+    percent_off integer NOT NULL,
+    expires_at timestamp with time zone
+);
+
+
+ALTER TABLE public.coupons OWNER TO neondb_owner;
+
+--
 -- Name: orders; Type: TABLE; Schema: public; Owner: neondb_owner
 --

@@ -29,7 +42,8 @@
     id integer NOT NULL,
     customer_id integer NOT NULL,
     total numeric(10,2) NOT NULL,
-    created_at timestamp with time zone DEFAULT now()
+    created_at timestamp with time zone DEFAULT now(),
+    discount_code text
 );
```

Each branch's schema is dumped as `pg_dump --schema-only` SQL and the two dumps are compared, so the diff includes generated lines you didn't write directly, such as `-- Name: ...` comments and `ALTER TABLE ... OWNER TO` statements. Lines prefixed with `+` exist only on the branch under review; `-` lines exist only on the compare branch. If the schemas match, `diff` reports no differences instead.

--- [Document source](https://neon.com/docs/cli/docs.md) ---

> Summary: The Neon CLI `docs` command searches neon.com from your terminal: the docs, API reference, PostgreSQL tutorial, guides, FAQs, changelog, and blog. It needs no login; use `--category` to narrow results and `--output json` for machine-readable output when scripting or calling it from an agent.

# Neon CLI command: docs

Search the Neon docs, guides, and more from the terminal

Last updated: 2026-10-22

The `docs` command searches neon.com and prints matching pages in your terminal. It covers the docs, API reference, PostgreSQL tutorial, guides, FAQs, changelog, and blog. No login is required, and it doesn't touch your projects or account. To get a written answer instead of a list of pages, use [`neon ask`](https://neon.com/docs/cli/ask).

Subcommands: [search](https://neon.com/docs/cli/docs#search)

## neon docs search

Searches neon.com and lists the matching pages.

```bash
neon docs search <query> [options]
```

| Option       | Description                                                                                                                            | Type   | Default | Required |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--category` | Only return pages in these categories (repeatable) Possible values: `docs`, `api`, `postgresql`, `guides`, `faqs`, `blog`, `changelog` | array  | —       |    No    |
| `--limit`    | Maximum number of results (1-40)                                                                                                       | number | `10`    |    No    |

By default, each result shows the page title and matching section, with the URL on the next line. Long title lines are cut to fit your terminal; URLs never are. `--output json` and `--output yaml` also include each result's `category`, `breadcrumb`, and a short `excerpt` of the matching text.

To search more than one category, repeat `--category`.

Search for a topic:

```bash
neon docs search "reset a branch"
```

Search only the API reference and the docs, and return the top three results:

```bash
neon docs search "create branch" --category api --category docs --limit 3
```

```text
Manage branches ' Branching with the Neon API ' Create a branch with the API
  https://neon.com/docs/manage/branches

Neon CLI command: branches ' neon branches create
  https://neon.com/docs/cli/branches

Neon CLI quickstart ' Common operations ' Create a branch
  https://neon.com/docs/cli/quickstart
```

Get results as JSON so you can process them in a script:

```bash
neon docs search "reset a branch" --limit 2 --output json
```

<details>

<summary>Show output</summary>

```json
[
  {
    "title": "Manage branches",
    "url": "https://neon.com/docs/manage/branches",
    "category": "docs",
    "breadcrumb": ["Docs", "Manage & operate", "Projects & resources"],
    "heading": "Manage branches > Reset a branch from parent",
    "excerpt": "You can use Neon's Reset from parent feature to instantly update a branch with the latest schema and data from its parent. This feature can be an integral part of your CI/CD automation. You can use the Neon Console, CLI, or API. For details, see Reset from parent."
  },
  {
    "title": "Branching with the Neon CLI",
    "url": "https://neon.com/docs/guides/branching-neon-cli",
    "category": "docs",
    "breadcrumb": ["Docs", "Postgres", "Branching", "Automate & workflows"],
    "heading": "Branching with the Neon CLI > Resetting a branch from its parent",
    "excerpt": "Depending on your development workflow, you might need to periodically reset a branch to match the latest state of its parent. This is useful, for example, when resetting a development branch back to the production branch before starting work on a new feature. Use the followin..."
  }
]
```

</details>

--- [Document source](https://neon.com/docs/cli/env.md) ---

> Summary: The Neon CLI `neon env pull` command writes a branch's Neon environment variables to a local .env file. By default it targets an existing .env file, otherwise .env.local, and only Neon-managed variables are rewritten; other lines in the file are preserved. Use --file to target a specific file, --branch to pull from a specific branch, and --service to pull only selected services.

# Neon CLI command: env

Manage a branch's Neon environment variables locally

Last updated: 2026-10-15

The `env` command manages a branch's Neon environment variables locally. [`neon link`](https://neon.com/docs/cli/link) and [`neon checkout`](https://neon.com/docs/cli/checkout) pull env variables automatically by default.

Subcommands: [pull](https://neon.com/docs/cli/env#pull)

## neon env pull

Writes the branch's Neon environment variables to a local `.env` file.

`neon env pull` works with or without a [`neon.ts`](https://neon.com/docs/reference/neon-ts) configuration file. Without one, it writes everything the branch has: the core variables (`DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `NEON_BRANCH`, `NEON_BRANCH_ID`), credentials for each service provisioned on the branch, and the default AI Gateway credential. With a `neon.ts`, it writes the core variables plus credentials for each service you declare (Managed Better Auth, Data API, AI Gateway, Object Storage, [Realtime](https://neon.com/docs/cli/realtime)).

It also writes `NEON_FUNCTION_HOST_SUFFIX`. Neon injects it and `NEON_BRANCH_ID` into every deployed [Neon Function](https://neon.com/docs/compute/functions/overview). Together they make up any function's URL on the branch: `https://<NEON_BRANCH_ID>-<slug><NEON_FUNCTION_HOST_SUFFIX>`. To build that URL in code, use [`functionBaseUrl("<slug>")`](https://neon.com/docs/compute/functions/environment-variables#call-another-function) from `@neon/env`. A pull without `--service` writes the suffix whether or not your `neon.ts` declares functions, and the function doesn't have to be deployed yet. `--service functions` writes only `NEON_BRANCH`, `NEON_BRANCH_ID`, and `NEON_FUNCTION_HOST_SUFFIX`.

Neon CLI 9.0.0 replaced the per-function `NEON_FUNCTION_<SLUG>_BASE_URL` variables that earlier releases wrote. A pull without `--service`, or with `--service functions`, removes those old lines, and `--env NEON_FUNCTION_<SLUG>_BASE_URL` fails with an error that points you to `functionBaseUrl`. To update code that read those variables, see [Call another function](https://neon.com/docs/compute/functions/environment-variables#call-another-function).

Unset function env vars don't block a pull. If a declared function reads a `process.env.*` value that isn't set, `neon env pull` (and the pull that [`neon link`](https://neon.com/docs/cli/link) and [`neon checkout`](https://neon.com/docs/cli/checkout) run) skips that value and writes everything else instead of failing. The commands that actually build or run your functions still require every declared value: `neon deploy`, `neon dev`, and `neon-env run`.

```bash
neon env pull [options]
```

| Option                          | Description                                                                                                                                                                                                                                         | Type   | Default | Required |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--config`                      | Path to a neon.ts policy (defaults to the neon.ts next to .neon, or in cwd without one)                                                                                                                                                             | string | —       |    No    |
| `--env`, `-e`                   |                                                                                                                                                                                                                                                     | array  | —       |    No    |
| `--file`                        | Target .env file to write, relative to cwd. Defaults to an existing .env, otherwise .env.local, in the project directory (next to .neon, or cwd without one). Only Neon variables are updated; other lines are preserved.                           | string | —       |    No    |
| `--service`, `-s`, `--services` | Pull only these services' variables: postgres, auth, data-api, functions, object-storage, ai-gateway, realtime. Repeat the flag or comma-separate. Overrides neon.ts, and prunes only within the services you name. Combines with --env as a union. | array  | —       |    No    |
| `--branch`                      | Branch ID or name                                                                                                                                                                                                                                   | string | —       |    No    |
| `--project-id`                  | Project ID                                                                                                                                                                                                                                          | string | —       |    No    |

Write the linked branch's Neon variables into `.env.local` (or `.env` if present):

```bash
neon env pull
```

Pull a specific branch into a specific file:

```bash
neon env pull --branch preview --file .env.preview
```

Pull only the variables for the services you name, ignoring `neon.ts`. Repeat `--service` or comma-separate the values (`postgres`, `auth`, `data-api`, `functions`, `object-storage`, `ai-gateway`, `realtime`):

```bash
neon env pull --service ai-gateway --service postgres
```

For [Realtime](https://neon.com/docs/realtime/overview), the pull writes `NEON_REALTIME_URL` and `NEON_REALTIME_SECRET`. With `--service realtime`, if Realtime is still provisioning on the branch (for example, right after [`neon realtime enable`](https://neon.com/docs/cli/realtime#enable)) or [rotating its secret](https://neon.com/docs/cli/realtime#rotate-secret), the pull waits until it's ready. `--service realtime` on its own doesn't write `DATABASE_URL`, so name `postgres` too when you need both:

```bash
neon env pull --service postgres --service realtime
```

Use a specific `neon.ts` policy instead of the one in the project directory (next to the nearest `.neon`, or the current directory when there's no `.neon`):

```bash
neon env pull --config ./config/neon.ts
```

--- [Document source](https://neon.com/docs/cli/feedback.md) ---

> Summary: The Neon CLI `feedback` command sends a short message to the Neon team without leaving your terminal. Pass your note with `--message`. It needs no login and doesn't touch your projects or account. Don't include passwords, API keys, connection strings, or other personal information.

# Neon CLI command: feedback

Send feedback about the Neon CLI and docs to the Neon team

Last updated: 2026-10-10

The `feedback` command sends a short message to the Neon team from the terminal: `neon feedback --message "<your feedback>"`. Use it to report a confusing command, a docs gap, or anything else about the CLI you'd like the team to see. To ask the Neon assistant a question instead, use [`neon ask`](https://neon.com/docs/cli/ask).

No login is required, and the command doesn't read or change your projects or account. Don't put passwords, API keys, connection strings, or other personal information in the message.

The `feedback` command requires Neon CLI version 8.0.2 or later. Run `neon --version` to check your version, and [upgrade the CLI](https://neon.com/docs/cli/install#upgrade) if needed. For other ways to reach the Neon team, see [Send feedback](https://neon.com/docs/introduction/feedback).

## Usage

```bash
neon feedback --message <feedback>
```

Pass your note with `--message`. It's the only required option.

## Options

| Option      | Description                                                                     | Type   | Default | Required |
| ----------- | ------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--message` | The feedback to send. Do not include passwords, API keys, or connection strings | string | —       |    Yes   |

## Examples

```bash
neon feedback --message "The branch docs were unclear about default branch names"
```

```text filename="Output"
Feedback received. Thank you!
```

--- [Document source](https://neon.com/docs/cli/functions.md) ---

> Summary: The Neon CLI `neon functions` command manages Neon Functions on a branch: create functions from Function Registry templates, deploy, list, get, and delete functions, and register and manage their custom domains with the `domains` subcommands.

# Neon CLI command: functions

Create, deploy, list, inspect, and delete Neon Functions, and manage their custom domains

Last updated: 2026-10-26

The `functions` command manages [Neon Functions](https://neon.com/docs/compute/functions/overview) on a branch. This is the command reference; for the full deployment workflow, see [Deploy functions](https://neon.com/docs/compute/functions/deploy). To run functions locally, see [`neon dev`](https://neon.com/docs/cli/dev). To add a function from a template, see [Use function templates](https://neon.com/docs/compute/functions/templates).

Subcommands: [delete](https://neon.com/docs/cli/functions#delete), [deploy](https://neon.com/docs/cli/functions#deploy), [domains](https://neon.com/docs/cli/functions#domains), [get](https://neon.com/docs/cli/functions#get), [list](https://neon.com/docs/cli/functions#list), [new](https://neon.com/docs/cli/functions#new), [templates](https://neon.com/docs/cli/functions#templates)

## neon functions new

Creates a function from a [Function Registry template](https://neon.com/functions/templates). It writes the template's files to `functions/<slug>/` and declares the function in `neon.ts`, creating the file if needed. It doesn't need a project or a signed-in session. Requires the Neon CLI 8.11.0 or later.

```bash
neon functions new [template] [options]
```

| Option                     | Description                                                                                                                                                                                  | Type    | Default | Required |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--add-to-config`          | Declare the function in neon.ts, creating it when missing. On by default; use --no-add-to-config to skip.                                                                                    | boolean | —       |    No    |
| `--all-operations`         | Include every operation. Conflicts with --operation.                                                                                                                                         | boolean | —       |    No    |
| `--config`                 | Path to the neon.ts to edit (defaults to the neon.ts next to .neon, or in cwd without one; created there when missing)                                                                       | string  | —       |    No    |
| `--dir`                    | Destination directory (defaults to functions/\<slug> next to neon.ts)                                                                                                                        | string  | —       |    No    |
| `--force`                  | Overwrite differing files and keep an existing neon.ts declaration                                                                                                                           | boolean | —       |    No    |
| `--install`                | Install the template's dependencies, plus @neon/config and @neon/env when neon.ts is created. A TTY asks when omitted, --yes installs, and anything else leaves the install command in Next. | boolean | —       |    No    |
| `--operation`              | Operation to include (repeatable). Without it, a TTY asks and anything else uses the recommended operations.                                                                                 | array   | —       |    No    |
| `--slug`                   | Function slug, also used as the directory name. A separate template keeps its own slugs and uses this only for the directory. Defaults to the template ID                                    | string  | —       |    No    |
| `--yes`, `-y`, `--default` | Skip prompts: use the recommended operations and install dependencies                                                                                                                        | boolean | —       |    No    |
| `--branch`                 | Branch ID or name                                                                                                                                                                            | string  | —       |    No    |
| `--project-id`             | Project ID                                                                                                                                                                                   | string  | —       |    No    |

By default, the slug is the template ID with everything except lowercase letters and digits removed, so `neon functions new context-dev` writes to `functions/contextdev/`.

A `router` template becomes one function, with a generated `index.ts` that routes each URL path to an operation. A `separate` template declares one function per operation under slugs the template sets, so `--slug` only renames the directory.

If the template needs environment variables, the command declares them in `neon.ts` and adds their names, without values, to `.env.example`. Set the values in `.env.local`, which `neon dev` loads automatically, and deploy with `neon deploy --env .env.local`. The `Next:` list may print `neon config apply` instead, which does the same thing as `neon deploy`.

Create a function from the `basic` template:

```bash
neon functions new basic --no-install
```

```text filename="Output"
Fetching template "basic" from the Function Registry…
Function created.
-----------------

  Template      Basic function (Neon)
  Function      basic
  Directory     functions/basic
  Config        neon.ts created: added functions.basic
  Dependencies  not installed

Next:
  npm install @neon/config @neon/env
  neon dev
  neon config apply
```

Use your own slug and skip `neon.ts`:

```bash
neon functions new basic --slug hello --no-add-to-config
```

```text filename="Output"
Fetching template "basic" from the Function Registry…
Function created.
-----------------

  Template   Basic function (Neon)
  Function   hello
  Directory  functions/hello
  Config     not added

Next:
  neon dev --source functions/hello/index.ts
  neon functions deploy hello --src functions/hello/index.ts
```

Templates live in [`registry/`](https://github.com/neondatabase/examples/tree/main/registry) in `neondatabase/examples`. Set `NEON_FUNCTION_REGISTRY_DIR` to a local copy of that directory to install templates you're developing. See [Test a template locally](https://neon.com/docs/compute/functions/registry#test-your-template-locally).

## neon functions templates

Browse the templates at [neon.com/functions/templates](https://neon.com/functions/templates). For the end-to-end workflow, see [Use function templates](https://neon.com/docs/compute/functions/templates). The live catalog is [registry.json](https://neon.com/functions/registry/registry.json). To contribute your own, see [Contribute a function template](https://neon.com/docs/compute/functions/registry).

Subcommands: [list](https://neon.com/docs/cli/functions#templates-list)

### neon functions templates list

Lists the templates you can pass to [`neon functions new`](https://neon.com/docs/cli/functions#new).

```bash
neon functions templates list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon functions templates list
```

```text filename="Output"
ID           Title                 Provider     Description
basic        Basic function        Neon         A minimal Neon Function with a JSON response.
context-dev  Context.dev web data  Context.dev  Search the web and news, read pages, answer questions, and retrieve brand data with Context.dev.
```

## neon functions deploy

Deploys a function from a local directory or entry file. The `<slug>` is the permanent function identifier: 1 to 20 lowercase letters and digits (`^[a-z0-9]{1,20}$`).

```bash
neon functions deploy <slug> [options]
```

| Option         | Description                                                                                                                              | Type    | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--bundle`     | Bundle --src with esbuild. Use --no-bundle to zip a prebuilt directory (root must contain index.mjs or index.js) or a file of that name. | boolean | `true`  |    No    |
| `--env`        | Environment variable as KEY=VALUE (repeatable)                                                                                           | array   | —       |    No    |
| `--runtime`    | Function runtime Possible values: `nodejs24`                                                                                             | string  | —       |    No    |
| `--src`        | Function source: a directory containing index.ts, index.js, or index.mjs (first file match is the entry), or a path to the entry file    | string  | —       |    No    |
| `--wait`       | Wait for the deployment to finish building                                                                                               | boolean | `true`  |    No    |
| `--branch`     | Branch ID or name                                                                                                                        | string  | —       |    No    |
| `--project-id` | Project ID                                                                                                                               | string  | —       |    No    |

By default, `deploy` waits until the deployment finishes building (`--wait=true`), which is the predictable path for scripts and CI. Use `--no-wait` to return immediately after triggering the deployment.

By default, `deploy` bundles your `--src` with esbuild before uploading. Pass `--no-bundle` to skip bundling and deploy a prebuilt source instead: the directory root (or the file you point at) must be named or contain `index.mjs` or `index.js`. This is useful when you run your own build step and want to ship the output as-is.

Deploy a function from an entry file:

```bash
neon functions deploy hello --src functions/hello.ts
```

```text filename="Output"
Function deployment triggered for function hello.
Function hello
URL            https://br-cool-darkness-123456-hello.compute.c-1.us-east-2.aws.neon.tech/
Deployment ID  1
Status         completed
Runtime        nodejs24
Memory         2048 MiB
Created At     2026-06-12T00:14:58.044690Z
```

Deploy with environment variables and wait for the build:

```bash
neon functions deploy hello --src functions/hello.ts --env LOG_LEVEL=info --wait
```

## neon functions list

Lists the functions on the branch.

```bash
neon functions list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon functions list
```

```text filename="Output"
Slug   Name   Status     URL                                                                         Created At
hello  hello  completed  https://br-cool-darkness-123456-hello.compute.c-1.us-east-2.aws.neon.tech/  2026-06-12T00:14:57.942988Z
```

List with full deployment details for scripts and agents:

```bash
neon functions list --output json
```

<details>

<summary>Show output</summary>

```json
[
  {
    "id": "hello",
    "slug": "hello",
    "name": "hello",
    "invocation_url": "https://br-cool-darkness-123456-hello.compute.c-1.us-east-2.aws.neon.tech/",
    "current_deployment": {
      "id": 1,
      "status": "completed",
      "memory_mib": 2048,
      "runtime": "nodejs24",
      "created_at": "2026-06-12T00:14:58.044690Z"
    },
    "active_deployment": {
      "id": 1,
      "status": "completed",
      "memory_mib": 2048,
      "runtime": "nodejs24",
      "created_at": "2026-06-12T00:14:58.044690Z"
    },
    "created_at": "2026-06-12T00:14:57.942988Z"
  }
]
```

</details>

## neon functions get

Shows a function's details.

```bash
neon functions get <slug> [options]
```

| Option                       | Description                                                  | Type    | Default | Required |
| ---------------------------- | ------------------------------------------------------------ | ------- | ------- | :------: |
| `--list-env-variables`, `-E` | List the environment variable names of the active deployment | boolean | `false` |    No    |
| `--branch`                   | Branch ID or name                                            | string  | —       |    No    |
| `--project-id`               | Project ID                                                   | string  | —       |    No    |

```bash
neon functions get hello
```

```text filename="Output"
Function
Slug        hello
Name        hello
URL         https://br-cool-darkness-123456-hello.compute.c-1.us-east-2.aws.neon.tech/
Created At  2026-06-12T00:14:57.942988Z

Deployment (current, active)
Deployment ID  1
Status         completed
Runtime        nodejs24
Memory         2048 MiB
Created At     2026-06-12T00:14:58.044690Z
```

## neon functions delete

Deletes a function on the branch.

```bash
neon functions delete <slug> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon functions delete hello
```

```text filename="Output"
Function hello deleted from branch br-cool-darkness-123456
```

## neon functions domains

Manage custom domains for functions on the branch.

Subcommands: [delete](https://neon.com/docs/cli/functions#domains-delete), [list](https://neon.com/docs/cli/functions#domains-list), [register](https://neon.com/docs/cli/functions#domains-register)

### neon functions domains list

Lists the custom domains registered on the branch.

```bash
neon functions domains list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon functions domains list
```

The default table shows the domain, target function, and CNAME target. To inspect DNS and routing status, use JSON output:

```bash
neon functions domains list --output json
```

```json filename="Output"
[
  {
    "domain": "docs.example.com",
    "entity_type": "function",
    "entity_id": "hello",
    "cname_target": "fn-custom-domains.us-east-2.aws.neon.tech",
    "status": "active",
    "dns_status": "ok",
    "binding_status": "present",
    "status_reason": ""
  }
]
```

An `active` status confirms that DNS, CAA authorization, and routing are ready. Verify the domain with an HTTPS request because certificate issuance isn't included in this status.

### neon functions domains register

Points a domain you already own at a function on the branch. Both `--slug` and the domain are required. The command prints a CNAME target; create a CNAME record for the domain at your DNS provider pointing at that target. See [Custom domains](https://neon.com/docs/compute/functions/custom-domains) for DNS, CAA, and TLS details.

```bash
neon functions domains register <domain> [options]
```

| Option         | Description                               | Type   | Default | Required |
| -------------- | ----------------------------------------- | ------ | ------- | :------: |
| `--slug`       | Function slug this domain should point at | string | —       |    Yes   |
| `--branch`     | Branch ID or name                         | string | —       |    No    |
| `--project-id` | Project ID                                | string | —       |    No    |

```bash
neon functions domains register docs.example.com --slug hello
```

### neon functions domains delete

Deletes a custom domain from the branch.

```bash
neon functions domains delete <domain> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon functions domains delete docs.example.com
```

Routing changes are eventually consistent, so the custom URL can continue reaching the function briefly after deletion. Deleting a function doesn't delete its custom-domain registration; delete the domain separately.

--- [Document source](https://neon.com/docs/cli/git.md) ---

> Summary: The Neon CLI `git` command connects git branch switches to Neon checkout. It installs a git post-checkout hook so that switching git branches checks out the mapped Neon branch, with subcommands to install and remove the hook (install, uninstall), run the sync by hand (sync), inspect the current state (status), and prune stale branch mappings (cleanup).

# Neon CLI command: git

Keep your Neon branch in sync with the git branch you have checked out

Last updated: 2026-10-07

The `git` command connects your git workflow to Neon branching. After you install its git hook, switching git branches with `git checkout` also checks out the Neon branch mapped to that git branch, so your application code and its database branch stay in sync. Under the hood it delegates to [`neon checkout`](https://neon.com/docs/cli/checkout) and records the git-to-Neon mapping in your local [context file](https://neon.com/docs/cli/link).

**Coming soon: Preview**

The `neon git` command group is in preview. The commands and their behavior may change.

Before you install the hook, link a Neon project at your repository root with [`neon link`](https://neon.com/docs/cli/link) or [`neon checkout`](https://neon.com/docs/cli/checkout). The hook reads the `.neon` context file at the repository root, so the project link has to live there.

Subcommands: [cleanup](https://neon.com/docs/cli/git#cleanup), [install](https://neon.com/docs/cli/git#install), [status](https://neon.com/docs/cli/git#status), [sync](https://neon.com/docs/cli/git#sync), [uninstall](https://neon.com/docs/cli/git#uninstall)

## neon git install

Installs a managed `post-checkout` git hook that runs `neon git sync` whenever you switch branches with `git checkout`. The hook honors your configured git hooks directory and won't overwrite an existing unmanaged `post-checkout` hook.

The command requires a project already linked at the repository root's own `.neon` file. If none is linked, install stops and tells you to run `neon link` or `neon checkout <branch>` there first.

```bash
neon git install [options]
```

```bash
neon git install
```

```text filename="Output"
Git → Neon sync installed. `git checkout <branch>` will now check out the mapped Neon branch.
Hook: /path/to/your/app/.git/hooks/post-checkout
```

## neon git status

Shows your current git branch, whether the hook is installed, whether sync-on-checkout is enabled, the Neon branch mapped to the current git branch, and all recorded mappings. Use `--output json` or `--output yaml` for scripting.

```bash
neon git status [options]
```

```bash
neon git status
```

```text filename="Output"
GitBranch         main
HookInstalled     false
FollowOnCheckout  false
MappedNeonBranch  (unmapped — will derive on next sync)
Mappings          (none)
```

## neon git sync

Checks out the Neon branch mapped to the current git branch. This is the command the installed hook runs on every `git checkout`, and you can also run it by hand. If no mapping exists yet, sync derives a Neon branch name from the current git branch and checks it out, then saves the resulting mapping so later checkouts of that git branch stay stable. The Neon branch has to exist already: sync doesn't create it, so a git branch with no matching Neon branch reports `Branch <name> not found. Pass --create to create it.` unless a `checkout.before` hook maps it to an existing branch. A detached HEAD has no git branch, so sync skips it.

Pass `--pull` to run `git pull --ff-only` before syncing, so committed files such as migrations match the branch before any `checkout.after` hook runs. A pull failure warns and sync continues. Pass `--no-env-pull` to skip pulling the branch's Neon environment variables into a local `.env` after sync.

```bash
neon git sync [options]
```

| Option       | Description                                                                                                                                                                                                                | Type    | Default | Required |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--env-pull` | Pull the branch's Neon env vars into a local .env after sync. On by default.                                                                                                                                               | boolean | `true`  |    No    |
| `--pull`     | Run `git pull --ff-only` before syncing so local files (incl. migration files) match the branch before any checkout.after migration runs. Without the flag, prompts when run manually in a TTY and skips in the hook / CI. | boolean | —       |    No    |
| `--quiet`    | Suppress sync's own routine status lines (git pull result, detached HEAD notice). Warnings and the delegated checkout's own output are unaffected. Used by the installed git hook.                                         | boolean | `false` |    No    |

```bash
neon git sync --no-pull
```

```text filename="Output"
Checked out branch br-billing-a1b2c3d4 on project polished-snowflake-12345678 (org org-example-12345678). Updated /path/to/your/app/.neon.
Pulled 5 Neon variables into .env.local
  Postgres        DATABASE_URL, DATABASE_URL_UNPOOLED
  Branch          NEON_BRANCH, NEON_BRANCH_ID
  Functions       NEON_FUNCTION_HOST_SUFFIX
```

## neon git cleanup

Removes git-to-Neon mappings whose local git branch no longer exists. By default it only prunes the mappings. Add `--prune-neon-branches` to also delete the orphaned Neon branches, which never touches the default or a protected branch. Deleting Neon branches prompts for confirmation unless you pass `--yes`.

```bash
neon git cleanup [options]
```

| Option                  | Description                                                                       | Type    | Default | Required |
| ----------------------- | --------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--prune-neon-branches` | Also delete the orphaned Neon branches (never the default or a protected branch). | boolean | `false` |    No    |
| `--yes`                 | Skip the confirmation prompt before deleting Neon branches.                       | boolean | `false` |    No    |

Prune stale mappings only:

```bash
neon git cleanup
```

```text filename="Output"
Pruned 1 stale mapping(s) from .neon:
  feature/billing → feature/billing
These Neon branch(es) are no longer mapped and were not deleted: feature/billing. Delete them with `neon branches delete <name>`, or run `neon git cleanup --prune-neon-branches` next time before a mapping-only cleanup.
```

Prune stale mappings and delete their Neon branches without a prompt:

```bash
neon git cleanup --prune-neon-branches --yes
```

## neon git uninstall

Removes the managed `post-checkout` hook installed by `neon git install` and turns off sync-on-checkout. If the `post-checkout` hook isn't the one Neon manages, uninstall leaves it in place and only clears the sync flag.

```bash
neon git uninstall [options]
```

```bash
neon git uninstall
```

```text filename="Output"
Removed the neon git post-checkout hook. Git → Neon sync is off.
```

--- [Document source](https://neon.com/docs/cli/init.md) ---

> Summary: The `neon init` command sets up the current directory to use Neon with your AI coding assistant. It installs agent tooling (either a plugin, or skills and the MCP server), links a Neon project, and optionally writes a neon.ts config. It runs interactively by default; pass -y for the recommended setup with no prompts, or add flags such as --skill, MCP options, or --claimable for the custom setup.

# Neon CLI command: init

Set up the current directory for Neon with agent tooling, a linked project, and an optional neon.ts config

Last updated: 2026-11-05

The `init` command sets up the current directory to use Neon with your AI coding assistant. It's a thin wrapper that runs Neon's other setup commands for you: it installs agent tooling, [links a Neon project](https://neon.com/docs/cli/link), and can write a [`neon.ts` config](https://neon.com/docs/cli/config). It sets up the current directory in place.

`init` is interactive, so run it from a terminal. It asks how coding agents should get Neon, prompts you to pick a project to link, and asks whether to write `neon.ts`. If you don't have the CLI installed, run it with `npx`:

```bash
npx neon@latest init
```

For agents, CI, or scripts that can't answer prompts, see [Run it non-interactively](https://neon.com/docs/cli/init#run-it-non-interactively).

**Note: Behavior changed in Neon CLI 6.0**

Before 6.0, `init` could scaffold a starter template in an empty directory, and it accepted `--template` and `--skip-template`. From 6.0, `init` only sets up the current directory in place, those template flags are gone, and `-y` runs a recommended setup. To scaffold a starter project, use [`neon bootstrap`](https://neon.com/docs/cli/bootstrap) instead.

## Usage

```bash
neon init [options]
```

## Recommended and custom setup

`init` has two setup modes:

- **Recommended setup** installs tooling for your detected coding agents, links a Neon project when the CLI is authenticated (or the session is interactive), and writes a default `neon.ts`. Run it with no prompts using `-y`. When no agents are detected, it writes the default skills in the current directory.
- **Custom setup** applies the specific answers you pass as flags and falls back to the recommended defaults for anything you don't. Passing `--skill`, an MCP flag (`--mcp-auth`, `--mcp-config-location`, or `--mcp-project-scoped`), `--no-agent-setup`, or `--claimable` selects it.

`-y` alone runs the recommended setup without prompts and never opens a browser. `-y` with any of those flags runs the custom setup with your answers, still without prompts.

## What it does

### Choose how coding agents get Neon

In a terminal, `init` asks how your coding agents should get Neon:

- **Plugin (recommended)** installs the `neon-postgres` plugin, which bundles agent skills and the MCP server.
- **Skills and MCP separately** installs [agent skills](https://neon.com/docs/cli/skills), then the [Neon MCP server](https://neon.com/docs/cli/mcp).
- **Skip agent setup** continues without a plugin, skills, or MCP.

You can also make this choice with flags, which skips the prompt:

- `--agent` (without skill or MCP flags) installs the plugin for the named agents, plus skills and MCP for any agent the plugin can't cover.
- `--skill` selects skills (not the plugin) and skips the skills picker. Combined with an MCP flag, it also configures MCP.
- An MCP flag (`--mcp-auth`, `--mcp-config-location`, or `--mcp-project-scoped`) selects skills and MCP.
- `--no-agent-setup` skips agent setup entirely.

The plugin and the skills-plus-MCP option are mutually exclusive; `init` sets up one family per run. Installing skills needs Node.js 22.20 or newer.

Recommended setup installs agent tooling globally for your detected agents, so it's available across projects. Custom setup can set up the current directory instead: pass `--mcp-config-location project` to write the MCP configuration locally. To control the scope yourself, run [`neon skills`](https://neon.com/docs/cli/skills) or [`neon plugins`](https://neon.com/docs/cli/plugins) directly.

### Link a project and write neon.ts

After agent setup, `init` runs [`neon link`](https://neon.com/docs/cli/link) (unless the directory is already linked). Linking writes a `.neon` file with your org, project, and branch. `init` then pulls the branch's environment variables (including `DATABASE_URL`) into `.env` if one exists, otherwise `.env.local`. Pass `--no-link` to set up agent tooling and `neon.ts` without linking a project; you can link later with `neon link`.

It can also write a [`neon.ts` config](https://neon.com/docs/cli/config) you can edit and apply with [`neon deploy`](https://neon.com/docs/cli/deploy). In a terminal, `init` asks whether to create it. Pass `--config` to create it without asking, `--no-config` to skip it, or `--services` to create it with specific services declared (which implies `--config`). Pass `--package-manager` (`npm`, `pnpm`, `yarn`, or `bun`) to choose which package manager installs the `neon.ts` dependencies.

When `init` creates a new `neon.ts`, it pulls environment variables once, after the file is written. If `neon.ts` declares only services that need no deploy (the AI Gateway or Functions), the pull includes all of them. If it declares Managed Better Auth, the Data API, Object Storage, or Realtime, `init` pulls Postgres (plus the AI Gateway and the scaffolded function's URL when declared), and [`neon deploy`](https://neon.com/docs/cli/deploy) provisions the rest and pulls their variables. With `--claimable`, `init` skips the pull when `neon.ts` declares services beyond Postgres.

When `init` writes a new `neon.ts` for a linked project, it lists next steps under `Next`. Preview the changes with [`neon config plan`](https://neon.com/docs/cli/config#plan), then apply them with [`neon deploy`](https://neon.com/docs/cli/deploy). It also suggests [`neon checkout dev --create`](https://neon.com/docs/cli/checkout) to work on a development branch once you've deployed. These steps appear even for the default Postgres-only `neon.ts`. For a claimable project, `init` lists `neon claim accept` instead, followed by the plan and deploy steps when `neon.ts` declares services beyond Postgres. If you skip `neon.ts` (for example, with `--no-config`) and the directory doesn't have one, `init` suggests [`neon config init`](https://neon.com/docs/cli/config#init) to create it later.

`--services realtime` declares [Realtime](https://neon.com/docs/realtime/overview) in `neon.ts`. `init` doesn't enable it on the branch: [`neon deploy`](https://neon.com/docs/cli/deploy) does, or you can run [`neon realtime enable`](https://neon.com/docs/cli/realtime#enable). The interactive service picker doesn't list Realtime, so pass `--services realtime` to declare it.

When `neon.ts` declares the [Data API](https://neon.com/docs/data-api/get-started), `init` checks the linked branch's Data API first. If it uses an external identity provider, `init` declares the [external form](https://neon.com/docs/reference/neon-ts#dataapi) (`authProvider: "external"`) instead of `dataApi: true`, so `neon deploy` doesn't enable Managed Better Auth. If `init` can't read the branch, for example without credentials, it declares `dataApi: true` with `auth: true`. It never starts a login to check.

## Options

| Option                          | Description                                                                                                                                                                                                                                                                       | Type    | Default | Required |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--agent`, `-a`                 | Coding agent to install into (repeatable). Skips agent selection. Values listed below                                                                                                                                                                                             | array   | —       |    No    |
| `--agent-setup`                 | Install Neon into coding agents. Use --no-agent-setup to skip. Plugin vs skills is inferred from --skill and MCP flags                                                                                                                                                            | boolean | `true`  |    No    |
| `--branch`, `--branch-id`       | Forwarded to link: branch name or ID to pin                                                                                                                                                                                                                                       | string  | —       |    No    |
| `--claimable`                   | Create a claimable project that expires in 72 hours unless claimed. Selects Custom                                                                                                                                                                                                | boolean | `false` |    No    |
| `--config`                      | Create neon.ts after linking. Use --no-config to skip. Omitted in Custom: you will be asked                                                                                                                                                                                       | boolean | —       |    No    |
| `--link`                        | Link a Neon project during setup. Use --no-link to skip without being asked                                                                                                                                                                                                       | boolean | `true`  |    No    |
| `--mcp-auth`                    | MCP authentication. Selects skills and MCP setup. oauth is neon mcp --oauth Possible values: `oauth`, `api-key`                                                                                                                                                                   | string  | —       |    No    |
| `--mcp-config-location`         | Where to configure the Neon MCP server: global (user config, same as neon mcp) or project (this directory, same as neon mcp --project). Selects skills and MCP setup Possible values: `global`, `project`                                                                         | string  | —       |    No    |
| `--mcp-project-scoped`          | Limit MCP tools to the linked project, same as neon mcp --project-id. Selects skills and MCP setup                                                                                                                                                                                | boolean | `false` |    No    |
| `--org-id`                      | Forwarded to link: organization ID to link to                                                                                                                                                                                                                                     | string  | —       |    No    |
| `--package-manager`             | Package manager for neon.ts dependencies. -y uses this without asking. Custom asks only when none is detected Possible values: `npm`, `pnpm`, `yarn`, `bun`                                                                                                                       | string  | —       |    No    |
| `--project-id`                  | Forwarded to link: existing project ID to link to                                                                                                                                                                                                                                 | string  | —       |    No    |
| `--project-name`                | Name for a new project, forwarded to link or to the claimable project                                                                                                                                                                                                             | string  | —       |    No    |
| `--region-id`                   | Region for a new project, forwarded to link or to the claimable project                                                                                                                                                                                                           | string  | —       |    No    |
| `--services`, `-s`, `--service` | Services to declare in neon.ts: postgres, auth, data-api, functions, object-storage, ai-gateway, realtime. Repeat the flag or comma-separate. postgres alone writes the starter policy; every branch has Postgres. Implies creating neon.ts. Cannot be combined with --no-config. | array   | —       |    No    |
| `--skill`                       | Neon skill to install (repeatable). Selects skills setup (not the plugin) and skips the skills picker. With MCP flags, also configures MCP. Values listed below                                                                                                                   | array   | —       |    No    |
| `--yes`, `-y`                   | Skip prompts. Alone: Recommended (detected agents, link when authenticated, default neon.ts). With --skill, MCP flags, --no-agent-setup, or --claimable: Custom using those flags                                                                                                 | boolean | `false` |    No    |

Pass `-y` (alias `--yes`) to run each step with its defaults instead of prompting. On its own, `-y` runs the recommended setup: it detects agents from your global agent configuration, the project folders, and the host CLI agent you're running inside, then installs the plugin globally for each detected agent that supports it, and skills and MCP for the rest. Run `neon init --help` to see which agents fall into each family. If it detects no agent, it writes the default skills in the current directory. `-y` links your only organization and project, or prints the IDs and exits when you have several (pass `--org-id`/`--project-id` to choose), and it never opens a browser.

Pass `--agent` (alias `-a`) to name the coding agents to set up, which skips both detection and the picker. It's repeatable (`neon init --agent cursor --agent claude-code`) and works with `-y`. Without skill or MCP flags, it installs the plugin, plus skills and MCP for any agent the plugin can't cover. Run `neon init --help` to see which agents each family supports. Passing `--agent` with no value returns an error.

Pass `--claimable` to create a [claimable project](https://neon.com/docs/reference/claimable-neon) that expires in 72 hours unless it's claimed. This selects the custom setup. The project goes in `aws-us-east-2` unless you add `--region-id`. `--claimable` can't be combined with `--no-link`, `--org-id`, `--project-id`, `--project-name`, or `--branch`.

## Run it non-interactively

Combine `-y` with any of those flags to set up without prompts, for example in CI or from an agent. Without a TTY, pass `-y` or enough flags to answer every question:

```bash
neon init -y --agent cursor
```

By default, `init` links to the project the directory is already linked to, and when it isn't linked yet, [`neon link`](https://neon.com/docs/cli/link) picks one interactively. To target a project without prompts, `init` forwards project-selection flags to `link`: pass `--project-id` (with `--org-id`) to link an existing project, or `--org-id`, `--project-name`, and `--region-id` to create and link a new one. Pass `--branch` to pin a branch.

```bash
# Existing project, fully non-interactive
neon init -y --agent cursor --project-id <project-id> --org-id <org-id>

# Create a new project and link it
neon init -y --agent cursor --org-id <org-id> --project-name my-app --region-id aws-us-east-2

# Custom setup: install the neon skill and configure MCP with OAuth in this directory
neon init -y --skill neon --mcp-auth oauth --mcp-config-location project
```

Authenticate without a browser by setting `NEON_API_KEY` or passing `--api-key`. Agents can find the IDs with `neon orgs list --output json` and `neon projects list --org-id <org-id> --output json`. To control `neon.ts` in the same run, add `--config`, `--no-config`, or `--services`.

When `-y` can't authenticate, it finishes every step it can and lists what's left under `Next`. With no credential at all, it skips the environment pull. If you also pass `--org-id`, `--project-id`, and `--branch`, it writes `.neon` without contacting Neon (like [`neon link --no-checks`](https://neon.com/docs/cli/link)), and Neon checks those IDs on the first command that reaches it. With fewer IDs, it skips linking and prints the `neon login` and `neon link` commands to run. A project-scoped or organization API key can link and pull, but it can't mint the API key the Neon MCP server uses. In that case, `init` configures MCP with OAuth instead. If you asked for `--mcp-auth api-key`, it skips MCP, finishes the other steps, and exits with an error that names the retry command.

## What gets created

The files created depend on the flags you pass. Each one is written by the command `init` runs, so see that command's page for details.

| Artifact                                              | Written by                                                                                                                                            | Scope                      |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `.neon` (org, project, and branch context)            | [`neon link`](https://neon.com/docs/cli/link)                                                                                                         | Project                    |
| `.env` or `.env.local` (`DATABASE_URL` and Neon vars) | [`neon link`](https://neon.com/docs/cli/link)                                                                                                         | Project                    |
| `neon.ts` (config-as-code policy)                     | [`neon config init`](https://neon.com/docs/cli/config)                                                                                                | Project                    |
| Agent skills, MCP config, or plugin                   | [`neon skills`](https://neon.com/docs/cli/skills) / [`neon mcp`](https://neon.com/docs/cli/mcp) / [`neon plugins`](https://neon.com/docs/cli/plugins) | User or project, per agent |

## Examples

Run `init` from your project root:

```bash
npx neon@latest init
```

Choose your agent setup, then pick a project to link. Linking writes the context. If you create a `neon.ts`, `init` writes it and then pulls your environment variables:

```text
Linked .neon
  Project         my-app (polished-snowflake-12345678)
  Branch          main
  Org             org-example-12345678

Creating neon.ts...
Installing Neon dependencies with npm...
Pulling Neon environment variables...
Pulled 5 Neon variables into .env.local from branch main (br-restless-wildflower-a1b2c3d4)
  Postgres        DATABASE_URL, DATABASE_URL_UNPOOLED
  Branch          NEON_BRANCH, NEON_BRANCH_ID
  Functions       NEON_FUNCTION_HOST_SUFFIX
```

After setup, restart your editor and ask your assistant to "Get started with Neon." The installed [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server) points your assistant to the right docs, so it can connect to your database and use Neon features as you build.

Install the Neon plugin for a specific agent and create a [claimable project](https://neon.com/docs/reference/claimable-neon). Naming an agent with `--agent` selects the custom setup, which installs the plugin at the project level:

```bash
neon init -y --claimable --agent cursor
```

<details>

<summary>Show output</summary>

```text
Installing the Neon plugin...
Installing the Neon plugin for Cursor (1/1)...
Plugins
Scope  Plugin         Agent   Status
user   neon-postgres  cursor  installed
Installed the Neon plugin (user).
Creating a claimable project...
Project ID            sweet-breeze-12345678
Branch ID             br-restless-wildflower-a1b2c3d4
Region ID             aws-us-east-2
State                 unclaimed
Project Expires At    2026-09-29T01:51:07.360Z
Granted Capabilities  postgres
Creating neon.ts...
Installing Neon dependencies with npm...
Pulling Neon environment variables...
Pulled 5 Neon variables into .env.local from branch main (br-restless-wildflower-a1b2c3d4)
  Postgres        DATABASE_URL, DATABASE_URL_UNPOOLED
  Branch          NEON_BRANCH, NEON_BRANCH_ID
  Functions       NEON_FUNCTION_HOST_SUFFIX

Neon setup complete.
--------------------

  Agents   Neon plugin: cursor
  Project  claimable
  Config   neon.ts created

Next:
  This project expires at 2026-09-29T01:51:07.360Z.
  To keep it, open the claim flow and sign in to Neon:
  neon claim accept
```

</details>

## Manual setup

To configure a specific agent without running `init`, or to register only the Neon MCP Server, see [Set up your AI agent](https://neon.com/docs/ai/agent-setup). To install only agent skills, use [`neon skills`](https://neon.com/docs/cli/skills); to install only the MCP server, use [`neon mcp`](https://neon.com/docs/cli/mcp).

--- [Document source](https://neon.com/docs/cli/inspect.md) ---

> Summary: The Neon CLI `neon inspect` command runs read-only diagnostic queries against a branch's Postgres, reporting on table and index sizes, unused indexes, locks, long-running and expensive queries, cache hit rates, autovacuum status, bloat, and replication. Use it to troubleshoot performance and understand what a database is doing without leaving the terminal.

# Neon CLI command: inspect

Run diagnostic queries against a branch's Postgres to check its health and configuration

Last updated: 2026-10-09

The `inspect` command runs a set of read-only diagnostic queries against a branch's Postgres and prints the results. Each query targets a common operational question, such as which tables are largest, which indexes go unused, what is holding locks, or how the cache is performing. Nothing is modified, so the command is safe to run against any branch.

Subcommands: [db](https://neon.com/docs/cli/inspect#db)

## neon inspect db

Run a single diagnostic query against a branch's Postgres. Pick the query with a subcommand, for example `neon inspect db table-sizes`.

```bash
neon inspect db <sub-command> [options]
```

| Option            | Description                                                                                                                                                                                                                                                | Type   | Default | Required |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--branch`        | Branch ID or name                                                                                                                                                                                                                                          | string | —       |    No    |
| `--database-name` | Database to inspect. Omit to cover every database the API lists for the branch. Ranking and row limits stay per database. One failing database fails the whole run. Compute-wide checks run once against the first listed database. Ignored with --db-url. | string | —       |    No    |
| `--db-url`        | Inspect any Postgres via a connection string, bypassing the Neon API (project/branch resolution is skipped)                                                                                                                                                | string | —       |    No    |
| `--project-id`    | Project ID                                                                                                                                                                                                                                                 | string | —       |    No    |
| `--role-name`     | Role name. Defaults to neondb\_owner, else the only role besides the Data API and Neon Auth roles                                                                                                                                                          | string | —       |    No    |

By default the command resolves the project, branch, database, and role from your [context](https://neon.com/docs/cli/link) and connects through the Neon API. Pass `--db-url` to inspect any Postgres directly from a connection string, which bypasses API resolution and lets you point `inspect` at a database outside Neon without being logged in to Neon.

Without `--role-name`, `inspect` connects as the same role as [`neon connection-string`](https://neon.com/docs/cli/connection-string): the branch's only role, or `neondb_owner` on branches with several roles. If there's no `neondb_owner`, it uses the only role left after skipping the Data API and Managed Better Auth roles (`authenticator`, `anonymous`, and `authenticated`).

When you omit `--database-name`, `inspect` covers every database on the branch and adds a `database` column so you can tell the rows apart. Pass `--database-name` to inspect a single database, which also scopes `locks` and `long-running-queries` to that database so lock and relation names resolve correctly. Database-scoped checks such as `table-sizes`, `locks`, and `outliers` run against each database, while compute-wide checks (`lfc-hit-rate`, `working-set`, and `replication-slots`) run once. If any database fails, the whole run fails, so pass `--database-name` to narrow to one when that happens. `--db-url` always inspects the single database in the connection string and never adds the `database` column.

Some queries read from Postgres statistics extensions. `outliers` and `calls` need [`pg_stat_statements`](https://neon.com/docs/extensions/pg_stat_statements), and `lfc-hit-rate` and `working-set` need the [`neon`](https://neon.com/docs/extensions/neon) extension. If a required extension is not installed, the command reports it instead of returning rows.

**Note:** On large fixed-size computes (18 CU and above), Neon disables the file cache and serves the [compute cache](https://neon.com/docs/extensions/neon#what-is-the-compute-cache) from Postgres `shared_buffers`, so `lfc-hit-rate` and `working-set` return empty or misleading results on those computes. Use the [Compute cache hit rate](https://neon.com/docs/introduction/monitoring-page#compute-cache-hit-rate) graph or run `SHOW shared_buffers` instead.

From an AI assistant, the same checks are available through the Neon MCP server's `inspect_database` tool. See [Database diagnostics](https://neon.com/docs/ai/neon-mcp-server#database-diagnostics).

Subcommands: [bloat](https://neon.com/docs/cli/inspect#db-bloat), [calls](https://neon.com/docs/cli/inspect#db-calls), [index-sizes](https://neon.com/docs/cli/inspect#db-index-sizes), [lfc-hit-rate](https://neon.com/docs/cli/inspect#db-lfc-hit-rate), [locks](https://neon.com/docs/cli/inspect#db-locks), [long-running-queries](https://neon.com/docs/cli/inspect#db-long-running-queries), [outliers](https://neon.com/docs/cli/inspect#db-outliers), [replication-slots](https://neon.com/docs/cli/inspect#db-replication-slots), [seq-scans](https://neon.com/docs/cli/inspect#db-seq-scans), [stalled-queries](https://neon.com/docs/cli/inspect#db-stalled-queries), [subscriptions](https://neon.com/docs/cli/inspect#db-subscriptions), [table-sizes](https://neon.com/docs/cli/inspect#db-table-sizes), [unused-indexes](https://neon.com/docs/cli/inspect#db-unused-indexes), [vacuum-stats](https://neon.com/docs/cli/inspect#db-vacuum-stats), [working-set](https://neon.com/docs/cli/inspect#db-working-set)

### neon inspect db table-sizes

Size of each table, including TOAST, largest first.

```bash
neon inspect db table-sizes
```

```text
Schema  Name       Size
public  events     16 MB
public  orders     4752 kB
public  customers  1616 kB
```

### neon inspect db index-sizes

Size of each index, largest first.

```bash
neon inspect db index-sizes
```

### neon inspect db unused-indexes

Non-unique, non-primary-key indexes with fewer than 50 scans, largest first. These are candidates for removal. Check the `Index Scans` column: an index that has never been scanned (`0`) while taking up space is a strong candidate to drop.

```bash
neon inspect db unused-indexes
```

```text
Table             Index                   Index Size  Index Scans
public.events     events_created_at_idx   1368 kB     0
public.orders     orders_customer_id_idx  1024 kB     2
public.customers  customers_email_idx     808 kB      0
public.orders     orders_status_idx       560 kB      20
```

### neon inspect db seq-scans

Number of sequential scans recorded against each table, highest first. A high count on a large table often points to a missing index.

```bash
neon inspect db seq-scans
```

### neon inspect db long-running-queries

Queries that have been running longer than five minutes. Run it to catch a runaway statement. When nothing qualifies, it says so instead of printing an empty table:

```bash
neon inspect db long-running-queries
```

```text
No long-running queries in any database.
```

### neon inspect db stalled-queries

Active queries running longer than 30 seconds, with their parallel workers, what each one is waiting on, and any queries blocking them. It runs compute-wide. When nothing qualifies, it says so instead of printing an empty table:

```bash
neon inspect db stalled-queries
```

```text
No active queries running longer than 30 seconds.
```

### neon inspect db locks

Locks currently held, with the query that acquired each one and its age. When writes are blocked, run this to find what is holding the lock.

```bash
neon inspect db locks
```

```text
No locks held in any database.
```

### neon inspect db stalled-queries

Active queries that have been running for at least 30 seconds, reported with their waits, blockers, parallel workers, query IDs, and query text. Where `long-running-queries` catches statements past a five-minute mark, this surfaces stalls sooner and shows what each backend is waiting on. Parallel workers are grouped with their leader process, and the `Blocking Pids` column shows which backends are holding others up. Run it during an incident to see what is running right now and what is blocking it.

```bash
neon inspect db stalled-queries
```

### neon inspect db outliers

The top 25 queries by cumulative execution time (`Total Exec Time`), with each query's share of the total (`Prop Exec Time`) and how often it ran (`Ncalls`). This ranks by total time spent, so a cheap query that runs constantly can outrank an expensive one that runs rarely. Needs the [`pg_stat_statements`](https://neon.com/docs/extensions/pg_stat_statements) extension.

```bash
neon inspect db outliers
```

<details>

<summary>Show output</summary>

```text
Total Exec Time  Prop Exec Time  Ncalls  Query
00:00:00.875831  57.0%           250     SELECT * FROM orders WHERE customer_id = $1
00:00:00.439406  28.6%           400     SELECT * FROM customers WHERE email = $1
00:00:00.220669  14.4%           15      SELECT status, count(*), sum(total_cents) FROM orders GROUP BY status
```

</details>

### neon inspect db calls

The top 25 queries by call count (`Ncalls`). Where `outliers` ranks by total time, this ranks by how often a query runs, so it highlights hot paths worth caching or batching even when each individual call is cheap. Needs the [`pg_stat_statements`](https://neon.com/docs/extensions/pg_stat_statements) extension.

```bash
neon inspect db calls
```

<details>

<summary>Show output</summary>

```text
Ncalls  Total Exec Time  Prop Exec Time  Query
400     00:00:00.439406  59.8%           SELECT * FROM customers WHERE email = $1
250     00:00:00.875831  37.4%           SELECT * FROM orders WHERE customer_id = $1
15      00:00:00.220669  2.2%            SELECT status, count(*), sum(total_cents) FROM orders GROUP BY status
```

</details>

### neon inspect db lfc-hit-rate

Compute cache hit rate, the share of reads served from your compute's cache instead of storage. A low or falling ratio means your working set no longer fits in the cache. Read it after the compute has handled some traffic, not on a freshly resumed one. Needs the [`neon`](https://neon.com/docs/extensions/neon) extension.

```bash
neon inspect db lfc-hit-rate
```

### neon inspect db working-set

Estimated working set size over several time windows, compared with the compute cache size. When `Exceeds LFC` is `no`, your recent data fits in cache. A `yes` means the working set has outgrown the cache, and a larger compute may help. Needs the [`neon`](https://neon.com/docs/extensions/neon) extension.

```bash
neon inspect db working-set
```

```text
Window  Working Set  LFC Size  Exceeds LFC
1m      48 MB        607 MB    no
5m      48 MB        607 MB    no
15m     48 MB        607 MB    no
1h      48 MB        607 MB    no
```

### neon inspect db vacuum-stats

Autovacuum status per table: last (auto)vacuum time, dead tuples, and the autovacuum threshold, ordered by dead tuples. Rising dead tuples with no recent autovacuum points at autovacuum falling behind.

```bash
neon inspect db vacuum-stats
```

**Note: Vacuum stats reset on auto-suspend**

Postgres resets these counters whenever the compute restarts, including after a scale-to-zero auto-suspend. On a freshly resumed compute they start near empty, so read them after the database has handled some real traffic.

### neon inspect db bloat

The top 25 tables by estimated wasted bytes. It needs no extension. The number is a statistical estimate, so use it to decide where to look, not as an exact measurement.

```bash
neon inspect db bloat
```

### neon inspect db replication-slots

Replication slots with their kind, status, client, restart and confirmed-flush LSNs, and lag. Check the lag and status columns to see how far each replica or subscriber is behind the primary.

```bash
neon inspect db replication-slots
```

### neon inspect db subscriptions

Per-table logical replication progress on this subscriber. Run it on a database with a subscription to see which tables are still copying and which have caught up. On other databases it reports that no subscriptions were found.

```bash
neon inspect db subscriptions
```

--- [Document source](https://neon.com/docs/cli/install.md) ---

> Summary: Install the Neon CLI (neon) with npm i -g neon@latest, or on macOS, Windows, or Linux via Homebrew, bun, or a standalone binary, with no-install options via npx or bunx. After installing, connect by running `neon login` for browser-based authentication, or set the NEON_API_KEY environment variable or pass --api-key per command. Vercel-Managed Integration users must use an API key because web auth requires a Neon-registered account.

# Neon CLI: Install and connect

Install the Neon CLI and connect with web auth or API key

Last updated: 2026-10-27

## Install

Install the Neon CLI globally with [npm](https://www.npmjs.com/package/neon):

```shell
npm i -g neon@latest
```

Requires [Node.js 20.19.0](https://nodejs.org/en/download/) or higher. The CLI is invoked as `neon`, and `neonctl` is an alias for `neon`.

<details>

<summary>Other install options</summary>

Homebrew, bun, and standalone binaries are also available. The Homebrew formula is named `neonctl`, so install commands use that name even though you run the CLI as `neon`.

**macOS**

**Install with [Homebrew](https://formulae.brew.sh/formula/neonctl)**

```bash
brew install neonctl
```

**Install with bun**

```bash
bun install -g neon
```

**macOS binary**

Download the binary. No installation required.

```bash
curl -sL https://github.com/neondatabase/neon-pkgs/releases/latest/download/neon-macos-x64 -o neon
```

Run the CLI from the download directory:

```bash
neon <command> [options]
```

**Windows**

**Install with bun**

```bash
bun install -g neon
```

**Windows binary**

Download the binary. No installation required.

```bash
curl -sL -O https://github.com/neondatabase/neon-pkgs/releases/latest/download/neon-win-x64.exe
```

Run the CLI from the download directory:

```bash
neon-win-x64.exe <command> [options]
```

**Linux**

**Install with bun**

```bash
bun install -g neon
```

**Linux binary**

Download the x64 or ARM64 binary, depending on your processor type. No installation required.

x64:

```bash
curl -sL https://github.com/neondatabase/neon-pkgs/releases/latest/download/neon-linux-x64 -o neon
```

ARM64:

```bash
curl -sL https://github.com/neondatabase/neon-pkgs/releases/latest/download/neon-linux-arm64 -o neon
```

Run the CLI from the download directory:

```bash
neon <command> [options]
```

You can also run the Neon CLI without installing it using **npx** or the `bun` equivalent, **bunx**:

```shell
# npx
npx neon <command>

# bunx
bunx neon <command>
```

</details>

### Upgrade

Upgrade using the method that matches how you installed the CLI. To check for the latest version, see the [Neon CLI **Releases** page](https://github.com/neondatabase/neon-pkgs/releases). To check your installed version, run:

```bash
neon --version
```

**Note: Node.js 20.19.0 is required to upgrade**

The current CLI requires Node.js 20.19.0 or higher. On an older version (such as Node.js 18), npm only warns about the engine mismatch when you install or upgrade, and then every `neon` command exits with `neon requires Node.js 20.19 or newer` and the version it found. If you're on an older version, [upgrade Node.js](https://nodejs.org/en/download/) before you upgrade the CLI.

**npm**

```shell
npm update -g neon
```

**Homebrew**

```bash
brew upgrade neonctl
```

**Binary**

To upgrade a [binary](https://github.com/neondatabase/neon-pkgs/releases) version, download the `latest` binary as described in the install instructions above, and replace your old binary with the new one.

In CI/CD tools like GitHub Actions, you can safely pin the Neon CLI to `latest`, as we prioritize stability for CI/CD processes.

**npm (recommended)**

In your GitHub Actions workflow, use the `latest` tag with `npm`:

```yaml
- name: Install Neon CLI
  run: npm install -g neon@latest
```

**Binary**

If you're downloading a binary, reference the latest release from the [Releases page](https://github.com/neondatabase/neon-pkgs/releases) using `curl` or `wget` in your workflow:

```yaml
- name: Install Neon CLI
  run: |
    curl -L https://github.com/neondatabase/neon-pkgs/releases/latest/download/neon-linux-x64 -o /usr/local/bin/neon
    chmod +x /usr/local/bin/neon
```

## Connect

The Neon CLI supports connecting via web authentication or API key.

### Web authentication

Run the following command to connect to Neon via web authentication:

```bash
neon login
```

The [neon login](https://neon.com/docs/cli/login) command launches a browser window where you can authorize the Neon CLI to access your Neon account. If you haven't authenticated previously, running any Neon CLI command launches the web authentication process automatically unless you've specified an API key.

**Note:** If you use Neon through the [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration), you must authenticate connections from the CLI client using a Neon API key (see below). The `neon login` command requires an account registered through Neon rather than Vercel.

### API key

To authenticate with a Neon API key, specify the `--api-key` option when running a Neon CLI command:

```bash
neon projects list --api-key <neon_api_key>
```

To avoid including `--api-key` with each command, export your API key to the `NEON_API_KEY` environment variable.

```bash
export NEON_API_KEY=<neon_api_key>
```

For information about obtaining a Neon API key, see [Creating API keys](https://neon.com/docs/manage/api-keys#creating-api-keys).

## Configure autocompletion

The Neon CLI supports autocompletion. See [Neon CLI commands: completion](https://neon.com/docs/cli/completion) to set it up.

--- [Document source](https://neon.com/docs/cli/ip-allow.md) ---

> Summary: The Neon CLI `ip-allow` command controls project-level IP allowlists with subcommands `list`, `add`, `remove`, and `reset`, supporting individual IP addresses, IP ranges, and CIDR notation. Use this page when you need to restrict database access to specific IPs from the command line, rather than through the Neon console. The `add` subcommand accepts a `--protected-only` flag to scope the allowlist to protected branches only.

# Neon CLI command: ip-allow

Manage the IP allowlist: list, add, remove, and reset allowed IPs

Last updated: 2026-09-18

The `ip-allow` command lists, adds, removes, and resets the IP allowlist for your Neon project. An allowlist can contain individual IP addresses, IP ranges, or [CIDR notation](https://neon.com/docs/reference/glossary#cidr-notation). For information about Neon's IP Allow feature, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

Subcommands: [add](https://neon.com/docs/cli/ip-allow#add), [list](https://neon.com/docs/cli/ip-allow#list), [remove](https://neon.com/docs/cli/ip-allow#remove), [reset](https://neon.com/docs/cli/ip-allow#reset)

The `--project-id` option is required only if your Neon account has more than one project and no project is set in your [context file](https://neon.com/docs/cli/link).

## neon ip-allow list

Lists the addresses in the IP allowlist.

```bash
neon ip-allow list [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

List the IP allowlist:

```bash
neon ip-allow list --project-id cold-grass-40154007
```

List the IP allowlist with the `--output` format set to `json`:

```bash
neon ip-allow list --project-id cold-grass-40154007 --output json
```

## neon ip-allow add

Adds IP addresses to the IP allowlist for your Neon project.

```bash
neon ip-allow add [ips...]
```

| Option             | Description                                                   | Type    | Default | Required |
| ------------------ | ------------------------------------------------------------- | ------- | ------- | :------: |
| `--protected-only` | If true, the list will be applied only to protected branches. | boolean | —       |    No    |
| `--project-id`     | Project ID                                                    | string  | —       |    No    |

Use `--protected-only` to apply the allowlist to [protected branches](https://neon.com/docs/guides/protected-branches) only. Use `--protected-only false` to remove this setting.

```bash
neon ip-allow add 192.0.2.3 --project-id cold-grass-40154007
```

## neon ip-allow remove

Removes IP addresses from the IP allowlist for your project.

```bash
neon ip-allow remove [ips...]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon ip-allow remove 192.0.2.3 --project-id cold-grass-40154007
```

## neon ip-allow reset

Resets the allowlist to the IP addresses you specify. If you specify no addresses, the currently defined IP addresses are removed.

```bash
neon ip-allow reset [ips...]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon ip-allow reset 192.0.2.1 --project-id cold-grass-40154007
```

--- [Document source](https://neon.com/docs/cli/link.md) ---

> Summary: Covers the usage of the `link` command in the Neon CLI to bind the current directory to a Neon project, including interactive and non-interactive workflows for CI, scripts, and AI agents.

# Neon CLI command: link

Link a directory to a Neon project and write a `.neon` context file

Last updated: 2026-10-09

The `link` command binds the current directory to a Neon project and writes a `.neon` context file. Once linked, commands you run here (or in any subdirectory) know which organization, project, and branch to use, so you don't repeat `--org-id` and `--project-id` every time.

`link` always pins a branch as part of that context. Pass `--branch` to choose one, or use [`checkout`](https://neon.com/docs/cli/checkout) to switch it later.

**Note: Behavior changed in Neon CLI 5.0.0**

Before 5.0.0, `link` wrote `orgId` and `projectId` but pinned a branch only when you passed `--branch`, so a `.neon` file could be incomplete. From 5.0.0, `link` always pins a branch, and `--no-checks` also requires `--branch`. In non-interactive scripts, pass `--branch` (or `-y` for the default branch).

**Tip: Prefer link over set-context**

For most workflows, use `neon link` instead of manually running `neon set-context --project-id ...`. The `link` command guides you through organization and project selection and ensures the context file is complete.

## Usage

```bash
neon link [options]
```

## Options

| Option                    | Description                                                                                                                                                                                                                                           | Type    | Default | Required |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--branch`, `--branch-id` | Branch name or ID to pin in the context (resolved to its name before writing).                                                                                                                                                                        | string  | —       |    No    |
| `--checks`                | Verify the org/project/branch exist (and resolve the org from the project) before writing. On by default; use --no-checks to write the context offline with no API calls — it then requires --org-id, --project-id, and --branch, and skips env pull. | boolean | `true`  |    No    |
| `--clear`                 | Remove the org/project/branch context (writes an empty context file) instead of linking.                                                                                                                                                              | boolean | `false` |    No    |
| `--config`                | Offer to create neon.ts after interactive linking. Use --no-config to skip the offer                                                                                                                                                                  | boolean | `true`  |    No    |
| `--env-pull`              | Pull the linked branch's Neon env vars (DATABASE\_URL, ...) into a local .env after linking. On by default; use --no-env-pull to skip, for example when injecting env at runtime with `neon-env run` (from `@neon/env`) or `neon dev`.                | boolean | `true`  |    No    |
| `--org-id`                | Organization ID to link to                                                                                                                                                                                                                            | string  | —       |    No    |
| `--params`                | JSON object with link parameters, e.g. '\{"orgId":"...","projectId":"..."}' or '\{"orgId":"...","projectName":"...","regionId":"..."}'. Flags take precedence over fields in --params.                                                                | string  | —       |    No    |
| `--project-id`            | Existing project ID to link to                                                                                                                                                                                                                        | string  | —       |    No    |
| `--project-name`          | Name for a new project to create and link to                                                                                                                                                                                                          | string  | —       |    No    |
| `--region-id`             | Region ID for a new project (e.g. aws-us-east-2). Required with --project-name.                                                                                                                                                                       | string  | —       |    No    |
| `--yes`, `-y`             | Skip prompts. Select the only organization and project, or print IDs and the flag to pass. Pin the default branch when several exist. Does not create a project unless --project-name and --region-id are set.                                        | boolean | `false` |    No    |

By default, linking pulls the linked branch's environment variables (such as `DATABASE_URL`) into `.env.local` (or `.env` if present). Use `--no-env-pull` to skip this step, for example when you inject environment variables at runtime instead.

After an interactive link, `link` also prompts you to create a [`neon.ts` config](https://neon.com/docs/cli/config) when the directory doesn't already have one, so you can manage the project's Neon setup as code. Accept the prompt to write `neon.ts`, or pass `--no-config` to skip it. This applies to interactive linking only; non-interactive runs never prompt.

## Interactive mode (default)

Run `neon link` with no flags for guided prompts:

```bash
neon link
```

```text filename="Output"
? Which organization would you like to link? ' Personal Org (org-abc123)
? Which project would you like to link? ' + Create new project
? Name for the new project: ' my-app
? Which region should the new project run in? ' AWS US East (Ohio) (aws-us-east-2)
Created project my-app in aws-us-east-2
Linked .neon
  Project         my-app (polished-snowflake-12345678)
  Branch          br-steep-math-aiu3vve7
  Org             org-abc123
```

## Non-interactive mode

Use flags or a `--params` JSON blob for scripts, CI, and AI agents:

```bash
# Link to an existing project (pin a branch, or pass -y for the default)
neon link --org-id org-abc123 --project-id polished-snowflake-12345678 --branch main

# Create a new project and link
neon link --org-id org-abc123 --project-name my-app --region-id aws-us-east-2

# Same payload, one JSON blob
neon link --params '{"orgId":"org-abc123","projectName":"my-app","regionId":"aws-us-east-2"}'
```

Flags take precedence over fields in `--params`.

Because `link` writes a complete context, a non-interactive run needs a branch: pass `--branch` (or `--branch-id`), or use `-y` to pin the project's default branch. `link` pins the only branch automatically when a project has just one.

Agents find the IDs with `neon orgs list --output json` and `neon projects list --org-id <org-id> --output json`, then link with `--project-id` (or create a project with `--org-id`, `--project-name`, and `--region-id`).

## The `.neon` context file

`link` is a thin wrapper around [`set-context`](https://neon.com/docs/cli/set-context): both write to the same `.neon` file, so anything `link` can write, `set-context` can write too. `link` writes the file into the current working directory by default. If an existing `.neon` is found in any parent directory, that file is reused, so commands run from a subdirectory of a linked project still pick up the project's context. To pin the location explicitly, pass the global `--context-file <path>` option. See [Using a named context file](https://neon.com/docs/cli/set-context#using-a-named-context-file).

Example `.neon` file:

```json
{
  "orgId": "org-abc123",
  "projectId": "polished-snowflake-12345678",
  "branch": "br-steep-math-aiu3vve7"
}
```

The first time a `.neon` file is created, the CLI adds `.neon` to `.gitignore` in that folder so local project settings are not committed by accident. If you want to commit `.neon` and share context with your team, remove the entry from `.gitignore`. The CLI doesn't re-add it when updating an existing file.

**Note:** Neon does not save confidential information to the context file (for example, auth tokens). You can safely commit this file to your repository or share it with others.

## Organization-scoped API keys

Organization-scoped API keys (those created at the organization level rather than the user level) cannot list user organizations or call the regions endpoint. `link` handles this transparently:

- If the API key is org-scoped and at least one project already exists in the org, the CLI auto-detects the `org_id` from the first project.
- When the regions endpoint is not allowed, `link` falls back to a built-in static region list.

--- [Document source](https://neon.com/docs/cli/login.md) ---

> Summary: The `neon login` command authenticates the Neon CLI to a Neon account by launching a browser OAuth flow that saves credentials to `~/.config/neon/credentials.json`. Use this command when setting up the CLI for the first time or when not using an API key. `neon auth` is a legacy alias for `neon login`. Vercel-Managed Integration users must authenticate via API key (`--api-key` or `NEON_API_KEY`) instead. The CLI resolves authentication in priority order: `--api-key` flag, then `NEON_API_KEY` env var, then the credentials file, then triggers browser login if none are found.

# Neon CLI command: login

Authenticate to Neon via browser or API key and manage credentials

Last updated: 2026-10-09

The `login` command authenticates you to Neon. `neon auth` is a legacy alias for `neon login`.

## Usage

```bash
neon login [options]
```

The command launches a browser window where you authorize the Neon CLI to access your Neon account. Your credentials are then saved locally to `credentials.json`:

```text filename="Output"
~/.config/neon/credentials.json
```

**Note:** If you use Neon through the [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration), authenticate with a Neon API key instead (see below). The `neon login` command requires an account registered through Neon rather than Vercel.

Instead of running `neon login`, you can provide an API key with the global `--api-key` option or the `NEON_API_KEY` environment variable. See [Global options](https://neon.com/docs/cli#global-options).

**Info:**

The Neon CLI resolves authentication in this order:

- The `--api-key` option, if provided.
- The `NEON_API_KEY` environment variable, if set.
- The `credentials.json` file created by `neon login`.
- If none are found, the CLI starts the `neon login` web authentication flow. `neon me` is the exception: it reports that you're signed out instead.

## Options

| Option      | Description                                                                                                               | Type    | Default | Required |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--keyring` | Store the credential in the OS keyring. Per profile; a later login without the flag stays there. See `neon profile list`. | boolean | —       |    No    |

Pass `--keyring` to store the credential in your operating system's keyring instead of the `credentials.json` file. The choice is saved per profile, so once set, `neon login` keeps using the keyring for that profile even without the flag. Along with this option, `login` accepts the [global options](https://neon.com/docs/cli#global-options).

--- [Document source](https://neon.com/docs/cli/logs.md) ---

> Summary: The Neon CLI `neon logs` command reads the logs a branch's services emit. Today that covers Neon Functions and Object Storage; Postgres compute logs are coming. Query records over a time window, filter by source, severity, or OpenTelemetry attributes, run raw LogQL, list which fields and values a branch reports, and call the branch's Loki-compatible read API. Logs are available in AWS US East (Ohio), US East (N. Virginia), Europe (Frankfurt), and Asia Pacific (Singapore).

# Neon CLI command: logs

Query the logs a branch's services emit

Last updated: 2026-11-06

The `logs` command reads the logs a branch's services emit. Today that covers Neon Functions and Object Storage; Postgres compute logs are coming. Query records over a time window, filter by source, severity, or OpenTelemetry attribute, and list which fields and values a branch reports so you can build precise filters. For output in Loki's format, use [`neon logs loki`](https://neon.com/docs/cli/logs#loki).

Logs are currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`), so your project must be in one of these regions to use them. Support is expanding toward [all regions](https://neon.com/docs/introduction/regions).

Every subcommand resolves the project and branch from your [context](https://neon.com/docs/cli/link). Pass `--project-id` and `--branch` to target a specific branch instead.

Subcommands: [field-values](https://neon.com/docs/cli/logs#field-values), [fields](https://neon.com/docs/cli/logs#fields), [loki](https://neon.com/docs/cli/logs#loki), [query](https://neon.com/docs/cli/logs#query)

## neon logs query

Query log records over a time window. By default it returns the last hour of logs on the default branch, newest first.

```bash
neon logs query [options]
```

| Option               | Description                                                                                                                                                                                                              | Type   | Default | Required |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------ | ------- | :------: |
| `--body-contains`    | Match the case-sensitive rendered message. Structured bodies are rendered as compact JSON.                                                                                                                               | string | —       |    No    |
| `--cursor`           | Pagination cursor returned as next\_cursor by a previous call. Repeat the same time range and filters.                                                                                                                   | string | —       |    No    |
| `--end-time`         | Exclusive end of the window (RFC 3339). Defaults to the current time.                                                                                                                                                    | string | —       |    No    |
| `--limit`            | Maximum number of records to return per page (1-1000)                                                                                                                                                                    | number | `100`   |    No    |
| `--logql`            | Raw LogQL expression (stream selectors and line filters only). Replaces the structured filters; the window, --limit, --sort-order and --cursor still apply.                                                              | string | —       |    No    |
| `--minimum-severity` | Only records at or above this severity. Combines with --severity-text. If Neon reports that this filter is unsupported, use --severity-text instead. Possible values: `trace`, `debug`, `info`, `warn`, `error`, `fatal` | string | —       |    No    |
| `--scope-name`       | Match the OpenTelemetry instrumentation scope name exactly                                                                                                                                                               | string | —       |    No    |
| `--service-name`     | Match the OpenTelemetry service.name resource attribute exactly                                                                                                                                                          | string | —       |    No    |
| `--severity-text`    | Match the OpenTelemetry severity text exactly. Run `neon logs field-values severity_text` to discover the values present.                                                                                                | string | —       |    No    |
| `--since`            | Length of the window, ending at --end-time or now. Defaults to 1h; the maximum window is 7d. Mutually exclusive with --start-time.                                                                                       | string | —       |    No    |
| `--sort-order`       | Order records by timestamp. Defaults to desc (newest first). Possible values: `asc`, `desc`                                                                                                                              | string | —       |    No    |
| `--source`           | Only records emitted by this service Possible values: `function`, `storage`, `pg_endpoint`                                                                                                                               | string | —       |    No    |
| `--start-time`       | Inclusive start of the window (RFC 3339, e.g. 2025-01-01T00:00:00Z). The maximum window is 7d. Mutually exclusive with --since.                                                                                          | string | —       |    No    |
| `--trace-id`         | Match records carrying this trace ID (32 lowercase hex digits)                                                                                                                                                           | string | —       |    No    |
| `--branch`           | Branch ID or name                                                                                                                                                                                                        | string | —       |    No    |
| `--project-id`       | Project ID                                                                                                                                                                                                               | string | —       |    No    |

Bound the window with `--since` (a duration like `30m` or `1h`, ending at `--end-time` or now) or with an explicit `--start-time`/`--end-time` pair. `--since` and `--start-time` are mutually exclusive, and the maximum window is 7 days.

The structured content filters (`--source`, `--service-name`, `--scope-name`, `--severity-text`, `--body-contains`, and `--trace-id`) combine with each other. Passing `--logql` replaces all of them with a raw [LogQL](https://grafana.com/docs/loki/latest/query/) expression (stream selectors and line filters only); the window, `--limit`, `--sort-order`, and `--cursor` still apply.

`--source` accepts `function`, `storage`, and `pg_endpoint`. Only `function` and `storage` return records today; `pg_endpoint` (Postgres compute) is accepted but comes back empty until Postgres logs ship.

Filter by severity with `--severity-text`, which matches the exact, case-sensitive value a record carries (for example `ERROR` or `INFO`, uppercase). Severities vary by source, so a filter can legitimately return nothing. Storage logs take their level from the HTTP status (`WARN` for 4xx, `ERROR` for 5xx, `INFO` otherwise), so `--source storage --severity-text ERROR` returns only server errors. Run `neon logs field-values severity_text` to see the values a branch actually reports before filtering. `--minimum-severity` (match a level and everything above it) is not supported by the branch log backend; use `--severity-text` for an exact match instead.

```bash
neon logs query --since 30m
```

Filter function errors on a specific branch:

```bash
neon logs query --branch main --source function --severity-text ERROR
```

Read one function's logs. A function's service name is `neon-function/<slug>`:

```bash
neon logs query --source function --service-name neon-function/hello
```

Use a raw LogQL selection instead of the structured filters:

```bash
neon logs query --since 1h --logql '{entity_type="function"} |= "timeout"'
```

When more records match than fit in one page, the command reports a pagination cursor on stderr. Re-run with the same window and filters plus `--cursor=<value>` to fetch the next page.

## neon logs fields

List the log fields a branch reports. Pass any of these field names to `neon logs field-values` to see the values it carries.

```bash
neon logs fields [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

## neon logs field-values

List the distinct values a single field carries over a time window, so you know what to filter on with `neon logs query`. By default it looks back six hours.

```bash
neon logs field-values <field> [options]
```

| Option         | Description                                                                                                                        | Type   | Default | Required |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--end-time`   | Exclusive end of the window (RFC 3339). Defaults to the current time.                                                              | string | —       |    No    |
| `--limit`      | Maximum number of distinct values to return (1-1000)                                                                               | number | —       |    No    |
| `--since`      | Length of the window, ending at --end-time or now. Defaults to 6h; the maximum window is 7d. Mutually exclusive with --start-time. | string | —       |    No    |
| `--source`     | Only consider records emitted by this service Possible values: `function`, `storage`, `pg_endpoint`                                | string | —       |    No    |
| `--start-time` | Inclusive start of the window (RFC 3339, e.g. 2025-01-01T00:00:00Z). The maximum window is 7d. Mutually exclusive with --since.    | string | —       |    No    |
| `--branch`     | Branch ID or name                                                                                                                  | string | —       |    No    |
| `--project-id` | Project ID                                                                                                                         | string | —       |    No    |

Show the service names seen in the last six hours:

```bash
neon logs field-values service_name --since 6h
```

## neon logs loki

Call the branch's [Loki-compatible read API](https://neon.com/docs/cli/logs#loki-read-api) and print its JSON response unchanged. Lines come back grouped by their stream labels, with nanosecond timestamps, where [`neon logs query`](https://neon.com/docs/cli/logs#query) returns one record per line rounded to the second. Use `neon logs loki` when the order of lines within a second matters or a tool expects Loki output. You can also use it to try a LogQL selector before you point a Loki client at the endpoint. For readable tables, structured filters, and cursor pagination, use `neon logs query`.

```bash
neon logs loki [query] [options]
```

| Option         | Description                                                                                                                                        | Type   | Default       | Required |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------- | :------: |
| `--branch`     | Branch ID or name (defaults to the project's default branch)                                                                                       | string | —             |    No    |
| `--direction`  | Timestamp order (query\_range only): forward (oldest first) or backward (newest first) Possible values: `forward`, `backward`                      | string | —             |    No    |
| `--end`        | Window end as RFC 3339 or Unix nanoseconds (kept as a string). Defaults to now.                                                                    | string | —             |    No    |
| `--endpoint`   | Read endpoint: query\_range, labels, or label/\<name>/values                                                                                       | string | `query_range` |    No    |
| `--limit`      | Maximum number of log lines (query\_range only); the server enforces its cap                                                                       | number | —             |    No    |
| `--project-id` | Project ID                                                                                                                                         | string | —             |    No    |
| `--since`      | Lookback window as a positive Go duration, e.g. 30m or 24h. Defaults to 1h for queries and 6h for label values. Explicit --start takes precedence. | string | —             |    No    |
| `--start`      | Window start as RFC 3339 or Unix nanoseconds (kept as a string)                                                                                    | string | —             |    No    |

The default endpoint, `query_range`, needs a LogQL query. `--endpoint labels` and `--endpoint label/<name>/values` list labels and their values; for these, the query is optional and can only be a stream selector. Neon supports stream selectors and line filters, and rejects metric queries and parser stages. The window can be at most 168 hours. Output is JSON or YAML only.

Each value in a range result is a `[timestamp, line]` pair, with the timestamp as a nanosecond string. There's no cursor: a result that reaches `--limit`, or the server's cap of 10,000 lines, may be incomplete. Narrow the window or the selector to get everything.

List the services that logged on the branch in the last six hours:

```bash
neon logs loki --endpoint label/service_name/values --since 6h
```

Query function log lines that contain `invoke end`:

```bash
neon logs loki '{entity_type="function"} |= "invoke end"' --since 6h --limit 2
```

<details>

<summary>Show output</summary>

```json
{
  "status": "success",
  "data": {
    "resultType": "streams",
    "result": [
      {
        "stream": {
          "entity_type": "function",
          "scope_name": "neon.function.request",
          "service_name": "neon-function/todos",
          "severity_text": "INFO"
        },
        "values": [
          [
            "1793993911665404000",
            "invoke end"
          ],
          [
            "1793993910924177000",
            "invoke end"
          ]
        ]
      }
    ]
  }
}
```

</details>

## Loki-compatible read API

The same branch logs are also readable over HTTP through a Loki-compatible endpoint, for tools that speak the [Loki](https://grafana.com/docs/loki/latest/reference/loki-http-api/) query API directly rather than through the CLI. [`neon logs loki`](https://neon.com/docs/cli/logs#loki) calls the same endpoints from the terminal. Authenticate with a Neon API key as a bearer token, against this branch-scoped base URL:

```text
https://console.neon.tech/telemetry/v1/projects/{project_id}/branches/{branch_id}/loki
```

It exposes a read-only subset of the Loki HTTP API:

- `GET /api/v1/query_range`: query log lines over a window. Supports LogQL stream selectors and line filters, `since` or `start`/`end`, `limit`, and `direction`. It does not support aggregations, parsers, or formatting stages.
- `GET /api/v1/labels`: list the available stream labels (for example `entity_type`, `service_name`, `severity_text`).
- `GET /api/v1/label/{name}/values`: list the values a label carries (for example `entity_type` returns `function` and `storage`).

```bash
curl "https://console.neon.tech/telemetry/v1/projects/$PROJECT_ID/branches/$BRANCH_ID/loki/api/v1/labels" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

The stream label is `entity_type` (not `--source`), so a LogQL selector reads `{entity_type="function"}`. This is a read-only subset, not a push endpoint or a complete Loki deployment. A Loki client that builds its own paths may need a different root: a Grafana data source, for example, appends `/loki/api/v1` to whatever URL it is given. Confirm the data-source URL against this base rather than pasting it verbatim.

Like the CLI, this API reads logs only on branches in a supported region: AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward all regions. A branch in any other region returns `404`.

--- [Document source](https://neon.com/docs/cli/mcp.md) ---

> Summary: The Neon CLI `mcp` command installs the [Neon MCP Server](/docs/ai/neon-mcp-server) into your coding agents by writing their MCP config for you. Run it with no flags for an interactive walkthrough, or pass flags to skip the prompts and script the install. It handles the server URL, authentication, and which tools each agent gets.

# Neon CLI command: mcp

Install the Neon MCP Server into your coding agents

Last updated: 2026-11-03

The `mcp` command installs the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server) into your coding agents by writing their MCP config for you. It points each agent at the hosted server (`https://mcp.neon.tech/mcp`), sets up authentication, and can narrow which tools the agent sees.

Run `neon mcp` with no flags for an interactive walkthrough: it asks whether to write global or project-level config, which detected agents to install into, and whether to authenticate with a minted API key or OAuth, then shows you what it will do before writing anything. Pass flags to skip the prompts and run it non-interactively, which is what you want in scripts or a headless environment.

**mcp vs init:**

For the full setup, use [`neon init`](https://neon.com/docs/cli/init). For just one piece: [`neon skills`](https://neon.com/docs/cli/skills) (skills), [`neon plugins`](https://neon.com/docs/cli/plugins) (skills and MCP), or `neon mcp` (MCP server).

## Usage

```bash
neon mcp [options]
```

## Options

| Option                      | Description                                                                                                                                                                  | Type    | Default | Required |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--agent`, `-a`             | Coding agent to install into (repeatable). Skips the agent picker. Values listed below                                                                                       | array   | —       |    No    |
| `--category`                | MCP tool category (repeatable or comma-separated). Default: all. Values listed below                                                                                         | array   | —       |    No    |
| `--oauth`                   | Write the server URL only. The agent prompts for Neon sign-in on first use. No CLI login, no API key minted. Skips the auth question                                         | boolean | `false` |    No    |
| `--project`                 | Write project-level MCP config. Skips the config-location question. A linked project-folder install may still pin a project and scope a newly minted key                     | boolean | `false` |    No    |
| `--project-id`              | Pin MCP tools to one Neon project (?projectId=). A newly minted API key is limited to that project. A linked project-folder install asks the same when you pick API-key auth | string  | —       |    No    |
| `--read-only`, `--readonly` | Restrict MCP tools to read-only (?readonly=true). Not prompted. Does not change the minted key                                                                               | boolean | `false` |    No    |
| `--yes`, `-y`               | Skip prompts. Defaults listed below. --agent, --project, --oauth, --read-only, --project-id and --category still apply                                                       | boolean | `false` |    No    |

### Authentication

By default, `mcp` mints a new Neon API key and writes it into each agent's config. Minting requires you to already be signed in, so run [`neon login`](https://neon.com/docs/cli/login) first or pass `--api-key`. If you aren't authenticated, the command stops and tells you to sign in, pass `--api-key`, or use `--oauth`.

**Warning: Minted keys are account-wide by default**

By default a minted API key reaches everything your account can access, in every organization. Pass `--project-id` to limit a newly minted key to a single project instead (see [Scoping the tools](https://neon.com/docs/cli/mcp#scoping-the-tools)). The command prints the key's id when it mints one. Revoke it with [`neon api-keys revoke <id>`](https://neon.com/docs/cli/api-keys).

To install without minting a key, pass `--oauth`. This writes the server URL only, and the agent prompts you to sign in to Neon on first use. When `mcp` finds a Neon API key already configured for an agent, it reuses that key instead of minting a new one.

### Choosing agents

Without `--agent`, the interactive command detects installed agents and lets you pick from them. In non-interactive mode, `-y` installs into every detected agent. Pass `--agent <name>` (repeatable) to name agents explicitly and skip the picker.

The supported agents are `antigravity`, `cline`, `cline-cli`, `claude-code`, `codex`, `cursor`, `factory-droid`, `fx`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `hermes`, `junie`, `kilo-code`, `kimi-code`, `kiro-cli`, `mcporter`, `opencode`, `pi`, `vscode`, `windsurf`, and `zed`. A few names also accept aliases (`claude` for `claude-code`, `copilot` for `vscode`, `gemini` for `gemini-cli`). Passing an unknown agent stops the command and prints the current supported list. A supported agent that can't take the chosen config (for example, one with no project-level config file when you pass `--project`) is reported and skipped.

### Scoping the tools

By default the server exposes every MCP tool. Use these flags to narrow what an agent can do:

- `--read-only` hides the write tools by adding `?readonly=true` to the server URL.
- `--category <name>` limits tools to one or more categories (repeatable, or comma-separated). Categories are `projects`, `branches`, `endpoints`, `snapshots`, `schema`, `querying`, `neon_auth`, `data_api`, `observability`, `docs`, `functions`, `storage`, and `realtime`. The flag currently accepts only `projects`, `branches`, `schema`, `querying`, `neon_auth`, `data_api`, `observability`, and `docs`. For the other categories, add `?category=<name>` to the server URL in your agent's config yourself (see [Category filtering](https://neon.com/docs/ai/neon-mcp-server#category-filtering)).
- `--project-id <id>` pins the tools to a single Neon project with `?projectId=`, and limits a newly minted key to that project.

`--read-only` and `--category` shape the server URL only; they don't change a key's scope, and neither does reusing an already-configured key.

### Global vs project config

By default `mcp` writes global (per-user) agent config. Pass `--project` to write project-level config in the current directory instead, so the setup travels with the repository. If a project-level config file is tracked by git, the command refuses to write an API key into it. Use `--oauth` in that case, or untrack the file first.

## Examples

Run the interactive install. It walks you through config location, agents, and authentication, then asks you to confirm:

```bash
neon mcp
```

Install non-interactively into every detected agent, using global config. It reuses an API key already configured for an agent, or mints a new one (you must be signed in to mint):

```bash
neon mcp -y
```

Install without minting a key. Each agent prompts you to sign in to Neon on first use:

```bash
neon mcp --oauth
```

Install into specific agents only:

```bash
neon mcp --agent cursor --agent claude-code
```

Write project-level config that travels with the repository. Here, `--oauth` skips minting a key and `--agent` names the target directly, so the command runs without prompts:

```bash
neon mcp --oauth --project --agent cursor
```

```text
Wrote /home/user/my-app/.cursor/mcp.json
URL: https://mcp.neon.tech/mcp
MCP
Agent   Status
cursor  installed
The agent will prompt for Neon sign-in on first use.
```

Give the agent read-only access:

```bash
neon mcp --read-only
```

Limit the agent to schema and querying tools:

```bash
neon mcp --category querying --category schema
```

Pin the tools to one project and limit the minted key to it:

```bash
neon mcp --project-id cold-grass-40154007
```

--- [Document source](https://neon.com/docs/cli/me.md) ---

> Summary: The `neon me` CLI command prints the authenticated user's login, email, name, and credential source in the default table output. Use it to confirm which account is active and how it's authenticated. JSON output (`-o json`) exposes additional fields, such as the account id, plan, and linked auth accounts.

# Neon CLI command: me

View the authenticated user and login details

Last updated: 2026-10-09

The `me` command shows information about the authenticated Neon CLI user: login, email, name, and how you're authenticated (the credential source, such as `OAuth` or an API key, and the profile in use).

## Usage

```bash
neon me [options]
```

## Options

Takes only the [global options](https://neon.com/docs/cli#global-options).

## Examples

```bash
neon me
```

```text filename="Output"
Login           sally
Email           sally@example.com
Name            Sally Smith
Authentication  OAuth (profile DEFAULT)
```

When you're signed out, `me` doesn't start a browser sign-in. It prints a notice to stderr and exits with status `1`, so scripts and agents can run `neon me` as a sign-in check:

```text filename="Output"
Not signed in: profile "DEFAULT" has no stored credential. Run `neon login --profile DEFAULT` to sign in, or use an API key with --api-key or NEON_API_KEY.
```

Show details with `--output json`, which includes data omitted from the `table` output:

```bash
neon me -o json
```

<details>

<summary>Show output</summary>

```json
{
  "active_seconds_limit": 0,
  "auth_accounts": [
    {
      "email": "sally@example.com",
      "image": "",
      "login": "sally",
      "name": "Sally Smith",
      "provider": "google"
    }
  ],
  "email": "sally@example.com",
  "id": "8a9f604e-d04e-1234-baf7-e78909a5d123",
  "image": "",
  "login": "sally",
  "name": "Sally Smith",
  "last_name": "",
  "projects_limit": 0,
  "branches_limit": 0,
  "max_autoscaling_limit": 0,
  "plan": "free"
}
```

</details>

The `active_seconds_limit`, `projects_limit`, `branches_limit`, and `max_autoscaling_limit` fields report `0`. These are account-level limits from before Neon moved to organizations; project and branch quotas are now governed by your organization, not your user account.

--- [Document source](https://neon.com/docs/cli/neon-auth.md) ---

> Summary: The Neon CLI `neon neon-auth` command manages Managed Better Auth on a database branch from the terminal. Use `enable`, `status`, and `disable` to provision, inspect, or remove Managed Better Auth, and the `oauth-provider` subcommands to add, update, or delete Google, GitHub, Vercel, Microsoft, and Apple OAuth providers. The `domain` subcommands manage trusted redirect domains, including `allow-localhost` settings for local development. The `config` subcommands cover email and password authentication, the email provider, the organization plugin, webhooks, and the OAuth server, and `oauth-client` manages that server's clients, while `plugins` and `user` let you inspect plugin configurations and manage auth users.

# Neon CLI command: neon-auth

Manage Managed Better Auth from the CLI

Last updated: 2026-10-30

The `neon-auth` command manages [Managed Better Auth](https://neon.com/docs/auth/overview) on a database branch from the terminal. You can enable or disable Managed Better Auth, configure OAuth providers, trusted domains, email settings, and webhooks, and manage auth users.

Subcommands: [config](https://neon.com/docs/cli/neon-auth#config), [disable](https://neon.com/docs/cli/neon-auth#disable), [domain](https://neon.com/docs/cli/neon-auth#domain), [enable](https://neon.com/docs/cli/neon-auth#enable), [oauth-client](https://neon.com/docs/cli/neon-auth#oauth-client), [oauth-provider](https://neon.com/docs/cli/neon-auth#oauth-provider), [plugins](https://neon.com/docs/cli/neon-auth#plugins), [status](https://neon.com/docs/cli/neon-auth#status), [user](https://neon.com/docs/cli/neon-auth#user)

If `--project-id` or `--branch` are omitted, the CLI resolves them from your [context file](https://neon.com/docs/cli/link), auto-selects when there is only one option, and otherwise asks you to pass the flag.

## Enable and status

### neon neon-auth enable

Provisions Managed Better Auth on the current branch.

```bash
neon neon-auth enable [options]
```

| Option            | Description                        | Type   | Default | Required |
| ----------------- | ---------------------------------- | ------ | ------- | :------: |
| `--database-name` | Database name to use for auth data | string | —       |    No    |
| `--branch`        | Branch ID or name                  | string | —       |    No    |
| `--project-id`    | Project ID                         | string | —       |    No    |

```bash
neon neon-auth enable
```

### neon neon-auth status

Shows whether Managed Better Auth is configured on the branch and displays the current connection details.

```bash
neon neon-auth status [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth status
```

### neon neon-auth disable

Removes Managed Better Auth from the branch.

```bash
neon neon-auth disable [options]
```

| Option          | Description                                                        | Type    | Default | Required |
| --------------- | ------------------------------------------------------------------ | ------- | ------- | :------: |
| `--delete-data` | Permanently delete all Neon Auth data and schema from the database | boolean | `false` |    No    |
| `--branch`      | Branch ID or name                                                  | string  | —       |    No    |
| `--project-id`  | Project ID                                                         | string  | —       |    No    |

**Important:** The `--delete-data` option permanently deletes all Managed Better Auth data and schema from the database. This can't be undone.

Remove Managed Better Auth from the branch and delete its data:

```bash
neon neon-auth disable --delete-data
```

## OAuth providers

The `oauth-provider` subcommands manage the OAuth providers (`google`, `github`, `vercel`, `microsoft`, and `apple`) for the branch.

Subcommands: [add](https://neon.com/docs/cli/neon-auth#oauth-provider-add), [delete](https://neon.com/docs/cli/neon-auth#oauth-provider-delete), [list](https://neon.com/docs/cli/neon-auth#oauth-provider-list), [update](https://neon.com/docs/cli/neon-auth#oauth-provider-update)

### neon neon-auth oauth-provider list

Lists the OAuth providers configured for the branch.

```bash
neon neon-auth oauth-provider list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth oauth-provider list
```

### neon neon-auth oauth-provider add

Adds an OAuth provider.

```bash
neon neon-auth oauth-provider add [options]
```

| Option                       | Description                                                                                                                                                                      | Type   | Default | Required |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--apple-key-id`             | Key ID of the Sign in with Apple private key (apple only). Sent together with a new apple client secret, and only with one                                                       | string | —       |    No    |
| `--apple-team-id`            | Apple Developer Team ID (apple only)                                                                                                                                             | string | —       |    No    |
| `--microsoft-tenant-id`      | Tenant ID for the microsoft provider: common, organizations, consumers, a tenant GUID, or a domain                                                                               | string | —       |    No    |
| `--oauth-client-id`          | OAuth client ID from your provider app. For apple, the Services ID. Omit to use Neon's shared OAuth app, where one exists; microsoft and apple always need your own credentials. | string | —       |    No    |
| `--oauth-client-secret`      | OAuth client secret from your provider app. Omit to use Neon's shared OAuth app, where one exists; microsoft and apple always need your own credentials.                         | string | —       |    No    |
| `--oauth-client-secret-file` | Read the OAuth client secret from a file, for example the apple .p8 private key                                                                                                  | string | —       |    No    |
| `--provider-id`              | OAuth provider ID. Supported values: google, github, vercel, microsoft, apple                                                                                                    | string | —       |    Yes   |
| `--branch`                   | Branch ID or name                                                                                                                                                                | string | —       |    No    |
| `--project-id`               | Project ID                                                                                                                                                                       | string | —       |    No    |

Add the Google OAuth provider with your own credentials:

```bash
neon neon-auth oauth-provider add --provider-id google --oauth-client-id <client-id> --oauth-client-secret <client-secret>
```

Add Apple with the `.p8` key file, Team ID, and Key ID:

```bash
neon neon-auth oauth-provider add --provider-id apple --oauth-client-id <services-id> --oauth-client-secret-file AuthKey_XXXXXXXXXX.p8 --apple-team-id <team-id> --apple-key-id <key-id>
```

Add Microsoft, optionally restricted to a tenant:

```bash
neon neon-auth oauth-provider add --provider-id microsoft --oauth-client-id <client-id> --oauth-client-secret <client-secret> --microsoft-tenant-id <tenant>
```

See [Set up OAuth](https://neon.com/docs/auth/guides/setup-oauth) for the provider-side setup.

### neon neon-auth oauth-provider update

Updates the credentials for an existing OAuth provider.

```bash
neon neon-auth oauth-provider update [options]
```

| Option                       | Description                                                                                                                                                                      | Type   | Default | Required |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--apple-key-id`             | Key ID of the Sign in with Apple private key (apple only). Sent together with a new apple client secret, and only with one                                                       | string | —       |    No    |
| `--apple-team-id`            | Apple Developer Team ID (apple only)                                                                                                                                             | string | —       |    No    |
| `--microsoft-tenant-id`      | Tenant ID for the microsoft provider: common, organizations, consumers, a tenant GUID, or a domain                                                                               | string | —       |    No    |
| `--oauth-client-id`          | OAuth client ID from your provider app. For apple, the Services ID. Omit to use Neon's shared OAuth app, where one exists; microsoft and apple always need your own credentials. | string | —       |    No    |
| `--oauth-client-secret`      | OAuth client secret from your provider app. Omit to use Neon's shared OAuth app, where one exists; microsoft and apple always need your own credentials.                         | string | —       |    No    |
| `--oauth-client-secret-file` | Read the OAuth client secret from a file, for example the apple .p8 private key                                                                                                  | string | —       |    No    |
| `--provider-id`              | OAuth provider ID. Supported values: google, github, vercel, microsoft, apple                                                                                                    | string | —       |    Yes   |
| `--branch`                   | Branch ID or name                                                                                                                                                                | string | —       |    No    |
| `--project-id`               | Project ID                                                                                                                                                                       | string | —       |    No    |

```bash
neon neon-auth oauth-provider update --provider-id github --oauth-client-id <client-id> --oauth-client-secret <client-secret>
```

### neon neon-auth oauth-provider delete

Deletes an OAuth provider from the branch.

```bash
neon neon-auth oauth-provider delete [options]
```

| Option          | Description                                                                   | Type   | Default | Required |
| --------------- | ----------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--provider-id` | OAuth provider ID. Supported values: google, github, vercel, microsoft, apple | string | —       |    Yes   |
| `--branch`      | Branch ID or name                                                             | string | —       |    No    |
| `--project-id`  | Project ID                                                                    | string | —       |    No    |

```bash
neon neon-auth oauth-provider delete --provider-id vercel
```

## Domains

The `domain` subcommands manage the trusted domains that Managed Better Auth accepts as redirect URIs for the branch.

Subcommands: [add](https://neon.com/docs/cli/neon-auth#domain-add), [allow-localhost](https://neon.com/docs/cli/neon-auth#domain-allow-localhost), [delete](https://neon.com/docs/cli/neon-auth#domain-delete), [list](https://neon.com/docs/cli/neon-auth#domain-list)

### neon neon-auth domain list

Lists the trusted domains configured for the branch.

```bash
neon neon-auth domain list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth domain list
```

### neon neon-auth domain add

Adds a trusted domain.

```bash
neon neon-auth domain add <domain> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth domain add https://app.example.com
```

A trusted domain is an origin, so include the protocol (`https://`, or `http://` for local development) and omit any trailing slash. Use `https://app.example.com`, not `app.example.com` or `https://app.example.com/`. See [Configure trusted domains](https://neon.com/docs/auth/guides/configure-domains).

### neon neon-auth domain delete

Deletes a trusted domain.

```bash
neon neon-auth domain delete <domain> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth domain delete example.com
```

### neon neon-auth domain allow-localhost

Manages localhost connection settings for the branch.

Subcommands: [disable](https://neon.com/docs/cli/neon-auth#domain-allow-localhost-disable), [enable](https://neon.com/docs/cli/neon-auth#domain-allow-localhost-enable), [get](https://neon.com/docs/cli/neon-auth#domain-allow-localhost-get)

### neon neon-auth domain allow-localhost get

Gets the current localhost connection setting.

```bash
neon neon-auth domain allow-localhost get [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth domain allow-localhost get
```

### neon neon-auth domain allow-localhost enable

Allows localhost connections for local development.

```bash
neon neon-auth domain allow-localhost enable [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth domain allow-localhost enable
```

### neon neon-auth domain allow-localhost disable

Restricts localhost connections.

```bash
neon neon-auth domain allow-localhost disable [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth domain allow-localhost disable
```

## Configuration

The `config` subcommands configure auth features for the branch: email and password authentication, the email provider, the organization plugin, and webhooks.

Subcommands: [email-password](https://neon.com/docs/cli/neon-auth#config-email-password), [email-provider](https://neon.com/docs/cli/neon-auth#config-email-provider), [oauth-server](https://neon.com/docs/cli/neon-auth#config-oauth-server), [organization](https://neon.com/docs/cli/neon-auth#config-organization), [webhook](https://neon.com/docs/cli/neon-auth#config-webhook)

### neon neon-auth config email-password

Manages email and password authentication settings.

Subcommands: [get](https://neon.com/docs/cli/neon-auth#config-email-password-get), [update](https://neon.com/docs/cli/neon-auth#config-email-password-update)

### neon neon-auth config email-password get

Gets the current email and password configuration.

```bash
neon neon-auth config email-password get [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth config email-password get
```

### neon neon-auth config email-password update

Updates the email and password configuration.

```bash
neon neon-auth config email-password update [options]
```

| Option                                 | Description                                                  | Type    | Default | Required |
| -------------------------------------- | ------------------------------------------------------------ | ------- | ------- | :------: |
| `--auto-sign-in-after-verification`    | Auto sign in users after verifying their email               | boolean | —       |    No    |
| `--disable-sign-up`                    | Disable new user sign ups                                    | boolean | —       |    No    |
| `--email-verification-method`          | Email verification method                                    | string  | —       |    No    |
| `--enabled`                            | Enable email and password authentication                     | boolean | —       |    No    |
| `--require-email-verification`         | Require email verification before users can sign in          | boolean | —       |    No    |
| `--revoke-sessions-on-password-reset`  | Revoke all of a user's sessions when their password is reset | boolean | —       |    No    |
| `--send-verification-email-on-sign-in` | Send verification email on sign in                           | boolean | —       |    No    |
| `--send-verification-email-on-sign-up` | Send verification email on sign up                           | boolean | —       |    No    |
| `--branch`                             | Branch ID or name                                            | string  | —       |    No    |
| `--project-id`                         | Project ID                                                   | string  | —       |    No    |

```bash
neon neon-auth config email-password update --enabled --require-email-verification
```

### neon neon-auth config email-provider

Manages the email provider configuration.

Subcommands: [get](https://neon.com/docs/cli/neon-auth#config-email-provider-get), [test](https://neon.com/docs/cli/neon-auth#config-email-provider-test), [update](https://neon.com/docs/cli/neon-auth#config-email-provider-update)

### neon neon-auth config email-provider get

Gets the current email provider configuration.

```bash
neon neon-auth config email-provider get [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth config email-provider get
```

### neon neon-auth config email-provider update

Updates the email provider configuration.

```bash
neon neon-auth config email-provider update [options]
```

| Option           | Description                                               | Type   | Default | Required |
| ---------------- | --------------------------------------------------------- | ------ | ------- | :------: |
| `--host`         | SMTP host (required for standard)                         | string | —       |    No    |
| `--password`     | SMTP password (required for standard)                     | string | —       |    No    |
| `--port`         | SMTP port (required for standard)                         | number | —       |    No    |
| `--sender-email` | Sender email address                                      | string | —       |    No    |
| `--sender-name`  | Sender display name                                       | string | —       |    No    |
| `--type`         | Email provider type Possible values: `standard`, `shared` | string | —       |    Yes   |
| `--username`     | SMTP username (required for standard)                     | string | —       |    No    |
| `--branch`       | Branch ID or name                                         | string | —       |    No    |
| `--project-id`   | Project ID                                                | string | —       |    No    |

Configure the `standard` email provider type with your own SMTP server:

```bash
neon neon-auth config email-provider update --type standard --host smtp.example.com --port 587 --username example_username --password AbC123dEf --sender-email noreply@example.com --sender-name "Example App"
```

### neon neon-auth config email-provider test

Sends a test email through your saved SMTP provider so you can verify it works. Configure the provider first with [`update`](https://neon.com/docs/cli/neon-auth#config-email-provider-update).

```bash
neon neon-auth config email-provider test [options]
```

| Option              | Description                                  | Type   | Default | Required |
| ------------------- | -------------------------------------------- | ------ | ------- | :------: |
| `--recipient-email` | Email address to deliver the test message to | string | —       |    Yes   |
| `--branch`          | Branch ID or name                            | string | —       |    No    |
| `--project-id`      | Project ID                                   | string | —       |    No    |

```bash
neon neon-auth config email-provider test --recipient-email user@example.com
```

### neon neon-auth config organization

Manages organization plugin settings.

Subcommands: [get](https://neon.com/docs/cli/neon-auth#config-organization-get), [update](https://neon.com/docs/cli/neon-auth#config-organization-update)

### neon neon-auth config organization get

Gets the current organization plugin configuration.

```bash
neon neon-auth config organization get [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth config organization get
```

### neon neon-auth config organization update

Updates the organization plugin configuration.

```bash
neon neon-auth config organization update [options]
```

| Option           | Description                                                             | Type    | Default | Required |
| ---------------- | ----------------------------------------------------------------------- | ------- | ------- | :------: |
| `--creator-role` | Role assigned to organization creator Possible values: `admin`, `owner` | string  | —       |    No    |
| `--enabled`      | Enable the organization plugin                                          | boolean | —       |    No    |
| `--limit`        | Maximum number of organizations a user can create                       | number  | —       |    No    |
| `--branch`       | Branch ID or name                                                       | string  | —       |    No    |
| `--project-id`   | Project ID                                                              | string  | —       |    No    |

```bash
neon neon-auth config organization update --enabled --limit 5 --creator-role owner
```

### neon neon-auth config webhook

Manages webhook configuration.

Subcommands: [get](https://neon.com/docs/cli/neon-auth#config-webhook-get), [update](https://neon.com/docs/cli/neon-auth#config-webhook-update)

### neon neon-auth config webhook get

Gets the current webhook configuration.

```bash
neon neon-auth config webhook get [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth config webhook get
```

### neon neon-auth config webhook update

Updates the webhook configuration.

```bash
neon neon-auth config webhook update [options]
```

| Option             | Description                                                                                           | Type    | Default | Required |
| ------------------ | ----------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--enabled`        | Enable webhooks                                                                                       | boolean | —       |    Yes   |
| `--enabled-events` | Events to enable Possible values: `user.before_create`, `user.created`, `send.otp`, `send.magic_link` | array   | —       |    No    |
| `--timeout`        | Webhook timeout in seconds (1-10)                                                                     | number  | —       |    No    |
| `--url`            | Webhook endpoint URL                                                                                  | string  | —       |    No    |
| `--branch`         | Branch ID or name                                                                                     | string  | —       |    No    |
| `--project-id`     | Project ID                                                                                            | string  | —       |    No    |

```bash
neon neon-auth config webhook update --enabled --url https://example.com/webhooks/neon-auth --enabled-events user.created --timeout 5
```

### neon neon-auth config oauth-server

Manages the [OAuth provider plugin](https://neon.com/docs/auth/guides/plugins/oauth-provider), which turns Managed Better Auth into an OAuth 2.1 authorization server for your MCP server, API, or other apps. These commands configure the server. To manage its clients, see [OAuth clients](https://neon.com/docs/cli/neon-auth#oauth-client). The `oauth-provider` commands are for social sign-in providers, not this server.

Subcommands: [get](https://neon.com/docs/cli/neon-auth#config-oauth-server-get), [resource](https://neon.com/docs/cli/neon-auth#config-oauth-server-resource), [update](https://neon.com/docs/cli/neon-auth#config-oauth-server-update)

### neon neon-auth config oauth-server get

Gets the current OAuth server configuration.

```bash
neon neon-auth config oauth-server get [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth config oauth-server get
```

### neon neon-auth config oauth-server update

Updates the OAuth server configuration. To enable the server, it needs a login page, a consent page, and at least one protected resource or an MCP server URL. The login and consent pages must be on a [trusted domain](https://neon.com/docs/cli/neon-auth#domain).

```bash
neon neon-auth config oauth-server update [options]
```

| Option                               | Description                                                                                                                                                    | Type                             | Default | Required |    |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- | :------: | -- |
| `--consent-page`                     | URL of the page authorization requests redirect to for consent                                                                                                 | string                           | —       |    No    |    |
| `--enabled`                          | Enable the OAuth server. Use --no-enabled or --enabled false to disable                                                                                        | boolean                          | —       |    No    |    |
| `--login-page`                       | URL of the page authorization requests redirect to for sign-in                                                                                                 | string                           | —       |    No    |    |
| `--mcp`                              | Remove the MCP configuration (only --no-mcp is accepted)                                                                                                       | boolean                          | —       |    No    |    |
| `--mcp-client-id-metadata-documents` | Allow MCP clients to identify themselves with a Client ID Metadata Document (CIMD) URL. Use --no-mcp-client-id-metadata-documents to disallow                  | boolean                          | —       |    No    |    |
| `--mcp-resource`                     | MCP server URL that MCP clients are linked to. Defaults to the stored value when another --mcp-\* flag is given. To remove the MCP configuration, use --no-mcp | string                           | —       |    No    |    |
| `--resources`                        | Protected resource URLs that clients can be linked to; replaces the stored list. Use \`resource add                                                            | remove\` for incremental changes | array   |     —    | No |
| `--branch`                           | Branch ID or name                                                                                                                                              | string                           | —       |    No    |    |
| `--project-id`                       | Project ID                                                                                                                                                     | string                           | —       |    No    |    |

```bash
neon neon-auth config oauth-server update --enabled --login-page https://app.example.com/sign-in --consent-page https://app.example.com/consent
```

Set the MCP server URL to protect an MCP server, or remove the MCP configuration with `--no-mcp`:

```bash
neon neon-auth config oauth-server update --mcp-resource https://mcp.example.com/mcp
```

### neon neon-auth config oauth-server resource

Manages the protected resources that OAuth clients can request tokens for. `add` and `remove` read the stored list and write back the full list, so a change someone else makes at the same time can be overwritten.

Subcommands: [add](https://neon.com/docs/cli/neon-auth#config-oauth-server-resource-add), [list](https://neon.com/docs/cli/neon-auth#config-oauth-server-resource-list), [remove](https://neon.com/docs/cli/neon-auth#config-oauth-server-resource-remove)

### neon neon-auth config oauth-server resource list

Lists the protected resources.

```bash
neon neon-auth config oauth-server resource list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth config oauth-server resource list
```

### neon neon-auth config oauth-server resource add

Adds one or more protected resources.

```bash
neon neon-auth config oauth-server resource add <url...> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth config oauth-server resource add https://api.example.com
```

### neon neon-auth config oauth-server resource remove

Removes one or more protected resources. Clients stop listing a removed resource, and list it again if you add it back. On an enabled server, removing the last resource fails unless an MCP server URL is set.

```bash
neon neon-auth config oauth-server resource remove <url...> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth config oauth-server resource remove https://api.example.com
```

## OAuth clients

The `oauth-client` subcommands manage the clients registered with the branch's OAuth server. Enable and configure the server first with [`config oauth-server`](https://neon.com/docs/cli/neon-auth#config-oauth-server).

Subcommands: [create](https://neon.com/docs/cli/neon-auth#oauth-client-create), [delete](https://neon.com/docs/cli/neon-auth#oauth-client-delete), [get](https://neon.com/docs/cli/neon-auth#oauth-client-get), [list](https://neon.com/docs/cli/neon-auth#oauth-client-list), [rotate-secret](https://neon.com/docs/cli/neon-auth#oauth-client-rotate-secret), [update](https://neon.com/docs/cli/neon-auth#oauth-client-update)

### neon neon-auth oauth-client list

Lists the OAuth clients.

```bash
neon neon-auth oauth-client list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth oauth-client list
```

### neon neon-auth oauth-client create

Creates an OAuth client. Each resource you link must already be a [protected resource](https://neon.com/docs/cli/neon-auth#config-oauth-server-resource). A confidential client gets a client secret, which the command prints only once. Store it before you continue.

```bash
neon neon-auth oauth-client create [options]
```

| Option            | Description                                                                                                              | Type    | Default | Required |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | :------: |
| `--name`          | Display name of the client                                                                                               | string  | —       |    Yes   |
| `--redirect-uris` | Redirect URIs the client may use (https, or http on loopback when localhost is allowed)                                  | array   | —       |    Yes   |
| `--resources`     | Protected resource URLs to link the client to; each must be configured with `neon-auth config oauth-server resource add` | array   | —       |    Yes   |
| `--skip-consent`  | Skip the consent prompt (first-party clients only)                                                                       | boolean | —       |    No    |
| `--type`          | Client type. Confidential clients receive a secret that is shown only once Possible values: `confidential`, `public`     | string  | —       |    Yes   |
| `--branch`        | Branch ID or name                                                                                                        | string  | —       |    No    |
| `--project-id`    | Project ID                                                                                                               | string  | —       |    No    |

```bash
neon neon-auth oauth-client create --name "Example app" --type confidential --redirect-uris https://app.example.com/callback --resources https://api.example.com
```

### neon neon-auth oauth-client get

Gets an OAuth client.

```bash
neon neon-auth oauth-client get <client-id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth oauth-client get <client-id>
```

### neon neon-auth oauth-client update

Updates an OAuth client. `--redirect-uris` and `--resources` replace the stored lists. You can't change the client type.

```bash
neon neon-auth oauth-client update <client-id> [options]
```

| Option            | Description                                                                                                   | Type    | Default | Required |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--disabled`      | Disable the client. Use --no-disabled or --disabled false to re-enable                                        | boolean | —       |    No    |
| `--name`          | Display name of the client                                                                                    | string  | —       |    No    |
| `--redirect-uris` | Redirect URIs the client may use; replaces the stored list                                                    | array   | —       |    No    |
| `--resources`     | Protected resource URLs to link the client to; replaces the stored list (at least one)                        | array   | —       |    No    |
| `--skip-consent`  | Skip the consent prompt (first-party clients only). Use --no-skip-consent or --skip-consent false to turn off | boolean | —       |    No    |
| `--branch`        | Branch ID or name                                                                                             | string  | —       |    No    |
| `--project-id`    | Project ID                                                                                                    | string  | —       |    No    |

```bash
neon neon-auth oauth-client update <client-id> --name "Example app (staging)"
```

### neon neon-auth oauth-client rotate-secret

Rotates the secret of a confidential client. The old secret stops working immediately.

```bash
neon neon-auth oauth-client rotate-secret <client-id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth oauth-client rotate-secret <client-id>
```

### neon neon-auth oauth-client delete

Deletes an OAuth client. Tokens the client already received stay valid until they expire.

```bash
neon neon-auth oauth-client delete <client-id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth oauth-client delete <client-id>
```

## Plugins

The `plugins` subcommands show the Managed Better Auth plugin configurations for the branch.

Subcommands: [get](https://neon.com/docs/cli/neon-auth#plugins-get), [list](https://neon.com/docs/cli/neon-auth#plugins-list)

### neon neon-auth plugins list

Lists all plugin configurations.

```bash
neon neon-auth plugins list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth plugins list
```

### neon neon-auth plugins get

Gets a specific plugin configuration.

```bash
neon neon-auth plugins get <plugin-name> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth plugins get organization
```

## Users

The `user` subcommands manage Managed Better Auth users on the branch.

Subcommands: [create](https://neon.com/docs/cli/neon-auth#user-create), [delete](https://neon.com/docs/cli/neon-auth#user-delete), [set-role](https://neon.com/docs/cli/neon-auth#user-set-role)

### neon neon-auth user create

Creates an auth user.

```bash
neon neon-auth user create [options]
```

| Option         | Description                                           | Type   | Default | Required |
| -------------- | ----------------------------------------------------- | ------ | ------- | :------: |
| `--email`      | User email address                                    | string | —       |    Yes   |
| `--name`       | User display name (defaults to email if not provided) | string | —       |    No    |
| `--branch`     | Branch ID or name                                     | string | —       |    No    |
| `--project-id` | Project ID                                            | string | —       |    No    |

```bash
neon neon-auth user create --email alex@example.com --name "Alex Lopez"
```

### neon neon-auth user delete

Deletes an auth user.

```bash
neon neon-auth user delete <user-id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth user delete <user-id>
```

### neon neon-auth user set-role

Sets roles for an auth user.

```bash
neon neon-auth user set-role <user-id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--roles`      | Roles to assign   | array  | —       |    Yes   |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon neon-auth user set-role <user-id> --roles admin
```

--- [Document source](https://neon.com/docs/cli/open.md) ---

> Summary: The Neon CLI `open` command opens your linked project's dashboard in the Neon Console in your default browser. It resolves the project from your local `.neon` context file, or from an explicit `--project-id`. Use it to jump from the terminal to the Console without looking up the project URL.

# Neon CLI command: open

Open the linked project in the Neon Console in your browser

Last updated: 2026-11-01

The `open` command opens the linked project's dashboard in the [Neon Console](https://console.neon.tech) in your default browser. It resolves the project from your local `.neon` [context file](https://neon.com/docs/cli/link), so run [`neon link`](https://neon.com/docs/cli/link) or [`neon set-context`](https://neon.com/docs/cli/set-context) first, or pass `--project-id` to target a project directly. If no project is linked and you don't pass `--project-id`, the command tells you to run `neon link`.

## Usage

```bash
neon open [options]
```

## Options

| Option         | Description                                          | Type   | Default | Required |
| -------------- | ---------------------------------------------------- | ------ | ------- | :------: |
| `--project-id` | Project ID (defaults to the project linked in .neon) | string | —       |    No    |

## Examples

Open the project linked in the current directory's `.neon` context file:

```bash
neon open
```

```text
Opening https://console.neon.tech/app/projects/cold-grass-40154007 in your browser.
```

Open a specific project without relying on the linked context:

```bash
neon open --project-id cold-grass-40154007
```

--- [Document source](https://neon.com/docs/cli/operations.md) ---

> Summary: The Neon CLI `neon operations list` command retrieves the history of system operations for a Neon project, showing each operation's ID, action type (such as `apply_config` or `suspend_compute`), status, and creation timestamp. Use this command to inspect or audit long-running or recently completed operations when debugging project state or configuration changes. Requires the Neon CLI to be installed and authenticated; scope to a specific project with `--project-id` when your account has multiple projects.

# Neon CLI command: operations

List operations for a Neon project and check the status of one

Last updated: 2026-11-05

From the terminal, the `operations` command lists a project's operations and shows the details of one. For information about operations in Neon, see [System operations](https://neon.com/docs/manage/operations). If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

Subcommands: [get](https://neon.com/docs/cli/operations#get), [list](https://neon.com/docs/cli/operations#list)

## neon operations list

Lists operations for a Neon project.

```bash
neon operations list [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon operations list
```

```text filename="Output"
ID                                    Action           Status    Created At
fce8642e-259e-4662-bdce-518880aee723  apply_config     finished  2026-06-20T00:45:19Z
dc1dfb0c-b854-474b-be20-2ea1d2172563  apply_config     finished  2026-06-20T00:43:17Z
7a83e300-cf5f-4c1a-b9b5-569b6d6feab9  suspend_compute  finished  2026-06-19T23:50:56Z
```

## neon operations get

Shows one operation, including its branch, compute, failure count, and duration. Get the ID from `neon operations list`.

```bash
neon operations get <id> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon operations get 8f3c2a1e-5b7d-4c9a-a1e2-3d4f5a6b7c8d
```

```text filename="Output"
ID                 8f3c2a1e-5b7d-4c9a-a1e2-3d4f5a6b7c8d
Action             suspend_compute
Status             finished
Branch ID          br-lively-sunset-123456
Endpoint ID        ep-cool-king-123456
Failures Count     0
Total Duration Ms  84
Created At         2026-11-05T14:24:09Z
Updated At         2026-11-05T14:24:09Z
```

--- [Document source](https://neon.com/docs/cli/orgs.md) ---

> Summary: The `neon orgs` CLI command lists the Neon organizations you belong to and shows one organization's details. Its subcommands also list, inspect, update, and remove members, list and send invitations, and get, set, or remove the organization's monthly spending limit. Use it to look up an org ID before running org-scoped commands, or to manage an organization from the terminal.

# Neon CLI command: orgs

List and inspect organizations, and manage members, invitations, and the spending limit

Last updated: 2026-11-05

The `orgs` command lists the organizations you belong to, shows one organization, and manages its members, invitations, and monthly spending limit. For background, see [Manage organizations](https://neon.com/docs/manage/orgs-manage).

Every subcommand except `list` takes `--org-id`. Without it, the CLI uses the organization in your [`.neon` context file](https://neon.com/docs/cli/link#the-neon-context-file), then the only organization you belong to. Otherwise, it fails and asks you to pass `--org-id`. Changing a member's role, removing a member, and setting or removing the spending limit require an organization Admin.

Subcommands: [get](https://neon.com/docs/cli/orgs#get), [invitations](https://neon.com/docs/cli/orgs#invitations), [list](https://neon.com/docs/cli/orgs#list), [members](https://neon.com/docs/cli/orgs#members), [spending-limit](https://neon.com/docs/cli/orgs#spending-limit)

## neon orgs list

Lists all organizations associated with the authenticated Neon CLI user.

```bash
neon orgs list [options]
```

List your organizations with the default `table` output format. The organization in your [`.neon` context file](https://neon.com/docs/cli/link#the-neon-context-file) is marked `[current]`:

```bash
neon orgs list
```

```text filename="Output"
Organizations
ID                     Name                   Plan
org-xxxxxxxx-xxxxxxxx  [current] Example Org  Launch
org-yyyyyyyy-yyyyyyyy  Another Org            Free
```

List your organizations with `--output json`, which also shows the fields omitted from the `table` output, such as the handle and timestamps. JSON keeps the API's plan ID (for example, `launch`) rather than the display name:

```bash
neon orgs list -o json
```

<details>

<summary>Show output</summary>

```json
[
  {
    "id": "org-xxxxxxxx-xxxxxxxx",
    "name": "Example Org",
    "handle": "example-org-xxxxxxxx",
    "plan": "launch",
    "created_at": "2026-04-22T16:50:41Z",
    "managed_by": "console",
    "updated_at": "2026-06-28T15:38:26Z",
    "require_mfa": false
  }
]
```

</details>

## neon orgs get

Shows an organization's details. Pass the organization ID as an argument or with `--org-id`.

```bash
neon orgs get [id] [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

```bash
neon orgs get org-xxxxxxxx-xxxxxxxx
```

```text filename="Output"
ID          org-xxxxxxxx-xxxxxxxx
Name        Example Org
Handle      example-org-xxxxxxxx
Plan        Scale
Created At  2026-09-10T16:36:29Z
```

## neon orgs members

Lists, inspects, updates, and removes the members of an organization.

```bash
neon orgs members <sub-command> [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

Subcommands: [get](https://neon.com/docs/cli/orgs#members-get), [list](https://neon.com/docs/cli/orgs#members-list), [remove](https://neon.com/docs/cli/orgs#members-remove), [update](https://neon.com/docs/cli/orgs#members-update)

### neon orgs members list

Lists members with their email and organization role. Use the `ID` column as the `<member-id>` for the other `members` subcommands. JSON and YAML output keep the API's shape: each item has a `member` object and a `user` object.

```bash
neon orgs members list [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

```bash
neon orgs members list
```

```text filename="Output"
Members of org-xxxxxxxx-xxxxxxxx
ID                                    Email              Role   Joined At
a1b2c3d4-1111-4a2b-8c3d-0123456789ab  alex@example.com   admin  2026-09-10T16:36:29Z
b2c3d4e5-2222-4b3c-9d4e-123456789abc  dana@example.com   admin  2026-09-25T18:18:32Z
```

### neon orgs members get

Shows one member.

```bash
neon orgs members get <member-id> [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

```bash
neon orgs members get a1b2c3d4-1111-4a2b-8c3d-0123456789ab
```

### neon orgs members update

Changes a member's organization role. The role sets the member's baseline access across every project in the organization. See [Organization roles](https://neon.com/docs/manage/user-permissions#organization-roles). `--role` accepts `admin`, `editor`, `viewer`, or `collaborator`. `member` is a legacy alias for `editor`. Some roles may not be available for every organization.

```bash
neon orgs members update <member-id> [options]
```

| Option     | Description                                                                                      | Type   | Default | Required |
| ---------- | ------------------------------------------------------------------------------------------------ | ------ | ------- | :------: |
| `--role`   | The new organization role Possible values: `admin`, `member`, `editor`, `viewer`, `collaborator` | string | —       |    Yes   |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one                           | string | —       |    No    |

```bash
neon orgs members update b2c3d4e5-2222-4b3c-9d4e-123456789abc --role viewer
```

### neon orgs members remove

Removes a member from the organization.

```bash
neon orgs members remove <member-id> [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

```bash
neon orgs members remove b2c3d4e5-2222-4b3c-9d4e-123456789abc
```

## neon orgs invitations

Lists and sends invitations to join an organization.

```bash
neon orgs invitations <sub-command> [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

Subcommands: [create](https://neon.com/docs/cli/orgs#invitations-create), [list](https://neon.com/docs/cli/orgs#invitations-list)

### neon orgs invitations list

Lists pending invitations.

```bash
neon orgs invitations list [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

```bash
neon orgs invitations list
```

```text filename="Output"
Invitations to org-xxxxxxxx-xxxxxxxx
ID                                    Email              Role    Invited At
c3d4e5f6-3333-4c4d-8e5f-23456789abcd  zhang@example.com  viewer  2026-11-05T14:26:14Z
```

### neon orgs invitations create

Invites people by email. Repeat `--email` to invite several people at once. Every invitee gets the same `--role`. Neon emails each one, and anyone who already has a Neon account joins right away.

[Organization API keys](https://neon.com/docs/manage/api-keys#types-of-api-keys) can't send invitations. Use a personal API key instead.

```bash
neon orgs invitations create [options]
```

| Option     | Description                                                                                                     | Type   | Default | Required |
| ---------- | --------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--email`  | Email address to invite. Repeat to invite several                                                               | array  | —       |    Yes   |
| `--role`   | The organization role every invitee gets Possible values: `admin`, `member`, `editor`, `viewer`, `collaborator` | string | —       |    Yes   |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one                                          | string | —       |    No    |

```bash
neon orgs invitations create --email dana@example.com --email zhang@example.com --role editor
```

## neon orgs spending-limit

Gets, sets, and removes the organization's monthly spending limit, which the Console calls the [spending notification](https://neon.com/docs/introduction/spending-notifications) threshold. Available on the Launch and Scale plans.

```bash
neon orgs spending-limit <sub-command> [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

Subcommands: [delete](https://neon.com/docs/cli/orgs#spending-limit-delete), [get](https://neon.com/docs/cli/orgs#spending-limit-get), [set](https://neon.com/docs/cli/orgs#spending-limit-set)

### neon orgs spending-limit get

Shows the monthly spending limit, or `Not set`. JSON and YAML output keep the API's `spending_limit_cents` field.

```bash
neon orgs spending-limit get [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

```bash
neon orgs spending-limit get
```

```text filename="Output"
Spending limit for org-xxxxxxxx-xxxxxxxx
Monthly Limit  $500.00
```

### neon orgs spending-limit set

Sets the monthly spending limit in US dollars, with up to two decimal places. Neon emails organization Admins at 80% and 100% of the limit. Reaching the limit doesn't suspend computes.

```bash
neon orgs spending-limit set <usd> [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

```bash
neon orgs spending-limit set 500
```

### neon orgs spending-limit delete

Removes the monthly spending limit.

```bash
neon orgs spending-limit delete [options]
```

| Option     | Description                                                            | Type   | Default | Required |
| ---------- | ---------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id` | Organization ID. Defaults to the linked organization, or your only one | string | —       |    No    |

```bash
neon orgs spending-limit delete
```

```text filename="Output"
Spending limit removed from org-xxxxxxxx-xxxxxxxx
```

--- [Document source](https://neon.com/docs/cli/plugins.md) ---

> Summary: The Neon CLI `plugins` command installs the `neon-postgres` plugin into coding agents that support plugin marketplaces, such as Claude Code, Cursor, and Codex. The plugin bundles Neon's agent skills and MCP access. Run it with no flags for an interactive walkthrough, or pass `--agent` and `-y` to pick the agents and skip the prompts.

# Neon CLI command: plugins

Install the Neon plugin into coding agents that support plugin marketplaces

Last updated: 2026-11-01

The `plugins` command installs the `neon-postgres` plugin into coding agents that support plugin marketplaces, so tools like Claude Code, Cursor, and Codex know how to work with Neon. The plugin bundles [Neon's agent skills](https://neon.com/docs/ai/agent-skills) and the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server) in one package.

```bash
neon plugins
```

[Install the Neon CLI](https://neon.com/docs/cli/install) with `npm i -g neon@latest`, or run it once with `npx neon@latest plugins`.

With no flags it runs an interactive walkthrough: pick the agents, then confirm. Pass flags to skip the prompts and script it. Without a terminal, pass `-y` to install into detected agents, or name agents with `--agent`.

**plugins vs skills vs mcp:**

Use [`neon plugins`](https://neon.com/docs/cli/plugins) for agents that support plugin marketplaces, where the plugin bundles skills and MCP in one. For the full setup, use [`neon init`](https://neon.com/docs/cli/init); for skills or the MCP server on their own, use [`neon skills`](https://neon.com/docs/cli/skills) or [`neon mcp`](https://neon.com/docs/cli/mcp).

`plugins` runs via `npx`, so it needs Node.js; without it the command stops with a message to install Node.js and retry.

## Usage

```bash
neon plugins [options]
```

## Options

| Option          | Description                                                                                   | Type    | Default | Required |
| --------------- | --------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--agent`, `-a` | Coding agent to install into (repeatable). Skips the agent picker. Values listed below        | array   | —       |    No    |
| `--yes`, `-y`   | Skip prompts. Detected agents (project folders, else the host CLI agent, else installed apps) | boolean | `false` |    No    |

### Choosing agents

Without `--agent`, the interactive command lists the supported agents, pre-selects the ones it detects, and lets you toggle the selection. In non-interactive mode, `-y` installs into every detected agent. Pass `--agent <name>` (repeatable) to name agents explicitly and skip the picker.

The agents that support plugins are `claude-code`, `claude-desktop`, `codex`, `cursor`, `github-copilot-cli`, `grok-build`, `kimi-code`, and `vscode`. Several also accept aliases: `claude` for `claude-code`, `grok` for `grok-build`, and `copilot`, `github-copilot`, or `vs-code` for `vscode`. Passing an unknown agent stops the command and prints the supported list. An agent with no plugin support is skipped when others can install, or stops the command when it's the only one selected.

Agents that share a target collapse into one: Claude Desktop and Claude Code both write to `claude-code`, and VS Code and the GitHub Copilot CLI both write to `github-copilot`.

### Install location

`plugins` installs the plugin user-level, so it applies to every project. There's no project-level install. The `--global` flag from earlier versions is still accepted and does the same thing as the default, so existing scripts keep working (Neon CLI 8.23.2 and later).

## Examples

Run the interactive install:

```bash
neon plugins
```

Install into a specific agent, skipping every prompt:

```bash
neon plugins --agent claude-code -y
```

```text filename="Output"
Plugins
Scope  Plugin         Agent        Status
user   neon-postgres  claude-code  installed

Installed the Neon plugin (user).
```

Install into several agents at once:

```bash
neon plugins --agent cursor --agent claude-code
```

Install non-interactively into every detected agent:

```bash
neon plugins -y
```

--- [Document source](https://neon.com/docs/cli/postgres.md) ---

> Summary: The Neon CLI `postgres` command (aliases `pg` and `lakebase`) groups the Lakebase Postgres commands: `computes`, `databases`, `roles`, `connection-string`, and `psql`. Use this reference for `neon postgres computes`, which lists, inspects, resizes, suspends, starts, restarts, and deletes the computes in a Neon project. The other subcommands match their top-level forms, such as `neon roles` and `neon psql`.

# Neon CLI command: postgres

Manage computes, databases, and roles, and connect to Lakebase Postgres, from one command group

The `postgres` command groups the commands that work with Lakebase Postgres in a Neon project: [computes](https://neon.com/docs/cli/postgres#computes), [databases](https://neon.com/docs/cli/databases), [roles](https://neon.com/docs/cli/roles), [connection strings](https://neon.com/docs/cli/connection-string), and [psql](https://neon.com/docs/cli/psql). Its aliases are `pg` and `lakebase`, so `neon pg roles list` and `neon lakebase roles list` work too.

`computes` is only available under `postgres`. The other subcommands run the same command as their top-level spelling, so `neon postgres roles list` and `neon roles list` do the same thing. Both spellings work.

If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

Subcommands: [computes](https://neon.com/docs/cli/postgres#computes), [connection-string](https://neon.com/docs/cli/postgres#connection-string), [databases](https://neon.com/docs/cli/postgres#databases), [psql](https://neon.com/docs/cli/postgres#psql), [roles](https://neon.com/docs/cli/postgres#roles)

## neon postgres computes

Manages the computes in a Neon project. Aliases: `compute`, `endpoints`, and `endpoint`. For background, see [Manage computes](https://neon.com/docs/manage/computes).

```bash
neon postgres computes <sub-command> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

Subcommands: [delete](https://neon.com/docs/cli/postgres#computes-delete), [get](https://neon.com/docs/cli/postgres#computes-get), [list](https://neon.com/docs/cli/postgres#computes-list), [restart](https://neon.com/docs/cli/postgres#computes-restart), [start](https://neon.com/docs/cli/postgres#computes-start), [suspend](https://neon.com/docs/cli/postgres#computes-suspend), [update](https://neon.com/docs/cli/postgres#computes-update)

`update`, `start`, `suspend`, `restart`, and `delete` wait until the change is applied. Pass `--no-wait` to return as soon as the API accepts the request. To add a compute, use [`neon branches add-compute`](https://neon.com/docs/cli/branches#add-compute).

### neon postgres computes list

Lists computes. With `--branch`, or when your `.neon` context file pins a branch, it lists that branch's computes. Otherwise it lists every compute in the project. `--all-branches` lists every compute in the project even when `.neon` pins a branch.

```bash
neon postgres computes list [options]
```

| Option           | Description                                                                    | Type    | Default | Required |
| ---------------- | ------------------------------------------------------------------------------ | ------- | ------- | :------: |
| `--all-branches` | List every compute in the project, ignoring --branch and the branch .neon pins | boolean | `false` |    No    |
| `--branch`       | Branch ID or name                                                              | string  | —       |    No    |
| `--project-id`   | Project ID                                                                     | string  | —       |    No    |

```bash
neon postgres computes list --branch main
```

```text filename="Output"
Computes on main
ID                      Branch ID                  Type        Current State  Autoscaling Limit Min Cu  Autoscaling Limit Max Cu
ep-cool-king-123456     br-lively-sunset-123456    read_write  active         0.25                      2
```

### neon postgres computes get

Shows a compute's details, including its host, state, autoscaling limits, and scale-to-zero timeout.

```bash
neon postgres computes get <id> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon postgres computes get ep-cool-king-123456
```

<details>

<summary>Show output</summary>

```text
ID                        ep-cool-king-123456
Branch ID                 br-lively-sunset-123456
Type                      read_write
Current State             active
Host                      ep-cool-king-123456.us-east-2.aws.neon.tech
Region ID                 aws-us-east-2
Autoscaling Limit Min Cu  0.25
Autoscaling Limit Max Cu  2
Suspend Timeout Seconds   600
Disabled                  false
Last Active               2026-11-05T14:46:05Z
Created At                2026-11-05T14:46:01Z
```

</details>

### neon postgres computes update

Changes a compute's size, scale-to-zero timeout, name, or connection access. It sends only the options you pass, and fails if you pass none. When the change is applied, it prints the compute.

```bash
neon postgres computes update <id> [options]
```

| Option              | Description                                                                                                                                                                                                                                                                                        | Type    | Default | Required |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--cu`              | The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").                                                                                                                                                                                       | string  | —       |    No    |
| `--disabled`        | Restrict connections to the compute. Disabling schedules a suspend. Use --disabled=false to allow connections again.                                                                                                                                                                               | boolean | —       |    No    |
| `--name`            | Name of the compute                                                                                                                                                                                                                                                                                | string  | —       |    No    |
| `--suspend-timeout` | Scale-to-zero idle timeout, in seconds, before the compute suspends. `0` uses the plan default; `-1` disables scale-to-zero (never suspends). Minimum is plan-dependent (Scale: 60); maximum 604800 (one week). Free cannot change it; Launch can only enable or disable; Scale can set any value. | number  | —       |    No    |
| `--wait`            | Wait until the change is applied. Use --no-wait to return as soon as the API accepts it                                                                                                                                                                                                            | boolean | `true`  |    No    |
| `--project-id`      | Project ID                                                                                                                                                                                                                                                                                         | string  | —       |    No    |

Set autoscaling to 0.25 to 2 compute units (CU) and suspend after 10 minutes of inactivity:

```bash
neon postgres computes update ep-cool-king-123456 --cu 0.25-2 --suspend-timeout 600
```

`--disabled` restricts connections to the compute and schedules a suspend. Pass `--disabled=false` to allow connections again:

```bash
neon postgres computes update ep-cool-king-123456 --disabled=false
```

### neon postgres computes start

Starts a suspended compute and prints it once it's active.

```bash
neon postgres computes start <id> [options]
```

| Option         | Description                                                                             | Type    | Default | Required |
| -------------- | --------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--wait`       | Wait until the change is applied. Use --no-wait to return as soon as the API accepts it | boolean | `true`  |    No    |
| `--project-id` | Project ID                                                                              | string  | —       |    No    |

```bash
neon postgres computes start ep-cool-king-123456
```

### neon postgres computes suspend

Suspends a compute and prints it once it's idle.

```bash
neon postgres computes suspend <id> [options]
```

| Option         | Description                                                                             | Type    | Default | Required |
| -------------- | --------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--wait`       | Wait until the change is applied. Use --no-wait to return as soon as the API accepts it | boolean | `true`  |    No    |
| `--project-id` | Project ID                                                                              | string  | —       |    No    |

```bash
neon postgres computes suspend ep-cool-king-123456
```

### neon postgres computes restart

Restarts a compute and prints it once it's back up.

```bash
neon postgres computes restart <id> [options]
```

| Option         | Description                                                                             | Type    | Default | Required |
| -------------- | --------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--wait`       | Wait until the change is applied. Use --no-wait to return as soon as the API accepts it | boolean | `true`  |    No    |
| `--project-id` | Project ID                                                                              | string  | —       |    No    |

```bash
neon postgres computes restart ep-cool-king-123456
```

With `--no-wait`, the output says the restart was accepted but not yet applied:

```text filename="Output"
Compute ep-cool-king-123456: restart accepted, not yet applied
```

### neon postgres computes delete

Deletes a compute, such as a [read replica](https://neon.com/docs/introduction/read-replicas) you no longer need, and prints a confirmation.

```bash
neon postgres computes delete <id> [options]
```

| Option         | Description                                                                             | Type    | Default | Required |
| -------------- | --------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--wait`       | Wait until the change is applied. Use --no-wait to return as soon as the API accepts it | boolean | `true`  |    No    |
| `--project-id` | Project ID                                                                              | string  | —       |    No    |

```bash
neon postgres computes delete ep-divine-tree-123456
```

```text filename="Output"
Compute ep-divine-tree-123456 deleted
```

## neon postgres databases

Lists, creates, and deletes databases. It's the same command as [`neon databases`](https://neon.com/docs/cli/databases), which documents its subcommands and options.

```bash
neon postgres databases <sub-command> [options]
```

```bash
neon postgres databases list
```

## neon postgres roles

Lists, inspects, creates, and deletes roles, and resets their passwords. It's the same command as [`neon roles`](https://neon.com/docs/cli/roles), which documents its subcommands and options.

```bash
neon postgres roles <sub-command> [options]
```

```bash
neon postgres roles list
```

## neon postgres connection-string

Prints a connection string for a branch. Alias: `cs`. It's the same command as [`neon connection-string`](https://neon.com/docs/cli/connection-string), which documents its options.

```bash
neon postgres connection-string [branch] [options]
```

```bash
neon pg cs main
```

## neon postgres psql

Opens a psql session on a branch. It's the same command as [`neon psql`](https://neon.com/docs/cli/psql), which documents its options.

```bash
neon postgres psql [branch] [options] [-- psql-args]
```

```bash
neon postgres psql main -- -c "SELECT version()"
```

--- [Document source](https://neon.com/docs/cli/profile.md) ---

> Summary: The `neon profile` CLI command creates, lists, rotates, and removes named credential sets, so one machine can hold logins for several Neon accounts. Use it to see which profile is active, which account each one holds, rotate a profile's key, and revoke a profile's token when you no longer need it.

# Neon CLI command: profile

Manage named sets of Neon credentials

Last updated: 2026-10-19

A profile is a pointer to a credentials file, so one machine can hold logins for several Neon accounts and pick between them per command.

Create one with `neon profile create`, or by authenticating with a name:

```bash
neon profile create work
```

`--profile` is a [global option](https://neon.com/docs/cli#global-options), so you can pass it to any command to act as that profile's account. `neon me` confirms which account a profile holds:

```bash
neon me --profile work
```

```text filename="Output"
Login           alex
Email           alex@domain.com
Name            Alex Lopez
Authentication  OAuth (profile work)
```

Naming a profile that doesn't exist is an error, not a silent fall back to `DEFAULT`.

Credentials resolve from `--profile`, then `NEON_PROFILE`, then a profile named `DEFAULT`. Nothing persists between commands, so set `NEON_PROFILE` to avoid repeating the flag. `DEFAULT` is what a plain `neon login` gives you, with or without profiles.

Profiles live in `profiles.json` in the config directory, which is `~/.config/neon` by default (`XDG_CONFIG_HOME` moves it) and `--config-dir` overrides per command. That file maps each profile name to the credentials file that holds its token. The CLI manages it for you, so create and remove profiles with the commands below rather than editing it by hand.

**Note: Profiles carry credentials, not context**

A profile sets which account you act as, not which organization or project. Commands that need one still resolve it from `--org-id`, the `.neon` context file, or a prompt:

```bash
neon projects list --profile work --org-id org-example-12345678
```

See [set-context](https://neon.com/docs/cli/set-context) and [checkout](https://neon.com/docs/cli/checkout) for pinning an org or branch.

Subcommands: [create](https://neon.com/docs/cli/profile#create), [list](https://neon.com/docs/cli/profile#list), [remove](https://neon.com/docs/cli/profile#remove), [rotate-key](https://neon.com/docs/cli/profile#rotate-key)

## neon profile create

Creates a profile. It holds either a browser sign-in or an API key, never both.

```bash
neon profile create <name> [options]
```

| Option         | Description                                                                                                              | Type    | Default | Required |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ | ------- | ------- | :------: |
| `--api-key`    | API key to store, or "-" to read it from stdin                                                                           | string  | —       |    No    |
| `--keyring`    | Store the credential in the OS keyring. Per profile; later create without the flag stays there. See `neon profile list`. | boolean | —       |    No    |
| `--mint`       | Sign in once in the browser, then store a freshly minted API key and nothing else                                        | boolean | `false` |    No    |
| `--org-id`     | With --mint, mint a key for this organization instead of your account                                                    | string  | —       |    No    |
| `--project-id` | With --mint, mint a key that can access only this project                                                                | string  | —       |    No    |

Most of the time you create a profile one of two ways: a browser sign-in, or a freshly minted key.

Sign in with the browser, the same as `neon login --profile work`:

```bash
neon profile create work
```

With `--mint`, sign in once in the browser, then store a freshly minted API key and nothing else. This leaves no browser session behind, which suits CI:

```bash
neon profile create ci --mint --org-id org-abc-123
```

Pass `--project-id` with `--mint` to mint a key that can access only one project, or `--org-id` to mint it for an organization instead of your account.

If you already have a key minted elsewhere, store it with `--api-key`. Pipe it to `--api-key -`, where `-` tells the CLI to read the key from stdin, so it stays out of the process arguments where `ps` would otherwise expose it. Here `$KEY` is a shell variable holding the key:

```bash
echo "$KEY" | neon profile create work --api-key -
```

Passing the key as the argument value works too, but avoid it outside a throwaway shell, since the key is then visible to other processes:

```bash
neon profile create work --api-key "$KEY"
```

`create` ignores `NEON_API_KEY`, so exporting that variable doesn't supply the key here. Pass it explicitly with `--api-key`.

By default the credential is saved to a `credentials.json` file. Pass `--keyring` to store it in your operating system's keyring instead. The choice is saved per profile. `neon profile list` shows `keyring` in the `Credentials` column for a keyring profile, and `-o json` includes a `storage` field.

## neon profile list

Lists each profile, the account it holds, and where its credentials live. `Active` marks the profile this invocation would use.

```bash
neon profile list [options]
```

```bash
neon profile list
```

```text filename="Output"
Profiles
Active  Name     Account                               Auth     Credentials               Scope
*       DEFAULT  3f8a1c2e-5b7d-4e9a-8c1f-2d6b9e0a4c53  oauth    credentials.json          account
        work     alex@example.com                      oauth    credentials.work.json     account
        ci       alex@example.com                      api key  credentials.ci.json       account
        org      org-example-12345678                  api key  credentials.org.json      org org-example-12345678
        project  org-example-12345678                  api key  credentials.project.json  project cool-darkness-12345678
        laptop   alex@example.com                      oauth    keyring                   account
```

`Account` is the recorded email label, the user ID when there's no label (as with a `DEFAULT` profile from a plain `neon login`), or the organization identifier for an organization- or project-scoped key. `Auth` shows how the profile authenticates (`oauth` for a browser sign-in, `api key` for a stored key). `Credentials` gives the credentials file's name, or `keyring` when the credential is kept in the OS keyring. `Scope` shows what the credential can reach: `account` for a browser sign-in or an account key, or `org <org-id>` or `project <project-id>` for a key limited to that organization or project. Pass `-o json` to also get two more fields: `file`, which reports whether the credential could be read (`ok`, or else `missing`, `invalid`, or `unreadable`), and `storage`, which is `file` or `keyring`.

## neon profile rotate-key

Mints a fresh API key for a profile, at the same scope, and revokes the one it replaces. Anything using the old key stops working immediately.

```bash
neon profile rotate-key <name> [options]
```

```bash
neon profile rotate-key ci
```

This works for account-scoped keys, where the profile's own credential can mint the replacement. An organization- or project-scoped key can't rotate itself, since only a personal credential can mint those keys. Re-mint it with a browser sign-in instead, matching the original scope:

```bash
neon profile create ci --mint --org-id org-example-12345678
```

The `rotate-key` error names the exact command to run for the profile's scope.

## neon profile remove

Revokes the profile's token, then removes the profile. Anything using that token stops working immediately.

Pass `--yes` to skip the confirmation prompt. In CI, a removal without `--yes` is refused rather than assumed.

The credentials file is deleted only if the CLI created it. A profile pointing outside the config directory is left on disk, and the command says so, so the secret is still there.

If the token can't be revoked, the profile is still removed locally, and the command tells you the token may remain valid. Revoke it yourself from the [Neon Console](https://console.neon.tech) if it was an API key.

Removing the last profile deletes `profiles.json` too, leaving the config directory as it was before you created any profiles.

```bash
neon profile remove <name> [options]
```

| Option        | Description                  | Type    | Default | Required |
| ------------- | ---------------------------- | ------- | ------- | :------: |
| `--yes`, `-y` | Skip the confirmation prompt | boolean | `false` |    No    |

Remove a profile:

```bash
neon profile remove work
```

```text filename="Output"
? Remove profile "work" (alex@domain.com)? ' (y/N)
```

The prompt defaults to no, so pressing Enter leaves the profile in place.

To switch accounts rather than discard one, authenticate again under the same name:

```bash
neon login --profile work
```

--- [Document source](https://neon.com/docs/cli/projects.md) ---

> Summary: The Neon CLI `neon projects` command provides subcommands to list, create, update, delete, recover, and retrieve Neon projects from the terminal, including support for region selection (AWS and Azure), blocking public or VPC connections, and filtering shared projects. Use this page when you need CLI automation for project lifecycle tasks or to recover a deleted project within its 7-day recovery window. Projects created via the CLI default to Postgres 18; use `--pg-version` to select a different major version.

# Neon CLI command: projects

List, create, update, delete, recover, and get Neon projects

Last updated: 2026-10-09

The `projects` command lists, creates, updates, deletes, recovers, and retrieves Neon projects from the terminal. For information about projects in Neon, see [Projects](https://neon.com/docs/manage/projects). Subcommands that show no options table accept only the [global options](https://neon.com/docs/cli#global-options). If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

Subcommands: [create](https://neon.com/docs/cli/projects#create), [delete](https://neon.com/docs/cli/projects#delete), [get](https://neon.com/docs/cli/projects#get), [list](https://neon.com/docs/cli/projects#list), [recover](https://neon.com/docs/cli/projects#recover), [update](https://neon.com/docs/cli/projects#update)

## neon projects list

Lists projects that belong to your Neon account, as well as any projects that were shared with you.

```bash
neon projects list [options]
```

| Option               | Description                                                   | Type    | Default | Required |
| -------------------- | ------------------------------------------------------------- | ------- | ------- | :------: |
| `--org-id`           | List projects of a given organization                         | string  | —       |    No    |
| `--recoverable-only` | List only deleted projects within their deletion grace period | boolean | —       |    No    |

- List projects in your [default organization](https://neon.com/docs/reference/glossary#default-organization). If no organization context is set, the CLI prompts you to select one.

  ```bash
  neon projects list
  ```

  ```text
  Projects
  ID                      Name      Region ID      Created At
  crimson-voice-12345678  frontend  aws-us-east-2  2026-04-15T11:17:30Z
  calm-thunder-12121212   backend   aws-us-east-2  2026-04-10T15:21:01Z
  nameless-hall-87654321  billing   aws-us-east-2  2026-04-10T14:35:17Z
  Shared with you
  ID                 Name  Region ID         Created At
  noisy-fire-212121  API   aws-eu-central-1  2026-04-22T18:41:13Z
  ```

  In the default table, your currently linked project (the one recorded in `.neon`) is marked `[current]` next to its name.

List all projects belonging to a specific organization:

```bash
neon projects list --org-id org-xxxx-xxxx
```

List projects that can be recovered (deleted within the last 7 days):

```bash
neon projects list --recoverable-only
```

```text filename="Output"
Projects
ID                   Name       Region ID      Created At            Deleted At            Recoverable Until
crimson-voice-12345  myproject  aws-us-east-2  2026-04-15T11:17:30Z  2026-04-16T14:22:15Z  2026-04-23T14:22:15Z
```

## neon projects create

Creates a Neon project.

```bash
neon projects create [options]
```

| Option                       | Description                                                                                                                                                                                | Type    | Default            | Required |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ------------------ | :------: |
| `--block-public-connections` | When set, connections from the public internet are disallowed. This supersedes the AllowedIPs list. This parameter is under active development and its semantics may change in the future. | boolean | —                  |    No    |
| `--block-vpc-connections`    | When set, connections using VPC endpoints are disallowed. This parameter is under active development and its semantics may change in the future.                                           | boolean | —                  |    No    |
| `--cu`                       | The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").                                                                               | string  | —                  |    No    |
| `--database`                 | The database name. If not specified, the default database name, `neondb`, will be used.                                                                                                    | string  | neondb             |    No    |
| `--hipaa`                    | Enable HIPAA compliance for the project.                                                                                                                                                   | boolean | —                  |    No    |
| `--name`                     | The project name. If not specified, the name will be identical to the generated project ID                                                                                                 | string  | project ID         |    No    |
| `--org-id`                   | The project's organization ID                                                                                                                                                              | string  | —                  |    No    |
| `--pg-version`               | Major PostgreSQL version (14–19). Version 19 is available only in regions where it has been enabled.                                                                                       | number  | —                  |    No    |
| `--psql`                     | Connect to a new project via psql                                                                                                                                                          | boolean | `false`            |    No    |
| `--region-id`                | The region ID. Possible values: aws-us-west-2, aws-ap-southeast-1, aws-ap-southeast-2, aws-eu-central-1, aws-us-east-2, aws-us-east-1, azure-eastus2                                       | string  | —                  |    No    |
| `--role`                     | The role name. If not specified, the default role name, `{database_name}_owner`, will be used.                                                                                             | string  | \{database}\_owner |    No    |
| `--secrets`                  | Include connection credentials in command output. Use --no-secrets to omit them                                                                                                            | boolean | `true`             |    No    |
| `--set-context`              | Set the current context to the new project                                                                                                                                                 | boolean | `false`            |    No    |

The `--region-id` value defaults to `aws-us-east-2` if not specified. `--block-public-connections` and `--block-vpc-connections` are part of [Private Networking](https://neon.com/docs/guides/neon-private-networking); `--hipaa` enables [HIPAA compliance](https://neon.com/docs/security/hipaa) for the project.

**Note:**

Neon projects created using the CLI use the default Postgres version, which is Postgres 18. To create a project with a different Postgres version, pass `--pg-version`:

```bash
neon projects create --name mynewproject --pg-version 17
```

You can also enable logical replication for an existing project with `neon projects update <project-id> --enable-logical-replication` (add `--yes` to skip the confirmation prompt), and create protected branches with `neon branches create --protected`.

Create a project with a user-defined name in a specific region:

```bash
neon projects create --name mynewproject --region-id aws-us-west-2
```

```text filename="Output"
Project
ID          muddy-wood-123456
Name        mynewproject
Region ID   aws-us-west-2
Created At  2026-07-09T17:04:29Z

Connection URIs
Connection URI
postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

**Tip:** The Neon CLI provides a `neon connection-string` command you can use to extract a connection URI programmatically. See [the connection-string command](https://neon.com/docs/cli/connection-string).

Create a project with a specific Postgres major version:

```bash
neon projects create --name mynewproject --pg-version 17
```

Omit the connection string from the output, keeping it out of terminal scrollback and CI logs:

```bash
neon projects create --name mynewproject --no-secrets
```

Needs Neon CLI 4.9.0+; older versions ignore `--no-secrets` and still print the connection string.

- Create a project with `--output json`, which returns the full project response data and is the recommended format for scripts and agents. The output below was captured on an earlier CLI version; new projects report `"pg_version": 18`.

  ```bash
  neon projects create --output json
  ```

  <details>

  <summary>Show output</summary>

  ```json
  {
    "project": {
      "data_storage_bytes_hour": 0,
      "data_transfer_bytes": 0,
      "written_data_bytes": 0,
      "compute_time_seconds": 0,
      "active_time_seconds": 0,
      "cpu_used_sec": 0,
      "id": "long-wind-77910944",
      "platform_id": "aws",
      "region_id": "aws-us-east-2",
      "name": "long-wind-77910944",
      "provisioner": "k8s-pod",
      "default_endpoint_settings": {
        "autoscaling_limit_min_cu": 1,
        "autoscaling_limit_max_cu": 1,
        "suspend_timeout_seconds": 0
      },
      "pg_version": 17,
      "proxy_host": "us-east-2.aws.neon.tech",
      "branch_logical_size_limit": 204800,
      "branch_logical_size_limit_bytes": 214748364800,
      "store_passwords": true,
      "creation_source": "neon",
      "history_retention_seconds": 604800,
      "created_at": "2026-08-04T16:16:45Z",
      "updated_at": "2026-08-04T16:16:45Z",
      "consumption_period_start": "0001-01-01T00:00:00Z",
      "consumption_period_end": "0001-01-01T00:00:00Z",
      "owner_id": "e56ad68e-7f2f-4d74-928c-9ea25d7e9864"
    },
    "connection_uris": [
      {
        "connection_uri": "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require",
        "connection_parameters": {
          "database": "dbname",
          "password": "AbC123dEf",
          "role": "alex",
          "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
          "pooler_host": "ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech"
        }
      }
    ]
  }
  ```

  </details>

Create a project and connect to it with `psql` immediately. Arguments after `--` are passed through to psql, so you can run an `.sql` file or a query on creation:

```bash
neon projects create --psql
neon projects create --psql -- -f dump.sql
neon projects create --psql -- -c "SELECT version()"
```

Create a project and set the Neon CLI project context to it:

```bash
neon projects create --set-context
```

## neon projects update

Updates a Neon project. The `<id>` is the project ID, which you can obtain by listing your projects or from the **Settings** page in the Neon Console.

```bash
neon projects update <id> [options]
```

| Option                         | Description                                                                                                                                                                                                                                                | Type    | Default | Required |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--block-public-connections`   | When set, connections from the public internet are disallowed. This supersedes the AllowedIPs list. This parameter is under active development and its semantics may change in the future. Use --block-public-connections=false to set the value to false. | boolean | —       |    No    |
| `--block-vpc-connections`      | When set, connections using VPC endpoints are disallowed. This parameter is under active development and its semantics may change in the future. Use --block-vpc-connections=false to set the value to false.                                              | boolean | —       |    No    |
| `--cu`                         | The number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").                                                                                                                                               | string  | —       |    No    |
| `--enable-logical-replication` | Enable logical replication for all project endpoints. This suspends active endpoints and cannot be disabled.                                                                                                                                               | boolean | —       |    No    |
| `--hipaa`                      | Enable HIPAA compliance for the project.                                                                                                                                                                                                                   | boolean | —       |    No    |
| `--name`                       | The project name                                                                                                                                                                                                                                           | string  | —       |    No    |
| `--yes`                        | Skip the confirmation prompt when enabling logical replication.                                                                                                                                                                                            | boolean | `false` |    No    |

`--block-public-connections`, `--block-vpc-connections`, and `--hipaa` behave as described under [projects create](https://neon.com/docs/cli/projects#create).

Update the project name:

```bash
neon projects update muddy-wood-123456 --name dev_project_1
```

```text filename="Output"
ID          muddy-wood-123456
Name        dev_project_1
Region ID   aws-us-west-2
Created At  2026-07-09T17:04:29Z
```

Block connections from the public internet (see [restrict public internet access](https://neon.com/docs/guides/neon-private-networking#restrict-public-internet-access)):

```bash
neon projects update orange-credit-12345678 --block-public-connections=true
```

Enable [logical replication](https://neon.com/docs/guides/logical-replication-neon) for the project. This suspends active endpoints and cannot be disabled, so `--yes` skips the confirmation prompt:

```bash
neon projects update orange-credit-12345678 --enable-logical-replication --yes
```

## neon projects delete

Deletes a Neon project. The `<id>` is the project ID.

```bash
neon projects delete <id> [options]
```

```bash
neon projects delete muddy-wood-123456
```

```text filename="Output"
ID          muddy-wood-123456
Name        dev_project_1
Region ID   aws-us-west-2
Created At  2026-07-09T17:04:29Z
```

Verify the deletion with `neon projects list`.

## neon projects recover

Recovers a deleted project within the deletion recovery period. The `<id>` is the project ID, which you can obtain by listing recoverable projects with `neon projects list --recoverable-only`.

```bash
neon projects recover <id> [options]
```

```bash
neon projects recover crimson-voice-12345678
```

```text filename="Output"
ID          crimson-voice-12345678
Name        myproject
Region ID   aws-us-east-2
Created At  2026-04-15T11:17:30Z
```

For details on what's recovered and what requires reconfiguration after recovery, see [Recover a deleted project](https://neon.com/docs/manage/projects#recover-a-deleted-project).

## neon projects get

Retrieves details about a Neon project. The `<id>` is the project ID.

```bash
neon projects get <id> [options]
```

```bash
neon projects get muddy-wood-123456
```

```text filename="Output"
Project
Name               dev_project_1
ID                 muddy-wood-123456
Region ID          aws-us-west-2
Postgres Version   18
Organization       org-xxxxxxxx-xxxx
Default Compute    0.25 CU
History Retention  6 hours
Created At         2026-07-09T17:04:29Z
Updated At         2026-07-09T17:04:29Z
```

The table shows a detail view: Postgres version, organization, default compute range, and history retention alongside the identifiers. For the complete project record, including all settings and quotas, use `--output json`.

--- [Document source](https://neon.com/docs/cli/psql.md) ---

> Summary: Covers the usage of the `psql` command in the Neon CLI to open a psql session against a branch in your Neon project, including pooled connections and time-travel support.

# Neon CLI command: psql

Connect to a Neon database via psql

Last updated: 2026-11-05

The `psql` command connects to a database in your Neon project using the `psql` client. It builds a connection string for the specified branch (or the default branch from your [context file](https://neon.com/docs/cli/link)) and launches `psql`, equivalent to running [`neon connection-string --psql`](https://neon.com/docs/cli/connection-string) as a dedicated top-level command. It's also available as [`neon postgres psql`](https://neon.com/docs/cli/postgres#psql).

If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`. `--role-name` and `--database-name` are needed only when the branch has more than one role or database.

## Usage

```bash
neon psql [branch] [options] [-- psql-args]
```

The `[branch]` is the branch name or ID. If omitted, the default branch from your context (or the project's default branch) is used. You can also use the point-in-time format `branch@timestamp` or `branch@lsn` for [time travel](https://neon.com/docs/guides/time-travel-assist) connections. Arguments after `--` are forwarded to `psql`.

## Options

| Option            | Description                                                             | Type    | Default   | Required |
| ----------------- | ----------------------------------------------------------------------- | ------- | --------- | :------: |
| `--database-name` | Database name                                                           | string  | —         |    No    |
| `--endpoint-type` | Endpoint type                                                           | string  | —         |    No    |
| `--pooled`        | Use pooled connection                                                   | boolean | `false`   |    No    |
| `--project-id`    | Project ID                                                              | string  | —         |    No    |
| `--role-name`     | Role name                                                               | string  | —         |    No    |
| `--ssl`           | SSL mode Possible values: `require`, `verify-ca`, `verify-full`, `omit` | string  | `require` |    No    |

`neon psql` uses the native `psql` binary from your `$PATH` if one is available, and otherwise falls back to a built-in TypeScript implementation, so no PostgreSQL client tools installation is required. The built-in implementation is a full port, not a simplified subset: it supports SCRAM-SHA-256 authentication, backslash commands (`\d`, `\dt`, `\d+`, etc.), tab completion, command history, and COPY. It's verified against Postgres 14 through 18.

To force the built-in implementation in CI or other environments where native `psql` is present but you want consistent behavior, set `NEONCTL_PSQL_FALLBACK=1`.

## Examples

Connect to the default branch:

```bash
neon psql
```

Connect to a named branch. Projects created with the CLI or API get a default branch named `main`; Console-created projects use `production` (run `neon branches list` if you're unsure):

```bash
neon psql main
```

Run a single query:

```bash
neon psql main -- -c "SELECT version()"
```

Run an SQL file:

```bash
neon psql main -- -f dump.sql
```

Connect to a branch at a specific point in time:

```bash
neon psql main@2024-01-01T00:00:00Z
```

Use a pooled connection:

```bash
neon psql --pooled
```

--- [Document source](https://neon.com/docs/cli/quickstart.md) ---

> Summary: The Neon CLI quickstart installs neon on macOS, Windows, or Linux via Homebrew, npm, or bun, then authenticates using browser-based `neon login` or a personal API key. Use this page when setting up terminal access to Neon for the first time, before working through the full CLI reference. It also covers the `.neon` context file (`neon link`) to avoid repeating `--project-id` and `--org-id` flags, shell tab completion, and first commands like `neon projects list`, `neon branches create`, and `neon connection-string`.

# Neon CLI quickstart

Get set up with the Neon CLI in just a few steps

Last updated: 2026-09-18

The Neon CLI lets you manage Neon directly from the terminal. This guide helps you set up and start using it. The CLI is invoked as `neon`; `neonctl` is an alias for `neon`, so commands work with either name.

## Install the CLI

Choose your platform and install the Neon CLI:

**macOS**

**Install with Homebrew**

```bash
brew install neonctl
```

**Install via npm**

```shell
npm i -g neon
```

**Install with bun**

```bash
bun install -g neon
```

**Windows**

**Install via npm**

```shell
npm i -g neon
```

**Install with bun**

```bash
bun install -g neon
```

**Linux**

**Install via npm**

```shell
npm i -g neon
```

**Install with bun**

```bash
bun install -g neon
```

Verify the installation by checking the CLI version:

```bash
neon --version
```

For the latest version, refer to the [Neon CLI GitHub repository](https://github.com/neondatabase/neon-pkgs/tree/main/packages/cli).

## Authenticate

Authenticate with your Neon account using one of these methods:

**Web Authentication (recommended)**

Run the command below to authenticate through your browser:

```bash
neon login
```

This opens a browser window where you can authorize the CLI to access your Neon account.

**API Key Authentication**

Alternatively, use a personal Neon API key, which you can create in the Neon Console. See [Create a personal API key](https://neon.com/docs/manage/api-keys#create-a-personal-api-key).

```bash
neon projects list --api-key <your-api-key>
```

To avoid entering your API key with each command, set it as an environment variable:

```bash
export NEON_API_KEY=<your-api-key>
```

For more about authenticating, see [Neon CLI commands: login](https://neon.com/docs/cli/login).

## Link your project

The easiest way to set up CLI context is with [`neon link`](https://neon.com/docs/cli/link). It guides you through organization and project selection and writes a `.neon` context file in your project directory.

```bash
neon link
```

You can also link non-interactively for scripts and CI. `link` writes a complete context, so pin a branch with `--branch` (or pass `-y` to pin the project's default branch):

```bash
neon link --org-id <your-org-id> --project-id <your-project-id> --branch main
```

**Tip:** If you run a CLI command without an organization context, the CLI prompts you to select an organization and offers to save it as your default, creating a `.neon` context file automatically.

**Tip:** Once linked, you can run CLI commands from any subdirectory of your project; the CLI walks up parent folders to find the `.neon` file. The file is also automatically added to `.gitignore` so it's not committed by accident.

**Info:** You can find your organization ID in the Neon Console by selecting your organization and navigating to **Settings**. You can find your Neon project ID by opening your project in the Neon Console and navigating to **Settings** > **General**.

Either form of `neon link` creates a `.neon` file in your current directory with your project context.

```bash
cat .neon
```

```json
{
  "projectId": "broad-surf-52155946",
  "orgId": "org-solid-base-83603457",
  "branch": "main"
}
```

**Note: Deprecated**

Earlier versions of the CLI used [`neon set-context`](https://neon.com/docs/cli/set-context) to write the `.neon` file directly. That command is deprecated in favor of `neon link`, prints a deprecation warning when you run it, and may be removed in a future release. Use `neon link` for new workflows.

## Enable shell completion

Set up autocompletion to make using the CLI faster:

**Bash**

```bash
neon completion >> ~/.bashrc
source ~/.bashrc
```

**Zsh**

```bash
neon completion >> ~/.zshrc
source ~/.zshrc
```

Now you can press **Tab** to complete Neon CLI commands and options. For further details, see [Neon CLI commands: completion](https://neon.com/docs/cli/completion).

## Common operations

### List your projects

```bash
neon projects list
```

If no organization context is set, the CLI prompts you to select an organization.

For more about the `projects` command, see [Neon CLI commands: projects](https://neon.com/docs/cli/projects).

### Create a branch

```bash
neon branches create --name <branch-name>
```

Set your project context or specify `--project-id <your-project-id>` if you have more than one Neon project.

To switch the active branch in your context file, use [`neon checkout`](https://neon.com/docs/cli/checkout):

```bash
neon checkout <branch>
```

For more about the `branches` command, see [Neon CLI commands: branches](https://neon.com/docs/cli/branches).

### Get a connection string

Get the connection string for the default branch in your project:

```bash
neon connection-string
```

For a specific branch, specify the branch name:

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

To connect with `psql` directly, use the dedicated [`neon psql`](https://neon.com/docs/cli/psql) command:

```bash
neon psql
```

For more about the `connection-string` command, see [Neon CLI commands: connection-string](https://neon.com/docs/cli/connection-string).

## Next steps

Now that you're set up with the Neon CLI, you can:

- Create more Neon projects with `neon projects create`
- Manage your branches with various `neon branches` commands such as `reset`, `restore`, `rename`, `schema-diff`, and more
- Create and manage databases with `neon databases` commands
- Create and manage roles with `neon roles` commands
- View the full set of Neon CLI commands available to you with `neon --help`

For more details on all available commands, see the [CLI Reference](https://neon.com/docs/cli).

--- [Document source](https://neon.com/docs/cli/realtime.md) ---

> Summary: The Neon CLI `neon realtime` command manages Neon Realtime on a database branch. Use `enable` to provision Realtime and set the browser origins allowed to connect, `disable` to remove it, `rotate-secret` to replace its shared secret, and `subscribe` to stream a live SQL query.

# Neon CLI command: realtime

Manage Neon Realtime and subscribe to live queries from the CLI

Last updated: 2026-11-05

The `realtime` command enables and disables [Neon Realtime](https://neon.com/docs/realtime/overview) on a branch and rotates the branch's Realtime secret. Once Realtime is on, you can stream a live SQL query's results with `neon realtime subscribe`, and [`neon env pull`](https://neon.com/docs/cli/env) writes the branch's `NEON_REALTIME_URL` and `NEON_REALTIME_SECRET` to your `.env`. To manage Realtime declaratively instead, add it to your `neon.ts` with [`neon config add realtime`](https://neon.com/docs/cli/config#add-realtime).

Subcommands: [disable](https://neon.com/docs/cli/realtime#disable), [enable](https://neon.com/docs/cli/realtime#enable), [rotate-secret](https://neon.com/docs/cli/realtime#rotate-secret), [subscribe](https://neon.com/docs/cli/realtime#subscribe)

If `--project-id` is omitted, the CLI reads it from your [context file](https://neon.com/docs/cli/link) or auto-selects your only project. If `--branch` is omitted, it uses the context file's branch, or the project's default branch.

## neon realtime enable

Requests Realtime provisioning for a branch. Provisioning finishes in the background, usually within a few seconds. Run it again on a branch that already has Realtime to replace its allowed origins with the ones you pass. Without `--allowed-origin`, a re-run keeps the existing origins.

```bash
neon realtime enable [options]
```

| Option             | Description                                                   | Type   | Default | Required |
| ------------------ | ------------------------------------------------------------- | ------ | ------- | :------: |
| `--allowed-origin` | Allowed browser origin (repeatable). "\*" allows every origin | array  | —       |    No    |
| `--branch`         | Branch ID or name                                             | string | —       |    No    |
| `--project-id`     | Project ID                                                    | string | —       |    No    |

`--allowed-origin` sets the browser origins allowed to connect. Repeat the flag for each origin, up to 16. Each value must be `*`, which allows every origin, or an `http` or `https` origin with no path, query, or fragment, such as `https://app.example.com`. `*` can't be combined with other origins. The CLI checks the values before it sends the request.

By default, any browser origin can connect. Pass `--allowed-origin` to limit connections to the origins you list. A new branch starts with its parent's list. Child branches created from a Realtime-enabled branch have Realtime enabled automatically. A new list can take about a minute to apply after the change finishes. Allowed origins only restrict browsers: a client that sends no `Origin` header, such as a server, can connect either way.

```bash
neon realtime enable --allowed-origin https://app.example.com --allowed-origin http://localhost:3000
```

```text
Realtime enable requested for branch br-cool-darkness-123456.
```

## neon realtime disable

Requests Realtime deprovisioning for a branch.

```bash
neon realtime disable [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon realtime disable
```

```text
Realtime disable requested for branch br-cool-darkness-123456.
```

Disabling also discards the branch's Realtime secret, so apps using that branch's `NEON_REALTIME_SECRET` stop working. If you enable Realtime again later, the branch gets a new secret, so pull the env vars again.

After you disable Realtime, `neon realtime subscribe` on that branch fails with an error that points you back to `neon realtime enable`.

## neon realtime rotate-secret

Requests a new Realtime shared secret for a branch. Rotation runs in the background: until it finishes, the current secret keeps working. Once it finishes, the new secret takes over and the old one stops working, so update every app that uses it.

```bash
neon realtime rotate-secret [options]
```

| Option         | Description                                     | Type    | Default | Required |
| -------------- | ----------------------------------------------- | ------- | ------- | :------: |
| `--wait`       | Wait for the Realtime secret rotation to finish | boolean | `true`  |    No    |
| `--branch`     | Branch ID or name                               | string  | —       |    No    |
| `--project-id` | Project ID                                      | string  | —       |    No    |

By default, the command waits up to a minute for the rotation to finish, then reminds you to pull the new secret. If the wait times out, the command exits with an error, but the rotation may still be in progress. With `--no-wait`, it prints only the "rotation requested" line and returns right away. If the rotation is still running, `neon env pull` waits for it to finish, then writes the new secret.

```bash
neon realtime rotate-secret
```

```text
Realtime secret rotation requested for branch br-cool-darkness-123456.
Realtime secret rotation completed for branch br-cool-darkness-123456.
Run neon env pull --service realtime to update NEON_REALTIME_SECRET.
```

The command doesn't print the new secret. Write the new `NEON_REALTIME_SECRET` to your env file with [`neon env pull`](https://neon.com/docs/cli/env):

```bash
neon env pull --service realtime
```

Every `rotate-secret` run replaces the secret, so only repeat the command when you want another rotation.

## neon realtime subscribe

Runs a `SELECT` query as a live subscription and prints its results as they change. Use it to watch a table while you develop, or to check what a Realtime client would receive. For a guided walkthrough, see the [Realtime quickstart](https://neon.com/docs/realtime/quickstart). The branch needs Realtime enabled first: run `neon realtime enable`, or declare it in `neon.ts` with [`neon config add realtime`](https://neon.com/docs/cli/config#add-realtime) and apply.

```bash
neon realtime subscribe "<query>" [options]
```

| Option         | Description                      | Type    | Default | Required |
| -------------- | -------------------------------- | ------- | ------- | :------: |
| `--branch`     | Branch ID or name                | string  | —       |    No    |
| `--changes`    | Show raw rows and changes events | boolean | `false` |    No    |
| `--project-id` | Project ID                       | string  | —       |    No    |

The CLI resolves the branch's Realtime URL, secret, and database name for you, the same values [`neon env pull`](https://neon.com/docs/cli/env) writes, so you don't need a `.env` file first. If Realtime is still provisioning, it waits until it's ready. Quote the query so your shell passes it as one argument. If `--project-id` is omitted, it reads it from your [context file](https://neon.com/docs/cli/link) or auto-selects your only project. If `--branch` is omitted, it uses the context file's branch, or the project's default branch.

The subscription runs until you press Ctrl+C, or until the server closes it or reports an error.

### Output

The default table output is an append-only log, so it doesn't take over your terminal. It opens with a header naming the project, branch, database, mode, and query, then prints:

- The initial result once, as a table.
- One entry per transaction, labeled with its transaction ID and a `+inserted ~updated -deleted` count, listing each changed row with its change type. A deleted row shows its last known values. A row that changes position in an ordered result shows as `↔ move` with its values, and the count ends with `↔` and the number of rows that moved.
- Connection state changes, such as connecting, live, and stale.

Every entry starts with a UTC timestamp. The server can send a complete `rows` replacement instead of incremental `changes` at any point, and then `realtime subscribe` prints the full result again. Some queries, such as ones with `ORDER BY`, can get a complete replacement for a change.

With `--changes`, it prints the raw events instead: a `rows` event with the complete current result, each row carrying a row ID, followed by `changes` events that list each change's type (`upsert`, `remove`, or `move`), row ID, and row. In table output, a `move` also shows `after_row_id`, the ID of the row it now follows, or `(head)` when it moved to the first position. A `rows` event replaces the full row set and invalidates earlier row IDs.

With `--output json`, each event is one JSON object per line. With `--output yaml`, each event is a separate YAML document. Each event has a `type` of `snapshot` (the default mode), or `rows` or `changes` (with `--changes`). Machine-readable output carries only the events: the header and connection states are terminal-only.

### Examples

Print the initial result, then a log of each transaction:

```bash
neon realtime subscribe "SELECT * FROM items"
```

Here, a row is inserted, another is renamed, the new row is deleted, and then one transaction inserts a row and renames another:

<details>

<summary>Show output</summary>

```text
Live query
Project   cool-darkness-12345678
Branch    dev (br-small-cell-a1b2c3d4)
Database  neondb
Mode      Materialized result
Query     SELECT * FROM items
[2026-10-13T13:49:35.168Z] Connecting…

[2026-10-13T13:49:35.725Z] Initial snapshot · 2 rows
ID  Name
1   apple
2   banana
[2026-10-13T13:49:35.726Z] Live — waiting for changes.

[2026-10-13T13:49:42.349Z] Transaction 15379 · +1 ~0 -0
Change    ID  Name
+ insert  3   cherry

[2026-10-13T13:49:45.992Z] Transaction 15380 · +0 ~1 -0
Change    ID  Name
~ update  2   blueberry

[2026-10-13T13:49:49.636Z] Transaction 15381 · +0 ~0 -1
Change    ID  Name
- delete  3   cherry

[2026-10-13T13:49:53.284Z] Transaction 15382 · +1 ~1 -0
Change    ID  Name
+ insert  4   date
~ update  1   apricot
```

</details>

Print the raw `rows` and `changes` events:

```bash
neon realtime subscribe --changes "SELECT * FROM items"
```

Here, a row is inserted, updated, and then deleted, one transaction each:

<details>

<summary>Show output</summary>

```text
Live query
Project   cool-darkness-12345678
Branch    dev (br-small-cell-a1b2c3d4)
Database  neondb
Mode      Raw changes
Query     SELECT * FROM items
[2026-10-13T13:48:40.801Z] Connecting…

[2026-10-13T13:48:41.461Z] Rows · 2 rows
Row ID                                                            Row
97254c8a1b75b7e21a05f98973614ea5af20ae9f4d481389eddb304c9b331ecf  {"id":1,"name":"apple"}
3045adcead9109b462b3c0e501e1c78c48b6cdbeb28bd3d3e01b83a61eaee302  {"id":2,"name":"banana"}
[2026-10-13T13:48:41.462Z] Live — waiting for changes.

[2026-10-13T13:48:48.072Z] Transaction 15370 · 1 upsert, 0 removals
Type    Row ID                                                            Row
upsert  1257d5759a0894512f6859dd60b504e69cbf6f8d9d4d977ee9b3b396661928bf  {"id":3,"name":"cherry"}

[2026-10-13T13:48:51.750Z] Transaction 15371 · 1 upsert, 0 removals
Type    Row ID                                                            Row
upsert  3045adcead9109b462b3c0e501e1c78c48b6cdbeb28bd3d3e01b83a61eaee302  {"id":2,"name":"blueberry"}

[2026-10-13T13:48:55.376Z] Transaction 15372 · 0 upserts, 1 removal
Type    Row ID
remove  1257d5759a0894512f6859dd60b504e69cbf6f8d9d4d977ee9b3b396661928bf
```

</details>

Stream events as newline-delimited JSON, for example to pipe into another tool. Each event is a full snapshot of the result:

```bash
neon realtime subscribe "SELECT * FROM items ORDER BY id" --output json
```

```json
{"type":"snapshot","rows":[{"id":1,"name":"apple"},{"id":2,"name":"banana"}]}
{"type":"snapshot","rows":[{"id":1,"name":"apple"},{"id":2,"name":"banana"},{"id":3,"name":"cherry"}]}
{"type":"snapshot","rows":[{"id":1,"name":"apple"},{"id":2,"name":"blueberry"},{"id":3,"name":"cherry"}]}
```

--- [Document source](https://neon.com/docs/cli/roles.md) ---

> Summary: The `neon roles` CLI command lists, inspects, creates, and deletes database roles in a Neon project and resets their passwords. Its subcommands target a specific branch or the project default. Use it when you need to add an admin or a scoped read-only or read-write role, create a passwordless role with `--no-login`, rotate a password, or remove a role from the command line. Role names are capped at 63 bytes; commands require the Neon CLI and either browser-based auth or an API key.

# Neon CLI command: roles

List, inspect, create, and delete database roles, and reset their passwords

Last updated: 2026-11-05

From the terminal, the `roles` command lists, inspects, creates, and deletes roles in a Neon project, and resets their passwords. It's also available as [`neon postgres roles`](https://neon.com/docs/cli/postgres#roles). For information about roles in Neon, see [Manage roles](https://neon.com/docs/manage/roles). If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

Subcommands: [create](https://neon.com/docs/cli/roles#create), [delete](https://neon.com/docs/cli/roles#delete), [get](https://neon.com/docs/cli/roles#get), [list](https://neon.com/docs/cli/roles#list), [reset-password](https://neon.com/docs/cli/roles#reset-password)

## neon roles list

Lists roles. If you don't specify a branch ID or name with `--branch`, the command targets the project's default branch. This applies to all `roles` subcommands.

```bash
neon roles list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

List roles with the default `table` output format:

```bash
neon roles list
```

```text filename="Output"
Roles on main
Name          Created At
neondb_owner  2026-06-19T18:27:19Z
```

The table is titled with the branch the roles belong to, so you can tell at a glance which branch you're looking at.

List roles with the `--output` format set to `json`:

```bash
neon roles list --output json
```

<details>

<summary>Show output</summary>

```json
[
  {
    "branch_id": "br-odd-frog-123456",
    "name": "neondb_owner",
    "protected": false,
    "created_at": "2026-06-28T10:17:28Z",
    "updated_at": "2026-06-28T10:17:28Z"
  }
]
```

</details>

## neon roles create

Creates a role. The role name cannot exceed 63 bytes.

```bash
neon roles create [options]
```

| Option         | Description                                                                                                                                                                                                                                                 | Type    | Default | Required |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--access`     | admin joins neon\_superuser. read\_only grants SELECT; read\_write adds INSERT, UPDATE, DELETE. Scoped roles are created with SQL as the database owner and cover tables that owner owns, now and later Possible values: `admin`, `read_only`, `read_write` | string  | `admin` |    No    |
| `--database`   | Database a read\_only or read\_write role is scoped to. Defaults to the branch's only database                                                                                                                                                              | string  | —       |    No    |
| `--name`       | Role name                                                                                                                                                                                                                                                   | string  | —       |    Yes   |
| `--no-login`   | Create a passwordless role that cannot login                                                                                                                                                                                                                | boolean | —       |    No    |
| `--schema`     | Schema a read\_only or read\_write role can use. Repeat for more. Defaults to public                                                                                                                                                                        | array   | —       |    No    |
| `--branch`     | Branch ID or name                                                                                                                                                                                                                                           | string  | —       |    No    |
| `--project-id` | Project ID                                                                                                                                                                                                                                                  | string  | —       |    No    |

```bash
neon roles create --name sally
```

```text filename="Output"
Role created on main
Name        sally
Password    npg_aBcDeFgH1234
Created At  2026-06-20T00:43:17Z
```

The create output includes the password Neon generated for the new role. Neon returns it only once, so copy it now, or run [`neon roles reset-password`](https://neon.com/docs/cli/roles#reset-password) later to get a new one. A `--no-login` role has no password, so no `Password` row appears.

By default, a new role joins `neon_superuser`, which makes it an admin on every database. Pass `--access read_only` for a role that can only read, or `--access read_write` for one that can also insert, update, and delete rows. A scoped role applies to one database. Name it with `--database`, or leave it out when the branch has only one. Its access is limited to the `public` schema unless you pass `--schema`, and to tables owned by that database's owner, including tables the owner creates later.

```bash
neon roles create --name reporting --access read_only
```

```bash
neon roles create --name app_writer --access read_write --database neondb --schema public
```

`--database` and `--schema` work only with `--access read_only` or `--access read_write`.

## neon roles get

Shows a role's details. The `<role>` is the role name.

```bash
neon roles get <role> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon roles get reporting
```

```text filename="Output"
Name                   reporting
Branch ID              br-lively-sunset-123456
Protected              false
Authentication Method  password
Created At             2026-11-05T14:24:30Z
Updated At             2026-11-05T14:24:30Z
```

## neon roles reset-password

Generates a new password for a role and prints it. The old password stops working. By default the command waits until the compute applies the new password, so you can connect with it right away. With `--no-wait`, it returns as soon as the API accepts the reset.

```bash
neon roles reset-password <role> [options]
```

| Option         | Description                                                                                                   | Type    | Default | Required |
| -------------- | ------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--wait`       | Wait until the compute applies the new password. Use --no-wait to return as soon as the API accepts the reset | boolean | `true`  |    No    |
| `--branch`     | Branch ID or name                                                                                             | string  | —       |    No    |
| `--project-id` | Project ID                                                                                                    | string  | —       |    No    |

```bash
neon roles reset-password sally
```

```text filename="Output"
Password reset for sally on main
Name        sally
Password    npg_aBcDeFgH1234
Created At  2026-06-20T00:43:17Z
```

## neon roles delete

Deletes a role. The `<role>` is the role name.

```bash
neon roles delete <role> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon roles delete sally
```

```text filename="Output"
Role deleted from main
Name        sally
Created At  2026-06-20T00:43:17Z
```

--- [Document source](https://neon.com/docs/cli/set-context.md) ---

> Summary: The `set-context` Neon CLI command saves a project ID, organization ID, or branch to a `.neon` context file so subsequent commands run against that project or org without requiring `--project-id` or `--org-id` flags each time. Use this command when working repeatedly against the same project to eliminate repetitive flag passing across a CLI session. Context is stored in a `.neon` file (or a named `--context-file`) found by walking up the directory tree to the project root, supports multiple independent named files, and persists until reset with `neon set-context` or deleted manually.

# Neon CLI command: set-context

Set default project context for CLI sessions to avoid repeating project ID

Last updated: 2026-10-09

The `set-context` command sets a background context for your CLI sessions, so you don't have to specify the project ID in every command. The context is saved to a default `.neon` file in the current directory, or to a [named context file](https://neon.com/docs/cli/set-context#using-a-named-context-file) of your choice, and stays in place until you reset it or remove the file.

**Note: Deprecated**

`set-context` is deprecated in favor of [`neon link`](https://neon.com/docs/cli/link), which writes the same `.neon` context file. It still works but prints a deprecation warning when you run it, and may be removed in a future release. Use `neon link` to set project context; it verifies your inputs and infers your organization. For a write-without-checks behavior like `set-context` (for example, in scripts), use `neon link --no-checks` with `--org-id`, `--project-id`, and `--branch`. To switch branches, use [`neon checkout`](https://neon.com/docs/cli/checkout).

**Tip: How the CLI finds your `.neon` file**

When you run a command, the CLI starts in your current directory and checks for a `.neon` file. If it does not find one, it checks the parent directory, then the parent of that, and so on until it finds a `.neon` file or reaches your home directory. This means you can run commands from any subdirectory of a linked project without re-specifying `--project-id`.

To write context to a specific file or location, use `--context-file`.

## Usage

```bash
neon set-context [options]
```

To save the context to a file other than the default `.neon` file, add the global `--context-file <your_context_file>` option. You can switch contexts by providing different files.

## Options

| Option         | Description     | Type   | Default | Required |
| -------------- | --------------- | ------ | ------- | :------: |
| `--branch-id`  | Branch ID       | string | —       |    No    |
| `--org-id`     | Organization ID | string | —       |    No    |
| `--project-id` | Project ID      | string | —       |    No    |

Set at least one of these options.

## Using the default context file

Set the context to the default `.neon` file:

```bash
neon set-context --project-id patient-frost-50125040 --org-id org-bright-sky-12345678
```

List all branches for this project with `branches list`, without including `--project-id` or `--org-id`, even if you belong to multiple organizations or have multiple projects:

```bash
neon branches list
```

```text filename="Output"
Name            ID                      Current State  Expires At  Created At
development     br-raspy-meadow-123456  ready          never       2026-11-28T19:19:11Z
[default] main  br-curly-bar-123456     ready          never       2026-10-23T12:49:41Z
```

## Using a named context file

Set the context to the context file of your choice:

```bash
neon set-context --project-id plain-waterfall-84865553 --context-file Documents/MyContext
```

List all branches with `branches list`. The context file provides the project:

```bash
neon branches list --context-file Documents/MyContext
```

```text filename="Output"
Name            ID                         Current State  Expires At  Created At
development     br-soft-base-123456        ready          never       2026-11-21T18:41:47Z
[default] main  br-young-bush-123456       ready          never       2026-11-21T18:00:10Z
staging         br-billowing-union-123456  ready          never       2026-11-21T18:44:22Z
```

**Note:** These two `branches list` commands use independent contexts in the same account: the default `.neon` file points to `patient-frost-50125040`, while the named context file points to `plain-waterfall-84865553`. You can set as many context files as you'd like, using unique names or different directories.

## Setting context when creating a new project

Use `--set-context` to set the project context at creation time:

```bash
neon projects create --name MyLatest --set-context
```

This creates a hidden `.neon` file by default with the following context:

```json
{
  "projectId": "quiet-water-76237589"
}
```

Commands that would normally require `--project-id` now default to this context.

## Reset or remove context

To clear the current context, either:

1. Run the `set-context` command with no options:

   ```bash
   neon set-context
   ```

2. Delete the `.neon` file (or your custom `--context-file`):

   ```bash
   rm .neon
   # Or for a custom context file:
   rm your_context_file
   ```

## `.gitignore` on first create

The first time a `.neon` file is created in a directory, the CLI adds `.neon` to `.gitignore` in that same folder:

- If no `.gitignore` exists, the CLI creates one with a single `.neon` line.
- If `.gitignore` already exists, the CLI appends `.neon` only if it is not already listed.

This keeps local project settings out of git by default. If you want to commit `.neon` and share context with your team, remove the entry from `.gitignore`. The CLI will not re-add it when updating an existing `.neon` file.

**Note:** Neon does not save any confidential information to the context file (for example, auth tokens). You can safely commit this file to your repository or share with others.

--- [Document source](https://neon.com/docs/cli/skills.md) ---

> Summary: The Neon CLI `skills` command installs [Neon agent skills](/docs/ai/agent-skills) into your coding agents so they know how to work with Neon. Run it with no flags for an interactive walkthrough, or pass flags to pick the skills and agents and skip the prompts. Use `neon skills update` to refresh installed skills to their latest versions, and `neon skills status` to check whether they're current.

# Neon CLI command: skills

Install, update, and check Neon agent skills in your coding agents

Last updated: 2026-11-02

The `skills` command installs [Neon agent skills](https://neon.com/docs/ai/agent-skills) into your coding agents, so tools like Cursor and Claude Code know how to work with Neon's Postgres, AI Gateway, Object Storage, and Functions.

```bash
neon skills
```

[Install the Neon CLI](https://neon.com/docs/cli/install) with `npm i -g neon@latest`, or run it once with `npx neon@latest skills`.

With no flags it runs an interactive walkthrough: pick the agents, then the skills, then confirm. Pass flags to skip the prompts and script it. Without a terminal, pass `-y` or `--skill` to tell it which skills to install; `--agent` alone isn't enough.

**skills vs init:**

For the full setup, use [`neon init`](https://neon.com/docs/cli/init). For just one piece: `neon skills` (skills), [`neon plugins`](https://neon.com/docs/cli/plugins) (skills and MCP), or [`neon mcp`](https://neon.com/docs/cli/mcp) (MCP server).

`skills` runs via `npx`, so it needs Node.js 22.20.0+; older or missing Node stops the command with an upgrade message.

Subcommands: [status](https://neon.com/docs/cli/skills#status), [update](https://neon.com/docs/cli/skills#update)

## neon skills

```bash
neon skills [command] [options]
```

| Option          | Description                                                                                                                     | Type    | Default | Required |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--agent`, `-a` | Coding agent to install into (repeatable). Skips the agent picker. Values listed below                                          | array   | —       |    No    |
| `--global`      | Install user-level skills (skills CLI -g). Default is this directory                                                            | boolean | `false` |    No    |
| `--skill`, `-s` | Skill to install (repeatable). Skips the skill picker. Does not select agents. Values listed below                              | array   | —       |    No    |
| `--yes`, `-y`   | Skip prompts. Detected agents (project folders, else the host CLI agent). --global uses installed apps, else the host CLI agent | boolean | `false` |    No    |

### Choosing agents

Without `--agent`, the interactive command lists all supported agents, pre-selects the ones it detects, and lets you toggle the selection. In non-interactive mode, `-y` installs into every detected agent. Pass `--agent <name>` (repeatable) to name agents explicitly and skip the picker.

The supported agents are `antigravity`, `cline`, `cline-cli`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `factory-droid`, `fx`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `hermes`, `junie`, `kilo-code`, `kimi-code`, `kiro-cli`, `opencode`, `pi`, `vscode`, `windsurf`, and `zed`. A few also accept aliases (`claude` for `claude-code`, `copilot` for `vscode`, `gemini` for `gemini-cli`). Passing an unknown agent stops the command and prints the current supported list.

An agent that can't install skills is skipped with a warning. Agents that share a target collapse into one: Claude Desktop and Claude Code both write to `claude-code`, and VS Code and the GitHub Copilot CLI both write to `github-copilot`.

### Choosing skills

Without `--skill`, the interactive command lets you pick from the catalog, and `-y` installs the default set. Pass `--skill <name>` (repeatable) to name skills explicitly and skip the picker.

The available skills are:

| Skill                           | Installed by default |
| ------------------------------- | -------------------- |
| `neon`                          | Yes                  |
| `neon-ai-gateway`               | Yes                  |
| `neon-auth`                     | Yes                  |
| `neon-functions`                | Yes                  |
| `neon-object-storage`           | Yes                  |
| `neon-postgres`                 | Yes                  |
| `neon-realtime`                 | Yes                  |
| `neon-postgres-agent-platforms` | No                   |

Passing an unknown skill stops the command and prints the current supported list.

The list of installable skills is built into each CLI release, so a skill that Neon publishes after the version you installed won't appear until you upgrade the CLI.

### Directory vs user-level

By default `skills` installs into the current directory, so the setup travels with the repository. Pass `--global` to install user-level skills instead, which apply across your projects.

### Examples

Run the interactive install:

```bash
neon skills
```

Install non-interactively into every detected agent, using the default skills in the current directory:

```bash
neon skills -y
```

Install named skills into a specific agent. Naming both `--skill` and `--agent` skips every prompt:

```bash
neon skills -s neon -s neon-ai-gateway --agent cursor
```

```text filename="Output"
Skills
Scope           Skills                 Agents  Status
this directory  neon, neon-ai-gateway  cursor  installed

Wrote skills in this directory.
```

Install user-level skills that apply across your projects:

```bash
neon skills --global
```

## neon skills update

Updates every skill installed in the current directory to its latest version, or every user-level skill with `--global`. It takes neither `--agent` nor `--skill`; it updates whatever is already installed. When there's nothing to update, the status is `none` and the `Detail` column shows the reason.

```bash
neon skills update [options]
```

| Option          | Description                                                                                        | Type    | Default | Required |
| --------------- | -------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--global`      | Update user-level skills (skills CLI -g). Default is this directory                                | boolean | `false` |    No    |
| `--yes`, `-y`   | Skip the confirm prompt                                                                            | boolean | `false` |    No    |
| `--agent`, `-a` | Coding agent to install into (repeatable). Skips the agent picker. Values listed below             | array   | —       |    No    |
| `--skill`, `-s` | Skill to install (repeatable). Skips the skill picker. Does not select agents. Values listed below | array   | —       |    No    |

Update skills in the current directory without prompting:

```bash
neon skills update -y
```

```text filename="Output"
Skills
Scope           Status   Detail
this directory  updated  ✓ Updated 1 skill(s)
```

Update user-level skills:

```bash
neon skills update --global -y
```

## neon skills status

Checks whether the Neon skills installed in the current directory match their source, or the user-level ones with `--global`. Passing `--agent` or `--skill` returns an error.

The command reads the skills lock file that `neon skills` and `npx skills add` write: `skills-lock.json` in the current directory, or with `--global`, `~/.agents/.skill-lock.json` (`$XDG_STATE_HOME/skills/.skill-lock.json` when `XDG_STATE_HOME` is set). It checks only skills installed from a Neon repository, and leaves out skills pinned to a git ref. Skills installed through an agent's plugin marketplace aren't in these files, so they aren't checked.

Unlike installing and updating, `status` doesn't run `npx`, so it works without Node.js 22.20.0.

```bash
neon skills status [options]
```

| Option          | Description                                                                                                                     | Type    | Default | Required |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--global`      | Check user-level skills (skills CLI -g). Default is this directory                                                              | boolean | `false` |    No    |
| `--agent`, `-a` | Coding agent to install into (repeatable). Skips the agent picker. Values listed below                                          | array   | —       |    No    |
| `--skill`, `-s` | Skill to install (repeatable). Skips the skill picker. Does not select agents. Values listed below                              | array   | —       |    No    |
| `--yes`, `-y`   | Skip prompts. Detected agents (project folders, else the host CLI agent). --global uses installed apps, else the host CLI agent | boolean | `false` |    No    |

Each skill gets one of three statuses:

- `up to date`: the installed copy matches the source.
- `outdated`: the source has changed since you installed it. Run `neon skills update`, or `neon skills update --global` for user-level skills, to refresh it.
- `not found upstream`: the skill no longer exists in its source repository.

Check skills in the current directory:

```bash
neon skills status
```

```text filename="Output"
Skills
Scope           Skill            Status
this directory  neon             outdated
this directory  neon-ai-gateway  up to date
Update them: neon skills update -y
```

Check user-level skills:

```bash
neon skills status --global
```

Each run fetches the latest skill files from GitHub, so the command needs network access. If you hit the GitHub API rate limit, set `GITHUB_TOKEN` (or `GH_TOKEN`) and run the command again.

### Outdated skills warning

You don't have to run `status` to find out. Once a day, after a command succeeds, other `neon` commands print a warning that names the outdated skills in the current directory and at the user level, followed by the update command for each:

```text filename="Output"
WARNING: Neon agent skills have updates:
  user-level: neon-postgres, neon, neon-ai-gateway, neon-functions, neon-object-storage
  this directory: neon
Update them:
  neon skills update --global -y
  neon skills update -y
```

The check runs in the background, so a new result shows up on a later command. The warning also appears when the CLI runs without a terminal, so coding agents see it too. It doesn't appear with `--output json` or `--output yaml`, in CI, in the standalone binary, or for `neon skills` commands. Set `NO_UPDATE_NOTIFIER` to turn it off, along with the CLI's update notice.

--- [Document source](https://neon.com/docs/cli/snapshots.md) ---

> Summary: The Neon CLI `snapshots` command provides subcommands (create, list, get, update, delete, restore, finalize, schedule) to manage point-in-time snapshots of your Neon branches. Use this reference for exact flags and syntax: snapshot a branch at an LSN or timestamp, set an expiration, restore a snapshot into a new or existing branch, and configure an automatic backup schedule.

# Neon CLI command: snapshots

Create, list, restore, and schedule branch snapshots from the terminal

Last updated: 2026-09-29

The `snapshots` command creates, lists, updates, deletes, and restores snapshots of your Neon branches, and manages the automatic backup schedule of a branch. A snapshot captures the state of a branch at a point in time, so you can restore it later. For background on the feature, plans, and limits, see [Backup and restore](https://neon.com/docs/guides/backup-restore).

If `--project-id` is omitted, the CLI resolves it from your [context file](https://neon.com/docs/cli/link), auto-selects when your account has only one project, and otherwise asks you to pass `--project-id`.

Subcommands: [create](https://neon.com/docs/cli/snapshots#create), [delete](https://neon.com/docs/cli/snapshots#delete), [finalize](https://neon.com/docs/cli/snapshots#finalize), [get](https://neon.com/docs/cli/snapshots#get), [list](https://neon.com/docs/cli/snapshots#list), [restore](https://neon.com/docs/cli/snapshots#restore), [schedule](https://neon.com/docs/cli/snapshots#schedule), [update](https://neon.com/docs/cli/snapshots#update)

## neon snapshots create

Creates a snapshot from a branch. By default, it snapshots the head of the branch from your context or the project's default branch. Use `--lsn` or `--timestamp` to capture an earlier point within the branch's [history window](https://neon.com/docs/introduction/history-window); the two options are mutually exclusive.

```bash
neon snapshots create [options]
```

| Option           | Description                                                                                                                                                 | Type   | Default | Required |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--branch`, `-b` | Branch id or name to snapshot. Defaults to the branch in your context, or the project's default branch.                                                     | string | —       |    No    |
| `--expires-at`   | When the snapshot is automatically deleted (RFC 3339, e.g. 2025-12-31T23:59:59Z). Omit to keep it indefinitely.                                             | string | —       |    No    |
| `--lsn`          | Take the snapshot at this LSN (e.g. 0/1F3C8A0). Must fall within the branch's restore window. Mutually exclusive with --timestamp.                          | string | —       |    No    |
| `--name`         | A name for the snapshot                                                                                                                                     | string | —       |    No    |
| `--timestamp`    | Take the snapshot at this point in time (RFC 3339, e.g. 2025-01-01T00:00:00Z). Must fall within the branch's restore window. Mutually exclusive with --lsn. | string | —       |    No    |
| `--project-id`   | Project ID                                                                                                                                                  | string | —       |    No    |

Snapshot the head of a branch with a name:

```bash
neon snapshots create --branch main --name pre-migration
```

Snapshot a branch at a specific LSN and set an expiration:

```bash
neon snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2027-12-31T23:59:59Z
```

Snapshot a branch at a point in time:

```bash
neon snapshots create --branch main --timestamp 2025-01-01T00:00:00Z
```

Timestamps and expiration times use RFC 3339 format. `--timestamp` must be in the past and `--expires-at` in the future. Omit `--expires-at` to keep the snapshot until you delete it; a manual snapshot's expiration has no maximum, unlike the 35-day cap on [scheduled snapshots](https://neon.com/docs/cli/snapshots#schedule-set). Snapshot names must be unique within a project.

## neon snapshots list

Lists the snapshots in a project.

```bash
neon snapshots list [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon snapshots list
```

## neon snapshots get

Retrieves a snapshot by ID or name. An ID match wins over a name.

```bash
neon snapshots get <id> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon snapshots get snap-1234
```

## neon snapshots update

Renames a snapshot or changes its expiration. Use `--clear-expiration` to keep a snapshot indefinitely; it's mutually exclusive with `--expires-at`.

```bash
neon snapshots update <id> [options]
```

| Option               | Description                                                                           | Type    | Default | Required |
| -------------------- | ------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--clear-expiration` | Clear the expiration so the snapshot is kept indefinitely.                            | boolean | —       |    No    |
| `--expires-at`       | Set when the snapshot expires (RFC 3339). Mutually exclusive with --clear-expiration. | string  | —       |    No    |
| `--name`             | Rename the snapshot                                                                   | string  | —       |    No    |
| `--project-id`       | Project ID                                                                            | string  | —       |    No    |

Rename a snapshot:

```bash
neon snapshots update snap-1234 --name pre-migration
```

Clear a snapshot's expiration:

```bash
neon snapshots update snap-1234 --clear-expiration
```

## neon snapshots delete

Deletes a snapshot by ID or name.

```bash
neon snapshots delete <id> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon snapshots delete snap-1234
```

## neon snapshots restore

Restores a snapshot into a branch. By default, the restore is left un-finalized so you can inspect the restored branch first, then swap it in with [snapshots finalize](https://neon.com/docs/cli/snapshots#finalize). Pass `--finalize` to move computes onto the restored branch and swap it in for the target immediately.

```bash
neon snapshots restore <id> [options]
```

| Option            | Description                                                                                                                                                                                                                 | Type    | Default | Required |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--finalize`      | Finalize the restore immediately: move computes onto the restored branch and swap it in for the target. Without this, the restore is left un-finalized so you can inspect it first, then run `snapshots finalize <branch>`. | boolean | `false` |    No    |
| `--name`          | Name for the newly restored branch. Auto-generated when omitted.                                                                                                                                                            | string  | —       |    No    |
| `--target-branch` | Branch id or name to restore the snapshot onto. Defaults to the snapshot's source branch. Recommended when you intend to finalize (replace an existing branch).                                                             | string  | —       |    No    |
| `--project-id`    | Project ID                                                                                                                                                                                                                  | string  | —       |    No    |

Restore a snapshot to a new branch:

```bash
neon snapshots restore snap-1234 --name recovered
```

Restore onto an existing branch un-finalized to preview, then finalize:

```bash
neon snapshots restore snap-1234 --target-branch main
```

Restore onto a branch and swap it in immediately:

```bash
neon snapshots restore snap-1234 --target-branch main --finalize
```

## neon snapshots finalize

Finalizes a previewed snapshot restore, swapping the restored branch in for the target. Use this after running `snapshots restore` without `--finalize`. The argument is the ID of the restored branch that `snapshots restore` created, not the target branch. The `restore` command prints the exact `finalize` command to run.

```bash
neon snapshots finalize <branch> [options]
```

| Option         | Description                                                          | Type   | Default | Required |
| -------------- | -------------------------------------------------------------------- | ------ | ------- | :------: |
| `--name`       | Name to give the replaced (old) branch. Auto-generated when omitted. | string | —       |    No    |
| `--project-id` | Project ID                                                           | string | —       |    No    |

```bash
neon snapshots finalize br-summer-water-au2msxjn
```

The replaced (old) branch is kept under an auto-generated name unless you set one with `--name`.

## Snapshot schedule

The `snapshots schedule` subcommands get and set the automatic snapshot (backup) schedule of a branch.

Subcommands: [get](https://neon.com/docs/cli/snapshots#schedule-get), [set](https://neon.com/docs/cli/snapshots#schedule-set)

### neon snapshots schedule get

Gets a branch's automatic snapshot schedule.

```bash
neon snapshots schedule get [options]
```

| Option           | Description                                                                                 | Type   | Default | Required |
| ---------------- | ------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--branch`, `-b` | Branch id or name. Defaults to the branch in your context, or the project's default branch. | string | —       |    No    |
| `--project-id`   | Project ID                                                                                  | string | —       |    No    |

```bash
neon snapshots schedule get --branch main
```

### neon snapshots schedule set

Sets a branch's automatic snapshot schedule. Build a single-entry schedule with `--frequency` and its companion flags, or pass a full JSON schedule with `--schedule` for a multi-entry schedule (this overrides the single-entry flags).

Pick one `--frequency`; that choice determines which of `--day` and `--hour` you must also set. The supported frequencies are:

| `--frequency` | Also required     | `--day` range       |
| ------------- | ----------------- | ------------------- |
| `daily`       | `--hour` (0-23)   | not used            |
| `weekly`      | `--day`, `--hour` | 1-7 (Monday-Sunday) |
| `monthly`     | `--day`, `--hour` | 1-31                |

The server enforces these combinations, so a schedule missing a value its frequency needs is rejected with an error such as `daily schedules must specify the hour of the day`.

Use `--retention` with any frequency to set how long each snapshot is kept.

```bash
neon snapshots schedule set [options]
```

| Option           | Description                                                                                                                                                | Type   | Default | Required |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--branch`, `-b` | Branch id or name. Defaults to the branch in your context, or the project's default branch.                                                                | string | —       |    No    |
| `--day`          | Day of the week/month (1-31) to take the snapshot (used with --frequency).                                                                                 | number | —       |    No    |
| `--frequency`    | How often to take snapshots. Combine with --hour, --day, and --retention to build a single-entry schedule. Possible values: `daily`, `weekly`, `monthly`   | string | —       |    No    |
| `--hour`         | Hour of the day (0-23) to take the snapshot (used with --frequency).                                                                                       | number | —       |    No    |
| `--month`        | Month of the year (1-12) to take the snapshot (used with --frequency).                                                                                     | number | —       |    No    |
| `--retention`    | How long to keep each snapshot, in seconds (min 3600). Omit to keep indefinitely.                                                                          | number | —       |    No    |
| `--schedule`     | Full schedule as JSON, for multi-entry schedules, e.g. '\[\{"frequency":"daily","hour":3,"retention\_seconds":604800}]'. Overrides the single-entry flags. | string | —       |    No    |
| `--project-id`   | Project ID                                                                                                                                                 | string | —       |    No    |

Of the options above, `--month` is the exception: none of the supported frequencies read it, so setting it has no effect on when snapshots are taken.

Set a daily 03:00 snapshot kept for 7 days (604800 seconds):

```bash
neon snapshots schedule set --branch main --frequency daily --hour 3 --retention 604800
```

Set a weekly snapshot on Mondays at 04:00:

```bash
neon snapshots schedule set --branch main --frequency weekly --day 1 --hour 4
```

Set a multi-entry schedule with JSON:

```bash
neon snapshots schedule set --branch main --schedule '[{"frequency":"daily","hour":3},{"frequency":"weekly","day":1,"hour":4}]'
```

`--retention` is in seconds, from 3600 (1 hour) to 3024000 (35 days). Omit it and scheduled snapshots are kept for 35 days, the maximum. Manual snapshots created with [snapshots create](https://neon.com/docs/cli/snapshots#create) follow the opposite rule: they never expire unless you set `--expires-at`. See [Snapshot retention](https://neon.com/docs/guides/backup-restore#snapshot-retention).

--- [Document source](https://neon.com/docs/cli/status.md) ---

> Summary: The Neon CLI `neon status` command shows the branch's live Neon state. It is an alias of `neon config status`, so you can check what is currently deployed without going through the config command group.

# Neon CLI command: status

Show the branch's live Neon state

Last updated: 2026-07-01

The `status` command shows the branch's live Neon state. It is an alias of [`neon config status`](https://neon.com/docs/cli/config#status), so it reports the same information without the `config` prefix.

```bash
neon status [options]
```

| Option             | Description                                                                                                                                                 | Type    | Default | Required |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | :------: |
| `--branch`         | Branch ID or name                                                                                                                                           | string  | —       |    No    |
| `--config-json`    | Print only the branch's live config as neon.ts-shaped JSON (services + branch tuning + preview), to stdout. Useful for scripting or copying into a neon.ts. | boolean | `false` |    No    |
| `--current-branch` | Print only the linked branch name from the local .neon file (no network). Exits non-zero when no branch is pinned.                                          | boolean | `false` |    No    |
| `--project-id`     | Project ID                                                                                                                                                  | string  | —       |    No    |

```bash
neon status
```

--- [Document source](https://neon.com/docs/cli/triggers.md) ---

> Summary: The Neon CLI `neon triggers` command manages function triggers on a branch: list, get, create, update, enable, disable, and delete triggers that invoke a Neon Function on a cron schedule or when an object is created in Object Storage.

# Neon CLI command: triggers

Create and manage function triggers that invoke a Neon Function on a cron schedule or when an object is created

Last updated: 2026-10-09

The `triggers` command manages function triggers on a branch. A trigger invokes a [Neon Function](https://neon.com/docs/compute/functions/overview) on a cron schedule (`schedule`), or when an object is created in an [Object Storage](https://neon.com/docs/storage/overview) bucket (`storage_object_created`). Use it to run recurring work like a nightly report or cleanup job, or to process uploads as they land, without a separate scheduler. You deploy the function with [`neon functions deploy`](https://neon.com/docs/cli/functions), then point a trigger at it by slug.

Triggers are branch-scoped. Pass `--project-id` and `--branch` to target a branch, or let the CLI resolve them from your [context file](https://neon.com/docs/cli/link). Triggers can also be inherited: a trigger created on a parent branch is visible on its child branches, where the `Inherited` column shows `true`. An inherited trigger stays disabled on the child until you enable it there with [`neon triggers enable`](https://neon.com/docs/cli/triggers#enable).

Subcommands: [create](https://neon.com/docs/cli/triggers#create), [delete](https://neon.com/docs/cli/triggers#delete), [disable](https://neon.com/docs/cli/triggers#disable), [enable](https://neon.com/docs/cli/triggers#enable), [get](https://neon.com/docs/cli/triggers#get), [list](https://neon.com/docs/cli/triggers#list), [update](https://neon.com/docs/cli/triggers#update)

## neon triggers list

Lists the triggers on the branch.

```bash
neon triggers list [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon triggers list --project-id solitary-heart-93902637 --branch main
```

The `Type` column shows each trigger's type, currently `schedule` or `storage_object_created`. `Schedule` holds the cron for schedule triggers; `Storage` holds the bucket (and prefix, if set) for storage triggers.

```text filename="Output"
Trigger ID                                    Name            Type                    Function Slug  Function Path  Schedule   Storage        Enabled  Inherited  Next Run At
trigger-12345678-90ab-cdef-1234-567890abcdef  nightly-report  schedule                child404       /              0 6 * * *                 true     false      2026-09-11T06:00:00.000000Z
trigger-abcdef12-3456-7890-abcd-ef1234567890  on-upload       storage_object_created  ingest         /object                       assets logos/  true     false
```

## neon triggers get

Shows a single trigger by ID.

```bash
neon triggers get <id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon triggers get trigger-12345678-90ab-cdef-1234-567890abcdef --project-id solitary-heart-93902637 --branch main --output json
```

<details>

<summary>Show output</summary>

```json
{
  "type": "schedule",
  "trigger_id": "trigger-12345678-90ab-cdef-1234-567890abcdef",
  "function_slug": "child404",
  "name": "nightly-report",
  "function_path": "/",
  "schedule": {
    "cron": "0 6 * * *"
  },
  "enabled": true,
  "version": 1390408,
  "next_run_at": "2026-09-11T06:00:00.000000Z",
  "inherited": false
}
```

</details>

A `storage_object_created` trigger has `storage_object_created` (bucket and optional prefix) in place of `schedule`, and no `next_run_at`:

<details>

<summary>Show output</summary>

```json
{
  "type": "storage_object_created",
  "trigger_id": "trigger-abcdef12-3456-7890-abcd-ef1234567890",
  "function_slug": "ingest",
  "name": "on-upload",
  "function_path": "/object",
  "storage_object_created": {
    "bucket_name": "assets",
    "prefix": "logos/"
  },
  "enabled": true,
  "version": 1390512,
  "inherited": false
}
```

</details>

## neon triggers create

Creates a trigger that invokes a function on a cron schedule or when an object is created. `--function-slug` and `--name` are required, and the name must be unique on the branch. Choose the type with one of:

- `--cron` for a `schedule` trigger, a five-field UTC cron expression.
- `--bucket` for a `storage_object_created` trigger, with an optional `--prefix` to match only object keys under that prefix.

`--cron` and `--bucket` are mutually exclusive (`Pass --cron or --bucket, not both.`), and `--prefix` requires `--bucket`.

Object-created triggers (`--bucket` and `--prefix`) require Neon CLI 4.21.0 or later. On an older CLI, `--bucket` isn't recognized and `create` reports a missing `--cron` argument instead.

```bash
neon triggers create [options]
```

| Option            | Description                                               | Type    | Default | Required |
| ----------------- | --------------------------------------------------------- | ------- | ------- | :------: |
| `--bucket`        | Object-storage bucket to watch (storage\_object\_created) | string  | —       |    No    |
| `--cron`          | Five-field UTC cron expression, e.g. '\*/15 \* \* \* \*'  | string  | —       |    No    |
| `--enabled`       | Whether the trigger runs (default true)                   | boolean | —       |    No    |
| `--function-path` | Path the invocation is sent to (default '/')              | string  | —       |    No    |
| `--function-slug` | Slug of the function to invoke                            | string  | —       |    Yes   |
| `--name`          | Trigger name (unique per branch)                          | string  | —       |    Yes   |
| `--prefix`        | Object-key prefix to match (requires --bucket on create)  | string  | —       |    No    |
| `--branch`        | Branch ID or name                                         | string  | —       |    No    |
| `--project-id`    | Project ID                                                | string  | —       |    No    |

By default the invocation is sent to `/` and the trigger is enabled. Use `--function-path` to send it to another route, and `--enabled false` to create it in a disabled state.

A schedule trigger:

```bash
neon triggers create --function-slug child404 --name nightly-report --cron '0 6 * * *' --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Trigger ID     trigger-12345678-90ab-cdef-1234-567890abcdef
Name           nightly-report
Type           schedule
Function Slug  child404
Function Path  /
Schedule       0 6 * * *
Enabled        true
Inherited      false
Next Run At    2026-09-11T06:00:00.000000Z
```

A storage trigger that fires when an object is created under `logos/` in the `assets` bucket:

```bash
neon triggers create --function-slug ingest --name on-upload --bucket assets --prefix 'logos/' --function-path /object --project-id solitary-heart-93902637 --branch main
```

## neon triggers update

Updates a trigger. Pass at least one of `--function-slug`, `--name`, `--function-path`, or `--enabled`, plus the field matching the trigger's type: `--cron` for a schedule trigger, or `--bucket`/`--prefix` for a `storage_object_created` trigger. With no fields to change, the command returns an error. The type is fixed at creation, so passing `--cron` to a storage trigger, or `--bucket`/`--prefix` to a schedule trigger, is rejected (`Trigger <id> is type <type>; ...`). Changing a schedule recomputes `Next Run At`.

```bash
neon triggers update <id> [options]
```

| Option            | Description                                               | Type    | Default | Required |
| ----------------- | --------------------------------------------------------- | ------- | ------- | :------: |
| `--bucket`        | Object-storage bucket to watch (storage\_object\_created) | string  | —       |    No    |
| `--cron`          | Five-field UTC cron expression                            | string  | —       |    No    |
| `--enabled`       | Whether the trigger runs                                  | boolean | —       |    No    |
| `--function-path` | Path the invocation is sent to                            | string  | —       |    No    |
| `--function-slug` | Slug of the function to invoke                            | string  | —       |    No    |
| `--name`          | Trigger name (unique per branch)                          | string  | —       |    No    |
| `--prefix`        | Object-key prefix to match                                | string  | —       |    No    |
| `--branch`        | Branch ID or name                                         | string  | —       |    No    |
| `--project-id`    | Project ID                                                | string  | —       |    No    |

Reschedule a schedule trigger:

```bash
neon triggers update trigger-12345678-90ab-cdef-1234-567890abcdef --cron '*/30 * * * *' --project-id solitary-heart-93902637 --branch main
```

Change the prefix a storage trigger matches:

```bash
neon triggers update trigger-abcdef12-3456-7890-abcd-ef1234567890 --prefix 'incoming/' --project-id solitary-heart-93902637 --branch main
```

## neon triggers enable

Enables a trigger so it runs on its schedule. Enabling recomputes `Next Run At`.

```bash
neon triggers enable <id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon triggers enable trigger-12345678-90ab-cdef-1234-567890abcdef --project-id solitary-heart-93902637 --branch main
```

## neon triggers disable

Disables a trigger without deleting it. A disabled trigger keeps its definition but does not run, and its `Next Run At` is cleared. Re-enable it with [`neon triggers enable`](https://neon.com/docs/cli/triggers#enable).

```bash
neon triggers disable <id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon triggers disable trigger-12345678-90ab-cdef-1234-567890abcdef --project-id solitary-heart-93902637 --branch main
```

## neon triggers delete

Deletes a trigger.

```bash
neon triggers delete <id> [options]
```

| Option         | Description       | Type   | Default | Required |
| -------------- | ----------------- | ------ | ------- | :------: |
| `--branch`     | Branch ID or name | string | —       |    No    |
| `--project-id` | Project ID        | string | —       |    No    |

```bash
neon triggers delete trigger-12345678-90ab-cdef-1234-567890abcdef --project-id solitary-heart-93902637 --branch main
```

```text filename="Output"
Trigger trigger-12345678-90ab-cdef-1234-567890abcdef deleted
```

--- [Document source](https://neon.com/docs/cli/vpc.md) ---

> Summary: The Neon CLI `neon vpc` command controls Private Networking by registering, updating, removing, and checking VPC endpoints at the organization level, and by restricting or removing per-project VPC access. Use it when you need to limit Neon project connections to a specific AWS or Azure VPC rather than the public internet.

# Neon CLI command: vpc

Manage Private Networking VPC endpoints and project-level restrictions

Last updated: 2026-07-01

The `vpc` command manages [Private Networking](https://neon.com/docs/guides/neon-private-networking) configurations in Neon. Use it to register VPC endpoints at the organization level and to restrict individual projects to connections from a specific VPC.

Subcommands: [endpoint](https://neon.com/docs/cli/vpc#endpoint), [project](https://neon.com/docs/cli/vpc#project)

## VPC endpoints

The `vpc endpoint` subcommands list, assign, remove, and check the status of VPC endpoints for a Neon organization.

Subcommands: [assign](https://neon.com/docs/cli/vpc#endpoint-assign), [list](https://neon.com/docs/cli/vpc#endpoint-list), [remove](https://neon.com/docs/cli/vpc#endpoint-remove), [status](https://neon.com/docs/cli/vpc#endpoint-status)

You only need `--org-id` if your Neon account belongs to more than one organization. If your account has a single organization, the CLI uses it automatically. Instead of passing IDs on each command, you can also set them in a [context file](https://neon.com/docs/cli/set-context#using-a-named-context-file) and reference it with the `--context-file` option.

### neon vpc endpoint list

Lists the VPC endpoints configured for a Neon organization.

```bash
neon vpc endpoint list [options]
```

| Option        | Description                                                                                                                                          | Type   | Default | Required |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id`    | Organization ID                                                                                                                                      | string | —       |    No    |
| `--region-id` | The region ID. Possible values: aws-us-west-2, aws-ap-southeast-1, aws-ap-southeast-2, aws-eu-central-1, aws-us-east-2, aws-us-east-1, azure-eastus2 | string | —       |    Yes   |

```bash
neon vpc endpoint list --org-id org-bold-bonus-12345678 --region-id aws-us-east-1
```

### neon vpc endpoint assign

Adds or updates a VPC endpoint in a Neon organization. `add` and `update` are aliases for this command.

```bash
neon vpc endpoint assign <id> [options]
```

| Option        | Description                                                                                                                                          | Type   | Default | Required |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--label`     | An optional descriptive label for the VPC endpoint                                                                                                   | string | —       |    No    |
| `--org-id`    | Organization ID                                                                                                                                      | string | —       |    No    |
| `--region-id` | The region ID. Possible values: aws-us-west-2, aws-ap-southeast-1, aws-ap-southeast-2, aws-eu-central-1, aws-us-east-2, aws-us-east-1, azure-eastus2 | string | —       |    Yes   |

Add a VPC endpoint to a Neon organization in a specific region:

```bash
neon vpc endpoint assign vpce-1234567890abcdef0 --org-id org-bold-bonus-12345678 --region-id aws-us-east-1
```

After you assign a VPC endpoint to a Neon organization, client connections are accepted from the corresponding VPC for all projects in the organization unless you restrict access at the project level with [vpc project restrict](https://neon.com/docs/cli/vpc#project-restrict).

### neon vpc endpoint remove

Removes a VPC endpoint from a Neon organization.

```bash
neon vpc endpoint remove <id> [options]
```

| Option        | Description                                                                                                                                          | Type   | Default | Required |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id`    | Organization ID                                                                                                                                      | string | —       |    No    |
| `--region-id` | The region ID. Possible values: aws-us-west-2, aws-ap-southeast-1, aws-ap-southeast-2, aws-eu-central-1, aws-us-east-2, aws-us-east-1, azure-eastus2 | string | —       |    Yes   |

```bash
neon vpc endpoint remove vpce-1234567890abcdef0 --org-id org-bold-bonus-12345678 --region-id aws-us-east-1
```

**Note:** A removed VPC endpoint cannot be added back to the Neon organization.

### neon vpc endpoint status

Gets the status of a VPC endpoint in a Neon organization.

```bash
neon vpc endpoint status <id> [options]
```

| Option        | Description                                                                                                                                          | Type   | Default | Required |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | :------: |
| `--org-id`    | Organization ID                                                                                                                                      | string | —       |    No    |
| `--region-id` | The region ID. Possible values: aws-us-west-2, aws-ap-southeast-1, aws-ap-southeast-2, aws-eu-central-1, aws-us-east-2, aws-us-east-1, azure-eastus2 | string | —       |    Yes   |

```bash
neon vpc endpoint status vpce-1234567890abcdef0 --org-id org-bold-bonus-12345678 --region-id aws-us-east-1
```

## Project VPC restrictions

The `vpc project` subcommands list, configure, or remove VPC endpoint restrictions for specific projects in your Neon organization. By default, a project accepts connections from any VPC configured at the organization level. A restriction limits a project to connections from a specific VPC.

Subcommands: [list](https://neon.com/docs/cli/vpc#project-list), [remove](https://neon.com/docs/cli/vpc#project-remove), [restrict](https://neon.com/docs/cli/vpc#project-restrict)

You only need `--project-id` if your Neon account has more than one project.

### neon vpc project list

Lists all VPC endpoint restrictions for a Neon project.

```bash
neon vpc project list [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon vpc project list --project-id orange-credit-12345678
```

### neon vpc project restrict

Configures or updates a VPC endpoint restriction for a Neon project. `update` is an alias for this command.

```bash
neon vpc project restrict <id> [options]
```

| Option         | Description                                                    | Type   | Default | Required |
| -------------- | -------------------------------------------------------------- | ------ | ------- | :------: |
| `--label`      | An optional descriptive label for the VPC endpoint restriction | string | —       |    No    |
| `--project-id` | Project ID                                                     | string | —       |    No    |

```bash
neon vpc project restrict vpce-1234567890abcdef0 --project-id orange-credit-12345678
```

### neon vpc project remove

Removes a VPC endpoint restriction from a Neon project.

```bash
neon vpc project remove <id> [options]
```

| Option         | Description | Type   | Default | Required |
| -------------- | ----------- | ------ | ------- | :------: |
| `--project-id` | Project ID  | string | —       |    No    |

```bash
neon vpc project remove vpce-1234567890abcdef0 --project-id orange-credit-12345678
```

--- [Document source](https://neon.com/docs/community/ai-tools.md) ---

> Summary: Claude slash commands in the Neon website repo automate common documentation tasks. Includes writing and rewriting pages, quality checks, MDX validation, PR descriptions, and glossary audits. Use this reference to choose the right command for each task. Commands are stored in .claude/commands/ and their sub-agents in .claude/agents/.

# AI tools for documentation

Claude commands available when working on Neon docs

Last updated: 2026-08-27

The Neon website repo includes Claude commands for common documentation tasks. All changes are reviewed by humans via pull requests.

Run `/list-doc-tools` in Claude to see the full list with descriptions, or browse the files under `.claude/commands/` in the [website repository](https://github.com/neondatabase/website).

## Writing content

| Command           | Description                                                                                                                               |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `/write-content`  | Full orchestrated workflow for new pages or substantial rewrites: IA specialist → drafter → refiner → syntax validator.                   |
| `/simple-content` | Lighter single-thread workflow with confirmation at each step. Use for edits to existing pages or smaller additions.                      |
| `/review-content` | Review a page for terminology, voice, structure, and MDX compliance. Produces a structured findings report with an option to apply fixes. |
| `/humanize`       | Remove AI writing patterns and apply Neon voice: contractions, active voice, direct address, concise sentences.                           |
| `/improve-intro`  | Rewrite just the first paragraph of a page to match Neon style.                                                                           |
| `/golden-corpus`  | Load exemplary doc files by type for style and structure reference.                                                                       |

## Docs quality

| Command              | Description                                                                                       |
| -------------------- | ------------------------------------------------------------------------------------------------- |
| `/validate`          | Pre-commit check: frontmatter, stray h1 headings, navigation entry, image paths, em dashes, lint. |
| `/check-consistency` | Find other pages that say the same thing; surface duplication and drift.                          |
| `/update-glossary`   | Find glossary gaps in a doc file (Mode A), or audit the glossary itself (Mode B).                 |
| `/redirect-update`   | After moving or renaming a file: add `redirectFrom`, update links and navigation.                 |

## Pull requests

| Command              | Description                                                                  |
| -------------------- | ---------------------------------------------------------------------------- |
| `/update-pr`         | Draft or update a PR title and description from changed files and commits.   |
| `/add-preview-links` | Add Vercel preview links to a PR description for every changed content file. |

## Reference and navigation

| Command                  | Description                                                                  |
| ------------------------ | ---------------------------------------------------------------------------- |
| `/navigation-principles` | Reference for `navigation.yaml` structure and how to add pages and sections. |
| `/docs-prime`            | Load project structure and key paths into context.                           |
| `/list-doc-tools`        | Print the full list of available commands with descriptions.                 |

## Agents

The `.claude/agents/` directory contains specialized sub-agents used by the writing workflow commands:

- **content-drafter**, **content-planner**, **content-refiner**, **ia-specialist**, **syntax-validator**, **supervisor** — write, plan, review, structure, validate, and orchestrate multi-step workflows

--- [Document source](https://neon.com/docs/community/community-intro.md) ---

> Summary: Ways to contribute to Neon's open-source serverless Postgres project: write docs, submit community guides, share example applications, or file bugs in Neon's GitHub repositories. Find the right entry point for contributing or connecting with other Neon users on Discord, X (Twitter), or YouTube.

# Neon community

Learn how to get involved in the Neon community

Last updated: 2026-09-17

Neon is [open source](https://neon.com/docs/get-started/why-neon#neon-is-open-source) and has an enthusiastic user community worldwide. Here's how you can get involved:

## Contribute

There are many ways to contribute to the Neon community:

- **Neon Docs**: Share suggestions, contribute content, or write new guides to help others working with Neon. Check out our [Documentation Contribution Guide](https://neon.com/docs/community/contribution-guide) to get started. You can also create visual diagrams using our [Mermaid Diagrams Guide](https://neon.com/docs/community/mermaid-diagrams). If you want to consume our docs as markdown (e.g. for LLMs or APIs), see [Using Neon docs as markdown](https://neon.com/docs/community/llms-markdown-guide).
- **Community Guides**: Share your knowledge by writing a guide about Neon or Postgres. These guides can help developers learn new technologies, techniques, and best practices. Submit your guide to our [Community Guides](https://neon.com/guides) page by forking the [Neon website repository](https://github.com/neondatabase/website) and creating a PR to add it to the [/content/guides](https://github.com/neondatabase/website/tree/main/content/guides) directory.
- **Examples and applications**: Share examples and applications that demonstrate how to integrate Neon with different tools and platforms. Post your examples on our [Discord Server](https://neon.com/discord) or contribute to the [Neon examples repository](https://github.com/neondatabase/examples).
- **Code contributions**: Contribute to Neon's development by fixing bugs, proposing new features, or submitting code to [Neon's GitHub repositories](https://github.com/neondatabase). It's also a good way to dig into how Neon is built.

## Join the Discussion

Join us on Discord and X (Twitter), and subscribe to the Neon YouTube channel for videos and presentations.

- [Neon Discord Server](https://neon.com/discord)
- [X (Twitter)](https://twitter.com/neondatabase)
- [Neon YouTube](https://www.youtube.com/@neondatabase)

--- [Document source](https://neon.com/docs/community/component-architecture.md) ---

> Summary: Technical reference for the Neon documentation MDX component system. Covers file layout under src/components/pages/doc/, the sharedMdxComponents.js registry, and the two icon loading strategies. TechCards loads dynamic SVG files from /public/images/technology-logos/. DetailIconCards uses static inline imports mapped in component code. Use this page when adding, modifying, or debugging MDX components, not when looking for usage examples or icon names.

# Component architecture

Technical implementation details for developers and maintainers

Last updated: 2026-06-05

A technical reference for developers and maintainers who need to understand, modify, or extend the Neon documentation component system. This guide covers the architecture, file structure, and implementation details.

**What you will learn:**

- How MDX components are structured and organized
- Technical implementation details for each component type
- Development workflows for adding and modifying components
- File organization and build process details

**Related topics**

- [Component Guide](https://neon.com/docs/community/component-guide)
- [Component Specialized Guide](https://neon.com/docs/community/component-specialized)
- [Component Icon Guide](https://neon.com/docs/community/component-icon-guide)
- [Documentation Contribution Guide](https://neon.com/docs/community/contribution-guide)

## Quick navigation

- [Component architecture](https://neon.com/docs/community/component-architecture#component-architecture) - How MDX components are integrated
- [File structure](https://neon.com/docs/community/component-architecture#file-structure) - Directory organization and component locations
- [Component registration](https://neon.com/docs/community/component-architecture#component-registration) - How components are registered in MDX
- [Icon systems](https://neon.com/docs/community/component-architecture#icon-systems) - Technical implementation of icon loading
- [Shared content](https://neon.com/docs/community/component-architecture#shared-content) - How shared templates work
- [Development workflow](https://neon.com/docs/community/component-architecture#development-workflow) - How to add, modify, or debug components
- [Build process](https://neon.com/docs/community/component-architecture#build-process) - How components are processed during build
- [Troubleshooting](https://neon.com/docs/community/component-architecture#troubleshooting) - Common issues and debugging techniques

---

## Component architecture

### MDX integration

Neon documentation uses MDX (Markdown + JSX) to enable React components within markdown content. The component system is built on top of this foundation.

### Component hierarchy

```
MDX Content
  ↓
Component Registry (sharedMdxComponents)
  ↓
React Components (src/components/pages/doc/)
  ↓
Rendered HTML
```

### Key files

- `sharedMdxComponents.js` - Main component registry
- `src/components/pages/doc/` - Component implementations
- `content/docs/` - MDX content files
- `content/docs/shared-content/` - Shared template content

---

## File structure

### Component directory organization

Most MDX components follow a consistent pattern in the Neon website repository:

```
src/components/pages/doc/
├── {component-name}/
│   ├── {component-name}.jsx          # Main component implementation
│   ├── index.js                      # Export file
│   └── images/                       # Component-specific assets
│       └── {icons}.inline.svg        # Inline SVG icons
├── shared/                           # Shared components
│   ├── request-form/
│   └── ...
└── ...
```

### Example: DocsList component

Let's explore the DocsList component as an example:

```
src/components/pages/doc/docs-list/
├── docs-list.jsx                     # Main component implementation
├── index.js                          # Export: export { default } from './docs-list'
└── images/                           # Component-specific images
    ├── docs.inline.svg
    └── repo.inline.svg
```

### Key files to check

When exploring a component, look for these files:

- **Component Definition** (`{component-name}.jsx`)
  - Contains the React component code
  - Defines props and their types
  - Implements the rendering logic
  - May include styled components or CSS modules

- **Index File** (`index.js`)
  - Usually a simple export: `export { default } from './component-name';`
  - Makes the component importable from the directory

- **Images Directory** (`images/`)
  - Contains SVGs, icons, or other assets used by the component
  - For icon-based components, this is where you'll find available icons

---

## Component registration

### Registration process

Components are registered in `sharedMdxComponents.js` to make them available in MDX files:

```js
// sharedMdxComponents.js
import DocsList from '../src/components/pages/doc/docs-list';
import TechCards from '../src/components/pages/doc/tech-cards';
// ... other imports

export const sharedMdxComponents = {
  DocsList,
  TechCards,
  // ... other components
};
```

### MDX Integration

The `sharedMdxComponents` object is passed to the MDX processor, making all registered components available in markdown files:

```jsx
// In MDX files
<DocsList title="Related documentation">
  <a href="/docs/guides/node">Node.js Guide</a>
</DocsList>
```

### Component availability

- **Global**: Components registered in `sharedMdxComponents` are available in all MDX files
- **Local**: Some components may be registered locally for specific pages
- **Conditional**: Components may be conditionally available based on page context

---

## Icon systems

### TechCards icon loading

TechCards icons are loaded dynamically from the public directory. If the file exists, it will be rendered. Otherwise, the image will be broken or missing.

**File Requirements:**

- Icons must exist in `/public/images/technology-logos/`
- Format: `{icon-name}.svg` and `{icon-name}-dark.svg`
- Case-sensitive naming

### DetailIconCards icon loading

DetailIconCards icons are statically imported and mapped:

```js
// DetailIconCards component implementation
import Prisma from './images/prisma.inline.svg';
import NodeJs from './images/node-js.inline.svg';
// ... other imports

const icons = {
  prisma: Prisma,
  'node-js': NodeJs,
  // ... other mappings
};

const Icon = icons[icon];
```

**File Requirements:**

- Icons must be imported as inline SVGs
- Must be explicitly mapped in the component code
- Case-sensitive naming

### Icon system differences

| Aspect          | TechCards                          | DetailIconCards              |
| --------------- | ---------------------------------- | ---------------------------- |
| **Loading**     | Dynamic file loading               | Static imports               |
| **Location**    | `/public/images/technology-logos/` | Component-specific `images/` |
| **Format**      | Standard SVG files                 | Inline SVG imports           |
| **Dark Mode**   | Separate `-dark.svg` files         | Single file with CSS         |
| **Flexibility** | Easy to add new icons              | Requires code changes        |

---

## Shared content

### Shared templates

Shared content components load from templates in `content/docs/shared-content/`:

```
content/docs/shared-content/
├── feature-beta.md
├── public-preview.md
├── early-access.md
└── ...
```

### Template registration

Templates are registered in `shared-content/index.js`:

```js
// shared-content/index.js
export const sharedContent = {
  'feature-beta': () => import('./feature-beta.md'),
  'public-preview': () => import('./public-preview.md'),
  // ... other templates
};
```

### Usage in components

Shared content is loaded dynamically:

```jsx
// In MDX files
<FeatureBeta />  // Loads content from feature-beta.md
<PublicPreview /> // Loads content from public-preview.md
```

### Template structure

Shared templates are standard MDX files with frontmatter:

```mdx
---
title: Feature Beta
description: Beta feature announcement
---

This feature is currently in beta...
```

---

## Development workflow

### Adding a new component

1. **Create Component Directory**

   ```bash
   mkdir src/components/pages/doc/my-component
   ```

2. **Create Component File**

   ```jsx
   // src/components/pages/doc/my-component/my-component.jsx
   import React from 'react';

   const MyComponent = ({ title, children }) => {
     return (
       <div className="my-component">
         <h3>{title}</h3>
         {children}
       </div>
     );
   };

   export default MyComponent;
   ```

3. **Create Index File**

   ```js
   // src/components/pages/doc/my-component/index.js
   export { default } from './my-component';
   ```

4. **Register Component**

   ```js
   // sharedMdxComponents.js
   import MyComponent from '../src/components/pages/doc/my-component';

   export const sharedMdxComponents = {
     // ... existing components
     MyComponent,
   };
   ```

5. **Test Component**

   ```mdx
   <!-- In any MDX file -->

   <MyComponent title="Test">This is a test of my new component.</MyComponent>
   ```

### Modifying existing components

1. **Locate Component**
   - Find the component in `src/components/pages/doc/{component-name}/`
   - Check the main `.jsx` file for implementation

2. **Make Changes**
   - Modify the component logic in the `.jsx` file
   - Update props, styling, or functionality as needed

3. **Test Changes**
   - Check that the component renders correctly
   - Verify that existing usage still works
   - Test edge cases and error conditions

### Debugging components

1. **Check Console Errors**
   - Look for JavaScript errors in browser console
   - Check for missing imports or undefined variables

2. **Verify Registration**
   - Ensure component is properly exported from `index.js`
   - Confirm component is registered in `sharedMdxComponents`

3. **Check File Paths**
   - Verify all imports resolve correctly
   - Check that asset files exist in expected locations

4. **Test in Isolation**
   - Create a simple test page with just the component
   - Remove other components to isolate issues

---

## Build process

### MDX processing

1. **Content Loading**: MDX files are loaded from `content/docs/`
2. **Component Resolution**: `sharedMdxComponents` are injected into MDX context
3. **Transformation**: MDX is transformed to React components
4. **Rendering**: Components are rendered to HTML

### Build pipeline

```
MDX Files → MDX Processor → React Components → HTML Output
     ↓              ↓              ↓              ↓
content/docs/ → sharedMdxComponents → src/components/ → public/
```

### Optimization

- **Code Splitting**: Components are code-split for performance
- **Asset Optimization**: Images and SVGs are optimized during build
- **Caching**: Static assets are cached for faster loading

---

## Troubleshooting

### Common issues

1. **Component Not Found**
   - Check that component is registered in `sharedMdxComponents`
   - Verify the component name matches exactly (case-sensitive)
   - Ensure the component is properly exported

2. **Icon Not Displaying**
   - For TechCards: Check if SVG file exists in `/public/images/technology-logos/`
   - For DetailIconCards: Check if icon is mapped in component code
   - Verify icon name spelling and case

3. **Build Errors**
   - Check for syntax errors in component files
   - Verify all imports resolve correctly
   - Ensure all required dependencies are installed

4. **Styling Issues**
   - Check CSS class names and specificity
   - Verify that styles are properly imported
   - Test in different browsers and screen sizes

### Debugging techniques

1. **Console Logging**

   ```jsx
   const MyComponent = (props) => {
     console.log('MyComponent props:', props);
     return <div>...</div>;
   };
   ```

2. **React DevTools**
   - Use React DevTools to inspect component hierarchy
   - Check props and state values
   - Verify component rendering

3. **Network Tab**
   - Check for failed asset requests
   - Verify that images and SVGs load correctly
   - Look for 404 errors

4. **Source Maps**
   - Enable source maps for better error tracking
   - Use browser dev tools to step through code

### Performance considerations

1. **Bundle Size**
   - Keep components lightweight
   - Use code splitting for large components
   - Optimize images and assets

2. **Rendering Performance**
   - Avoid expensive operations in render methods
   - Use React.memo for expensive components
   - Implement proper key props for lists

3. **Asset Loading**
   - Optimize image sizes and formats
   - Use appropriate loading strategies
   - Consider lazy loading for non-critical components

---

## Summary

This guide provides technical details for working with Neon's MDX component system. Key points:

- **Components** are organized in `src/components/pages/doc/`
- **Registration** happens in `sharedMdxComponents.js`
- **Icons** use different loading strategies for TechCards vs DetailIconCards
- **Shared content** loads from templates in `content/docs/shared-content/`
- **Development** follows standard React patterns with MDX integration

For component usage examples, see the [Component Guide](https://neon.com/docs/community/component-guide) and [Component Specialized Guide](https://neon.com/docs/community/component-specialized).

--- [Document source](https://neon.com/docs/community/component-guide.md) ---

> Summary: MDX component reference for Neon documentation writers. Covers syntax, props, and live-rendered previews for frequently used components: Admonition, Steps, CodeTabs, TechCards, DetailIconCards, TwoColumnLayout, CheckList, and InfoBlock. Use this page when choosing between similar components or looking up correct prop names and MDX syntax.

# Component guide

Most commonly used components for documentation writers

Last updated: 2026-08-26

A practical guide for the most commonly used MDX components in Neon documentation. This guide focuses on components you'll use most frequently when writing documentation.

**What you will learn:**

- How to use common MDX components in Neon docs
- How to choose between different components
- Best practices
- Proper syntax and prop usage

**Related topics**

- [Component Specialized Guide](https://neon.com/docs/community/component-specialized)
- [Component Icon Guide](https://neon.com/docs/community/component-icon-guide)
- [Component Architecture](https://neon.com/docs/community/component-architecture)
- [Documentation Contribution Guide](https://neon.com/docs/community/contribution-guide)

## Quick navigation

- [Essential components](https://neon.com/docs/community/component-guide#essential-components) - Most commonly used
- [Tabbed content](https://neon.com/docs/community/component-guide#tabbed-content) - CodeTabs and Tabs for organized content
- [Content organization](https://neon.com/docs/community/component-guide#content-organization) - Structure and navigation components
- [Interactive elements](https://neon.com/docs/community/component-guide#interactive-elements) - UI elements and forms
- [Common shared components](https://neon.com/docs/community/component-guide#common-shared-components) - Reusable content
- [External content](https://neon.com/docs/community/component-guide#external-content) - Embedding external code and video

---

## Essential components

These are the most frequently used components in Neon docs.

### Admonition

Callouts for notes, warnings, and tips. There are six types available: `note` (default), `important`, `tip`, `info`, `warning`, `comingSoon`.

```mdx

<Admonition type="warning" title="Important">
Critical information requiring immediate attention.
</Admonition>
```

**Live preview:**

**Warning: Important**

Critical information requiring immediate attention.

**All Admonition types:**

**Note: Note**

Highlights information that users should take into account.

**Important:** Crucial information necessary for users to succeed.

**Tip: Pro tip**

Optional information to help a user be more successful.

**Info:** Information that helps users understand things better.

**Warning:** Critical content demanding immediate user attention due to potential risks.

**Coming soon:** Information about features that are coming soon.

---

### Callout

Highlighted block for supplementary information the reader should notice, but that doesn't carry the urgency of an Admonition. Use it for tips, best practices, or "good to know" context. The default label is "Good to know".

```mdx
<Callout title="Before you start">

Make sure you have Node.js 18+ installed.

</Callout>
```

**Live preview:**

**Before you start:**

Make sure you have Node.js 18+ installed.

**Props:**

| Prop       | Type   | Default        | Description                         |
| ---------- | ------ | -------------- | ----------------------------------- |
| `children` | node   | (required)     | Content rendered inside the callout |
| `title`    | string | `Good to know` | Label displayed in the header       |

**When to use Callout vs Admonition:**

- **Callout** — supplementary context, best practices, or neutral "good to know" information.
- **Admonition** — warnings, important notices, tips with urgency, or coming-soon flags. Use when missing the information could cause user error.

---

### Steps

Numbered step-by-step instructions split by `h2` headings.

```mdx
<Steps>

## Get a Glass

Take a clean glass from the cabinet or dish rack.

## Turn on Tap

Adjust the faucet to your preferred temperature and flow rate.

## Fill and Drink

Fill the glass to desired level and enjoy your water.

</Steps>
```

**Live preview:**

## Get a Glass

Take a clean glass from the cabinet or dish rack.

## Turn on Tap

Adjust the faucet to your preferred temperature and flow rate.

## Fill and Drink

Fill the glass to desired level and enjoy your water.

---

## Tabbed content

Components for organizing content into tabs.

### CodeTabs

Multi-language code examples with tabs.

````mdx
<CodeTabs labels={["JavaScript", "Python", "Go"]}>

```javascript
const { Client } = require('pg');
const client = new Client({
  connectionString: process.env.DATABASE_URL,
});
await client.connect();
```

```python
import psycopg2
import os

conn = psycopg2.connect(os.environ["DATABASE_URL"])
cur = conn.cursor()
```

```go
import (
    "database/sql"
    _ "github.com/lib/pq"
)

db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
```

</CodeTabs>
````

**Live preview:**

**JavaScript**

```javascript
const { Client } = require('pg');
const client = new Client({
  connectionString: process.env.DATABASE_URL,
});
await client.connect();
```

**Python**

```python
import psycopg2
import os

conn = psycopg2.connect(os.environ["DATABASE_URL"])
cur = conn.cursor()
```

**Go**

```go
import (
    "database/sql"
    _ "github.com/lib/pq"
)

db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
```

---

### Tabs

General tabbed content (not just code). For code-specific tabs, use [CodeTabs](https://neon.com/docs/community/component-guide#codetabs) instead.

````mdx
<Tabs labels={["Console", "CLI", "API"]}>
<TabItem>
Create a database using the Neon Console by navigating to your project dashboard and clicking "Create Database".
</TabItem>
<TabItem>
Use the Neon CLI to create a database:

```bash
neon databases create --name my-database
```

</TabItem>
<TabItem>
Use the API to create a database:

```bash
curl -X POST https://console.neon.tech/api/v2/projects/my-project/databases \
  -H "Authorization: Bearer $NEON_API_KEY"
```

</TabItem>
</Tabs>
````

**Live preview:**

**Console**

Create a database using the Neon Console by navigating to your project dashboard and clicking "Create Database".

**CLI**

Use the Neon CLI to create a database:

```bash
neon databases create --name my-database
```

**API**

Use the API to create a database:

```bash
curl -X POST https://console.neon.tech/api/v2/projects/my-project/databases \
  -H "Authorization: Bearer $NEON_API_KEY"
```

---

## Content organization

Components for structuring and organizing page content.

### TechCards / DetailIconCards

Technology cards with icons, titles, and descriptions. These components use different [icon systems](https://neon.com/docs/community/component-icon-guide) - see the [comparison table](https://neon.com/docs/community/component-guide#techcards-vs-detailiconcards-vs-docslist) below to choose the right one.

#### TechCards

Standard technology cards layout using [TechCards icons](https://neon.com/docs/community/component-icon-guide#techcards-icons):

```mdx
<TechCards>
  <a
    href="/docs/guides/node"
    title="Node.js"
    description="Connect Node.js applications to Neon"
    icon="node-js"
  >
    Node.js
  </a>
  <a
    href="/docs/guides/python"
    title="Python"
    description="Connect Python applications to Neon"
    icon="python"
  >
    Python
  </a>
  <a
    href="/docs/guides/nextjs"
    title="Next.js"
    description="Build Next.js apps with Neon"
    icon="next-js"
  >
    Next.js
  </a>
</TechCards>
```

**Live preview:**

- [Node.js](https://neon.com/docs/guides/node): Connect Node.js applications to Neon
- [Python](https://neon.com/docs/guides/python): Connect Python applications to Neon
- [Next.js](https://neon.com/docs/guides/nextjs): Build Next.js apps with Neon

---

#### DetailIconCards

Alternative layout using [DetailIconCards icons](https://neon.com/docs/community/component-icon-guide#detailiconcards-icons):

```mdx
<DetailIconCards>
  <a
    href="/docs/ai/openai"
    title="OpenAI integration"
    description="Build AI features with OpenAI"
    icon="openai"
  >
    OpenAI Integration
  </a>
  <a
    href="/docs/ai/langchain"
    title="LangChain integration"
    description="Create AI workflows with LangChain"
    icon="langchain"
  >
    LangChain Integration
  </a>
  <a
    href="/docs/development"
    title="Code development"
    description="Development tools and practices"
    icon="code"
  >
    Code Development
  </a>
  <a
    href="/docs/cloud/aws"
    title="AWS integration"
    description="Deploy and scale with AWS"
    icon="aws"
  >
    AWS Integration
  </a>
</DetailIconCards>
```

**Live preview:**

- [OpenAI Integration](https://neon.com/docs/ai/openai): Build AI features with OpenAI
- [LangChain Integration](https://neon.com/docs/ai/langchain): Create AI workflows with LangChain
- [Code Development](https://neon.com/docs/development): Development tools and practices
- [AWS Integration](https://neon.com/docs/cloud/aws): Deploy and scale with AWS

---

> DetailIconCards uses a different [icon system](https://neon.com/docs/community/component-icon-guide#detailiconcards-icons) than [TechCards](https://neon.com/docs/community/component-icon-guide#techcards-icons), which is why different icons are available._

#### TechCards vs DetailIconCards vs DocsList

Quick comparison to help you choose the right component:

| Component                                                                              | Use For                        | Icon System                                                                                             | Layout      |
| -------------------------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------- | ----------- |
| **[TechCards](https://neon.com/docs/community/component-guide#techcards)**             | Technology/framework showcases | [Technology logos](https://neon.com/docs/community/component-icon-guide#techcards-icons) (colorful)     | Card grid   |
| **[DetailIconCards](https://neon.com/docs/community/component-guide#detailiconcards)** | Feature/service showcases      | [Detail icons](https://neon.com/docs/community/component-icon-guide#detailiconcards-icons) (monochrome) | Card grid   |
| **[DocsList](https://neon.com/docs/community/component-guide#docslist)**               | Documentation links            | Checkbox (default), docs, or repo icon                                                                  | Simple list |

### DefinitionList

Accessible term/definition lists for defining technical terms and concepts.

```mdx
<DefinitionList>

Database URL
: Connection string for your Neon database
: Format: `postgresql://user:password@host:port/database`

Connection Pool
: A cache of database connections
: Improves performance by reusing connections

Branch
: An isolated copy of your database
: Used for development and testing

</DefinitionList>
```

**Live preview:**

Database URL
: Connection string for your Neon database
: Format: `postgresql://user:password@host:port/database`

Connection Pool
: A cache of database connections
: Improves performance by reusing connections

Branch
: An isolated copy of your database
: Used for development and testing

---

### DocsList

Simple, clean lists for documentation links with optional theming. DocsList provides a lightweight alternative to card-based components for presenting navigation links or content summaries.

**Props:**

- `title` (string) - Optional title for the list section
- `theme` (string) - Visual theme: `"docs"` (document icon), `"repo"` (repository icon), or default (checkbox icon)

**Default Theme (Checkbox Icon):**

**MDX Code:**

```mdx
<DocsList title="Related documentation">
  <a href="/docs/guides/node">Node.js Connection Guide</a>
  <a href="/docs/guides/python">Python Connection Guide</a>
  <a href="/docs/api-reference">API Reference</a>
  <a href="/docs/cli">CLI Documentation</a>
</DocsList>
```

**Live preview:**

**Related documentation**

- [Node.js Connection Guide](https://neon.com/docs/guides/node)
- [Python Connection Guide](https://neon.com/docs/guides/python)
- [API Reference](https://neon.com/docs/api-reference)
- [CLI Documentation](https://neon.com/docs/cli)

---

### InfoBlock

InfoBlock creates a multi-column layout for organizing related content sections. Use it for "at-a-glance" summaries at the top of documentation pages, combining learning objectives with related resources. Use two columns.

**Key Features:**

- Commonly paired with DocsList for structured content presentation
- Ideal for page introductions and overview sections

**Basic Two-Column Layout:**

```mdx
<InfoBlock>
<DocsList title="What you will learn:">
<p>How to view and modify data in the console</p>
<p>Create an isolated database copy per developer</p>
<p>Reset your branch to production when ready to start new work</p>
</DocsList>

<DocsList title="Related topics" theme="docs">
<a href="/docs/introduction/branching">About branching</a>
<a href="/docs/get-started/workflow-primer">Branching workflows</a>
<a href="/docs/get-started/connect-neon">Connect Neon to your stack</a>
</DocsList>
</InfoBlock>
```

**Renders as:**

**What you will learn:**

- How to view and modify data in the console
- Create an isolated database copy per developer
- Reset your branch to production when ready to start new work

**Related topics**

- [About branching](https://neon.com/docs/introduction/branching)
- [Branching workflows](https://neon.com/docs/get-started/workflow-primer)
- [Connect Neon to your stack](https://neon.com/docs/get-started/connect-neon)

---

### TwoColumnLayout

Two-column layout for tutorials and reference documentation. Use `TwoColumnLayout.Step` for numbered tutorial steps, `TwoColumnLayout.Item` for reference items.

Add `layout: wide` to the page frontmatter when using this component, to hide the right sidebar and give the layout more room.

````mdx
<TwoColumnLayout>

<TwoColumnLayout.Step title="Install dependencies">
<TwoColumnLayout.Block>

Install the required packages.

</TwoColumnLayout.Block>
<TwoColumnLayout.Block label="Terminal">

```bash
npm install @neon/neon-js
```

</TwoColumnLayout.Block>
</TwoColumnLayout.Step>

</TwoColumnLayout>
````

**Subcomponents:**

| Subcomponent             | Props                   | Purpose                                    |
| ------------------------ | ----------------------- | ------------------------------------------ |
| `TwoColumnLayout.Step`   | `title`                 | Numbered step for tutorials                |
| `TwoColumnLayout.Item`   | `title`, `method`, `id` | Reference item                             |
| `TwoColumnLayout.Block`  | `label` (optional)      | Content block within a step or item        |
| `TwoColumnLayout.Footer` | —                       | Full-width content at the bottom of a step |

See [Managed Better Auth with Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only) for a live example.

---

### FeatureList

Visual list of features, split by `##` and `###` headings. Supports an optional `icons` prop.

```mdx
<FeatureList>

### Instant provisioning

Create databases in seconds.

### Autoscaling

Scale compute up and down automatically.

</FeatureList>
```

To add icons, pass an array of icon names (see `src/components/shared/feature-list/icon/icon.jsx` for available icons):

```mdx
<FeatureList icons={['agent', 'speedometer']}>
```

---

## Interactive elements

Components for user engagement and interaction.

### CheckList

Interactive checklists for setup guides and tutorials. CheckList uses CheckItem components internally.

```mdx
<CheckList title="Setup checklist">
  <CheckItem title="Create Neon account" href="#signup">
    Sign up for a free Neon account at console.neon.tech
  </CheckItem>
  <CheckItem title="Install dependencies" href="#install">
    Install the required packages for your project
  </CheckItem>
  <CheckItem title="Configure environment" href="#config">
    Set up your database connection string
  </CheckItem>
  <CheckItem title="Test connection" href="#test">
    Verify your application can connect to Neon
  </CheckItem>
</CheckList>
```

**Live preview:**

## Setup checklist

- [ ] [Create Neon account](https://neon.com/docs/community/component-guide#signup)
    Sign up for a free Neon account at console.neon.tech
- [ ] [Install dependencies](https://neon.com/docs/community/component-guide#install)
    Install the required packages for your project
- [ ] [Configure environment](https://neon.com/docs/community/component-guide#config)
    Set up your database connection string
- [ ] [Test connection](https://neon.com/docs/community/component-guide#test)
    Verify your application can connect to Neon

---

### CheckItem

Individual checklist items used within CheckList components.

```mdx
<CheckItem title="Task name" href="#anchor">
  Description of the task or requirement
</CheckItem>
```

---

**Usage Notes:**

- Always used within a `<CheckList>` component
- `title` prop is required
- `href` prop is optional for anchor linking
- Content is the description text

---

### Faq / FaqItem

The standard, SEO-friendly frequently-asked-questions section for the end of docs and guides. Use it instead of ad-hoc `### question` headings, `**Q:/A:**` text, or `DefinitionList` for FAQs, so every FAQ looks and behaves the same. It emits `FAQPage` schema.org JSON-LD to help search engines and AI agents parse the questions and answers, and it renders each answer with native collapsible `<details>`, so answers stay crawlable and accessible even when collapsed. It also gives every FAQ consistent styling and deep-link anchors.

Add a `## Frequently asked questions` heading above the component (sentence case) so the section appears in the table of contents.

```mdx
## Frequently asked questions

<Faq>

<FaqItem question="What is a branch?">
A branch is a copy-on-write clone of your data that you can create from a current or past state.
</FaqItem>

<FaqItem question="Does creating a branch affect my production database?">
No. Creating a branch does not increase load on the parent branch or affect its performance.
</FaqItem>

</Faq>
```

**Live preview:**

## Frequently asked questions

### What is a branch?

A branch is a copy-on-write clone of your data that you can create from a current or past state.

### Does creating a branch affect my production database?

No. Creating a branch does not increase load on the parent branch or affect its performance.

**Usage Notes:**

- `FaqItem` requires a `question` prop. It renders as an `<h3>` inside the summary and is used verbatim in the JSON-LD.
- `id` (optional) sets the anchor; it defaults to a slug of the question, so `#your-question` deep links work.
- `defaultOpen` (optional) renders an item expanded on load.
- Answers accept full markdown (lists, tables, links, images, code). Keep blank lines around block content.
- Questions do not appear in the table of contents; the `## Frequently asked questions` heading is the single TOC entry.
- Put shared blocks like `<NeedHelp/>` after `</Faq>`, not inside an item.

### CTA (Call to Action)

Prominent call-to-action buttons for important actions.

```mdx
<CTA
  title="Try Neon free"
  description="Start building with serverless Postgres today. No credit card required."
  buttonText="Sign Up"
  buttonUrl="https://console.neon.tech/signup"
/>
```

**Live preview:**

> **Try Neon free**
>
> Start building with serverless Postgres today. No credit card required.
>
> [Sign Up](https://console.neon.tech/signup)

---

### CopyPrompt

Displays a copyable LLM prompt from a file. Use when providing a pre-built prompt to help users get started faster. Prompt files go in `public/prompts/`.

```mdx
<CopyPrompt
  src="/prompts/my-prompt.md"
  displayText="Use this pre-built prompt to get started faster."
  buttonText="Copy prompt"
/>
```

**Props:**

| Prop          | Type   | Default                                            | Description                                  |
| ------------- | ------ | -------------------------------------------------- | -------------------------------------------- |
| `src`         | string | (required)                                         | Path to the prompt file in `public/prompts/` |
| `displayText` | string | `Use this pre-built prompt to get started faster.` | CTA text shown to the left                   |
| `buttonText`  | string | `Copy prompt`                                      | Button label                                 |

---

### NeedHelp

Support widget for getting assistance.

```mdx
<NeedHelp />
```

**Live preview:**

---

---

## Common shared components

Reusable content components that load from shared templates.

### LinkAPIKey

Link to API key management in the console.

```mdx
<LinkAPIKey />
```

**Live preview:**

**Note:** To learn more about the types of API keys you can create — personal, organization, or project-scoped — see [Manage API Keys](https://neon.com/docs/manage/api-keys).

---

### FeatureBetaProps

Status indicator for beta features with custom feature name.

```mdx
<FeatureBetaProps feature_name="OpenTelemetry integration" />
```

**Live preview:**

**Note: Beta**

**OpenTelemetry integration** is in beta. Share your feedback on [Discord](https://neon.com/discord) or via the [Neon Console](https://console.neon.tech/app/projects?modal=feedback).

---

---

## External content

Components for embedding content from outside the repo.

### ExternalCode

Embed code from an external URL with syntax highlighting. Always use raw GitHub URLs.

```mdx
<ExternalCode
  url="https://raw.githubusercontent.com/neondatabase/neon/main/README.md"
  language="markdown"
/>
```

**Props:**

| Prop              | Type    | Default               | Description                      |
| ----------------- | ------- | --------------------- | -------------------------------- |
| `url`             | string  | (required)            | Raw URL to the file              |
| `language`        | string  | (auto from extension) | Language for syntax highlighting |
| `showLineNumbers` | boolean | false                 | Show line numbers                |
| `shouldWrap`      | boolean | false                 | Enable code wrapping             |

### YoutubeIframe

Embeds a YouTube video player.

```mdx
<YoutubeIframe embedId="IcoOpnAcO1Y" />
```

Pass the video ID from the YouTube URL (the part after `v=`).

---

## Best practices

### Component selection

- **[Admonition](https://neon.com/docs/community/component-guide#admonition)** for urgent callouts and warnings
- **[Callout](https://neon.com/docs/community/component-guide#callout)** for supplementary "good to know" context
- **[Steps](https://neon.com/docs/community/component-guide#steps)** for sequential instructions
- **[CodeTabs](https://neon.com/docs/community/component-guide#codetabs)** for multi-language examples
- **[TechCards](https://neon.com/docs/community/component-guide#techcards)** for technology showcases
- **[TwoColumnLayout](https://neon.com/docs/community/component-guide#twocolumnlayout)** for tutorials and reference docs requiring a two-column layout
- **[FeatureList](https://neon.com/docs/community/component-guide#featurelist)** for listing product features visually
- **[CheckList](https://neon.com/docs/community/component-guide#checklist)** for setup guides
- **[CopyPrompt](https://neon.com/docs/community/component-guide#copyprompt)** for providing a copyable LLM prompt
- **[InfoBlock](https://neon.com/docs/community/component-guide#infoblock)** for page introductions with multiple content sections
- **[DocsList](https://neon.com/docs/community/component-guide#docslist)** for simple navigation lists with theming options

### Content organization tips

- Use [InfoBlock](https://neon.com/docs/community/component-guide#infoblock) at the top of pages to provide quick orientation
- Add `layout: wide` to frontmatter when using [TwoColumnLayout](https://neon.com/docs/community/component-guide#twocolumnlayout)
- For [TechCards](https://neon.com/docs/community/component-guide#techcards), always check that the SVG file exists in `/public/images/technology-logos/`
- For [DetailIconCards](https://neon.com/docs/community/component-guide#detailiconcards), use only icon names that are mapped in the component code
- Choose [DocsList](https://neon.com/docs/community/component-guide#docslist) themes based on content type: default for tasks, `docs` for documentation, `repo` for code
- Use the [comparison table](https://neon.com/docs/community/component-guide#techcards-vs-detailiconcards-vs-docslist) to choose between [TechCards](https://neon.com/docs/community/component-guide#techcards), [DetailIconCards](https://neon.com/docs/community/component-guide#detailiconcards), and [DocsList](https://neon.com/docs/community/component-guide#docslist)

---

## Component summary

This guide covers the most commonly used MDX components in Neon documentation. Each component includes:

- **MDX syntax**: Copy-paste ready code examples
- **Live rendering**: See exactly how components appear
- **Props documentation**: Available parameters and options
- **Best practices**: When and how to use each component

### Component categories

| **Category**                                                                                             | **Components**                                                                                                                                                                                                                                                                                                                                                                                                         | **Use Case**                           |
| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| **[Essential](https://neon.com/docs/community/component-guide#essential-components)**                    | [Admonition](https://neon.com/docs/community/component-guide#admonition), [Steps](https://neon.com/docs/community/component-guide#steps)                                                                                                                                                                                                                                                                               | Most commonly used components          |
| **[Tabbed Content](https://neon.com/docs/community/component-guide#tabbed-content)**                     | [CodeTabs](https://neon.com/docs/community/component-guide#codetabs), [Tabs](https://neon.com/docs/community/component-guide#tabs)                                                                                                                                                                                                                                                                                     | Organizing content into tabs           |
| **[Content organization](https://neon.com/docs/community/component-guide#content-organization)**         | [TechCards](https://neon.com/docs/community/component-guide#techcards--detailiconcards), [DetailIconCards](https://neon.com/docs/community/component-guide#techcards--detailiconcards), [DefinitionList](https://neon.com/docs/community/component-guide#definitionlist), [DocsList](https://neon.com/docs/community/component-guide#docslist), [InfoBlock](https://neon.com/docs/community/component-guide#infoblock) | Structure and navigation               |
| **[Interactive elements](https://neon.com/docs/community/component-guide#interactive-elements)**         | [CheckList](https://neon.com/docs/community/component-guide#checklist), [CheckItem](https://neon.com/docs/community/component-guide#checkitem), [CTA](https://neon.com/docs/community/component-guide#cta-call-to-action), [NeedHelp](https://neon.com/docs/community/component-guide#needhelp)                                                                                                                        | User engagement and interaction        |
| **[Common shared components](https://neon.com/docs/community/component-guide#common-shared-components)** | [LinkAPIKey](https://neon.com/docs/community/component-guide#linkapikey), [FeatureBetaProps](https://neon.com/docs/community/component-guide#featurebetaprops)                                                                                                                                                                                                                                                         | Reusable content and status indicators |

For specialized components and specific use cases, see the [Component Specialized Guide](https://neon.com/docs/community/component-specialized).

--- [Document source](https://neon.com/docs/community/component-icon-guide.md) ---

> Summary: Icon reference for Neon docs components, covering two systems: TechCards (colorful technology logos, kebab-case names) and DetailIconCards (monochrome feature icons). Use this page to find the exact icon name and correct component when authoring cards. TechCards uses kebab-case. DetailIconCards accepts camelCase or kebab-case. Also covers SVG file locations.

# Component icon guide

Complete reference for all icon systems and usage

Last updated: 2026-10-08

A comprehensive guide to all icon systems used in Neon documentation. This guide helps you understand which icon system to use and how to implement them correctly.

**What you will learn:**

- How to choose the right icon system for your use case
- Which icons are available in each system
- How to implement icons correctly in components
- Best practices for icon usage and troubleshooting

**Related topics**

- [Component Guide](https://neon.com/docs/community/component-guide)
- [Component Specialized Guide](https://neon.com/docs/community/component-specialized)
- [Component Architecture](https://neon.com/docs/community/component-architecture)
- [Documentation Contribution Guide](https://neon.com/docs/community/contribution-guide)

## Quick navigation

- [Icon system overview](https://neon.com/docs/community/component-icon-guide#icon-system-overview) - Understanding the different icon systems
- [TechCards Icons](https://neon.com/docs/community/component-icon-guide#techcards-icons) - Technology logos and frameworks
- [DetailIconCards Icons](https://neon.com/docs/community/component-icon-guide#detailiconcards-icons) - Feature and service icons
- [Icon usage guidelines](https://neon.com/docs/community/component-icon-guide#icon-usage-guidelines) - Best practices and conventions
- [Icon Decision Tree](https://neon.com/docs/community/component-icon-guide#icon-decision-tree) - Which icon system to use when

---

## Icon system overview

Neon documentation uses multiple icon systems for different components. Understanding which system to use is crucial for proper implementation.

### Available icon systems

1. **TechCards Icons** - Colorful technology logos and framework icons
2. **DetailIconCards Icons** - Monochrome feature and service icons
3. **DocsList Icons** - Simple navigation and action icons

### Component compatibility

| Component           | Icon System           | Use Case                       |
| ------------------- | --------------------- | ------------------------------ |
| **TechCards**       | TechCards Icons       | Technology/framework showcases |
| **DetailIconCards** | DetailIconCards Icons | Feature/service showcases      |
| **DocsList**        | Built-in themes       | Documentation links            |

### Usage example

```mdx
<DetailIconCards>
  <a
    href="/docs/ai/openai"
    title="OpenAI integration"
    description="Build AI features with OpenAI"
    icon="openai"
  >
    OpenAI Integration
  </a>
  <a
    href="/docs/ai/langchain"
    title="LangChain integration"
    description="Create AI workflows with LangChain"
    icon="langchain"
  >
    LangChain Integration
  </a>
</DetailIconCards>
```

_For technical implementation details, see the [Icon Systems section](https://neon.com/docs/community/component-architecture#icon-systems) in the Component Architecture guide._

---

## Icon usage guidelines

### Choosing the right icon system

- **TechCards**: Use for technology and framework showcases
- **DetailIconCards**: Use for feature and service showcases
- **DocsList**: Use built-in themes for documentation links

### Icon naming conventions

- **TechCards**: Use kebab-case (for example, `node-js`, `next-js`)
- **DetailIconCards**: Use camelCase or kebab-case as defined in the mapping
- **File Requirements**: Ensure SVG files exist in the correct directories

### Best practices

1. **Test your icons**: Always verify that your chosen icon works in the target component
2. **Check both systems**: If an icon doesn't work in one system, try the other
3. **Use descriptive names**: Choose icon names that clearly represent the technology or feature
4. **Document your choices**: Keep track of which icons work in which components
5. **Fallback gracefully**: Provide alternative text or descriptions when icons aren't available

---

### Component selection guide

| Use Case            | Component       | Icon System           | Example                |
| ------------------- | --------------- | --------------------- | ---------------------- |
| Technology showcase | TechCards       | TechCards Icons       | Node.js, React, Python |
| Feature showcase    | DetailIconCards | DetailIconCards Icons | OpenAI, AWS, Database  |
| Documentation links | DocsList        | Built-in themes       | Guides, API docs       |
| Simple navigation   | DocsList        | Built-in themes       | Related topics         |

---

## Troubleshooting

### Common issues

1. **Icon not displaying**: Check that the icon name exists in the correct system
2. **Wrong icon system**: Verify you're using the right component for your icon
3. **Missing files**: Ensure SVG files exist in the correct directories
4. **Case sensitivity**: Icon names are case-sensitive

### Testing icons

To test if an icon works:

1. **TechCards**: Check if `{icon}.svg` exists in `/public/images/technology-logos/`
2. **DetailIconCards**: Check if the icon is mapped in the component code
3. **DocsList**: Use the built-in themes (default, docs, repo)

### Getting help

- Review the [Component Architecture](https://neon.com/docs/community/component-architecture) for technical details
- Test icons in a development environment before using in production

---

## Complete icon showcase

### TechCards Icons (Technology Logos)

#### Programming Languages & Frameworks

- [Bun](https://neon.com/docs/community/component-icon-guide#): JavaScript runtime (icon: bun)
- [Express](https://neon.com/docs/community/component-icon-guide#): Node.js web framework (icon: express)
- [Hasura](https://neon.com/docs/community/component-icon-guide#): GraphQL API engine (icon: hasura)
- [Hono](https://neon.com/docs/community/component-icon-guide#): Web framework (icon: hono)
- [Java](https://neon.com/docs/community/component-icon-guide#): Programming language (icon: java)
- [JavaScript](https://neon.com/docs/community/component-icon-guide#): Programming language (icon: javascript)
- [Kotlin](https://neon.com/docs/community/component-icon-guide#): Programming language (icon: kotlin)
- [Laravel](https://neon.com/docs/community/component-icon-guide#): PHP framework (icon: laravel)
- [Nest.js](https://neon.com/docs/community/component-icon-guide#): Node.js framework (icon: nest-js)
- [Next.js](https://neon.com/docs/community/component-icon-guide#): React framework (icon: next-js)
- [Node.js](https://neon.com/docs/community/component-icon-guide#): JavaScript runtime (icon: node-js)
- [Nuxt](https://neon.com/docs/community/component-icon-guide#): Vue framework (icon: nuxt)
- [Phoenix](https://neon.com/docs/community/component-icon-guide#): Elixir framework (icon: phoenix)
- [Python](https://neon.com/docs/community/component-icon-guide#): Programming language (icon: python)
- [Quarkus](https://neon.com/docs/community/component-icon-guide#): Java framework (icon: quarkus)
- [Rails](https://neon.com/docs/community/component-icon-guide#): Ruby framework (icon: rails)
- [React](https://neon.com/docs/community/component-icon-guide#): JavaScript library (icon: react)
- [Redwood SDK](https://neon.com/docs/community/component-icon-guide#): Full-stack framework (icon: redwoodsdk)
- [Reflex](https://neon.com/docs/community/component-icon-guide#): Python framework (icon: reflex)
- [Remix](https://neon.com/docs/community/component-icon-guide#): React framework (icon: remix)
- [Ruby](https://neon.com/docs/community/component-icon-guide#): Programming language (icon: ruby)
- [Rust](https://neon.com/docs/community/component-icon-guide#): Programming language (icon: rust)
- [Solid](https://neon.com/docs/community/component-icon-guide#): JavaScript library (icon: solid)
- [Svelte](https://neon.com/docs/community/component-icon-guide#): JavaScript framework (icon: svelte)
- [Symfony](https://neon.com/docs/community/component-icon-guide#): PHP framework (icon: symfony)
- [Vue](https://neon.com/docs/community/component-icon-guide#): JavaScript framework (icon: vue)

#### Cloud & Infrastructure

- [AWS S3 Bucket](https://neon.com/docs/community/component-icon-guide#): Cloud storage service (icon: aws-s3-bucket)
- [Backblaze](https://neon.com/docs/community/component-icon-guide#): Cloud storage and backup (icon: backblaze)
- [Heroku](https://neon.com/docs/community/component-icon-guide#): Cloud platform (icon: heroku)
- [Koyeb](https://neon.com/docs/community/component-icon-guide#): Cloud platform (icon: koyeb)
- [Netlify](https://neon.com/docs/community/component-icon-guide#): Web hosting platform (icon: netlify)
- [Railway](https://neon.com/docs/community/component-icon-guide#): Deployment platform (icon: railway)
- [Render](https://neon.com/docs/community/component-icon-guide#): Cloud platform (icon: render)
- [Vercel](https://neon.com/docs/community/component-icon-guide#): Deployment platform (icon: vercel)

#### Databases & Data

- [Convex](https://neon.com/docs/community/component-icon-guide#): Backend platform (icon: convex)
- [Entity](https://neon.com/docs/community/component-icon-guide#): Data modeling tool (icon: entity)
- [Estuary](https://neon.com/docs/community/component-icon-guide#): Data streaming platform (icon: estuary)
- [Exograph](https://neon.com/docs/community/component-icon-guide#): GraphQL framework (icon: exograph)
- [Ferret](https://neon.com/docs/community/component-icon-guide#): Data processing tool (icon: ferret)
- [Kafka](https://neon.com/docs/community/component-icon-guide#): Stream processing platform (icon: kafka)
- [Knex](https://neon.com/docs/community/component-icon-guide#): SQL query builder (icon: knex)
- [Liquibase](https://neon.com/docs/community/component-icon-guide#): Database migration tool (icon: liquibase)
- [Materialize](https://neon.com/docs/community/component-icon-guide#): Streaming database (icon: materialize)
- [Neon](https://neon.com/docs/community/component-icon-guide#): Serverless Postgres (icon: neon)
- [Outerbase](https://neon.com/docs/community/component-icon-guide#): Database interface (icon: outerbase)
- [Draxlr](https://neon.com/docs/community/component-icon-guide#): Database interface (icon: draxlr)
- [Polyscale](https://neon.com/docs/community/component-icon-guide#): Database proxy (icon: polyscale)
- [PostgreSQL](https://neon.com/docs/community/component-icon-guide#): Database system (icon: postgresql)
- [Prisma](https://neon.com/docs/community/component-icon-guide#): ORM for Node.js (icon: prisma)
- [Sequelize](https://neon.com/docs/community/component-icon-guide#): ORM for Node.js (icon: sequelize)
- [Sequin](https://neon.com/docs/community/component-icon-guide#): Data synchronization (icon: sequin)
- [Snowflake](https://neon.com/docs/community/component-icon-guide#): Data warehouse (icon: snowflake)
- [SQLAlchemy](https://neon.com/docs/community/component-icon-guide#): Python ORM (icon: sqlalchemy)
- [StepZen](https://neon.com/docs/community/component-icon-guide#): GraphQL platform (icon: stepzen)
- [Supabase](https://neon.com/docs/community/component-icon-guide#): Backend platform (icon: supabase)
- [Tortoise ORM](https://neon.com/docs/community/component-icon-guide#): Python ORM (icon: tortoise-orm)
- [TypeORM](https://neon.com/docs/community/component-icon-guide#): TypeScript ORM (icon: typeorm)
- [Drizzle](https://neon.com/docs/community/component-icon-guide#): TypeScript ORM (icon: drizzle)

#### Services & APIs

- [Cloudinary](https://neon.com/docs/community/component-icon-guide#): Cloud media management (icon: cloudinary)
- [ImageKit](https://neon.com/docs/community/component-icon-guide#): Image optimization (icon: imagekit)
- [Inngest](https://neon.com/docs/community/component-icon-guide#): Background job platform (icon: inngest)
- [Micronaut](https://neon.com/docs/community/component-icon-guide#): Java framework (icon: micronaut)
- [Neo Tax](https://neon.com/docs/community/component-icon-guide#): Tax calculation service (icon: neo-tax)
- [OAuth](https://neon.com/docs/community/component-icon-guide#): Authentication protocol (icon: oauth)
- [Okta](https://neon.com/docs/community/component-icon-guide#): Identity platform (icon: okta)
- [Uploadcare](https://neon.com/docs/community/component-icon-guide#): File handling service (icon: uploadcare)

### DetailIconCards Icons (Feature Icons)

#### AI & Machine Learning

- [LangChain](https://neon.com/docs/community/component-icon-guide#): AI framework (icon: langchain)
- [LlamaIndex](https://neon.com/docs/community/component-icon-guide#): Data framework for LLMs (icon: llamaindex)
- [Ollama](https://neon.com/docs/community/component-icon-guide#): Local LLM framework (icon: ollama)
- [OpenAI](https://neon.com/docs/community/component-icon-guide#): AI platform (icon: openai)

#### Development Tools

- [Atom](https://neon.com/docs/community/component-icon-guide#): Code editor (icon: atom)
- [Binary Code](https://neon.com/docs/community/component-icon-guide#): Programming and code (icon: binary-code)
- [Bug](https://neon.com/docs/community/component-icon-guide#): Debugging and testing (icon: bug)
- [CLI](https://neon.com/docs/community/component-icon-guide#): Command line interface (icon: cli)
- [CLI Cursor](https://neon.com/docs/community/component-icon-guide#): Terminal cursor (icon: cli-cursor)
- [Code](https://neon.com/docs/community/component-icon-guide#): Programming and development (icon: code)
- [GitHub](https://neon.com/docs/community/component-icon-guide#): Code repository (icon: github)
- [Hook](https://neon.com/docs/community/component-icon-guide#): Development hooks (icon: hook)
- [Ladder](https://neon.com/docs/community/component-icon-guide#): Development progression (icon: ladder)
- [Laptop](https://neon.com/docs/community/component-icon-guide#): Development machine (icon: laptop)
- [Setup](https://neon.com/docs/community/component-icon-guide#): Configuration and setup (icon: setup)
- [Wrench](https://neon.com/docs/community/component-icon-guide#): Tools and utilities (icon: wrench)

#### Business & Analytics

- [A Chart](https://neon.com/docs/community/component-icon-guide#): Analytics and charts (icon: a-chart)
- [App Store](https://neon.com/docs/community/component-icon-guide#): Application marketplace (icon: app-store)
- [Calendar Day](https://neon.com/docs/community/component-icon-guide#): Scheduling and time (icon: calendar-day)
- [Cards](https://neon.com/docs/community/component-icon-guide#): Card-based interface (icon: cards)
- [Check](https://neon.com/docs/community/component-icon-guide#): Verification and approval (icon: check)
- [Cheque](https://neon.com/docs/community/component-icon-guide#): Payment processing (icon: cheque)
- [Chart Bar](https://neon.com/docs/community/component-icon-guide#): Data visualization (icon: chart-bar)
- [CSV](https://neon.com/docs/community/component-icon-guide#): Data format (icon: csv)
- [Data](https://neon.com/docs/community/component-icon-guide#): Data and information (icon: data)
- [Metrics](https://neon.com/docs/community/component-icon-guide#): Performance metrics (icon: metrics)
- [Performance](https://neon.com/docs/community/component-icon-guide#): System performance (icon: performance)
- [Queries](https://neon.com/docs/community/component-icon-guide#): Database queries (icon: queries)
- [Research](https://neon.com/docs/community/component-icon-guide#): Development research (icon: research)
- [Stopwatch](https://neon.com/docs/community/component-icon-guide#): Timing and performance (icon: stopwatch)
- [Table](https://neon.com/docs/community/component-icon-guide#): Data tables (icon: table)
- [Todo](https://neon.com/docs/community/component-icon-guide#): Task management (icon: todo)
- [Transactions](https://neon.com/docs/community/component-icon-guide#): Database transactions (icon: transactions)
- [Trend Up](https://neon.com/docs/community/component-icon-guide#): Growth and trends (icon: trend-up)

#### UI & Design

- [Audio Jack](https://neon.com/docs/community/component-icon-guide#): Audio connectivity (icon: audio-jack)
- [Cards](https://neon.com/docs/community/component-icon-guide#): Card-based interface (icon: cards)
- [Gamepad](https://neon.com/docs/community/component-icon-guide#): Gaming and interaction (icon: gamepad)
- [GUI](https://neon.com/docs/community/component-icon-guide#): Graphical user interface (icon: gui)
- [Screen](https://neon.com/docs/community/component-icon-guide#): Display and interface (icon: screen)
- [Sparkle](https://neon.com/docs/community/component-icon-guide#): Visual effects (icon: sparkle)
- [User](https://neon.com/docs/community/component-icon-guide#): User interface (icon: user)

#### Infrastructure & Services

- [Autoscaling](https://neon.com/docs/community/component-icon-guide#): Automatic scaling (icon: autoscaling)
- [AWS](https://neon.com/docs/community/component-icon-guide#): Cloud computing platform (icon: aws)
- [Branching](https://neon.com/docs/community/component-icon-guide#): Database branching (icon: branching)
- [Database](https://neon.com/docs/community/component-icon-guide#): Database systems (icon: database)
- [Discord](https://neon.com/docs/community/component-icon-guide#): Communication platform (icon: discord)
- [Download](https://neon.com/docs/community/component-icon-guide#): File download (icon: download)
- [Enable](https://neon.com/docs/community/component-icon-guide#): Feature enablement (icon: enable)
- [Filter](https://neon.com/docs/community/component-icon-guide#): Data filtering (icon: filter)
- [Find Replace](https://neon.com/docs/community/component-icon-guide#): Search and replace (icon: find-replace)
- [Gear](https://neon.com/docs/community/component-icon-guide#): Settings and configuration (icon: gear)
- [Globe](https://neon.com/docs/community/component-icon-guide#): Global connectivity (icon: globe)
- [Handshake](https://neon.com/docs/community/component-icon-guide#): Partnerships and agreements (icon: handshake)
- [Heroku](https://neon.com/docs/community/component-icon-guide#): Cloud platform (icon: heroku)
- [Hourglass](https://neon.com/docs/community/component-icon-guide#): Time and waiting (icon: hourglass)
- [Import](https://neon.com/docs/community/component-icon-guide#): Data import (icon: import)
- [Invert](https://neon.com/docs/community/component-icon-guide#): Data transformation (icon: invert)
- [Lock Landscape](https://neon.com/docs/community/component-icon-guide#): Security and access control (icon: lock-landscape)
- [Neon](https://neon.com/docs/community/component-icon-guide#): Serverless Postgres (icon: neon)
- [Network](https://neon.com/docs/community/component-icon-guide#): Network connectivity (icon: network)
- [Postgres](https://neon.com/docs/community/component-icon-guide#): Database system (icon: postgres)
- [Prisma](https://neon.com/docs/community/component-icon-guide#): ORM for Node.js (icon: prisma)
- [Privacy](https://neon.com/docs/community/component-icon-guide#): Data privacy (icon: privacy)
- [Puzzle](https://neon.com/docs/community/component-icon-guide#): Problem solving (icon: puzzle)
- [Refresh](https://neon.com/docs/community/component-icon-guide#): Data refresh (icon: refresh)
- [Respond Arrow](https://neon.com/docs/community/component-icon-guide#): Response and feedback (icon: respond-arrow)
- [Scale Up](https://neon.com/docs/community/component-icon-guide#): Scaling and growth (icon: scale-up)
- [Search](https://neon.com/docs/community/component-icon-guide#): Search functionality (icon: search)
- [Split Branch](https://neon.com/docs/community/component-icon-guide#): Code branching (icon: split-branch)
- [SQL](https://neon.com/docs/community/component-icon-guide#): Database queries (icon: sql)
- [Unlock](https://neon.com/docs/community/component-icon-guide#): Access control (icon: unlock)
- [Vercel](https://neon.com/docs/community/component-icon-guide#): Deployment platform (icon: vercel)
- [Wallet](https://neon.com/docs/community/component-icon-guide#): Payment and billing (icon: wallet)
- [Warning](https://neon.com/docs/community/component-icon-guide#): Alerts and warnings (icon: warning)
- [X](https://neon.com/docs/community/component-icon-guide#): Close or cancel (icon: x)
- [Zap](https://neon.com/docs/community/component-icon-guide#): Realtime and instant operations (icon: zap)

---

## Summary

This guide provides an overview of Neon's icon systems and usage guidelines. For complete icon listings and detailed examples, refer to the [Component Guide](https://neon.com/docs/community/component-guide).

### Key takeaways

- **TechCards** uses colorful technology logos from `/public/images/technology-logos/`
- **DetailIconCards** uses monochrome feature icons mapped in component code
- **DocsList** uses built-in themes for simple navigation
- Always test icons in the target component before using
- Choose the right component based on your use case, not just the icon availability

--- [Document source](https://neon.com/docs/community/component-specialized.md) ---

> Summary: Reference for infrequently used Neon docs MDX components. Covers ExternalCode, YoutubeIframe, Video, feature status indicators (PrivatePreview, PublicPreview, FeatureBeta), auto-generated SDK components, RequestForm, AgentSkillsTip, MCPTools, and CommunityBanner. Use this page when the main Component Guide does not cover the component you need. Each entry includes copy-paste MDX syntax, live rendering, dependency requirements, and guidance on when to choose a simpler alternative.

# Component specialized guide

Specialized and less common components for specific use cases

Last updated: 2026-10-14

A comprehensive reference for specialized and less commonly used MDX components in Neon documentation. This guide covers components used in specific scenarios, specialized workflows, and edge cases.

**Note: Component status**

Some components in this guide are currently unused or may be deprecated in future updates. These are included for reference but may be removed from the codebase.

**What you will learn:**

- How to use specialized MDX components for specific use cases
- When to choose specialized components over common ones
- Technical requirements and dependencies for specialized components
- Best practices for complex component implementations

**Related topics**

- [Component Guide](https://neon.com/docs/community/component-guide)
- [Component Icon Guide](https://neon.com/docs/community/component-icon-guide)
- [Component Architecture](https://neon.com/docs/community/component-architecture)
- [Documentation Contribution Guide](https://neon.com/docs/community/contribution-guide)

## Quick navigation

- [Code display](https://neon.com/docs/community/component-specialized#code-display) - Enhanced code blocks and external code
- [Media components](https://neon.com/docs/community/component-specialized#media-components) - Video and multimedia content
- [Specialized shared components](https://neon.com/docs/community/component-specialized#specialized-shared-components) - Feature status indicators
- [SDK components](https://neon.com/docs/community/component-specialized#sdk-components) - Auto-generated SDK documentation
- [Utility components](https://neon.com/docs/community/component-specialized#utility-components) - Forms and specialized UI elements
- [Specialized components](https://neon.com/docs/community/component-specialized#specialized-components) - Complex and specialized functionality
- [Community components](https://neon.com/docs/community/component-specialized#community-components) - Community engagement features

---

## Code display

Enhanced code blocks and external code embedding.

### ExternalCode

Embed code from external sources or files.

```mdx
<ExternalCode url="https://raw.githubusercontent.com/neondatabase/neon/master/README.md" />
```

**Live preview:**

_[External code loaded from GitHub README.md with syntax highlighting]_

Example of external code loading (mocked for showcase):

```markdown
# Neon Database

Serverless Postgres built for the cloud.

## Key Features

- **Instant provisioning**: Create databases in seconds
- **Autoscaling**: Scale compute up and down automatically
- **Branching**: Create database branches like Git
- **Scale to zero**: Save costs when inactive

## Quick Start

1. Sign up at console.neon.tech
2. Create your first project
3. Connect using your preferred client
```

---

## Media components

Components for embedding and displaying multimedia content.

### YoutubeIframe

Embedded YouTube video player.

```mdx
<YoutubeIframe embedId="IcoOpnAcO1Y" />
```

**Live preview:**

[Watch on YouTube](https://youtube.com/watch?v=IcoOpnAcO1Y)

---

### Video

Native video player component.

```mdx
<Video
  sources={[{ src: '/videos/pages/doc/neon-mcp.mp4', type: 'video/mp4' }]}
  width={960}
  height={1080}
/>
```

**Live preview:**

---

## Specialized shared components

Status indicators for features in different stages of development and release.

### Feature Announcements

Status indicators for features in different stages:

```mdx
<PrivatePreview />
<PrivatePreviewEnquire />
<PublicPreview />
<FeatureBeta />
<NewPricing />
<MigrationAssistant />
```

**Live preview:**

**Coming soon: Private Preview**

This feature is currently accessible in Private Preview only.

**Coming soon: Private Preview**

This feature is in private preview: it's not ready for production use, and it may be briefly unavailable as we deploy updates. To get access, [sign up here](https://neon.com/blog/were-building-backends#access).

**Note: Public Preview**

This feature is in Public Preview. Please provide [Feedback](https://console.neon.tech/app/projects?modal=feedback) from the Neon Console or by connecting with us on [Discord](https://neon.com/discord).

**Note: Beta**

This feature is in beta. Please give us [Feedback](https://console.neon.tech/app/projects?modal=feedback) from the Neon Console or by connecting with us on [Discord](https://neon.com/discord). For more ways to reach us, see [Send feedback](https://neon.com/docs/introduction/feedback).

**Coming soon: New pricing plans**

On February 19th, 2024, Neon will launch new, simplified pricing plans. You can see the [details of all the plans here](https://neon.com/2024-plan-updates).

**Note: New feature**

If you are looking to migrate your database to Neon, you may want to try our new **Migration Assistant**, which can help. Read the [guide](https://neon.com/docs/import/migration-assistant) to learn more.

---

### EarlyAccessProps

Status indicator for early access features with custom feature name.

```mdx
<EarlyAccessProps feature_name="My Feature" />
```

**Live preview:**

**Coming soon: Early access**

**My Feature** is currently in early access.

---

## SDK components

Auto-generated components specifically for SDK documentation. These load content from [shared templates](https://neon.com/docs/community/component-guide#common-shared-components).

### Getting Started

```mdx
<GetStarted sdkName="Next.js" />
```

### SDK Type Components

```mdx
<SdkUser sdkName="React" />
<SdkProject sdkName="Node.js" />
<SdkUseUser sdkName="Vue" />
```

**Note**: These SDK components require corresponding files in the `content/docs/shared-content/` directory and proper configuration in `sharedMdxComponents`.

---

## Utility components

Specialized UI components for specific use cases.

### RequestForm

Contact or request submission form.

There are types (`extension` and `regions`) defined in `src/components/shared/request-form/data.js`. To define a new type, define a new config in `data.js` and register it in `DATA` there.

```mdx
<RequestForm type="extension" />
```

**Live preview:**

> **Request a new extension**
>
> Looking for a specific Postgres extension in Neon? Submit a request through [Neon support](https://neon.com/docs/introduction/support) or let us know in the [Neon Discord](https://neon.com/discord).

---

### ChatOptions

Chat interface options component with a specific use case in the sidebar navigation.

**Important:** This component is designed for internal navigation use only and should not be used in regular documentation content.

---

## Specialized components

Complex components for specialized functionality and workflows.

### AgentSkillsTip

Shared tip admonition that links to the Agent Skills page with a customizable topic.

```mdx
<AgentSkillsTip skill_topic="the Neon Serverless Driver, general connection advice," />
```

**Live preview:**

**Tip: AI assistant support**

Neon's [Agent Skills](https://neon.com/docs/ai/agent-skills) give AI coding assistants context about the Neon Serverless Driver, general connection advice, and other Neon features. Install them for more accurate code suggestions.

---

### MCPTools

Model Context Protocol tools integration component.

```mdx
<MCPTools />
```

**Live preview:**

## Available tools

Tools are grouped into categories. Use the `?category=` URL parameter to restrict which categories are active. You can pass it more than once to enable multiple categories.

| Category                          | What it enables                                                                                                                                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Project management (`projects`)   | List, create, describe, and delete projects; count projects; get project and branch consumption; list organizations                                                                                                |
| Branch management (`branches`)    | Create, reset, and delete branches; manage Postgres roles and databases                                                                                                                                            |
| Compute endpoints (`endpoints`)   | List, create, start, suspend, and restart branch computes                                                                                                                                                          |
| Snapshots (`snapshots`)           | Create, restore, and schedule snapshots                                                                                                                                                                            |
| Schema (`schema`)                 | Inspect tables and columns; compare schemas                                                                                                                                                                        |
| SQL (`querying`)                  | Execute queries and transactions; apply schema changes on a temporary branch; run the same diagnostics as `neon inspect db`                                                                                        |
| Managed Better Auth (`neon_auth`) | Provision Auth; configure branch settings (localhost access, email and password, email provider, plugins, webhooks); manage OAuth providers, the OAuth provider plugin and its clients, trusted domains, and users |
| Neon Data API (`data_api`)        | Enable, update, and disable the Data API for a branch                                                                                                                                                              |
| Observability (`observability`)   | Query function and storage logs; check AI Gateway availability                                                                                                                                                     |
| Documentation (`docs`)            | Search and read Neon docs, the API reference, guides, the PostgreSQL tutorial, the blog, and the changelog from within your assistant (no OAuth required)                                                          |
| Functions (`functions`)           | List, deploy, update, and delete Neon Functions                                                                                                                                                                    |
| Object storage (`storage`)        | Manage buckets and objects; create presigned URLs                                                                                                                                                                  |
| Realtime (`realtime`)             | Enable and disable Realtime for a branch; get and rotate its secret                                                                                                                                                |

Search and navigation tools (search across projects, fetch resource details by ID) are available by default but disabled in [project-scoped mode](https://neon.com/docs/ai/neon-mcp-server#project-scoped-mode).

Schema tools accept schema-qualified table names, such as `crm.contacts`. An unqualified name resolves against the database `search_path`, which defaults to the `public` schema.

**Note:** The `observability` tools query [Neon Functions logs](https://neon.com/docs/compute/functions/logs) and [object storage logs](https://neon.com/docs/storage/logs), which are part of the Neon backend, currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). Log querying returns results only for projects in a supported region. Database diagnostics via `inspect_database` are under `querying`, not `observability`.

---

## Community components

Components for community engagement and interaction.

### CommunityBanner

Community engagement banner for promoting community participation.

```mdx
<CommunityBanner buttonText="Join Discord" buttonUrl="https://neon.com/discord" logo="discord">
  Connect with the Neon community!
</CommunityBanner>
```

**Live preview:**

Connect with the Neon community!: [Join Discord](https://neon.com/discord)

---

## Usage guidelines

### When to use specialized components

- **ExternalCode**: When you need to embed code from external repositories or sources
- **Media Components**: For video tutorials, demos, or multimedia content
- **Specialized Shared Components**: For feature announcements and status updates
- **SDK Components**: For auto-generated SDK documentation
- **Utility Components**: For specialized forms and navigation elements
- **Specialized Components**: For AI-powered features and complex workflows
- **Community Components**: For community engagement and participation

### Best practices

- **Use sparingly**: These components are specialized and should be used only when appropriate
- **Test thoroughly**: Specialized components may have specific requirements or dependencies
- **Document usage**: When using specialized components, document the specific use case
- **Consider alternatives**: Always consider if a simpler component would work better
- **Follow patterns**: Use established patterns for similar functionality

### Component dependencies

Some specialized components have specific dependencies:

- **SDK Components**: Require shared content files and proper configuration
- **RequestForm**: Requires specific type configurations in the data files
- **Media Components**: May require specific video formats or hosting
- **Specialized Components**: May have AI or external service dependencies

---

## Component summary

This guide covers specialized MDX components used in specific scenarios. Each component includes:

- **MDX syntax**: Copy-paste ready code examples
- **Live rendering**: See exactly how components appear
- **Usage guidelines**: When and how to use each component
- **Dependencies**: Requirements and configurations needed

### Component categories

| **Category**                                                                                                             | **Components**                                                                                                                                                                                   | **Use Case**                          |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| **[Code Display](https://neon.com/docs/community/component-specialized#code-display)**                                   | [ExternalCode](https://neon.com/docs/community/component-specialized#externalcode)                                                                                                               | External code embedding               |
| **[Media Components](https://neon.com/docs/community/component-specialized#media-components)**                           | [YoutubeIframe](https://neon.com/docs/community/component-specialized#youtubeiframe), [Video](https://neon.com/docs/community/component-specialized#video)                                       | Multimedia content                    |
| **[Specialized Shared Components](https://neon.com/docs/community/component-specialized#specialized-shared-components)** | [Feature Announcements](https://neon.com/docs/community/component-specialized#feature-announcements), [EarlyAccessProps](https://neon.com/docs/community/component-specialized#earlyaccessprops) | Feature status indicators             |
| **[SDK Components](https://neon.com/docs/community/component-specialized#sdk-components)**                               | [Getting Started](https://neon.com/docs/community/component-specialized#getting-started), [SDK Type Components](https://neon.com/docs/community/component-specialized#sdk-type-components)       | Auto-generated SDK documentation      |
| **[Utility Components](https://neon.com/docs/community/component-specialized#utility-components)**                       | [RequestForm](https://neon.com/docs/community/component-specialized#requestform), [ChatOptions](https://neon.com/docs/community/component-specialized#chatoptions)                               | Specialized UI elements               |
| **[Specialized Components](https://neon.com/docs/community/component-specialized#specialized-components)**               | [AgentSkillsTip](https://neon.com/docs/community/component-specialized#agentskillstip), [MCPTools](https://neon.com/docs/community/component-specialized#mcptools)                               | Complex and specialized functionality |
| **[Community Components](https://neon.com/docs/community/component-specialized#community-components)**                   | [CommunityBanner](https://neon.com/docs/community/component-specialized#communitybanner)                                                                                                         | Community engagement                  |

For commonly used components, see the [Component Guide](https://neon.com/docs/community/component-guide).

--- [Document source](https://neon.com/docs/community/contribution-guide.md) ---

> Summary: How to submit edits and new guides to the neondatabase/website repository. Edit files directly on GitHub or fork the repo and open a pull request. The full authoring workflow covers frontmatter fields, navigation.yaml sidebar updates, Markdown syntax, CodeTabs, admonitions, image paths, and style rules for voice, capitalization, connection strings, and fake user data. Also covers the doc AI tools (Cursor and Claude slash commands) for consistency checks, redirects, and guided writing.

# Docs contribution guide

Learn how to contribute to the Neon documentation

Last updated: 2026-09-17

This page covers everything you need to contribute to the Neon documentation, whether you're fixing a typo or writing a full guide.

**Note: TL;DR: Contributing to the Neon Docs**

- You can edit files on GitHub via the **Edit this page** link on our documentation pages or by forking the [neondatabase/website](https://github.com/neondatabase/website) repository and submitting a pull request.
- If you want to contribute a guide, we provide a [template](https://github.com/neondatabase/website/blob/main/content/docs/guides/GUIDE_TEMPLATE.md) to help you get started. See [How to contribute](https://neon.com/docs/community/contribution-guide#how-to-contribute) for details.
- Reference this contribution guide as needed for Markdown and style guidelines.

## Why should you contribute?

Open-source projects are always evolving. Contributing to documentation is a good starting point for open source beginners, and a way for experienced developers to share knowledge with the community.

By contributing to the Neon docs, you're helping us create a stronger learning resource for all developers. Whether you've found a typo, a section that's hard to understand, or a topic that's missing, we'd love to have your contribution.

## How to contribute

Documentation source files are located in the [neondatabase/website](https://github.com/neondatabase/website) repository, in the `/content/docs` directory. To contribute, you have two options:

1. Edit files directly on GitHub.
2. Fork the [neondatabase/website](https://github.com/neondatabase/website) repository, create a branch for your changes, and submit a pull request.

If you prefer the first option, which is great for edits and small updates, there is an **Edit this page** link at the bottom of each Neon documentation page.

![GitHub edit this page link](https://neon.com/docs/community/edit_this_page.png)

Clicking the link takes you to the Markdown file in GitHub, where you can click the **Edit this page** icon to make a change. When you finish editing, commit your changes to create a pull request.

If you would rather fork the [neondatabase/website](https://github.com/neondatabase/website) repository and submit a pull request, but you're not familiar with the process, we suggest going through the [GitHub Open Source Guide](https://opensource.guide/how-to-contribute/#opening-a-pull-request). This guide describes how to fork a repository, create a branch, and submit a pull request. To help you get started, we provide a [GUIDE_TEMPLATE.md](https://github.com/neondatabase/website/blob/main/content/docs/guides/GUIDE_TEMPLATE.md) file, which you can find in the [neondatabase/website](https://github.com/neondatabase/website) repository, under the `/content/docs/guides` directory. After you create a branch, copy the template file and rename it. Don't forget to add your guide to the sidebar. See [Add a new page](https://neon.com/docs/community/contribution-guide#add-a-new-page).

## Markdown

Neon uses Markdown as the documentation source format. Markdown is a lightweight markup language that lets you add formatting elements to plaintext text documents. It's designed to be easy to read and easy to write.

If you're new to Markdown, GitHub provides an excellent guide to get you started. The [GitHub Markdown Documentation](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) covers most of the basic writing and formatting syntax you'll need to contribute to the Neon docs.

For advanced formatting and custom components, see the [Component Guide](https://neon.com/docs/community/component-guide). To add visual diagrams to your documentation, check out our [Mermaid Diagrams Guide](https://neon.com/docs/community/mermaid-diagrams).

## Preview changes in VSCode

At Neon, we use VSCode for writing documentation. VSCode includes a built-in markdown previewer that you can use to view your changes locally.

To use this feature, open the command palette (⌘ + ⇧ + V on Mac or Ctrl + Shift + V on Windows). This opens a preview window for viewing your changes in formatted Markdown.

## Contribution review process

After you submit a contribution, the Neon documentation team reviews your changes, provides feedback, and merges the pull request when it's ready.

Please reach out to us on our [Discord Server](https://neon.com/discord) if you have any questions or need further assistance.

## Documentation file structure

The Neon documentation file structure reflects the navigation you see on the website. However, the order of the directories under `/content/docs/` is alphabetical.

```text
└── content
  └── docs
    ├── ai
    ├── community
    ├── connect
    ├── extensions
    ├── get-started
    ├── guides
    ├── introduction
    ├── manage
    ├── reference
    ├── security
    └── serverless
```

- Every Markdown file in the `/docs` folder becomes a documentation page unless it's defined with an `isDraft: true` property in the page [frontmatter](https://neon.com/docs/community/contribution-guide#markdown-frontmatter).
- Folder and file names should use [kebab-case](https://en.wiktionary.org/wiki/kebab_case) (hyphens between words).

## Documentation table of contents

This section describes how to modify the documentation table of contents, also referred to as the "sidebar". Adding, removing, or moving a page in the documentation requires updating the sidebar. The sidebar is defined in `navigation.yaml`, which you can find at the root of the `/docs` directory.

Refer to the [## Navigation](https://github.com/neondatabase/website/blob/main/content/docs/README.md#navigation) in the docs README for more information on how to update the sidebar.

## Markdown frontmatter

Each Neon documentation Markdown file includes a frontmatter section at the beginning of the file containing file metadata. The frontmatter section is distinguished by three dashes, as shown here:

```yaml
---
tile: Page Title
enableTableOfContents: true
---
```

The only required attribute is `title`, which becomes the page title that appears on the page and the browser tab.

### Frontmatter attributes

Frontmatter attributes include:

| Attribute             | Description                                                                                                                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| subtitle              | A secondary title or description that appears on the page, under the main title.                                                                                                                                      |
| enableTableOfContents | A boolean flag (i.e., true or false) that tells the static site generator whether to generate a right-hand table of contents for the page. We recommend adding this option if your page has more than a few sections. |
| isDraft               | Adding this attribute and setting it to `true` prevents the page from becoming a documentation page and being searchable. Include this option to avoid publishing the content before it's ready.                      |
| redirectFrom          | A list of directory paths that should redirect to this file. This is useful if the page has moved and you want old URLs to continue working.                                                                          |
| updatedOn             | This attribute is added automatically. You do not need to add it.                                                                                                                                                     |

Example:

```yaml
---
title: Connect a Next.js application to Neon
subtitle: Set up a Neon project and connect from a Next.js application
enableTableOfContents: true
redirectFrom:
  - /docs/content/<old_directory_name>
updatedOn: '2023-10-07T12:25:27.662Z'
---
```

## Heading levels

The page title in the frontmatter is translated into an `h1` element when the page is converted to HTML.

Top-level section headings in the body of your document are defined with two hash characters, which is equivalent to an `h2` heading:

```md
## Section heading
```

To add a subsection heading, equivalent to an `h3`, add another `#` character:

```md
### Subsection heading
```

- Try to avoid heading levels beyond h4 (`####`).
- Do not skip a level, for example, do not go from `##` to `####`.
- Ensure there's a blank line before and after each heading.

## Common markup

```md
External link markup: [Example.com website](https://www.example.com/)
Neon documentation page link: [Connection from any application](https://neon.com/docs/connect/connect-from-any-app)
Neon documentation same page link: [Code blocks](https://neon.com/docs/community/contribution-guide#code-blocks)
Italics markup: _italic_
Bold markup: **strong**
monospace: `backtick`
```

## Comment tags

To comment out content in a markdown file use this construction:

```md
[comment]: <> (Single line comment.)

[comment]: <> (
Multiline comment.
You can't use line breaks or () parentheses here.
)
```

If you need to comment out more complicated blocks of code you can use JSX-style comments:

```md
{/*

content

*/}
```

Unfortunately, JSX-style comments have problems with Prettier, so in case of using them you should add your file to [.prettierignore](https://github.com/neondatabase/website/blob/main/.prettierignore).

## Code blocks

To insert a code block into your Markdown file, specify three backticks (```) on the lines before and after the code. Specify the language identifier to enable code highlighting, as in this example:

````md
```sql
SELECT * FROM posts ORDER BY id;
```
````

You can add language-specific highlighting to code blocks, as in the example above. See [Supported language highlighting for code blocks](https://shiki.matsu.io/languages).

Code block accepts the following options:

- `showLineNumbers`: Shows the line numbers in the code block
- `shouldWrap`: Enables code wrapping in the code block. This is useful for long commands or connection strings that would otherwise require the reader to scroll.

Example:

````md
```bash shouldWrap
A really long line that scrolls off the page
```
````

## Code tabs

To display code tabs, enclose all pieces of code within `<CodeTabs></CodeTabs>` and specify labels in order, as shown in the following example:

````md
<CodeTabs labels={["node-postgres", "postgres.js"]}>

```shell
npm install pg
```

```shell
npm install postgres
```

</CodeTabs>
````

To view this example in the Neon documentation, see [Create a Next.js project and add dependencies](https://neon.com/docs/guides/nextjs#create-a-nextjs-project-and-add-dependencies).

## Admonitions

The Neon documentation supports the following admonitions:

- Note
- Important
- Tip
- Warning
- Info

To use an admonition, enclose your text with `<Admonition></Admonition>` and specify the admonition type: `note`, `important`, `tip`, `warning`, and `info`. The default is `note`.

For a complete list of available components and their usage, see the [Component Guide](https://neon.com/docs/community/component-guide).

```md
<Admonition type="note">
This is an important note
</Admonition>
```

You can specify a title with the `title` property.

```md
<Admonition type="note" title="Very important note">
This is a very important note.
</Admonition>
```

Example output:

**Note: Very important note**

This is a very important note.

## Diagrams and screen captures

Neon uses Figma to create diagrams.

If you're interested in updating or adding a diagram, please open a GitHub issue with your suggestions. Please include a draft, if possible. You can use a tool like [tldraw](https://www.tldraw.com/) to create a draft.

For technical details about how components are implemented, see the [Component Architecture](https://neon.com/docs/community/component-architecture) guide.

If possible, please take screen captures on a high resolution monitor (UHD/4K). Screen captures should be unaltered (no borders or special effects).

Diagrams and images are stored in the `/public/docs` directory in the Neon website repository. The directory location of the diagram or image under `public` mirrors the location of the file that includes the diagram or image, as shown below:

Example file structure:

```md
├── content
│ ├── docs
│ │ ├── introduction
│ │ │ ├── architecture-overview.md

├── public
│ ├── docs
│ │ ├── introduction
│ │ │ ├── neon_architecture.png // put images in the public directory with the same name
```

To add an image to your Markdown file, add an entry that looks like this:

```md
![lakebase architecture diagram](https://neon.com/docs/introduction/neon_architecture.png)
```

## Style Guide

This section covers the style conventions we follow.

### Voice and language

The voice in the documentation should sound like one human being explaining something to another, while striking the right balance between being approachable and professional.

#### Guidelines

1. **Use contractions**:
   - **Do**: Use contractions like "it's", "don't", "you're" to make the tone more conversational.
     - _Example_: "It's essential to save your progress."
   - **Don't**: Overuse contractions, which can compromise clarity.

2. **Simplicity over jargon**:
   - **Do**: Choose simpler words when possible.
     - _Example_: "Use the tool," not "Utilize the instrument."
   - **Don't**: Oversimplify to the point of being inaccurate or leaving out useful context.

3. **Active voice**:
   - **Do**: Prefer active voice.
     - _Example_: "The software converts the file."
   - **Don't**: Over-rely on passive voice.
     - _Example_: "The file is converted by the software."

4. **Brief sentences**:
   - **Do**: Keep sentences concise.
     - _Example_: "Check the settings."

5. **Personalize when relevant**:
   - **Do**: Use "you" to address the reader.
     - _Example_: "You can adjust the setting."
   - **Don't**: Overdo direct addresses. Not every sentence should start with "You".

6. **Consistent terminology**:
   - **Do**: Stick to one term for one concept.
     - _Example_: Always use "dashboard". Don't mix that term with "control panel".
   - **Don't**: Confuse with synonyms.
     - _Example_: Switching between "log-in", "sign-in", and "access point".

7. **Examples for clarity**:
   - **Do**: Provide clear examples.
     - _Example_: "For instance, to upload a file, click on the 'Upload' button."

8. **Use US English**:
   - **Do**: Adhere to US English spelling and grammar rules.

9. **Avoid emojis and exclamations**:
   - **Don't**: Use emojis or exclamation marks in the documentation.

### Link instead of repeating text

Avoid repeating or duplicating information from other topics. Instead, link to the original source of information and explain why it is important.

### Capitalization

Use lowercase wherever possible.

For topic titles, use sentence-style capitalization. For example: "Create your first project"

Product names should align with the official names of the products, protocols, etc., maintaining exact capitalization.

#### UI text

When referencing specific user interface text, such as button labels or menu items, use the same capitalization displayed in the user interface wherever possible.

#### Feature names

Generally, feature names should be lowercase.

#### Other terms

Capitalize names of:

- Third-party organizations, software, and products. Kubernetes, Git, and Vercel.
- Methods or methodologies. Continuous Integration, Continuous Deployment, etc.

Follow the capitalization style used by the authoritative source, which may use non-standard case styles. For example: PostgreSQL, GitHub, npm.

### Fake user information

When including user information in connection details, API calls, or UI instructions, don't use real user information or email addresses.

- Use an email address ending in `@example.com` or `domain.com`.
- Use strings like `example_username` or one of the following diverse and non-gendered names: Zhang Kai, Alex Lopez, or Dana Smith.

### Connection strings

Connection strings should be defined as follows:

```text
postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

If you need to provide a connection string with realistic values, use one of the user names mentioned above, `AbC123dEf` for the password, and `dbname` for the database name:

```text
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

### Commands, parameters, values, filenames

Commands, parameters, values, filenames, error messages, connection strings, and other similar items should be enclosed in backticks. For example:

- "Run the `neon projects list` command."

- "Execute `git clone` to clone a Git repository..."

- `git clone` is a command that should be in lowercase, whereas Git is the product and should have a capital G.

- "A connection string has this format: `postgresql://[user]:[password]@[neon_hostname]/[dbname]`"

## Working with doc AI

The Neon website repo includes rules and commands (in Cursor and Claude) to keep documentation consistent. You don't need to memorize them.

- **Open the doc** you're editing so the right rules apply, then describe what you want in plain language.
- **Optional:** You can ask for specific help (for example "check consistency on this page," "use our style examples," or "walk me through the redirect steps.").
- **Curious what's available?** Ask: "What doc AI tools are available?" to see the list.
- All changes go through a pull request and human review.

For the full list of tools, see [AI tools for documentation](https://neon.com/docs/community/ai-tools).

## Additional Resources

These resources are also worth bookmarking:

- **[Component Guide](https://neon.com/docs/community/component-guide)**: Complete reference for common MDX components
- **[Component Specialized Guide](https://neon.com/docs/community/component-specialized)**: Advanced and specialized components
- **[Component Icon Guide](https://neon.com/docs/community/component-icon-guide)**: Icon systems and usage guidelines
- **[Component Architecture](https://neon.com/docs/community/component-architecture)**: Technical implementation details

--- [Document source](https://neon.com/docs/community/llms-markdown-guide.md) ---

> Summary: Neon documentation is available as plain Markdown for LLMs, API clients, and scripts. Request any docs URL with an `Accept: text/markdown` header or append `.md` to the path. Use this page when you need to programmatically fetch doc pages or discover all available content through the llms.txt index at https://neon.com/docs/llms.txt. Each Markdown response includes page location context, converted body content, and a "Related docs" section. HTML pages expose a `<link rel="alternate" type="text/markdown">` tag and an `X-LLMs-Txt` header so agents can discover Markdown URLs automatically.

# Getting Neon docs as Markdown

How to get our documentation as plain Markdown for LLMs, tools, and scripts

Last updated: 2026-10-09

Neon provides its documentation in plain Markdown so that LLMs, API clients, and scripts can consume it easily. We follow the [llms.txt](https://llmstxt.org/) approach: same URLs as the website, with Markdown available when requested.

## How to get Markdown

You can get Markdown by requesting it explicitly: use the same docs URL with an `Accept` header, or append `.md` to the path.

1. **Same URL, request Markdown:** Use the same path you would use in a browser (for example, `/docs/connect/choose-connection`). Send an `Accept: text/markdown` or `Accept: text/plain` header, or make the request with a user agent string associated with ChatGPT, Claude, Cursor, etc., as long as the `Accept` header doesn't include `text/html`. We respond with the Markdown version of that page. For example:

   ```bash
   curl -H "Accept: text/markdown" https://neon.com/docs/connect/choose-connection
   ```

2. **Append `.md` to the path:** Request the URL with `.md` at the end. For example:
   - HTML: [https://neon.com/docs/connect/choose-connection](https://neon.com/docs/connect/choose-connection)
   - Markdown: [https://neon.com/docs/connect/choose-connection.md](https://neon.com/docs/connect/choose-connection.md)

Whether you use the `Accept` header or the `.md` extension, you get the same Markdown output.

### Why not serve the source MDX?

Our docs are authored in MDX (Markdown plus components) and stored in the [neon-website](https://github.com/neondatabase/website/tree/main/content/docs) repository. If you read those source files directly, custom components and shared snippets can obscure the content or leave it incomplete (for example, a component might inject text that does not appear inline in the file).

The Markdown we serve is built from that MDX and gives you a single, flat page with all content in place. This is why we serve plain Markdown over the raw MDX.

## Finding content: the index

A full table of contents is available at:

- [https://neon.com/docs/llms.txt](https://neon.com/docs/llms.txt) (canonical)
- [https://neon.com/llms.txt](https://neon.com/llms.txt) (also serves the same file)

The index lists our doc pages with titles and links. Use it to discover URLs or to feed a list of pages into your tool.

## What you get on each page

Each Markdown page is plain Markdown (no interactive components or JSX). We add a bit of structure so that consumers know where they are and what to read next:

- **At the top:** A short block with the page location in the doc tree (e.g. `Connect > Choose a connection`) and a link to the full index (llms.txt). That gives context and a way to jump to the full catalog.

- **Body:** The main content, converted from our source format into standard Markdown (headings, links, code blocks, lists, etc.).

- **At the bottom:** A "Related docs" section with links to sibling pages in the same section, which is visible in the HTML version in the navigation bar. That helps with discovery and follow-up reading.

Each URL gives you the page content plus lightweight navigation and discovery.

## Headers and discovery metadata

We set a number of headers on our doc responses. These are the ones relevant to Markdown discovery and retrieval:

- `<link rel="alternate" type="text/markdown" href="...">`: Each HTML doc page includes this tag in the head, so agents can discover the Markdown URL without knowing about `.md` or `Accept` header conventions.
- `X-Robots-Tag: noindex`: Markdown responses include this header so search engines don't index them alongside the HTML versions.
- `X-LLMs-Txt` and `Link: rel="llms-txt"`: HTML doc responses include these headers pointing to `/docs/llms.txt` (an index of all docs as Markdown URLs), so agents can find the index from any page without parsing HTML. We adopted this convention from [Mintlify](https://mintlify.com).

## Summary for agents

| Goal                        | What to do                                                                                                     |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Get one page as Markdown    | Request the HTML docs URL with `Accept: text/markdown` or append `.md` to the URL                              |
| Get the full list of docs   | [https://neon.com/docs/llms.txt](https://neon.com/docs/llms.txt)                                               |
| Understand page context     | Read the short block at the top of each Markdown page (location + index link)                                  |
| Find related pages          | Use the "Related docs" section at the bottom of each page                                                      |
| Discover Markdown from HTML | Look for `<link rel="alternate" type="text/markdown" href="...">` in the page head, or the `X-LLMs-Txt` header |

--- [Document source](https://neon.com/docs/community/mermaid-diagrams.md) ---

> Summary: Authoring guide for Mermaid diagrams in Neon documentation. Shows how to embed flowcharts, sequence diagrams, ER diagrams, state diagrams, gitGraph, class diagrams, Gantt charts, and pie charts using a fenced mermaid code block. Diagrams auto-render with Neon brand colors in both light and dark modes, with no manual color configuration required. Also covers AI prompt templates for Cursor and Claude, syntax error fixes, and a Mermaid Live Editor validation workflow.

# Using Mermaid diagrams

Guide for creating visual diagrams in Neon documentation

Last updated: 2026-09-17

This guide shows Neon documentation writers and contributors how to create visual diagrams using Mermaid, a markdown-like syntax for generating diagrams and flowcharts. Mermaid diagrams are automatically styled with Neon's brand colors and support both light and dark modes.

## Why use Mermaid diagrams?

Visual diagrams help explain complex concepts, workflows, and architectures more effectively than text alone. Mermaid diagrams are ideal for Neon documentation because they:

- **Stay in sync**: Diagrams are created from text, making them easy to update alongside code
- **Work everywhere**: Rendered automatically in documentation, no external tools needed
- **Look professional**: Automatically styled with Neon's brand colors (#00E599 green)
- **Support themes**: Seamlessly switch between light and dark modes
- **AI-friendly**: Can be generated quickly using Cursor, Claude, or ChatGPT

## Quick start

Add a Mermaid diagram to any documentation page by using a code block with the `mermaid` language tag:

````markdown
```mermaid
flowchart TD
    A[Production Database] --> B[Create Branch]
    B --> C[Development Branch]
    C --> D[Make Changes]
    D --> E[Deploy]
```
````

This renders as:

```mermaid
flowchart TD
    A[Production Database] --> B[Create Branch]
    B --> C[Development Branch]
    C --> D[Make Changes]
    D --> E[Deploy]
```

**Note:** **Keep diagrams simple**: Mermaid diagrams are constrained to a maximum width of 800px for readability. Keep your diagrams focused with 5-10 nodes maximum. For complex workflows, consider breaking them into multiple simpler diagrams.

## Using AI to generate diagrams

At Neon, we use **Cursor** and **Claude** (or ChatGPT) extensively to generate Mermaid diagrams. Here's how to use AI to create diagrams:

### Using Cursor AI

Cursor has built-in AI that can generate Mermaid diagrams directly in your editor:

1. **Open your markdown file** in Cursor
2. **Start Cursor Composer** (Cmd+I or Ctrl+I)
3. **Write a prompt** describing the diagram you need

**Example prompts for Cursor:**

```
Create a Mermaid flowchart showing Neon's branching workflow:
- User creates a project
- Creates a development branch
- Makes schema changes
- Tests changes
- Merges to production
```

```
Generate a Mermaid sequence diagram for Neon's autoscaling process:
- Client connects
- Proxy checks compute status
- If idle, wake up compute
- Load data from storage
- Execute query
- Return results
```

```
Make a Mermaid ER diagram for a SaaS application using Neon with:
- tenants table
- users table
- subscriptions table
Show the relationships
```

**Tips for Cursor:**

- Be specific about the diagram type (flowchart, sequence, ER, etc.)
- Mention you want Mermaid syntax
- Include the main nodes/steps you want to show
- Ask for revisions if the first result isn't perfect

### Using Claude or ChatGPT

If you prefer using Claude or ChatGPT in their web interfaces:

1. **Open Claude or ChatGPT**
2. **Ask for a Mermaid diagram** with clear requirements
3. **Copy the generated code** and paste it into your markdown file

**Example prompts for Claude/ChatGPT:**

```
Create a Mermaid flowchart showing how Neon's scale-to-zero works:
1. Database is active
2. No activity detected for X minutes
3. Compute scales to zero
4. New connection arrives
5. Compute automatically resumes
6. Connection established

Use clear labels and make it easy to understand.
```

```
Generate a Mermaid class diagram showing Neon's API structure with:
- Project class (id, name, region, methods: createBranch, deleteBranch)
- Branch class (id, name, projectId, methods: createCompute, restore)
- Compute class (id, status, methods: start, suspend)
Show the relationships between them
```

```
Create a Mermaid Gantt chart for a database migration project:
- Planning phase (1 week)
- Schema migration (2 weeks)
- Data transfer (2 weeks)
- Testing (1 week)
- Production deployment (3 days)
```

**Pro tips:**

- Ask for specific Mermaid diagram types by name
- Provide the structure or flow you want to visualize
- Request revisions to adjust complexity or styling
- Validate the syntax using [Mermaid Live Editor](https://mermaid.live/)

### AI prompt templates

Here are reusable prompt templates for common diagram needs:

**Architecture diagram:**

```
Create a Mermaid flowchart showing [system/feature] architecture with:
- [Component 1]
- [Component 2]
- [Component 3]
Show how they interact and data flows between them.
```

**Workflow diagram:**

```
Generate a Mermaid flowchart for the [process name] workflow:
1. [Step 1]
2. [Step 2]
3. [Decision point]
4. [Step 3a or 3b based on decision]
5. [Final step]
```

**Database schema:**

```
Create a Mermaid ER diagram for [use case] with these tables:
- [table1] with fields [field1, field2, field3]
- [table2] with fields [field1, field2]
- [table3] with fields [field1, field2]
Show the relationships between them.
```

## Supported diagram types

Mermaid supports many diagram types. Here are the most useful for Neon documentation:

### Flowcharts

Best for: Workflows, decision trees, process flows

````markdown
```mermaid
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```
````

**Directions:**

- `TD` or `TB` - Top to bottom
- `LR` - Left to right
- `RL` - Right to left
- `BT` - Bottom to top

### Sequence Diagrams

Best for: API interactions, request/response flows, time-based processes

````markdown
```mermaid
sequenceDiagram
    participant Client
    participant Proxy
    participant Compute
    participant Storage

    Client->>Proxy: Connection Request
    Proxy->>Compute: Wake Up
    Compute->>Storage: Load Data
    Storage-->>Compute: Data Ready
    Compute-->>Proxy: Ready
    Proxy-->>Client: Connected
```
````

### Entity Relationship Diagrams

Best for: Database schemas, data models

````markdown
```mermaid
erDiagram
    PROJECTS ||--o{ BRANCHES : contains
    BRANCHES ||--o{ DATABASES : has
    BRANCHES ||--o{ COMPUTES : runs

    PROJECTS {
        uuid id PK
        string name
        string region
    }

    BRANCHES {
        uuid id PK
        string name
        uuid project_id FK
    }
```
````

**Relationships:**

- `||--||` - One to one
- `||--o{` - One to many
- `}o--o{` - Many to many

### State Diagrams

Best for: Lifecycle states, status changes

````markdown
```mermaid
stateDiagram-v2
    [*] --> Idle
    Idle --> Active: Connection
    Active --> Idle: Timeout
    Active --> Suspended: Manual Suspend
    Suspended --> Active: Resume
    Idle --> [*]: Delete
```
````

### Git Graphs

Best for: Branching strategies, version control workflows

````markdown
```mermaid
gitGraph
    commit id: "Initial"
    branch development
    checkout development
    commit id: "Feature A"
    checkout main
    merge development
    commit id: "Release"
```
````

### Class Diagrams

Best for: Code architecture, API structure

````markdown
```mermaid
classDiagram
    class Project {
        +String id
        +String name
        +createBranch()
        +delete()
    }

    class Branch {
        +String id
        +String name
        +restore()
    }

    Project "1" --> "*" Branch
```
````

### Gantt Charts

Best for: Project timelines, migration plans

````markdown
```mermaid
gantt
    title Migration Timeline
    dateFormat YYYY-MM-DD
    section Planning
        Requirements    :a1, 2024-01-01, 7d
        Design         :a2, after a1, 5d
    section Execution
        Migration      :b1, after a2, 14d
        Testing        :b2, after b1, 7d
```
````

### Pie Charts

Best for: Usage statistics, distributions

````markdown
```mermaid
pie title Workload Distribution
    "OLTP" : 45
    "Analytics" : 25
    "Dev/Test" : 20
    "AI/ML" : 10
```
````

## Styling and best practices

### Color scheme

Mermaid diagrams automatically use Neon's brand colors:

- **Primary**: Neon green (#00E599) for main elements
- **Secondary**: Blue (#2272b4) for connections
- **Git branches**: Full Neon color palette
- **Dark mode**: Automatically adapts with proper contrast

No manual color configuration needed!

### Writing effective diagrams

**Keep it simple:**

- Focus on one concept per diagram
- Limit to 5-10 nodes for readability
- Use clear, concise labels

**Use meaningful labels:**

```mermaid
flowchart TD
    A[User Creates Branch] --> B[Neon Provisions Compute]
    B --> C[Database Ready]
```

Better than:

```mermaid
flowchart TD
    A[Step 1] --> B[Step 2]
    B --> C[Step 3]
```

**Consider mobile users:**

- Avoid overly wide diagrams
- Test on smaller screens
- Use top-to-bottom layouts when possible

**Add context:**

- Include a brief description before the diagram
- Explain what the diagram shows
- Reference related documentation

## Testing your diagrams

### Test in Mermaid Live Editor

Before adding a diagram to documentation:

1. Go to [Mermaid Live Editor](https://mermaid.live/)
2. Paste your Mermaid code
3. Verify it renders correctly
4. Check for syntax errors

### Test locally

Run the docs site locally to see how your diagram looks:

```bash
npm run dev
```

Then navigate to your page and:

- Check light mode appearance
- Toggle to dark mode
- Test on mobile viewport
- Verify on different screen sizes

### Common syntax errors

**Missing quotes:**

```text
# Wrong - special characters in labels may cause issues
flowchart TD
    A[Label with special chars!] --> B
```

**Incorrect direction:**

```text
# Wrong - XY is not a valid direction
flowchart XY
    A --> B

# Correct - use TD, LR, RL, or BT
flowchart TD
    A --> B
```

**Broken relationships in ER diagrams:**

```text
# Wrong - incorrect relationship syntax
erDiagram
    A ||--|{ B : has

# Correct - use proper relationship notation
erDiagram
    A ||--o{ B : has
```

## Examples for common Neon use cases

### Branching workflow

```mermaid
flowchart TD
    A[Production Database] -->|Create Branch| B[Development Branch]
    B -->|Make Changes| C[Test Changes]
    C -->|Deploy| D[Merge to Production]
    D --> A
    C -->|Issues Found| B
```

### Autoscaling process

```mermaid
sequenceDiagram
    participant App as Application
    participant Proxy as Neon Proxy
    participant Compute as Compute
    participant Storage as Storage

    App->>Proxy: Connection Request
    Proxy->>Compute: Check Status

    alt Compute Idle
        Proxy->>Compute: Wake Up
        Compute->>Storage: Load Data
        Storage-->>Compute: Ready
    end

    Compute-->>Proxy: Active
    Proxy-->>App: Connected
```

### Multi-tenant architecture

```mermaid
erDiagram
    TENANTS ||--o{ USERS : has
    TENANTS ||--o{ DATABASES : owns
    USERS ||--o{ SESSIONS : creates
    DATABASES ||--o{ TABLES : contains

    TENANTS {
        uuid id PK
        string name
        timestamp created_at
    }

    USERS {
        uuid id PK
        uuid tenant_id FK
        string email
    }

    DATABASES {
        uuid id PK
        uuid tenant_id FK
        string name
    }
```

### Compute lifecycle

```mermaid
stateDiagram-v2
    [*] --> Provisioning
    Provisioning --> Active: Startup Complete
    Active --> Active: Processing Queries
    Active --> Idle: No Activity
    Idle --> Active: New Connection
    Active --> Suspended: Manual Suspend
    Suspended --> Active: Resume
    Idle --> [*]: Auto-Suspend
    Active --> [*]: Delete Branch
```

### Migration timeline

```mermaid
gantt
    title Database Migration to Neon
    dateFormat YYYY-MM-DD
    section Planning
        Assess Current Setup    :a1, 2024-01-01, 5d
        Design Architecture     :a2, after a1, 5d
    section Migration
        Schema Migration        :b1, after a2, 7d
        Data Transfer          :b2, after b1, 14d
    section Testing
        Functional Testing     :c1, after b2, 7d
        Performance Testing    :c2, after c1, 5d
    section Deployment
        Staging Deployment     :d1, after c2, 2d
        Production Cutover     :d2, after d1, 1d
```

## Troubleshooting

### Diagram not rendering

**Check the language tag:**

Wrong:

````markdown
```diagram
flowchart TD
    A --> B
```
````

Correct:

````markdown
```mermaid
flowchart TD
    A --> B
```
````

**Validate syntax:**

- Use [Mermaid Live Editor](https://mermaid.live/)
- Check for missing quotes, arrows, or semicolons
- Look for typos in diagram type names

### Theme not switching correctly

If diagrams don't update when switching themes:

- Hard refresh the page (Cmd+Shift+R / Ctrl+Shift+R)
- Clear browser cache
- Check browser console for JavaScript errors

### Performance issues

For pages with many diagrams:

- Consider splitting into multiple pages
- Simplify complex diagrams
- Use fewer nodes per diagram

## Additional resources

- **[Mermaid Official Documentation](https://mermaid.js.org/)** - Complete syntax reference
- **[Mermaid Live Editor](https://mermaid.live/)** - Test diagrams before adding to docs
- **[Component Guide](https://neon.com/docs/community/component-guide)** - Other custom components available
- **[Contribution Guide](https://neon.com/docs/community/contribution-guide)** - General documentation guidelines

## Getting help

Need help with Mermaid diagrams?

- **Discord**: Ask in [#docs channel](https://neon.com/discord)
- **GitHub**: Open an issue in the [website repository](https://github.com/neondatabase/website)
- **AI**: Use Cursor or Claude to help debug syntax errors

---

Ready to add visual diagrams to your documentation? Start with a simple flowchart and iterate from there. The AI tools make it easy to create professional diagrams quickly!

--- [Document source](https://neon.com/docs/compute/functions/agents.md) ---

> Summary: Neon Functions are a long-running home for AI agents. A single request can stream a response for minutes while the agent calls models and tools, with the Neon AI Gateway wired in automatically and Postgres next to your code.

# AI agents on Neon Functions

Run streaming, tool-calling agents on Neon Functions.

Last updated: 2026-10-09

AI agents make several model and tool calls to answer a single request, then stream the result back. That work can run for minutes, but lambda-style serverless caps execution at roughly 10 to 60 seconds, so a multi-step tool loop or an image-generation run gets cut off mid-stream.

Neon Functions use different limits: begin responding within 15 minutes, then keep an active stream open while data flows (send at least one byte every 15 minutes on a quiet stream). That's enough for an agent that makes many model and tool calls before it finishes responding. The function runs next to your Postgres database, and once you enable the [Neon AI Gateway](https://neon.com/docs/ai-gateway/overview) on the branch, its credentials are injected automatically, so one credential reaches the whole model catalog. See [Runtime limits](https://neon.com/docs/compute/functions/reference/runtime-limits) for details.

## Stream a tool-calling agent

Declare the AI Gateway and the function in `neon.ts`. `neon deploy` provisions the gateway and injects its credentials at runtime:

```ts filename="neon.ts"
import { defineConfig } from '@neon/config/v1';

export default defineConfig({
  aiGateway: true,
  functions: {
    agent: {
      name: 'AI agent',
      source: './functions/agent.ts',
    },
  },
});
```

Install the AI SDK, the Neon provider, and `pg`:

```bash
npm install ai@^7 @neon/ai-sdk-provider @neon/functions pg zod
```

Pin `ai` to v7, the major `@neon/ai-sdk-provider` supports.

The handler streams a tool-calling agent. The `@neon/ai-sdk-provider` reads the injected gateway credentials on its own, so `neon('<model>')` is the only model configuration you need. Tools run inside the function, right next to Postgres:

```ts filename="functions/agent.ts"
import { neon } from '@neon/ai-sdk-provider';
import { attachDatabasePool } from '@neon/functions';
import { streamText, tool, stepCountIs, type ModelMessage } from 'ai';
import { z } from 'zod';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
attachDatabasePool(pool);

export default {
  async fetch(request: Request) {
    if (request.method !== 'POST') {
      return new Response('POST { messages } here', { status: 405 });
    }
    const { messages } = (await request.json()) as { messages: ModelMessage[] };

    const result = streamText({
      model: neon('gpt-5-mini'), // any model in the AI Gateway catalog
      system: 'You are a concise assistant. Use tools when relevant.',
      messages,
      tools: {
        dbTime: tool({
          description: 'Get the current time from the database.',
          inputSchema: z.object({}),
          execute: async () => {
            const { rows } = await pool.query<{ now: string }>('SELECT now()::text AS now');
            return { now: rows[0].now };
          },
        }),
      },
      // Let the model call tools and then summarize, instead of stopping after
      // the first tool call. The loop runs in-process on Neon compute, not
      // behind a short proxy limit.
      stopWhen: stepCountIs(5),
      onError({ error }) {
        console.error('[streamText]', error);
      },
    });

    return result.toUIMessageStreamResponse({
      onError: (error) => (error instanceof Error ? error.message : String(error)),
    });
  },
};
```

`tool({ inputSchema, execute })` is the AI SDK v5+ shape. Create the `pg` pool once at module scope so it's reused across requests, and call `attachDatabasePool(pool)` so an idle disconnect can't crash the isolate (see [Connecting to Postgres](https://neon.com/docs/compute/functions/get-started#connect-to-postgres)). Pick any model from the [AI Gateway catalog](https://neon.com/docs/ai-gateway/models); swap `gpt-5-mini` for a different one without changing anything else.

Deploy and call it. `toUIMessageStreamResponse()` returns a stream the AI SDK's `useChat` hook consumes directly:

```bash
curl -N -X POST "$(neon functions get agent -o json | jq -r .invocation_url)" \
  -H 'content-type: application/json' \
  -d '{"messages":[{"role":"user","content":"What time is it in the database?"}]}'
```

## Call the function directly from the client

Call the function directly from the browser, not through your web app's backend. If you proxy the stream through a Vercel, Netlify, or Cloudflare host, it's bound by that host's serverless execution limit (often 10 to 60 seconds), so a long agent run gets cut off even though the function would keep going. A direct call keeps any host out of the stream's path, so the handler authenticates the request itself. See [Authentication](https://neon.com/docs/compute/functions/authentication#call-a-function-directly-from-the-client) for the JWT, CORS, and Vercel AI SDK transport pattern.

## Run on a schedule

An agent doesn't have to wait for a client call. A scheduled [Function Trigger](https://neon.com/docs/compute/functions/triggers/schedule) invokes the function on a cron schedule, so a summarization or cleanup agent runs on its own and fires even when the compute is scaled to zero.

## Persist what matters

Module memory is wiped when an isolate is evicted, and several isolates can run in parallel, so keep anything that must last in Postgres: conversation history, run metadata, results. For generated assets like images, declare a bucket in `neon.ts` (`buckets: { images: {} }`) and write them to [Object Storage](https://neon.com/docs/storage/objects), which branches with your database. When a bucket is declared, `neon deploy` injects `AWS_*` credentials automatically. For example, using the [Files SDK](https://files-sdk.dev):

```bash
npm install files-sdk @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
```

Install `@aws-sdk/lib-storage` even though the Files SDK lists it as optional. `neon deploy` bundles your function, and the bundle fails without it.

```typescript
import { Files } from 'files-sdk';
import { neon } from 'files-sdk/neon';

const files = new Files({ adapter: neon({ bucket: 'images' }) });
await files.upload('outputs/result.png', imageBuffer, { contentType: 'image/png' });
const url = await files.url('outputs/result.png', { expiresIn: 3600 });
```

## Examples

- [with-ai-sdk](https://github.com/neondatabase/examples/tree/main/with-ai-sdk): an image-generation agent using the AI SDK, AI Gateway, and Object Storage.
- [with-mastra](https://github.com/neondatabase/examples/tree/main/with-mastra): a personal-assistant agent using Mastra with Postgres-backed memory.

--- [Document source](https://neon.com/docs/compute/functions/authentication.md) ---

> Summary: A Neon Function has a public URL, so authenticate it yourself. Verify a Neon Auth JWT against the injected JWKS, check an API key, and add CORS when the browser calls the function directly.

# Neon Functions authentication

Verify callers before a Neon Function does any work.

Last updated: 2026-11-05

A Neon Function has a public HTTPS URL, so anyone who knows it can reach it. There's no platform gate in front of your handler. Authenticate the caller yourself, at the top of the handler, and reject anything that doesn't check out.

**Looking for credentials to call Neon services?:**

This page covers verifying inbound requests to your function. For the credentials Neon injects into a function to call Object Storage or AI Gateway, see [Environment variables](https://neon.com/docs/compute/functions/environment-variables), [Object Storage authentication](https://neon.com/docs/storage/authentication#credentials-in-neon-functions), or [AI Gateway authentication](https://neon.com/docs/ai-gateway/authentication#credentials-in-neon-functions).

How you authenticate depends on who calls the function:

- A browser or another service holding a **JWT**: verify the token (see [Verify a JWT](https://neon.com/docs/compute/functions/authentication#verify-a-jwt)).
- Your own scripts, cron jobs, or internal tools: check an **API key** (see [Check an API key](https://neon.com/docs/compute/functions/authentication#check-an-api-key)).
- A WebSocket or SSE client: the browser can't set headers, so pass the token as a query parameter or cookie (see [WebSocket and SSE clients](https://neon.com/docs/compute/functions/authentication#websocket-and-sse-clients)).

## Verify a JWT

When [Managed Better Auth](https://neon.com/docs/auth/overview) is enabled on the branch, the function gets `NEON_AUTH_JWKS_URL` and `NEON_AUTH_BASE_URL` injected at runtime. Verify incoming tokens against the JWKS with [`jose`](https://github.com/panva/jose), and check that the token's issuer matches your Managed Better Auth URL. Build the remote key set once at module scope, then verify on each request:

```bash
npm install jose
```

```ts filename="functions/secure.ts"
import { createRemoteJWKSet, jwtVerify } from 'jose';

const jwks = createRemoteJWKSet(new URL(process.env.NEON_AUTH_JWKS_URL!));
const issuer = new URL(process.env.NEON_AUTH_BASE_URL!).origin;

export default {
  async fetch(request: Request) {
    const auth = request.headers.get('authorization');
    if (!auth?.toLowerCase().startsWith('bearer ')) {
      return new Response('Unauthorized', { status: 401 });
    }
    try {
      const { payload } = await jwtVerify(auth.slice(7), jwks, { issuer });
      const userId = payload.sub; // scope the work to this user
      // ... do the work, return a response
      return Response.json({ ok: true, userId });
    } catch {
      return new Response('Unauthorized', { status: 401 });
    }
  },
};
```

Managed Better Auth issues these tokens for your signed-in users; they're EdDSA-signed and short-lived (15 minutes), so see the [JWT plugin](https://neon.com/docs/auth/guides/plugins/jwt) for retrieving and refreshing them. The function only verifies. If you sign your own tokens instead (with a signer like NextAuth or [Better Auth](https://better-auth.com)'s `jwt` plugin), verify against your app's JWKS and issuer rather than the Managed Better Auth ones.

## Call a function directly from the client

A long stream (an agent, an SSE feed) stays long only if nothing in front of it times out. Proxy it through your web app's backend on Vercel, Netlify, or Cloudflare, and that host's short serverless limit cuts the stream off. So call the function directly from the browser. That means there's no app backend in front of it, which is exactly why the handler has to authenticate the request itself.

Two things make the direct call work:

- **A short-lived token.** With Managed Better Auth, the signed-in client calls `authClient.getSession()`, and the SDK puts the session's JWT in `data.session.token`. With a custom signer, mint it on your app backend (a fast call, well within host limits). Either way, the client sends it as `Authorization: Bearer <token>`.
- **CORS.** The browser calls the function cross-origin, so handle the preflight and set the headers:

```ts filename="functions/cors.ts"
function cors(request: Request) {
  return {
    'Access-Control-Allow-Origin': request.headers.get('origin') ?? '*',
    'Access-Control-Allow-Headers': 'authorization, content-type',
    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
  };
}

export default {
  async fetch(request: Request) {
    if (request.method === 'OPTIONS') {
      return new Response(null, { status: 204, headers: cors(request) });
    }
    // ... verify the JWT as above, then do the work ...
    return Response.json({ ok: true }, { headers: cors(request) });
  },
};
```

This example echoes any request origin. In production, check `request.headers.get('origin')` against an allowlist of your app's domains and reject the rest, so the function only answers calls from sites you control.

With the [Vercel AI SDK](https://neon.com/docs/compute/functions/agents), point the transport at the function URL and attach the token in `fetch`:

```ts
import { DefaultChatTransport } from 'ai';

new DefaultChatTransport({
  api: NEON_FUNCTION_URL,
  fetch: (url, init) =>
    fetch(url, { ...init, headers: { ...init?.headers, authorization: `Bearer ${token}` } }),
});
```

## Check an API key

When the callers are your own scripts, cron jobs, or internal tools, you don't need full user auth. Check a shared secret instead. Set it on the deployment with `--env` (see [Environment variables](https://neon.com/docs/compute/functions/environment-variables)), then compare it on every request:

```ts
export default {
  async fetch(request: Request) {
    if (request.headers.get('authorization') !== `Bearer ${process.env.API_KEY}`) {
      return new Response('Unauthorized', { status: 401 });
    }
    // ... do the work
    return Response.json({ ok: true });
  },
};
```

```bash
neon functions deploy secure --src functions/secure.ts --env API_KEY=your-secret
```

The secret stays server-side, and rotating it is a redeploy with a new value. It's a solid default until you need real per-user identity, at which point use JWTs.

## WebSocket and SSE clients

Browsers can't set request headers on a WebSocket or an `EventSource`, so the `Authorization` header isn't available. Pass the token as a query parameter (or a cookie for SSE) and verify it before accepting the connection. See [WebSockets and SSE](https://neon.com/docs/compute/functions/websockets#authentication) for the pattern.

## OAuth and MCP clients

Managed Better Auth handles user sign-in and issues JWTs you verify as above. A different case is a third-party client like an MCP client (Cursor or Claude) self-authorizing against your server through the OAuth flow in the MCP spec. That's a larger setup: run your own OAuth provider (such as [Better Auth](https://better-auth.com)) alongside your app and have the function verify the access tokens it issues. See the [with-mcp example](https://github.com/neondatabase/examples/tree/main/with-mcp) for a working server.

## Example

[with-websockets-function](https://github.com/neondatabase/examples/tree/main/with-websockets-function) authenticates a WebSocket connection with a Managed Better Auth JWT end to end.

--- [Document source](https://neon.com/docs/compute/functions/custom-domains.md) ---

> Summary: Register a custom domain for a Neon Function, configure its DNS CNAME record, verify TLS and routing, troubleshoot domain status, and remove it safely.

# Custom domains for Neon Functions

Serve a Neon Function from a domain you own.

Last updated: 2026-11-02

Each Neon Function has a native invocation URL. You can also serve it from a
domain you own, such as `api.example.com`. Neon routes the custom domain to one
function on one branch and provisions its TLS certificate automatically. You
don't need to change your function code.

For example, one function is reachable at both URLs:

```text
Native:  https://br-cool-forest-a1b2c3d4-api.compute.c-2.us-east-2.aws.neon.tech
Custom:  https://api.example.com
```

Custom domains are branch-scoped: a domain registered on one branch isn't
inherited by its child branches, and each hostname can be registered only once.
Use a distinct hostname for each preview or development branch.

Neon Functions do not support hosting websites.

**Warning: Secure both function URLs**

Adding a custom domain doesn't authenticate the function or disable its native Neon URL. Both URLs remain publicly reachable, so protect the function with [application-level authentication](https://neon.com/docs/compute/functions/authentication).

## Before you start

You need:

- A deployed Neon Function.
- A domain you control, and access to its DNS settings.
- Optional: The latest [Neon CLI](https://neon.com/docs/cli), if you want to manage the domain from the command line.
- Optional: `@neon/sdk` 5.0.0 or later, if you want to manage the domain with the SDK.

## Register a custom domain

**Console**

1. In the Neon Console, open your project's **Settings**, then **Functions** > **Custom domains**.
2. Enter the domain you own.
3. Select **Function**, then select the function to serve from the domain.
4. Select **Add custom domain**.

The Console displays the CNAME target to add at your DNS provider.

**CLI**

```bash filename="Neon CLI"
neon functions domains register api.example.com --slug api --output json
```

The CLI resolves the project and branch from your Neon CLI context, so you don't pass them explicitly. See the [`neon functions domains register`](https://neon.com/docs/cli/functions#domains-register) reference for all options.

The command returns the registered domain and its `cname_target`:

```json filename="Output"
{
  "domain": "api.example.com",
  "entity_type": "function",
  "entity_id": "api",
  "cname_target": "fn-custom-domains.us-east-2.aws.neon.tech",
  "status": "pending",
  "dns_status": "pending",
  "binding_status": "pending",
  "status_reason": ""
}
```

**SDK**

```ts
import { createNeonClient } from '@neon/sdk';

const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
});
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;

const { data: domain, error } =
  await neon.functions.customDomains.register({
    projectId,
    branchId,
    domain: 'api.example.com',
    entity_type: 'function',
    entity_id: 'api',
  });

if (error) throw error;
console.log(domain.cname_target);
```

**API**

```bash
curl -X POST \
  "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/custom-domains" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "api.example.com",
    "entity_type": "function",
    "entity_id": "api"
  }'
```

See the [register custom domain API reference](https://neon.com/docs/reference/api/functions/register-project-branch-custom-domain) for request, response, and error schemas.

`entity_type` is `function`, the only supported value today. The function is
identified by its slug: the CLI `--slug` flag and the API `entity_id` field
carry the same value. Re-registering the same domain for the same function
returns the same result. Registering a
domain already assigned to another target returns a conflict without revealing
the existing owner.

## Declare with neon.ts

If you manage the branch with a [`neon.ts`](https://neon.com/docs/reference/neon-ts) policy, declare the domain on the function instead of registering it imperatively. Add `customDomains` to the function and run `neon deploy`:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    api: {
      name: "API",
      source: "./functions/api.ts",
      customDomains: ["api.example.com"],
    },
  },
});
```

```bash filename="Neon CLI"
neon deploy
```

`neon deploy` registers the domain and prints the CNAME target to configure below. The static `customDomains` list applies on the default branch only, since a hostname is globally unique and can't be inherited by child branches. Removing a domain from `neon.ts` doesn't delete its registration; delete it explicitly, as described in [Delete a custom domain](https://neon.com/docs/compute/functions/custom-domains#delete-a-custom-domain). For per-branch overrides and the full ruleset, see the [neon.ts reference](https://neon.com/docs/reference/neon-ts).

## Configure DNS

At your DNS provider, create a CNAME record using the target returned during
registration:

**Note: Use a subdomain**

Standard DNS doesn't allow a CNAME record at the zone apex. Use a subdomain such as `api.example.com` unless your DNS provider supports CNAME flattening.

- **Type:** `CNAME`
- **Name:** Your custom domain, such as `api.example.com`. Some providers expect
  only the host label, such as `api`.
- **Value:** Copy the exact `cname_target` hostname returned by Neon, such as `fn-custom-domains.us-east-2.aws.neon.tech`. Don't include `https://` or a URL path.
- **TTL:** Your provider's default.

Configure the record as DNS-only. If your provider proxies the record, Neon
can't validate the domain. On Cloudflare, set the record to "DNS only" (grey
cloud), not "Proxied" (orange cloud).

Remove conflicting `A`, `AAAA`, or CNAME records for the same hostname. DNS
changes can take time to propagate according to the record's TTL.

**Important: Allow Let's Encrypt in CAA records**

If your domain uses CAA records, authorize Let's Encrypt:

```text
CAA 0 issue "letsencrypt.org"
```

Neon can't provision a certificate when an applicable CAA record blocks Let's
Encrypt.

## List domains and check status

**Console**

In the Neon Console, open your project's **Settings**, then **Functions** > **Custom domains**. The table lists each domain, its target function, and its CNAME target.

**CLI**

Use JSON output to include the status fields:

```bash filename="Neon CLI"
neon functions domains list --output json
```

See the [`neon functions domains list`](https://neon.com/docs/cli/functions#domains-list) reference for all options.

```json filename="Output"
[
  {
    "domain": "api.example.com",
    "entity_type": "function",
    "entity_id": "api",
    "cname_target": "fn-custom-domains.us-east-2.aws.neon.tech",
    "status": "active",
    "dns_status": "ok",
    "binding_status": "present",
    "status_reason": ""
  }
]
```

**SDK**

```ts
import { createNeonClient } from '@neon/sdk';

const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
});
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;

const { data: domains, error } =
  await neon.functions.customDomains.list({ projectId, branchId }).all();

if (error) throw error;
console.log(domains);
```

**API**

```bash
curl \
  "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/custom-domains" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

See the [list custom domains API reference](https://neon.com/docs/reference/api/functions/list-project-branch-custom-domains) for response and pagination schemas.

When a response includes `pagination.next`, pass that value unchanged as the
next request's `cursor`. Don't construct or modify cursor values.

Each domain reports a top-level `status`, plus the `dns_status` and
`binding_status` that feed it.

`status` is:

- `pending`: Neon is still checking DNS or completing internal routing setup.
- `active`: DNS points to the Neon edge, CAA permits Let's Encrypt, and internal
  routing is in place.
- `error`: DNS, CAA, or internal routing needs attention. Check `status_reason`.

`dns_status` is `pending`, `ok`, `misconfigured` (resolves somewhere other than
the Neon edge), or `caa_blocked` (a CAA record forbids Let's Encrypt).
`binding_status` is `pending`, `present`, or `missing`, where `missing` is an
internal fault.

When `status` is `error`, `status_reason` names the cause and its fix:

| `status_reason`              | Meaning                                                   | Fix                                                                                    |
| ---------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `cname-not-pointing-at-edge` | The hostname resolves somewhere other than the Neon edge. | Check the CNAME and remove conflicting or proxied records.                             |
| `caa-blocks-lets-encrypt`    | An applicable CAA record doesn't authorize Let's Encrypt. | Add `CAA 0 issue "letsencrypt.org"`, including any CAA inherited from a parent domain. |
| `binding-missing`            | Neon's internal routing is unavailable.                   | Contact Neon Support if it persists.                                                   |

Status checks run asynchronously. Poll the domain every few seconds until it
becomes `active` or reports an actionable error.

**Important: Verify HTTPS separately**

`active` verifies DNS, CAA, and routing. It doesn't report certificate issuance
state. Make an HTTPS request before using the custom domain in production:

```bash
curl -i https://api.example.com/health
```

The first HTTPS request can trigger certificate issuance. If DNS is correct and
the API reports `active`, wait a minute and retry. Contact Neon Support if HTTPS
continues to fail.

## Runtime behavior

A request through a custom domain preserves its method, path, query, body,
normal application headers, and streaming behavior. WebSockets and SSE work
through the custom URL without additional configuration.

Inside the function, `Request.url` and the `Host` header use the function's
native Neon hostname, not the custom hostname. To read the hostname the client
requested, use the `x-forwarded-host` header; Neon overwrites any client-supplied
value, so it's safe to trust for tenant routing.

[`functionBaseUrl('<slug>')`](https://neon.com/docs/compute/functions/environment-variables#call-another-function)
from `@neon/env` returns the function's native URL, not the custom one. Store
the custom URL separately in your application configuration.

If a browser calls the custom domain directly, configure
[CORS and authentication](https://neon.com/docs/compute/functions/authentication) for that
origin.

## Delete a custom domain

Remove the DNS record before releasing the domain registration. This prevents a
dangling CNAME from continuing to point at Neon's custom-domain edge.

1. Remove the CNAME record at your DNS provider.
2. Wait for public DNS to stop returning the Neon target. Check with `dig +short api.example.com`.
3. Delete the registration using one of the following methods.

**Console**

Under **Settings** > **Functions** > **Custom domains** in the Neon Console, open the actions menu (⋮) for the domain, select **Delete**, then select **Remove domain** to confirm.

**CLI**

```bash filename="Neon CLI"
neon functions domains delete api.example.com
```

See the [`neon functions domains delete`](https://neon.com/docs/cli/functions#domains-delete) reference for all options.

**SDK**

```ts
import { createNeonClient } from '@neon/sdk';

const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
});
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;

const { error } = await neon.functions.customDomains.delete({
  projectId,
  branchId,
  domain: 'api.example.com',
});

if (error) throw error;
```

**API**

```bash
curl -X DELETE \
  "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/custom-domains/api.example.com" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

See the [delete custom domain API reference](https://neon.com/docs/reference/api/functions/delete-project-branch-custom-domain) for response and error schemas.

Routing changes take a short time to apply everywhere. Requests can continue
reaching the old function briefly after deletion, so verify that the custom URL
no longer serves it before reassigning the hostname.

Deleting a function doesn't remove its custom-domain registration. Remove the
domain explicitly when deleting a function.

Deleting a project doesn't release its custom domains either. If you want to
reuse a hostname, delete its custom-domain registration before you delete the
project. If you've already deleted the project, [contact Support](https://neon.com/docs/introduction/support)
to release the domain.

--- [Document source](https://neon.com/docs/compute/functions/deploy.md) ---

> Summary: Reference for deploying Neon Functions with neon deploy, neon functions deploy, or the Neon API, including flags, deployment states, and slug rules. Also covers deploying a function from a Neon Function Registry template, checking status, listing functions, and deleting them.

# Deploy and manage Neon Functions

CLI and API reference for deploying and managing Neon Functions.

Last updated: 2026-10-24

## Deploy with `neon.ts`

If your project has a [`neon.ts`](https://neon.com/docs/reference/neon-ts) config, this is the recommended way to deploy. `neon deploy` reads the config and applies the entire branch policy in one step: services, per-branch tuning, and every function it declares:

```bash
neon deploy
```

| Flag                | Default                   | Description                                                                                          |
| ------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------- |
| `--config`          | next to `.neon`, else cwd | Path to the `neon.ts` policy                                                                         |
| `--env`             | (none)                    | Path to a `.env` file loaded before `neon.ts` is evaluated, so function `env` values resolve from it |
| `--env-pull`        | `true`                    | Pull the branch's env vars into a local `.env` after a successful apply (`--no-env-pull` to skip)    |
| `--branch`          | linked branch             | Target branch ID or name                                                                             |
| `--project-id`      | linked project            | Project ID                                                                                           |
| `--update-existing` | `false`                   | Override branch settings that differ from `neon.ts` without asking                                   |
| `--allow-protected` | `false`                   | Apply to a branch marked protected on Neon without asking                                            |
| `--yes`, `-y`       | `false`                   | Answer yes to both confirmations: `--update-existing` and `--allow-protected`                        |

In a terminal, `neon deploy` asks before it overrides branch settings or applies to a protected branch. In CI, or anywhere without a terminal, it stops and names the flag to pass instead. `neon deploy` is an alias for `neon config apply`. To preview what a deploy would change without applying it, run `neon config plan`.

You can declare scheduled [Function Triggers](https://neon.com/docs/compute/functions/triggers/schedule) and [custom domains](https://neon.com/docs/compute/functions/custom-domains) in the same `neon.ts` config, so they deploy alongside the function.

Note that `--env` here takes a path to a `.env` file. The `--env` flag on `neon functions deploy` below takes `KEY=VALUE` pairs instead.

## Deploy with `neon functions deploy`

To deploy one function directly, without a `neon.ts` config:

```bash
neon functions deploy <slug> [--src <dir-or-entry-file>] [--env KEY=VALUE] [--wait]
```

By default, the CLI bundles your source with esbuild, zips the output, and uploads it. Pass `--no-bundle` to skip esbuild and ship a prebuilt source as-is. The first deploy creates the function; subsequent deploys update it. See the [neon functions reference](https://neon.com/docs/cli/functions) for the full command surface.

**Note: esbuild not found**

The `neon` CLI ships `esbuild` for most platforms. If bundling fails with an `esbuild not found` error, install it (`npm install -g esbuild`) or set `NEON_ESBUILD_PATH` to an esbuild binary. `NEON_ESBUILD_PATH` is read by the CLI's own bundler, not by `buildFunctionBundle` in [`@neon/config-runtime`](https://neon.com/docs/reference/config-runtime#function-bundling); when calling that package directly, pass a custom `bundleFunction` instead.

| Flag              | Default       | Description                                                                                                                                                                                              |
| ----------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--src`           | (none)        | Function source: a directory containing `index.ts`, `index.js`, or `index.mjs` (the first match is the entry), or a path to the entry file                                                               |
| `--env KEY=VALUE` | (none)        | Set an environment variable. Repeatable. Stored with the deployment. Takes `KEY=VALUE` pairs, not a `.env` file path like `neon deploy --env`                                                            |
| `--runtime`       | `nodejs24`    | Function runtime. `nodejs24` is the only valid value                                                                                                                                                     |
| `--branch`        | linked branch | Target branch. Defaults to the branch in `.neon`                                                                                                                                                         |
| `--wait`          | `true`        | Poll until `completed` or `failed`, up to 10 minutes                                                                                                                                                     |
| `--no-bundle`     | off (bundles) | Skip esbuild and zip a prebuilt source as-is. The directory root, or the file you point at, must be `index.mjs` or `index.js` (TypeScript can't ship unbundled). Use it when you run your own build step |

**Examples:**

```bash
neon functions deploy hello --src functions/hello.ts
```

```bash
neon functions deploy hello --src . --env RESEND_API_KEY=re_...
```

```bash
neon functions deploy hello --src functions/hello.ts --branch feat/my-feature
```

The CLI doesn't support a config-only deploy. Every `neon functions deploy` call bundles and uploads source, whether you pass `--src` or let it default to the current directory, so there's no way to change just an environment variable without also pointing at valid source, as in the example above.

For a deploy that skips bundling and updates only the environment or runtime, use [the API](https://neon.com/docs/compute/functions/deploy#deploy-with-the-api), which accepts config-only updates.

## Deploy with the API

Bundle with esbuild, zip the output, then POST to the deploy endpoint.

**1. Bundle:**

```bash
esbuild functions/hello.ts --bundle --platform=node --target=node24 --format=esm \
  --banner:js="import{createRequire as ___cr}from'module';import{fileURLToPath as ___f}from'url';import{dirname as ___d}from'path';const require=___cr(import.meta.url);const __filename=___f(import.meta.url);const __dirname=___d(__filename);" \
  --outfile=dist/index.mjs
```

**Note:** `--format=esm` is required: esbuild doesn't infer ESM output from the `.mjs` extension alone, and without it the runtime fails with `module is not defined in ES module scope`. The `--banner` line restores `require`, `__filename`, and `__dirname` for bundled CommonJS dependencies that reference them internally (as `pg` does); without it, the runtime fails with `Dynamic require of "<module>" is not supported`. `buildFunctionBundle` below applies the same banner automatically.

**2. Zip:**

```bash
zip -j function.zip dist/index.mjs
```

The archive's entry file must be named `index.mjs` or `index.js`; the runtime looks for those names.

From Node.js, `buildFunctionBundle` from [`@neon/config-runtime`](https://neon.com/docs/reference/config-runtime#function-bundling) does both steps in one call and produces exactly the archive the deploy endpoint expects. See the [`@neon/config-runtime` reference](https://neon.com/docs/reference/config-runtime) for the rest of that package's programmatic API (`inspect`, `plan`, `apply`), useful for calling a deploy from a custom CI step instead of the CLI:

```ts
import { buildFunctionBundle } from "@neon/config-runtime/v1";

const zip = await buildFunctionBundle({
  slug: "hello",
  name: "My first function",
  source: "./functions/hello.ts",
  env: {},
  runtime: "nodejs24",
});
```

**3. Deploy:**

```bash
curl -X POST \
  "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/functions/{slug}/deployments" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -F "zip=@function.zip" \
  -F 'environment={"MY_SECRET":"value"}'
```

| Field         | Type   | Required          | Description                                                                                           |
| ------------- | ------ | ----------------- | ----------------------------------------------------------------------------------------------------- |
| `zip`         | binary | When code changes | ZIP of the bundled function. Omit only to update `environment` or `runtime` on an existing deployment |
| `runtime`     | string | No                | `nodejs24` is the only valid value                                                                    |
| `environment` | string | No                | JSON-encoded string-to-string map                                                                     |

The deploy endpoint accepts `multipart/form-data`. Use a `zip` part for code deploys and a single `environment` part containing the JSON-encoded map; don't send bracketed fields such as `environment[KEY]=value`. The first deployment for a function must include `zip`; later deployments can omit it for config-only changes.

The API returns immediately for code deploys. Poll the get endpoint (see [Check status](https://neon.com/docs/compute/functions/deploy#check-status)) until the deployment completes. Config-only deployments can complete synchronously because they reuse the latest bundle. Builds have an absolute 2-minute budget from the time the deploy is accepted; if the build can't complete within that window, the deployment fails.

### Deploy with `@neon/sdk`

The [`@neon/sdk`](https://www.npmjs.com/package/@neon/sdk) client includes a `neon.functions` namespace for branch-scoped function management:

```ts
import { createNeonClient } from '@neon/sdk';
import { readFile } from 'node:fs/promises';

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY! });
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;
const zipBytes = await readFile('function.zip');

const { data: deployment } = await neon.functions.deploy({
  projectId,
  branchId,
  slug: 'hello',
  zip: new File([zipBytes], 'function.zip', { type: 'application/zip' }),
  runtime: 'nodejs24',
  environment: JSON.stringify({ MY_SECRET: 'value' }),
});
```

`neon.functions.deploy` uses the same multipart API fields as the raw endpoint. `list`, `get`, `update`, and `delete` are also available under `neon.functions`.

## Deploy a function from a template

A function template adds a ready-made function to your project. Browse the catalog at [neon.com/functions/templates](https://neon.com/functions/templates), then add one with [`neon functions new`](https://neon.com/docs/cli/functions#new):

```bash
neon functions new basic   # writes functions/basic/ and declares it in neon.ts
```

From there, it deploys like any other function. Some templates also need services such as AI Gateway or Object Storage enabled first. For the full workflow, see [Use function templates](https://neon.com/docs/compute/functions/templates).

## Slugs

The slug is assigned at first deploy: either the key in `neon.ts` or the positional argument to `neon functions deploy`. It becomes part of the invocation URL and can't be changed afterward. Slugs must match `^[a-z0-9]{1,20}$`: lowercase letters and digits only, 1 to 20 characters, no hyphens.

## Deployment states

| State       | Meaning                                 |
| ----------- | --------------------------------------- |
| `pending`   | Queued, not yet building                |
| `building`  | Source is being compiled and bundled    |
| `completed` | Function is live and accepting requests |
| `failed`    | Build or deployment error               |

## Manage functions

### Check status

**CLI**

```bash
neon functions get hello
```

**API**

```text
GET /projects/{project_id}/branches/{branch_id}/functions/{slug}
```

The output includes the function's public URL (`URL` in the CLI table, `invocation_url` in JSON and the API):

```
https://<branch_id>-<slug>.compute.<cell>.us-east-2.aws.neon.tech/
```

### List functions

**CLI**

```bash
neon functions list
```

**API**

```text
GET /projects/{project_id}/branches/{branch_id}/functions
```

### Delete a function

**CLI**

```bash
neon functions delete hello
```

**API**

```text
DELETE /projects/{project_id}/branches/{branch_id}/functions/{slug}
```

--- [Document source](https://neon.com/docs/compute/functions/discord-bot.md) ---

> Summary: Host a Discord interactions bot on Neon Functions. Receive slash commands over HTTP at a public function URL, verify Discord's Ed25519 request signatures, and store data in Postgres on the same branch.

# How to host a Discord bot on Neon Functions

Receive slash commands at a public function URL with no Gateway connection

Last updated: 2026-10-31

Discord can deliver slash commands over HTTP. There's no Gateway connection and no discord.js client. Discord POSTs each interaction to the Interactions Endpoint URL on your app. This guide uses a [Neon Function](https://neon.com/docs/compute/functions/overview) as that URL.

The template verifies Discord's request signatures and answers the `PING`/`PONG` handshake. Discord's [Interactions Overview](https://discord.com/developers/docs/interactions/overview) is optional background if you want the crypto details.

**Note: Not for Gateway bots**

Neon Functions are not the right primitive for a Discord Gateway bot yet. Gateway bots need a long-lived, stateful process with session resume, presence and sharding. This guide is HTTP only: Discord POSTs slash commands to your function URL.

## Prerequisites

- A Neon project in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). See [Get started with Neon Functions](https://neon.com/docs/compute/functions/get-started).
- The latest [Neon CLI](https://neon.com/docs/cli), installed and authenticated. Upgrade with `npm install -g neon@latest`, then see [CLI login](https://neon.com/docs/cli/login).
- Node.js 24 (`node -v`). Deployed functions run on `nodejs24`, so 24 locally is the closest match. Node.js 20+ works.
- A Discord account.
- A Discord server you own. Create one if you need to. You often can't add a bot to someone else's server.

This guide uses npm commands, matching the template.

## Create a Discord application

Open the [Discord Developer Portal](https://discord.com/developers/applications) and click **New Application**. Give it a name (for example `Neon HTTP bot`), accept the Developer Terms, then click **Create**.

![Discord Developer Portal New Application modal](https://neon.com/docs/compute/functions/discord-new-application.png)

On **General Information**, copy the **Application ID** and **Public Key**. Stash them somewhere local. They go into `.env.local` after you scaffold the project.

![Discord General Information showing Application ID and Public Key](https://neon.com/docs/compute/functions/discord-general-information.png)

Open the **Bot** tab and click **Reset Token**. Copy the token. Discord shows it once. Resetting invalidates any previous token, so if this app already had one, update `.env.local` after you create it.

![Discord Bot tab showing the Reset Token button](https://neon.com/docs/compute/functions/discord-bot-token.png)

**Warning:** Treat the bot token like a password. Anyone who has it can act as your bot. Never commit it or paste it into screenshots, tickets or chat.

The public key is what the function uses to verify that a POST really came from Discord. The application ID and bot token are what `npm run register:commands` uses to declare slash commands. `/help` uses the token at request time for command mentions.

### Invite the bot to a test server

Create a Discord server you own if you don't already have one.

This walkthrough uses **OAuth2** → **URL Generator**, not the **Installation** tab.

Under **Scopes**, check `bot` and `applications.commands`.

![Discord OAuth2 URL Generator with bot and applications.commands scopes](https://neon.com/docs/compute/functions/discord-oauth-scopes.png)

Under **Bot Permissions**, check **Send Messages** and **Use Slash Commands**.

![Discord OAuth2 URL Generator with Send Messages and Use Slash Commands](https://neon.com/docs/compute/functions/discord-oauth-url-generator.png)

The screenshots are cropped to the checkboxes. Copy the generated URL at the bottom of **URL Generator**, below **Bot Permissions**. Open it, pick your test server, click **Continue**, then **Authorize**.

Slash commands show up after you [register them](https://neon.com/docs/compute/functions/discord-bot#register-slash-commands).

## Scaffold the project

`neon bootstrap` copies the HTTP example into an empty directory and prompts you to install dependencies and set up the project. Accept the prompts. Pass `--no-link` to skip linking for now; you'll [link](https://neon.com/docs/cli/link) in the next step, after creating `.env.local`, so Neon writes its variables straight into that file. The template id is `discord-bot-http`:

```bash
neon bootstrap my-discord-bot --template discord-bot-http --no-link
cd my-discord-bot
```

See [`neon bootstrap`](https://neon.com/docs/cli/bootstrap) for flags. Later commands in this guide assume you're in that directory.

To start from the source instead, copy [bots/discord-bot-http](https://github.com/neondatabase/examples/tree/main/bots/discord-bot-http) from the [examples](https://github.com/neondatabase/examples) repo, `cd` into it, then install dependencies and `neon link`.

`neon.ts` declares the `discord` function, the Discord env vars and a local `dev` port:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    discord: {
      name: "Discord interactions",
      source: "./functions/discord.ts",
      env: {
        DISCORD_PUBLIC_KEY: process.env.DISCORD_PUBLIC_KEY!,
        DISCORD_APPLICATION_ID: process.env.DISCORD_APPLICATION_ID!,
        DISCORD_BOT_TOKEN: process.env.DISCORD_BOT_TOKEN!,
        ...(process.env.DISCORD_GUILD_ID ? { DISCORD_GUILD_ID: process.env.DISCORD_GUILD_ID } : {}),
      },
      dev: {
        port: 8787,
      },
    },
  },
});
```

The key `discord` is the function slug. It's permanent after the first deploy and appears in CLI commands and the invocation URL. See the [neon.ts reference](https://neon.com/docs/reference/neon-ts).

This walkthrough is deploy-only. Discord needs a public HTTPS URL, so we don't use `npm run dev` here. The scaffold still sets `dev.port` to `8787` to match the template.

## Add Discord secrets

Template scripts read `.env.local` (for example `neon deploy --env .env.local` and `node --env-file=.env.local`), the same convention as Next.js and `vercel env pull`. Bootstrap scaffolds a `.env.example` but no `.env.local` yet. Install dependencies, copy the example, then link. `neon link` loads `neon.ts` to pull the branch's variables, so the packages must be installed first:

```bash
npm install
cp .env.example .env.local
neon link
```

Linking merges `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `NEON_BRANCH`, `NEON_BRANCH_ID`, and `NEON_FUNCTION_HOST_SUFFIX` into `.env.local`, leaving the Discord keys untouched. Uncomment and fill the three required `DISCORD_*` keys:

```env filename=".env.local"
# Required. Add real values before deploying; a missing key throws at deploy, an empty one uploads "".
# DISCORD_PUBLIC_KEY=
# DISCORD_APPLICATION_ID=
# DISCORD_BOT_TOKEN=

# Optional: your test server's ID for fast guild commands; blank registers global commands.
DISCORD_GUILD_ID=

# Written into `.env.local` by `neon link`.
NEON_BRANCH=
DATABASE_URL=
DATABASE_URL_UNPOOLED=
NEON_BRANCH_ID=
NEON_FUNCTION_HOST_SUFFIX=
```

For this guide, also set `DISCORD_GUILD_ID` to your test server. In Discord, turn on Developer Mode (User Settings → App Settings → Advanced), right-click the server name in the sidebar and click **Copy Server ID**. A guild is a Discord server.

Leave the pulled `NEON_*` and `DATABASE_URL*` values as written. See [Environment variables](https://neon.com/docs/compute/functions/environment-variables).

If you omit `DISCORD_GUILD_ID`, the register script creates global commands, which can take up to an hour to show up. Skip that until you want a production-wide install.

## Deploy the function

`npm run deploy` runs `neon deploy --env .env.local`, which evaluates `neon.ts` with your Discord secrets in `process.env`:

```bash
npm run deploy
```

The CLI applies the `neon.ts` policy, bundles the function and waits until that apply finishes. You'll see `Applied changes` and a **Function URLs** list. If the command fails, check [function logs](https://neon.com/docs/compute/functions/logs). Flags are in [Deploy and manage functions](https://neon.com/docs/compute/functions/deploy).

Deployed env is a snapshot of `.env.local` at apply time. Run `npm run deploy` again after any change to `.env.local`.

## Apply the database schema

```bash
npm run db:push
```

`neon link` wrote `DATABASE_URL` into `.env.local`, so you can apply the schema any time after linking. `/ping` works without the tables; `/name` and `/profile` need them.

## Set the Interactions Endpoint URL

Your interactions endpoint is the `discord` function's URL with the path `/api/interactions`. `npm run deploy` prints it in the **Function URLs** list, and `neon functions get discord` shows it in its `URL` field:

```text
https://br-cool-darkness-123456-discord.compute.c-2.us-east-2.aws.neon.tech/api/interactions
```

Your URL will differ. Use your own `discord` URL; the host is specific to your branch.

In the Developer Portal, open **General Information**. Paste that URL into **Interactions Endpoint URL** and save.

Discord immediately POSTs a `PING` (`type: 1`). The handler verifies the signature and returns a `PONG`. If that handshake succeeds, Discord saves the URL (the Developer Portal shows a green success message).

If save fails, retry once. Confirm the public key in `.env.local` matches General Information, you redeployed after editing `.env.local` and the path ends with `/api/interactions`. Then open or curl the function URL (from `neon functions get discord`, or that URL plus `/api/interactions`). GET returns JSON with these keys:

```json
{
  "ok": true,
  "service": "discord-interactions",
  "interactionsPath": "/api/interactions",
  "interactionsUrl": "https://br-cool-darkness-123456-discord.compute.c-2.us-east-2.aws.neon.tech/api/interactions"
}
```

`ok: true` proves the isolate is up, and `interactionsUrl` echoes the public endpoint you paste into Discord, so it should match the URL you saved. GET does not use the public key, so a wrong key or a stale deploy still fails Discord's `PING`. Check [function logs](https://neon.com/docs/compute/functions/logs); signature failures show up there. Fix `.env.local` and redeploy. The first PING can miss a cold start.

## Register slash commands

Discord doesn't read commands from your handler. Register them once with the Discord API:

```bash
npm run register:commands
```

That compiles `scripts/registerCommands.ts` and calls Discord's HTTP API with your bot token. It runs locally. It isn't part of the Neon Function. On success it prints the registered command list as JSON.

The hosted function still needs `DISCORD_BOT_TOKEN`, `DISCORD_APPLICATION_ID` and `DISCORD_PUBLIC_KEY` in the deployed env. `/help` uses the token at request time for command mentions. The public key is for request verification.

If it throws, check that `.env.local` exists and the token is set (Discord returns `401 Unauthorized` for a bad token). If the bot isn't in the target server, Discord returns `403 Missing Access`; invite it first (see [Invite the bot to a test server](https://neon.com/docs/compute/functions/discord-bot#invite-the-bot-to-a-test-server)). A wrong `DISCORD_GUILD_ID` returns `404 Unknown Guild`.

With `DISCORD_GUILD_ID` set, the script registers guild commands on that server.

The template registers `/ping`, `/info`, `/help`, `/buttons`, `/name` and `/profile`. Each command has an optional `ephemeral` boolean in Discord's `/` picker when you invoke it. Set it so only you see the reply. It isn't an env var or a code edit.

Restart the Discord client after registering so the `/` picker picks up the new commands.

## Try /ping

In your test server, type `/` and pick **ping** from Discord's command picker, then send it. The bot should reply with a Pong embed and an estimated interaction latency.

HTTP-only bots stay **offline** in the member list. That's expected. They still handle slash commands.

You must send Discord an initial response within about 3 seconds, or Discord invalidates the interaction token. This template answers in the request.

If nothing appears, or Discord says "The application did not respond":

- The bot is in the server with the `applications.commands` scope.
- Discord saved the Interactions Endpoint URL after a successful PING/PONG.
- `npm run deploy` finished (redeploy after any `.env.local` change).
- `npm run register:commands` printed JSON (then you restarted Discord).
- `DISCORD_GUILD_ID` is this server.
- Check [function logs](https://neon.com/docs/compute/functions/logs) for a failed PING or a slow cold start. Try `/ping` again once the branch is warm.

## How it works

`functions/discord.ts` default-exports `async function handler(request: Request)` and returns a `Response`. GET returns `{ ok, service, interactionsPath, interactionsUrl }`. POST reads the raw body, verifies the Discord signature, then dispatches on interaction type.

**Important: Verify the raw body**

Call `request.text()` and verify **before** `JSON.parse`. Discord signs `timestamp + body` as the exact bytes it sent. Parsing JSON first can change whitespace and fail verification. See [Interactions Overview](https://discord.com/developers/docs/interactions/overview).

The POST path reads the raw body and verifies the signature before parsing:

```ts filename="functions/discord.ts"
  const body = await request.text();
  const env = getDiscordEnv();
  const isVerified = verifyDiscordRequest({
    body,
    publicKey: env.DISCORD_PUBLIC_KEY,
    signature: request.headers.get("x-signature-ed25519"),
    timestamp: request.headers.get("x-signature-timestamp"),
  });

  if (!isVerified) {
    return jsonResponse({ error: "invalid request signature" }, { status: 401 });
  }

  let payloadBody: unknown;

  try {
    payloadBody = JSON.parse(body);
  } catch {
    return jsonResponse({ error: "invalid json" }, { status: 400 });
  }
```

<details>

<summary>View full code: </summary>

```typescript
import { InteractionResponseType, InteractionType } from "discord-api-types/v10";
import { DISCORD_EPHEMERAL_OPTION_NAME, DISCORD_INTERACTIONS_PATH } from "../src/constants/discord.js";
import { getDiscordEnv } from "../src/env.js";
import { discordInteractionSchema } from "../src/schemas/discord.js";
import { commandHandlers, trackApplicationCommandRun } from "../src/utils/discordCommands.js";
import { getBooleanCommandOption } from "../src/utils/discordOptions.js";
import { createErrorResponseData } from "../src/utils/discordResponses.js";
import { createButtonTestClickResponseData, parseButtonTestCustomId } from "../src/utils/generalComponents.js";
import { jsonResponse } from "../src/utils/jsonResponse.js";
import { verifyDiscordRequest } from "../src/utils/verifyDiscordRequest.js";

export default async function handler(request: Request): Promise<Response> {
  const url = new URL(request.url);

  switch (request.method) {
    case "GET":
      return jsonResponse({
        ok: true,
        service: "discord-interactions",
        interactionsPath: DISCORD_INTERACTIONS_PATH,
        interactionsUrl: `${url.origin}${DISCORD_INTERACTIONS_PATH}`,
      });
    case "POST":
      break;
    default:
      return jsonResponse({ error: "method not allowed" }, { status: 405 });
  }

  const body = await request.text();
  const env = getDiscordEnv();
  const isVerified = verifyDiscordRequest({
    body,
    publicKey: env.DISCORD_PUBLIC_KEY,
    signature: request.headers.get("x-signature-ed25519"),
    timestamp: request.headers.get("x-signature-timestamp"),
  });

  if (!isVerified) {
    return jsonResponse({ error: "invalid request signature" }, { status: 401 });
  }

  let payloadBody: unknown;

  try {
    payloadBody = JSON.parse(body);
  } catch {
    return jsonResponse({ error: "invalid json" }, { status: 400 });
  }

  const parsedPayload = discordInteractionSchema.safeParse(payloadBody);

  if (!parsedPayload.success) {
    return jsonResponse({ error: "invalid interaction payload" }, { status: 400 });
  }

  const payload = parsedPayload.data;
  const options = payload.data?.options ?? [];
  const ephemeral = getBooleanCommandOption(options, DISCORD_EPHEMERAL_OPTION_NAME);

  switch (payload.type) {
    case InteractionType.Ping:
      return jsonResponse({ type: InteractionResponseType.Pong });
    case InteractionType.ApplicationCommand: {
      if (!payload.data?.name) {
        break;
      }

      const commandHandler = commandHandlers[payload.data.name];

      if (commandHandler) {
        void trackApplicationCommandRun(payload);

        return jsonResponse({
          type: InteractionResponseType.ChannelMessageWithSource,
          data: await commandHandler({ payload, request, url, ephemeral, options }),
        });
      }

      break;
    }
    case InteractionType.MessageComponent: {
      if (!payload.data?.custom_id) {
        break;
      }

      const buttonTestAction = parseButtonTestCustomId(payload.data.custom_id);

      if (buttonTestAction) {
        return jsonResponse({
          type: InteractionResponseType.UpdateMessage,
          data: createButtonTestClickResponseData(buttonTestAction),
        });
      }

      return jsonResponse({
        type: InteractionResponseType.ChannelMessageWithSource,
        data: createErrorResponseData("That button is not handled by this bot."),
      });
    }
  }

  return jsonResponse({
    type: InteractionResponseType.ChannelMessageWithSource,
    data: createErrorResponseData("Unknown command. Try `/help`."),
  });
}

```

</details>

View it on [GitHub](https://github.com/neondatabase/examples/blob/main/bots/discord-bot-http/functions/discord.ts).

## Commands

- `/ping`: Pong embed with estimated interaction latency.
- `/info` and `/help`: [Components v2](https://discord.com/developers/docs/components/overview) panels (Discord's newer message layout) with runtime details and slash-command mentions.
- `/buttons`: Components v2 buttons (primary, secondary, success and danger).
- `/name` and `/profile`: Postgres via Drizzle (`profiles` and `command_usage` tables). If the database misses a 2.5-second deadline, the bot replies "Warming up"; run the command again once the branch is warm.

## Related templates

- [Community guide: Discord bot on Neon Functions](https://neon.com/guides/discord-bot-on-neon-functions): adds LLM chat and image generation, built from scratch.
- [Telegram HTTP bot](https://github.com/neondatabase/examples/tree/main/bots/telegram-bot-http)
- [WhatsApp HTTP bot](https://github.com/neondatabase/examples/tree/main/bots/whatsapp-bot-http)

## Example

Create a copy of the example with the Neon CLI:

```bash
neon bootstrap my-discord-bot --template discord-bot-http
cd my-discord-bot
```

You can find the example in [`bots/discord-bot-http`](https://github.com/neondatabase/examples/tree/main/bots/discord-bot-http).

--- [Document source](https://neon.com/docs/compute/functions/environment-variables.md) ---

> Summary: Neon injects branch-scoped variables like DATABASE_URL into deployed functions automatically. Set your own variables with --env at deploy time or in neon.ts, and pull branch variables locally with neon env pull.

# Neon Functions environment variables

Neon-injected variables and how to set your own secrets.

Last updated: 2026-10-23

## Neon-injected variables

Neon injects connection strings, credentials, and service URLs automatically at runtime. You don't declare these in `neon.ts` or pass them at deploy time. They're resolved from the branch the function is deployed to. This is why a function doesn't configure Postgres, the AI Gateway, or Object Storage itself: enable the service, and its credentials are there in `process.env`.

Each variable is present only when its service is enabled on the branch. `DATABASE_URL` and `DATABASE_URL_UNPOOLED`, for example, are undefined on a functions-only branch with no Postgres database.

| Variable                                     | Service             | Description                                                                                                                         |
| -------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL`                               | Postgres            | Pooled connection string. Use this for most queries.                                                                                |
| `DATABASE_URL_UNPOOLED`                      | Postgres            | Direct connection string. Use for migrations, `LISTEN`/`NOTIFY`, and multi-round-trip transactions.                                 |
| `NEON_BRANCH`                                | Core                | Branch name (e.g. `main`, `preview/foo`). Present on all branches.                                                                  |
| `NEON_BRANCH_ID`                             | Core                | Branch ID (e.g. `br-cool-darkness-123456`). Present on all branches.                                                                |
| `NEON_FUNCTION_HOST_SUFFIX`                  | Functions           | Hostname suffix shared by the branch's functions, e.g. `.compute.c-2.us-east-2.aws.neon.tech`.                                      |
| `NEON_AUTH_BASE_URL`                         | Managed Better Auth | Base URL for Managed Better Auth.                                                                                                   |
| `NEON_AUTH_JWKS_URL`                         | Managed Better Auth | JWKS endpoint for verifying Managed Better Auth JWTs. See [Authentication](https://neon.com/docs/compute/functions/authentication). |
| `NEON_DATA_API_URL`                          | Data API            | Base URL for the Neon Data API (PostgREST). Present when the Data API is provisioned on the branch.                                 |
| `NEON_AI_GATEWAY_TOKEN`                      | AI Gateway          | Gateway bearer token.                                                                                                               |
| `NEON_AI_GATEWAY_BASE_URL`                   | AI Gateway          | Gateway host root. Append a dialect route, e.g. `/v1` for Chat Completions or `/openai/v1` for the OpenAI Responses API.            |
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | Object Storage      | S3-compatible credentials for the branch's buckets.                                                                                 |
| `AWS_ENDPOINT_URL_S3`, `AWS_REGION`          | Object Storage      | S3 endpoint and region. The `AWS_*` names mean the AWS SDKs work with no setup.                                                     |

These variables are branch-scoped: each branch injects its own values. A function deployed to a preview branch connects to that branch's database, not the default branch's.

**Note: Two AI Gateway endpoints**

`NEON_AI_GATEWAY_BASE_URL` is the bare gateway host: append a dialect path yourself. Use `/openai/v1` for the OpenAI **Responses API** and `/v1` for **Chat Completions** (see [Chat completions](https://neon.com/docs/ai-gateway/chat-completions)). The [`@neon/ai-sdk-provider`](https://neon.com/docs/compute/functions/agents) handles this routing for you.

**Note: Local pull vs. deployed runtime**

A deployed function gets credentials injected automatically for every service enabled on its branch, so you don't ship a `.env`. For local development, `neon env pull` writes the branch's core variables plus credentials for any services you **declare in `neon.ts`**, which can be a subset. Declare a service (`auth: true`, `dataApi: true`, `aiGateway: true`, `buckets: { ... }`) to pull its credentials locally and to get type-safe access. (Outside a `neon.ts` workflow, `neon env pull` still writes the branch's core variables — see the [`env` command](https://neon.com/docs/cli/env).)

For type-safe access, the [`@neon/env`](https://www.npmjs.com/package/@neon/env) package ships `parseEnv`. It takes your `neon.ts` config and returns a typed env object validated against the services the config declares:

```ts
import { parseEnv } from '@neon/env';
import config from './neon';

const env = parseEnv(config);
env.postgres.databaseUrl;          // DATABASE_URL
env.postgres.databaseUrlUnpooled;  // DATABASE_URL_UNPOOLED
env.auth.baseUrl;                  // NEON_AUTH_BASE_URL (only when auth: true)
env.auth.jwksUrl;                  // NEON_AUTH_JWKS_URL (only when auth: true)
```

TypeScript narrows the shape based on your config: `env.auth` is only present when `auth: true` is set in `neon.ts`.

## User-defined variables

Each deployment carries its own snapshot of user-defined variables. To change one, deploy again.

### At deploy time

Pass `--env KEY=VALUE` to `neon functions deploy`. The flag is repeatable:

```bash
neon functions deploy hello --src functions/hello.ts --env RESEND_API_KEY=re_...
```

Neon injects variables like `DATABASE_URL`, `NEON_AI_GATEWAY_*`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, and `AWS_REGION` when the matching service is enabled on the branch. These are defaults, not reserved names: if you define a variable with the same name, your value overrides the injected one.

A deploy doesn't wipe variables set by earlier deploys. The `--env` flags you pass are merged into the existing set:

- `--env KEY=value` adds or updates `KEY`
- `--env KEY=` (empty value) deletes `KEY`
- Variables you don't mention carry over unchanged

### In neon.ts

Declare variables under the function's `env` field. Values are resolved when `neon deploy` runs, so you can read from `process.env` to avoid hardcoding secrets:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    hello: {
      name: "My first function",
      source: "./functions/hello.ts",
      env: {
        RESEND_API_KEY: process.env.RESEND_API_KEY!,
      },
    },
  },
});
```

Load a `.env` file before running `neon deploy` to make secrets available during config evaluation:

```bash
neon deploy --env .env.production
```

The file isn't forwarded to the function directly. Only variables declared in the `env` field are deployed; `--env` only controls what `process.env` contains when `neon.ts` is evaluated.

## Pull variables locally

`neon link` and `neon checkout` pull the branch's Neon-injected variables into a local `.env` file automatically (pass `--no-env-pull` to skip). To re-pull at any time:

```bash
neon env pull
```

By default this writes to `.env` if it exists, otherwise `.env.local`. Use `--file` to write to any file:

```bash
neon env pull --file .env.preview
```

To pull from a different branch, switch with `neon checkout`; it pulls the new branch's variables as part of the switch.

`env pull` writes only the Neon-managed variables and preserves every other line in the file. That's the core variables `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `NEON_BRANCH`, and `NEON_BRANCH_ID`, plus the variables for any service you **declare in `neon.ts`**: the Managed Better Auth URLs, the Neon Data API URL, the AI Gateway credentials (`NEON_AI_GATEWAY_TOKEN`, `NEON_AI_GATEWAY_BASE_URL`), and the Object Storage credentials (`AWS_*`). It also writes `NEON_FUNCTION_HOST_SUFFIX`, which together with `NEON_BRANCH_ID` lets code running locally build the same function URLs as deployed code. See [Call another function](https://neon.com/docs/compute/functions/environment-variables#call-another-function).

## Call another function

Every function on a branch answers at `https://<NEON_BRANCH_ID>-<slug><NEON_FUNCTION_HOST_SUFFIX>`. Neon injects both variables into every deployed function. Locally, `neon env pull` writes them, and `neon dev` sets them for the functions it serves. `functionBaseUrl` from `@neon/env` 2.0.0 or later builds the URL for you, without a trailing slash:

```ts
import { functionBaseUrl } from '@neon/env';

const res = await fetch(`${functionBaseUrl('hello')}/greet`);
```

Under [`neon dev`](https://neon.com/docs/cli/dev), `functionBaseUrl` returns `http://localhost:<port>` for each function that `neon dev` is serving and the deployed URL for any other slug. It throws a `TypeError` for an invalid slug, and a `PlatformError` when either variable is missing.

`functionBaseUrl` reads `process.env` by default. When the two variables come from somewhere else, pass them as the second argument:

```ts
functionBaseUrl('hello', { NEON_BRANCH_ID: branchId, NEON_FUNCTION_HOST_SUFFIX: hostSuffix });
```

Browser code can't read these variables. Build the URL on the server with `functionBaseUrl` and pass it to the client.

Neon CLI 9.0.0 and `@neon/env` 2.0.0 replaced the per-function `NEON_FUNCTION_<SLUG>_BASE_URL` variables, which deployed functions never received. If your code reads `env.functions.<slug>.baseUrl`, upgrade to `@neon/env` 2 and call `functionBaseUrl('<slug>')` instead.

## Constraints

| Constraint                   | Value  |
| ---------------------------- | ------ |
| Max variables per deployment | 1,000  |
| Max total size               | 32 KiB |

The total size counts every variable's name and value. A deploy that exceeds it fails with `400 invalid environment: total size <N> bytes exceeds the 32768-byte limit`. To fix it, remove or shorten variables in the same deploy. Leave some headroom: the variables Neon injects at runtime, such as `DATABASE_URL`, also count toward the limit when your function runs.

--- [Document source](https://neon.com/docs/compute/functions/get-started.md) ---

> Summary: Deploy your first Neon Function, a long-running serverless function that runs on your Neon branch: initialize a project, define the function in neon.ts, develop locally with neon dev, and deploy with neon deploy. The function gets a public HTTPS URL with DATABASE_URL injected from the branch's Postgres database.

# Get started with Neon Functions

Deploy your first Neon Function and call it over HTTP.

Last updated: 2026-11-05

A function takes a request and returns a web response, running on long-lived Node.js compute next to your database. The request can come over HTTP, or from a [Function Trigger](https://neon.com/docs/compute/functions/triggers/overview) on a schedule or object upload.

**Prefer to start from a working example?:**

Browse the [function templates](https://neon.com/functions/templates) for ready-made APIs, MCP servers, AI agents, and bots, then add one to your project with `neon functions new`. See [Use function templates](https://neon.com/docs/compute/functions/templates). To scaffold a complete app instead, use [`neon bootstrap`](https://neon.com/docs/cli/bootstrap).

## Hello world

Write a file and deploy it:

```ts filename="hello-world.ts"
export default {
  fetch: (request: Request) => new Response('Hello world'),
};
```

```bash filename="Neon CLI"
neon link
neon functions deploy helloworld --src hello-world.ts
```

Done, function deployed. Get the public URL:

```bash filename="Neon CLI"
neon functions get helloworld -o yaml
```

```yaml
id: helloworld
slug: helloworld
name: helloworld
invocation_url: https://br-wispy-brook-a1b2c3d4-helloworld.compute.c-2.us-east-2.aws.neon.tech/
current_deployment:
  id: 1
  status: completed
  memory_mib: 2048
  runtime: nodejs24
  created_at: 2026-08-03T21:19:18.120982Z
active_deployment:
  id: 1
  status: completed
  memory_mib: 2048
  runtime: nodejs24
  created_at: 2026-08-03T21:19:18.120982Z
created_at: 2026-08-03T21:19:17.989227Z
```

When `status` is `completed`, the function is live. Call `invocation_url` to see the function's output, which is "Hello world" in this case.

That's a deployed function in three commands. The rest of this guide builds a more realistic one: declared in `neon.ts`, run locally with `neon dev`, and querying Postgres.

## Prerequisites

- A Neon project in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions).
- The latest `neon`, installed and authenticated. Functions commands are new and change often, so upgrade before you start (`npm install -g neon@latest`).
- Node.js 20 or later. Deployed functions run on Node.js 24, so use 24 locally for the closest match.

To give your AI coding assistant context for Neon and Functions, install the [agent skills](https://neon.com/docs/ai/agent-skills) with the [Neon CLI](https://neon.com/docs/cli):

```bash
neon skills -s neon -s neon-functions
```

Without the Neon CLI, run `npx skills add neondatabase/agent-skills -s neon -s neon-functions` instead.

## Set up your project

Create your project directory:

```bash
mkdir my-function && cd my-function
```

Then link the directory to your Neon project. There are two ways:

**With an AI coding assistant.** Ask your assistant to set up Neon for the project. Using the skills you installed, it links your project (creating one if you need it) with `neon link` and pulls your environment variables. Sign-in opens a browser window, so complete the OAuth step when prompted.

**By hand.** Run `neon link` and select your project and branch when prompted (or pass `--project-id`). This writes a `.neon` file and pulls the branch's environment variables into a local `.env` file (or `.env.local` if there's no `.env` yet).

```bash
neon link
```

To start from a working example instead, run `neon bootstrap`. It scaffolds a starter template, installs dependencies, and links it. Templates include a REST API, GraphQL API, tRPC API, MCP server, realtime chat and counter, AI agents, and Discord, Telegram, and WhatsApp bots. Run `neon bootstrap --list-templates` for the full catalog. This guide builds the function by hand.

## Define your function

Create `neon.ts` at your project root. It declares your functions and is what `neon dev` and `neon deploy` read:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    // The key is the function's slug:
    // a permanent ID used in CLI commands and the URL.
    hello: {
      name: "My first function", // display label only
      source: "./functions/hello.ts", // path to the handler file
    },
  },
});
```

The slug is permanent: it can't be renamed after the first deploy. It allows only 1 to 20 lowercase letters and digits, so `sendemail` works and `send-email` doesn't. See the [neon.ts reference](https://neon.com/docs/reference/neon-ts) for all options.

As a shortcut, `neon config add function hello` creates this `neon.ts` and a starter `functions/hello.ts` handler for you. See [`neon config add`](https://neon.com/docs/cli/config#add). To start from a ready-made [function template](https://neon.com/functions/templates) instead, see [Use function templates](https://neon.com/docs/compute/functions/templates).

Install dependencies:

```bash
npm install @neon/config @neon/functions hono pg
npm install --save-dev @types/pg
```

A function is any module whose default export has a `fetch(request)` method that returns a `Response`. That can be an object with a `fetch` method:

```ts
export default {
  fetch: (request: Request) => new Response('Hello world'),
};
```

Or a bare async function:

```ts
export default async function handler(request: Request) {
  return new Response('Hello world');
}
```

A Hono app exports the object shape, so `export default app` works directly. For this guide, write a handler that queries Postgres. `DATABASE_URL` is injected automatically from the linked branch's Postgres database:

```ts filename="functions/hello.ts"
import { Hono } from 'hono';
import { attachDatabasePool } from '@neon/functions';
import { Pool } from 'pg';

// Create the pool once at module scope so it's reused across requests.
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
attachDatabasePool(pool);
const app = new Hono();

app.get('/', async (c) => {
  const { rows } = await pool.query('SELECT version()');
  return c.json(rows[0]);
});

export default app;
```

**Important: Use a connection pool, not the serverless driver**

A function keeps running across requests, so connect to Postgres with a long-lived `pg` `Pool` created once at module scope. Don't use `@neondatabase/serverless` here: it's built for short-lived, edge-style invocations that open a connection per request, which wastes the persistent runtime a function gives you. Use the pooled `DATABASE_URL` for queries; use `DATABASE_URL_UNPOOLED` only where you need a dedicated connection (such as `LISTEN`/`NOTIFY`).

Call `attachDatabasePool(pool)` once after creating the pool (requires `@neon/functions` 0.8.0 or later). When Postgres drops an idle client (scale-to-zero, pooler reclaim, a TCP reset), `pg` emits an `error` on the pool; with no listener attached, that becomes an uncaught exception and the isolate exits. `attachDatabasePool` swallows expected idle disconnects and logs anything unexpected. The pool has already discarded the dead client, so the next query opens a fresh connection. You don't need to drain the pool on shutdown: when the runtime evicts an isolate, Neon's pooler reclaims those connections for you.

## Develop locally

`neon dev` serves all functions declared in `neon.ts` with hot reload. It injects `DATABASE_URL` and other Neon env vars from the linked branch. See [Environment variables](https://neon.com/docs/compute/functions/environment-variables) for the full list and how to pull them into a local `.env` file.

```bash
neon dev
```

The terminal prints the URL for each running function:

```text
  Neon Functions dev server

  hello                http://localhost:8787
```

## Deploy

`neon deploy` reads `neon.ts` and applies it to the linked branch, deploying every function it declares:

```bash
neon deploy
```

The CLI bundles each function with esbuild, uploads it, and waits for the deployment to complete.

To deploy a single file without a `neon.ts`, deploy it by slug instead:

```bash
neon functions deploy hello --src functions/hello.ts
```

For all deploy options, including the Neon API, see [Deploy and manage functions](https://neon.com/docs/compute/functions/deploy).

## Invoke

Once the deployment reaches `completed`, retrieve the invocation URL:

```bash
neon functions get hello
```

The `URL` field contains the public URL for your function (`invocation_url` in `--output json`):

```
https://<branch_id>-<slug>.compute.<cell>.us-east-2.aws.neon.tech/
```

Call it with curl:

```bash
curl https://<branch_id>-hello.compute.<cell>.us-east-2.aws.neon.tech/
```

The response is a JSON object with your branch's Postgres version:

```json
{ "version": "PostgreSQL 17.x on ..., compiled by gcc ..." }
```

## Next steps

- [Use function templates](https://neon.com/docs/compute/functions/templates): add a ready-made function from the [template catalog](https://neon.com/functions/templates) instead of writing one by hand
- [Function Triggers](https://neon.com/docs/compute/functions/triggers/overview): invoke a function on a cron schedule or an object upload instead of over HTTP
- [Deploy and manage](https://neon.com/docs/compute/functions/deploy): the CLI and API for managing deployed functions
- [Authentication](https://neon.com/docs/compute/functions/authentication): verify callers before a function runs
- [Custom domains](https://neon.com/docs/compute/functions/custom-domains): serve a function from a domain you own

--- [Document source](https://neon.com/docs/compute/functions/logs.md) ---

> Summary: View a deployed function's logs in the Neon Console: console.* output from your handler and its dependencies, plus a platform-emitted invoke begin / invoke end line around each request. Covers the console-method-to-level mapping, common log entries that look like a problem but aren't, and wiring up application instrumentation like Sentry or OpenTelemetry.

# Neon Functions logs

View, search, and download logs for a deployed function.

Last updated: 2026-11-06

Every deployed function streams its logs to the Neon Console: everything your handler and its dependencies write with `console.log`, `console.info`, `console.warn`, `console.error`, or `console.debug`, plus a platform-emitted `invoke begin` / `invoke end` line around each request:

```text
2026-07-09T19:31:43.902476000Z    INFO    invoke end
2026-07-09T19:31:43.831541000Z    INFO    invoke begin
```

## View logs

Function logs live on the branch's [Monitoring page, in the **Functions** tab](https://neon.com/docs/introduction/monitor-logs). To jump straight to one function's logs, open the **Functions** list, open that function's menu, and select **View logs**. Or go to **Monitoring** and open the **Functions** tab to see every function's logs together.

Expand a row to see its full context: `timestamp`, `severity`, `entity_type`, `scope_name`, and `service_name`.

`scope_name` distinguishes platform-emitted lines from your own output:

- `neon.function.request`: the `invoke begin` / `invoke end` line the platform emits around each request.
- Your own `console.*` output is scoped to the function's app logs, alongside `console.*` output from your dependencies.

## Log levels

A function's log level comes from the `console` method used to emit it:

| Level   | Emitted by                    |
| ------- | ----------------------------- |
| `DEBUG` | `console.debug`               |
| `INFO`  | `console.log`, `console.info` |
| `WARN`  | `console.warn`                |
| `ERROR` | `console.error`               |

`NOTICE` and `FATAL` also appear as filters in the log viewer but aren't currently emitted by Functions; they're part of the console's shared log-level set.

Only those `console` methods reach your logs. Output written straight to `process.stdout` or `process.stderr`, including from a logger configured to write to a stream, is discarded. Point your logger at `console`, or use a [monitoring SDK](https://neon.com/docs/compute/functions/logs#application-instrumentation).

## Common log entries

Most of what shows up in your logs is your own `console.log`/`console.error` output. A few entries look like something's wrong when it isn't, or point you somewhere other than the log itself. Here's what to do when you see them.

**Seeing this SSL warning on cold start? Ignore it, or set `sslmode=verify-full` to silence it.**

```text
(node:95) Warning: SECURITY WARNING: The SSL modes 'prefer', 'require', and 'verify-ca' are treated as aliases for 'verify-full'.
```

It's a `pg` (node-postgres) deprecation warning, not a connection problem: the injected `DATABASE_URL` uses `sslmode=require`, and `pg` warns on that mode regardless of whether anything is wrong. It logs at `ERROR` because Node prints process warnings through `console.error`, not because the severity was assessed. If you'd rather not see it, connect with `sslmode=verify-full` explicitly instead of relying on the default.

**Seeing an `ERROR` `invoke end` with no other detail? It's not your code, don't debug your handler for it.** The platform never puts internal failure detail (no execution node reachable, a launch or scheduler failure) into customer-facing logs, so this line won't tell you more than "the platform failed to complete this request." Retry; if it keeps happening, contact support rather than searching your own code for the cause. (Your own handler returning an error response is a different case and logs as `INFO`, since the platform still successfully invoked your function.)

**Requests not showing up in your logs at all? Check the invocation URL and branch, not the logs.** A wrong branch, a typo'd slug, or a momentary control-plane hiccup returns a 404 or 503 straight to the caller and never reaches your function's log stream, because the platform hasn't resolved which function to attribute logs to yet. If you expect traffic and see nothing, the request likely never reached your function.

**Function not starting after a deploy? Read the response body, not the logs.** A missing entry point, an import that throws at load time, or a default export of the wrong shape returns a `function_load_failed` error with your actual error message in the response body of the failed request, not as a log line. Check the response you got back from calling the function, not the Functions tab.

## Application instrumentation

A function is a long-lived Node.js process, so standard Node monitoring SDKs like [Sentry](https://sentry.io) and [OpenTelemetry](https://opentelemetry.io) work unchanged. Initialize the SDK once at module load, before your handler starts serving requests, so the whole isolate is instrumented. Gate it on an environment variable (the SDK's DSN or endpoint) so local `neon dev` runs and branches without the secret configured stay a no-op, then pass the SDK's secret at deploy time as a [user-defined variable](https://neon.com/docs/compute/functions/environment-variables#user-defined-variables).

Neon sends `SIGINT`/`SIGTERM` before evicting an idle isolate, so flush buffered telemetry in a shutdown handler or the last events are lost:

```ts
process.on('SIGINT', () => void Sentry.flush(2000));
```

To send unexpected database pool errors to your monitoring SDK, pass `onUnexpectedError` when you call [`attachDatabasePool`](https://neon.com/docs/compute/functions/get-started#connect-to-postgres). Expected idle disconnects are still swallowed; only unexpected errors reach the handler:

```ts
import { attachDatabasePool } from '@neon/functions';
import { Pool } from 'pg';
import { Sentry } from './instrument';

const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
attachDatabasePool(pool, {
  onUnexpectedError: (err) => Sentry.captureException(err),
});
```

`neon deploy` bundles your code with esbuild, which defeats auto-instrumentation that patches modules at import time. If a library's spans are missing from a deployed function, that's the first thing to check.

## Filter and search

For details on filtering by level or service name, searching log bodies, live tail, and downloading logs, see [Monitor logs](https://neon.com/docs/introduction/monitor-logs).

You can also read function logs from the terminal with [`neon logs query`](https://neon.com/docs/cli/logs). `--source function` returns every function on the branch, and `--service-name neon-function/<slug>` narrows it to one:

```bash
neon logs query --source function --service-name neon-function/hello --since 1h
```

--- [Document source](https://neon.com/docs/compute/functions/mcp-server.md) ---

> Summary: Build an MCP server on Neon Functions that customers connect from Claude, Cursor, or ChatGPT. Managed Better Auth issues OAuth tokens, your Next.js app hosts the sign-in and consent pages, and each tool reads and writes only the signed-in user's rows.

# Build an MCP server with Managed Better Auth

Give your app an MCP server on Neon Functions, with OAuth sign-in from Managed Better Auth.

Let your customers use your app from Claude, Cursor, or ChatGPT. They connect to your app's MCP server, sign in with their existing account, and call tools that read and write only their own rows in Lakebase Postgres.

The MCP server runs on [Neon Functions](https://neon.com/docs/compute/functions/overview). [Managed Better Auth](https://neon.com/docs/auth/overview), with its [OAuth provider plugin](https://neon.com/docs/auth/guides/plugins/oauth-provider), is the OAuth 2.1 authorization server. Your app hosts the sign-in and consent pages on a public HTTPS origin, because remote clients can't complete OAuth against `localhost`. This guide builds the pages in Next.js, but any framework works if its pages meet the [page requirements](https://neon.com/docs/compute/functions/mcp-server#what-your-sign-in-and-consent-pages-must-do).

If you don't need per-user sign-in, start from the [`mcp-postgres` function template](https://neon.com/functions/templates/mcp-postgres) instead.

Use this prompt to build this with your AI agent. [View prompt](https://neon.com/prompts/mcp-server-on-neon-functions-prompt.md)

## How it works

```mermaid
sequenceDiagram
  participant C as MCP client
  participant F as Your function (/mcp)
  participant A as Managed Better Auth
  participant P as Your app (sign-in, consent)
  C->>F: Call /mcp without a token
  F-->>C: 401 with resource_metadata
  C->>A: Start authorization
  A->>P: Send the user to your sign-in page
  P->>A: Sign in, then approve on the consent page
  A-->>C: Access token
  C->>F: Call /mcp with the token
  F->>F: Verify the token, query that user's rows
```

The MCP client calls your function, which answers `401` and names Managed Better Auth as the authorization server. The client then sends the user through your app's sign-in and consent pages and gets an access token from Managed Better Auth. Every later call carries that token: the function verifies it, reads the user ID from its `sub` claim, and queries only that user's rows.

### What your sign-in and consent pages must do

- Run on a public HTTPS origin that you add as a [trusted domain](https://neon.com/docs/auth/guides/configure-domains).
- On the sign-in page, sign the user in. If the sign-in response doesn't redirect, resume the authorization request with `oauth2.continue({ selected: true })`. Do the same when a signed-in user lands on the page with an OAuth query.
- On the consent page, require a session. Show the client name, redirect hosts, and the requested `scope` and `resource`, and warn when every redirect URI is loopback. Then call `oauth2.consent({ accept })`.
- Block framing with a `frame-ancestors 'none'` header.

The `@neon/auth` client (0.8.0 or later) passes the signed OAuth query for you. Without it, call the endpoints in [How the pages complete the flow](https://neon.com/docs/auth/guides/plugins/oauth-provider#how-the-pages-complete-the-flow).

## The example

This guide builds a to-do list with `list_todos`, `add_todo`, and `complete_todo`.

Asked for your todos, ChatGPT calls `list_todos` and shows the result:

![ChatGPT listing the signed-in user's todos, with completed ones checked](https://neon.com/docs/compute/functions/mcp-todos-chatgpt.png)

The optional [MCP Apps section](https://neon.com/docs/compute/functions/mcp-server#render-todos-in-chat-with-mcp-apps-optional) adds an interactive widget.

## Before you start

For this guide, you need:

- A Neon project in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions).
- The [Neon CLI](https://neon.com/docs/cli/install), signed in with `neon login`.
- A Next.js 16 or later app, or another framework whose pages meet the [page requirements](https://neon.com/docs/compute/functions/mcp-server#what-your-sign-in-and-consent-pages-must-do). In Next.js 16, route protection lives in `proxy.ts`.

## Set up the project

In your app's directory, link it to your project and check out a development branch, not production:

```bash
neon link
neon checkout --create dev
```

[`neon link`](https://neon.com/docs/cli/link) pins your default branch, so run [`neon checkout`](https://neon.com/docs/cli/checkout) before anything else. It pins the development branch for the commands that follow and writes its environment variables to `.env.local`. If the parent branch already has this guide's setup, the new branch inherits its table, function, trusted domain, and OAuth settings.

Create [`neon.ts`](https://neon.com/docs/reference/neon-ts) in your app's root if you don't have one:

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

export default defineConfig({
  auth: true,
});
```

Install the config package, apply `neon.ts`, and check that Managed Better Auth is on:

```bash
npm install @neon/config
neon deploy
neon neon-auth status
```

## Create the table

Managed Better Auth stores users in the `neon_auth` schema, so keep app tables like `todos` in `public`. Run this SQL in the [SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or with `psql`:

```sql
CREATE TABLE IF NOT EXISTS todos (
  id serial PRIMARY KEY,
  user_id text NOT NULL,
  text text NOT NULL,
  done boolean NOT NULL DEFAULT false
);

CREATE INDEX IF NOT EXISTS todos_user_id_idx ON todos (user_id);
```

`user_id` stores the access-token `sub`. Use `text` because the ID is a string.

## Write the MCP server

Install the function's dependencies:

```bash
npm install @neon/oauth @neon/functions @modelcontextprotocol/sdk hono pg zod
npm install -D @types/pg
```

The server uses [`@neon/oauth`](https://github.com/neondatabase/neon-pkgs/tree/main/packages/oauth) 0.3.0 or later (beta) to verify tokens, and the web-standard MCP transport needs `@modelcontextprotocol/sdk` 1.25.0 or later.

Each tool filters by the token's `sub`. Build a new `McpServer` per request so the tools close over it, and keep the `pg` pool at module scope. Never take the user ID from tool input.

```typescript filename="functions/todos/index.ts"
import { Hono } from "hono";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
import { createMcpAuth } from "@neon/oauth/mcp";
import { honoMcp, type McpAuthVariables } from "@neon/oauth/mcp/hono";
import { attachDatabasePool } from "@neon/functions";
import { Pool } from "pg";
import { z } from "zod";

type Todo = { id: number; text: string; done: boolean };

// Neon injects sslmode=require. Rewrite it to verify-full so node-postgres
// keeps its current behavior without warnings.
function databaseUrl() {
  const url = new URL(process.env.DATABASE_URL!);
  if (url.searchParams.get("sslmode") === "require") {
    url.searchParams.set("sslmode", "verify-full");
  }
  return url.toString();
}

const pool = new Pool({ connectionString: databaseUrl(), max: 5 });
attachDatabasePool(pool);

const mcpAuth = createMcpAuth({
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  resource: process.env.MCP_RESOURCE!,
});

const asText = (payload: unknown) => ({
  content: [{ type: "text" as const, text: JSON.stringify(payload) }],
});

function createServer(userId: string) {
  const server = new McpServer({ name: "todos", version: "1.0.0" });

  server.registerTool(
    "list_todos",
    {
      title: "List todos",
      description: "List the signed-in user's todos.",
      inputSchema: {},
      // ChatGPT treats tools without readOnlyHint as writes and may block them
      // until the user allows write tools.
      annotations: { readOnlyHint: true },
    },
    async () => {
      const { rows } = await pool.query<Todo>(
        "SELECT id, text, done FROM todos WHERE user_id = $1 ORDER BY id",
        [userId],
      );
      return asText(rows);
    },
  );

  server.registerTool(
    "add_todo",
    {
      title: "Add todo",
      description: "Add a todo for the signed-in user.",
      inputSchema: { text: z.string().min(1) },
      annotations: { readOnlyHint: false },
    },
    async ({ text }) => {
      const { rows } = await pool.query<Todo>(
        "INSERT INTO todos (user_id, text) VALUES ($1, $2) RETURNING id, text, done",
        [userId, text],
      );
      return asText(rows[0]);
    },
  );

  server.registerTool(
    "complete_todo",
    {
      title: "Complete todo",
      description: "Mark one of the signed-in user's todos as done.",
      inputSchema: { id: z.number().int().positive() },
      annotations: { readOnlyHint: false },
    },
    async ({ id }) => {
      const { rows } = await pool.query<Todo>(
        "UPDATE todos SET done = true WHERE id = $1 AND user_id = $2 RETURNING id, text, done",
        [id, userId],
      );
      return asText(rows[0] ?? { error: "not found" });
    },
  );

  return server;
}

const app = new Hono<McpAuthVariables>();

app.use(honoMcp(mcpAuth, { path: "/mcp" }));

app.all("/mcp", async (c) => {
  const server = createServer(c.get("auth").sub);
  const transport = new WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });
  await server.connect(transport);
  return transport.handleRequest(c.req.raw);
});

export default app;
```

## Deploy the function

Neon injects `DATABASE_URL`, and `NEON_AUTH_BASE_URL` once Managed Better Auth is on for the branch. The function also needs `MCP_RESOURCE`, its own `/mcp` URL. You only get that URL after the first deploy, so you deploy twice. Until the second deploy, every request returns `502` with `function_load_failed`, because `createMcpAuth` requires an absolute `resource` URL.

The slug (`todos`) can be up to 20 lowercase letters or digits and can't change after the first deploy. If the branch inherited a `todos` function from its parent, the first deploy updates it, and it serves the parent's `MCP_RESOURCE` until the second deploy.

Deploy once with [`neon functions deploy`](https://neon.com/docs/cli/functions#deploy) and read the function URL:

```bash
neon functions deploy todos --src functions/todos
neon functions get todos
```

Append `/mcp` to the function URL from the output and deploy again:

```bash
neon functions deploy todos \
  --src functions/todos \
  --env "MCP_RESOURCE=https://<branch_id>-todos.compute.<cell>.aws.neon.tech/mcp"
```

A new deployment can take a few minutes to serve traffic. To confirm the running value, check that `resource` in the [protected resource metadata](https://neon.com/docs/auth/guides/plugins/oauth-provider#protect-an-mcp-server) matches `MCP_RESOURCE`:

```bash
curl https://<branch_id>-todos.compute.<cell>.aws.neon.tech/.well-known/oauth-protected-resource/mcp
```

To serve the function from your own domain instead, see [Use a custom domain](https://neon.com/docs/compute/functions/mcp-server#use-a-custom-domain-optional).

### Manage the function from neon.ts (optional)

The function isn't declared in `neon.ts`, so `neon deploy` doesn't redeploy it. To manage it from `neon.ts` instead, declare it once you know the URL:

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

export default defineConfig({
  auth: true,
  functions: {
    todos: {
      name: "todos",
      source: "functions/todos/index.ts",
      env: { MCP_RESOURCE: process.env.MCP_RESOURCE! },
    },
  },
});
```

Add `MCP_RESOURCE` to `.env.local`, then deploy with the file:

```bash
neon deploy --env .env.local
```

`neon deploy` and `neon checkout --create` then refuse to run until `MCP_RESOURCE` is set.

## Build the sign-in and consent pages (Next.js example)

This section builds the pages in Next.js. On another framework, build pages that meet the [page requirements](https://neon.com/docs/compute/functions/mcp-server#what-your-sign-in-and-consent-pages-must-do) and skip to the next section.

Install the Managed Better Auth SDK and generate a cookie secret:

```bash
npm install @neon/auth@latest
openssl rand -base64 32
```

The `neon deploy` you ran during setup wrote `NEON_AUTH_BASE_URL` to `.env.local`. If it's missing, run `neon env pull`. Add the cookie secret next to it:

```env filename=".env.local"
NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-2.aws.neon.tech/neondb/auth
NEON_AUTH_COOKIE_SECRET=paste-the-openssl-output-here
```

Create `lib/auth/server.ts`, `lib/auth/client.ts`, and the `app/api/auth/[...path]/route.ts` handler as shown in [Use Managed Better Auth with Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only). If Managed Better Auth already works in your Next.js app, keep that setup.

For an MCP server, `proxy.ts` must protect every route except `/` and the sign-in and sign-up pages, so the consent page always has a session:

```typescript filename="proxy.ts"
import { auth } from "@/lib/auth/server";

export default auth.middleware({
  loginUrl: "/auth/sign-in",
  publicRoutes: ["/", "/auth/sign-in", "/auth/sign-up"],
});

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"],
};
```

Block framing of the sign-in and consent pages with a `frame-ancestors 'none'` header. Add the `headers()` function to your existing `next.config.ts` instead of replacing the file:

```typescript filename="next.config.ts"
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: "/auth/:path*",
        headers: [
          {
            key: "Content-Security-Policy",
            value: "frame-ancestors 'none'",
          },
        ],
      },
    ];
  },
};

export default nextConfig;
```

Add a sign-up page at `/auth/sign-up` so test users can create accounts, like the one in [Use Managed Better Auth with Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only).

The markup below is unstyled. In a default Next.js app, Tailwind's base styles remove input borders, so the fields look invisible until you style them.

### Sign-in page

Put the OAuth logic in a helper that resumes the authorization request only when the URL has `client_id` and `response_type`. A normal visit, such as after sign-up, has no OAuth query, and `oauth2.continue` returns HTTP 400 for it:

```typescript filename="lib/auth/oauth.ts"
import { authClient } from "@/lib/auth/client";

// Auth sends users to the sign-in page with the authorization request in the query.
// A normal visit has no OAuth query, and oauth2.continue returns HTTP 400 for it.
export function hasOAuthQuery() {
  const params = new URLSearchParams(window.location.search);
  return params.has("client_id") && params.has("response_type");
}

// Resume the authorization request. Returns an error message, or null.
export async function continueOAuth() {
  const { error } = await authClient.oauth2.continue({ selected: true });
  return error ? "This sign-in link expired. Go back to the app and try again." : null;
}
```

Then call it from the sign-in page:

```tsx filename="app/auth/sign-in/page.tsx"
"use client";

import { useEffect, useState } from "react";
import { useRouter } from "next/navigation";
import { authClient } from "@/lib/auth/client";
import { continueOAuth, hasOAuthQuery } from "@/lib/auth/oauth";

export default function SignInPage() {
  const router = useRouter();
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");
  const [error, setError] = useState<string | null>(null);
  const [pending, setPending] = useState(false);

  // A signed-in user sent here by an MCP client: resume the authorization request.
  useEffect(() => {
    let cancelled = false;

    async function resume() {
      if (!hasOAuthQuery()) return;
      const { data } = await authClient.getSession();
      if (cancelled || !data?.user) return;
      const message = await continueOAuth();
      if (message && !cancelled) setError(message);
    }

    void resume();
    return () => {
      cancelled = true;
    };
  }, []);

  async function onSubmit(event: React.FormEvent) {
    event.preventDefault();
    setPending(true);
    setError(null);

    const { data, error } = await authClient.signIn.email({ email, password });
    setPending(false);

    if (error) {
      setError(error.message || "Failed to sign in");
      return;
    }

    // After sign-in: let the SDK redirect, resume OAuth, or go home.
    if (data?.redirect) return;
    if (hasOAuthQuery()) {
      setError(await continueOAuth());
      return;
    }
    router.push("/");
  }

  return (
    <main>
      <h1>Sign in</h1>
      <form onSubmit={onSubmit}>
        <label>
          Email
          <input
            type="email"
            value={email}
            onChange={(event) => setEmail(event.target.value)}
            required
          />
        </label>
        <label>
          Password
          <input
            type="password"
            value={password}
            onChange={(event) => setPassword(event.target.value)}
            required
          />
        </label>
        {error ? <p>{error}</p> : null}
        <button type="submit" disabled={pending}>
          {pending ? "Signing in..." : "Sign in"}
        </button>
      </form>
    </main>
  );
}
```

### Consent page

Load the client with `oauth2.publicClient`, show the details listed in the [page requirements](https://neon.com/docs/compute/functions/mcp-server#what-your-sign-in-and-consent-pages-must-do), then call `oauth2.consent({ accept })`:

```tsx filename="app/auth/consent/page.tsx"
"use client";

import { useEffect, useState } from "react";
import { authClient } from "@/lib/auth/client";

type PublicClient = {
  client_id: string;
  client_name: string;
  client_uri?: string;
  logo_uri?: string;
  redirect_uris?: string[];
};

type ConsentRequest = {
  client: PublicClient;
  scope: string;
  resource: string;
};

function hostFromUri(uri: string) {
  try {
    return new URL(uri).host;
  } catch {
    return uri;
  }
}

function isLoopback(uri: string) {
  try {
    const { hostname } = new URL(uri);
    return (
      hostname === "localhost" ||
      hostname === "127.0.0.1" ||
      hostname === "[::1]"
    );
  } catch {
    return false;
  }
}

export default function ConsentPage() {
  const [request, setRequest] = useState<ConsentRequest | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [pending, setPending] = useState(false);

  useEffect(() => {
    let cancelled = false;

    async function load() {
      // Read the query in the browser. window doesn't exist during prerender.
      const params = new URLSearchParams(window.location.search);
      const { data, error } = await authClient.oauth2.publicClient({
        query: { client_id: params.get("client_id") ?? "" },
      });

      if (cancelled) return;
      if (error) {
        setError(error.message || "Failed to load client details");
        return;
      }
      setRequest({
        client: data as PublicClient,
        scope: params.get("scope") ?? "",
        resource: params.get("resource") ?? "",
      });
    }

    void load();
    return () => {
      cancelled = true;
    };
  }, []);

  async function respond(accept: boolean) {
    setPending(true);
    setError(null);
    const { error } = await authClient.oauth2.consent({ accept });
    setPending(false);
    if (error) {
      setError(error.message || "Consent failed");
    }
  }

  const redirectUris = request?.client.redirect_uris ?? [];
  const onlyLoopback =
    redirectUris.length > 0 && redirectUris.every(isLoopback);

  return (
    <main>
      <h1>Allow access</h1>
      {request ? (
        <>
          <p>
            <strong>{request.client.client_name}</strong> wants access to your
            account.
          </p>
          {request.client.client_uri ? (
            <p>Client site: {request.client.client_uri}</p>
          ) : null}
          {redirectUris.length > 0 ? (
            <p>Redirect hosts: {redirectUris.map(hostFromUri).join(", ")}</p>
          ) : null}
          {request.scope ? <p>Scopes: {request.scope}</p> : null}
          {request.resource ? <p>Resource: {request.resource}</p> : null}
          {onlyLoopback ? (
            <p>
              This client redirects only to localhost, so it runs on this
              device. The name above is not proof of identity.
            </p>
          ) : null}
        </>
      ) : (
        <p>Loading client details...</p>
      )}
      {error ? <p>{error}</p> : null}
      <button type="button" disabled={pending} onClick={() => void respond(true)}>
        Allow
      </button>
      <button
        type="button"
        disabled={pending}
        onClick={() => void respond(false)}
      >
        Deny
      </button>
    </main>
  );
}
```

The page reads `window.location.search` inside an effect, not during render. Next.js prerenders client components, and `window` doesn't exist there, so reading it during render fails `next build`.

## Deploy the app and turn on the OAuth server

Deploy your app to a public HTTPS origin (this guide uses Vercel), then point Managed Better Auth at it.

```bash
vercel link --yes --project app-mcp-tutorial
vercel env add NEON_AUTH_BASE_URL production
vercel env add NEON_AUTH_COOKIE_SECRET production
vercel env add DATABASE_URL production   # only if your app reads todos
vercel deploy --prod --yes
```

`vercel deploy --prod` prints this deployment's own URL and the project's stable production URL:

```text filename="Output"
Production  https://<project>-<hash>-<team>.vercel.app
Aliased     https://<project>.vercel.app
```

Use the `Aliased` URL (`https://<your-app>.vercel.app`) in the commands below. It stays the same across deploys.

Add the Vercel app's origin as a trusted domain, because Managed Better Auth redirects only to trusted origins. If the command reports that the domain already exists, it's already trusted. Then turn on the OAuth server with [`neon neon-auth config oauth-server`](https://neon.com/docs/cli/neon-auth#config-oauth-server):

```bash
neon neon-auth domain add https://<your-app>.vercel.app

neon neon-auth config oauth-server update --enabled \
  --login-page https://<your-app>.vercel.app/auth/sign-in \
  --consent-page https://<your-app>.vercel.app/auth/consent \
  --mcp-resource https://<branch_id>-todos.compute.<cell>.aws.neon.tech/mcp \
  --mcp-client-id-metadata-documents

neon neon-auth config oauth-server get
```

With [Client ID Metadata Documents](https://neon.com/docs/auth/guides/plugins/oauth-provider#client-id-metadata-documents) (CIMD), clients identify themselves, so you don't create a client for each one. CIMD is on by default once you set an MCP resource. If it was turned off earlier, setting `--mcp-resource` doesn't turn it back on, so pass `--mcp-client-id-metadata-documents`. Leave [dynamic client registration](https://neon.com/docs/auth/guides/plugins/oauth-provider#dynamic-client-registration-legacy) off unless a client can't use CIMD.

Each branch has its own OAuth settings, OAuth clients, trusted domains, and MCP resource URL. A new child branch copies them from its parent, including each client's ID and secret, and its function keeps the parent's `MCP_RESOURCE`, so both point at the parent's function URL. Tokens from one branch don't work on another branch's server, because each branch has its own issuer. See [Branching authentication](https://neon.com/docs/auth/branching-authentication).

On a child branch, read that branch's function URL, then point both `MCP_RESOURCE` and the OAuth server's MCP resource at it:

```bash
neon functions get todos

neon functions deploy todos \
  --src functions/todos \
  --env "MCP_RESOURCE=https://<child_branch_id>-todos.compute.<cell>.aws.neon.tech/mcp"

neon neon-auth config oauth-server update \
  --mcp-resource https://<child_branch_id>-todos.compute.<cell>.aws.neon.tech/mcp
```

## Verify the server

1. Run `neon neon-auth config oauth-server get` and check that the login page (your sign-in page), consent page, and `mcp.resource` match your URLs.

2. Confirm `issuer` matches `NEON_AUTH_BASE_URL`. Load `.env.local` into your shell first, or paste the URL:

   ```bash
   curl "$NEON_AUTH_BASE_URL/.well-known/oauth-authorization-server"
   ```

3. Call the function with no token. Expect `401` and a `WWW-Authenticate` header with `resource_metadata`:

   ```bash
   curl -i https://<branch_id>-todos.compute.<cell>.aws.neon.tech/mcp
   ```

4. Create a user on `/auth/sign-up`. Connect ChatGPT (see [Connect ChatGPT](https://neon.com/docs/compute/functions/mcp-server#connect-chatgpt)) or another MCP client that supports OAuth and Streamable HTTP to the function's `/mcp` URL. Complete sign-in and consent, then call `list_todos` and `add_todo`.

5. Test isolation with two users. When user B calls `complete_todo` with the ID of one of user A's todos, the result must be `not found`.

If a step fails, first check that the Neon CLI targets the branch you configured, that `--mcp-resource` matches `MCP_RESOURCE` exactly, and that your app's origin is a trusted domain.

### Connect ChatGPT

When you add the server to ChatGPT:

1. Use the function URL ending in `/mcp`, not the Vercel app URL.
2. After OAuth, open the connector details and allow write tools, or choose Allow all tools. Without that, reads can work while writes fail with an opaque error such as "Unknown tool."
3. Refresh the connector or start a new chat after you change tools. ChatGPT caches the tool snapshot.

## Use a custom domain (optional)

To give customers a URL on your own domain, such as `https://mcp.example.com/mcp`, [register a custom domain](https://neon.com/docs/compute/functions/custom-domains) for the function. Then use the custom URL wherever this guide uses the function URL: `MCP_RESOURCE`, `--mcp-resource`, and the URL customers add to their MCP client. Your code doesn't change. `@neon/oauth` builds the `resource_metadata` URL and the token audience from `MCP_RESOURCE`, not from the request's host.

Custom domains aren't inherited, so on a child branch use that branch's own function URL or a separate hostname.

## Test locally over HTTPS (optional)

Use this to test the pages with a local or scripted MCP client. Managed Better Auth sets `__Secure-` session cookies, which scripted clients often omit on plain `http://localhost`. Plain `http://localhost` is a trusted domain by default, while [localhost access](https://neon.com/docs/auth/guides/configure-domains#localhost-is-pre-configured) is on, but `https://localhost` isn't, so add it:

```bash
npm run dev -- --port 3010 --experimental-https

neon neon-auth domain add https://localhost:3010

neon neon-auth config oauth-server update --enabled \
  --login-page https://localhost:3010/auth/sign-in \
  --consent-page https://localhost:3010/auth/consent \
  --mcp-resource https://<branch_id>-todos.compute.<cell>.aws.neon.tech/mcp \
  --mcp-client-id-metadata-documents
```

Point the OAuth pages back at your Vercel origin before you connect a remote client again.

## Render todos in chat with MCP Apps (optional)

MCP clients that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview), such as ChatGPT, can render HTML for a tool result inside the conversation.

Export the HTML from a TypeScript module, so `neon functions deploy` bundles it. A separate `.html` file read with `readFileSync` isn't bundled.

```typescript filename="functions/todos/todo-list-ui.ts"
export const TODO_LIST_UI_URI = "ui://todos/list-v2.html";
export const TODO_LIST_SKYBRIDGE_URI = `${TODO_LIST_UI_URI}+skybridge`;
export const MCP_APP_MIME = "text/html;profile=mcp-app";
export const SKYBRIDGE_MIME = "text/html+skybridge";

export const todoListHtml = `<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Todos</title>
    <style>
      body { font-family: system-ui, sans-serif; margin: 16px; }
      li.done span { text-decoration: line-through; opacity: 0.6; }
      button { margin-left: 8px; }
    </style>
  </head>
  <body>
    <h1>Your todos</h1>
    <p id="empty">No todos yet.</p>
    <ul id="list" hidden></ul>
    <script>
      function todosFrom(payload) {
        if (!payload) return [];
        if (Array.isArray(payload.todos)) return payload.todos;
        if (payload.structuredContent?.todos) return payload.structuredContent.todos;
        if (payload.result?.structuredContent?.todos) {
          return payload.result.structuredContent.todos;
        }
        return [];
      }

      function render(todos) {
        const list = document.getElementById("list");
        const empty = document.getElementById("empty");
        list.replaceChildren();
        if (!todos.length) {
          empty.hidden = false;
          list.hidden = true;
          return;
        }
        empty.hidden = true;
        list.hidden = false;
        for (const todo of todos) {
          const item = document.createElement("li");
          if (todo.done) item.classList.add("done");
          const label = document.createElement("span");
          label.textContent = todo.text;
          item.appendChild(label);
          if (!todo.done) {
            const button = document.createElement("button");
            button.textContent = "Complete";
            button.onclick = () => completeTodo(todo.id);
            item.appendChild(button);
          }
          list.appendChild(item);
        }
      }

      // Replies to tools/call requests sent over postMessage, keyed by request ID.
      const pending = new Map();

      function callTool(name, args) {
        if (window.openai?.callTool) return window.openai.callTool(name, args);
        const id = crypto.randomUUID();
        window.parent.postMessage(
          {
            jsonrpc: "2.0",
            id,
            method: "tools/call",
            params: { name, arguments: args },
          },
          "*",
        );
        return new Promise((resolve, reject) => pending.set(id, { resolve, reject }));
      }

      // Complete the todo, then fetch the list again so the widget shows the change.
      async function completeTodo(id) {
        try {
          await callTool("complete_todo", { id });
          render(todosFrom(await callTool("list_todos", {})));
        } catch (error) {
          console.error("complete_todo failed", error);
        }
      }

      window.addEventListener("message", (event) => {
        const data = event.data;
        if (!data || typeof data !== "object") return;
        if (data.id && pending.has(data.id)) {
          const { resolve, reject } = pending.get(data.id);
          pending.delete(data.id);
          if (data.error) reject(data.error);
          else resolve(data.result);
          return;
        }
        if (
          data.method === "ui/notifications/tool-result" ||
          data.method === "ui/initialize"
        ) {
          render(todosFrom(data.params));
        }
      });

      if (window.openai?.toolOutput) render(todosFrom(window.openai.toolOutput));
      window.parent.postMessage(
        { jsonrpc: "2.0", method: "ui/notifications/initialized" },
        "*",
      );
    </script>
  </body>
</html>
`;
```

The widget loads nothing from other origins. If yours calls an API or loads scripts, styles, or images from another domain, declare those domains in the resource's `_meta.ui.csp` (`connectDomains`, `resourceDomains`). See [OpenAI's CSP guidance](https://developers.openai.com/plugins/build/chatgpt-ui#content-security-policy-csp).

Register the UI as two resources in `functions/todos/index.ts`: the MCP Apps resource, and a `text/html+skybridge` variant, which ChatGPT still expects for widgets:

```typescript filename="functions/todos/index.ts"
import {
  MCP_APP_MIME,
  SKYBRIDGE_MIME,
  TODO_LIST_SKYBRIDGE_URI,
  TODO_LIST_UI_URI,
  todoListHtml,
} from "./todo-list-ui";

function registerTodoListUi(server: McpServer) {
  const readHtml = async (uri: string, mimeType: string) => ({
    contents: [{ uri, mimeType, text: todoListHtml }],
  });

  server.registerResource(
    "todo-list",
    TODO_LIST_UI_URI,
    {
      title: "Todo list",
      description: "Interactive list of the signed-in user's todos.",
      mimeType: MCP_APP_MIME,
    },
    async () => readHtml(TODO_LIST_UI_URI, MCP_APP_MIME),
  );

  server.registerResource(
    "todo-list-skybridge",
    TODO_LIST_SKYBRIDGE_URI,
    {
      title: "Todo list",
      description: "Interactive list of the signed-in user's todos.",
      mimeType: SKYBRIDGE_MIME,
    },
    async () => readHtml(TODO_LIST_SKYBRIDGE_URI, SKYBRIDGE_MIME),
  );
}
```

Call `registerTodoListUi(server)` from `createServer`, then replace `list_todos` with this version. It points at the UI with `_meta` and returns `structuredContent`. The query is the same as before:

```typescript filename="functions/todos/index.ts"
server.registerTool(
  "list_todos",
  {
    title: "List todos",
    description: "List the signed-in user's todos.",
    inputSchema: {},
    annotations: { readOnlyHint: true },
    _meta: {
      ui: { resourceUri: TODO_LIST_UI_URI },
      "ui/resourceUri": TODO_LIST_UI_URI,
      "openai/outputTemplate": TODO_LIST_SKYBRIDGE_URI,
      "openai/widgetAccessible": true,
    },
  },
  async () => {
    const { rows } = await pool.query<Todo>(
      "SELECT id, text, done FROM todos WHERE user_id = $1 ORDER BY id",
      [userId],
    );
    const summary =
      rows.length === 0
        ? "No todos."
        : `Found ${rows.length} todo${rows.length === 1 ? "" : "s"}.`;
    return {
      // Short text avoids ChatGPT showing JSON next to the HTML widget.
      content: [{ type: "text", text: summary }],
      structuredContent: { todos: rows },
    };
  },
);
```

Redeploy the function, refresh the ChatGPT connector or start a new chat, then ask it to list todos. Expect the HTML widget plus the short summary:

![ChatGPT showing the todo list widget, with completed todos crossed out and a Complete button on each open todo](https://neon.com/docs/compute/functions/mcp-apps-todo-widget.png)

## Further reading

- [Use Managed Better Auth with Next.js (API methods)](https://neon.com/docs/auth/quick-start/nextjs-api-only)
- [OAuth Provider](https://neon.com/docs/auth/guides/plugins/oauth-provider)
- [Neon Functions authentication](https://neon.com/docs/compute/functions/authentication)
- [Configure trusted domains](https://neon.com/docs/auth/guides/configure-domains)
- [Neon CLI command: neon-auth](https://neon.com/docs/cli/neon-auth)

--- [Document source](https://neon.com/docs/compute/functions/overview.md) ---

> Summary: Neon Functions are long-running serverless functions you deploy onto a Neon branch. Host an API, AI agent, real-time server, or webhook handler that runs next to your Postgres data, with DATABASE_URL injected automatically.

# Neon Functions

Long-running serverless functions on your Neon branch, next to your data.

Last updated: 2026-11-02

Host APIs, agents, and webhooks at an HTTP URL, with no servers to manage, running on your Neon branch right next to your Postgres data.

[View prompt](https://neon.com/prompts/functions-landing.md)

## Get started

- [Quickstart](https://neon.com/docs/compute/functions/get-started): Deploy your first function and call it over HTTP in under 5 minutes.
- [Function templates](https://neon.com/docs/compute/functions/templates): Add a ready-made API, MCP server, AI agent, or bot to your project with one command.
- [Function Triggers](https://neon.com/docs/compute/functions/triggers/overview): Invoke a function on a cron schedule or an object upload, with no external scheduler.
- [Custom domains](https://neon.com/docs/compute/functions/custom-domains): Serve a function from a domain you own with automatic TLS.
- [AI agents](https://neon.com/docs/compute/functions/agents): Run streaming, tool-calling AI agents next to your data.
- [WebSockets and SSE](https://neon.com/docs/compute/functions/websockets): Hold long-lived connections open with WebSockets or SSE.
- [Authentication](https://neon.com/docs/compute/functions/authentication): Verify callers before a function does any work.
- [Environment variables](https://neon.com/docs/compute/functions/environment-variables): Neon-injected variables and how to add your own secrets.
- [Deploy and manage](https://neon.com/docs/compute/functions/deploy): CLI and API reference for deploying and managing functions.
- [Logs](https://neon.com/docs/compute/functions/logs): View, search, and download a function's logs in the Console.
- [Runtime limits](https://neon.com/docs/compute/functions/reference/runtime-limits): Timeouts, slug constraints, memory, and other hard limits.

## About Neon Functions

Neon Functions put your backend code on a Neon branch, in the same region as your data. Use them for APIs, AI agents, real-time servers, and webhook handlers, with no servers to set up or manage. They're long-running, and branch with your database, so each branch runs its own copy of your functions against its own data.

What makes Neon Functions different from lambda-style serverless?

- **Next to your data.** A function runs in the same region as its branch, so queries reach Postgres with no cross-region hops.
- **Long-running.** Start responding within 15 minutes, then keep streaming while data flows, so agents and WebSocket/SSE servers aren't cut off by a short execution limit. They're still serverless: idle functions can be evicted (see [Runtime limits](https://neon.com/docs/compute/functions/reference/runtime-limits)).
- **Branch-scoped.** Functions branch with your project. Each branch runs its own deployment of them, at branch-specific URLs, against that branch's data.
- **Event-driven.** Invoke a function on a cron schedule or an object upload with [Function Triggers](https://neon.com/docs/compute/functions/triggers/overview), no external scheduler.

Functions run on Neon's own compute platform, the same infrastructure that runs your Postgres.

> Functions are currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Create your project in one of these regions to use them. Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). Functions are available on any plan, subject to [usage limits](https://neon.com/docs/compute/functions/reference/runtime-limits). See [plans and pricing](https://neon.com/docs/introduction/plans#functions) for rates.

**Important: JavaScript and TypeScript only**

Neon Functions currently run JavaScript or TypeScript on the Node.js runtime. Deploy JS/TS handlers, or code that bundles to JS for Node.js 24. Other runtimes and language targets aren't currently supported.

## Request/response, not background jobs

A function always runs in response to a request and returns a web response: JSON, an HTTP stream, an SSE feed, or a WebSocket upgrade. The request usually comes from a client (a `fetch`, a browser, an agent), but it can also come from Neon: a [Function Trigger](https://neon.com/docs/compute/functions/triggers/overview) invokes the function on a cron schedule.

Functions fit request/response work, including scheduled runs with [Function Triggers](https://neon.com/docs/compute/functions/triggers/overview). They aren't a job queue. Queued, retryable, cancellable work with its own lifecycle, like sending a welcome email after signup, still needs a queue or workflow engine to own that lifecycle. You can pair a function with a third-party queue like [Upstash QStash](https://upstash.com/docs/qstash) or [Inngest](https://www.inngest.com), which owns the queue and retries and invokes your function over HTTP. A native Neon job queue and workflow engine is a separate, upcoming offering.

Any module whose default export provides a `fetch(request)` method that returns a `Response` is a function. It embraces the web platform standards: the Fetch API's `Request` and `Response` interface, the same handler shape used by other serverless runtimes and standardized by [WinterTC](https://wintertc.org/). That can be an object with a `fetch` method:

```ts
export default {
  fetch: (request: Request) => new Response('Hello world'),
};
```

Or a bare async function:

```ts
export default async function handler(request: Request) {
  return new Response('Hello world');
}
```

A [Hono](https://hono.dev) app exports the object shape, so `export default app` works directly. Hono is the recommended framework.

## When to use Neon Functions

- **REST APIs and CRUD backends**: request in, JSON out, queries running next to Postgres. See [Quickstart](https://neon.com/docs/compute/functions/get-started).
- **AI agents**: stream tokens back across multiple model calls and tool invocations without a short execution limit cutting the run off. See [AI agents](https://neon.com/docs/compute/functions/agents).
- **Real-time apps**: WebSocket servers for chat and presence, or SSE for live updates. See [WebSockets and SSE](https://neon.com/docs/compute/functions/websockets).
- **MCP servers**: expose database-backed tools to AI clients over a single `fetch` endpoint. See the [with-mcp example](https://github.com/neondatabase/examples/tree/main/with-mcp).
- **File upload APIs**: receive a file, write it to [Object Storage](https://neon.com/docs/storage/overview), return a result.
- **Webhook handlers and bots**: receive events and query Postgres in the same region.
- **Scheduled and event-driven jobs**: run a function on a cron schedule or when a file lands in Object Storage, with no external scheduler. See [Function Triggers](https://neon.com/docs/compute/functions/triggers/overview).

## How Functions fit with your app

Functions are backend primitives, not full-stack app hosting. Host your app on Vercel, Netlify, or another frontend host; reach for a function for the long-running, stateful slice of your backend that belongs next to your data. Two common shapes:

- **Add a function to a full-stack app.** Your Next.js or TanStack Start app owns the UI, auth, and most routes. When one workload outgrows the host's short serverless limit (a WebSocket or SSE server, or a long-running agent), move only that piece onto a function and call it directly from the client. See [Authentication](https://neon.com/docs/compute/functions/authentication) for the direct-call pattern.
- **Run the backend on functions.** When the frontend is client-only (a React or TanStack SPA), the client calls functions directly: REST APIs, request/response agents, MCP servers, and anything stateful that belongs close to Postgres and Object Storage.

**Note:** Neon Functions do not support hosting websites.

## Starter templates

Each example is a complete, runnable build. Read the source on GitHub, or scaffold one with `neon bootstrap --template <id>` (it copies the files, links a Neon project, and pulls env vars). You can also browse them at [build-on-neon.vercel.app](https://build-on-neon.vercel.app/). To add one function to an existing project, use a [function template](https://neon.com/docs/compute/functions/templates) instead of bootstrap.

| Example                  | `--template`        | Source                                                                                                                  | Neon services                                   | Stack                 |
| ------------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | --------------------- |
| REST API                 | `hono`              | [with-hono](https://github.com/neondatabase/examples/tree/main/with-hono)                                               | Functions, Postgres                             | Hono, Drizzle         |
| Image-generation agent   | `ai-sdk`            | [with-ai-sdk](https://github.com/neondatabase/examples/tree/main/with-ai-sdk)                                           | Functions, Postgres, AI Gateway, Object Storage | AI SDK, Drizzle       |
| Personal-assistant agent | `mastra`            | [with-mastra](https://github.com/neondatabase/examples/tree/main/with-mastra)                                           | Functions, Postgres, AI Gateway                 | Mastra                |
| MCP server               | `mcp`               | [with-mcp](https://github.com/neondatabase/examples/tree/main/with-mcp)                                                 | Functions, Postgres                             | Hono, Drizzle         |
| WebSocket chat           | `realtime-chat`     | [with-websockets-function](https://github.com/neondatabase/examples/tree/main/with-websockets-function)                 | Functions, Postgres, Managed Better Auth        | Next.js, Hono         |
| SSE counter              | `realtime-sse`      | [with-server-sent-events-function](https://github.com/neondatabase/examples/tree/main/with-server-sent-events-function) | Functions, Postgres                             | TanStack Router, Hono |
| Discord bot              | `discord-bot-http`  | [bots/discord-bot-http](https://github.com/neondatabase/examples/tree/main/bots/discord-bot-http)                       | Functions, Postgres                             | Drizzle               |
| Telegram bot             | `telegram-bot-http` | [bots/telegram-bot-http](https://github.com/neondatabase/examples/tree/main/bots/telegram-bot-http)                     | Functions, Postgres                             | Drizzle               |
| WhatsApp bot             | `whatsapp-bot-http` | [bots/whatsapp-bot-http](https://github.com/neondatabase/examples/tree/main/bots/whatsapp-bot-http)                     | Functions, Postgres                             | Drizzle               |

--- [Document source](https://neon.com/docs/compute/functions/reference/runtime-limits.md) ---

> Summary: Hard limits for Neon Functions: lifecycle and eviction behavior, 15-minute timeouts, slug constraints, and the Node.js 24 runtime. Functions are long-running but still serverless.

# Neon Functions runtime limits

Hard constraints for Neon Functions.

Last updated: 2026-09-16

Neon Functions run on Node.js 24.

## Lifecycle

Neon Functions are long-running: you can host WebSocket servers, SSE endpoints, and agents that stream over HTTP without hitting a short execution timeout. They're still serverless. The platform shuts a function down when it's idle, with no open connections or pending `waitUntil` work, and can also evict and restart it for operational reasons. Treat eviction like a process restart: clients should reconnect when a connection drops.

When the platform stops a function, it sends `SIGINT`. If the process is still running 5 seconds later, the platform forcibly stops the function. Handle `SIGINT` with `process.on('SIGINT', ...)` to flush in-flight work within that window. You don't need to drain a `pg` pool: when the process exits, the OS closes its sockets and Neon's pooler reclaims those connections, so dropped connections are detected without extra handling.

## Timeouts

**Time to first byte: 15 minutes.** Your handler must begin returning a response within 15 minutes of receiving a request. The limit prevents runaway functions that hold resources indefinitely with no way to cancel them. In practice most handlers complete in seconds. The 15-minute limit gives agent workloads like image or video generation enough time to finish.

**Heartbeat: 15 minutes.** Active WebSocket connections and HTTP streams stay open as long as data flows. The timeout only fires when the connection goes silent. Send at least one byte every 15 minutes to keep a quiet stream alive.

**`waitUntil`: 15 minutes.** Work registered with `waitUntil` continues after the response is sent. It's for short post-response work: analytics writes, audit logs, webhook fan-outs, agent callbacks, and other short follow-up calls. It's not a background job runner. Use a dedicated system for work that needs its own lifecycle or cancellation.

```ts
import { Hono } from 'hono';
import { waitUntil } from '@neon/functions';

const app = new Hono();

app.post('/event', async (c) => {
  waitUntil(writeAnalytics(c.req.raw)); // writeAnalytics returns Promise
  return c.json({ ok: true });
});

export default app;
```

Pass `waitUntil` a promise and the invocation stays alive until the promise settles, up to the 15-minute cap. The API follows the same shape as `waitUntil` on [Vercel](https://vercel.com/docs/functions/functions-api-reference/vercel-functions-package#waituntil) and other serverless platforms. Off the Neon runtime (local dev, tests) it's a no-op: the promise still runs but isn't tracked, so the same code is safe to call in `neon dev`.

## Concurrency

Each isolate is a Node.js process. Because work runs on the event loop, a single isolate can handle several requests at once, interleaving them. Under load the platform starts more isolates on demand: a request that doesn't fit on an existing isolate goes to a freshly booted one or waits briefly in a queue.

Because each isolate is its own process and handles concurrent requests, module-scope state behaves as follows:

- **Shared within an isolate**: module-scope objects (a `pg` pool, an in-memory cache) are shared across all requests on the same isolate. Create connection pools once at module scope and reuse them.
- **Not shared across isolates**: every isolate holds its own module state. Keep `max` small on `pg` pools (for example, 5). The effective connection count is `max` × the number of live isolates. Any module-scope setup (seeding, migrations) runs once per isolate, so make it safe to repeat or guard it with a Postgres advisory lock.
- **Lost on eviction**: in-memory state disappears when an isolate is evicted. Persist anything that matters in Postgres.

To prevent abusive use, Neon also enforces an account-wide limit of **100 concurrent invocations** across all your functions. This is a default, not a hard ceiling tied to your plan; due to internal load balancing, the effective ceiling can run modestly higher. Exceeding it returns a `429 Too Many Requests` with the plain-text body `per-account concurrency limit reached` and a `Retry-After` header (in seconds). A slot frees up as soon as one of your in-flight requests completes, so a near-term retry is usually enough.

## Slug constraints

Slugs must match `^[a-z0-9]{1,20}$` and are immutable after the first deployment. See [Slugs](https://neon.com/docs/compute/functions/deploy#slugs) for the full rules.

## Runtime

| Property          | Value                                                                                                                                                                                                           |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Runtime           | Node.js 24                                                                                                                                                                                                      |
| Isolation         | microVM per isolate                                                                                                                                                                                             |
| Concurrency       | Multiple requests in flight per isolate (interleaved on the event loop), scaling out with additional isolates. See [Concurrency](https://neon.com/docs/compute/functions/reference/runtime-limits#concurrency). |
| Concurrency limit | 100 concurrent invocations per account (default). See [Concurrency](https://neon.com/docs/compute/functions/reference/runtime-limits#concurrency).                                                              |
| Memory            | 2048 MiB (fixed, not configurable)                                                                                                                                                                              |

## Environment variables

See [Environment variables](https://neon.com/docs/compute/functions/environment-variables#constraints) for limits on variable count and total size.

--- [Document source](https://neon.com/docs/compute/functions/registry.md) ---

> Summary: How to contribute a template to the Neon Function Registry: module format, template.json and registry.json fields, layouts, categories, limits, local testing with NEON_FUNCTION_REGISTRY_DIR, and the review checklist.

# Contribute a function template

Share a reusable Neon Function that anyone can add to their project with neon functions new.

Last updated: 2026-11-07

The Function Registry is the public catalog behind [`neon functions new`](https://neon.com/docs/cli/functions#new). Each template is a folder in [`registry/`](https://github.com/neondatabase/examples/tree/main/registry) in `neondatabase/examples`. To add one, you open a pull request with the template folder and an index entry. Neon reviews it, and after it merges to `main`, the template shows up in the CLI and on [neon.com/functions/templates](https://neon.com/functions/templates) within about an hour. You don't publish anything yourself.

Merged files get copied straight into people's projects, so every template goes through review before it lands. To use a template rather than publish one, see [Use function templates](https://neon.com/docs/compute/functions/templates).

## How a template is laid out

```text
registry/
├── registry.json            # the index the CLI reads first
├── schemas/
│   ├── registry.schema.json
│   └── template.schema.json
└── <template-id>/
    ├── template.json        # metadata, no inline source
    ├── README.md            # setup and usage instructions
    └── functions/
        └── <operation>.ts   # one module per operation
```

The CLI lists templates from `registry.json`. Installing one downloads the `neondatabase/examples` tarball from GitHub and extracts only `registry/<id>/`. Every path is relative and must stay inside the registry: no absolute paths, no `..`, no backslashes, and no symlinks that lead outside it.

## Write the modules

Each module default-exports a fetch handler:

```ts filename="functions/send-email.ts"
export default {
  async fetch(request: Request): Promise<Response> {
    return Response.json({ ok: true });
  },
};
```

- Read configuration from `process.env`, and declare every variable you read in `environment`.
- Don't do network work at import time.
- Don't import a sibling module from the template folder. The CLI copies each module on its own.

## Write template.json

```json filename="sendgrid/template.json"
{
  "$schema": "https://neon.com/functions/registry/schemas/template.schema.json",
  "id": "sendgrid",
  "provider": "SendGrid",
  "title": "Send email with SendGrid",
  "description": "Send transactional email through the SendGrid v3 API.",
  "categories": ["email"],
  "layout": "separate",
  "dependencies": ["@sendgrid/mail@8.1.3"],
  "environment": [
    { "name": "SENDGRID_API_KEY", "description": "API key from the SendGrid dashboard." }
  ],
  "operations": [
    {
      "id": "send-email",
      "title": "Send an email",
      "description": "Send a single transactional email.",
      "source": "functions/send-email.ts",
      "slug": "sendemail",
      "recommended": true
    }
  ]
}
```

Keep `$schema` set to the neon.com URL for editor completion. The CLI's parser has the final say, so a template that passes the schema still has to pass the [local test](https://neon.com/docs/compute/functions/registry#test-your-template-locally).

## Add the index entry

Append the template to `templates` in `registry.json`:

```json filename="registry.json"
{
  "id": "sendgrid",
  "provider": "SendGrid",
  "title": "Send email with SendGrid",
  "description": "Send transactional email through the SendGrid v3 API.",
  "path": "sendgrid/template.json",
  "categories": ["community"],
  "logo": "https://example.com/sendgrid.svg",
  "website": "https://example.com/"
}
```

`id`, `title`, `description`, and `provider` should match `template.json`. `categories` differs: the entry holds the source label and `template.json` holds the topical labels. An entry that fails validation is dropped from the listing without an error, so always check that your template shows up.

## Test it and open a pull request

Run the [local test](https://neon.com/docs/compute/functions/registry#test-your-template-locally), go through the [review checklist](https://neon.com/docs/compute/functions/registry#review-checklist), then open a pull request on [`neondatabase/examples`](https://github.com/neondatabase/examples) with one template folder and one index entry.

## template.json fields

| Field                  | Required | Rule                                                                                                                                                                      |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | yes      | Lowercase letters, digits, and hyphens, starting with a letter or digit. Must match the index entry. Use it as the folder name too.                                       |
| `title`, `description` | yes      | Non-empty.                                                                                                                                                                |
| `layout`               | yes      | `router` or `separate`. See [Layouts](https://neon.com/docs/compute/functions/registry#layouts).                                                                          |
| `categories`           | no       | Topical listing labels, such as `ai` or `email`. The source label goes in the index entry. See [Categories](https://neon.com/docs/compute/functions/registry#categories). |
| `provider`             | no       | Shown in listings. Defaults to `Neon`.                                                                                                                                    |
| `dependencies`         | no       | Exact `name@version` pins, scoped packages included. No ranges and no `latest`, so users install the version a reviewer approved.                                         |
| `environment`          | no       | `UPPER_SNAKE` names, each with a description. The CLI declares them in `neon.ts` and adds them to `.env.example`, using the description as the comment.                   |
| `operations`           | no       | 1 to 40 entries. Leave them out for a single-module template.                                                                                                             |

Each operation takes these fields:

| Field                  | Rule                                                                                                                          |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | Same rule as the template `id`, unique within the template. It names the scaffolded file (`<id>.ts`).                         |
| `title`, `description` | Non-empty.                                                                                                                    |
| `source`               | Path to the module, relative to `template.json`. Unique.                                                                      |
| `recommended`          | Boolean. At least one operation must be `true`. The recommended set is what `-y` and non-interactive runs scaffold.           |
| `route`                | `router` layout only. A unique URL path starting with `/`. Defaults to `/<id>`.                                               |
| `slug`                 | `separate` layout only, and required there. 1 to 20 lowercase letters and digits, no hyphens, unique. It's the function slug. |

## Index entry fields

The entry in `registry.json` repeats `id`, `title`, `description`, and `provider`, and adds:

| Field        | Required | Rule                                                                                                                                       |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `path`       | yes      | Path to the template's `template.json`, relative to `registry.json`.                                                                       |
| `categories` | yes      | The source label: `first-party`, `partner`, or `community`. See [Categories](https://neon.com/docs/compute/functions/registry#categories). |
| `logo`       | no       | Absolute `https://` URL. Display only. The CLI never fetches it.                                                                           |
| `website`    | no       | Absolute `https://` URL to the provider's site. Display only. The CLI never fetches it.                                                    |

## Layouts

A `router` template scaffolds one Neon Function. The CLI copies the selected modules and generates an `index.ts` that dispatches each request to an operation by its `route`. Any other path returns a 404 that lists the valid routes.

A `separate` template scaffolds one Neon Function per selected operation, each under its own `slug`. Use it when operations should scale, fail, or receive secrets independently.

If you leave out `operations`, the template ships exactly one module at `functions/index.ts`. Set `layout` to `router`.

## Categories

Categories drive filtering on [neon.com/functions/templates](https://neon.com/functions/templates), which combines the labels from both files. They're lowercase hyphenated strings, not a fixed list. The CLI ignores them.

The index entry in `registry.json` gets one source label that says who wrote the template:

| Category      | Use it for                                                                                   |
| ------------- | -------------------------------------------------------------------------------------------- |
| `first-party` | Templates written and maintained by Neon, even when they wrap a third-party SDK.             |
| `partner`     | Templates written by a company Neon works with closely, such as Mastra, TanStack, or WorkOS. |
| `community`   | Templates written by anyone else.                                                            |

Add at least one topical label to `template.json`, even though the schema doesn't require it. Reuse one from this table where it fits:

| Category            | Use it for                                        |
| ------------------- | ------------------------------------------------- |
| `ai`                | Templates that use AI Gateway or an AI framework. |
| `ai-infrastructure` | Third-party AI data or tooling providers.         |
| `api`               | HTTP APIs, with or without Postgres.              |
| `auth`              | Authentication or access control.                 |
| `bots`              | Chat or messaging bots.                           |
| `mcp`               | Model Context Protocol servers.                   |

To add a new topical category, use it in your `template.json` and add a row to the categories table in the registry [README](https://github.com/neondatabase/examples/blob/main/registry/README.md).

## Limits

| Limit                                | Value          |
| ------------------------------------ | -------------- |
| Entries in `registry.json`           | 500            |
| `registry.json` or a `template.json` | 1 MB           |
| One module                           | 256 KB         |
| All modules of one template          | 2 MB           |
| Path length                          | 255 characters |

## Test your template locally

Point the CLI at your checkout with `NEON_FUNCTION_REGISTRY_DIR`. In this mode, the CLI reads the files in that folder and doesn't download the GitHub tarball.

```bash
export NEON_FUNCTION_REGISTRY_DIR=/path/to/examples/registry

# Your template should be listed. If it isn't, its index entry failed validation.
neon functions templates list

# Loads template.json and every module it references, then scaffolds into a scratch directory.
neon functions new <id> -y --dir /tmp/<id> --no-add-to-config --no-install
```

The last command prints a `neon dev --source …` line for each function it created. Run each one with [`neon dev`](https://neon.com/docs/cli/dev) and call every route or function once.

Registry commands need Neon CLI 8.11.0 or later.

## Review checklist

- The template is listed, and `neon functions new <id> -y` succeeds against a local checkout.
- Every operation was run once with `neon dev`.
- Dependencies are pinned and come from the provider's official SDK.
- Every `process.env` read is declared in `environment`, and no secret or default key is hard-coded.
- There are no network calls at import time and no telemetry the user didn't ask for.
- The recommended operations are the ones most users want on day one.
- `README.md` explains how to use the template: the Neon services to enable (for example, `neon config add ai-gateway`), environment variables to set, whether to deploy before running `neon dev`, and an example request. The `Next:` list from `neon functions new` doesn't cover services, so users rely on the README for them.

## Where the catalog is served

The CLI reads the catalog from neon.com, which proxies `registry/` on the `main` branch of `neondatabase/examples`. If neon.com is unreachable, the CLI falls back to [the same files on GitHub](https://raw.githubusercontent.com/neondatabase/examples/main/registry/registry.json).

| File            | URL                                                                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Catalog index   | [https://neon.com/functions/registry/registry.json](https://neon.com/functions/registry/registry.json)                               |
| Catalog schema  | [https://neon.com/functions/registry/schemas/registry.schema.json](https://neon.com/functions/registry/schemas/registry.schema.json) |
| Template schema | [https://neon.com/functions/registry/schemas/template.schema.json](https://neon.com/functions/registry/schemas/template.schema.json) |

The CLI's parser and these schemas define the format together. If your template needs a field the parser doesn't know yet, see "Changing the schema" in [CONTRIBUTING.md](https://github.com/neondatabase/examples/blob/main/registry/CONTRIBUTING.md) before you use it.

--- [Document source](https://neon.com/docs/compute/functions/telegram-bot.md) ---

> Summary: Host a Telegram bot on Neon Functions. Receive webhook updates, run bot commands, verify the webhook secret token, and store data in Postgres on the same branch.

# How to host a Telegram bot on Neon Functions

Receive Telegram messages, run bot commands and store data in Postgres

Last updated: 2026-10-31

Telegram can send bot updates to an HTTPS webhook. A [Neon Function](https://neon.com/docs/compute/functions/overview) can receive those updates, run bot commands and query Postgres from the same branch.

The template verifies the secret token on each incoming update, handles messages and processes inline keyboard callbacks. See Telegram's [Bot API](https://core.telegram.org/bots/api) when you add other update types.

**Note: Webhook delivery only**

This guide uses Telegram webhooks. It doesn't run a polling process with `getUpdates`. Telegram disables `getUpdates` while a webhook is active.

## Prerequisites

- A Neon project in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). See [Get started with Neon Functions](https://neon.com/docs/compute/functions/get-started).
- The latest [Neon CLI](https://neon.com/docs/cli), installed and authenticated. Upgrade with `npm install -g neon@latest`, then see [CLI login](https://neon.com/docs/cli/login).
- Node.js 24 (`node -v`). Deployed functions run on `nodejs24`, so 24 locally is the closest match. Node.js 20+ works.
- A Telegram account.

The template uses npm. Its scripts load Telegram values from `.env.local`, the same convention as Next.js and `vercel env pull`.

## Create a Telegram bot

Open [BotFather](https://t.me/BotFather) in Telegram and send `/newbot`. BotFather asks for a display name and username. Usernames must be 5 to 32 characters and end in `bot`. They can contain Latin letters, numbers and underscores. For example, use `example_neon_bot`. You can't change the username later.

After you choose a username, BotFather sends you an authentication token and a link to the bot. Save both for later.

**Warning:** Treat the bot token like a password. Anyone who has it can control your bot. Never commit it or paste it into screenshots, tickets or chat. If it leaks, use `/token` in BotFather to replace it.

For more BotFather options, see [Creating a new bot](https://core.telegram.org/bots/features#creating-a-new-bot).

## Scaffold the project

`neon bootstrap` copies the Telegram example into a new directory and prompts you to install dependencies and set up the project. Accept the prompts. Pass `--no-link` to skip linking for now; you'll [link](https://neon.com/docs/cli/link) in the next step, after creating `.env.local`, so Neon writes its variables straight into that file. The template ID is `telegram-bot-http`:

```bash
neon bootstrap my-telegram-bot --template telegram-bot-http --no-link
cd my-telegram-bot
```

See [`neon bootstrap`](https://neon.com/docs/cli/bootstrap) for flags. Later commands in this guide assume you're in that directory.

To start from the source instead, copy [bots/telegram-bot-http](https://github.com/neondatabase/examples/tree/main/bots/telegram-bot-http) from the [examples](https://github.com/neondatabase/examples) repo, `cd` into it, then install dependencies and run `neon link`.

`neon.ts` declares the `telegram` function and passes the bot token and webhook secret to it:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    telegram: {
      name: "Telegram webhook",
      source: "./functions/telegram.ts",
      env: {
        TELEGRAM_BOT_TOKEN: process.env.TELEGRAM_BOT_TOKEN!,
        TELEGRAM_WEBHOOK_SECRET: process.env.TELEGRAM_WEBHOOK_SECRET!,
      },
      dev: {
        port: 8787,
      },
    },
  },
});
```

The key `telegram` is the function slug. It's permanent after the first deploy and appears in CLI commands and the invocation URL. See the [neon.ts reference](https://neon.com/docs/reference/neon-ts).

This walkthrough deploys the function before connecting Telegram. Telegram requires a public HTTPS webhook, so it can't reach `localhost` unless you use a tunnel.

## Add Telegram secrets

Bootstrap scaffolds a `.env.example` but no `.env.local`. Install dependencies, copy the example, then link. `neon link` loads `neon.ts` to pull the branch's variables, so the packages must be installed first:

```bash
npm install
cp .env.example .env.local
neon link
```

Linking merges `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `NEON_BRANCH`, `NEON_BRANCH_ID`, and `NEON_FUNCTION_HOST_SUFFIX` into `.env.local`, leaving the Telegram keys untouched.

Generate a webhook secret:

```bash
openssl rand -hex 32
```

Uncomment and set `TELEGRAM_BOT_TOKEN` (the BotFather token) and `TELEGRAM_WEBHOOK_SECRET` (the value you just generated). Leave `TELEGRAM_WEBHOOK_URL` empty until you deploy:

```env filename=".env.local"
# Required. Add real values before deploying; a missing key throws at deploy, an empty one uploads "".
# TELEGRAM_BOT_TOKEN=
# TELEGRAM_WEBHOOK_SECRET=

# Local only, used by the set:webhook script. Set after you deploy.
TELEGRAM_WEBHOOK_URL=

# Written into `.env.local` by `neon link`.
NEON_BRANCH=
DATABASE_URL=
DATABASE_URL_UNPOOLED=
NEON_BRANCH_ID=
NEON_FUNCTION_HOST_SUFFIX=
```

The webhook secret can contain 1 to 256 characters from `A-Z`, `a-z`, `0-9`, `_` and `-`. The `openssl` command above produces a valid value.

Leave the pulled `NEON_*` and `DATABASE_URL*` values as written. See [Environment variables](https://neon.com/docs/compute/functions/environment-variables).

Only the local webhook setup script reads `TELEGRAM_WEBHOOK_URL`. Neon doesn't pass it to the function.

## Deploy the function

The `deploy` script runs `neon deploy --env .env.local`, which evaluates `neon.ts` with your Telegram secrets in `process.env`:

```bash
npm run deploy
```

The CLI applies the `neon.ts` policy, bundles the function and waits for the deployment to finish. You'll see `Applied changes` and a **Function URLs** list. If the deployment fails, check [function logs](https://neon.com/docs/compute/functions/logs) and [Deploy and manage functions](https://neon.com/docs/compute/functions/deploy).

## Apply the database schema

```bash
npm run db:push
```

`neon link` wrote `DATABASE_URL` into `.env.local`, so you can apply the schema any time after linking. `/ping` works without the tables; `/name` and `/profile` need them.

## Set the webhook

Telegram sends updates to `/api/webhook`. Your webhook URL is the `telegram` function's URL with the path `/api/webhook`. `npm run deploy` prints it in the **Function URLs** list, and `neon functions get telegram` shows it in its `URL` field. Set `TELEGRAM_WEBHOOK_URL` to it:

```env filename=".env.local"
TELEGRAM_WEBHOOK_URL=https://br-cool-darkness-123456-telegram.compute.c-2.us-east-2.aws.neon.tech/api/webhook
```

Register that URL and your webhook secret with Telegram:

```bash
npm run set:webhook
```

The script calls Telegram's [`setWebhook`](https://core.telegram.org/bots/api#setwebhook) method with the URL, webhook secret and the `message` and `callback_query` update types. Telegram returns `true` when it accepts the webhook.

The function URL must use HTTPS. Telegram includes your secret in the `X-Telegram-Bot-Api-Secret-Token` header on every update.

If you change the webhook secret, run `npm run deploy` first so the function has the new value. Then run `npm run set:webhook` again so Telegram sends the same value.

Open the webhook URL in a browser to check that the function is available. A GET request returns:

```json
{
  "ok": true,
  "service": "telegram-webhook",
  "webhookPath": "/api/webhook",
  "webhookUrl": "https://br-cool-darkness-123456-telegram.compute.c-2.us-east-2.aws.neon.tech/api/webhook"
}
```

`ok: true` confirms only that the function is reachable at that URL. `webhookUrl` echoes the public URL you requested; registering it with Telegram is still a separate step (`npm run set:webhook`). This GET doesn't verify the webhook secret or confirm webhook registration. A `true` result from `npm run set:webhook` confirms registration. Sending `/ping` verifies end-to-end delivery.

## Register bot commands

Register the command menu with Telegram:

```bash
npm run register:commands
```

The script calls Telegram's `setMyCommands` method with `/ping`, `/info`, `/help`, `/buttons`, `/name` and `/profile`. On success it prints `true`.

Run this command again after you change the command list.

## Try /ping

Open the bot link that BotFather gave you. If Telegram shows a **Start** button, click it. Then send `/ping`. The bot replies with `Pong` and an estimated webhook latency.

The template doesn't register a `/start` command, so tapping **Start** may return `Unknown command`. Send `/ping` instead.

If the bot doesn't reply:

- Confirm that `npm run set:webhook` returned `true`.
- Check that `TELEGRAM_WEBHOOK_URL` ends with `/api/webhook`.
- Check that `TELEGRAM_WEBHOOK_SECRET` matches the value used in the latest deployment.
- Redeploy after changing `TELEGRAM_BOT_TOKEN` or `TELEGRAM_WEBHOOK_SECRET`.
- Check [function logs](https://neon.com/docs/compute/functions/logs) for an invalid webhook secret, invalid update payload or Telegram API error.

Telegram retries webhook updates when your endpoint doesn't return a `2xx` response.

The template doesn't deduplicate Telegram `update_id` values. If you add a command with side effects, make it safe to run more than once.

## How it works

`functions/telegram.ts` handles GET and POST requests. GET returns the webhook URL. POST checks the secret header, validates the Telegram update and dispatches messages or button callbacks.

**Important: Verify the webhook secret**

Check `X-Telegram-Bot-Api-Secret-Token` before processing an update. The template compares it with `TELEGRAM_WEBHOOK_SECRET` using Node.js `timingSafeEqual`.

The POST path verifies the secret before parsing the update:

```ts filename="functions/telegram.ts"
  const isVerified = verifyTelegramRequest(
    getTelegramWebhookSecret(),
    request.headers.get("x-telegram-bot-api-secret-token"),
  );

  if (!isVerified) {
    return jsonResponse({ error: "invalid webhook secret" }, { status: 401 });
  }

  let payloadBody: unknown;

  try {
    payloadBody = await request.json();
  } catch {
    return jsonResponse({ error: "invalid json" }, { status: 400 });
  }
```

It handles callback queries, tracks recognized commands without delaying replies and sends `Unknown command. Try /help.` for unsupported commands.

<details>

<summary>View full code: </summary>

```typescript
import { TELEGRAM_WEBHOOK_PATH } from "../src/constants/telegram.js";
import { getTelegramBotToken, getTelegramWebhookSecret } from "../src/env.js";
import { telegramUpdateSchema } from "../src/schemas/telegram.js";
import { commandHandlers, trackTelegramCommandRun } from "../src/utils/telegramCommands.js";
import {
  createButtonTestClickMessage,
  parseButtonTestCallbackData,
} from "../src/utils/generalComponents.js";
import { jsonResponse } from "../src/utils/jsonResponse.js";
import {
  answerTelegramCallbackQuery,
  editTelegramMessageText,
  sendTelegramMessage,
} from "../src/utils/telegramApi.js";
import { createErrorMessage } from "../src/utils/telegramResponses.js";
import { parseTelegramCommand } from "../src/utils/telegramText.js";
import { verifyTelegramRequest } from "../src/utils/verifyTelegramRequest.js";

const handleCallbackQuery = async (
  botToken: string,
  update: Awaited<ReturnType<typeof telegramUpdateSchema.parse>>,
): Promise<Response> => {
  const callbackQuery = update.callback_query;

  if (!callbackQuery) {
    return jsonResponse({ ok: true });
  }

  const action = callbackQuery.data ? parseButtonTestCallbackData(callbackQuery.data) : undefined;

  if (!action) {
    await answerTelegramCallbackQuery({
      botToken,
      callbackQueryId: callbackQuery.id,
      text: "That button is not handled by this bot.",
    });

    return jsonResponse({ ok: true });
  }

  if (!callbackQuery.message) {
    await answerTelegramCallbackQuery({
      botToken,
      callbackQueryId: callbackQuery.id,
      text: "The original message is not available.",
    });

    return jsonResponse({ ok: true });
  }

  const responseMessage = createButtonTestClickMessage(callbackQuery.message.chat.id, action);

  await Promise.all([
    answerTelegramCallbackQuery({ botToken, callbackQueryId: callbackQuery.id }),
    editTelegramMessageText({
      botToken,
      chatId: responseMessage.chatId,
      messageId: callbackQuery.message.message_id,
      replyMarkup: responseMessage.replyMarkup,
      text: responseMessage.text,
    }),
  ]);

  return jsonResponse({ ok: true });
};

export default async function handler(request: Request): Promise<Response> {
  const url = new URL(request.url);

  switch (request.method) {
    case "GET":
      return jsonResponse({
        ok: true,
        service: "telegram-webhook",
        webhookPath: TELEGRAM_WEBHOOK_PATH,
        webhookUrl: `${url.origin}${TELEGRAM_WEBHOOK_PATH}`,
      });
    case "POST":
      break;
    default:
      return jsonResponse({ error: "method not allowed" }, { status: 405 });
  }

  const isVerified = verifyTelegramRequest(
    getTelegramWebhookSecret(),
    request.headers.get("x-telegram-bot-api-secret-token"),
  );

  if (!isVerified) {
    return jsonResponse({ error: "invalid webhook secret" }, { status: 401 });
  }

  let payloadBody: unknown;

  try {
    payloadBody = await request.json();
  } catch {
    return jsonResponse({ error: "invalid json" }, { status: 400 });
  }

  const parsedPayload = telegramUpdateSchema.safeParse(payloadBody);

  if (!parsedPayload.success) {
    return jsonResponse({ error: "invalid telegram update payload" }, { status: 400 });
  }

  const update = parsedPayload.data;
  const botToken = getTelegramBotToken();

  if (update.callback_query) {
    return handleCallbackQuery(botToken, update);
  }

  const message = update.message;
  const command = parseTelegramCommand(message?.text);

  if (!message || !command) {
    return jsonResponse({ ok: true });
  }

  const commandHandler = commandHandlers[command.name];

  if (commandHandler) {
    void trackTelegramCommandRun(message, command.name);

    const responseMessage = await commandHandler({
      args: command.args,
      botToken,
      command: command.name,
      message,
      request,
      update,
      url,
    });

    await sendTelegramMessage({ botToken, ...responseMessage });

    return jsonResponse({ ok: true });
  }

  await sendTelegramMessage({
    botToken,
    ...createErrorMessage(message.chat.id, "Unknown command. Try /help."),
  });

  return jsonResponse({ ok: true });
}

```

</details>

View it on [GitHub](https://github.com/neondatabase/examples/blob/main/bots/telegram-bot-http/functions/telegram.ts).

## Commands

- `/ping`: replies with Pong and an estimated webhook latency.
- `/info`: Node.js version, platform, request method, function URL and Neon branch.
- `/help`: lists the template's commands.
- `/buttons`: inline keyboard with refresh, echo, time and confirm callbacks.
- `/name <your name>`: stores a display name. `/name` without an argument shows the stored name.
- `/profile`: stored name, total command count and per-command usage.

The template stores Telegram user IDs, display names and usage counts in the `profiles` and `command_usage` tables. Usage tracking is best-effort and doesn't block replies. If the database misses a 2.5-second deadline, the bot replies "Warming up"; run the command again once the branch is warm.

## Related templates

- [Telegram AI chat bot](https://neon.com/functions/templates/telegram-bot): a [function template](https://neon.com/docs/compute/functions/templates) that adds AI Gateway chat to a Telegram bot.
- [Discord HTTP bot](https://github.com/neondatabase/examples/tree/main/bots/discord-bot-http)
- [WhatsApp HTTP bot](https://github.com/neondatabase/examples/tree/main/bots/whatsapp-bot-http)

## Example

Create a copy of the example with the Neon CLI:

```bash
neon bootstrap my-telegram-bot --template telegram-bot-http
cd my-telegram-bot
```

You can find the example in [`bots/telegram-bot-http`](https://github.com/neondatabase/examples/tree/main/bots/telegram-bot-http).

--- [Document source](https://neon.com/docs/compute/functions/templates.md) ---

> Summary: How to find and use Neon Function Registry templates: browse the catalog at neon.com/functions/templates or with neon functions templates list, add a template with neon functions new, enable the services it needs, run it locally with neon dev, and deploy it. Also explains how registry templates differ from neon bootstrap starter apps.

# Use function templates

Add a ready-made Neon Function to your project with one command, then run and deploy it.

Function templates are ready-made [Neon Functions](https://neon.com/docs/compute/functions/overview) you can add to your project instead of writing one from scratch. There are templates for REST APIs, MCP servers, authenticated APIs, AI agents, image generation and analysis, and chat bots. Some are built by Neon and some by partners such as Mastra, TanStack, and Telegram.

A template adds one function to the project in your current directory. The source lands in your repo, so you can read it, change it, and deploy it like any function you wrote yourself.

## Browse the templates

Browse the full catalog at [neon.com/functions/templates](https://neon.com/functions/templates). You can search and filter by category. Each template has a page with its install command and a link to its source on GitHub.

- [Browse function templates](https://neon.com/functions/templates): Search and filter every template in the Function Registry

You can also list them from the terminal:

```bash
neon functions templates list
```

```text filename="Output"
ID                 Title                                                Provider     Description
basic              Basic function                                       Neon         A minimal Neon Function with a JSON response.
mcp-postgres       MCP server backed by Postgres                        Neon         A Hono MCP server exposing create, list, update, and delete tools backed by a Postgres database.
rest-api-postgres  REST API with Hono and Postgres                      Neon         A CRUD REST API on Neon Functions with Hono, backed by Lakebase Postgres.
image-generation   AI image generation API                              Neon         Generate an image with AI Gateway, store it in Object Storage, and return a presigned URL.
...
```

The `ID` column is what you pass to `neon functions new`.

## Before you start

Templates need the [Neon CLI](https://neon.com/docs/cli/install) 8.11.0 or later. To deploy one, you also need a Neon project and a directory [linked](https://neon.com/docs/cli/link) to it.

Read the template's README before you install it. Open **Template source** on the template's page, or browse [`registry/`](https://github.com/neondatabase/examples/tree/main/registry) in `neondatabase/examples`. The README lists what the template needs, such as other Neon services or third-party API keys, and how to call the function once it's running.

## Add the template

From your project directory, run `neon functions new` with the template ID:

```bash
neon functions new image-generation
```

The command copies the template into `functions/<slug>/` and declares the function in [`neon.ts`](https://neon.com/docs/reference/neon-ts), creating the file if needed. The slug is the template ID with hyphens removed, so this example creates `functions/imagegeneration/`. Pass `--slug` to choose a different one.

Leave out the ID to pick a template interactively. If a template has several operations, the command asks which ones to include. Pass `-y` to take the recommended ones and install dependencies without prompting. See [`neon functions new`](https://neon.com/docs/cli/functions#new) for all options.

The command ends with a `Next:` list of the exact commands for that template:

```text filename="Output"
Next:
  npm install @neon/config @neon/env
  npm install -E @aws-sdk/client-s3@3.1156.0 @aws-sdk/s3-request-presigner@3.1156.0 @neon/ai-sdk-provider@1.1.0 ai@7.0.150
  neon dev
  neon config apply
```

Run the `npm install` lines. Dependencies are pinned to the versions Neon reviewed.

## Enable the services the template uses

The `Next:` list doesn't enable other Neon services for you. If the template uses [AI Gateway](https://neon.com/docs/ai-gateway/overview), [Object Storage](https://neon.com/docs/storage/overview), or [Managed Better Auth](https://neon.com/docs/auth/overview), declare them in `neon.ts`. The template's README says which ones it needs. For `image-generation`, that's AI Gateway and a private bucket named `images`:

```bash
neon config add ai-gateway
neon config add bucket images
```

See [`neon config add`](https://neon.com/docs/cli/config#add) for the other services you can add.

If the template reads its own environment variables, such as an API key for a third-party service, `neon functions new` declares them in `neon.ts` and adds their names to `.env.example`. Set the values in `.env.local`.

## Deploy to provision services

If you added services in the previous step, deploy once so Neon provisions them on your branch:

```bash
neon deploy
```

After deploying, Neon writes the new services' credentials, such as the `NEON_AI_GATEWAY_*` and `AWS_*` variables, to your local env file. `neon dev` needs them to run the function. If the template has no extra services or variables, you can skip this step and run it locally first.

If you set your own variables in `.env.local`, deploy with `neon deploy --env .env.local`. Without `--env`, the deploy fails because those variables are undefined.

## Run it locally

```bash
neon dev
```

`neon dev` serves the function at `http://localhost:8787` by default and loads `.env` and `.env.local`. Call it with the request shown in the template's README. For `image-generation`:

```bash
curl -X POST http://localhost:8787/ \
  -H "content-type: application/json" \
  -d '{"prompt":"An astronaut drinking coffee in a neon-lit cafe"}'
```

## Deploy

When it works locally, deploy it to your branch:

```bash
neon deploy
```

`neon config apply` does the same thing, which is why the `Next:` list may end with it. To find the function's URL and manage it after deploy, see [Deploy and manage functions](https://neon.com/docs/compute/functions/deploy).

## Customize a template

The template's files are now part of your project, so edit them like any other code. The CLI doesn't track changes or update installed templates.

Many templates don't authenticate requests, so anyone with the function URL can call them. This matters for templates that call paid services like AI Gateway. Check the README, and add your own check before you share the URL. See [Authentication](https://neon.com/docs/compute/functions/authentication).

## Function templates vs. starter apps

Neon has two kinds of templates:

|              | Function templates                                                   | Starter apps                                                                                                                 |
| ------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| What you get | One function, added to your existing project                         | A complete app in a new directory                                                                                            |
| Command      | `neon functions new <id>`                                            | [`neon bootstrap --template <id>`](https://neon.com/docs/cli/bootstrap)                                                      |
| Browse       | [neon.com/functions/templates](https://neon.com/functions/templates) | [Starter templates](https://neon.com/docs/compute/functions/overview#starter-templates) or `neon bootstrap --list-templates` |

Use a function template to add a capability to a project you already have. Use a starter app when you're starting from an empty directory.

## Contribute a template

Anyone can propose a template by opening a pull request on `neondatabase/examples`. Neon reviews each one before it's published. See [Contribute a function template](https://neon.com/docs/compute/functions/registry).

--- [Document source](https://neon.com/docs/compute/functions/triggers/object-storage.md) ---

> Summary: Create and manage storage_object_created Function Triggers from the Neon Console, the CLI, the Neon API, or neon.ts: a Hono handler for the upload event, the bucket and prefix filter, what your function receives, and how to confirm a run in the logs.

# Trigger on an object upload

Run a function when an object is created in a bucket.

Last updated: 2026-11-05

A `storage_object_created` trigger tells Neon to invoke a deployed [Neon Function](https://neon.com/docs/compute/functions/overview) when an object is created in an [Object Storage](https://neon.com/docs/storage/overview) bucket. Optionally scope it to a key `prefix`, so only uploads under that path fire the function. There's no external event wiring and no compute kept running to watch the bucket.

For what a trigger is and how it behaves across branches, see the [overview](https://neon.com/docs/compute/functions/triggers/overview). The scheduled trigger type is covered in [Schedule a function](https://neon.com/docs/compute/functions/triggers/schedule); this page covers the object-created type. You can manage object-created triggers from the Neon Console, the [`neon triggers`](https://neon.com/docs/cli/triggers) CLI, the Neon API, or declaratively in [`neon.ts`](https://neon.com/docs/reference/neon-ts#triggers); the steps below show each.

Because the function is long-running, it can do real work on each upload, whatever the file size.

![A new object fires the long-running function, which can generate a thumbnail, parse a CSV, extract and index text, or record metadata in Postgres](https://neon.com/docs/compute/functions/triggers/object-upload-use-cases.png)

## Before you begin

You need a [deployed function](https://neon.com/docs/compute/functions/get-started) and its [slug](https://neon.com/docs/compute/functions/deploy#slugs), and a [bucket](https://neon.com/docs/storage/buckets) on the branch. The API also needs a Neon [API key](https://neon.com/docs/manage/api-keys); the Console doesn't. If you deployed with the CLI, [`neon link`](https://neon.com/docs/cli/link) already wrote your project and branch to a `.neon` file; you can also find the IDs in the [Neon Console](https://console.neon.tech).

The API examples use these variables:

```bash
export API="https://console.neon.tech/api/v2"
export NEON_API_KEY="<your-api-key>"
export PROJECT_ID="<your-project-id>"
export BRANCH_ID="<your-branch-id>"
```

To build this with an AI agent, start from this prompt and fill in the task:

```text filename="AI assistant prompt"
Create a Neon Function that <task>, then trigger it on new uploads with a Function Trigger.
Docs: https://neon.com/docs/compute/functions/triggers/object-storage.md

- Add one unauthenticated POST route (trigger invocations arrive without credentials). Read `data.bucket_name` and `data.object_key` from the JSON body; keep the handler idempotent.
- If the task uses Postgres, connect with the injected DATABASE_URL through a module-scope `pg` Pool with `attachDatabasePool` from `@neon/functions`, not `@neondatabase/serverless`.
- Deploy it, then create a `storage_object_created` trigger via the Console, CLI, API, or `neon.ts` with the bucket name, optionally scoped to a key prefix. Upload an object to confirm a run in the logs.
- The route and trigger both default to `/`; set `function_path` on both if you want a different path.
```

## Write a handler for the upload event

An object-created invocation is a `POST` whose JSON body carries the occurrence: `data.bucket_name`, `data.object_key`, the `trigger` that fired, and an `invocation_id`. Neon delivers it to the function's public URL, so the route sits outside your auth middleware. You can confirm the call came from Neon with the `X-Neon-Trigger-Invocation-Id` header (see [Confirming a request came from Neon](https://neon.com/docs/compute/functions/triggers/overview#confirming-a-request-came-from-neon)); keep the handler idempotent and guard destructive actions regardless.

This [Hono](https://hono.dev) function records each uploaded object. From here you'd typically fetch and process the object, enqueue a job, or notify another service:

```ts
import { Hono } from 'hono';
import { attachDatabasePool } from '@neon/functions';
import { Pool } from 'pg';

// Create the pool once at module scope so it's reused across invocations.
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
attachDatabasePool(pool);
const app = new Hono();

// This route is public. Neon strips client-set X-Neon-* headers, so the presence of
// X-Neon-Trigger-Invocation-Id attests the call came from Neon's trigger system.
app.post('/', async (c) => {
  if (!c.req.header('x-neon-trigger-invocation-id')) {
    return c.json({ error: 'not a trigger call' }, 401);
  }

  const { data } = await c.req.json<{ data: { bucket_name: string; object_key: string } }>();
  const { bucket_name: bucket, object_key: key } = data;

  await pool.query(
    `INSERT INTO uploads (bucket, object_key)
     VALUES ($1, $2)
     ON CONFLICT (bucket, object_key) DO NOTHING`,
    [bucket, key]
  );

  console.log(`object created: ${bucket}/${key}`);
  return c.json({ ok: true, bucket, object_key: key });
});

export default app;
```

`DATABASE_URL` is injected for you. See [Environment variables](https://neon.com/docs/compute/functions/environment-variables). The handler connects through a module-scope `pg` pool, as in [Use a connection pool](https://neon.com/docs/compute/functions/get-started#connect-to-postgres). The `ON CONFLICT (bucket, object_key) DO NOTHING` clause makes a redelivered occurrence a no-op.

Create the table it writes to, in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or with [`neon psql`](https://neon.com/docs/cli/psql):

```sql
CREATE TABLE IF NOT EXISTS uploads (
  bucket      text,
  object_key  text,
  seen_at     timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (bucket, object_key)
);
```

Then deploy the function:

```bash
neon functions deploy onupload --src functions/onupload.ts
```

## Create the trigger

With the function deployed, create the trigger. It fires when an object is created in the bucket, optionally scoped to a key prefix.

**Console**

In the [Neon Console](https://console.neon.tech), open **Functions**, click the **⋮** menu next to your function, and select **Manage Triggers**. Click **Create trigger** (the **Function** is already set to the one you opened) and choose **Object upload** under **Trigger type**, then fill in:

- **Trigger name**: a label, unique across the branch, including inherited triggers.
- **Function path**: the request path sent to the function. Defaults to `/`.
- **Bucket name**: matches this bucket name exactly.
- **Path prefix (optional)**: matches object keys that start with this exact, case-sensitive prefix. Leave blank to match every object in the bucket.
- **Enable trigger**: on by default.

Click **Create trigger** to save.

**CLI**

[`neon triggers create`](https://neon.com/docs/cli/triggers#create) needs `--function-slug`, `--name`, and `--bucket`; `--prefix`, `--function-path`, and `--enabled` are optional. Object-created triggers require Neon CLI 4.21.0 or later.

```bash
neon triggers create --function-slug onupload --name record-uploads --bucket my-bucket --prefix 'uploads/'
```

The CLI resolves the project and branch from your [context file](https://neon.com/docs/cli/set-context), or pass `--project-id` and `--branch`. See [`neon triggers`](https://neon.com/docs/cli/triggers) for the full command reference.

**API**

`POST` to the branch's triggers collection. `type`, `function_slug`, `name`, and `storage_object_created` (with `bucket_name`) are required; `prefix`, `function_path`, and `enabled` are optional.

```bash
curl -X POST "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "storage_object_created",
    "function_slug": "onupload",
    "name": "record-uploads",
    "storage_object_created": {
      "bucket_name": "my-bucket",
      "prefix": "uploads/"
    },
    "function_path": "/",
    "enabled": true
  }'
```

Neon responds `201` with the trigger wrapped in a `trigger` object:

```json
{
  "trigger": {
    "type": "storage_object_created",
    "trigger_id": "trigger-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "function_slug": "onupload",
    "name": "record-uploads",
    "function_path": "/",
    "storage_object_created": {
      "bucket_name": "my-bucket",
      "prefix": "uploads/"
    },
    "enabled": true,
    "version": 1347042,
    "inherited": false
  }
}
```

Unlike a scheduled trigger, an object-created trigger has no `schedule` or `next_run_at`: it fires on the event, not the clock.

**neon.ts**

Declare the trigger in the top-level `triggers` record in [`neon.ts`](https://neon.com/docs/reference/neon-ts#triggers), with `function` pointing at your function's slug, then apply it with `neon deploy`. `bucket` selects the bucket, which must also be declared under `buckets` in the same file, and `prefix` optionally scopes it to keys under that path.

```ts filename="neon.ts"
functions: {
  onupload: {
    name: "On upload",
    source: "./functions/onupload.ts",
  },
},
buckets: {
  "my-bucket": {},
},
triggers: {
  "record-uploads": {
    type: "storage_object_created",
    function: "onupload",
    bucket: "my-bucket",
    prefix: "uploads/",
  },
},
```

## Confirm it ran

Upload an object under the bucket and prefix you configured (see [Upload and manage objects](https://neon.com/docs/storage/objects)), then read the function's logs:

```bash
neon logs query --source function --service-name neon-function/onupload
```

`--service-name neon-function/<slug>` limits the output to this function. Your `object created: ...` line appears with the `bucket_name` and `object_key` from the request body. See [Observability](https://neon.com/docs/compute/functions/triggers/object-storage#observability) for why that line matters.

To iterate on the handler without uploading objects, replay the payload against `neon dev` locally. See [Test triggers locally](https://neon.com/docs/compute/functions/triggers/overview#test-triggers-locally).

**Note:** A newly created trigger takes a few seconds to become active. If your first test upload doesn't fire the function, wait a moment and upload again.

## What your function receives

An object-created invocation delivers the same envelope shape as every trigger type, with `trigger.type` set to `storage_object_created` and the event details under `data`:

```json
{
  "version": 1,
  "invocation_id": "abc123FUPHOw0Pl1ZooidgpJhvHaShi1aX40cQ0b321",
  "trigger": { "type": "storage_object_created", "id": "trigger-1a2b3c4d-5e6f-7890-abcd-ef1234567890", "name": "record-uploads" },
  "data": {
    "bucket_name": "my-bucket",
    "object_key": "uploads/report.csv"
  },
  "previous_attempts": [],
  "previous_attempts_omitted": 0
}
```

- **`data.bucket_name`**: the bucket the object was created in.
- **`data.object_key`**: the full key of the created object, including any prefix.

The request carries the same headers as any trigger invocation. For the full envelope, headers, and how to confirm a request came from Neon, see [What your function receives](https://neon.com/docs/compute/functions/triggers/overview#what-your-function-receives) in the overview. For retries, failure history, and duplicate handling, see [Delivery and retries](https://neon.com/docs/compute/functions/triggers/overview#delivery-and-retries).

## Trigger config

The object-created settings live under `storage_object_created`:

| Field         | Required | Description                                                                                      |
| ------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `bucket_name` | Yes      | The bucket to watch, on the trigger's branch.                                                    |
| `prefix`      | No       | Only objects whose key starts with this prefix fire the trigger. Omit to watch the whole bucket. |

The top-level `type`, `function_slug`, `name`, `function_path`, and `enabled` fields, and the read-only `trigger_id` / `version` / `inherited`, work exactly as in [Trigger fields](https://neon.com/docs/compute/functions/triggers/overview#trigger-fields).

![With prefix uploads/, keys under uploads/ fire the trigger and others are ignored; prefix matching is case-sensitive](https://neon.com/docs/compute/functions/triggers/prefix-filter.png)

## Manage triggers

List, update, disable, and delete triggers from the Console, CLI, or API. Triggers declared in [`neon.ts`](https://neon.com/docs/reference/neon-ts#triggers) are managed by editing the declaration and re-running `neon deploy`.

**Console**

Manage object-created triggers from the same **Functions → ⋮ → Manage Triggers** panel: edit a trigger's fields, toggle **Enable trigger** on or off, or delete it.

**CLI**

The [`neon triggers`](https://neon.com/docs/cli/triggers) command group manages triggers by ID:

```bash
neon triggers list
neon triggers get <trigger-id>
neon triggers update <trigger-id> --bucket my-bucket --prefix 'incoming/'
neon triggers disable <trigger-id>
neon triggers enable <trigger-id>
neon triggers delete <trigger-id>
```

See [`neon triggers`](https://neon.com/docs/cli/triggers) for every subcommand and flag.

**API**

Listing, getting, updating, disabling, and deleting use the same endpoints as scheduled triggers, described in [Manage triggers](https://neon.com/docs/compute/functions/triggers/schedule#manage-triggers). A `PATCH` must include the `type` discriminator; for this type you can change `function_slug`, `name`, `function_path`, `enabled`, and the `storage_object_created` config (for example, to move the watched `prefix`):

```bash
curl -X PATCH "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers/$TRIGGER_ID" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "storage_object_created",
    "storage_object_created": { "bucket_name": "my-bucket", "prefix": "incoming/" }
  }'
```

## Observability

In the platform logs, an object-created invocation looks like any other HTTP call: the `invoke begin` and `invoke end` lines under the `neon.function.request` scope are the same either way. Trace a run from your own handler output instead. A `console.log` that includes the object key gives you a searchable line tied to the run that produced it:

```ts
console.log(`object created: ${bucket}/${key}`);
```

Your output appears under the `neon.function.app` scope, in the Console's Functions tab and in `neon logs query --source function --service-name neon-function/onupload` (not the `functions` command group). Standard Node instrumentation such as Sentry or OpenTelemetry also works, and the incoming `traceparent` header ties a run into an existing trace.

## Common errors

The API rejects a bad request with an HTTP status and message:

| Situation                                               | Status | Message                                        |
| ------------------------------------------------------- | ------ | ---------------------------------------------- |
| A trigger with that `name` already exists on the branch | `409`  | function trigger name already exists on branch |
| No `storage_object_created` object                      | `400`  | storage\_object\_created (field required)      |
| `storage_object_created` without `bucket_name`          | `400`  | bucket\_name (field required)                  |
| A query string in `function_path`                       | `400`  | invalid function trigger path                  |
| No function with that slug on the branch                | `404`  | target function not visible on branch          |

The request body is strict: any field not in the schema is rejected rather than ignored, so a typo fails loudly. The function is identified by `function_slug`; there's no `function_id` field.

## Related

- [Function Triggers overview](https://neon.com/docs/compute/functions/triggers/overview)
- [Schedule a function](https://neon.com/docs/compute/functions/triggers/schedule): the time-based trigger type
- [Triggers in `neon.ts`](https://neon.com/docs/reference/neon-ts#triggers): declare triggers as code
- [Object Storage](https://neon.com/docs/storage/overview) and [Upload and manage objects](https://neon.com/docs/storage/objects)
- [Deploy and manage](https://neon.com/docs/compute/functions/deploy)
- [Logs](https://neon.com/docs/compute/functions/logs)

--- [Document source](https://neon.com/docs/compute/functions/triggers/overview.md) ---

> Summary: Function Triggers invoke a deployed Neon Function in response to an event, with no external scheduler and no compute kept running to watch for it. Covers the trigger types (schedule and object-created), what an invocation sends your function, and how triggers behave across branches.

# Function Triggers

Let Neon invoke a function for you.

Last updated: 2026-11-05

A Function Trigger tells Neon to invoke a deployed [Neon Function](https://neon.com/docs/compute/functions/overview) in response to an event, so recurring or event-driven work runs as your own code next to your data. There's no scheduler or queue to operate and no compute kept running to watch for the event. Functions are long-running, so one trigger handles a quick health check or a table-scanning batch, and it fires even when the compute is scaled to zero.

Trigger types available today:

- **`schedule`**: a cron expression evaluated in Coordinated Universal Time (UTC). See [Schedule a function](https://neon.com/docs/compute/functions/triggers/schedule).
- **`storage_object_created`**: an object created in an [Object Storage](https://neon.com/docs/storage/overview) bucket, optionally under a key prefix. See [Trigger on an object upload](https://neon.com/docs/compute/functions/triggers/object-storage).

![Both trigger types invoke one Neon Function, which can reach Postgres, external HTTP APIs, the AI Gateway, and Object Storage](https://neon.com/docs/compute/functions/triggers/types-fan-in.png)

The API uses a `type` discriminator, so more types can be added later without changing existing triggers. Manage triggers from the [Neon Console](https://console.neon.tech), the [`neon triggers`](https://neon.com/docs/cli/triggers) CLI, the Neon API, or [`neon.ts`](https://neon.com/docs/reference/neon-ts); each guide shows which of these its type supports.

## Trigger fields

A trigger belongs to a project and branch and points to one function on that branch.

| Field                    | Required                     | Description                                                                                                                                                                     |
| ------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                   | Yes                          | `"schedule"` or `"storage_object_created"`.                                                                                                                                     |
| `function_slug`          | Yes                          | The [slug](https://neon.com/docs/compute/functions/deploy#slugs) of the function to invoke, matching `^[a-z0-9]{1,20}$` and fixed after first deploy. It's the only identifier. |
| `name`                   | Yes                          | A label, 1 to 256 characters. Unique among triggers visible on the branch, including inherited ones.                                                                            |
| `schedule`               | For `schedule`               | `{ "cron": "*/15 * * * *" }`, always UTC. See [Schedule a function](https://neon.com/docs/compute/functions/triggers/schedule).                                                 |
| `storage_object_created` | For `storage_object_created` | `{ "bucket_name": "my-bucket", "prefix": "uploads/" }` (`prefix` optional). See [Trigger on an object upload](https://neon.com/docs/compute/functions/triggers/object-storage). |
| `function_path`          | No                           | Path the invocation is sent to, 1 to 2048 characters. Defaults to `/`. Path only, no query string.                                                                              |
| `enabled`                | No                           | Defaults to `true`. Set `false` to keep a trigger without running it.                                                                                                           |

Neon returns these read-only fields on every trigger:

| Field         | Description                                                                  |
| ------------- | ---------------------------------------------------------------------------- |
| `trigger_id`  | Opaque ID in the form `trigger-<uuid>`, stable across the project.           |
| `version`     | A number that increases when the trigger's configuration changes.            |
| `next_run_at` | Next run, UTC. `null` while disabled. Advances automatically after each run. |
| `inherited`   | `true` when that configuration came from an ancestor branch.                 |

A function can have multiple triggers, each evaluated independently, for example a 15-minute sync and a nightly full run. Give each a distinct `function_path`, or read `trigger.id` / `trigger.name` from the request body, so the handler can tell them apart.

## What your function receives

When a trigger fires, Neon sends the function:

- **Method:** `POST`.

- **Path:** the trigger's `function_path`, exactly as configured. Your handler needs a route that matches it (the default `/` matches `app.post('/')`).

- **Body:** a JSON envelope describing the occurrence. The shape is the same for every trigger type; `trigger.type` and the `data` object vary:

  ```json
  {
    "version": 1,
    "invocation_id": "abc123FUPHOw0Pl1ZooidgpJhvHaShi1aX40cQ0b321",
    "trigger": { "type": "schedule", "id": "trigger-1a2b3c4d-5e6f-7890-abcd-ef1234567890", "name": "uptime-check" },
    "data": { "scheduled_at": "2026-09-08T19:30:00Z" },
    "previous_attempts": [],
    "previous_attempts_omitted": 0
  }
  ```

  `data` holds the event details: `scheduled_at` (UTC) for a `schedule` trigger, or `bucket_name` and `object_key` for a [`storage_object_created`](https://neon.com/docs/compute/functions/triggers/object-storage#what-your-function-receives) trigger. `trigger` says which trigger fired, so a function with several triggers can tell them apart. Here `trigger.id` is the same value as the trigger resource's `trigger_id`, and this `version` is the payload's schema version, not the trigger's configuration `version`. For `previous_attempts` and `previous_attempts_omitted`, see [Read previous failures](https://neon.com/docs/compute/functions/triggers/overview#read-previous-failures).

- **Headers:** `content-type: application/json`, a W3C [`traceparent`](https://www.w3.org/TR/trace-context/), and `X-Neon-Trigger-Invocation-Id` (equal to the body's `invocation_id`).

Design your handler for the trigger type you use: it answers `POST` and reads what it needs from `data`.

A trigger invocation can be slower on a cold start: if the function's runtime was idle and evicted, Neon spins it up first, and a query to a Postgres compute that has [scaled to zero](https://neon.com/docs/introduction/scale-to-zero) wakes that compute too.

### Confirming a request came from Neon

Neon delivers trigger calls to the function's public URL. To confirm a request is a genuine trigger invocation and not an arbitrary caller, check for the `X-Neon-Trigger-Invocation-Id` header: Neon strips any client-supplied `X-Neon-*` header at the edge, so a request that carries one is sent by Neon's trigger system. A handler that only serves triggers can reject requests that lack it with `401 Unauthorized`, as the [worked handler](https://neon.com/docs/compute/functions/triggers/schedule#write-a-handler-for-the-scheduled-call) does.

The `invocation_id` is a correlation ID, not a secret. It's a digest of the trigger and its occurrence, stable across retries, so it ties your logs to a specific run. What proves the request came from Neon is the presence of the header, not its value, so matching the header against the body is only a consistency check. Keep the handler idempotent and guard destructive actions regardless.

## Delivery and retries

Neon retries failed trigger deliveries a few times, up to 72 hours after the event is created. A `2xx` response marks the delivery as successful once your function finishes sending the response body. Other responses, including redirects and `429`, count as failures. Neon doesn't follow redirects. Errors in your function, including errors that prevent it from loading, also count as failures, as does a delivery to a function that's missing or can't run. If the last retry fails, Neon discards the event.

Delivery can happen more than once, even if your handler already did the work, and deliveries can arrive out of order. The `invocation_id` stays the same across deliveries of the same event. Make your handler idempotent, so processing the same event again doesn't repeat side effects. For example, use `invocation_id` as a unique key when recording a result, and commit that record together with the database changes it protects.

Retries use the same [Functions pricing](https://neon.com/docs/introduction/plans#functions) as other invocations.

### Request a later retry

If your handler needs more time before another attempt, return `503 Service Unavailable` with a `Retry-After` header. Neon honors this header only on a `503` returned by your handler. It ignores the header on other statuses, including `429`.

The header accepts a whole number of seconds, such as `Retry-After: 60`, or an HTTP-date, such as `Retry-After: Wed, 21 Oct 2026 07:28:00 GMT`. Neon clamps the requested wait to 1 to 900 seconds. Zero or a past date becomes a one-second wait. The retry can happen slightly later than that wait.

A valid header can keep retries going beyond the usual retry limits, but it never extends the event's original 72-hour lifetime. The lifetime starts when the event is created, not when your handler returns `503`. Each later failure needs its own valid `503` and `Retry-After` to extend retries again. An absent or invalid header uses the usual retry policy; it doesn't reset the retry limits.

### Read previous failures

The request body's `previous_attempts` array is empty on the first delivery. On later deliveries, it contains only previous failures from your function, ordered from oldest to newest among the retained entries. Neon keeps up to the latest 16 entries and limits the serialized history to 32 KiB, dropping the oldest entries as needed. `previous_attempts_omitted` is an integer that counts the failures left out of the array. It starts at `0`.

Each entry has these fields:

| Field                     | Type              | Description                                                                                                                                           |
| ------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status_code`             | Integer or `null` | HTTP status returned by your function, or `null` if the failure had no HTTP response.                                                                 |
| `timestamp`               | String            | UTC timestamp when the response or failure completed.                                                                                                 |
| `response_body`           | String            | Up to the first 1 KiB of the response body, decoded as UTF-8 with replacement for invalid bytes. For failures without a response, a short error text. |
| `response_body_truncated` | Boolean           | `true` if the response preview was cut short.                                                                                                         |

For example, a delivery after your handler returned `503` can include:

```json
{
  "previous_attempts": [
    {
      "status_code": 503,
      "timestamp": "2026-10-20T12:00:00Z",
      "response_body": "Dependency unavailable",
      "response_body_truncated": false
    }
  ],
  "previous_attempts_omitted": 0
}
```

These fields are part of the [full request envelope](https://neon.com/docs/compute/functions/triggers/overview#what-your-function-receives). Failures on Neon's side don't appear in this history or count toward your function's retries. History is bounded, so use `invocation_id` to handle duplicates rather than the number of history entries.

## Test triggers locally

Triggers only fire from Neon's side against the deployed function, so a trigger never calls your local machine. To iterate on the handler, serve the function with [`neon dev`](https://neon.com/docs/compute/functions/get-started#develop-locally) and replay the trigger payload yourself with `curl`.

1. Start the dev server:

   ```bash
   neon dev
   ```

   It serves the functions declared in `neon.ts` with hot reload, injects `DATABASE_URL` and other Neon variables from the linked branch, and prints a local URL for each function (by default `http://localhost:8787`).

2. Send a `POST` to the local URL plus the trigger's `function_path`, with the same JSON envelope the trigger would send. Include an `X-Neon-Trigger-Invocation-Id` header if your handler checks for it, set to the body's `invocation_id`. A schedule replay carries `data.scheduled_at`:

   ```bash
   curl -X POST http://localhost:8787/ \
     -H "Content-Type: application/json" \
     -H "X-Neon-Trigger-Invocation-Id: local-1" \
     -d '{"version":1,"invocation_id":"local-1","trigger":{"type":"schedule","id":"trigger-local","name":"local-schedule"},"data":{"scheduled_at":"2026-09-08T19:30:00Z"},"previous_attempts":[],"previous_attempts_omitted":0}'
   ```

   An object-created replay carries `data.bucket_name` and `data.object_key`:

   ```bash
   curl -X POST http://localhost:8787/ \
     -H "Content-Type: application/json" \
     -H "X-Neon-Trigger-Invocation-Id: local-2" \
     -d '{"version":1,"invocation_id":"local-2","trigger":{"type":"storage_object_created","id":"trigger-local","name":"local-upload"},"data":{"bucket_name":"my-bucket","object_key":"uploads/report.csv"},"previous_attempts":[],"previous_attempts_omitted":0}'
   ```

Handler output appears in the `neon dev` terminal rather than in `neon logs query`. Leave off the `X-Neon-Trigger-Invocation-Id` header to confirm a guarded handler returns `401`. If the handler reads from Object Storage, the bucket and object live on the branch, so deploy first and make sure the object you replay exists there.

## Triggers and branching

Triggers follow Neon's branch inheritance:

- **A child branch inherits its parent's triggers.** They appear with `inherited: true`, `enabled: false`, and `next_run_at: null`, and keep the same `trigger_id`. An inherited trigger doesn't run on the child until you enable it there.
- **Editing an inherited trigger makes it branch-local.** The `PATCH` creates a child-local copy under the same `trigger_id`, and `inherited` becomes `false`. The parent is unchanged.
- **Deleting an inherited trigger on the child removes it there for good.** It won't reappear, and the parent keeps running it.

So branching a production branch for a test doesn't double your scheduled work. Nothing runs on the child until you enable it, and enabling it there can't affect the parent.

## Next steps

When you're ready, walk through a worked example for each type: [Schedule a function](https://neon.com/docs/compute/functions/triggers/schedule) (with a cron reference) and [Trigger on an object upload](https://neon.com/docs/compute/functions/triggers/object-storage).

--- [Document source](https://neon.com/docs/compute/functions/triggers/schedule.md) ---

> Summary: Create and manage scheduled Function Triggers from the Neon Console, the neon triggers CLI, the Neon API, or neon.ts: a Hono handler for the scheduled POST, a five-field UTC cron reference, how to confirm a run in the logs, and the common errors.

# Schedule a function

Create and manage scheduled Function Triggers.

Last updated: 2026-11-05

Schedule a function to run recurring work as your own code: a nightly report, a cleanup job, a periodic sync, or a health check. It runs next to your data and fires even when the compute is scaled to zero.

![A schedule fires a POST to the uptime function, which reads scheduled\_at, fetches a URL, and records the result in Postgres](https://neon.com/docs/compute/functions/triggers/schedule-flow.png)

This guide creates a scheduled trigger, then covers listing, updating, disabling, and deleting it. For what a trigger is and how it behaves across branches, see the [overview](https://neon.com/docs/compute/functions/triggers/overview). You can manage scheduled triggers from the Neon Console, the [`neon triggers`](https://neon.com/docs/cli/triggers) CLI, the Neon API, or declaratively in [`neon.ts`](https://neon.com/docs/reference/neon-ts); the steps below show each.

For retries, failure history, and duplicate handling, see [Delivery and retries](https://neon.com/docs/compute/functions/triggers/overview#delivery-and-retries).

## Before you begin

You need a [deployed function](https://neon.com/docs/compute/functions/get-started) and its [slug](https://neon.com/docs/compute/functions/deploy#slugs). The CLI and API also need a Neon [API key](https://neon.com/docs/manage/api-keys); the Console doesn't. If you deployed with the CLI, [`neon link`](https://neon.com/docs/cli/link) already wrote your project and branch to a `.neon` file; you can also find the IDs in the [Neon Console](https://console.neon.tech).

The API examples use these variables:

```bash
export API="https://console.neon.tech/api/v2"
export NEON_API_KEY="<your-api-key>"
export PROJECT_ID="<your-project-id>"
export BRANCH_ID="<your-branch-id>"
```

To build this with an AI agent, start from this prompt and fill in the task:

```text filename="AI assistant prompt"
Create a Neon Function that <task>, then schedule it with a Function Trigger.
Docs: https://neon.com/docs/compute/functions/triggers/schedule.md

- Add one unauthenticated POST route (scheduled invocations arrive without credentials). Read `data.scheduled_at` from the JSON body; keep the handler idempotent.
- If the task uses Postgres, connect with the injected DATABASE_URL through a module-scope `pg` Pool with `attachDatabasePool` from `@neon/functions`, not `@neondatabase/serverless`.
- Deploy it, then create a schedule trigger via the Neon API with a five-field UTC cron. Start at `* * * * *` to confirm a run, then PATCH to the real cadence.
- The route and trigger both default to `/`; set `function_path` on both if you want a different path.
```

## Write a handler for the scheduled call

A scheduled invocation is a `POST` whose JSON body carries the occurrence: `data.scheduled_at`, the `trigger` that fired, and an `invocation_id`. Neon delivers it to the function's public URL, so the route sits outside your auth middleware. You can confirm the call came from Neon with the `X-Neon-Trigger-Invocation-Id` header (see [Confirming a request came from Neon](https://neon.com/docs/compute/functions/triggers/overview#confirming-a-request-came-from-neon)); keep the handler idempotent and guard destructive actions regardless.

This [Hono](https://hono.dev) function checks a URL and records the result:

```ts
import { Hono } from 'hono';
import { attachDatabasePool } from '@neon/functions';
import { Pool } from 'pg';

// Create the pool once at module scope so it's reused across invocations.
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
attachDatabasePool(pool);
const app = new Hono();

// This route is public. Neon strips client-set X-Neon-* headers, so the presence of
// X-Neon-Trigger-Invocation-Id attests the call came from Neon's trigger system.
app.post('/', async (c) => {
  if (!c.req.header('x-neon-trigger-invocation-id')) {
    return c.json({ error: 'not a trigger call' }, 401);
  }

  const { data } = await c.req.json<{ data: { scheduled_at: string } }>();
  const scheduledAt = data.scheduled_at;

  const started = performance.now();
  const res = await fetch('https://example.com', { signal: AbortSignal.timeout(10_000) });
  const latencyMs = Math.round(performance.now() - started);

  await pool.query(
    `INSERT INTO checks (scheduled_at, status_code, latency_ms)
     VALUES ($1, $2, $3)
     ON CONFLICT (scheduled_at) DO NOTHING`,
    [scheduledAt, res.status, latencyMs]
  );

  console.log(`check ${scheduledAt}: ${res.status} in ${latencyMs}ms`);
  return c.json({ ok: true, scheduled_at: scheduledAt, status: res.status });
});

export default app;
```

`DATABASE_URL` is injected for you. See [Environment variables](https://neon.com/docs/compute/functions/environment-variables). The handler connects through a module-scope `pg` pool, as in [Use a connection pool](https://neon.com/docs/compute/functions/get-started#connect-to-postgres). The `ON CONFLICT (scheduled_at) DO NOTHING` clause makes a redelivered occurrence a no-op.

Create the table it writes to, in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or with [`neon psql`](https://neon.com/docs/cli/psql):

```sql
CREATE TABLE IF NOT EXISTS checks (
  scheduled_at timestamptz PRIMARY KEY,
  status_code  int,
  latency_ms   int
);
```

Then deploy the function:

```bash
neon functions deploy uptime --src functions/uptime.ts
```

## Create the trigger

With the function deployed, create a schedule trigger. Start with `* * * * *` so you can confirm the trigger in under a minute, then move it to a real cadence below.

**Console**

In the [Neon Console](https://console.neon.tech), open **Functions**, click the **⋮** menu next to your function, and select **Manage Triggers**. Click **Create trigger** (the **Function** is already set to the one you opened) and choose **Schedule** under **Trigger type**, then fill in:

- **Trigger name**: a label, unique across the branch, including inherited triggers.
- **Function path**: the request path sent to the function. Defaults to `/`.
- **Cron schedule**: five numeric fields: minute, hour, day of month, month, day of week. See [Cron reference](https://neon.com/docs/compute/functions/triggers/schedule#cron-reference).
- **Timezone**: fixed to UTC; schedules are always evaluated in UTC.
- **Enable trigger**: on by default.

Click **Create trigger** to save.

**CLI**

[`neon triggers create`](https://neon.com/docs/cli/triggers#create) needs `--function-slug`, `--name`, and `--cron`; `--function-path` and `--enabled` are optional.

```bash
neon triggers create --function-slug uptime --name uptime-check --cron '* * * * *'
```

The CLI resolves the project and branch from your [context file](https://neon.com/docs/cli/set-context), or pass `--project-id` and `--branch`. See [`neon triggers`](https://neon.com/docs/cli/triggers) for the full command reference.

**API**

`POST` to the branch's triggers collection. `type`, `function_slug`, `name`, and `schedule` are required; `function_path` and `enabled` are optional.

```bash
curl -X POST "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "function_slug": "uptime",
    "name": "uptime-check",
    "schedule": { "cron": "* * * * *" },
    "function_path": "/",
    "enabled": true
  }'
```

Neon responds `201` with the trigger wrapped in a `trigger` object:

```json
{
  "trigger": {
    "type": "schedule",
    "trigger_id": "trigger-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "function_slug": "uptime",
    "name": "uptime-check",
    "function_path": "/",
    "schedule": { "cron": "* * * * *" },
    "enabled": true,
    "version": 1347042,
    "next_run_at": "2026-09-08T19:31:00.000000Z",
    "inherited": false
  }
}
```

`next_run_at` is when the first run happens. It's in UTC and advances automatically after each run.

**neon.ts**

Declare the trigger in the top-level `triggers` record in [`neon.ts`](https://neon.com/docs/reference/neon-ts), with `function` pointing at your function's slug, then apply it with `neon deploy`. `cron` is a five-field UTC expression.

```ts filename="neon.ts"
functions: {
  uptime: {
    name: "Uptime",
    source: "./functions/uptime.ts",
  },
},
triggers: {
  "uptime-check": {
    type: "schedule",
    function: "uptime",
    cron: "* * * * *",
  },
},
```

## Confirm it ran

The schedule is every minute, so wait about a minute, then read the function's logs:

```bash
neon logs query --source function --service-name neon-function/uptime
```

`--service-name neon-function/<slug>` limits the output to this function. Your `check ...` line appears with the `scheduled_at` value read from `data`. See [Observability](https://neon.com/docs/compute/functions/triggers/schedule#observability) for why that line matters.

To iterate on the handler without waiting for the clock, replay the payload against `neon dev` locally. See [Test triggers locally](https://neon.com/docs/compute/functions/triggers/overview#test-triggers-locally).

Once you've seen a run, move the trigger to its real cadence (see [Manage triggers](https://neon.com/docs/compute/functions/triggers/schedule#manage-triggers)). Left at `* * * * *`, it keeps invoking the function every minute.

## Cron reference

A schedule is a five-field numeric cron expression, always interpreted in **UTC**.

![The five cron fields (minute, hour, day of month, month, day of week); 0 9 \* \* 1-5 means 09:00 Monday through Friday](https://neon.com/docs/compute/functions/triggers/cron-anatomy.png)

To track local time, convert to UTC yourself, and account for daylight saving shifts. You can test your expressions with [crontab.guru](https://crontab.guru/).

| Expression     | Meaning (UTC)                     |
| -------------- | --------------------------------- |
| `*/15 * * * *` | Every 15 minutes                  |
| `0 9 * * 1-5`  | 09:00, Monday through Friday      |
| `0,30 * * * *` | On the hour and half hour         |
| `15 14 1 * *`  | 14:15 on the 1st of each month    |
| `0 0 1 * *`    | Midnight on the 1st of each month |
| `* * * * *`    | Every minute                      |

Ranges (`1-5`), lists (`0,30`), steps (`*/2`), and fixed values all work, down to every minute, with no maximum interval. Fields are numeric, so use numbers for days and months (`1` for Monday, `1` for January), not names. A value outside its field's range (`70 * * * *`), a named day or month (`0 9 * * MON`, `0 0 1 JAN *`), a macro (`@daily`, `@hourly`), a seconds field (`* * * * * *`), or a zero step (`*/0 * * * *`) each return a `400`.

## Manage triggers

List, update, disable, and delete triggers from the Console, CLI, or API. Triggers declared in [`neon.ts`](https://neon.com/docs/reference/neon-ts) are managed by editing the declaration and re-running `neon deploy`.

**Console**

Open **Functions → ⋮ → Manage Triggers** for the function. The panel lists that function's triggers with their schedule, next run, and enabled state. From there you can edit a trigger's fields, toggle **Enable trigger** on or off, or delete it.

**CLI**

The [`neon triggers`](https://neon.com/docs/cli/triggers) command group manages triggers by ID:

```bash
neon triggers list
neon triggers get <trigger-id>
neon triggers update <trigger-id> --cron '0 3 * * *'
neon triggers disable <trigger-id>
neon triggers enable <trigger-id>
neon triggers delete <trigger-id>
```

See [`neon triggers`](https://neon.com/docs/cli/triggers) for every subcommand and flag.

**API**

These examples use `$TRIGGER_ID`, the `trigger_id` from the create response.

**List triggers on a branch**

```bash
curl "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```json
{
  "triggers": [
    {
      "type": "schedule",
      "trigger_id": "trigger-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "function_slug": "uptime",
      "name": "uptime-check",
      "function_path": "/",
      "schedule": { "cron": "0 3 * * *" },
      "enabled": true,
      "version": 1347043,
      "next_run_at": "2026-09-09T03:00:00.000000Z",
      "inherited": false
    }
  ]
}
```

The list is ordered by `trigger_id`, includes triggers [inherited](https://neon.com/docs/compute/functions/triggers/overview#triggers-and-branching) from a parent branch, and returns every trigger on the branch in one response.

**Get one trigger**

```bash
curl "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers/$TRIGGER_ID" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Returns the same `{ "trigger": { ... } }` shape as create.

**Update a trigger**

`PATCH` is partial, but it must include the `type` discriminator plus at least one field to change. You can change `function_slug`, `name`, `function_path`, `schedule`, and `enabled`.

```bash
curl -X PATCH "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers/$TRIGGER_ID" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "schedule", "schedule": { "cron": "0 3 * * *" } }'
```

A successful update returns `200` with the full object. `version` increases and `next_run_at` is recomputed against the new schedule.

**Disable and re-enable**

Disabling keeps the trigger but stops scheduling it:

```bash
curl -X PATCH "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers/$TRIGGER_ID" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "schedule", "enabled": false }'
```

Disabling sets `next_run_at` to `null` and increments `version`. Send `"enabled": true` to start it again; `next_run_at` is recomputed from the current time.

**Delete a trigger**

```bash
curl -X DELETE "$API/projects/$PROJECT_ID/branches/$BRANCH_ID/triggers/$TRIGGER_ID" \
  -H "Authorization: Bearer $NEON_API_KEY" -i
```

```
HTTP/1.1 204 No Content
```

**Note:** Disabling or deleting stops future runs, but a run already queued for the upcoming minute still fires. To skip an imminent run, change the trigger well before that minute, not in the same instant.

## Observability

In the platform logs, a scheduled invocation looks like any other HTTP call: the `invoke begin` and `invoke end` lines under the `neon.function.request` scope are the same either way. Trace a run from your own handler output instead. A `console.log` that includes `scheduled_at` gives you a searchable line tied to the run that produced it:

```ts
console.log(`check ${scheduledAt}: ${res.status} in ${latencyMs}ms`);
```

Your output appears under the `neon.function.app` scope, in the Console's Functions tab and in:

```bash
neon logs query --source function --service-name neon-function/uptime
```

Function logs come from `neon logs query --source function`, not the `functions` command group. Standard Node instrumentation such as Sentry or OpenTelemetry also works, and the incoming `traceparent` header ties a run into an existing trace.

## Common errors

The API and CLI reject a bad request with an HTTP status and message:

| Situation                                               | Status | Message                                                                          |
| ------------------------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| A trigger with that `name` already exists on the branch | `409`  | function trigger name already exists on branch                                   |
| Invalid cron expression                                 | `400`  | invalid function trigger configuration: cron: cron value is outside field bounds |
| A `timezone` key inside `schedule`                      | `400`  | unexpected field "timezone"                                                      |
| A query string in `function_path`                       | `400`  | invalid function trigger path                                                    |
| No function with that slug on the branch                | `404`  | target function not visible on branch                                            |

The request body is strict: any field not in the schema is rejected rather than ignored, so a typo fails loudly. In particular, the function is identified by `function_slug`; there's no `function_id` field.

## Function Triggers vs pg_cron

[pg_cron](https://neon.com/docs/extensions/pg_cron) schedules SQL inside Postgres. A scheduled Function Trigger runs your function code instead. They solve different problems:

|                        | pg\_cron                             | Function Triggers                                                                                                            |
| ---------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| Runs                   | A SQL statement or Postgres function | Your JavaScript or TypeScript function                                                                                       |
| Where                  | Inside the Postgres compute          | On Neon's compute, next to your data                                                                                         |
| External APIs          | No                                   | Yes: HTTP, [AI Gateway](https://neon.com/docs/ai-gateway/overview), [Object Storage](https://neon.com/docs/storage/overview) |
| Compute scaled to zero | Doesn't run                          | Runs; the invocation starts the function                                                                                     |

## Related

- [Function Triggers overview](https://neon.com/docs/compute/functions/triggers/overview)
- [Trigger on an object upload](https://neon.com/docs/compute/functions/triggers/object-storage): the object-created trigger type
- [Triggers in `neon.ts`](https://neon.com/docs/reference/neon-ts#triggers): declare triggers as code
- [pg_cron](https://neon.com/docs/extensions/pg_cron): schedule SQL inside Postgres instead
- [Deploy and manage](https://neon.com/docs/compute/functions/deploy)
- [Authentication](https://neon.com/docs/compute/functions/authentication)
- [Logs](https://neon.com/docs/compute/functions/logs)

--- [Document source](https://neon.com/docs/compute/functions/websockets.md) ---

> Summary: Neon Functions stay alive while data flows, so they can host real-time backends. Use WebSockets for two-way connections with upgradeWebSocket from @neon/functions, server-sent events for one-way streams, and Postgres to broadcast across isolates.

# WebSockets and SSE on Neon Functions

Hold long-lived connections open for real-time apps.

Last updated: 2026-09-16

Real-time backends on Neon Functions still follow the request/response model: one request opens a connection, and the handler keeps a streamed response open while data keeps moving. Because the function keeps running for the life of that connection, it can host a real-time backend on the same branch as your Postgres database, using Postgres itself for cross-isolate messaging (polling, or `LISTEN/NOTIFY`) instead of a separate broker like Redis.

Two options, depending on direction:

- **[WebSockets](https://neon.com/docs/compute/functions/websockets#serve-a-websocket)**: two-way, low-latency frames. Reach for these when the client also sends messages (chat, presence, collaborative editing).
- **[Server-sent events (SSE)](https://neon.com/docs/compute/functions/websockets#server-sent-events-sse)**: one-way, server to client. Simpler to run (plain HTTP, no upgrade, no library), and the browser's `EventSource` reconnects automatically. Reach for these for live counters, notifications, progress, and token streams.

## Serve a WebSocket

Accept a WebSocket connection with `upgradeWebSocket` from `@neon/functions` (0.7.0 or later). Called inside your normal `fetch` handler, `upgradeWebSocket(request)` turns a handshake into a live connection and returns `{ socket, response }`: return `response` to complete the upgrade, and `socket` is a standard [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket), with no `ws` dependency. The API mirrors [`Deno.upgradeWebSocket`](https://docs.deno.com/api/deno/~/Deno.upgradeWebSocket).

```ts filename="functions/echo.ts"
import { upgradeWebSocket } from '@neon/functions';

export default {
  fetch(request: Request) {
    if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
      return new Response('This endpoint speaks WebSocket. Send an Upgrade request.', {
        status: 426,
      });
    }

    const { socket, response } = upgradeWebSocket(request);
    socket.addEventListener('message', (event) => {
      socket.send(`echo: ${event.data}`);
    });
    return response;
  },
};
```

Install the dependency (`@neon/functions` 0.7.0 or later):

```bash
npm install @neon/functions
```

Local WebSocket support needs the `neon` CLI 2.45.0 or later. With an earlier CLI, `neon dev` returns `200 OK` instead of `101 Switching Protocols` for upgrade requests, so test against a deployed function or upgrade the CLI. Installing `@neon/functions` does not upgrade the CLI; they version independently.

Note:

- **Return `response` unchanged.** The runtime writes the `101 Switching Protocols` only when your handler returns it, and the socket opens (firing `open`) at that point. Cloning or rebuilding the response (`new Response(res.body, res)`, which response-rewriting middleware does) discards the upgrade, and the runtime fails the request with a `500` rather than leaving the client hanging.
- **`socket` is a standard `WebSocket`.** Both `addEventListener` and the `onmessage`/`onopen`/`onclose`/`onerror` properties work. It's still `CONNECTING` when you get it, and its `binaryType` defaults to `'arraybuffer'` rather than the browser's `'blob'`, so `event.data` is a `string` for text frames and an `ArrayBuffer` (not a `Blob`) for binary ones.
- **It throws instead of degrading.** `upgradeWebSocket` raises a `TypeError` whenever it can't produce a real socket: off-platform (outside a Neon Functions runtime), on a request that isn't a WebSocket handshake, or if you call it twice for the same request. That second case is why the example above returns `426` before calling it, so guard any handler that also serves plain HTTP. On-platform it works both locally under `neon dev` and when deployed, so there's nothing extra to do to test it.

To select a subprotocol, pass `protocol`, but only one the client actually offered: per [RFC 6455](https://datatracker.ietf.org/doc/html/rfc6455#section-4.2.2) a server may only select from the client's list, so passing one it didn't offer throws a `TypeError`. The client's offers are in the `Sec-WebSocket-Protocol` request header, so read them inside `fetch` and select conditionally before calling `upgradeWebSocket`:

```ts
const offered = request.headers.get('sec-websocket-protocol')?.split(',').map((s) => s.trim());
const protocol = offered?.includes('chat.v2') ? 'chat.v2' : undefined;
const { socket, response } = upgradeWebSocket(request, protocol ? { protocol } : undefined);
```

Test it with [`wscat`](https://github.com/websockets/wscat):

```bash
npm install -g wscat
wscat --connect ws://localhost:<port>   # local; use the URL `neon dev` prints
wscat --connect wss://<your-function-url>   # deployed
```

Type a message and press Enter. The server echoes it back.

## Hono app with WebSocket

For a Hono app, use `upgradeWebSocket` from `@neon/functions/hono` (needs `@neon/functions` 0.9.0 or later). It's a Hono route helper: pass a function that returns `onOpen`, `onMessage`, `onClose`, and `onError` handlers. The handshake is a normal request to your app, so it flows through routing and middleware like any other, and auth is just route middleware, not something you reimplement on a raw socket.

Watch the import path. The similarly named `upgradeWebSocket` from `@hono/node-server` is a different function that does not work here, because it requires Hono's own `serve()` wrapper, which the runtime doesn't use.

```ts filename="functions/hono-echo.ts"
import { Hono } from 'hono';
import { upgradeWebSocket } from '@neon/functions/hono';

const app = new Hono();

app.get('/', (c) => c.text('WebSocket server. Connect via wss://'));

app.get(
  '/ws',
  // Normal Hono middleware, applied to the handshake. verifyToken is your own
  // JWT or API-key check; see Authentication below.
  async (c, next) => {
    if (!(await verifyToken(c.req.query('token')))) return c.text('unauthorized', 401);
    await next();
  },
  upgradeWebSocket(() => ({
    onOpen: (_event, ws) => ws.send('welcome'),
    onMessage: (event, ws) => ws.send(`echo: ${event.data}`),
    onClose: () => console.log('client disconnected'),
  })),
);

export default {
  fetch: (request: Request) => app.fetch(request),
};
```

Install the dependencies (`@neon/functions` 0.9.0 or later, plus Hono):

```bash
npm install @neon/functions hono
```

The `ws` handle passed to each callback is Hono's [`WSContext`](https://hono.dev/docs/helpers/websocket): use `ws.send()`, `ws.close()`, and `ws.readyState`, and reach the underlying standard `WebSocket` through `ws.raw`. A non-upgrade request on the same path is left alone and passed to the next handler, so a plain `GET /ws` still reaches any route you define below it.

**Warning: Middleware that rebuilds the response breaks the upgrade**

The upgrade completes only when the runtime writes the handler's `response` unchanged, so Hono middleware that reads or rebuilds the response defeats it. In particular, `app.use('*', cors())` on an upgrade route fails the handshake with HTTP `500` and `websocket_upgrade_response_lost`; the same happens when middleware reads `c.res` before calling `next()` and sets headers afterward. Scope response-rewriting middleware to your non-WebSocket routes, not the upgrade route.

## Cross-isolate messaging

WebSocket connections are local to the isolate they land on, so clients on different isolates can't communicate through shared memory. Under load the runtime spreads connections across several isolates, each with its own `Set` of clients, so broadcasting to only the local set means a client on one isolate never sees a message produced on another. `neon dev` runs a single isolate, so this looks fine locally and only shows up in production.

Postgres is the shared source of truth. Start with polling, which keeps [scale to zero](https://neon.com/docs/introduction/scale-to-zero); use `LISTEN/NOTIFY` only on always-on compute that needs sub-second latency; for very large or multi-region fan-out, reach for a dedicated broker like [Upstash](https://upstash.com) Redis instead.

### Poll Postgres (default)

Each isolate polls for rows past a cursor and pushes them to its own clients. Polling stops when the isolate has no clients, so an idle compute still suspends and scale to zero keeps working.

Create a table for writers to `INSERT` into (no `pg_notify` needed):

```sql
CREATE TABLE messages (id bigserial PRIMARY KEY, body text);
```

Then each isolate polls it:

```ts filename="functions/feed.ts"
import { upgradeWebSocket, attachDatabasePool } from '@neon/functions';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
attachDatabasePool(pool); // add a pool error handler; without one, node-postgres crashes the process on a pool error

const clients = new Set<WebSocket>();
let cursor = '0'; // highest message id seen; a bigint, so a string
let polling = false;

async function poll() {
  if (polling || clients.size === 0) return; // guard against overlap; skip when no clients so the compute can idle out
  polling = true;
  try {
    const { rows } = await pool.query('SELECT id, body FROM messages WHERE id > $1 ORDER BY id', [cursor]);
    for (const row of rows) {
      cursor = row.id;
      for (const socket of clients) {
        if (socket.readyState === socket.OPEN) socket.send(row.body); // skip a socket mid-close
      }
    }
  } catch (err) {
    console.error('[poll]', err);
  } finally {
    polling = false;
  }
}

// Seed the cursor with the latest id so a fresh isolate sends only new rows, then poll.
pool
  .query('SELECT coalesce(max(id), 0)::text AS id FROM messages')
  .then(({ rows }) => { cursor = rows[0].id; })
  .catch((err) => console.error('[seed]', err))
  .finally(() => setInterval(poll, 1000).unref?.());

export default {
  fetch(request: Request) {
    if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
      return new Response('This endpoint speaks WebSocket. Send an Upgrade request.', { status: 426 });
    }
    const { socket, response } = upgradeWebSocket(request);
    socket.addEventListener('open', () => clients.add(socket)); // add once the 101 is written
    socket.addEventListener('close', () => clients.delete(socket));
    return response;
  },
};
```

Install the dependencies:

```bash
npm install @neon/functions pg
npm install --save-dev @types/pg
```

Between messages a quiet feed sends nothing, so pair it with a [heartbeat](https://neon.com/docs/compute/functions/websockets#heartbeat) to keep idle clients from being dropped.

`WHERE id > cursor` can skip a row that commits out of sequence: a transaction that took a lower id but commits after a higher one is already behind the cursor, so the poll never returns it. For a broadcast feed occasional loss is usually acceptable; when you need every row, use `LISTEN/NOTIFY` (below, on always-on compute) or poll by `created_at` with a small overlap window and dedupe by id.

### LISTEN/NOTIFY (lowest latency, always-on compute only)

For sub-second latency, each isolate holds one `LISTEN` connection at module scope and broadcasts with `NOTIFY`, so every isolate re-pushes to its own clients.

**Warning: LISTEN/NOTIFY disables scale to zero**

The `LISTEN` client holds an idle connection open on every isolate, and an idle connection doesn't count as active traffic. [Scale to zero](https://neon.com/docs/introduction/scale-to-zero) suspends the compute on its normal timer and drops that connection, silently killing the feed. Only use `LISTEN`/`NOTIFY` on an always-on compute, with scale to zero disabled (a paid-plan setting).

Each isolate keeps a `Set` of the `upgradeWebSocket` sockets it accepted, one `LISTEN` client to receive `NOTIFY`, and a pool to `pg_notify` when a client sends a message.

Install the additional dependencies:

```bash
npm install @neon/functions pg
npm install --save-dev @types/pg
```

```ts filename="functions/chat.ts"
import { upgradeWebSocket, attachDatabasePool } from '@neon/functions';
import { Pool, Client } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
attachDatabasePool(pool);

// One dedicated LISTEN client per isolate. Don't call attachDatabasePool on it:
// that would swallow the idle drop that kills the feed. The error listener keeps
// the process alive; in production, reconnect the client on error (omitted here).
const listener = new Client({ connectionString: process.env.DATABASE_URL_UNPOOLED });
listener.on('error', (err) => console.error('[listen]', err));
listener
  .connect()
  .then(() => listener.query('LISTEN chat'))
  .catch((err) => console.error('[listen] failed:', err));

const clients = new Set<WebSocket>();
const CHANNEL = 'chat';

// Re-push every NOTIFY to this isolate's own clients.
listener.on('notification', (msg) => {
  if (!msg.payload) return;
  for (const socket of clients) {
    if (socket.readyState === socket.OPEN) socket.send(msg.payload);
  }
});

export default {
  fetch(request: Request) {
    if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
      return new Response('This endpoint speaks WebSocket. Send an Upgrade request.', { status: 426 });
    }
    const { socket, response } = upgradeWebSocket(request);
    socket.addEventListener('open', () => clients.add(socket)); // add once the 101 is written
    socket.addEventListener('close', () => clients.delete(socket));
    socket.addEventListener('message', async (event) => {
      const body = String(event.data).trim();
      if (!body) return;
      await pool.query('SELECT pg_notify($1, $2)', [CHANNEL, body]);
    });
    return response;
  },
};
```

Use `DATABASE_URL_UNPOOLED` for the `LISTEN` client. The pooled `DATABASE_URL` routes through PgBouncer, which doesn't support `LISTEN/NOTIFY`.

## Heartbeat

The connection only lives while data moves across it. Neon's idle timeout is 15 minutes, but the proxies and load balancers in between usually drop an idle socket much sooner, sometimes within tens of seconds. Rather than rely on steady app traffic, send a keepalive on a timer.

The standard `WebSocket` from `upgradeWebSocket` has no `ping()` method, so send an application-level message. It arrives as an ordinary message, so the client has to filter it out (for example, ignore a message whose data is `'ping'`):

```ts
const HEARTBEAT_MS = 25_000; // under typical proxy idle timeouts

const beat = setInterval(() => {
  for (const socket of clients) {
    if (socket.readyState === socket.OPEN) socket.send('ping');
  }
}, HEARTBEAT_MS);
beat.unref?.(); // don't hold the process open on the timer alone

process.on('SIGINT', () => clearInterval(beat));
```

`clients` is this isolate's `Set` of live connections, populated where you accept a socket (the feed and chat examples above).

## Server-sent events (SSE)

When you only need server-to-client updates, SSE is simpler than a WebSocket. There's no upgrade handshake and no library to install. A plain `fetch` handler returns a `Response` whose body is a `ReadableStream`, with the `Content-Type` set to `text/event-stream`. The runtime keeps that response open while the stream keeps writing.

```ts filename="functions/sse.ts"
const encoder = new TextEncoder();

export default {
  fetch(request: Request) {
    const url = new URL(request.url);
    if (url.pathname !== '/events') return new Response('ok');

    let count = 0;
    let tick: ReturnType<typeof setInterval>;
    let beat: ReturnType<typeof setInterval>;
    const stream = new ReadableStream<Uint8Array>({
      start(controller) {
        controller.enqueue(encoder.encode('data: connected\n\n'));
        tick = setInterval(() => {
          controller.enqueue(encoder.encode(`data: ${++count}\n\n`));
        }, 1000);
        // A line starting with `:` is a comment. Use it as a heartbeat so the
        // stream never goes idle (proxies drop quiet connections quickly).
        beat = setInterval(() => controller.enqueue(encoder.encode(': ping\n\n')), 25_000);
      },
      cancel() {
        // Fires when the client disconnects.
        clearInterval(tick);
        clearInterval(beat);
      },
    });

    return new Response(stream, {
      headers: { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache, no-transform' },
    });
  },
};
```

An SSE frame is `data: <payload>\n\n`. Send a `: ping\n\n` comment every 25 to 30 seconds, the SSE equivalent of the WebSocket [heartbeat](https://neon.com/docs/compute/functions/websockets#heartbeat), so idle streams stay alive, and set `Cache-Control: no-cache, no-transform` so proxies don't cache or buffer the stream.

On the client, `EventSource` reads the stream and handles reconnection for you, so there's no backoff logic to write:

```ts
const source = new EventSource(`${FUNCTION_URL}/events`); // GET only
source.onmessage = (e) => console.log('update', e.data);
source.onerror = () => {}; // EventSource auto-reconnects
```

Reconnection doesn't replay what it missed: `EventSource` only resumes from a point if you emit an `id:` on each event and read the `Last-Event-ID` request header on reconnect. Without that, events sent during a disconnect are lost, which is fine for a live counter (the next update is current) but not for a feed where every item matters.

To push to every client, fan out across isolates exactly as with WebSockets: hold a `Set` of stream controllers and `enqueue` to each when a new row appears (poll or `NOTIFY`; see [Cross-isolate messaging](https://neon.com/docs/compute/functions/websockets#cross-isolate-messaging)). `EventSource` is GET-only and can't set headers, so authenticate it with a query parameter or cookie, the same as a WebSocket (see [Authentication](https://neon.com/docs/compute/functions/websockets#authentication)).

For a complete SSE backend (Hono endpoint, `LISTEN`/`NOTIFY` fan-out, a counter persisted in Postgres, and a client-only SPA), see the [server-sent events example](https://github.com/neondatabase/examples/tree/main/with-server-sent-events-function).

## Authentication

A function has a public URL, so authenticate the caller before accepting a connection. See [Authentication](https://neon.com/docs/compute/functions/authentication) for the full picture (JWT verification, API keys, CORS).

Browsers can't set custom headers on a WebSocket or an `EventSource`, so you can't use `Authorization`. Pass the token as a query parameter and verify it before accepting the connection. Refusing an unauthenticated connection is the normal case for a WebSocket endpoint.

A browser client can't read why a handshake was refused; it sees only a generic connection failure, not the status or body you returned. Refuse to keep unauthenticated clients out, but send any detail the client needs over a separate authenticated request.

In the snippet below (and in the Hono example above), `verifyToken(token)` is your own check: verify a JWT with `jose`'s `jwtVerify`, or look up an API key, returning the caller's identity or `null`.

Refuse the handshake by returning an ordinary `Response` from `fetch` before you upgrade, so you don't call `upgradeWebSocket` at all until the caller checks out. In a Hono app, do the same as route middleware ahead of the `upgradeWebSocket` helper, as in the [Hono example](https://neon.com/docs/compute/functions/websockets#hono-app-with-websocket).

```ts
async fetch(request: Request) {
  const url = new URL(request.url);
  const token = url.searchParams.get('token');
  const identity = token ? await verifyToken(token) : null; // e.g. jwtVerify with jose

  if (!identity) {
    return new Response('unauthorized', { status: 401 });
  }

  const { socket, response } = upgradeWebSocket(request);
  // authenticated; identity is in scope
  return response;
},
```

For a complete example with JWT verification, Managed Better Auth integration, and client-side reconnection, see the [WebSocket chat example](https://github.com/neondatabase/examples/tree/main/with-websockets-function).

## Eviction and shutdown

On shutdown the platform sends `SIGINT`, then forcibly stops the function 5 seconds later. You don't need to drain the `pg` pool: when the process exits, the OS closes its sockets and Neon's pooler reclaims those connections. Use a `SIGINT` handler only to flush in-flight work that would otherwise be lost, such as clearing the heartbeat timer above.

When the function stops or is evicted, connected clients see their socket drop, and no clean close frame is guaranteed, so build reconnection into the client. The browser's `EventSource` reconnects on its own; a WebSocket client needs its own retry loop, re-minting its token on each attempt since tokens are short-lived.

See [Runtime limits](https://neon.com/docs/compute/functions/reference/runtime-limits) for eviction and timeout behavior.

--- [Document source](https://neon.com/docs/compute/functions/whatsapp-bot.md) ---

> Summary: Host a WhatsApp bot on Neon Functions. Receive WhatsApp Cloud API webhooks, verify Meta's request signatures, reply through the Graph API, and store data in Postgres on the same branch.

# How to host a WhatsApp bot on Neon Functions

Receive WhatsApp messages and reply through the Graph API

Last updated: 2026-10-31

WhatsApp Cloud API sends incoming messages to HTTP webhooks. In this guide, you deploy a [Neon Function](https://neon.com/docs/compute/functions/overview) as the webhook endpoint. The function verifies Meta's requests, handles bot commands and sends replies through the Graph API.

The template uses Drizzle to store user names and command usage in Neon Postgres. See Meta's [WhatsApp Cloud API get started guide](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/) for details about setting up an account and phone number.

**Note: WhatsApp Cloud API only**

This example uses Meta's hosted WhatsApp Cloud API. It doesn't automate a personal WhatsApp account or the WhatsApp Business mobile app.

## Prerequisites

- A Neon project in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). See [Get started with Neon Functions](https://neon.com/docs/compute/functions/get-started).
- The latest [Neon CLI](https://neon.com/docs/cli), installed and authenticated. Upgrade with `npm install -g neon@latest`, then see [CLI login](https://neon.com/docs/cli/login).
- Node.js 24 (`node -v`). Deployed functions run on `nodejs24`, so 24 locally is the closest match. Node.js 20+ works.
- A Meta developer account.
- A Meta app connected to a WhatsApp Business Account, with a Cloud API phone number and a test recipient. Meta's get started flow can create test resources for you.

The example's README and package scripts use npm. The commands in this guide do the same.

## Set up WhatsApp Cloud API

In the Meta App Dashboard, create an app. On **App details**, enter an app name such as `Neon Bot` and continue.

![App details with Neon Bot entered as the app name](https://neon.com/docs/compute/functions/whatsapp-create-app.png)

On **Use cases**, select **Connect with customers through WhatsApp**, then continue through the app creation flow.

![Connect with customers through WhatsApp selected as the app use case](https://neon.com/docs/compute/functions/whatsapp-use-case.png)

Follow Meta's [WhatsApp Cloud API get started guide](https://developers.facebook.com/docs/whatsapp/cloud-api/get-started/) to **WhatsApp** > **API Setup**. Generate an access token, select the phone numbers you'll use for testing and send the first test message.

![WhatsApp API Setup with access token and test phone number details](https://neon.com/docs/compute/functions/whatsapp-api-setup.png)

Keep these values:

- **Access token**: authorizes calls from the function to the Graph API.
- **Phone number ID**: identifies the Cloud API sender used by the function.
- **App secret**: lets the function verify the `X-Hub-Signature-256` header on incoming webhook POSTs.

The temporary access token from the API setup flow expires quickly. To keep developing the bot, follow Meta's instructions to create a system user and permanent access token.

Create a separate webhook verify token with any strong random value that only you and Meta know:

```bash
openssl rand -hex 32
```

Save the output locally. You'll use the same value for `WHATSAPP_VERIFY_TOKEN` and Meta's **Verify token** field.

**Warning:** Treat the access token, app secret and webhook verify token like passwords. Never commit them or paste them into screenshots, tickets or chat.

## Scaffold the project

`neon bootstrap` copies the WhatsApp HTTP example into a new directory and prompts you to install dependencies and set up the project. Accept the prompts. Pass `--no-link` to skip linking for now; you'll [link](https://neon.com/docs/cli/link) in the next step, after creating `.env.local`, so Neon writes its variables straight into that file. The template ID is `whatsapp-bot-http`:

```bash
neon bootstrap my-whatsapp-bot --template whatsapp-bot-http --no-link
cd my-whatsapp-bot
```

See [`neon bootstrap`](https://neon.com/docs/cli/bootstrap) for flags. Run the remaining commands from that directory.

`neon.ts` declares one function named `whatsapp` and passes the four WhatsApp variables into its environment:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  functions: {
    whatsapp: {
      name: "WhatsApp webhook",
      source: "./functions/whatsapp.ts",
      env: {
        WHATSAPP_ACCESS_TOKEN: process.env.WHATSAPP_ACCESS_TOKEN!,
        WHATSAPP_PHONE_NUMBER_ID: process.env.WHATSAPP_PHONE_NUMBER_ID!,
        WHATSAPP_VERIFY_TOKEN: process.env.WHATSAPP_VERIFY_TOKEN!,
        WHATSAPP_APP_SECRET: process.env.WHATSAPP_APP_SECRET!,
      },
      dev: {
        port: 8787,
      },
    },
  },
});
```

The `whatsapp` key is the function slug. It appears in CLI commands and the invocation URL. See the [`neon.ts` reference](https://neon.com/docs/reference/neon-ts).

Deploy the function before connecting Meta. Meta needs a public HTTPS callback URL, so you don't need `npm run dev`.

## Add WhatsApp secrets

The deploy script runs `neon deploy --env .env.local`, the same convention as Next.js and `vercel env pull`. Bootstrap scaffolds a `.env.example` but no `.env.local`. Install dependencies, copy the example, then link. `neon link` loads `neon.ts` to pull the branch's variables, so the packages must be installed first:

```bash
npm install
cp .env.example .env.local
neon link
```

Linking merges `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `NEON_BRANCH`, `NEON_BRANCH_ID`, and `NEON_FUNCTION_HOST_SUFFIX` into `.env.local`, leaving the WhatsApp keys untouched. Uncomment and add them:

```env filename=".env.local"
# Required. Add real values before deploying; a missing key throws at deploy, an empty one uploads "".
# WHATSAPP_ACCESS_TOKEN=
# WHATSAPP_PHONE_NUMBER_ID=
# WHATSAPP_VERIFY_TOKEN=
# WHATSAPP_APP_SECRET=

# Written into `.env.local` by `neon link`.
NEON_BRANCH=
DATABASE_URL=
DATABASE_URL_UNPOOLED=
NEON_BRANCH_ID=
NEON_FUNCTION_HOST_SUFFIX=
```

Set `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID` and `WHATSAPP_APP_SECRET` to the values from Meta. Set `WHATSAPP_VERIFY_TOKEN` to the random value you generated.

Leave the pulled `NEON_*` and `DATABASE_URL*` values as written. Neon also injects them into the deployed function. See [Environment variables](https://neon.com/docs/compute/functions/environment-variables).

## Deploy the function

Deploy the function with the WhatsApp secrets from `.env.local`:

```bash
npm run deploy
```

The script runs `neon deploy --env .env.local`. The CLI evaluates `neon.ts`, bundles the handler and waits for the deployment to finish. If the deployment fails, check [function logs](https://neon.com/docs/compute/functions/logs) and [Deploy and manage functions](https://neon.com/docs/compute/functions/deploy).

Deployed environment variables are a snapshot of `.env.local` at deployment time. Run `npm run deploy` again after changing any WhatsApp value.

## Apply the database schema

```bash
npm run db:push
```

`neon link` wrote `DATABASE_URL` into `.env.local`, so you can apply the schema any time after linking. `/ping` works without the tables; `/name` and `/profile` need them.

## Set the webhook

Your callback URL is the `whatsapp` function's URL with the path `/api/webhook`. `npm run deploy` prints it in the **Function URLs** list, and `neon functions get whatsapp` shows it in its `URL` field:

```text
https://br-cool-darkness-123456-whatsapp.compute.c-2.us-east-2.aws.neon.tech/api/webhook
```

Your URL will differ. Use your own `whatsapp` URL; the host is specific to your branch.

In the Meta App Dashboard, open **WhatsApp** > **Configuration**. Enter:

- **Callback URL**: the full Neon URL ending in `/api/webhook`
- **Verify token**: the exact value of `WHATSAPP_VERIFY_TOKEN`

Select **Verify and save**. Meta sends a GET request with `hub.mode`, `hub.verify_token` and `hub.challenge`. The function checks that the mode is `subscribe` and the token matches, then returns the challenge as plain text.

![WhatsApp webhook configuration with callback URL, verify token and Verify and save highlighted](https://neon.com/docs/compute/functions/whatsapp-configuration.png)

Once Meta verifies the webhook, subscribe to the **messages** field. Meta uses this field for incoming messages and outgoing message status updates. See Meta's [webhook setup guide](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks/) and [messages webhook reference](https://developers.facebook.com/docs/whatsapp/cloud-api/webhooks/components/).

If verification fails:

- Confirm that the callback URL ends in `/api/webhook`.
- Confirm that Meta's verify token exactly matches `WHATSAPP_VERIFY_TOKEN`.
- Redeploy after editing `.env.local`.
- Check [function logs](https://neon.com/docs/compute/functions/logs).

Opening the callback URL directly in a browser returns `403 invalid verify token`. That's expected because a normal browser request doesn't contain Meta's verification query parameters.

## Try /ping

Use a WhatsApp account registered as a test recipient to send `/ping` to the Cloud API phone number. The bot should reply with `Pong` and an estimated webhook latency.

WhatsApp doesn't need a separate command registration step. The function parses incoming text messages directly.

If the bot doesn't reply:

- Confirm that webhook verification succeeded and the **messages** field is subscribed.
- Confirm that you sent the message to the phone number associated with `WHATSAPP_PHONE_NUMBER_ID`.
- Check whether a temporary `WHATSAPP_ACCESS_TOKEN` expired.
- Confirm that `WHATSAPP_APP_SECRET` matches the Meta app. A mismatch causes POST signature verification to return `401`.
- Redeploy after changing `.env.local`, then check [function logs](https://neon.com/docs/compute/functions/logs).

## How it works

`functions/whatsapp.ts` handles GET verification requests and POST webhook deliveries at `/api/webhook`. The GET path checks the mode and verify token, then returns the challenge value as plain text.

**Important: Verify the raw body**

Call `request.text()` and verify the signature before `JSON.parse`. Meta computes `X-Hub-Signature-256` from the exact request body with your app secret. Parsing and serializing the payload first can change its bytes and invalidate the signature.

For a POST, the handler reads the raw body, verifies its HMAC signature with the app secret and only then parses the JSON:

```ts filename="functions/whatsapp.ts"
const body = await request.text();
const isVerified = verifyWhatsAppRequest({
  appSecret: getWhatsAppAppSecret(),
  body,
  signature: request.headers.get("x-hub-signature-256"),
});

if (!isVerified) {
  return jsonResponse({ error: "invalid request signature" }, { status: 401 });
}

let payloadBody: unknown;

try {
  payloadBody = JSON.parse(body);
} catch {
  return jsonResponse({ error: "invalid json" }, { status: 400 });
}

const parsedPayload = whatsAppWebhookPayloadSchema.safeParse(payloadBody);

if (!parsedPayload.success) {
  return jsonResponse({ error: "invalid whatsapp webhook payload" }, { status: 400 });
}
```

The handler extracts entries that contain a `messages` array. For each incoming message, it:

1. Tries to mark the message as read.
2. Handles an interactive button reply if one is present.
3. Parses a text command.
4. Runs the matching command handler.
5. Sends the result through the Graph API as a reply to the triggering message.

Read status updates and command usage tracking are best effort. A failure in either task doesn't block the command reply. Valid status webhooks don't contain an incoming `messages` array, so the handler acknowledges them without running a command.

<details>

<summary>View full code: </summary>

```typescript
import { WHATSAPP_WEBHOOK_PATH } from "../src/constants/whatsapp.js";
import {
  getWhatsAppAccessToken,
  getWhatsAppAppSecret,
  getWhatsAppPhoneNumberId,
  getWhatsAppVerifyToken,
} from "../src/env.js";
import { whatsAppWebhookPayloadSchema } from "../src/schemas/whatsapp.js";
import type {
  WhatsAppMessage,
  WhatsAppMessageContext,
  WhatsAppMessageHandlerContext,
  WhatsAppWebhookPayload,
} from "../src/types/whatsapp.js";
import { createButtonTestClickMessage, parseButtonTestCallbackData } from "../src/utils/generalComponents.js";
import { jsonResponse } from "../src/utils/jsonResponse.js";
import { markWhatsAppMessageAsRead, sendWhatsAppMessage } from "../src/utils/whatsappApi.js";
import { commandHandlers, trackWhatsAppCommandRun } from "../src/utils/whatsappCommands.js";
import { createErrorMessage } from "../src/utils/whatsappResponses.js";
import { parseWhatsAppCommand } from "../src/utils/whatsappText.js";
import {
  verifyWhatsAppRequest,
  verifyWhatsAppWebhookChallenge,
} from "../src/utils/verifyWhatsAppRequest.js";

const getWhatsAppMessages = (payload: WhatsAppWebhookPayload): WhatsAppMessage[] =>
  payload.entry?.flatMap((entry) => entry.changes?.flatMap((change) => change.value?.messages ?? []) ?? []) ?? [];

const getButtonReplyId = (message: WhatsAppMessage): string | undefined =>
  message.interactive?.type === "button_reply" ? message.interactive.button_reply?.id : undefined;

const markIncomingMessageAsRead = async ({
  accessToken,
  message,
  phoneNumberId,
}: WhatsAppMessageContext): Promise<void> => {
  if (!message.id) {
    return;
  }

  try {
    await markWhatsAppMessageAsRead({ accessToken, messageId: message.id, phoneNumberId });
  } catch (error) {
    console.error("WhatsApp read status update failed.", error);
  }
};

const handleButtonReply = async ({
  accessToken,
  message,
  phoneNumberId,
}: WhatsAppMessageContext): Promise<boolean> => {
  const buttonReplyId = getButtonReplyId(message);
  const action = buttonReplyId ? parseButtonTestCallbackData(buttonReplyId) : undefined;

  if (!buttonReplyId) {
    return false;
  }

  await sendWhatsAppMessage({
    accessToken,
    phoneNumberId,
    replyToMessageId: message.id,
    ...(action
      ? createButtonTestClickMessage(message.from, action)
      : createErrorMessage(message.from, "That button is not handled by this bot.")),
  });

  return true;
};

const handleMessage = async ({
  accessToken,
  message,
  phoneNumberId,
  request,
  url,
}: WhatsAppMessageHandlerContext): Promise<void> => {
  await markIncomingMessageAsRead({ accessToken, message, phoneNumberId });

  if (await handleButtonReply({ accessToken, message, phoneNumberId })) {
    return;
  }

  const command = parseWhatsAppCommand(message.text?.body);

  if (!command) {
    return;
  }

  const commandHandler = commandHandlers[command.name];

  if (commandHandler) {
    void trackWhatsAppCommandRun(message, command.name);

    const responseMessage = await commandHandler({
      accessToken,
      args: command.args,
      command: command.name,
      message,
      phoneNumberId,
      request,
      url,
    });

    await sendWhatsAppMessage({
      accessToken,
      phoneNumberId,
      replyToMessageId: message.id,
      ...responseMessage,
    });

    return;
  }

  await sendWhatsAppMessage({
    accessToken,
    phoneNumberId,
    replyToMessageId: message.id,
    ...createErrorMessage(message.from, "Unknown command. Try /help."),
  });
};

export default async function handler(request: Request): Promise<Response> {
  const url = new URL(request.url);

  if (request.method === "GET") {
    const isVerified = verifyWhatsAppWebhookChallenge({
      mode: url.searchParams.get("hub.mode"),
      token: url.searchParams.get("hub.verify_token"),
      verifyToken: getWhatsAppVerifyToken(),
    });

    if (!isVerified) {
      return new Response("invalid verify token", { status: 403 });
    }

    return new Response(url.searchParams.get("hub.challenge") ?? "", {
      headers: { "content-type": "text/plain" },
    });
  }

  if (request.method !== "POST") {
    return jsonResponse({ error: "method not allowed" }, { status: 405 });
  }

  const body = await request.text();
  const isVerified = verifyWhatsAppRequest({
    appSecret: getWhatsAppAppSecret(),
    body,
    signature: request.headers.get("x-hub-signature-256"),
  });

  if (!isVerified) {
    return jsonResponse({ error: "invalid request signature" }, { status: 401 });
  }

  let payloadBody: unknown;

  try {
    payloadBody = JSON.parse(body);
  } catch {
    return jsonResponse({ error: "invalid json" }, { status: 400 });
  }

  const parsedPayload = whatsAppWebhookPayloadSchema.safeParse(payloadBody);

  if (!parsedPayload.success) {
    return jsonResponse({ error: "invalid whatsapp webhook payload" }, { status: 400 });
  }

  const accessToken = getWhatsAppAccessToken();
  const phoneNumberId = getWhatsAppPhoneNumberId();
  const messages = getWhatsAppMessages(parsedPayload.data);

  for (const message of messages) {
    await handleMessage({ accessToken, message, phoneNumberId, request, url });
  }

  return jsonResponse({ ok: true });
}

```

</details>

View it on [GitHub](https://github.com/neondatabase/examples/blob/main/bots/whatsapp-bot-http/functions/whatsapp.ts).

## Commands

The template supports:

- `/ping`: returns `Pong` with latency estimated from the incoming message timestamp.
- `/info`: shows the Node.js version, platform, request method, Neon branch and function URL.
- `/help`: builds a command list from the template's command definitions.
- `/buttons`: sends **Refresh**, **Echo** and **Time** interactive reply buttons.
- `/name Dana Smith`: stores a name for the sender's WhatsApp user ID. `/name` without an argument returns the stored value.
- `/profile`: shows the stored name, total commands run and per-command usage.

The parser also accepts command names without the leading slash. An unrecognized command returns `Unknown command. Try /help.` The function ignores messages that don't match the command syntax.

The `/buttons` callbacks use the IDs `button-test:refresh`, `button-test:echo` and `button-test:time`. The handler processes `interactive.button_reply` events before text commands:

- **Refresh** sends the button panel again with a UTC timestamp.
- **Echo** confirms that interactive replies work.
- **Time** returns the current server time in UTC.

Text responses and button panels are sent through the same Graph API `messages` endpoint. When Meta includes an incoming message ID, the bot adds it as reply context.

The `/name` and `/profile` commands use Postgres via Drizzle. If the database misses a 2.5-second deadline, the bot replies "Warming up"; run the command again once the branch is warm.

## Related templates

- [Discord HTTP bot](https://github.com/neondatabase/examples/tree/main/bots/discord-bot-http)
- [Telegram HTTP bot](https://github.com/neondatabase/examples/tree/main/bots/telegram-bot-http)

## Example

Create a copy of the example with the Neon CLI:

```bash
neon bootstrap my-whatsapp-bot --template whatsapp-bot-http
cd my-whatsapp-bot
```

You can find the example in [`bots/whatsapp-bot-http`](https://github.com/neondatabase/examples/tree/main/bots/whatsapp-bot-http).

--- [Document source](https://neon.com/docs/concepts/branch-your-backend.md) ---

> Summary: A branch is an isolated copy of your whole Neon backend that starts from its parent's state when you create it. It includes the parent's enabled services: Lakebase Postgres, Managed Better Auth, Object Storage, Functions, and the AI Gateway. Most later changes stay on the branch. The exceptions to know: a restore rolls back Postgres and Auth only (not buckets or functions), the AI Gateway model catalog is global, and logical replication is not copied.

# Branch your backend

How branching works across the backend

Last updated: 2026-09-24

A **branch** is an isolated copy of your whole Neon backend. Like a Git branch, you create it from an existing branch and make changes freely on that child branch, without affecting the original.

A branch includes any services already enabled on its parent: Lakebase Postgres, Managed Better Auth, Object Storage, Functions, and the AI Gateway. When you create a branch, the exact handling depends on each service: some copy state, some share underlying storage until you write, and some create branch-specific endpoints and credentials with no data to copy.

![Three branch lanes over time (main, dev, and a feature branch). Each fork carries along the services enabled on the parent, and the branches then diverge independently.](https://neon.com/docs/concepts/branch-your-backend.png)

## When to branch

A branch gives you a full backend to work against, so you can make changes without affecting its parent, for example your production or staging branch.

- **Preview environments.** Create one branch for each pull request or preview deployment, so reviewers see the change running against its own data, users, and buckets.
- **Testing against production-like data.** Test migrations, destructive queries, and schema changes on a branch that starts from production-like data, then delete the branch.
- **Isolated development.** Use one branch per developer or feature instead of sharing one staging backend.
- **Temporary environments for CI and agents.** Create a branch for each CI run or AI-agent task, then delete it when the work is done.

## What a branch includes

When you create a branch, it starts with the services enabled on its parent. Here is how each one branches.

### Postgres branching

A Postgres branch starts with the parent's data as of the point of branch creation. Your writes stay on the branch, and the parent is unchanged. Nothing is copied up front: the branch stores its own copy of a data page only when it changes one. The [Data API](https://neon.com/docs/data-api/overview) serves the same database over HTTP, and each branch has its own Data API endpoint.

![Copy-on-write: the child branch shares the parent's data pages and stores its own copy only for the pages it changes. The parent is unchanged.](https://neon.com/docs/concepts/branch-postgres.png)

### Auth branching

Managed Better Auth needs no separate setup on a branch. Users, sessions, and organizations are stored in the `neon_auth` schema inside the branch's database, so they are included when the database branches. See [Branching authentication](https://neon.com/docs/auth/branching-authentication).

![Managed Better Auth data is stored in the neon\_auth schema inside Postgres, so it branches with the database.](https://neon.com/docs/concepts/branch-auth.png)

### Object Storage branching

A branch inherits the parent's buckets and objects without copying them up front. You can overwrite or delete an inherited object right away, and that change is local to the branch. The parent's objects are unchanged. See [Bucket branching](https://neon.com/docs/storage/buckets#bucket-branching).

![The child branch inherits the parent's objects and stores its own version only for the objects it overwrites. The parent is unchanged.](https://neon.com/docs/concepts/branch-object-storage.png)

### Functions branching

A branch inherits the parent's deployed functions and can run them immediately, at the branch's own invocation URL and against the branch's data, with no deploy. The first time you deploy a function on the branch, the branch gets its own version. The parent's version stays as it was.

![The child branch runs the parent's functions with no deploy, and gets its own version after its first deploy. The parent stays on the previous version.](https://neon.com/docs/concepts/branch-functions.png)

### AI Gateway branching

Each branch gets its own AI Gateway endpoint and credentials, so there is no branch data to copy. Everything else is shared across your account rather than set per branch: the [model catalog](https://neon.com/docs/ai-gateway/models), routing, rate limits, and your organization's [prepaid credit balance](https://neon.com/docs/ai-gateway/prepaid-credits) are the same for every branch, and you choose a model on each request.

![Each branch has its own AI Gateway endpoint and credentials, but shares one global model catalog.](https://neon.com/docs/concepts/branch-ai-gateway.png)

Branching does not change the shape of your account or project. For what contains what, see [The Neon object model](https://neon.com/docs/concepts/the-object-model).

## Why branching is instant

Branch creation is fast and does not grow with the size of your data, because no service copies its data up front. Each one branches by sharing or inheriting from its parent instead of duplicating it, so the whole backend forks in seconds no matter how much it holds. Lakebase Postgres is the clearest example: with copy-on-write, the branch shares the parent's data until it changes something, then stores only what changed. The other services follow the same principle, inheriting their state or simply getting their own branch-scoped endpoints. Because of this:

- Branch creation time does not depend on how much data you have.
- A Postgres branch adds storage primarily for what it changes, not a second full copy.
- Your changes stay on the branch and do not affect the parent or sibling branches.

You can create a branch from the parent's current state, or from an earlier point within the project's [history window](https://neon.com/docs/introduction/history-window). To pick up later changes from the parent, [reset the branch from its parent](https://neon.com/docs/guides/reset-from-parent).

This works because storage is separate from compute: durable data can start a new branch without being copied first, and each branch runs its own compute against that data. See [The lakebase architecture](https://neon.com/docs/introduction/architecture-overview).

## Limits and caveats

- **A restore rolls back Postgres and Auth only.** Restoring a branch rolls back its Postgres timeline, including Managed Better Auth data stored in the `neon_auth` schema. It does not roll back Object Storage buckets or objects, and it does not roll back deployed functions. See [Backup & restore](https://neon.com/docs/guides/backup-restore). A [reset from parent](https://neon.com/docs/guides/reset-from-parent) behaves differently: it does roll back Object Storage buckets and objects to the parent's state, though it still does not roll back functions.
- **AI Gateway configuration is global.** Branches get their own AI Gateway endpoint and credentials, but the model catalog, routing, rate limits, and your organization's prepaid credit balance are shared. Usage on every branch draws down the same credit balance. A branch can call a different model by sending a different `model` value in the request; it cannot have its own model catalog.
- **Logical replication is not copied.** A branch does not inherit logical replication slots or subscriptions. Set up replication again on the branch if it needs to publish or subscribe.
- **Not every service is available in every region.** Object Storage, Functions, and the AI Gateway currently run in four regions. See [Product availability](https://neon.com/docs/introduction/regions#product-availability).

## Where to go next

- [Branching](https://neon.com/docs/introduction/branching): How branching works in Lakebase Postgres, and the workflows it's for
- [Branching authentication](https://neon.com/docs/auth/branching-authentication): Test sign-in, OAuth, and permissions on a branch of your own
- [Bucket branching](https://neon.com/docs/storage/buckets#bucket-branching): How buckets and objects reach a child branch, and what diverges
- [Functions](https://neon.com/docs/compute/functions/overview): Your backend code on a branch, at the branch's own URL
- [The AI Gateway](https://neon.com/docs/ai-gateway/overview): A per-branch endpoint and credentials over one shared model catalog
- [The Neon object model](https://neon.com/docs/concepts/the-object-model): How organizations, projects, and branches contain the backend

--- [Document source](https://neon.com/docs/concepts/credentials-access.md) ---

> Summary: Neon uses a different credential for each job: API keys manage your projects, branches, and settings; scoped credentials do your running app's work in Object Storage and the AI Gateway; a database connection credential reaches Postgres; and the Data API takes a JWT that runs each query as a Postgres role. Scoped credentials are limited by their scopes and anchored to a branch and its descendants. Your access to a project is your organization role plus any per-project grant. IP Allow and Private Networking gate the Postgres endpoint; the other services are gated by their credentials.

# Credentials & access

How API keys, scoped credentials, permissions, and network controls govern access to your backend

Last updated: 2026-09-15

Access to your Neon backend runs on a handful of credentials, one for each kind of job: an **API key** manages your setup, a **scoped credential** does your running app's work, a **database connection credential** reaches Postgres, and a **JWT** authorizes end users through the Data API.

The most important line to draw is between the first two. An API key manages your setup and can mint scoped credentials, so keep API keys out of your app's runtime and give each workload its own scoped credential.

![Diagram of Neon's two credential kinds: API keys that manage your Neon setup, and scoped credentials that your app holds, scoped and anchored to a branch. An arrow shows API keys issuing scoped credentials.](https://neon.com/docs/concepts/credentials-access.png)

Availability differs by product and by region. See [Product availability](https://neon.com/docs/introduction/regions#product-availability).

## Which credential do you need?

Match what you're doing to the credential that does it. Each row has its own section below:

| Goal                                                                          | Use                                                                                                                  | Scope and reach                                                                                                                                          |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create or manage projects, branches, and settings, or issue other credentials | [API keys](https://neon.com/docs/concepts/credentials-access#api-keys)                                               | Personal keys act with your effective access; organization keys cover one organization; project-scoped keys cover one project and can't reach outside it |
| Have a workload read files or call models                                     | [Scoped credentials](https://neon.com/docs/concepts/credentials-access#scoped-credentials)                           | By its scopes, such as `storage:read`, plus a branch anchor that covers the branch and its descendants                                                   |
| Connect to Postgres                                                           | [Postgres connection credentials](https://neon.com/docs/concepts/credentials-access#postgres-connection-credentials) | IP Allow and Private Networking apply here, and only here                                                                                                |
| Authorize an end user through the Data API                                    | [End-user JWTs](https://neon.com/docs/concepts/credentials-access#end-user-jwts)                                     | Trust is registered on the project, and `GRANT`s and RLS in your database decide what the query can do                                                   |

## API keys

An API key is a bearer token for the [Neon API](https://neon.com/docs/reference/api), and there's one API surface for the whole platform rather than one per product, so a single key covers Postgres, Object Storage, the AI Gateway, Functions, and Managed Better Auth alike. Keys come in three kinds with decreasing reach:

- **Personal keys** act as you.
- **Organization keys** cover one organization.
- **Project-scoped keys** cover one project.

An API key can create a scoped credential, but a scoped credential cannot create or manage anything, so keep API keys out of your application runtime. See [Manage API keys](https://neon.com/docs/manage/api-keys).

You can also sign the CLI in with `neon login`; it then acts with your access, like a personal key. For scripts and CI, give the CLI an API key instead. See [CLI authentication](https://neon.com/docs/cli/login).

![Diagram of the three API key kinds nested by decreasing reach: personal keys, then organization keys, then project-scoped keys.](https://neon.com/docs/concepts/credentials-api-key-kinds.png)

## Scoped credentials

Most of what your running app connects to uses scoped credentials. Object Storage and the AI Gateway use one shared credential, and the scopes you attach decide what it unlocks:

- `storage:read` and `storage:write` for Object Storage.
- `ai_gateway:invoke` for the AI Gateway.

A credential has two independent dimensions: its scopes say what it can do, and its branch anchor says where it reaches. See [Object storage authentication](https://neon.com/docs/storage/authentication) and [AI Gateway authentication](https://neon.com/docs/ai-gateway/authentication).

![Diagram of a scoped credential defined by two independent things: the scopes that say what it can do, and the branch anchor that says where it reaches.](https://neon.com/docs/concepts/credentials-scope-branch.png)

### A branch and its descendants

A credential is tied to the branch you create it on. It works on that branch and on any branch that comes from it, now or later. So a credential created on your default branch reaches nearly every branch in your project, which is handy for preview branches. For production, create a credential on the specific branch that needs it, so its reach stays narrow. See [The object model](https://neon.com/docs/concepts/the-object-model) and [Branching](https://neon.com/docs/introduction/branching).

![Diagram of a credential anchored on a branch reaching that branch and its descendants but not its ancestors or sibling branches.](https://neon.com/docs/concepts/credentials-branch-anchor.png)

### S3 keys and bearer tokens

A scoped credential comes in the form each service expects: an S3-compatible access key for Object Storage, and a bearer token for services you call over HTTP, like the AI Gateway. Both are the same underlying credential, so if you revoke or delete it, both stop working at once. You cannot change a credential's scopes or branch after you create it. To rotate the secret while keeping the same credential, scopes, and branch, use `neon credentials rotate`. To change the scopes or branch, create a new credential and revoke the old one. See [Object storage authentication](https://neon.com/docs/storage/authentication#mapping-to-your-s3-sdk).

### Functions

A Neon Function is given a scoped credential for the branch it runs on, so your code can reach Object Storage and the AI Gateway on that branch without you adding a secret. But the function has a public HTTPS URL, and Neon does not check who is calling it. Authenticating incoming requests is up to you, in your handler. See [Environment variables](https://neon.com/docs/compute/functions/environment-variables) and [Neon Functions authentication](https://neon.com/docs/compute/functions/authentication).

## Postgres connection credentials

Connecting to Postgres uses a database connection credential: a Postgres role and its password, in the connection string your app or client uses. See [Connect to Neon](https://neon.com/docs/connect/connect-intro).

IP Allow and Private Networking gate the Postgres endpoint, and only the Postgres endpoint. Object Storage, the AI Gateway, and Function URLs are protected by their credentials instead. See [IP Allow](https://neon.com/docs/introduction/ip-allow) and [Private Networking](https://neon.com/docs/guides/neon-private-networking).

**Important: Network controls don't cover every service**

IP Allow and Private Networking gate the Postgres endpoint. They don't restrict requests to Object Storage, the AI Gateway, or Function URLs. For those services the credential is the access control, so scope it and anchor it deliberately.

## End-user JWTs

The [Data API](https://neon.com/docs/data-api/overview) and [Managed Better Auth](https://neon.com/docs/auth/overview) authenticate end users with JWTs. A request carries a JWT from an issuer the project trusts, Neon selects a Postgres role from it, and the query runs as that role, so your `GRANT`s and RLS decide what it can do. See [Manage the Data API](https://neon.com/docs/data-api/manage) and [Access control & security](https://neon.com/docs/data-api/access-control).

![Diagram of an end user's JWT verified by the Data API and run as a Postgres role whose access is governed by GRANTs and row-level security.](https://neon.com/docs/concepts/credentials-data-api-jwt.png)

## Who can access a project

Your access on a project is your organization role plus any per-project grant you hold, and a per-project grant only adds access, never removes it. A personal API key's reach follows this rule, which is why it tracks its owner's current access rather than being fixed at creation. See [User permissions](https://neon.com/docs/manage/user-permissions) and the [Permissions quickstart](https://neon.com/docs/manage/project-permissions-get-started).

## Where to go next

- [Manage API keys](https://neon.com/docs/manage/api-keys): Create, list, and revoke personal, organization, and project-scoped keys.
- [Object storage authentication](https://neon.com/docs/storage/authentication): Create a credential and use it with an AWS SDK.
- [AI Gateway authentication](https://neon.com/docs/ai-gateway/authentication): Create a bearer credential for model calls.
- [User permissions](https://neon.com/docs/manage/user-permissions): Organization roles, per-project grants, and how they combine.
- [Data API access control](https://neon.com/docs/data-api/access-control): How JWT verification, roles, and RLS secure the Data API.
- [IP Allow](https://neon.com/docs/introduction/ip-allow): Restrict database connections to trusted addresses.
- [Connect your app](https://neon.com/docs/connect/connect-intro): Connect your app to Postgres, Object Storage, the AI Gateway, and the Data API, one branch at a time.

--- [Document source](https://neon.com/docs/concepts/the-object-model.md) ---

> Summary: The Neon backend is structured as an organization, a project, and a branch. The branch is where the backend runs: Lakebase Postgres, Managed Better Auth, Object Storage, Functions, and the AI Gateway. A child branch is an isolated copy of that backend. Organizations hold billing, membership, and projects. A project sets the region and groups branches. Postgres and Object Storage use copy-on-write; Auth state lives in the database and branches with it; Functions and the AI Gateway get per-branch URLs and credentials. The AI Gateway model catalog is global. Computes, roles, databases, and the Data API belong to Postgres. API keys are scoped to an account, organization, or project, not to a branch.

# The Neon object model

How the Neon backend is structured

Last updated: 2026-10-13

On Neon, a **branch** is where your backend runs. It can include Lakebase Postgres, Managed Better Auth, Object Storage, Functions, and the AI Gateway.

You can create a child branch from the current or past state of another branch, starting from your `production` branch. Change it and delete it without affecting the original. That's useful for a preview, a pull request, or an experiment: you get a cloned backend to work against, not a second project to provision.

Every branch belongs to a **project**, and every project belongs to an **organization**.

![Tree diagram of the Neon object model. An organization contains projects (one region per project). A project contains branches. A branch holds five services: Lakebase Postgres, Managed Better Auth, Object Storage, Functions, and the AI Gateway. Lakebase Postgres has four children: computes, roles, databases, and the Data API.](https://neon.com/docs/concepts/the-object-model.png)

In the Neon Console, API, and CLI, the hierarchy is `org_id` → `project_id` → `branch_id`. Connection strings, Auth URLs, function URLs, and the AI Gateway endpoint all belong to a branch. An API key is scoped to an account, an organization, or a project, so the same key can reach every branch in that scope. See [What sits outside the hierarchy](https://neon.com/docs/concepts/the-object-model#what-sits-outside-the-hierarchy).

## The hierarchy

An **organization** is the top-level container for your Neon projects. Billing, membership, and project ownership live at this level. One Neon account can belong to several organizations, and you can transfer projects between them. See [Organizations](https://neon.com/docs/manage/organizations).

A **project** is the workspace that groups your branches and holds the settings they share. You choose a [region](https://neon.com/docs/introduction/regions) when you create the project, and it's fixed for the life of the project. Other project-level settings, such as the history window for instant restore, IP Allow rules, and project access, apply to every branch inside it. Each project is fully isolated, with separate data and credentials, which makes a project the right boundary for an app or a tenant that must stay separate. See [Projects](https://neon.com/docs/manage/projects) and [Multitenancy](https://neon.com/docs/guides/multitenancy).

A **branch** sits inside a project. Every project starts with a root branch you can't delete (`production` in the Neon Console, `main` via API or CLI). Every other branch is created as a child of an existing branch. Create a new project, rather than a branch, when you need a different region or a tenant that must stay fully separate. See [Manage branches](https://neon.com/docs/manage/branches).

## A full backend per branch

When you create a child branch, it includes the same services enabled on its parent. What gets copied, shared, or re-created depends on the service.

| Service                                                           | What lives on the branch                                                                                                                                   | What a child branch gets                                                                                                                                                                     |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**Lakebase Postgres**](https://neon.com/docs/postgres/overview)  | Serverless Postgres. You connect through a compute on the branch (`ep-...` in the connection string).                                                      | A copy-on-write clone of the parent's data at the moment you branch. Writes stay separate.                                                                                                   |
| [**Managed Better Auth**](https://neon.com/docs/auth/overview)    | Sign-in, users, sessions, and auth config. State lives in the branch's database, so there is nothing extra to provision. Each branch has its own Auth URL. | A copy of the whole database, including the `neon_auth` schema where its users and sessions live. See [Branching authentication](https://neon.com/docs/auth/branching-authentication).       |
| [**Object Storage**](https://neon.com/docs/storage/overview)      | S3-compatible buckets and objects.                                                                                                                         | A copy-on-write clone of existing buckets and objects. See [Buckets](https://neon.com/docs/storage/buckets).                                                                                 |
| [**Functions**](https://neon.com/docs/compute/functions/overview) | Your backend code, deployed on the branch, at its own function URL.                                                                                        | The same function at its own function URL, against this branch's data.                                                                                                                       |
| [**AI Gateway**](https://neon.com/docs/ai-gateway/overview)       | One credential for all models across every major LLM provider. Each branch has its own endpoint, credentials, access, and metering.                        | A new endpoint and credentials, with usage metered on that branch. The [model catalog](https://neon.com/docs/ai-gateway/models) is shared and global: you don't configure models per branch. |

Object Storage, Functions, and the AI Gateway aren't available in every region yet. See [Product availability](https://neon.com/docs/introduction/regions#product-availability).

### What Lakebase Postgres contains

You connect as a [role](https://neon.com/docs/manage/roles) to a [database](https://neon.com/docs/manage/databases) through a [compute](https://neon.com/docs/manage/computes). A branch has one read-write compute and can have multiple [read replicas](https://neon.com/docs/introduction/read-replicas). Autoscaling and scale to zero are settings on the compute. The compute runs Postgres; it does not own the data. Durable database storage sits in a separate storage layer. That separation of storage and compute is what defines Lakebase Postgres. See [The lakebase architecture](https://neon.com/docs/introduction/architecture-overview).

The [Data API](https://neon.com/docs/data-api/overview) is an HTTP interface to the same database, for callers that can't open a Postgres TCP connection, such as browsers and edge runtimes.

## What sits outside the hierarchy

- **Your Neon account.** The account is how you sign in. It isn't a container for resources, and it can belong to several organizations. See [Accounts](https://neon.com/docs/manage/accounts).
- **API keys.** A key is personal (your account), organization-scoped, or project-scoped. None of those scopes is a branch. See [Manage API keys](https://neon.com/docs/manage/api-keys).
- **Region.** The region is set on the project when you create it. Every branch in the project inherits it. See [Regions](https://neon.com/docs/introduction/regions).

## Where to go next

- [The lakebase architecture](https://neon.com/docs/introduction/architecture-overview): How compute and durable storage are separated underneath Postgres
- [Branching](https://neon.com/docs/introduction/branching): What branches are for and how to work with them
- [How a Neon backend fits together](https://neon.com/docs/get-started/backend-overview): One example app built across all five services

--- [Document source](https://neon.com/docs/connect/choose-connection.md) ---

> Summary: Decision guide for mapping each deployment environment to the correct Neon driver and transport. TCP with pg or postgres.js suits long-lived servers. @neondatabase/serverless over HTTP or WebSocket suits Cloudflare Workers and Netlify. The Data API suits browser apps. Use this page when choosing between pooled and direct connections, or when debugging double-pooling or WebSocket lifecycle errors in serverless request handlers. ORM compatibility for Drizzle, Prisma, Kysely, and TypeORM is also covered.

# Choosing your connection method

Find the right driver and connection type for your deployment platform

Last updated: 2026-09-14

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](https://neon.com/docs/connect/choose-connection#find-your-scenario) further down the page.

| Environment                                                                                                                        | Recommended driver         | Pooling                                                                         | Guide                                                                   |
| ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| [Any platform (non-JS/TS)](https://neon.com/docs/connect/choose-connection#not-using-javascript-or-typescript)                     | Native Postgres driver     | [Neon pooled connection](https://neon.com/docs/connect/connection-pooling)      | [Language guides](https://neon.com/docs/get-started/languages)          |
| [Railway / Render / VPS / Docker](https://neon.com/docs/connect/choose-connection#running-on-a-long-lived-server-jsts)             | `pg` or `postgres.js`      | Client-side or [Neon pooling](https://neon.com/docs/connect/connection-pooling) | [Framework guides](https://neon.com/docs/get-started/frameworks)        |
| [Vercel (Fluid)](https://neon.com/docs/connect/choose-connection#deploying-to-vercel-or-cloudflare-with-platform-pooling)          | `pg` (node-postgres)       | [`@vercel/functions`](https://www.npmjs.com/package/@vercel/functions)          | [Vercel guide](https://neon.com/docs/guides/vercel-connection-methods)  |
| [Cloudflare + Hyperdrive](https://neon.com/docs/connect/choose-connection#deploying-to-vercel-or-cloudflare-with-platform-pooling) | `pg` (node-postgres)       | [Hyperdrive](https://developers.cloudflare.com/hyperdrive/)                     | [Hyperdrive guide](https://neon.com/docs/guides/cloudflare-hyperdrive)  |
| [Cloudflare Workers](https://neon.com/docs/connect/choose-connection#deploying-to-another-serverless-or-edge-platform)             | `@neondatabase/serverless` | N/A                                                                             | [Serverless driver](https://neon.com/docs/serverless/serverless-driver) |
| [Netlify](https://neon.com/docs/connect/choose-connection#deploying-to-another-serverless-or-edge-platform)                        | `@neondatabase/serverless` | N/A                                                                             | [Serverless driver](https://neon.com/docs/serverless/serverless-driver) |
| [Client-side (browser)](https://neon.com/docs/connect/choose-connection#building-a-client-side-app-without-a-backend)              | `@neon/neon-js`            | N/A                                                                             | [Data API](https://neon.com/docs/data-api/overview)                     |

## Find your scenario

### Not using JavaScript or TypeScript?

Use a standard TCP-based Postgres driver with a [pooled connection](https://neon.com/docs/connect/connection-pooling). Connect from a secure backend server using your language's native driver.

| Language/Framework  | Guide                                                       |
| ------------------- | ----------------------------------------------------------- |
| Django (Python)     | [Django](https://neon.com/docs/guides/django)               |
| SQLAlchemy (Python) | [SQLAlchemy](https://neon.com/docs/guides/sqlalchemy)       |
| Elixir Ecto         | [Elixir Ecto](https://neon.com/docs/guides/elixir-ecto)     |
| Laravel (PHP)       | [Laravel](https://neon.com/docs/guides/laravel)             |
| Ruby on Rails       | [Ruby on Rails](https://neon.com/docs/guides/ruby-on-rails) |
| Go                  | [Go](https://neon.com/docs/guides/go)                       |
| Rust                | [Rust](https://neon.com/docs/guides/rust)                   |
| Java                | [Java](https://neon.com/docs/guides/java)                   |
| Kotlin              | [Kotlin](https://neon.com/docs/guides/kotlin)               |

For the full list, see [Language quickstarts](https://neon.com/docs/get-started/languages).

### 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](https://neon.com/docs/connect/connection-pooling). Your server can maintain a connection pool across requests, making TCP the fastest and most efficient option.

Recommended drivers: [`pg` (node-postgres)](https://node-postgres.com/), [`postgres.js`](https://github.com/porsager/postgres), or [`Bun.SQL`](https://bun.com/docs/runtime/sql#postgresql).

### 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`](https://www.npmjs.com/package/@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](https://neon.com/docs/guides/vercel-connection-methods) for details.

**Cloudflare (Hyperdrive):** Use `pg` (node-postgres) with [Hyperdrive](https://developers.cloudflare.com/hyperdrive/), which provides connection pooling for Workers. See the [Cloudflare Hyperdrive guide](https://neon.com/docs/guides/cloudflare-hyperdrive) for setup.

### Deploying to another serverless or edge platform?

For platforms like Netlify Functions or Cloudflare Workers (without Hyperdrive), use the [Neon serverless driver](https://neon.com/docs/serverless/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](https://neon.com/docs/connect/choose-connection#http-vs-websocket-serverless-driver) for details.

### Building a client-side app without a backend?

Use the [Neon Data API](https://neon.com/docs/data-api/overview) via [`@neon/neon-js`](https://www.npmjs.com/package/@neon/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](https://neon.com/docs/reference/javascript-sdk) 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](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size).

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

```text
# 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](https://neon.com/docs/connect/connection-pooling) for details.

### HTTP vs. WebSocket (serverless driver)

The [Neon serverless driver](https://neon.com/docs/serverless/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](https://neon.com/docs/data-api/overview) 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](https://neon.com/docs/guides/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](https://neon.com/docs/connect/choose-connection#pooled-vs-direct-connections).

| ORM     | Supported drivers                               | Guide                                                 |
| ------- | ----------------------------------------------- | ----------------------------------------------------- |
| Drizzle | `pg`, `postgres.js`, `@neondatabase/serverless` | [Drizzle guide](https://neon.com/docs/guides/drizzle) |
| Kysely  | `pg`, `postgres.js`, `@neondatabase/serverless` | [Kysely guide](https://neon.com/docs/guides/kysely)   |
| Prisma  | `pg`, `@neondatabase/serverless`                | [Prisma guide](https://neon.com/docs/guides/prisma)   |
| TypeORM | `pg`                                            | [TypeORM guide](https://neon.com/docs/guides/typeorm) |

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

## Common pitfalls

| Issue                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Double pooling       | **Neon-side pooling** uses PgBouncer to manage connections between your app and Postgres. **Client-side pooling** occurs within your driver before connections reach PgBouncer.<br/><br/>If you use a pooled Neon connection, avoid adding client-side pooling on top. Let Neon handle it. If you must use client-side pooling, release connections back to the pool promptly to avoid conflicts with PgBouncer.                                                                                                                              |
| Understanding limits | `max_connections` is the maximum number of concurrent Postgres connections, determined by your [compute size](https://neon.com/docs/connect/connection-pooling#connection-limits-without-connection-pooling). `default_pool_size` is the maximum number of backend connections PgBouncer maintains per user/database pair.<br/><br/>Increasing your compute to raise `max_connections` may not help if `default_pool_size` is the bottleneck. To increase `default_pool_size`, contact [Support](https://neon.com/docs/introduction/support). |
| Use request handlers | In serverless environments (Vercel Edge Functions, Cloudflare Workers), WebSocket connections cannot outlive a single request. Create, use, and close `Pool` or `Client` objects **within the same request handler**. Do not create them outside a handler or reuse them across handlers. See [Pool and Client](https://github.com/neondatabase/serverless?tab=readme-ov-file#pool-and-client) for details.                                                                                                                                   |

--- [Document source](https://neon.com/docs/connect/connect-from-any-app.md) ---

> Summary: Neon connection strings are generated in the Neon Console by selecting a branch, compute, database, and role. Use the pooled endpoint (append `-pooler`) for higher concurrency, or the direct endpoint on port 5432 when your driver requires a native connection. A serverless driver enables WebSocket and HTTP for edge runtimes where TCP is unavailable.

# Connect from any application

Learn how to connect to Neon from any application

Last updated: 2026-09-16

**What you will learn:**

- Where to find database connections details
- Where to find example connection snippets
- Protocols supported by Neon

**Related topics**

- [Choosing a driver and connection type](https://neon.com/docs/connect/choose-connection)
- [Neon VS Code Extension](https://neon.com/docs/local/vscode-extension)
- [Connect to Neon securely](https://neon.com/docs/connect/connect-securely)
- [Connection pooling](https://neon.com/docs/connect/connection-pooling)
- [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor)

You can connect to your Neon database from any application. The standard method is to copy your [connection string](https://neon.com/docs/connect/connect-from-any-app#get-a-connection-string-from-the-neon-console) from the Neon console and use it in your app or client. For a streamlined development experience, you can also use the [Neon VS Code extension](https://neon.com/docs/connect/connect-from-any-app#connect-with-the-neon-vs-code-extension) to manage connections, browse schemas, and run queries directly in your editor.

**Important:** You are responsible for maintaining the records and associations of any connection strings in your environment and systems.

## Get a connection string from the Neon console

When connecting to Neon from an application or client, you connect to a database in your Neon project. In Neon, a database belongs to a branch, which may be the default branch of your project (`main`) or a child branch.

You can find the connection details for your database by clicking the **Connect** button in the Console nav. This opens the **Connect to your branch** modal. Select a branch, a compute, a database, and a role. A connection string is constructed for you.

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

Neon supports both pooled and direct connections to your database. Neon's connection pooler supports a higher number of concurrent connections, so we provide pooled connection details in the **Connect to your branch** modal by default, which adds a `-pooler` option to your connection string. If needed, you can get direct database connection details from the modal disabling the **Connection pooling** toggle. For more information about pooled connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling#connection-pooling).

A Neon connection string includes the role, password, hostname, and database name.

```text
postgresql://alex:AbC123dEf@ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
             ^    ^         ^                         ^                              ^
       role -|    |         |- hostname               |- pooler option               |- database
                  |
                  |- password
```

**Note:** The hostname includes the ID of the compute, which has an `ep-` prefix: `ep-cool-darkness-123456`. For more information about Neon connection strings, see [connection string](https://neon.com/docs/reference/glossary#connection-string).

You can use the details from the **Connect to your branch** modal to configure your database connection. For example, you might place the connection details in an `.env` file, assign the connection string to a variable, or pass the connection string on the command-line.

**.env file**

```text
PGHOST=ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tech
PGDATABASE=dbname
PGUSER=alex
PGPASSWORD=AbC123dEf
PGPORT=5432
```

**Variable (`DATABASE_URL`)**

Most frameworks read the connection string from a `DATABASE_URL` environment variable. The connection string you copy from the **Connect** modal _is_ your `DATABASE_URL`. Assign it as-is:

```text
DATABASE_URL="postgresql://alex:AbC123dEf@ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require"
```

**Command-line**

```bash
psql postgresql://alex:AbC123dEf@ep-cool-darkness-a1b2c3d4-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

**Note:** Neon requires that all connections use SSL/TLS encryption, but you can increase the level of protection by configuring the `sslmode` option. For more information, see [Connect to Neon securely](https://neon.com/docs/connect/connect-securely).

### Get a connection string from the CLI

If you prefer the terminal, the Neon CLI returns the same connection string with the [`neon connection-string`](https://neon.com/docs/cli/connection-string) command:

```bash
neon connection-string
```

Pass a branch name as a positional argument, and use `--database-name`, `--role-name`, or `--pooled` to control the output. This is handy when you want to assign the result to an environment variable such as `DATABASE_URL` in a script.

## Connect with the Neon VS Code extension

The [Neon VS Code extension](https://neon.com/docs/local/vscode-extension) lets you connect to any Neon branch and manage your database directly in your IDE. Available for VS Code, Cursor, and other VS Code-compatible editors, this extension lets you:

- Connect to any Neon project and branch with automatic detection of connection strings in your workspace
- Copy connection strings directly to your `.env` file
- Browse database schemas, run SQL queries, and edit table data
- Create and manage branches directly from your editor
- Enable AI-powered database features with automatic MCP Server configuration

The extension provides a streamlined workflow for working with Neon during development without leaving your editor.

## Where can I find my password?

It's included in your Neon connection string. Click the **Connect** button in the Console nav to open the **Connect to your branch** modal.

### Save your connection details to 1Password

If you have a [1Password](https://1password.com/) browser extension, you can save your database connection details to 1Password directly from the Neon Console. Click **Connect** in the Console nav, then click **Save in 1Password**.

![1Password button on connection modal](https://neon.com/docs/connect/1_password_button.png)

## What port does Neon use?

Neon uses the default Postgres port, `5432`.

## How do I connect my application using the connection string?

Save the connection string as an environment variable (commonly `DATABASE_URL`), then read it from your code and pass it to a Postgres driver. Neon speaks the standard Postgres wire protocol, so any Postgres client works: `pg`, `psycopg2`, `psql`, Prisma, Drizzle, SQLAlchemy, and others.

**Node.js (pg)**

```javascript
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const { rows } = await pool.query('SELECT * FROM users WHERE id = $1', [1]);
```

**Node.js (neon)**

```javascript
// Best for serverless and edge runtimes
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL);
const rows = await sql`SELECT * FROM users WHERE id = ${1}`;
```

**Python (psycopg2)**

```python
import os
import psycopg2

conn = psycopg2.connect(os.environ["DATABASE_URL"])
```

**psql**

```bash
psql "$DATABASE_URL"
```

Read the string from the environment rather than hardcoding it in source, which is a common source of credential leaks. For Prisma, Drizzle, SQLAlchemy, and other ORMs, see the [frameworks](https://neon.com/docs/get-started/frameworks) and [languages](https://neon.com/docs/get-started/languages) guides.

### Connection examples in the Console

The **Connect to your branch** modal provides connection examples for different frameworks and languages, constructed for the branch, database, and role that you select.

![Language and framework connection examples](https://neon.com/docs/connect/code_connection_examples.png)

## Network protocol support

Neon projects provisioned on AWS support both [IPv4](https://en.wikipedia.org/wiki/Internet_Protocol_version_4) and [IPv6](https://en.wikipedia.org/wiki/IPv6) addresses. Neon projects provisioned on Azure support IPv4.

Additionally, Neon provides a low-latency serverless driver that supports connections over WebSockets and HTTP. Great for serverless or edge environments where connections over TCP may not be not supported. For further information, refer to our [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver) documentation.

## Connection notes

- Some older Postgres client libraries and drivers, including older `psql` executables, are built without [Server Name Indication (SNI)](https://neon.com/docs/reference/glossary#sni) support, which means that a connection workaround may be required. For more information, see [Connection errors: The endpoint ID is not specified](https://neon.com/docs/connect/connection-errors#the-endpoint-id-is-not-specified).
- Some Java-based tools that use the pgJDBC driver for connecting to Postgres, such as DBeaver, DataGrip, and CLion, do not support including a role name and password in a database connection string or URL field. When you find that a connection string is not accepted, try entering the database name, role, and password values in the appropriate fields in the tool's connection UI when configuring a connection to Neon. For examples, see [Connect a GUI or IDE](https://neon.com/docs/connect/connect-postgres-gui#connect-to-the-database).
- When connecting from BI tools like Metabase, Tableau, or Power BI, we recommend using a **read replica** instead of your main database compute. BI tools often run long or resource-intensive queries, which can impact performance on your primary branch. Read replicas can scale independently and handle these workloads without affecting your main production traffic. To learn more, see [Neon read replicas](https://neon.com/docs/introduction/read-replicas).

--- [Document source](https://neon.com/docs/connect/connect-hub.md) ---

> Summary: For all backend services, you connect your app to a particular branch. Each branch can serve whichever services you have enabled: Lakebase Postgres, Object Storage, Managed Better Auth, and AI Gateway. This guide walks through choosing a branch, getting your connection details, storing credentials, and using each service.

# Connect your app

Connect your app to Lakebase Postgres and other backend services

Last updated: 2026-10-30

For all backend services, you connect your app to a particular branch. Each branch can serve whichever services you have enabled: Lakebase Postgres, Object Storage, Managed Better Auth, and AI Gateway.

**Tip: Get your Postgres connection string**

If you only need a Postgres connection string, click **Connect** in the Console nav and copy it. See [Get your connection details](https://neon.com/docs/connect/connect-hub#get-your-connection-details).

## Choose your branch

Credentials are branch-scoped. Each branch has its own isolated credentials and data, whether it is your default branch (for example, `main`) or a child branch you use for development, testing, or preview deployments.

A child branch is a copy-on-write clone of its parent, so it starts with isolated credentials and its own copy of the data. You can test your app with real authentication workflows and real storage without touching your default branch. See [Develop with preview branches](https://neon.com/docs/connect/connect-hub#develop-with-preview-branches) below.

## Get your connection details

You can get connection details from the Console, CLI, or API.

**Console**

In the Neon Console, select your project and branch and click **Connect** to open the **Connect to your branch** modal.

![Connect to your branch modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

**CLI**

For Postgres credentials, use [`neon connection-string`](https://neon.com/docs/cli/connection-string):

```bash
neon connection-string mybranch --database-name mydb --role-name myrole
```

To pull all credentials for a branch (including Object Storage, Data API, Auth, and Functions if declared in `neon.ts`), use [`neon env pull`](https://neon.com/docs/cli/env):

```bash
neon env pull --branch mybranch --file .env.local
```

By default, `neon env pull` writes `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `NEON_BRANCH`, `NEON_BRANCH_ID`, and `NEON_FUNCTION_HOST_SUFFIX`. With a `neon.ts` file declaring services, it also writes credentials for each service. Use `--service` to pull only specific services:

```bash
neon env pull --service postgres --service object-storage
```

**API**

For Postgres, fetch the connection string with [`GET /api/v2/projects/{project_id}/connection_uri`](https://neon.com/docs/manage/branches#connect-to-a-branch):

```bash
curl "https://console.neon.tech/api/v2/projects/{project_id}/connection_uri?branch_id={branch_id}&database_name={database_name}&role_name={role_name}" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

For Object Storage credentials, use [`POST /api/v2/projects/{project_id}/branches/{branch_id}/credentials`](https://neon.com/docs/storage/authentication#creating-a-credential) with `storage:read` and `storage:write` scopes. For Data API and Auth, see [Managing the Data API](https://neon.com/docs/data-api/manage) and [Manage Auth via the API](https://neon.com/docs/auth/guides/manage-auth-api).

## Store your credentials

Store credentials in `.env` files for local development, in your CI secrets manager for CI/CD workflows, or let Neon Functions auto-inject them if you are deploying to Neon Functions.

### Local development

Use [`neon env pull`](https://neon.com/docs/cli/env) to write credentials to `.env.local` (or `.env`):

```bash
neon env pull --file .env.local
```

This writes `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `NEON_BRANCH`, `NEON_BRANCH_ID`, `NEON_FUNCTION_HOST_SUFFIX`, and (if you have a `neon.ts` declaring services) credentials for Object Storage (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, `AWS_REGION`), Data API, and Managed Better Auth.

### Production and CI

For production deployments, store credentials in your secrets manager (AWS Secrets Manager, Vercel environment variables, GitHub Secrets, etc.). Fetch credentials from the Console, CLI, or API, then set them in your platform's secrets configuration.

### Neon Functions

A deployed Neon Function gets credentials injected automatically for every service enabled on its branch. Enable Object Storage and the `AWS_*` credentials are in `process.env` with no manual setup. Declaring buckets in `neon.ts` is what pulls those credentials into your local `.env` (see [Local development](https://neon.com/docs/connect/connect-hub#local-development) above) and gives you type-safe access. See [Neon Functions environment variables](https://neon.com/docs/compute/functions/environment-variables).

## Use each service

Use the credentials for your selected branch with each enabled service.

**Postgres**

Lakebase Postgres is serverless Postgres that you can access with any Postgres driver or the Neon serverless driver.

You can also reach the same Postgres data over HTTP through the [Neon Data API](https://neon.com/docs/data-api/overview). It provides a PostgREST-compatible interface for clients that cannot use a Postgres driver.

```typescript
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);
const rows = await sql`SELECT * FROM users`;
```

**Learn more:** [Connect from any app](https://neon.com/docs/connect/connect-from-any-app)

**Object Storage**

Neon Object Storage is S3-compatible storage. Configure an AWS S3 SDK with the branch-specific `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, and `AWS_REGION` environment variables.

```typescript
import { S3Client } from '@aws-sdk/client-s3';

const client = new S3Client({
  region: process.env.AWS_REGION,
  endpoint: process.env.AWS_ENDPOINT_URL_S3,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  forcePathStyle: true,
});
```

**Learn more:** [Neon Object Storage overview](https://neon.com/docs/storage/overview)

**AI Gateway**

Neon AI Gateway uses a branch-scoped credential. Set `NEON_AI_GATEWAY_BASE_URL` to the branch host, append a dialect path such as `/v1`, and authenticate with `NEON_AI_GATEWAY_TOKEN`.

```typescript
import OpenAI from 'openai';
import 'dotenv/config';

const client = new OpenAI({
  apiKey: process.env.NEON_AI_GATEWAY_TOKEN,
  baseURL: `${process.env.NEON_AI_GATEWAY_BASE_URL}/v1`,
});
const response = await client.chat.completions.create({
  model: 'gpt-5-mini',
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);
```

**Learn more:** [AI Gateway overview](https://neon.com/docs/ai-gateway/overview)

**Auth**

Managed Better Auth stores authentication data in the `neon_auth` schema and remains branch-aware as your database branches.

```typescript
import { createAuthClient } from '@neon/neon-js/auth';

export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL);
```

**Learn more:** [Managed Better Auth overview](https://neon.com/docs/auth/overview)

**Note: Credentials access and the object model**

This guide focuses on connecting your app. For deeper background on how credentials work in Neon and how they map to the object hierarchy (projects, branches, databases, roles), see [Credentials and access](https://neon.com/docs/concepts/credentials-access) and [The object model](https://neon.com/docs/concepts/the-object-model).

## Develop with preview branches

When you create a child branch from your default branch, the child branch gets its own credentials that are valid only for that branch and its descendants. This means you can test authentication workflows, storage uploads, and data changes in a development, test, or preview environment without affecting your default branch.

Credentials are branch-scoped: a credential created on a branch is valid for that branch and any branches descended from it. It's not valid for branches outside that lineage. See [How branch binding works](https://neon.com/docs/storage/authentication#how-branch-binding-works) for details.

To automate preview branches, use [GitHub Actions](https://neon.com/docs/guides/branching-github-actions) or the [Vercel integration](https://neon.com/docs/guides/neon-managed-vercel-integration). For how branches work, see [Get started with branching](https://neon.com/docs/guides/branching-intro).

## Rotate or revoke

To rotate a Postgres password, generate a new one in the Console or CLI and update your environment variables. For Object Storage credentials, create a new credential, update your app, then revoke the old one. See [Revoking object storage credentials](https://neon.com/docs/storage/authentication#revoking-credentials) for API details.

Credential rotation workflows for Data API and Auth are similar: create a new credential or reset the password, update your app, then revoke the old one.

## Where to go next

- [Credentials and access](https://neon.com/docs/concepts/credentials-access) - how credentials work in Neon
- [The object model](https://neon.com/docs/concepts/the-object-model) - projects, branches, databases, and roles
- [Connect to Neon](https://neon.com/docs/connect/connect-intro) - connection methods, drivers, and tools
- [Object Storage overview](https://neon.com/docs/storage/overview) - buckets, objects, and authentication
- [AI Gateway overview](https://neon.com/docs/ai-gateway/overview) - unified access to AI models
- [Data API overview](https://neon.com/docs/data-api/overview) - REST API for Postgres
- [Managed Better Auth overview](https://neon.com/docs/auth/overview) - managed authentication service

--- [Document source](https://neon.com/docs/connect/connect-intro.md) ---

> Summary: Index of every supported Neon connection method: standard PostgreSQL connection strings, the Neon serverless driver (HTTP and WebSockets for edge and serverless environments), the Data API (driver-free HTTP queries), psql, and GUI tools such as pgAdmin and DBeaver. Also links to connection pooling, SSL/TLS security, and latency and timeout troubleshooting.

# Connect to Neon

Everything you need to know about connecting to Neon

Last updated: 2026-07-24

This section covers all the ways to connect to your Neon database, from standard Postgres connections to specialized drivers and tools. For framework-specific guides and quick starts, see [Get Started](https://neon.com/docs/get-started/connect-neon).

## Getting started with connections

- [Connect from any app](https://neon.com/docs/connect/connect-from-any-app): Learn about connection strings and how to connect to Neon from any application
- [Choose a connection type](https://neon.com/docs/connect/choose-connection): How to select the right driver and connection type for your application

## Connection methods

- [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver): Connect from serverless and edge environments over HTTP or WebSockets
- [Data API](https://neon.com/docs/data-api/overview): Query Postgres via HTTP without database drivers or connection pooling
- [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor): Connect with psql, the native command-line client for Postgres
- [GUI applications](https://neon.com/docs/connect/connect-postgres-gui): Connect from GUI tools like pgAdmin, DBeaver, and TablePlus
- [VS Code Extension](https://neon.com/docs/local/vscode-extension): Connect to Neon branches and manage your database directly in VS Code, Cursor, and other editors
- [Neon CLI (neon psql)](https://neon.com/docs/cli/psql): Open a psql session from the Neon CLI without a connection string or a psql install

## Optimize and secure your connections

- [Connection pooling](https://neon.com/docs/connect/connection-pooling): Enable connection pooling to support up to 10,000 concurrent connections
- [Secure connections](https://neon.com/docs/connect/connect-securely): Connect securely using SSL/TLS encryption and certificate verification
- [Latency and timeouts](https://neon.com/docs/connect/connection-latency): Strategies for managing connection latency and timeouts

## Troubleshooting

- [Connection errors](https://neon.com/docs/connect/connection-errors): Resolve common connection errors including SNI issues and driver compatibility

--- [Document source](https://neon.com/docs/connect/connect-looker-studio.md) ---

> Summary: Looker Studio connects to the database through Google's built-in PostgreSQL connector. The setup requires manually mapping connection string fields (host, database, username, password) and uploading an SSL server certificate. Use this page when adding Neon as a Looker Studio data source for dashboards and reports, especially if SSL configuration is blocking the connection. The required server certificate is isrgrootx1.pem from Let's Encrypt; client authentication should be left disabled.

# Connect Looker Studio to Neon

Learn how to connect your database to Looker Studio

Last updated: 2026-10-27

[Looker Studio](https://lookerstudio.google.com/) is Google's data visualization and business intelligence platform. This guide explains how to connect your database to Looker Studio using a PostgreSQL data source.

## Get your database connection string

1. In the Neon Console, select the **project** and **branch** you want to connect to.
2. Click **Connect** in the Console nav.
3. Click **Show Password** and copy the connection string.

For more details, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Add a PostgreSQL data source in Looker Studio

1. In Looker Studio, **Create** > **Data Source**.
2. Search for and select the **PostgreSQL** connector, and authorize it.
3. In the **Basic** section, fill in the fields using the details from your connection string.

   For example, if your connection string is:

   ```bash
   psql 'postgresql://neondb_owner:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require'
   ```

   You would enter:

   - **Host name or IP**: `ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech`
   - **Port (optional)**: Leave blank
   - **Database**: `neondb`
   - **Username**: `neondb_owner`
   - **Password**: `AbC123dEf`

   ![Looker studio connection details](https://neon.com/docs/connect/ls_connection_details.png)

## Configure SSL settings

1. Ensure **Enable SSL** is checked.
2. Leave **Enable client authentication** unchecked.

## Upload the server certificate

1. Download the `isrgrootx1.pem` file from [https://letsencrypt.org/certs/isrgrootx1.pem](https://letsencrypt.org/certs/isrgrootx1.pem). For more information about SSL certificates, see [Connect to Neon securely](https://neon.com/docs/connect/connect-securely).
2. In Looker Studio, upload the `isrgrootx1.pem` file using the **Upload** button next to the **Server Certificate** box.

   ![Looker studio upload pem file](https://neon.com/docs/connect/ls_pem_file.png)

## Authenticate

Click **Authenticate** to verify the connection. If successful, you will see your Neon tables listed in Looker Studio. In this example, there is one table listed: the `playing_with_neon` example table.

![Looker studio upload pem file](https://neon.com/docs/connect/ls_neon_tables.png)

## Connect

Click the **Connect** button in Looker Studio to view table details.

![Looker studio upload pem file](https://neon.com/docs/connect/ls_table_details.png)

--- [Document source](https://neon.com/docs/connect/connect-pgcli.md) ---

> Summary: pgcli is an interactive Postgres CLI with syntax highlighting, autocompletion, multi-line editing, query history, and named queries. It connects to Neon using a standard connection string available from the Neon Console. Choose pgcli over psql when you want a richer terminal experience for ad-hoc querying.

# Connect with pgcli

Learn how to connect to Neon using the interactive pgcli client

Last updated: 2026-09-16

The `pgcli` client is an interactive command-line interface for Postgres that offers several advantages over the traditional `psql` client, including syntax highlighting, autocompletion, multi-line editing, and query history.

## Installation

For installation instructions, please refer to the `pgcli` [installation documentation](https://www.pgcli.com/install).

## Usage information

To view `pgcli` usage information, run the following command:

```bash
pgcli --help
```

## Connect to Neon

The easiest way to connect to Neon using the `pgcli` client is with a connection string, which you can obtain by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select a branch, a role, and the database you want to connect to. A connection string is constructed for you.

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

From your terminal or command prompt, run the `pgcli` client with the connection string. Your command will look something like this:

```bash
pgcli postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

## Run queries

After establishing a connection, try the `pgcli` client by running the following queries. To test the `pgcli` [autocompletion](https://www.pgcli.com/completion) feature, type the `SELECT` query.

```sql
CREATE TABLE my_table AS SELECT now();
SELECT * FROM my_table;
```

The following result is returned:

```sql
SELECT 1
+-------------------------------+
| now                           |
|-------------------------------|
| 2023-05-21 09:23:18.086163+00 |
+-------------------------------+
SELECT 1
Time: 0.116s
```

The `pgcli` [query history](https://www.pgcli.com/history) feature allows you to use the **Up** and **Down** keys on your keyboard to navigate your query history.

The `pgcli` client also supports [named queries](https://www.pgcli.com/named_queries.md). To save a query, type:

```bash
\ns simple SELECT * FROM my_table;
```

To run a named query, type:

```bash
# Run a named query.
\n simple
> SELECT * FROM my_table
+-------------------------------+
| now                           |
|-------------------------------|
| 2023-05-21 09:23:18.086163+00 |
+-------------------------------+
SELECT 1
Time: 0.051s
```

For more information about `pgcli` features and capabilities, refer to the [pgcli documentation](https://www.pgcli.com/docs).

--- [Document source](https://neon.com/docs/connect/connect-postgres-gui.md) ---

> Summary: Connect a GUI application or IDE (pgAdmin, DBeaver, DataGrip, TablePlus) to Neon using a hostname, port 5432, role, password, and database name from the Neon Console Connect modal. Per-tool SSL configuration and SNI compatibility are addressed, with a tested compatibility table that includes SNI workarounds for Segment, Azure Data Studio, and older Postico versions. For BI tools such as Metabase, Tableau, and Power BI, Neon recommends connecting to a read replica to avoid performance impact on the primary branch.

# Connect a GUI application

Learn how to connect a GUI application to Neon

Last updated: 2026-11-06

This topic describes how to connect to a Neon database from a GUI application or IDE. Most GUI applications and IDEs that support connecting to a Postgres database also support connecting to Neon.

## Gather your connection details

The following details are typically required when configuring a connection:

- hostname
- port
- database name
- role (user)
- password

You can gather these details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select a branch, a role, and the database you want to connect to. A connection string is constructed for you.

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

**Note:** Neon supports pooled and direct connections to the database. Use a pooled connection string if your application uses a high number of concurrent connections. For more information, see [Connection pooling](https://neon.com/docs/connect/connection-pooling#connection-pooling).

The connection string includes the role, password, hostname, and database name.

```text
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
             ^              ^                                               ^
             |- <role>      |- <hostname>                                   |- <database>
```

- role name: `alex`
- hostname: `ep-cool-darkness-123456.us-east-2.aws.neon.tech`
- database name: `dbname`

Neon uses the default Postgres port, `5432`.

## Connect to the database

In the GUI application or IDE, enter the connection details into the appropriate fields and connect. Some applications permit specifying a connection string while others require entering connection details into separate fields. In the pgAdmin example below, connection details are entered into separate fields, and clicking **Save** establishes the database connection.

![Register - Server](https://neon.com/docs/connect/pgadmin4.png)

Some Java-based tools that use the pgJDBC driver for connecting to Postgres, such as DBeaver, DataGrip, and CLion, do not support including a role name and password in a database connection string or URL field. When you find that a connection string is not accepted, try entering the database name, role, and password values in the appropriate fields in the tool's connection UI when configuring a connection to Neon. For example, the DBeaver client has a **URL** field, but connecting to Neon requires specifying the connection details as shown:

![DBeaver connection](https://neon.com/docs/connect/dbeaver_connection.png)

## Tested GUI applications and IDEs

Connections from the GUI applications and IDEs in the table below have been tested with Neon.

**Note:** Some applications require an Server Name Indication (SNI) workaround. Neon uses compute domain names to route incoming connections. However, the Postgres wire protocol does not transfer the server domain name, so Neon relies on the Server Name Indication (SNI) extension of the TLS protocol to do this. Not all application clients support SNI. In these cases, a workaround is required. For more information, see [Connection errors](https://neon.com/docs/connect/connection-errors).

| Application or IDE                                                                                                            | Notes                                                                                                                                                                                                                                                                                                                                                                                                   |
| :---------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Appsmith](https://www.appsmith.com/)                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [AskYourDatabase](https://www.askyourdatabase.com/)                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [AWS Database Migration Service (DMS)](https://aws.amazon.com/dms/)                                                           | Use [SNI workaround D](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field). Use a `$` character as a separator between the `endpoint` option and password. For example: `endpoint=<endpoint_id>$<password>`. Also, you must set **Secure Socket Layer (SSL) mode** to `require`. See [Migrate with AWS DMS](https://neon.com/docs/import/migrate-aws-dms). |
| [Azure Data Studio](https://azure.microsoft.com/en-us/products/data-studio/)                                                  | Requires the [PostgreSQL extension](https://learn.microsoft.com/en-us/sql/azure-data-studio/extensions/postgres-extension?view=sql-server-ver16) and [SNI workaround D](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field)                                                                                                                                |
| [Beekeeper Studio](https://www.beekeeperstudio.io/)                                                                           | Requires the **Enable SSL** option                                                                                                                                                                                                                                                                                                                                                                      |
| [CLion](https://www.jetbrains.com/clion/)                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [Datagran](https://www.datagran.io/)                                                                                          | Requires [SNI workaround D](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field) connection workaround                                                                                                                                                                                                                                                      |
| [DataGrip](https://www.jetbrains.com/datagrip/)                                                                               |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [DBConvert Streams](https://streams.dbconvert.com/docs/connections/neon-database)                                             |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [DBeaver](https://dbeaver.io/)                                                                                                | To prevent scale-to-zero from interrupting an idle connection, go to **Edit Connection** > **Connection Settings** > **Initialization** and set **Keep-Alive (seconds)** to `60`. See [Using DBeaver with hosted Postgres](https://neon.com/guides/dbeaver-hosted-postgres).                                                                                                                            |
| [dbForge](https://www.devart.com/dbforge/)                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [DbVisualizer](https://www.dbvis.com/)                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [DBX](https://getdbx.com/)                                                                                                    |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [DB Pro](https://dbpro.app)                                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [Draxlr](https://www.draxlr.com/)                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [DronaHQ hosted cloud version](https://www.dronahq.com/)                                                                      | Requires selecting **Connect using SSL** when creating a connector                                                                                                                                                                                                                                                                                                                                      |
| [Forest Admin](https://www.forestadmin.com/)                                                                                  | The database requires at least one table                                                                                                                                                                                                                                                                                                                                                                |
| [Grafana](https://grafana.com/docs/grafana/latest/datasources/postgres/)                                                      | Requires `sslmode=verify-full`. See [SNI workaround C](https://neon.com/docs/connect/connection-errors#c-set-verify-full-for-golang-based-clients).                                                                                                                                                                                                                                                     |
| [Google Looker Studio](https://lookerstudio.google.com/)                                                                      | Requires **Enable SSL** and uploading the PEM-encoded ISRG Root X1 public root certificate issued by Let's Encrypt, which you can find here: [isrgrootx1.pem](https://letsencrypt.org/certs/isrgrootx1.pem). See the [Looker Studio guide](https://neon.com/docs/connect/connect-looker-studio) for detailed connection instructions.                                                                   |
| [Google Cloud Platform (GCP)](https://cloud.google.com/gcp)                                                                   | May require uploading the PEM-encoded ISRG Root X1 public root certificate issued by Let's Encrypt, which you can find here: [isrgrootx1.pem](https://letsencrypt.org/certs/isrgrootx1.pem).                                                                                                                                                                                                            |
| [Google Colab](https://colab.research.google.com/)                                                                            | See [Use Google Colab with Neon](https://neon.com/docs/ai/ai-google-colab).                                                                                                                                                                                                                                                                                                                             |
| [Luna Modeler](https://www.datensen.com/data-modeling/luna-modeler-for-relational-databases.html)                             | Requires enabling the SSL/TLS option                                                                                                                                                                                                                                                                                                                                                                    |
| [Metabase](https://www.metabase.com/)                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [OrcaQ](https://github.com/cin12211/orca-q)                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [Postico](https://eggerapps.at/postico2/)                                                                                     | SNI support since v1.5.21. For older versions, use [SNI workaround B](https://neon.com/docs/connect/connection-errors#b-use-libpq-keyvalue-syntax-in-the-database-field). Postico's [keep-connection-alive mechanism](https://eggerapps.at/postico/docs/v1.2/changelist.html), enabled by default, may prevent your compute from scaling to zero.                                                       |
| [PostgreSQL VS Code Extension by Chris Kolkman](https://marketplace.visualstudio.com/items?itemName=ckolkman.vscode-postgres) |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [pgAdmin 4](https://www.pgadmin.org/)                                                                                         | See [Using pgAdmin4 with hosted Postgres](https://neon.com/guides/pgAdmin4-hosted-postgres).                                                                                                                                                                                                                                                                                                            |
| [Retool](https://retool.com/)                                                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                         |
| [Tableau](https://www.tableau.com/)                                                                                           | Use the PostgreSQL connector with the **Require SSL** option selected                                                                                                                                                                                                                                                                                                                                   |
| [TablePlus](https://tableplus.com/)                                                                                           | SNI support on macOS since build 436, and on Windows since build 202. No SNI support on Linux currently. For older versions, use [SNI workaround B](https://neon.com/docs/connect/connection-errors#b-use-libpq-keyvalue-syntax-in-the-database-field).                                                                                                                                                 |
| [Segment](https://segment.com/)                                                                                               | Requires [SNI workaround D](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field)                                                                                                                                                                                                                                                                            |
| [Skyvia](https://skyvia.com/)                                                                                                 | Requires setting the **SSL Mode** option to `Require`, and **SSL TLS Protocol** to 1.2. The other SSL fields are not required for **SSL Mode**: `Require`.                                                                                                                                                                                                                                              |
| [Zoho Analytics](https://www.zoho.com/analytics/)                                                                             | Requires selecting **Other Cloud Services** as the Cloud Service Provider, and the **Connect directly using IP address** and **Use SSL** options when configuring a PostgreSQL connection.                                                                                                                                                                                                              |

## Connecting from Business Intelligence (BI) tools

When connecting from BI tools like Metabase, Tableau, or Power BI, we recommend using a **read replica** instead of your main database compute. BI tools often run long or resource-intensive queries, which can impact performance on your primary branch. Read replicas can scale independently and handle these workloads without affecting your main production traffic. To learn more, see [Neon read replicas](https://neon.com/docs/introduction/read-replicas).

## Connection issues

Applications that use older client libraries or drivers that do not support Server Name Indication (SNI) may not permit connecting to Neon. If you encounter the following error, refer to [Connection errors](https://neon.com/docs/connect/connection-errors) for possible workarounds.

```txt
ERROR: The endpoint ID is not specified. Either upgrade the Postgres client library (libpq) for SNI support or pass the endpoint ID (the first part of the domain name) as a parameter: '&options=endpoint%3D'. See [https://neon.com/sni](https://neon.com/sni) for more information.
```

--- [Document source](https://neon.com/docs/connect/connect-securely.md) ---

> Summary: Neon enforces SSL/TLS on every connection and rejects unencrypted clients. Three `sslmode` levels (`require`, `verify-ca`, `verify-full`) are supported, along with `channel_binding=require` for SCRAM-SHA-256-PLUS mutual authentication against man-in-the-middle attacks. Use this page to configure a secure Postgres connection string for psql, psycopg2, JDBC, or any driver that needs an explicit CA root certificate path. OS-specific root certificate locations for Debian/Ubuntu, CentOS, macOS, Windows, and Android are included. Neon uses the ISRG Root X1 certificate from Let's Encrypt.

# Connect to Neon securely

Learn how to connect to Neon securely when using a connection string

Last updated: 2026-06-05

Neon requires that all connections use SSL/TLS encryption to ensure that data sent over the Internet cannot be viewed or manipulated by third parties. Neon rejects connections that do not use SSL/TLS, behaving in the same way as standalone Postgres with only `hostssl` records in a `pg_hba.conf` configuration file.

However, there are different levels of protection when using SSL/TLS encryption, which you can configure by appending an `sslmode` parameter to your connection string.

## Connection modes

When connecting to Neon or any Postgres database, the `sslmode` parameter setting determines the security of the connection. You can append the `sslmode` parameter to your Neon connection string as shown:

```text
postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=verify-full
```

Neon supports the following `sslmode` settings, in order of least to most secure.

| sslmode       | Description                                                                                                                                                                                                                                                                       |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `require`     | Encryption is required and the server's SSL/TLS certificate is verified. If verification fails, the connection is refused.                                                                                                                                                        |
| `verify-ca`   | Encryption is required and the server's SSL/TLS certificate is verified. In addition, the client verifies that the server's certificate has been signed by a trusted certificate authority (CA).                                                                                  |
| `verify-full` | Encryption is required and the server's SSL/TLS certificate is fully verified, including hostname verification, expiration checks, and revocation checks. In addition, the client verifies that the server's certificate has been signed by a trusted certificate authority (CA). |

The choice of which mode to use depends on the specific security requirements of the application and the level of risk that you are willing to tolerate. Neon recommends that you always use `verify-full` mode, which ensures the highest level of security and protects against a wide range of attacks including man-in-the-middle attacks. The following sections describe how to configure connections using `verify-full` mode.

## Channel binding for enhanced security

`channel_binding=require` is a security parameter that ensures the client and server mutually authenticate each other using SCRAM-SHA-256-PLUS. This helps protect against man-in-the-middle attacks, even when using `sslmode=require` alone.

The required configuration for your connection depends on the client you are using.

## Connect from the psql client

To connect from the `psql` command-line client with `sslmode=verify-full`, provide the path to your system root certificates by setting the `PGSSLROOTCERT` variable to the location of your operating system's root certificates. You can set this environment variable in your shell, typically bash or similar, using the export command. For example, if your root certificate is at `/path/to/root.crt`, you would set the variable like so:

```bash
export PGSSLROOTCERT="/path/to/your/root.crt"
```

Refer to [Location of system root certificates](https://neon.com/docs/connect/connect-securely#location-of-system-root-certificates) below to find the path to system root certificates for your operating system.

## Connect from other clients

If the client application uses a popular Postgres client library, such as `psycopg2` for Python or JDBC for Java, the library typically provides built-in support for SSL/TLS encryption and verification, allowing you to configure an `sslmode` setting in the connection parameters. For example:

```python
import psycopg2

conn = psycopg2.connect(
    dbname='dbname',
    user='alex',
    password='AbC123dEf',
    host='ep-cool-darkness-123456.us-east-2.aws.neon.tech',
    port='5432',
    sslmode='verify-full',
    sslrootcert='/path/to/your/root.crt'
)
```

However, if your client application uses a non-standard Postgres client, SSL/TLS may not be enabled by default. In this case, you must manually configure the client to use SSL/TLS and specify an `sslmode` configuration. Refer to the client or the client's driver documentation for how to configure the path to your operating system's root certificates.

### Location of system root certificates

Neon uses the public ISRG Root X1 certificate issued by [Let's Encrypt](https://letsencrypt.org/). You can find the PEM-encoded certificate here: [isrgrootx1.pem](https://letsencrypt.org/certs/isrgrootx1.pem). Typically, you do not need to download this file directly, as it is usually available in a root store on your operating system. A root store is a collection of pre-downloaded root certificates from various Certificate Authorities (CAs). These are highly trusted CAs, and their certificates are typically shipped with operating systems and some applications.

The location of the root store varies by operating system or distribution. Here are some locations where you might find the required root certificates on popular operating systems:

- Debian, Ubuntu, Gentoo, etc.

  ```bash
  /etc/ssl/certs/ca-certificates.crt
  ```

- CentOS, Fedora, RedHat

  ```bash
  /etc/pki/tls/certs/ca-bundle.crt
  ```

- OpenSUSE

  ```bash
  /etc/ssl/ca-bundle.pem
  ```

- Alpine Linux

  ```bash
  /etc/ssl/cert.pem
  ```

- Android

  ```bash
  /system/etc/security/cacerts
  ```

- macOS:

  ```bash
  /etc/ssl/cert.pem
  ```

- Windows

  Windows does not provide a file containing the CA roots that can be used by your driver. However, many popular programming languages used on Windows like C#, Java, or Go do not require the CA root path to be specified and will use the Windows internal system roots by default.

  However, if you are using a language that requires specifying the CA root path, such as C or PHP, you can obtain a bundle of root certificates from the Mozilla CA Certificate program provided by the Curl project. You can download the bundle at [https://curl.se/docs/caextract.html](https://curl.se/docs/caextract.html). After downloading the file, you will need to configure your driver to point to the bundle.

The system root certificate locations listed above may differ depending on the version, distribution, and configuration of your operating system. If you do not find the root certificates in these locations, refer to your operating system documentation.

--- [Document source](https://neon.com/docs/connect/connection-errors.md) ---

> Summary: Neon connection error troubleshooting reference maps named Postgres errors to root causes and fixes. Errors covered include SNI endpoint ID missing, password auth failures, Prisma P1001 cold-start timeouts, PgBouncer unsupported startup parameters, max_connections exhaustion, and DNS resolution failures. Use this page when a connection attempt returns a named error and you need the exact fix rather than general connection setup guidance.

# Connection errors

Learn how to resolve connection errors

Last updated: 2026-09-16

This topic describes how to resolve connection errors you may encounter when using Neon. The errors covered include:

- [The endpoint ID is not specified](https://neon.com/docs/connect/connection-errors#the-endpoint-id-is-not-specified)
- [Password authentication failed for user](https://neon.com/docs/connect/connection-errors#password-authentication-failed-for-user)
- [Couldn't connect to compute node](https://neon.com/docs/connect/connection-errors#couldnt-connect-to-compute-node)
- [Can't reach database server](https://neon.com/docs/connect/connection-errors#cant-reach-database-server)
- [Error undefined: Database error](https://neon.com/docs/connect/connection-errors#error-undefined-database-error)
- [Terminating connection due to administrator command](https://neon.com/docs/connect/connection-errors#terminating-connection-due-to-administrator-command)
- [Unsupported startup parameter](https://neon.com/docs/connect/connection-errors#unsupported-startup-parameter)
- [You have exceeded the limit of concurrently active endpoints](https://neon.com/docs/connect/connection-errors#you-have-exceeded-the-limit-of-concurrently-active-endpoints)
- [Remaining connection slots are reserved for roles with the SUPERUSER attribute](https://neon.com/docs/connect/connection-errors#remaining-connection-slots-are-reserved-for-roles-with-the-superuser-attribute)
- [Relation not found](https://neon.com/docs/connect/connection-errors#relation-not-found)
- [cannot execute ... in a read-only transaction (SQLSTATE 25006)](https://neon.com/docs/connect/connection-errors#error-read-only-transaction)
- [Postgrex: DBConnection ConnectionError ssl send: closed](https://neon.com/docs/connect/connection-errors#postgrex-dbconnection-connectionerror-ssl-send-closed)
- [query_wait_timeout SSL connection has been closed unexpectedly](https://neon.com/docs/connect/connection-errors#querywaittimeout-ssl-connection-has-been-closed-unexpectedly)
- [The request could not be authorized due to an internal error](https://neon.com/docs/connect/connection-errors#the-request-could-not-be-authorized-due-to-an-internal-error)
- [Terminating connection due to idle-in-transaction timeout](https://neon.com/docs/connect/connection-errors#terminating-connection-due-to-idle-in-transaction-timeout)
- [Error connecting to database: Failed to fetch](https://neon.com/docs/connect/connection-errors#error-connecting-to-database-failed-to-fetch)
- [DNS resolution issues](https://neon.com/docs/connect/connection-errors#dns-resolution-issues)

**Info:** Connection problems are sometimes related to a system issue. To check for system issues, please refer to the [Neon status page](https://neonstatus.com/).

## The endpoint ID is not specified

With older clients and some native Postgres clients, you may receive the following error when attempting to connect to Neon:

```txt
ERROR: The endpoint ID is not specified. Either upgrade the Postgres client library (libpq) for SNI support or pass the endpoint ID (the first part of the domain name) as a parameter: '&options=endpoint%3D'. See [https://neon.com/sni](https://neon.com/sni) for more information.
```

This error occurs if your client library or application does not support the **Server Name Indication (SNI)** mechanism in TLS.

Neon uses compute IDs (the first part of a Neon domain name) to route incoming connections. However, the Postgres wire protocol does not transfer domain name information, so Neon relies on the Server Name Indication (SNI) extension of the TLS protocol to do this.

SNI support was added to `libpq` (the official Postgres client library) in Postgres 14, which was released in September 2021. Clients that use your system's `libpq` library should work if your Postgres version is >= 14. On Linux and macOS, you can check Postgres version by running `pg_config --version`. On Windows, check the `libpq.dll` version in your Postgres installation's `bin` directory. Right-click on the file, select **Properties** > **Details**.

If a library or application upgrade does not help, there are several workarounds, described below, for providing the required domain name information when connecting to Neon.

### A. Pass the endpoint ID as an option

Neon supports a connection option named `endpoint`, which you can use to identify the compute you are connecting to. Specifically, you can add `options=endpoint%3D[endpoint_id]` as a parameter to your connection string, as shown in the example below. The `%3D` is a URL-encoded `=` sign. Replace `[endpoint_id]` with your compute's ID, which you can find in your Neon connection string. It looks similar to this: `ep-cool-darkness-123456`.

```txt
postgresql://[user]:[password]@[neon_hostname]/[dbname]?options=endpoint%3D[endpoint-id]
```

**Note:** The `endpoint` connection option was previously named `project`. The `project` option is deprecated but remains supported for backward compatibility.

The `endpoint` option works if your application or library permits it to be set. Not all of them do, especially in the case of GUI applications.

### B. Use libpq key=value syntax in the database field

If your application or client is based on `libpq` but you cannot upgrade the library, such as when the library is compiled inside of a an application, you can take advantage of the fact that `libpq` permits adding options to the database name. So, in addition to the database name, you can specify the `endpoint` option, as shown below. Replace `[endpoint_id]` with your compute's endpoint ID, which you can find in your Neon connection string. It looks similar to this: `ep-cool-darkness-123456`.

```txt
dbname=neondb options=endpoint=[endpoint_id]
```

### C. Set verify-full for golang-based clients

If your application or service uses golang Postgres clients like `pgx` and `lib/pg`, you can set `sslmode=verify-full`, which causes SNI information to be sent when you connect. Most likely, this behavior is not intended but happens inadvertently due to the golang's TLS library API design.

### D. Specify the endpoint ID in the password field

Another supported workaround involves specifying the endpoint ID in the password field. So, instead of specifying only your password, you provide a string consisting of the `endpoint` option and your password, separated by a semicolon (`;`) or dollar sign character (`$`), as shown in the examples below. Replace `[endpoint_id]` with your compute's endpoint ID, which you can find in your Neon connection string. It looks similar to this: `ep-cool-darkness-123456`.

```txt
endpoint=<endpoint_id>;<password>
```

or

```txt
endpoint=<endpoint_id>$<password>
```

Example:

```txt
postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

**Note:** Using a dollar sign (`$`) character as a separator may be required if a semicolon (`;`) is not a permitted character in a password field. For example, the [AWS Database Migration Service (DMS)](https://aws.amazon.com/dms/) does not permit a semicolon character in the **Password** field when defining connection details for database endpoints.

This approach causes the authentication method to be downgraded from `scram-sha-256` (never transfers a plain text password) to `password` (transfers a plain text password). However, the connection is still TLS-encrypted, so the level of security is equivalent to the security provided by `https` websites as long as `sslmode=verify-full` or channel binding is used. We intend to deprecate this option when most libraries and applications provide SNI support.

### Libraries

Clients on the [list of drivers](https://wiki.postgresql.org/wiki/List_of_drivers) on the PostgreSQL community wiki that use your system's `libpq` library should work if your `libpq` version is >= 14.

Neon has tested the following drivers for SNI support:

| Driver            | Language   | SNI Support | Notes                                                                                                                                             |
| ----------------- | ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| npgsql            | C#         | ✓           |                                                                                                                                                   |
| Postgrex          | Elixir     | ✓           | [Requires ssl\_opts with server\_name\_indication](https://neon.com/docs/guides/elixir-ecto#configure-ecto)                                       |
| github.com/lib/pq | Go         | ✓           | Supported with macOS Build 436, Windows Build 202, and Ubuntu 20, 21 and 22 (Deprecated, use pgx instead)                                         |
| pgx               | Go         | ✓           | Recommended driver for Go. SNI support available in v5.0.0-beta.3 and later                                                                       |
| go-pg             | Go         | ✓           | requires `verify-full` mode                                                                                                                       |
| JDBC              | Java       | ✓           |                                                                                                                                                   |
| node-postgres     | JavaScript | ✓           | Requires the `ssl: {'sslmode': 'require'}` option                                                                                                 |
| postgres.js       | JavaScript | ✓           | Requires the `ssl: 'require'` option                                                                                                              |
| asyncpg           | Python     | ✓           |                                                                                                                                                   |
| pg8000            | Python     | ✓           | Requires [scramp >= v1.4.3](https://pypi.org/project/scramp/), which is included in [pg8000 v1.29.3](https://pypi.org/project/pg8000/) and higher |
| PostgresClientKit | Swift      | ✗           |                                                                                                                                                   |
| PostgresNIO       | Swift      | ✓           |                                                                                                                                                   |
| postgresql-client | TypeScript | ✓           |                                                                                                                                                   |

## Password authentication failed for user

The following error is often the result of an incorrectly defined connection information, or the driver you are using does not support Server Name Indication (SNI).

```text
ERROR:  password authentication failed for user '<user_name>' connection to server at "ep-billowing-fun-123456.us-west-2.aws.neon.tech" (12.345.67.89), port 5432 failed: ERROR:  connection is insecure (try using `sslmode=require&channel_binding=require`)
```

Check your connection to see if it is defined correctly. Your Neon connection string can be obtained by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. It appears similar to this:

```text
postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

For clients or applications that require specifying connection parameters such as user, password, and hostname separately, the values in a Neon connection string correspond to the following:

- **User**: `daniel`
- **Password**: `f74wh99w398H`
- **Hostname**: `ep-white-morning-123456.us-east-2.aws.neon.tech`
- **Port number**: `5432` (Neon uses default Postgres port, `5432`, and is therefore not included in the connection string)
- **Database name**: `neondb` (`neondb` is the ready-to-use database created with each Neon project. Your database name may differ.)

If you find that your connection string is defined correctly, see the instructions regarding SNI support outlined in the preceding section: [The endpoint ID is not specified](https://neon.com/docs/connect/connection-errors#the-endpoint-id-is-not-specified).

## Couldn't connect to compute node

This error arises when the Neon proxy, which accepts and handles connections from clients that use the Postgres protocol, fails to establish a connection with your compute. This issue sometimes occurs due to repeated connection attempts during the compute's restart phase after it has been idle due to [scale to zero](https://neon.com/docs/reference/glossary#scale-to-zero). The transition from an idle to an active state only takes a few hundred milliseconds.

Consider these recommended steps:

- Visit the [Neon status page](https://neonstatus.com/) to ensure there are no ongoing issues.
- Pause for a short period to allow your compute to restart, then try reconnecting.
- Try [connecting with psql](https://neon.com/docs/connect/query-with-psql-editor) to see if a connection can be established.
- Review the strategies in [Connection latency and timeouts](https://neon.com/docs/connect/connection-latency) for avoiding connection issues due to compute startup time.

If the connection issue persists, please reach out to [Support](https://neon.com/docs/introduction/support).

## Can't reach database server

This error is sometimes encountered when using Prisma Client with Neon.

```text
Error: P1001: Can't reach database server at `ep-white-thunder-826300.us-east-2.aws.neon.tech`:`5432`
Please make sure your database server is running at `ep-white-thunder-826300.us-east-2.aws.neon.tech`:`5432`.
```

A compute in Neon has two main states: **Active** and **Idle**. Active means that Postgres is currently running. If there are no active queries for 5 minutes, the activity monitor gracefully places the compute into an idle state to reduce compute usage.

When you connect to an idle compute, Neon automatically activates it. Activation typically happens within a few seconds. If the error above is reported, it most likely means that the Prisma query engine timed out before your Neon compute was activated. For dealing with this connection timeout scenario, refer to the [connection timeout](https://neon.com/docs/guides/prisma#connection-timeouts) instructions in our Prisma documentation. Our [connection latency and timeout](https://neon.com/docs/connect/connection-latency) documentation may also be useful in addressing this issue.

## Error undefined: Database error

This error is sometimes encountered when using Prisma Migrate with Neon.

```text
Error undefined: Database error
Error querying the database: db error: ERROR: prepared statement
"s0" already exists
```

Prisma Migrate requires a direct connection to the database. It does not support a pooled connection with PgBouncer, which is the connection pooler used by Neon. Attempting to run Prisma Migrate commands, such as `prisma migrate dev`, with a pooled connection causes this error. To resolve this issue, please refer to our [Connection pooling with Prisma Migrate](https://neon.com/docs/guides/prisma#connect-pooling-with-prisma-migrate) instructions.

## Terminating connection due to administrator command

The `terminating connection due to administrator command` error is typically encountered when running a query from a connection that has sat idle long enough for the compute to suspend due to inactivity. Neon automatically suspends a compute after 5 minutes of inactivity, by default. You can reproduce this error by connecting to your database from an application or client such as `psql`, letting the connection remain idle until the compute suspends, and then running a query from the same connection.

If you encounter this error, you can try adjusting the timing of your query or reestablishing the connection before running the query. Alternatively, if you are on a paid plan, you can disable scale to zero. For instructions, see [Configuring scale to zero for Neon computes](https://neon.com/docs/guides/scale-to-zero-guide). [Free plan](https://neon.com/docs/introduction/plans) users cannot disable scale to zero.

## Unsupported startup parameter

This error is reported in two variations:

```text
unsupported startup parameter: <...>
```

```text
unsupported startup parameter in options: <...>
```

The error occurs when using a pooled Neon connection string with startup options that are not supported by PgBouncer. PgBouncer allows only startup parameters it can keep track of in startup packets. These include: `client_encoding`, `datestyle`, `timezone`, `standard_conforming_strings`, and `application_name`. See **track_extra_parameters**, in the [PgBouncer documentation](https://www.pgbouncer.org/config.html#track_extra_parameters). To resolve this error, you can either remove the unsupported parameter from your connection string or use an unpooled Neon connection string. For information about pooled and unpooled connections in Neon, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## You have exceeded the limit of concurrently active endpoints

This error can also appear as: `active endpoints limit exceeded`.

Neon limits [concurrently active computes](https://neon.com/docs/reference/glossary#concurrently-active-compute-limit) to prevent resource exhaustion. When you exceed the limit, additional computes beyond the limit will remain suspended and you will see this error when attempting to connect to them. You can suspend other active computes and try again. Alternatively, if you encounter this error often, you can reach out to [Support](https://neon.com/docs/introduction/support) to request a `max_active_endpoints` limit increase.

## Remaining connection slots are reserved for roles with the SUPERUSER attribute

This error occurs when the maximum number of simultaneous database connections, defined by the Postgres `max_connections` setting, is reached.

To resolve this issue, you have several options:

- Find and remove long-running or idle connections. See [Find long-running or idle connections](https://neon.com/docs/postgresql/query-reference#find-long-running-or-idle-connections).
- Use a larger compute, with a higher `max_connections` configuration. See [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).
- Enable [connection pooling](https://neon.com/docs/connect/connection-pooling).

If you are already using connection pooling, you may need to reach out to Neon Support to request a higher `default_pool_size` setting for PgBouncer. See [Neon PgBouncer configuration settings for more information](https://neon.com/docs/connect/connection-pooling#neon-pgbouncer-configuration-settings).

## Relation not found

This error is often encountered when attempting to set the Postgres `search_path` session variable using a `SET search_path` statement over a pooled connection. For more information and workarounds, please see [Connection pooling in transaction mode](https://neon.com/docs/connect/connection-pooling#connection-pooling-in-transaction-mode).

## cannot execute ... in a read-only transaction (SQLSTATE 25006)

You attempted a write (`INSERT`, `UPDATE`, `DELETE`, `MERGE`, `COPY ... FROM`, or DDL such as `CREATE`, `ALTER`, `DROP`, or `TRUNCATE`) in a transaction that Postgres treats as read-only. The error looks like this:

```text
ERROR: cannot execute INSERT in a read-only transaction (SQLSTATE 25006)
```

Postgres raises this error (error code `25006`, `read_only_sql_transaction`) in three situations:

**1. You're connected to a read replica.** A [read replica](https://neon.com/docs/introduction/read-replicas) runs on a compute in recovery, which forces every transaction to be read-only. This is the most common cause. Writes must go to your read/write (primary) compute.

- Confirm which compute you're connected to. If your connection string points at a read replica compute, switch to your read/write compute for writes.
- If your framework routes reads and writes separately, make sure write and transaction queries target the primary. See [Use read replicas with Prisma](https://neon.com/docs/guides/read-replica-prisma) for an example.
- You can check whether the current connection is a replica by running `SELECT pg_is_in_recovery();`. A result of `t` means you're on a read replica.

**2. The session or transaction was set read-only.** An explicit `BEGIN TRANSACTION READ ONLY`, `SET TRANSACTION READ ONLY`, or `SET default_transaction_read_only = on` makes writes fail with this error.

- Check the setting with `SHOW default_transaction_read_only;`. If it's `on`, reset it with `RESET default_transaction_read_only;` (or `SET default_transaction_read_only = off;`).
- Prefer scoping read-only mode to individual transactions (`BEGIN TRANSACTION READ ONLY`) rather than setting it at the session, database, or role level.

**3. A pooled connection inherited a read-only setting from a previous session.** Neon's [pooled connection](https://neon.com/docs/connect/connection-pooling) uses PgBouncer in transaction mode, where backend connections are reused across clients. If one client sets `default_transaction_read_only = on` (or `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY`) and doesn't reset it, a later client that reuses the same backend can inherit the read-only state and hit this error intermittently.

- Audit your application code, migrations, and scheduled jobs for session-level `SET default_transaction_read_only` or `SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY`. Replace them with transaction-scoped `BEGIN TRANSACTION READ ONLY`, or run `RESET default_transaction_read_only` / `DISCARD ALL` before returning the connection.
- Run schema migrations, `pg_dump`, `pg_restore`, and other administrative tasks over a [direct (unpooled) connection string](https://neon.com/docs/connect/connection-pooling#when-to-use-pooled-vs-direct-connections) so session state can't leak into the pool. Note that the pooled endpoint does not route you to a read replica; it targets your read/write compute.

## Postgrex: DBConnection ConnectionError ssl send: closed

Postgrex has an `:idle_interval` connection parameter that defines an interval for pinging connections after a period of inactivity. The default setting is `1000ms`. If you rely on Neon's [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero) feature (auto-suspend) to scale your compute to zero when your database is not active, this setting will prevent that and you may encounter a `(DBConnection.ConnectionError) ssl send: closed (ecto_sql 3.12.0)` error as a result. As a workaround, you can set the interval to a higher value to allow your Neon compute to suspend. For example:

```elixir
config :app_name, AppName.Repo
  # normal connection options
  ...
  idle_interval:
:timer.hours(24)
```

For additional details, refer to this discussion on our Discord server: [Compute not suspended due to Postgrex idle_interval setting](https://discord.com/channels/1176467419317940276/1295401751574351923/1295419826319265903)

## query_wait_timeout SSL connection has been closed unexpectedly

The `query_wait_timeout` setting is a PgBouncer configuration option that determines the maximum time a query can wait in the queue before being executed. Neon's default value for this setting is **120 seconds**. If a query exceeds this timeout while in the queue, it will not be executed. For more details about this setting, refer to [Neon PgBouncer configuration settings](https://neon.com/docs/connect/connection-pooling#neon-pgbouncer-configuration-settings).

To avoid this error, we recommend reviewing your workload. If it includes batch processing with `UPDATE` or `INSERT` statements, review their performance. Slow queries may be the root cause. Try optimizing these queries to reduce execution time, which can help prevent them from exceeding the timeout.

Alternatively, Neon can increase the `query_wait_timeout` value for you, but this is not typically recommended, as increasing the timeout can lead to higher latency or blocked queries under heavy workloads.

## The request could not be authorized due to an internal error

This error page in the Neon Console is most often the result of attempting to access a Neon project in one browser window after you've have logged in under a different Neon user account from another browser window. The error occurs because the currently logged in Neon user account does not have access to the Neon project. To avoid this issue, ensure that you're logged in with a Neon user account that has access to the Neon project you're trying to access.

## Terminating connection due to idle-in-transaction timeout

This error occurs when a session remains idle within an open transaction for longer than the specified timeout period. By default, the `idle_in_transaction_session_timeout` setting is set to `5min` (300,000 milliseconds). This timeout helps prevent idle sessions from holding locks or contributing to table bloat.

If you encounter this error, you can adjust the `idle_in_transaction_session_timeout` setting to a higher value or disable it entirely by setting it to `0`. Below are ways to change this setting:

1. Change at the session level: `SET idle_in_transaction_session_timeout = 0;`

2. Change at the database level: `ALTER DATABASE <dbname> SET idle_in_transaction_session_timeout = 0;` (replace `<dbname>` with the name of your database)

3. Change at the role level: `ALTER ROLE <role> SET idle_in_transaction_session_timeout = 0;` (replace `<role>` with the name of the user role)

Be aware that leaving transactions idle for extended periods can prevent vacuuming and increase the number of open connections. Please use caution and consider only changing the value temporarily, as needed.

## Error connecting to database: Failed to fetch

This error appears on the **Tables** page in the Neon Console when the Console's request to your compute doesn't complete:

```text
Error connecting to database: Failed to fetch
```

The most common causes, in order, are:

- **The compute is starting up.** If your compute is suspended after [scale to zero](https://neon.com/docs/introduction/scale-to-zero), the Console wakes it before listing tables, and the first request can fail before the compute is ready. Wait a second or two and click **Refresh**. The second request usually succeeds. You can confirm the compute state on the **Branches** page, where a suspended compute shows as **Idle**. See [Couldn't connect to compute node](https://neon.com/docs/connect/connection-errors#couldnt-connect-to-compute-node) for more on cold-start timing.
- **A browser extension is blocking the request.** Ad-blockers, privacy extensions, and corporate browser security tools sometimes block requests to `*.neon.tech`. Open the Console in an incognito window with extensions disabled, or temporarily disable extensions like uBlock Origin or Privacy Badger on `console.neon.tech` and reload. Check the browser's developer console (**F12 → Network**) for blocked requests to your compute hostname.
- **IP Allow is rejecting your connection.** If you've configured an [IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow) list (Scale plan), the Tables view connects from the IP address you're browsing from, so the request is rejected when that address isn't on the allowlist. Add your current IP address under **Settings → Networking**, or if you only need IP Allow on protected branches, enable **Restrict IP Access to protected branches only** so queries against development branches still work.
- **A DNS resolution issue.** Some networks fail to resolve compute hostnames. See [DNS resolution issues](https://neon.com/docs/connect/connection-errors#dns-resolution-issues) below to test and resolve this.
- **A transient backend error.** If none of the above explain it, check the [Neon status page](https://neonstatus.com/) for ongoing incidents.

**Tip: Grab the error ID before contacting Support**

The full error message on the Tables view includes an error ID after the colon. Copy it before refreshing. Support uses that ID to look up the exact request in our logs, which is faster than reproducing the issue.

## DNS resolution issues

Some users encounter DNS resolution failures when connecting to their Neon database. These issues are often reported when using the **Tables** page in the Neon Console. In such cases, users may see an **Unexpected error happened** message like the one below:

![Unexpected error happened on Tables page](https://neon.com/docs/guides/tables_error.png)

To check for a DNS resolution issue, you can run `nslookup` on your Neon hostname, which is the part of your Neon database [connection string](https://neon.com/docs/reference/glossary#connection-string) starting with your endpoint ID (for example, `ep-cool-darkness-a1b2c3d4`) and ending with `neon.tech`. For example:

```bash
nslookup ep-cool-darkness-a1b2c3d4.ap-southeast-1.aws.neon.tech
```

If the Neon hostname resolves correctly, you'll see output similar to this:

```bash
nslookup ep-cool-darkness-a1b2c3d4.ap-southeast-1.aws.neon.tech
Server:		192.168.2.1
Address:	192.168.2.1#53

Non-authoritative answer:
ep-cool-darkness-a1b2c3d4.ap-southeast-1.aws.neon.tech	canonical name = ap-southeast-1.aws.neon.tech.
Name:	ap-southeast-1.aws.neon.tech
Address: 203.0.113.10
Name:	ap-southeast-1.aws.neon.tech
Address: 203.0.113.20
Name:	ap-southeast-1.aws.neon.tech
Address: 203.0.113.30
```

If the hostname does not resolve, you might see an error like this, where the DNS query is refused:

```bash
** server can't find ep-cool-darkness-a1b2c3d4.ap-southeast-1.aws.neon.tech: REFUSED
```

To verify that it's a DNS resolution issue, run the following test using a public DNS resolver, such as Google DNS:

```bash
nslookup ep-cool-darkness-a1b2c3d4.ap-southeast-1.aws.neon.tech 8.8.8.8
```

If this succeeds, it's very likely a DNS resolution issue.

**Cause**

Failure to resolve the Neon hostname can happen for different reasons:

- Regional DNS caching or propagation delays
- Restrictive or misconfigured DNS resolvers (such as those provided by your ISP)
- System-wide web proxy settings that interfere with DNS resolution

**Workarounds**

1. **Using a Public DNS Resolver**

   - Google DNS: 8.8.8.8, 8.8.4.4
   - Cloudflare DNS: 1.1.1.1, 1.0.0.1

   These can be changed at:

   - OS level (macOS, Windows, Linux)
   - Router level
   - Mobile device network settings
   - Android Private DNS (configure a trusted provider such as `dns.google` or `1dot1dot1dot1.cloudflare-dns.com`)

   To change your DNS configuration at the OS level:

   - **macOS**: System Settings → Network → Wi-Fi → Details → DNS
   - **Windows**: Control Panel → Network and Internet → Network Connections → Right-click your connection → Properties → Internet Protocol Version 4 (TCP/IPv4)
   - **Linux**: Edit `/etc/resolv.conf` or configure your network manager (for example, NetworkManager, Netplan)

   This article provides detailed instructions: [How to Turn on Private DNS Mode](https://news.trendmicro.com/2023/03/21/how-to-turn-on-private-dns-mode/)

2. **Disable system-wide web proxies**

   If you're using a proxy configured at the OS level, it may interfere with DNS lookups. To check and disable system proxy settings:

   - **macOS**: System Settings → Network → Wi-Fi → Details → Proxies. Uncheck any active proxy options (for example, "Web Proxy (HTTP)", "Secure Web Proxy (HTTPS)")
   - **Windows**: Settings → Network & Internet → Proxy. Turn off "Use a proxy server" if it's enabled
   - **Linux**: Check your environment variables (for example, `http_proxy`, `https_proxy`) and system settings under Network/Proxy.

3. **Using a VPN**

   Using a VPN routes DNS queries through a different resolver and often bypasses the issue entirely.

--- [Document source](https://neon.com/docs/connect/connection-latency.md) ---

> Summary: Connection latency in Neon is primarily caused by cold starts when a compute wakes from Scale to zero, typically adding a few hundred milliseconds. Options for reducing cold-start delays include disabling scale-to-zero, tuning the suspend timeout, co-locating the application and database in the same region, and adding retry logic with exponential backoff. Also covers the `sslnegotiation=direct` parameter, which shortens SSL handshake time on Neon's proxy layer regardless of the underlying database version.

# Connection latency and timeouts

Learn about strategies to manage connection latencies and timeouts

Last updated: 2026-11-04

Neon's _Scale to zero_ feature is designed to minimize costs by automatically scaling a compute resource down to zero after a period of inactivity. By default, Neon scales a compute to zero after 5 minutes of inactivity. A characteristic of this feature is the concept of a "cold start". During this process, a compute transitions from an idle state to an active state to process requests. Currently, activating a Neon compute from an idle state typically takes a few hundred milliseconds not counting other factors that can add to latencies such as the physical distance between your application and database or startup times of other services that participate in your connection process.

**Note:** Services you integrate with Neon may also have startup times, which can add to connection latencies. This topic does not address latencies of other vendors, but if your application connects to Neon via another service, remember to consider startup times for those services as well.

## Check the status of a compute

You can check the current status of a compute on the **Branches** page in the Neon Console. A compute will report either an **Active** or **Idle** status.

![Compute status](https://neon.com/docs/connect/compute_endpoint_state.png)

You can also see each branch's compute status and when it was last active on the **Branches** page.

User actions that activate an idle compute include connecting from a client or application, running a query on your database from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), or accessing the compute via the [Neon API](https://neon.com/docs/reference/api).

**Info:** The Neon API includes [Start endpoint](https://neon.com/docs/reference/api/endpoints/start-project-endpoint) and [Suspend endpoint](https://neon.com/docs/reference/api/endpoints/suspend-project-endpoint) APIs for the specific purpose of activating and suspending a compute.

You can try any of these methods and watch the status of your compute as it changes from an **Idle** to an **Active** state. By default, a compute is suspended after 300 seconds (5 minutes) of inactivity. Users on the Neon [Scale plan](https://neon.com/docs/introduction/plans) can configure this delay period, which is described later in this topic.

## Strategies for managing latency and timeouts

Given the potential impact on application responsiveness, it's important to have strategies in place to manage connection latencies and timeouts. Here are some methods you can implement:

- [Adjust your Scale to zero configuration](https://neon.com/docs/connect/connection-latency#adjust-your-scale-to-zero-configuration)
- [Place your application and database in the same region](https://neon.com/docs/connect/connection-latency#place-your-application-and-database-in-the-same-region)
- [Increase your connection timeout](https://neon.com/docs/connect/connection-latency#increase-your-connection-timeout)
- [Build connection timeout handling into your application](https://neon.com/docs/connect/connection-latency#build-connection-timeout-handling-into-your-application)
- [Use application-level caching](https://neon.com/docs/connect/connection-latency#use-application-level-caching)

### Adjust your scale to zero configuration

If cold starts are not acceptable for your workload, you can disable scale to zero entirely on a paid plan to keep your compute always active. See [Scale to zero](https://neon.com/docs/introduction/scale-to-zero) for configuration steps.

For workloads where occasional cold starts are acceptable, you can also adjust the timeout period. The default is 5 minutes. You can extend it up to 7 days to reduce how often cold starts occur, or on the Scale plan, configure it down to as little as 1 minute.

**Important:** If you disable scale to zero entirely or your compute is never idle long enough to be automatically suspended, you will have to manually restart your compute to pick up the latest updates to Neon's compute images. Neon typically releases compute-related updates weekly. Not all releases contain critical updates, but a weekly compute restart is recommended to ensure that you do not miss anything important. For how to restart a compute, see [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

To configure a custom scale to zero setting, modify `suspend_timeout_seconds` using the [Update compute endpoint API](https://neon.com/docs/reference/api/endpoints/update-project-endpoint) API, as shown below. To use this API, you need to specify your project ID and compute endpoint ID. You can find your project ID in your project's settings. You can find the compute endpoint ID on your branch page.

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project_id}/endpoints/{endpoint_id} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "endpoint": {
    "suspend_timeout_seconds": 300
  }
}
'
```

Consider combining this strategy with Neon's _Autoscaling_ feature, which allows you to run a compute with minimal resources and scale up on demand. For example, with autoscaling, you can configure a minimum compute size to reduce costs during off-peak times. In the image shown below, the scale to zero setting is set to 1 hour so that your compute only suspends after an hour of inactivity, and autoscaling is configured with a minimum compute size that keep costs low during periods of light usage.

For autoscaling configuration instructions, see [Compute size and autoscaling configuration](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration).

### Place your application and database in the same region

A key strategy for reducing connection latency is ensuring that your application and database are hosted in the same region, or as close as possible, geographically. For the regions supported by Neon, see [Regions](https://neon.com/docs/introduction/regions). For planning a move to another region, see [Migrate to another Neon region](https://neon.com/docs/import/migrate-neon-to-another-region) and [Import data from another Neon project](https://neon.com/docs/import/migrate-from-neon).

### Increase your connection timeout

By configuring longer connection timeout durations, your application has more time to accommodate cold starts and other factors that contribute to latency.

Connection timeout settings are typically configured in your application or the database client library you're using, and the specific way to do it depends on the language or framework you're using.

Here are examples of how to increase connection timeout settings in a few common programming languages and frameworks:

**Node.js**

```javascript
const { Pool } = require('pg');

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  connectionTimeoutMillis: 10000, // connection timeout in milliseconds
  idleTimeoutMillis: 10000, // idle timeout in milliseconds
});
```

**Python**

```python
import psycopg2
from psycopg2 import connect
from psycopg2.extensions import ISOLATION_LEVEL_AUTOCOMMIT
import os

DATABASE_URL = os.environ['DATABASE_URL']

conn = psycopg2.connect(DATABASE_URL, connect_timeout=10)
```

**Java**

```java
import java.sql.Connection;
import java.sql.DriverManager;
import java.util.Properties;

String dbUrl = System.getenv("DATABASE_URL");
Properties properties = new Properties();
properties.setProperty("connectTimeout", "10");

Connection conn = DriverManager.getConnection(dbUrl, properties);
```

**Prisma**

```prisma
DATABASE_URL=postgresql://[user]:[password]@[neon_hostname]/[dbname]?connect_timeout=15&pool_timeout=15`
```

**Note:** If you are using Prisma Client, your timeout issue could be related to Prisma's connection pool configuration. The Prisma Client query engine instantiates its own connection pool when it opens a first connection to the database. If you encounter a `Timed out fetching a new connection from the connection pool` error, refer to [Prisma connection pool timeouts](https://neon.com/docs/guides/prisma#troubleshooting) for information about configuring your Prisma connection pool size and pool timeout settings.

Remember that increasing connection timeout settings might impact the responsiveness of your application, and users could end up waiting longer for their requests to be processed. Always test and monitor your application's performance when making changes like these.

### Build connection timeout handling into your application

You can prepare your application to handle connection timeouts when latency is unavoidable. This might involve using retries with exponential backoff. This Javascript example connects to the database using the `pg` library and uses the `node-retry` library to handle connection retries with an exponential backoff. The general logic can be easily translated into other languages.

```javascript
require('dotenv').config();
var Client = require('pg').Client;
var retry = require('retry');

// Connection string from .env file
var connectionString = process.env.DATABASE_URL;

function connectWithRetry() {
  var operation = retry.operation({
    retries: 5, // number of retries before giving up
    minTimeout: 4000, // minimum time between retries in milliseconds
    randomize: true, // adds randomness to timeouts to prevent retries from overwhelming the server
  });

  operation.attempt(function (currentAttempt) {
    var client = new Client({ connectionString });

    client
      .connect()
      .then(function () {
        console.log('Connected to the database');

        // Perform your operations with the client
        // For example, let's run a simple SELECT query
        return client.query('SELECT NOW()');
      })
      .then(function (res) {
        console.log(res.rows[0]);

        return client.end();
      })
      .catch(function (err) {
        if (operation.retry(err)) {
          console.warn(`Failed to connect on attempt ${currentAttempt}, retrying...`);
        } else {
          console.error('Failed to connect to the database after multiple attempts:', err);
        }
      });
  });
}

// Usage
connectWithRetry();
```

In the example above, the `operation.attempt` function initiates the connection logic. If the connection fails (i.e., `client.connect()` returns a rejected Promise), the error is passed to `operation.retry`(err). If there are retries left, the retry function schedules another attempt with a delay based on the parameters defined in the `retry.operation`. The delay between retries is controlled by the `minTimeout` and `randomize` options.

The randomize option adds a degree of randomness to the delay to prevent a large number of retries from potentially overwhelming the server. The `minTimeout` option defines the minimum time between retries in milliseconds.

However, this example is a simplification. In a production application, you might want to use a more sophisticated strategy. For example, you could initially attempt to reconnect quickly in the event of a transient network issue, then fall back to slower retries if the problem persists.

For complete examples with connection pooling, transaction handling, and idempotency patterns for write operations, see [Building resilient applications with Postgres](https://neon.com/guides/building-resilient-applications-with-postgres).

#### Connection retry references

- [Building resilient applications with Postgres](https://neon.com/guides/building-resilient-applications-with-postgres)
- [SQL Alchemy: Dealing with disconnects](https://arc.net/l/quote/nojcaewr)
- [Fast API blog post: Recycling connections for Neon's scale to zero](https://neon.com/blog/deploy-a-serverless-fastapi-app-with-neon-postgres-and-aws-app-runner-at-any-scale)

### Use application-level caching

Implement a caching system like [Redis](https://redis.io/) to store frequently accessed data, which can be rapidly served to users. This approach can help reduce occurrences of latency, but only if the data requested is available in the cache. Challenges with this strategy include cache invalidation due to frequently changing data, and cache misses when queries request uncached data. This strategy will not avoid latency entirely, but you may be able to combine it with other strategies to improve application responsiveness overall.

### Optimizing connection latency with sslnegotiation

Starting with PostgreSQL 17, you can use the `sslnegotiation` connection parameter to control how SSL negotiation is handled when establishing a connection. The `sslnegotiation=direct` option reduces connection latency by skipping unnecessary negotiation steps.

Neon has implemented support for `sslnegotiation=direct` in our proxy layer, allowing you to benefit from faster connection times even if your database runs on an older PostgreSQL version. You just need a PostgreSQL 17 client to use this feature.

Here's a comparison of connection times with and without the `sslnegotiation=direct` parameter:

**Without sslnegotiation=direct:**

```bash
$ time psql "postgresql://neondb_owner@your-neon-endpoint/neondb?sslmode=require&channel_binding=require" -c "SELECT version();"
                                                version
---------------------------------------------------------------------------------------------------------
PostgreSQL 16.4 on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
(1 row)

real    0m0.872s
user    0m0.019s
sys     0m0.000s
```

**With sslnegotiation=direct:**

```bash
$ time psql "postgresql://neondb_owner@your-neon-endpoint/neondb?sslmode=require&channel_binding=require&sslnegotiation=direct" -c "SELECT version();"
                                                version
---------------------------------------------------------------------------------------------------------
PostgreSQL 17.0 on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
(1 row)

real    0m0.753s
user    0m0.016s
sys     0m0.005s
```

As shown in the example above, using `sslnegotiation=direct` reduces the connection time by skipping the initial SSL negotiation step. To use this optimization, simply append `sslnegotiation=direct` to your connection string:

```text
postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=verify-full&sslnegotiation=direct
```

## Latency benchmarking

See [Benchmarking latency in Neon's serverless Postgres](https://neon.com/docs/guides/benchmarking-latency) to learn how to measure and optimize query latency in your Neon database.

## Conclusion

With the right strategies, you can optimize your system to handle connection latencies and timeouts, ensuring your application delivers a consistently high level of performance. The best solution often involves a combination of strategies, so experiment and find the right configuration for your specific use case.

## Related resources

- [Neon latency benchmarks dashboard](https://neon.com/demos/regional-latency) - Interactive dashboard showing real-world latency measurements across different regions and workloads ([source code](https://github.com/neondatabase-labs/latency-benchmarks))
- [Connection pooling guide](https://neon.com/docs/connect/connection-pooling) - Reduce latency with efficient connection management
- [Regional deployment options](https://neon.com/docs/introduction/regions) - Choose the optimal region for lowest latency
- [Ship faster with Postgres](https://neon.tech/faster) - Explore examples and case studies demonstrating rapid development workflows

--- [Document source](https://neon.com/docs/connect/connection-pooling.md) ---

> Summary: Neon connection pooling uses PgBouncer in transaction mode, accepting up to 10,000 client connections through per-user, per-database pools sized at 90% of max_connections. Use the pooled connection string (hostname with -pooler suffix) for serverless functions and connection-per-request workloads. Use a direct connection for schema migrations, pg_dump, logical replication, and queries that depend on SET, LISTEN/NOTIFY, or session-level state. In transaction mode, SET, temporary tables, and SQL-level PREPARE/DEALLOCATE are not supported on pooled connections, though protocol-level prepared statements are supported.

# Connection pooling

Learn how connection pooling works in Neon

Last updated: 2026-10-19

Neon uses [PgBouncer](https://www.pgbouncer.org/) to provide connection pooling, enabling up to 10,000 concurrent connections. This guide explains how pooling works, when to use it, and how to avoid common issues.

## Why connection pooling matters

Each Postgres connection creates a new process in the operating system, consuming memory and CPU resources. Postgres limits the number of connections based on available RAM. In Neon, this limit is defined by `max_connections`, which varies by compute size:

| Compute size (CU) | RAM         | max\_connections |
| :---------------- | :---------- | :--------------- |
| 0.25              | 1 GB        | 104              |
| 0.50              | 2 GB        | 209              |
| 1                 | 4 GB        | 419              |
| 2                 | 8 GB        | 839              |
| 3                 | 12 GB       | 1258             |
| 4                 | 16 GB       | 1678             |
| 5                 | 20 GB       | 2098             |
| 6                 | 24 GB       | 2517             |
| 7                 | 28 GB       | 2937             |
| 8                 | 32 GB       | 3357             |
| 9 - 56            | 36 - 224 GB | 4000             |

**Note:** For compute sizes 9 CU and above, `max_connections` is capped at 4000 regardless of RAM size. See [Postgres settings that differ by compute size](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size) for details.

**Note:** Seven connections are reserved for the Neon superuser account. For a 0.25 CU compute, this means 97 connections are available for your application (104 total - 7 reserved).

**Common scenarios that exceed these limits:**

- Serverless functions (each invocation may open a connection)
- Connection-per-request web frameworks
- Multiple application instances without proper connection management
- Applications that don't close connections properly

Check your current limit:

```sql
SHOW max_connections;
```

View active connections:

```sql
SELECT usename, count(*)
FROM pg_stat_activity
WHERE datname = '<database_name>'
GROUP BY usename;
```

You can also view active connections on the [Monitoring page](https://neon.com/docs/introduction/monitoring-page#connections) in the Neon Console, which provides a visual graph of connection usage over time.

## How Neon's connection pooling works

Connection pooling solves the `max_connections` limit by maintaining a pool of reusable connections. Instead of opening a new Postgres connection for each client, PgBouncer routes multiple client connections through a smaller pool of actual Postgres connections.

```mermaid
flowchart LR
  subgraph client["Client application"]
    c1["user 1"]
    c2["user 1"]
    c3["..."]
    c4["user 2"]
    c5["user 1"]
  end

  subgraph pooler["PgBouncer connection pooler"]
    p1["user1/database1 pool"]
    p2["user2/database1 pool"]
    p3["user1/database2 pool"]
  end

  subgraph postgres["Postgres (max_connections limit)"]
    d1[("database 1")]
    d2[("database 2")]
  end

  c1 --> p1
  c2 --> p1
  c3 --> p1
  c4 --> p2
  c5 --> p3
  p1 --> d1
  p2 --> d1
  p3 --> d2
```

_The diagram shows how multiple client connections from different users route through separate PgBouncer pools (one per user/database combination), which share a limited number of actual Postgres connections to access the databases._

### Key concept: Per-user, per-database pools

**An important thing to understand about Neon's connection pooling:**

PgBouncer creates separate pools for each combination of database user and database name. This means:

- User `user1` connecting to `database1` gets one pool
- User `user2` connecting to `database1` gets a separate pool
- User `user1` connecting to `database2` gets another separate pool

Each pool has a maximum size defined by `default_pool_size`. In Neon, this is configured as:

```
default_pool_size = 0.9 × max_connections
```

For details on how `max_connections` is set based on compute size, see [Parameter settings that differ by compute size](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size).

**Example with a 1 CU compute:**

- `max_connections` = 419
- `default_pool_size` = 377 (90% of 419)

This means:

- User `user1` can have up to 377 active transactions to `database1` through the pooler
- User `user2` can simultaneously have up to 377 active transactions to the same `database1` database
- User `user1` can also have up to 377 active transactions to a different database `database2`

All of these pools share the underlying `max_connections` limit (419 in this example).

### Connection pooling vs concurrent queries

**Important:** The 10,000 connection limit does not mean 10,000 simultaneous query results.

- **10,000** = Maximum number of client connections PgBouncer can accept
- **~377** (for 1 CU) = Maximum concurrent active transactions per user per database
- **419** (for 1 CU) = Maximum concurrent connections to actual Postgres

The 10,000 limit is useful for applications with many idle or short-lived connections, such as serverless functions where connections are opened and closed frequently.

## Understanding connection pool limits

### Three types of limits

| Limit Type          | Value                    | What it controls                                 | When you hit it                            |
| ------------------- | ------------------------ | ------------------------------------------------ | ------------------------------------------ |
| `max_client_conn`   | 10,000                   | Maximum client connections to PgBouncer          | Client gets: "no more connections allowed" |
| `default_pool_size` | 90% of `max_connections` | Maximum active connections per user per database | Client waits in queue (2 min timeout)      |
| `max_connections`   | Varies by compute        | Direct connections to Postgres                   | Client gets: "too many connections"        |

### What happens when you hit limits

**Scenario 1: Hitting the per-user-per-database pool limit**

You have a 1 CU compute (`default_pool_size` = 377). User `user1` opens 377 connections to `database1`, all running long queries:

```
Connection 378 from user1 to database1 → Waits in queue
After 2 minutes → Error: "query_wait_timeout"
```

**Solution:**

- Ensure transactions complete quickly
- Use a larger compute size (increases pool size)
- Use multiple database users to get additional pools

**Scenario 2: Hitting the global client connection limit**

Your application opens 10,001 client connections to PgBouncer:

```
Connection 10,001 → Error: "no more connections allowed (max_client_conn)"
```

**Solution:**

- Fix connection leaks in your application
- Implement client-side connection pooling
- Reduce the number of application instances

**Scenario 3: Hitting max_connections with direct connections**

Using a non-pooled connection string with a 0.25 CU compute (104 max_connections):

```
Connection 105 → Error: "FATAL: remaining connection slots are reserved"
```

**Solution:**

- Use a pooled connection string (add `-pooler` to hostname)
- Increase compute size
- Implement connection pooling in your application

## How to use connection pooling

To enable connection pooling, use a pooled connection string. Add `-pooler` to your endpoint ID:

**Direct connection (no pooling):**

```text
postgresql://user1:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require
```

**Pooled connection:**

```text
postgresql://user1:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require
```

You can copy a pooled connection string from the Neon Console by clicking **Connect** in the Console nav and enabling the **Connection pooling** toggle.

![Connection Details pooled connection string](https://neon.com/docs/connect/connect_to_branch_modal.png)

### Enable, disable, and find the pooled connection string in the Console

To get the pooled connection string or switch between pooled and direct from the dashboard:

1. Sign in to the [Neon Console](https://console.neon.tech) and select your project.
2. Click **Connect** in the Console nav.
3. In the **Connect to your branch** modal, choose a **Branch**, **Compute**, **Database**, and **Role**.
4. Turn the **Connection pooling** toggle on to get the pooled string, or off to get the direct string, then copy it.

The toggle is on by default for new projects. It doesn't start or stop the pooler at the compute. The pooled endpoint is always available. The toggle just switches the displayed connection string between the pooled hostname (with the `-pooler` suffix) and the direct hostname, so you can pick which one your app uses. To enable pooling in your app, use the pooled string; to disable it, use the direct string.

### When to use pooled vs direct connections

| Use Case                          | Connection Type | Why                                       |
| --------------------------------- | --------------- | ----------------------------------------- |
| Serverless functions              | Pooled          | Many short-lived connections              |
| Web applications                  | Pooled          | Multiple concurrent requests              |
| Connection-per-request frameworks | Pooled          | High connection churn                     |
| Schema migrations                 | Direct          | Tools may not support transaction pooling |
| Long-running analytics queries    | Direct          | Avoid pool contention                     |
| `pg_dump` / `pg_restore`          | Direct          | Uses `SET` statements                     |
| Logical replication               | Direct          | Requires persistent connection            |
| Admin tasks                       | Direct          | May need session-level features           |

If you run on a highly elastic platform such as AWS Fargate, Google Cloud Run, or Vercel, see [Serverless connection pooling](https://neon.com/docs/guides/serverless-connection-pooling) for strategies that prevent connection leaks and exhaustion when instances scale out or suspend.

## Connection pooling in transaction mode

Neon uses PgBouncer in transaction mode (`pool_mode=transaction`), which means connections are returned to the pool after each transaction completes. This limits some Postgres features that require persistent sessions:

**Not supported with pooled connections:**

- `SET` / `RESET` (session variables)
- `LISTEN` / `NOTIFY`
- `WITH HOLD CURSOR`
- `PREPARE` / `DEALLOCATE` (SQL-level prepared statements)
- Temporary tables with `PRESERVE` / `DELETE ROWS`
- `LOAD` statement
- Session-level advisory locks

### Common issues with SET statements

The most common issue users encounter is with `SET` statements, particularly `SET search_path`.

**Problem example:**

```sql
SET search_path TO myschema;
SELECT * FROM mytable;  -- Works in this transaction
-- Transaction ends, connection returns to pool
SELECT * FROM mytable;  -- ERROR: relation "mytable" does not exist
```

**Solutions:**

1. **Use a direct connection** when you need persistent session settings
2. **Specify schema explicitly** in your queries: `SELECT * FROM myschema.mytable`
3. **Set at the role level** (persists across transactions):
   ```sql
   ALTER ROLE user1 SET search_path TO myschema, public;
   ```

This issue also affects tools like `pg_dump`, which relies on `SET` statements. Always use direct connections for `pg_dump`.

For the complete list of limitations, see the [PgBouncer features documentation](https://www.pgbouncer.org/features.html).

## Neon PgBouncer configuration

Neon's PgBouncer configuration:

```ini
[pgbouncer]
pool_mode=transaction
max_client_conn=10000
default_pool_size=0.9 * max_connections
max_prepared_statements=1000
query_wait_timeout=120
```

**Configuration details:**

- **`pool_mode=transaction`**: Connections are returned to the pool after each transaction
- **`max_client_conn=10000`**: Maximum number of client connections PgBouncer accepts
- **`default_pool_size`**: Maximum concurrent connections per user per database (90% of `max_connections`)
- **`max_prepared_statements=1000`**: Maximum protocol-level prepared statements per connection
- **`query_wait_timeout=120`**: Maximum time (seconds) a query waits for a connection from the pool

These settings are not user-configurable.

## Pool lifecycle and compute restarts

Connection pools help minimize disruption during compute restarts (maintenance, updates, or scaling):

- **Automatic reconnection**: Production connection pools detect stale connections and replace them
- **Health checks**: Configure validation queries (`pool_pre_ping` in SQLAlchemy, validation in HikariCP) to test connections before use
- **Connection lifecycle tuning**: Settings like `maxLifetime` (HikariCP) or `idleTimeoutMillis` (node-postgres) refresh connections periodically
- **Retry logic integration**: Combined with [retry logic and exponential backoff](https://neon.com/docs/connect/connection-latency#build-connection-timeout-handling-into-your-application), pools provide resilience during brief interruptions

For complete guidance, see [Building resilient applications with Postgres](https://neon.com/guides/building-resilient-applications-with-postgres).

## Protocol-level prepared statements

PgBouncer supports protocol-level prepared statements (as of PgBouncer 1.22.0), which can improve query performance and security.

**Note:** SQL-level `PREPARE` and `EXECUTE` statements are not supported with PgBouncer. You must use protocol-level prepared statements through your database driver.

**Example with JavaScript (pg):**

```javascript
const query = {
  name: 'fetch-user',
  text: 'SELECT * FROM users WHERE username = $1',
  values: ['alice'],
};
await client.query(query);
```

**Example with Python (psycopg2):**

```python
cur = conn.cursor()
query = "SELECT * FROM users WHERE username = %s;"
cur.execute(query, ('alice',), prepare=True)
results = cur.fetchall()
```

Benefits of prepared statements:

- **Performance**: Query parsing and planning happens once, speeding up repeated executions
- **Security**: Reduces SQL injection risk by separating query structure from data

Most PostgreSQL client libraries support protocol-level prepared statements. Check your driver's documentation for details.

## Monitoring connection pool activity

The [Monitoring page](https://neon.com/docs/introduction/monitoring-page) in the Neon Console provides two dedicated graphs for tracking PgBouncer connection pool activity:

- **Pooler client connections**: Shows connections from your applications to PgBouncer, including active, idle, and waiting states. This helps you understand client-side connection usage and identify when clients are waiting for available server connections.
- **Pooler server connections**: Shows connections from PgBouncer to your Postgres database, including active and idle server connections in the pool. This helps you monitor how efficiently the pool is being used relative to your `default_pool_size` limit.

For detailed descriptions of these graphs and what each connection state means, see:

- [Pooler client connections](https://neon.com/docs/introduction/monitoring-page#pooler-client-connections)
- [Pooler server connections](https://neon.com/docs/introduction/monitoring-page#pooler-server-connections)

PgBouncer metrics are also available via [OpenTelemetry](https://neon.com/docs/guides/opentelemetry) and [Datadog](https://neon.com/docs/guides/datadog) integrations.

--- [Document source](https://neon.com/docs/connect/passwordless-connect.md) ---

> Summary: Use the Neon CLI's `neon psql` command to open a `psql` session against any branch, role, and database in your project, without a connection string or a local psql install. It's the recommended alternative to the older `psql -h pg.neon.tech` passwordless auth flow, which connects only to the first database on the branch and is planned for deprecation in favor of `neon psql`.

# Passwordless auth

Learn how to connect to Neon without a password

Last updated: 2026-07-24

**Tip: Try neon psql instead**

The [Neon CLI](https://neon.com/docs/cli) offers a more capable way to open a `psql` session: [`neon psql`](https://neon.com/docs/cli/psql). It connects to any branch, role, and database in your project, works without a local `psql` install, and supports [pooled connections](https://neon.com/docs/connect/connection-pooling) and [time travel](https://neon.com/docs/guides/time-travel-assist). The `psql -h pg.neon.tech` flow on this page is planned for deprecation in favor of it.

```bash
neon psql
```

To get a connection string instead of an interactive session, use [`neon connection-string`](https://neon.com/docs/cli/connection-string). For all the ways to connect, see [Connect to Neon](https://neon.com/docs/connect/connect-intro).

Neon's `psql` passwordless auth feature helps you quickly authenticate a connection to Neon without providing a password.

The following instructions require a working installation of [psql](https://www.postgresql.org/download/), an interactive terminal for working with Postgres. For information about `psql`, refer to the [psql reference](https://www.postgresql.org/docs/15/app-psql.html), in the _PostgreSQL Documentation_.

To connect using Neon's `psql` passwordless auth feature:

1. In your terminal, run the following command:

   ```bash
   psql -h pg.neon.tech
   ```

   A response similar to the following is displayed:

   ```bash
   NOTICE:  Welcome to Neon!
   Authenticate by visiting (will expire in 2m):
    https://console.neon.tech/psql_session/cd6aebdc9fda9928
   ```

2. In your browser, navigate to the provided link. Log in to Neon if you are not already logged in. You are asked to select a Neon account and project (if you have multiple). If your project has more than one compute, you are also asked to select one.

   After confirming your selections, you are advised that you can return to your terminal or command window where information similar to the following is displayed:

   ```bash
   NOTICE:  Connecting to database.
   psql (17.2)
   SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: postgresql)
   Type "help" for help.

   casey=>
   ```

   The passwordless auth feature connects to the first database created in the branch. To check the database you are connected to, issue this query:

   ```sql
   SELECT current_database();
    current_database
   ------------------
    neondb
   ```

   Switching databases from the `psql` prompt (using `\c <database_name>`, for example) after you have authenticated restarts the passwordless auth authentication process to authenticate a connection to the new database.

## Running queries

After establishing a connection, try running the following queries to validate your database connection:

```sql
CREATE TABLE my_table AS SELECT now();
SELECT * FROM my_table;
```

The following result set is returned:

```sql
SELECT 1
              now
-------------------------------
 2022-09-11 23:12:15.083565+00
(1 row)
```

--- [Document source](https://neon.com/docs/connect/query-with-psql-editor.md) ---

> Summary: The `psql` command-line client connects to Neon using a standard PostgreSQL connection string over SSL on port 5432. Installation steps are provided for Mac, Linux, and Windows. Use this page when you need an interactive terminal session for ad-hoc queries, meta-commands, or scripted SQL against a Neon database. Older `psql` builds without SNI support require a workaround; see the linked connection errors reference for details.

# Connect with psql

Learn how to connect to Neon using psql

Last updated: 2026-10-09

The following instructions require a working installation of [psql](https://www.postgresql.org/download/). The `psql` client is the native command-line client for Postgres. It provides an interactive session for sending commands to Postgres and running ad-hoc queries. For more information about `psql`, refer to the [psql reference](https://www.postgresql.org/docs/15/app-psql.html), in the _PostgreSQL Documentation_.

**Note:** A Neon compute runs Postgres, which means that any Postgres application or standard utility such as `psql` is compatible with Neon. You can also use Postgres client libraries and drivers to connect. However, please be aware that some older client libraries and drivers, including older `psql` executables, are built without [Server Name Indication (SNI)](https://neon.com/docs/reference/glossary#sni) support and require a workaround. For more information, see [Connection errors](https://neon.com/docs/connect/connection-errors).

The [Neon CLI](https://neon.com/docs/cli) also provides a [`neon psql`](https://neon.com/docs/cli/psql) command that opens a `psql` session without a connection string, and doesn't require `psql` to be installed.

## How to install psql

If you don't have `psql` installed already, follow these steps to get set up:

**Mac (Intel x64)**

```bash
brew install libpq
echo 'export PATH="/usr/local/opt/libpq/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**Mac (Apple Silicon)**

```bash
brew install libpq
echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**Linux**

```bash
sudo apt update
sudo apt install postgresql-client
```

**Windows**

Download and install PostgreSQL from:

[https://www.postgresql.org/download/windows/](https://www.postgresql.org/download/windows/)

Ensure psql is included in the installation.

## Connect to Neon with psql

The easiest way to connect to Neon using `psql` is with a connection string.

You can obtain a connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select a branch, a role, and the database you want to connect to. A connection string is constructed for you.

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

From your terminal or command prompt, run the `psql` client with the connection string copied from the **Connect** dialog in the Neon Console.

```bash
psql postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

**Note:** Neon requires that all connections use SSL/TLS encryption, but you can increase the level of protection using the `sslmode` parameter setting in your connection string. For instructions, see [Connect to Neon securely](https://neon.com/docs/connect/connect-securely).

### Where do I obtain a password?

You can obtain a Neon connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

### What port does Neon use?

Neon uses the default Postgres port, `5432`. If you need to specify the port in your connection string, you can do so as follows:

```bash
psql postgresql://[user]:[password]@[neon_hostname][:port]/[dbname]
```

## Running queries

After establishing a connection, try running the following queries:

```sql
CREATE TABLE my_table AS SELECT now();
SELECT * FROM my_table;
```

The following result set is returned:

```sql
SELECT 1
              now
-------------------------------
 2022-09-11 23:12:15.083565+00
(1 row)
```

## Meta-commands

The `psql` client supports a variety of meta-commands, which act like shortcuts for interacting with your database.

### Benefits of Meta-Commands

Meta-commands can significantly speed up your workflow by providing quick access to database schemas and other critical information without needing to write full SQL queries. They are especially useful for database management tasks, making it easier to handle administrative duties directly from the Neon Console.

### Available meta-commands

Here are some of the meta-commands that you can use with `psql`.

**Note:** The Neon SQL Editor also supports meta-commands. See [Meta commands in the Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor#meta-commands).

```bash
Informational
  (options: S = show system objects, + = additional detail)
  \d[S+]                 list tables, views, and sequences
  \d[S+]  NAME           describe table, view, sequence, or index
  \da[S]  [PATTERN]      list aggregates
  \dA[+]  [PATTERN]      list access methods
  \dAc[+] [AMPTRN [TYPEPTRN]]  list operator classes
  \dAf[+] [AMPTRN [TYPEPTRN]]  list operator families
  \dAo[+] [AMPTRN [OPFPTRN]]   list operators of operator families
  \dAp[+] [AMPTRN [OPFPTRN]]   list support functions of operator families
  \db[+]  [PATTERN]      list tablespaces
  \dc[S+] [PATTERN]      list conversions
  \dconfig[+] [PATTERN]  list configuration parameters
  \dC[+]  [PATTERN]      list casts
  \dd[S]  [PATTERN]      show object descriptions not displayed elsewhere
  \dD[S+] [PATTERN]      list domains
  \ddp    [PATTERN]      list default privileges
  \dE[S+] [PATTERN]      list foreign tables
  \des[+] [PATTERN]      list foreign servers
  \det[+] [PATTERN]      list foreign tables
  \deu[+] [PATTERN]      list user mappings
  \dew[+] [PATTERN]      list foreign-data wrappers
  \df[anptw][S+] [FUNCPTRN [TYPEPTRN ...]]
                         list [only agg/normal/procedure/trigger/window] functions
  \dF[+]  [PATTERN]      list text search configurations
  \dFd[+] [PATTERN]      list text search dictionaries
  \dFp[+] [PATTERN]      list text search parsers
  \dFt[+] [PATTERN]      list text search templates
  \dg[S+] [PATTERN]      list roles
  \di[S+] [PATTERN]      list indexes
  \dl[+]                 list large objects, same as \lo_list
  \dL[S+] [PATTERN]      list procedural languages
  \dm[S+] [PATTERN]      list materialized views
  \dn[S+] [PATTERN]      list schemas
  \do[S+] [OPPTRN [TYPEPTRN [TYPEPTRN]]]
                         list operators
  \dO[S+] [PATTERN]      list collations
  \dp[S]  [PATTERN]      list table, view, and sequence access privileges
  \dP[itn+] [PATTERN]    list [only index/table] partitioned relations [n=nested]
  \drds [ROLEPTRN [DBPTRN]] list per-database role settings
  \drg[S] [PATTERN]      list role grants
  \dRp[+] [PATTERN]      list replication publications
  \dRs[+] [PATTERN]      list replication subscriptions
  \ds[S+] [PATTERN]      list sequences
  \dt[S+] [PATTERN]      list tables
  \dT[S+] [PATTERN]      list data types
  \du[S+] [PATTERN]      list roles
  \dv[S+] [PATTERN]      list views
  \dx[+]  [PATTERN]      list extensions
  \dX     [PATTERN]      list extended statistics
  \dy[+]  [PATTERN]      list event triggers
  \l[+]   [PATTERN]      list databases
  \lo_list[+]            list large objects
  \sf[+]  FUNCNAME       show a function's definition
  \sv[+]  VIEWNAME       show a view's definition
  \z[S]   [PATTERN]      same as \dp
```

For more information about meta-commands, see [psql Meta-Commands](https://www.postgresql.org/docs/current/app-psql.html#APP-PSQL-META-COMMANDS).

## Running psql from the Neon CLI

If you have `psql` and the [Neon CLI](https://neon.com/docs/cli) installed, you can run `psql` commands directly from the Neon CLI using the `connection-string` command with the `--psql` option.

```bash
neon connection-string --psql -- -c "SELECT version()"
```

For more examples, see [Neon CLI commands — connection-string](https://neon.com/docs/cli/connection-string).

--- [Document source](https://neon.com/docs/data-api/access-control.md) ---

> Summary: The Neon Data API has no separate permission system. All access control is delegated to PostgreSQL through two layers: GRANT-based table privileges and Row-Level Security (RLS) policies. The database role always comes from the JWT `role` claim: `authenticated` when the token carries `role: authenticated`, `anonymous` when it has no role claim, or any other role the claim names. Use this page to configure GRANT statements, enable RLS, and write per-row policies with `auth.user_id()`, which extracts the `sub` claim from the request JWT.

# Access control & security

Understand how the Data API authenticates requests and enforces database permissions.

Last updated: 2026-09-14

**Related docs**

- [Getting started with Data API](https://neon.com/docs/data-api/get-started)
- [Custom authentication providers](https://neon.com/docs/data-api/custom-authentication-providers)
- [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial)

The Neon Data API is designed to be secure by default. It relies on PostgreSQL's native security model, meaning the API does not have its own separate permission system; it acts as a gateway that respects the roles and Row-Level Security (RLS) policies defined in your database.

Securing your data involves two layers:

1. **Role Privileges (GRANT):** Determining which tables the API is allowed to access.
2. **Row-Level Security (RLS):** Determining which specific rows a user is allowed to see.

## API Roles

When the Data API receives an HTTP request, it switches to a specific PostgreSQL role before executing the query. That role is read from the `role` claim in the request's JWT: the API runs `SET ROLE` to the role the claim names. If the token has no `role` claim, the request falls back to the `anonymous` role. A valid signature on its own does not grant the `authenticated` role; the token must actually carry `"role": "authenticated"`.

### 1. The `authenticated` role

**Used for:** Tokens that carry `"role": "authenticated"`.

When a token's `role` claim is `authenticated`, the API switches to the `authenticated` role. This is the primary role for your application users, and it's the role the default `GRANT`s target. [Neon Auth](https://neon.com/docs/auth/overview) issues this claim automatically; a custom provider must be configured to include it (see [Required JWT claims](https://neon.com/docs/data-api/custom-authentication-providers#required-jwt-claims)).

- The JWT token identifies _who_ the user is (via the `sub` claim).
- The `authenticated` role defines _what_ the application is allowed to touch.

### 2. The `anonymous` role

**Used for:** Requests whose token carries no `role` claim, including unauthenticated or guest access.

Anonymous access still uses a JWT, but no user sign-in is required. How you obtain that token depends on your auth setup:

**With Managed Better Auth:** Set `allowAnonymous: true` in the client config. The SDK fetches a short-lived anonymous token (`GET /token/anonymous`) on the first request, caches it, and sends it as `Authorization: Bearer <jwt>` on every query.

```js
import { createClient } from '@neon/neon-js';

const client = createClient(import.meta.env.VITE_NEON_DATABASE_URL, {
  auth: {
    allowAnonymous: true,
  },
});

// No sign-in needed. The SDK fetches and caches an anonymous JWT automatically.
const { data, error } = await client.from('public_items').select('*');
```

**With a third-party provider:** Check whether your provider supports issuing anonymous or guest tokens. If it does, obtain the token using your provider's method and include it in the `Authorization: Bearer <token>` header on each request.

- By default, this role has **no permissions**.
- You can explicitly `GRANT` SELECT permissions to this role to expose public data (for example, a product list or public blog posts) without requiring users to log in.
- Typically, you'd only `GRANT SELECT` to this role, not write permissions. The syntax follows the same pattern as for the `authenticated` role. See [Configure schema access](https://neon.com/docs/data-api/get-started#3-configure-schema-access) for an example.

### 3. Custom roles

`authenticated` and `anonymous` are the two roles Neon sets up for you, but the `role` claim can name any Postgres role. This is the general rule behind both roles above: the API always runs `SET ROLE` to whatever the claim says. If you issue tokens with a different role (for example, `"role": "admin"`), the API switches to a role named `admin`. For this to work, the role must exist in your database, be granted to the `authenticator` role (the role the Data API connects as), and hold the privileges the request needs:

```sql
CREATE ROLE admin NOLOGIN;
GRANT admin TO authenticator;
GRANT USAGE ON SCHEMA public TO admin;
GRANT SELECT ON your_table_name TO admin;
```

If any of these is missing, the request fails:

- The role doesn't exist: `22023 role "admin" does not exist`
- The role isn't granted to `authenticator`: `42501 permission denied to set role "admin"`
- The role lacks the table grant: `42501 permission denied for table ...`

The sections below explain how to configure these roles.

## Layer 1: Table Privileges

Before RLS can even apply, the database role must have permission to perform the action (SELECT, INSERT, etc.) on the table.

### Automatic configuration

When you enable the Data API via the Console, Neon automatically applies default `GRANT` statements to the `authenticated` role for the `public` schema. See the manual configuration section below for the statements that are applied.

### Manual configuration

If you skipped the default Data API setup in the Neon Console or you are adding custom roles or working with schemas other than `public`, you may need to grant permissions explicitly.

The following example SQL commands grant the `authenticated` role access to all existing and future tables in the `public` schema. If your tables are in a different schema (for example, `sales`, `analytics` etc), update the schema name accordingly. You can also substitute `authenticated` with a custom role (for example, `admin`), but you must ensure that the role exists in your database.

Run these commands in the [SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) to ensure your API users can access your tables:

```sql
-- 1. Grant usage on the schema
GRANT USAGE ON SCHEMA public TO authenticated;

-- 2. Grant access to existing tables
GRANT SELECT, UPDATE, INSERT, DELETE ON ALL TABLES
  IN SCHEMA public TO authenticated;

-- 3. Ensure future tables are automatically accessible
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT, UPDATE, INSERT, DELETE ON TABLES TO authenticated;

-- 4. Grant access to sequences (required for auto-incrementing IDs)
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO authenticated;
```

**Info: Permission denied errors?**

If you encounter a "permission denied" error immediately after creating a new table, it is likely because the `authenticated` role hasn't been granted privileges on it. Running the `GRANT` commands above usually resolves this.

## Layer 2: Row-Level Security (RLS)

Granting `SELECT` access to the `authenticated` role allows the API to read **all rows** in the table. To restrict access to specific data (for example, "users can only see their own posts"), you must enable Row-Level Security and create policies.

### Understanding RLS states

RLS has three distinct states that affect data visibility:

| State                        | Behavior                                                         |
| ---------------------------- | ---------------------------------------------------------------- |
| **RLS disabled**             | All authenticated users see all rows (no filtering)              |
| **RLS enabled, no policies** | All access is blocked (users see nothing)                        |
| **RLS enabled + policies**   | Rows filtered by policy rules (typically using `auth.user_id()`) |

**Warning: RLS disabled means no filtering**

If RLS is disabled on a table, any authenticated user can see all rows in that table. This is different from "filtering without policies"; it means there is no filtering at all.

### Checking RLS status in the Console

The **Data API** page in the Neon Console shows the RLS status of your tables. If a table has RLS disabled, you'll see a warning message like:

> "table_name has RLS disabled. All authenticated users can view all rows in this table(s)."

You can click the **Enable RLS** button to enable Row-Level Security on the table without writing SQL. After enabling RLS, you'll need to create policies to allow access.

### The `user_id` column pattern

To filter rows by user, your tables need a column that stores the user's ID. The Data API provides `auth.user_id()`, a SQL function that extracts the User ID (`sub` claim) from the current request's JWT. Use this function to:

1. **Set a default value** so new rows are automatically associated with the current user
2. **Filter rows in policies** so users only see their own data

```sql
-- Example table with user_id column
CREATE TABLE posts (
  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  user_id text DEFAULT (auth.user_id()) NOT NULL,  -- Automatically set to current user
  content text NOT NULL
);
```

### Example workflow

1. **Enable RLS on the table:**

   ```sql
   ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
   ```

   _Once enabled, all access is blocked by default until a policy is created._

2. **Create a policy:**
   ```sql
   CREATE POLICY "User owns data" ON posts
     FOR ALL
     TO authenticated
     USING ( select auth.user_id() = user_id )
     WITH CHECK ( select auth.user_id() = user_id );
   ```

Now, even though the `authenticated` role has `SELECT` permission on the table, the database will only return rows where the `user_id` column matches the ID in the user's token.

--- [Document source](https://neon.com/docs/data-api/custom-authentication-providers.md) ---

> Summary: The Neon Data API works with any JWT-issuing identity system. Supply a JWKS URL to let the Data API validate tokens and enforce Row-Level Security, without requiring Managed Better Auth. Provider-specific JWKS URL formats and JWT Audience (aud claim) requirements are given for Auth0, Clerk, AWS Cognito, Azure AD, Firebase, and Keycloak. Use this page when your application already uses an existing auth provider and you need provider-specific configuration details rather than the default Managed Better Auth setup.

# Custom authentication providers

Configure custom authentication providers with the Data API

Last updated: 2026-09-30

**Related docs**

- [Getting started with Data API](https://neon.com/docs/data-api/get-started)
- [Access control & security](https://neon.com/docs/data-api/access-control)
- [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial)

**Source code**

- [pg_session_jwt extension](https://github.com/neondatabase/pg_session_jwt)

The Data API works with any authentication provider that issues [JSON Web Tokens (JWTs)](https://jwt.io/introduction). While [Managed Better Auth](https://neon.com/docs/auth/overview) provides the simplest setup, you can use existing authentication infrastructure with providers like Auth0, Clerk, AWS Cognito, and others.

**Important: Secure your data before exposing it**

The Data API has no permission layer of its own. Every request is authorized entirely by your PostgreSQL `GRANT` statements and [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security) policies, so a missing or misconfigured policy can expose a table to anyone with the endpoint URL. Before exposing data, follow [Access control & security](https://neon.com/docs/data-api/access-control) and [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial), and run the [Data API advisors](https://neon.com/docs/data-api/database-advisor) to catch misconfigurations.

## How it works

When you bring your own authentication provider, the JWT validation flow works as follows:

```
┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
│   Client    │         │   Your Auth      │         │  Neon Data  │
│ Application │         │    Provider      │         │     API     │
└──────┬──────┘         └────────┬─────────┘         └──────┬──────┘
       │                         │                          │
       │ 1. Authenticate         │                          │
       │────────────────────────>│                          │
       │                         │                          │
       │ 2. Return JWT token     │                          │
       │<────────────────────────│                          │
       │                         │                          │
       │ 3. API request with     │                          │
       │    Authorization header │                          │
       │────────────────────────────────────────────────────>│
       │                         │                          │
       │                         │ 4. Fetch JWKS keys       │
       │                         │<─────────────────────────│
       │                         │                          │
       │                         │ 5. Return public keys    │
       │                         │──────────────────────────>│
       │                         │                          │
       │                         │    6. Validate JWT       │
       │                         │    7. Extract user_id    │
       │                         │    8. Apply RLS policies │
       │                         │                          │
       │ 9. Return filtered data │                          │
       │<────────────────────────────────────────────────────│
       │                         │                          │
```

The key steps:

1. Your auth provider issues [JSON Web Tokens (JWTs)](https://jwt.io/introduction) to authenticated users.
2. Your application passes these JWTs to the Data API in the `Authorization` header.
3. Neon validates the tokens using your provider's [JWKS (JSON Web Key Set)](https://auth0.com/docs/secure/tokens/json-web-tokens/json-web-key-sets) URL.
4. The Data API enforces [Row-Level Security policies](https://neon.com/docs/guides/row-level-security) based on the user identity in the JWT.

## Required JWT claims

Neon checks the token's signature against your JWKS URL, but a valid signature is only half the story. The database role the query runs as comes from the token's `role` claim, not from the fact that the token passed validation. This trips up custom providers most often, because they don't add a `role` claim unless you configure them to.

- **`role`**: The Data API reads this claim and switches to the Postgres role it names. To use the default `authenticated` role (the role the [default `GRANT`s](https://neon.com/docs/data-api/access-control#layer-1-table-privileges) target), your provider must issue `"role": "authenticated"`. The role must exist in your database and hold the privileges the request needs. [Neon Auth](https://neon.com/docs/auth/overview) adds this claim for you; a custom provider does not.
- **`sub`**: Identifies the user for Row-Level Security. See [JWT token missing sub claim](https://neon.com/docs/data-api/troubleshooting#jwt-token-missing-sub-claim).

If a token has no `role` claim, the request runs as the fallback `anonymous` role instead. `anonymous` can enter the schema but has no table grants by default, so the query returns `42501 permission denied for table ...` even when `authenticated` has access. For how these roles are chosen and granted, see [Access control & security](https://neon.com/docs/data-api/access-control#api-roles).

## Add your authentication provider

You can configure your authentication provider when you first enable the Data API, or add it later from the **Settings** tab. Select **Other Provider** from the dropdown and enter:

- Your provider's **JWKS URL** (see provider-specific instructions below).
- Your **JWT Audience** value, if required by your provider (see [What is JWT Audience?](https://neon.com/docs/data-api/custom-authentication-providers#what-is-jwt-audience) below).

### What is JWT Audience?

The **JWT Audience** (the `aud` claim in a JWT) identifies the intended recipient of a token. It's a security measure that ensures tokens issued for one application can't be reused with another.

When you configure a JWT Audience value in the Data API:

- The Data API verifies that incoming JWTs contain a matching `aud` claim
- Tokens without a matching audience are rejected
- This prevents tokens meant for other services from being accepted by your API

**When is it required?**

- **Firebase/GCP**: Required; use your Firebase Project ID
- **Google Identity**: Required; use your OAuth 2.0 Client ID
- **Azure AD, Keycloak**: May be required depending on your configuration
- **Most other providers**: Optional; only configure if your provider includes an `aud` claim in tokens

If you're unsure whether your provider requires it, you can decode a sample JWT from your provider at [jwt.io](https://jwt.io) and check if it includes an `aud` claim.

## Find your JWKS URL

| Provider                                                                                          | JWKS URL Format                                                                             |
| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [Auth0](https://neon.com/docs/data-api/custom-authentication-providers#auth0)                     | `https://{YOUR_AUTH0_DOMAIN}/.well-known/jwks.json`                                         |
| [Clerk](https://neon.com/docs/data-api/custom-authentication-providers#clerk)                     | `https://{YOUR_CLERK_DOMAIN}/.well-known/jwks.json`                                         |
| [AWS Cognito](https://neon.com/docs/data-api/custom-authentication-providers#aws-cognito)         | `https://cognito-idp.{REGION}.amazonaws.com/{USER_POOL_ID}/.well-known/jwks.json`           |
| [Azure AD](https://neon.com/docs/data-api/custom-authentication-providers#azure-ad)               | `https://login.microsoftonline.com/{TENANT_ID}/discovery/v2.0/keys`                         |
| [Descope](https://neon.com/docs/data-api/custom-authentication-providers#descope)                 | `https://api.descope.com/{PROJECT_ID}/.well-known/jwks.json`                                |
| [Firebase/GCP](https://neon.com/docs/data-api/custom-authentication-providers#firebasegcp)        | `https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com` |
| [Google Identity](https://neon.com/docs/data-api/custom-authentication-providers#google-identity) | `https://www.googleapis.com/oauth2/v3/certs`                                                |
| [Keycloak](https://neon.com/docs/data-api/custom-authentication-providers#keycloak)               | `https://{DOMAIN}/auth/realms/{REALM}/protocol/openid-connect/certs`                        |
| [PropelAuth](https://neon.com/docs/data-api/custom-authentication-providers#propelauth)           | `https://{YOUR_PROPEL_AUTH_URL}/.well-known/jwks.json`                                      |
| [Stack Auth](https://neon.com/docs/data-api/custom-authentication-providers#stack-auth)           | `https://api.stack-auth.com/api/v1/projects/{PROJECT_ID}/.well-known/jwks.json`             |
| [Stytch](https://neon.com/docs/data-api/custom-authentication-providers#stytch)                   | `https://test.stytch.com/v1/sessions/jwks/{PROJECT_ID}`                                     |
| [SuperTokens](https://neon.com/docs/data-api/custom-authentication-providers#supertokens)         | `{CORE_CONNECTION_URI}/.well-known/jwks.json`                                               |
| [WorkOS](https://neon.com/docs/data-api/custom-authentication-providers#workos)                   | `https://api.workos.com/sso/jwks/{CLIENT_ID}`                                               |

### Auth0

Your Auth0 JWKS URL follows this format:

```bash
https://{YOUR_AUTH0_DOMAIN}/.well-known/jwks.json
```

To find your domain:

1. Open the **Settings** for your application in the Auth0 dashboard
2. Copy your **Domain** value
3. Use it to form your JWKS URL

![Find your Auth0 domain for JWKS URL](https://neon.com/docs/guides/auth0_neon_jwt.png)

For example, if your domain is `dev-abc123.us.auth0.com`, your JWKS URL would be:

```bash
https://dev-abc123.us.auth0.com/.well-known/jwks.json
```

### Clerk

Your Clerk JWKS URL follows this format:

```bash
https://{YOUR_CLERK_DOMAIN}/.well-known/jwks.json
```

To find your JWKS URL:

1. Go to the Clerk Dashboard
2. Navigate to **Configure → Developers → API Keys**
3. Click **Show JWT Public Key**
4. Copy the JWKS URL

For advanced JWT configuration (custom claims, token lifespans), you can use the dedicated Neon template in Clerk under **Configure > JWT Templates**.

### AWS Cognito

Your AWS Cognito JWKS URL follows this format:

```bash
https://cognito-idp.{YOUR_AWS_COGNITO_REGION}.amazonaws.com/{YOUR_AWS_COGNITO_USER_POOL_ID}/.well-known/jwks.json
```

To find your JWKS URL:

1. Open the AWS Cognito console
2. Navigate to **User pools**
3. Select your user pool
4. Find the **Token signing key URL** (this is your JWKS URL)

![Find your AWS Cognito JWKS URL](https://neon.com/docs/guides/aws_cognito_user_pool.png)

For example, if your region is `us-east-1` and your user pool ID is `us-east-1_XXXXXXXXX`, your JWKS URL would be:

```bash
https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXXXXXX/.well-known/jwks.json
```

### Azure AD

Your Azure Active Directory JWKS URL follows this format:

```bash
https://login.microsoftonline.com/{YOUR_TENANT_ID}/discovery/v2.0/keys
```

Replace `{YOUR_TENANT_ID}` with your Azure Active Directory tenant ID.

For example, if your tenant ID is `12345678-1234-1234-1234-1234567890ab`, your JWKS URL would be:

```bash
https://login.microsoftonline.com/12345678-1234-1234-1234-1234567890ab/discovery/v2.0/keys
```

**Note:** Depending on your Azure AD configuration, you may need to provide a JWT Audience value.

### Descope

Your Descope JWKS URL follows this format:

```bash
https://api.descope.com/{YOUR_DESCOPE_PROJECT_ID}/.well-known/jwks.json
```

To find your Project ID:

1. Go to the Descope Dashboard
2. Navigate to **Project Settings**
3. Copy your **Project ID**

![Find your Descope Project ID](https://neon.com/docs/guides/descope_project_id.png)

For example, if your Project ID is `P1234`, your JWKS URL would be:

```bash
https://api.descope.com/P1234/.well-known/jwks.json
```

### Firebase/GCP

Firebase and Google Cloud Identity Platform share the same authentication infrastructure and use a common JWKS URL for all projects:

```bash
https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com
```

You must also provide your Firebase/GCP Project ID as the JWT Audience value.

To find your Project ID:

1. Go to the [Firebase Console](https://console.firebase.google.com)
2. Navigate to **Settings** > **General**
3. Copy your **Project ID**

![Firebase Project ID](https://neon.com/docs/guides/firebase_project_id.png)

Enter your Project ID in the **JWT Audience** field when configuring the Data API.

**Note:** Every GCP Identity Platform project automatically creates a corresponding Firebase project, which is why we use the Firebase Console to get the Project ID.

### Google Identity

Your Google Identity JWKS URL is:

```bash
https://www.googleapis.com/oauth2/v3/certs
```

You must also provide your OAuth 2.0 Client ID as the JWT Audience value. You can find your Client ID in the [Google Cloud Console](https://console.cloud.google.com/apis/credentials) under **APIs & Services > Credentials**.

### Keycloak

Your Keycloak JWKS URL follows this format:

```bash
https://{YOUR_KEYCLOAK_DOMAIN}/auth/realms/{YOUR_REALM}/protocol/openid-connect/certs
```

Replace:

- `{YOUR_KEYCLOAK_DOMAIN}` with your Keycloak domain
- `{YOUR_REALM}` with your Keycloak realm name

**Note:** To ensure compatibility with the Data API, configure Keycloak to use only one signing algorithm (RS256 or ES256). You can verify this by opening the JWKS URL and checking the keys manually. Depending on your Keycloak configuration, you may also need to provide a JWT Audience value.

### PropelAuth

Your PropelAuth JWKS URL follows this format:

```bash
https://{YOUR_PROPEL_AUTH_URL}/.well-known/jwks.json
```

To find your PropelAuth URL:

1. Go to your PropelAuth dashboard
2. Navigate to **Backend Integration** in your project settings
3. Copy your Auth URL

![PropelAuth Auth URL](https://neon.com/docs/guides/propelauth_backend_integration_page.png)

For example, if your PropelAuth URL is `https://3211758.propelauthtest.com`, your JWKS URL would be:

```bash
https://3211758.propelauthtest.com/.well-known/jwks.json
```

### Stack Auth

Your Stack Auth JWKS URL follows this format:

```bash
https://api.stack-auth.com/api/v1/projects/{YOUR_PROJECT_ID}/.well-known/jwks.json
```

Replace `{YOUR_PROJECT_ID}` with your Stack Auth project ID.

For example, if your project ID is `my-awesome-project`, your JWKS URL would be:

```bash
https://api.stack-auth.com/api/v1/projects/my-awesome-project/.well-known/jwks.json
```

### Stytch

Your Stytch JWKS URL follows this format:

```bash
https://test.stytch.com/v1/sessions/jwks/{YOUR_PROJECT_ID}
```

Replace `{YOUR_PROJECT_ID}` with your Stytch project ID.

For example, if your project ID is `my-awesome-project`, your JWKS URL would be:

```bash
https://test.stytch.com/v1/sessions/jwks/my-awesome-project
```

**Note:** For production environments, replace `test.stytch.com` with `live.stytch.com`.

### SuperTokens

Your SuperTokens JWKS URL follows this format:

```bash
{YOUR_SUPER_TOKENS_CORE_CONNECTION_URI}/.well-known/jwks.json
```

To find your Core connection URI:

1. Go to the SuperTokens Dashboard
2. Navigate to **Core Management**
3. Copy your Core connection URI

![SuperTokens Dashboard](https://neon.com/docs/guides/supertokens_dashboard.png)

For example, if your connection URI is `https://try.supertokens.io`, your JWKS URL would be:

```bash
https://try.supertokens.io/.well-known/jwks.json
```

### WorkOS

Your WorkOS JWKS URL follows this format:

```bash
https://api.workos.com/sso/jwks/{YOUR_CLIENT_ID}
```

To find your Client ID:

1. Go to the WorkOS Dashboard
2. Navigate to the **Overview** page
3. Copy your **Client ID**

![WorkOS Overview Page](https://neon.com/docs/guides/workos_overview_page.png)

For example, if your Client ID is `client_12345`, your JWKS URL would be:

```bash
https://api.workos.com/sso/jwks/client_12345
```

## Next steps

After configuring your authentication provider, include the JWT in your Data API requests:

```http
GET https://ep-example.apirest.us-east-1.aws.neon.tech/neondb/rest/v1/posts
Authorization: Bearer {your_jwt_token}
```

Then set up [Row-Level Security policies](https://neon.com/docs/data-api/get-started#create-a-table-with-rls) to control data access using the `auth.user_id()` function, which extracts the user ID from your JWT.

--- [Document source](https://neon.com/docs/data-api/database-advisor.md) ---

> Summary: Data API Advisors scan your Neon database schema and configuration for security and performance issues specific to objects exposed by the Data API over HTTP. Security checks catch exploitable misconfigurations such as missing RLS, security definer views, and Managed Better Auth exposure. Performance checks flag unindexed foreign keys, duplicate indexes, and table bloat before they reach production. Checks are categorized as SECURITY or PERFORMANCE with severity levels INFO, WARN, or ERROR, and are accessible via the Neon Console or the REST API.

# Data API Advisors

Identify security and performance issues in your API-exposed database

Last updated: 2026-09-30

The Data API Advisors analyze your database schema and configuration to detect security and performance issues for tables and objects exposed by the [Data API](https://neon.com/docs/data-api/overview) feature. They run a set of checks against your database and report issues with severity levels and recommended fixes.

Because the Data API exposes your database schema directly over HTTP, security misconfigurations that would normally be hidden behind an application server become directly exploitable. Missing RLS policies and overly permissive views are especially dangerous in this context. The advisors also check for common performance issues like unindexed foreign keys and table bloat, helping you catch issues before they reach production.

**Important: Secure your data before exposing it**

The Data API has no permission layer of its own. Every request is authorized entirely by your PostgreSQL `GRANT` statements and [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security) policies, so a missing or misconfigured policy can expose a table to anyone with the endpoint URL. Before exposing data, follow [Access control & security](https://neon.com/docs/data-api/access-control) and [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial).

## Prerequisites

- Your compute must be active (not suspended) when running a scan.
- If the Data API is not yet enabled, the Advisors screen will show a "Data API not enabled" message. Enable the [Data API](https://neon.com/docs/data-api/get-started) to run scans.

## How to access

### Neon Console

In the Neon Console, go to **Monitoring > Data API Advisors** for your branch. The advisor scans your database and displays any issues found, grouped by category.

![Data API advisor](https://neon.com/docs/data-api/data-api-database-advisor-monitor.png)

Each issue includes a severity level, a description, and a recommended fix. Clicking an issue opens a detail view with an **Ask Assistant** option that analyzes the risk and suggests a specific fix (such as a SQL query tailored to your schema), along with a **Read our docs** link for general guidance on that type of issue.

![Data API advisor solution](https://neon.com/docs/data-api/data-api-database-advisor-resolve.png)

### API

You can also retrieve advisor issues via the [Neon API](https://neon.com/docs/reference/api/dataapi/get-project-advisor-security-issues):

```
GET /projects/{project_id}/advisors
```

This endpoint requires Data API to be enabled for the target project and branch.

Optional query parameters:

- `branch_id`: Target branch (defaults to the primary branch)
- `database_name`: Target database (required if the branch has multiple databases)
- `category`: Filter by `SECURITY` or `PERFORMANCE`
- `min_severity`: Minimum severity to include: `INFO`, `WARN`, or `ERROR`. For example, `WARN` returns WARN and ERROR issues but not INFO.

<details>

<summary>Example response</summary>

```json
{
  "issues": [
    {
      "name": "rls_disabled_in_public",
      "title": "RLS Disabled in Public",
      "level": "ERROR",
      "facing": "EXTERNAL",
      "categories": ["SECURITY"],
      "description": "Detects cases where row level security (RLS) has not been enabled on tables in schemas exposed to Data-API",
      "detail": "Table `public.users` is public, but RLS has not been enabled.",
      "remediation": "https://neon.com/docs/data-api/database-advisor#rls-disabled-in-public",
      "metadata": {}
    }
  ]
}
```

</details>

## Security checks

| Check                                                                                                                            | Severity | Description                                                                             |
| -------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- |
| [RLS disabled in public](https://neon.com/docs/data-api/database-advisor#rls-disabled-in-public)                                 | ERROR    | Tables exposed via the Data API without row-level security                              |
| [Policy exists RLS disabled](https://neon.com/docs/data-api/database-advisor#policy-exists-rls-disabled)                         | ERROR    | RLS policies exist but RLS is not enabled on the table                                  |
| [Sensitive columns exposed](https://neon.com/docs/data-api/database-advisor#sensitive-columns-exposed)                           | ERROR    | API-exposed tables without RLS that contain potentially sensitive columns               |
| [Security definer view](https://neon.com/docs/data-api/database-advisor#security-definer-view)                                   | ERROR    | Views using SECURITY DEFINER, bypassing the querying user's permissions                 |
| [Managed Better Auth users exposed](https://neon.com/docs/data-api/database-advisor#neon-auth-users-exposed)                     | ERROR    | Views exposing `neon_auth.user` data to API roles                                       |
| [RLS references Managed Better Auth metadata](https://neon.com/docs/data-api/database-advisor#rls-references-neon-auth-metadata) | ERROR    | RLS policies referencing user-editable Managed Better Auth fields                       |
| [FK to Managed Better Auth unique constraint](https://neon.com/docs/data-api/database-advisor#fk-to-neon-auth-unique-constraint) | ERROR    | Foreign keys referencing Managed Better Auth unique constraints instead of primary keys |
| [RLS policy always true](https://neon.com/docs/data-api/database-advisor#rls-policy-always-true)                                 | WARN     | RLS policies with always-true expressions that bypass access control                    |
| [Function search path mutable](https://neon.com/docs/data-api/database-advisor#function-search-path-mutable)                     | WARN     | Functions without an explicit `search_path` setting                                     |
| [Extension in public](https://neon.com/docs/data-api/database-advisor#extension-in-public)                                       | WARN     | Extensions installed in the `public` schema, exposing their objects via the Data API    |
| [Extension versions outdated](https://neon.com/docs/data-api/database-advisor#extension-versions-outdated)                       | WARN     | Extensions not using the recommended default version                                    |
| [Materialized view in API](https://neon.com/docs/data-api/database-advisor#materialized-view-in-api)                             | WARN     | Materialized views accessible to API roles, bypassing RLS                               |
| [Foreign table in API](https://neon.com/docs/data-api/database-advisor#foreign-table-in-api)                                     | WARN     | Foreign tables accessible over the Data API, which cannot use RLS                       |
| [Unsupported reg types](https://neon.com/docs/data-api/database-advisor#unsupported-reg-types)                                   | WARN     | Columns using `reg*` types that prevent `pg_upgrade`                                    |
| [RLS enabled no policy](https://neon.com/docs/data-api/database-advisor#rls-enabled-no-policy)                                   | INFO     | RLS is enabled but no policies have been created                                        |

## Performance checks

| Check                                                                                                        | Severity | Description                                                                     |
| ------------------------------------------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------- |
| [Auth RLS InitPlan](https://neon.com/docs/data-api/database-advisor#auth-rls-initplan)                       | WARN     | RLS policy functions re-evaluated per row instead of once per query             |
| [Multiple permissive policies](https://neon.com/docs/data-api/database-advisor#multiple-permissive-policies) | WARN     | Multiple permissive RLS policies on the same table for the same role and action |
| [Duplicate index](https://neon.com/docs/data-api/database-advisor#duplicate-index)                           | WARN     | Two or more identical indexes on the same table                                 |
| [Unindexed foreign keys](https://neon.com/docs/data-api/database-advisor#unindexed-foreign-keys)             | INFO     | Foreign key columns without a covering index                                    |
| [Unused index](https://neon.com/docs/data-api/database-advisor#unused-index)                                 | INFO     | Indexes that have never been used                                               |
| [No primary key](https://neon.com/docs/data-api/database-advisor#no-primary-key)                             | INFO     | Tables without a primary key                                                    |
| [Table bloat](https://neon.com/docs/data-api/database-advisor#table-bloat)                                   | INFO     | Tables with excessive bloat that may benefit from maintenance                   |

---

## Security check details

### RLS disabled in public

**Severity:** ERROR

Tables in schemas exposed through the Data API are accessible to anyone with your project's API URL if RLS is not enabled. Without RLS, all rows are fully readable and writable via the API.

See [Data API access control](https://neon.com/docs/data-api/access-control) and [RLS tutorial](https://neon.com/docs/guides/rls-tutorial).

<details>

<summary>Show resolution</summary>

Enable RLS on the affected table:

```sql
ALTER TABLE <schema>.<table> ENABLE ROW LEVEL SECURITY;
```

After enabling RLS, no data is accessible via the Data API until you create policies to define access rules.

If the table should not be accessible via the API at all, remove its schema from the exposed schemas in your [Data API settings](https://neon.com/docs/data-api/manage).

</details>

---

### Policy exists RLS disabled

**Severity:** ERROR

RLS policies have been created on a table, but RLS itself is not enabled. The policies have no effect until RLS is turned on, which may give a false sense of security.

<details>

<summary>Show resolution</summary>

Enable RLS on the table:

```sql
ALTER TABLE <schema>.<table> ENABLE ROW LEVEL SECURITY;
```

</details>

---

### Sensitive columns exposed

**Severity:** ERROR

Tables exposed via the Data API that contain columns with potentially sensitive data (credentials, personal identifiers, financial info) are at risk if RLS is not enabled. Without RLS, any API user can read all rows.

<details>

<summary>Show resolution</summary>

This check matches exact column names (case-insensitive, hyphens treated as underscores) against known sensitive patterns, including:

- **Credentials:** `password`, `secret`, `api_key`, `token`, `jwt`, `access_token`, `refresh_token`, `otp`, `2fa_secret`, and others
- **Personal identifiers:** `ssn`, `passport_number`, `tax_id`, `driver_license`, `national_id`
- **Financial data:** `credit_card`, `cvv`, `bank_account`, `iban`, `routing_number`
- **Other:** `health_record`, `ssh_key`, `pgp_key`, `mac_address`, `facial_recognition`

A column named `user_password_hash` would not be flagged because matching is on the full column name, not substrings.

Enable RLS on the table and create appropriate policies:

```sql
ALTER TABLE <schema>.<table> ENABLE ROW LEVEL SECURITY;

CREATE POLICY restrict_access ON <schema>.<table>
  FOR SELECT
  USING ((SELECT auth.uid()) = user_id);
```

Alternatively, move sensitive columns to a separate table with its own RLS policies, or remove the schema from the Data API's exposed schemas if API access is not needed.

</details>

---

### Security definer view

**Severity:** ERROR

Views default to SECURITY DEFINER in PostgreSQL, meaning they execute with the permissions of the view creator rather than the querying user. This bypasses RLS policies on the underlying tables and can expose more data than intended through the Data API.

See [PostgreSQL views](https://neon.com/postgresql/postgresql-views/managing-postgresql-views) for background.

<details>

<summary>Show resolution</summary>

Set the view to use SECURITY INVOKER mode so it respects the querying user's permissions and RLS policies:

```sql
CREATE OR REPLACE VIEW <schema>.<view_name>
  WITH (security_invoker=on)
AS
SELECT ...
FROM ...;
```

Note: The `security_invoker` option requires PostgreSQL 15 or later. This check only runs on PostgreSQL 15+.

</details>

---

### Managed Better Auth users exposed

**Severity:** ERROR

Views or materialized views that reference `neon_auth.user` can expose sensitive user data to API roles. Views in PostgreSQL default to SECURITY DEFINER mode, which means they bypass [row-level security](https://neon.com/postgresql/postgresql-administration/postgresql-row-level-security) policies on the underlying tables.

See [Managed Better Auth overview](https://neon.com/docs/auth/overview) and [Data API access control](https://neon.com/docs/data-api/access-control) for background.

<details>

<summary>Show resolution</summary>

**Option 1: Use a profiles table with a trigger**

Create a `public.profiles` table with only the user fields your application needs, and populate it via a trigger on `neon_auth.user`:

```sql
CREATE TABLE public.profiles (
  id uuid NOT NULL REFERENCES neon_auth.user ON DELETE CASCADE,
  display_name text,
  PRIMARY KEY (id)
);

CREATE FUNCTION public.handle_new_user()
RETURNS trigger
LANGUAGE plpgsql
SECURITY DEFINER SET search_path = ''
AS $$
BEGIN
  INSERT INTO public.profiles (id)
  VALUES (new.id);
  RETURN new;
END;
$$;

CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON neon_auth.user
  FOR EACH ROW EXECUTE PROCEDURE public.handle_new_user();
```

Then enable RLS on `public.profiles` and create policies to control access.

**Option 2: Use a security invoker view**

Create a view with `security_invoker=on` so it respects the querying user's permissions:

```sql
CREATE VIEW public.members
  WITH (security_invoker=on)
AS
SELECT id, created_at
FROM neon_auth.user;
```

Note: For this approach to work, RLS must also be enabled on the `neon_auth.user` table with appropriate policies. Otherwise, the security invoker view still exposes all rows.

</details>

---

### RLS references Managed Better Auth metadata

**Severity:** ERROR

RLS policies that reference user-editable fields from Managed Better Auth (such as `user.role` or `organization.metadata`) are insecure. Users can modify these fields, allowing them to bypass security checks.

See [Managed Better Auth overview](https://neon.com/docs/auth/overview).

<details>

<summary>Show resolution</summary>

Remove references to user-editable Managed Better Auth fields from your RLS policies. The specific fields detected by this check are:

- `neon_auth.user.role` -- users can change their own role
- `neon_auth.organization.metadata` -- organization metadata can be modified

Instead, base security decisions on stable, non-editable fields like the user's `id`.

For example, replace:

```sql
-- Insecure: references neon_auth.user.role which users can modify
CREATE POLICY role_based_access ON public.documents
  FOR SELECT
  USING (
    (SELECT role FROM neon_auth.user WHERE id = (SELECT auth.uid())) = 'admin'
  );
```

With a policy based on a stable identifier:

```sql
CREATE POLICY owner_access ON public.documents
  FOR SELECT
  USING ((SELECT auth.uid()) = user_id);
```

</details>

---

### FK to Managed Better Auth unique constraint

**Severity:** ERROR

Foreign keys referencing unique constraints (rather than primary keys) in the `neon_auth` schema are not supported. These unique constraints may change in future updates, which would break your foreign key references and block migrations.

<details>

<summary>Show resolution</summary>

Drop the foreign key constraint referencing the unique constraint and recreate it referencing the primary key instead:

```sql
ALTER TABLE <schema>.<table> DROP CONSTRAINT <foreign_key_name>;

ALTER TABLE <schema>.<table>
  ADD CONSTRAINT <foreign_key_name>
  FOREIGN KEY (<column>) REFERENCES neon_auth.user(id);
```

</details>

---

### RLS policy always true

**Severity:** WARN

RLS policies that use always-true expressions like `USING (true)` or `WITH CHECK (true)` for write operations (INSERT, UPDATE, DELETE) effectively bypass row-level security. While the table appears to have RLS enabled, these policies grant unrestricted access.

Note: `USING (true)` on SELECT-only policies is excluded from this check, as it is a common pattern for intentional public read access.

<details>

<summary>Show resolution</summary>

Replace the always-true policy with one that enforces actual access control:

```sql
DROP POLICY <policy_name> ON <schema>.<table>;

CREATE POLICY <new_policy_name> ON <schema>.<table>
  FOR <action>
  USING ((SELECT auth.uid()) = user_id);
```

If you need broad read access combined with restricted writes, use a restrictive policy:

```sql
CREATE POLICY restrict_writes ON <schema>.<table>
  AS RESTRICTIVE
  FOR UPDATE
  USING ((SELECT auth.uid()) = user_id);
```

</details>

---

### Function search path mutable

**Severity:** WARN

Functions without an explicit `search_path` inherit the calling user's session `search_path`. This can lead to inconsistent behavior and potential security issues if a user manipulates their `search_path` to resolve unqualified names to unexpected objects.

See [PostgreSQL schemas and search_path](https://neon.com/postgresql/postgresql-administration/postgresql-schema) for background.

<details>

<summary>Show resolution</summary>

Set `search_path` to an empty string in the function definition, and fully qualify all object references:

```sql
CREATE OR REPLACE FUNCTION <schema>.<function_name>()
  RETURNS void
  LANGUAGE sql
  SET search_path = ''
AS $$
  -- Use fully qualified names, e.g. public.my_table
$$;
```

</details>

---

### Extension in public

**Severity:** WARN

Extensions installed in the `public` schema make their functions, tables, and views appear as part of your API surface. This is usually unintentional and can expose internal functionality.

See [Neon extensions](https://neon.com/docs/extensions/pg-extensions) for more on managing extensions.

<details>

<summary>Show resolution</summary>

Move the extension to a non-exposed schema:

```sql
ALTER EXTENSION <extension_name> SET SCHEMA <non_exposed_schema>;
```

For example, to move the `ltree` extension out of `public`:

```sql
ALTER EXTENSION ltree SET SCHEMA extensions;
```

</details>

---

### Extension versions outdated

**Severity:** WARN

Running an outdated extension version may expose your database to known security vulnerabilities and prevent you from benefiting from bug fixes and performance improvements.

See [managing extensions](https://neon.com/docs/extensions/pg-extensions) for background.

<details>

<summary>Show resolution</summary>

Check the current and available versions:

```sql
SELECT name, installed_version, default_version
FROM pg_catalog.pg_available_extensions
WHERE name = '<extension_name>';
```

Then update to the default version:

```sql
ALTER EXTENSION <extension_name> UPDATE;
```

**Note:** Some extension updates may include breaking changes. Test the update in a development branch before applying to production, and review the extension's changelog if available.

</details>

---

### Materialized view in API

**Severity:** WARN

Materialized views cannot be protected with RLS. If a materialized view is accessible to API roles (`anonymous` or `authenticated`), all rows are visible to any API user.

See [PostgreSQL materialized views](https://neon.com/postgresql/postgresql-views/postgresql-materialized-views).

<details>

<summary>Show resolution</summary>

Revoke `SELECT` access from API roles:

```sql
REVOKE SELECT ON <schema>.<materialized_view> FROM public, anonymous, authenticated;
```

You can verify the change with:

```sql
SELECT pg_catalog.has_table_privilege('anonymous', '<schema>.<materialized_view>'::regclass::oid, 'select');
-- Should return: false
```

</details>

---

### Foreign table in API

**Severity:** WARN

Foreign tables do not support RLS. If a foreign table is accessible over the Data API, all rows are visible to any API user.

<details>

<summary>Show resolution</summary>

Revoke `SELECT` access from API roles:

```sql
REVOKE SELECT ON <schema>.<foreign_table> FROM public, anonymous, authenticated;
```

If you need to access data from the foreign table over the API, move it to a non-exposed schema, grant API roles access in the new schema, and create a function that implements security rules:

```sql
CREATE SCHEMA private;
ALTER FOREIGN TABLE public.<foreign_table> SET SCHEMA private;

-- Ensure API roles can still read from the foreign table
GRANT SELECT ON private.<foreign_table> TO anonymous, authenticated;

-- Create a function with security rules, accessible via RPC
CREATE OR REPLACE FUNCTION public.secure_foreign_read()
  RETURNS TABLE (id integer, data text, author_id uuid)
  LANGUAGE sql
  SET search_path = ''
AS $$
  SELECT id, data, author_id
  FROM private.<foreign_table>
  WHERE author_id = (SELECT auth.uid());
$$;
```

</details>

---

### Unsupported reg types

**Severity:** WARN

Columns using certain `reg*` types that reference PostgreSQL internals are not supported by [pg_upgrade](https://www.postgresql.org/docs/current/pgupgrade.html), the standard tool for upgrading between PostgreSQL versions. Using these types can block future database upgrades. The flagged types are: `regcollation`, `regconfig`, `regdictionary`, `regnamespace`, `regoper`, `regoperator`, `regproc`, and `regprocedure`.

<details>

<summary>Show resolution</summary>

Replace the `reg*` type column with a `text` column storing the object's name:

```sql
-- Instead of:
CREATE TABLE public.bad_table (
  id int PRIMARY KEY,
  my_collation regcollation
);

-- Use:
CREATE TABLE public.good_table (
  id int PRIMARY KEY,
  my_collation_name text
);
```

</details>

---

### RLS enabled no policy

**Severity:** INFO

RLS is enabled on a table but no policies have been created. This means no data is accessible via the Data API for this table, which may or may not be intentional.

<details>

<summary>Show resolution</summary>

If the table should be accessible, create an appropriate RLS policy:

```sql
CREATE POLICY select_own_rows ON <schema>.<table>
  FOR SELECT
  USING ((SELECT auth.uid()) = user_id);
```

If blocking all access is intentional, make it explicit with a denial policy:

```sql
CREATE POLICY deny_all ON <schema>.<table>
  FOR SELECT
  USING (false);
```

See [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial) for a step-by-step guide.

</details>

---

## Performance check details

### Auth RLS InitPlan

**Severity:** WARN

When RLS policies call functions like `auth.uid()` or `current_setting()` directly, PostgreSQL may re-evaluate them for every row the query touches. At scale, this adds significant overhead. Wrapping the call in a subquery caches the result for the duration of the query.

See [RLS performance with subqueries](https://neon.com/docs/guides/rls-tutorial) for more context.

<details>

<summary>Show resolution</summary>

Wrap the function call in a `SELECT` subquery:

```sql
-- Before (re-evaluated per row):
CREATE POLICY access_policy ON documents
  USING (auth.uid() = user_id);

-- After (evaluated once per query):
CREATE POLICY access_policy ON documents
  USING ((SELECT auth.uid()) = user_id);
```

This applies to `auth.uid()`, `auth.role()`, `auth.jwt()`, `auth.email()`, and `current_setting()` calls in RLS policies.

</details>

---

### Multiple permissive policies

**Severity:** WARN

When multiple permissive RLS policies apply to the same table for the same role and action, PostgreSQL must evaluate all of them (they combine with `OR` logic). This increases query overhead and can also lead to unintentionally broad access.

See [row-level security](https://neon.com/postgresql/postgresql-administration/postgresql-row-level-security) for background on policy types.

<details>

<summary>Show resolution</summary>

Consolidate multiple permissive policies into a single policy that combines the conditions:

```sql
-- Instead of two separate policies:
DROP POLICY policy_a ON <table>;
DROP POLICY policy_b ON <table>;

-- Combine into one:
CREATE POLICY consolidated_policy ON <table>
  FOR SELECT
  USING (
    <condition_a> OR <condition_b>
  );
```

This reduces the number of policy evaluations per row and gives the query planner better optimization opportunities.

Consolidation is a best practice, not a hard rule. If combining conditions leads to unreadable SQL, multiple policies may be acceptable for maintainability.

</details>

---

### Duplicate index

**Severity:** WARN

Two or more identical indexes on the same table add write overhead with no performance benefit. Each duplicate must be updated on every insert, update, and delete operation.

<details>

<summary>Show resolution</summary>

Drop all but one instance of the duplicate index:

```sql
DROP INDEX <schema_name>.<duplicate_index_name>;
```

</details>

---

### Unindexed foreign keys

**Severity:** INFO

Foreign key columns without a covering index can lead to slow joins and increased resource usage, especially as tables grow. Adding an index on foreign key columns improves join performance.

See [PostgreSQL foreign keys](https://neon.com/postgresql/postgresql-tutorial/postgresql-foreign-key) and [index types](https://neon.com/docs/postgresql/index-types) for background.

<details>

<summary>Show resolution</summary>

Create an index on the foreign key column:

```sql
CREATE INDEX ON <table>(<foreign_key_column>);
```

For example, if `order_item.customer_id` references `customer.id`:

```sql
CREATE INDEX ix_order_item_customer_id ON order_item(customer_id);
```

Choose an index type appropriate for the column's data type and query patterns. The default B-tree index works well for most foreign key columns.

</details>

---

### Unused index

**Severity:** INFO

Indexes that have never been used by any query still add overhead on every write operation (insert, update, delete) and consume storage. Removing unused indexes can improve write performance. This check only flags non-unique, non-primary-key indexes.

**Important:** PostgreSQL tracks index usage in `pg_stat_user_indexes`, but these statistics are local to the compute and do not persist across compute restarts (including suspend/resume cycles and failovers). An index showing zero scans may simply not have been used since the last compute start, not since it was created. Allow enough time for representative traffic before treating an index as truly unused.

See [PostgreSQL indexes](https://neon.com/postgresql/postgresql-indexes/postgresql-create-index) for background.

<details>

<summary>Show resolution</summary>

Before removing an index, confirm it is not needed for upcoming features or seasonal workloads. Then drop it:

```sql
DROP INDEX <schema_name>.<index_name>;
```

Consider testing in a development branch first to verify no performance regression.

</details>

---

### No primary key

**Severity:** INFO

Tables without a primary key lack a guaranteed unique row identifier. This can degrade query performance and prevents establishing [foreign key](https://neon.com/postgresql/postgresql-tutorial/postgresql-foreign-key) relationships with other tables.

<details>

<summary>Show resolution</summary>

Add a primary key to the table:

```sql
ALTER TABLE <schema>.<table> ADD PRIMARY KEY (<column>);
```

If no single column is unique, use a composite key:

```sql
ALTER TABLE <schema>.<table> ADD PRIMARY KEY (<column1>, <column2>);
```

Use simple, fixed-size types like `int`, `bigint`, or `uuid` for primary keys when possible.

</details>

---

### Table bloat

**Severity:** INFO

Tables with excessive bloat contain unused space from deleted or updated rows. This increases storage usage, slows down sequential scans, and increases I/O overhead. PostgreSQL's autovacuum normally reclaims this space, but it may not keep up with high-churn tables.

See [pg_repack](https://neon.com/docs/extensions/pg_repack) and [pgstattuple](https://neon.com/docs/extensions/pgstattuple) for tools to analyze and resolve bloat.

<details>

<summary>Show resolution</summary>

Start with a standard `VACUUM` which runs without locking the table:

```sql
VACUUM <schema>.<table>;
```

If that is not sufficient, `VACUUM FULL` reclaims more space but **locks the table** for the duration. Duration scales with table size, so plan for potential downtime on large tables.

```sql
VACUUM FULL <schema>.<table>;
```

For large or heavily used tables where downtime is not acceptable, consider using [pg_repack](https://neon.com/docs/extensions/pg_repack) as a less disruptive alternative.

You can check table size before and after:

```sql
SELECT pg_size_pretty(pg_table_size('<schema>.<table>'));
```

If a table is repeatedly flagged for bloat, review your autovacuum settings to ensure vacuuming runs frequently enough. Contact [Neon support](https://neon.com/docs/introduction/support) for help tuning autovacuum for high-churn tables.

</details>

Database lints originally based on [open-source lints](https://github.com/supabase/supabase/blob/master/apps/studio/lib/api/self-hosted/lints.ts) from the Supabase project, Apache 2.0.

--- [Document source](https://neon.com/docs/data-api/demo.md) ---

> Summary: Neon Data API tutorial using a React/Vite note-taking app. The app runs PostgREST-compatible SELECT, INSERT, UPDATE, and DELETE queries from the frontend via the @neondatabase/neon-js client. Row-Level Security policies written with Drizzle ORM enforce per-user data isolation, with `auth.user_id()` extracting the caller's identity from JWTs. Use this page for a working end-to-end example of Data API query patterns, RLS setup, and ON DELETE CASCADE.

# Neon Data API tutorial

Explore our demo note-taking app to learn about Data API queries with RLS

Last updated: 2026-09-30

This tutorial uses a note-taking app to show how Neon's Data API works with the `@neondatabase/neon-js` client library to write queries from your frontend code, with authentication and Row-Level Security (RLS) policies keeping your data secure. The Data API is compatible with PostgREST, so you can use any PostgREST client library.

**Important: Secure your data before exposing it**

The Data API has no permission layer of its own. Every request is authorized entirely by your PostgreSQL `GRANT` statements and [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security) policies, so a missing or misconfigured policy can expose a table to anyone with the endpoint URL. Before exposing data, follow [Access control & security](https://neon.com/docs/data-api/access-control) and [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial), and run the [Data API advisors](https://neon.com/docs/data-api/database-advisor) to catch misconfigurations.

**Tip: Data API works with any auth provider**

This tutorial uses [Managed Better Auth](https://neon.com/docs/auth/overview) for convenience, but the Data API works with any authentication provider that issues JWTs. The query patterns, RLS policies, and `auth.user_id()` function shown here apply regardless of your auth provider. See [Custom authentication providers](https://neon.com/docs/data-api/custom-authentication-providers) for setup details with Auth0, Clerk, Firebase, and others.

## About the sample application

This note-taking app is built with React and Vite. It uses Managed Better Auth for authentication, the Data API for direct database access, and Drizzle ORM for handling the schema.

![Notes app UI](https://neon.com/docs/data-api/all_notes.png)

> **See it in action:** Check out the live demo at [neon-data-api-neon-auth.vercel.app](https://neon-data-api-neon-auth.vercel.app/)
>
> **Tip:** If you encounter issues with social login providers, try email/password instead.

## Set up the demo app

### Prerequisites

Before you begin, ensure you have:

- [Bun](https://bun.sh/) (v1.0 or newer) installed
- A [Neon account](https://console.neon.tech/signup) (free tier works)

### Create a Neon project with Auth and Data API

1. Go to the [Neon Console](https://console.neon.tech) to create a new Neon project
2. In the Neon Console, navigate to your project and go to **Postgres database** > **Data API**
3. Select **Managed Better Auth** as your authentication option (the default), then click **Enable**

This enables both the Data API and Managed Better Auth in one step. For detailed instructions, see [Getting started with Data API](https://neon.com/docs/data-api/get-started).

### Clone and install

```bash
git clone https://github.com/neondatabase-labs/neon-data-api-neon-auth.git
cd neon-data-api-neon-auth
bun install
```

### Configure environment variables

Create a `.env` file in the project root:

```env
# Neon database URL for the client (no username, password, or query parameters)
# Start from the Data API URL in Neon Console → Data API or `neon data-api get`;
# remove the `.apirest` hostname label and trailing `/rest/v1` path.
# The SDK derives the Managed Better Auth and Data API URLs from this value.
VITE_NEON_DATABASE_URL=https://ep-example.c-2.us-east-1.aws.neon.tech/neondb

# Database Connection String (for migrations)
# Find this in Neon Console → Dashboard → Connection string (select "Pooled connection")
# This is a Postgres connection string, not the HTTPS URL used by VITE_NEON_DATABASE_URL above
DATABASE_URL=postgresql://user:password@your-project-id.pooler.region.neon.tech/neondb?sslmode=require
```

Prefer the older two-URL setup? See the [object-form alternative](https://neon.com/docs/reference/javascript-sdk#initializing) in the JavaScript SDK reference.

### Set up the database

Run the migration to create the tables and RLS policies:

```bash
bun run db:migrate
```

This will:

- Grant appropriate permissions to the `authenticated` and `anonymous` database roles
- Create the `notes` and `paragraphs` tables with RLS policies

### Start the development server

```bash
bun dev
```

Open [http://localhost:5173](http://localhost:5173) in your browser.

## How the demo app works

Now that you have the app running, let's explore how it uses the Data API. The following sections explain the key patterns and techniques used in the demo app.

### Initialize the client

The demo app uses `@neondatabase/neon-js` to connect to both the Data API and Managed Better Auth. Here's how the client is configured in `src/lib/auth.ts`:

```typescript
import { createClient } from '@neondatabase/neon-js';
import { BetterAuthReactAdapter } from '@neondatabase/neon-js/auth/react/adapters';
import type { Database } from '../../types/database';

export const client = createClient<Database>(import.meta.env.VITE_NEON_DATABASE_URL, {
  auth: {
    adapter: BetterAuthReactAdapter(),
  },
});
```

This single client provides:

- **Authentication methods** via `client.auth` (sign up, sign in, sign out, get session)
- **Database query methods** via `client.from()` (select, insert, update, delete)

The client automatically handles JWT token management; when a user is signed in, the token is included in all Data API requests, enabling RLS policies to work correctly.

### Database schema

The app uses two main tables: `notes` and `paragraphs`. Here's how they're defined in `src/db/schema.ts`:

```typescript
export const notes = pgTable(
  'notes',
  {
    id: uuid('id').defaultRandom().primaryKey(),
    ownerId: text('owner_id')
      .notNull()
      .default(sql`auth.user_id()`),
    title: text('title').notNull().default('untitled note'),
    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow(),
    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow(),
    shared: boolean('shared').default(false),
  }
  (table) => [
    // ... RLS policies defined here
  ]
).enableRLS();

export const paragraphs = pgTable(
  'paragraphs',
  {
    id: uuid('id').defaultRandom().primaryKey(),
    noteId: uuid('note_id').references(() => notes.id),
    content: text('content').notNull(),
    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow(),
  }
  (table) => [
    // ... RLS policies defined here
  ]
).enableRLS();
```

Each note belongs to a user (via `ownerId`), and paragraphs are linked to notes through `noteId`.

### Securing tables with RLS

When making direct database queries from the frontend, **Row-Level Security (RLS) policies** are essential. They ensure that users can access **only their own data**.

RLS is crucial for any real-world app. RLS policies act as a safety net at the database level, so even if your frontend code has bugs, your data stays protected.

The demo app uses [Drizzle ORM](https://neon.com/docs/guides/rls-drizzle) to define RLS policies, which we highly recommend as a simpler, more maintainable way of writing RLS policies. Here's how the notes table defines its policies:

```typescript
crudPolicy({
  role: authenticatedRole,
  read: authUid(table.ownerId),
  modify: authUid(table.ownerId),
}),
pgPolicy("shared_policy", {
  for: "select",
  to: authenticatedRole,
  using: sql`${table.shared} = true`,
}),
```

These Drizzle policies generate the equivalent SQL policies for all CRUD operations (`SELECT`, `INSERT`, `UPDATE`, `DELETE`). For example:

```sql
-- SELECT
CREATE POLICY "crud-authenticated-policy-select" ON "notes"
  AS PERMISSIVE FOR SELECT TO "authenticated"
  USING ((select auth.user_id() = "notes"."owner_id"));
-- DELETE (similar for INSERT and UPDATE)
CREATE POLICY "crud-authenticated-policy-delete" ON "notes"
  AS PERMISSIVE FOR DELETE TO "authenticated"
  USING ((select auth.user_id() = "notes"."owner_id"));
CREATE POLICY "shared_policy" ON "notes"
  AS PERMISSIVE FOR SELECT TO "authenticated"
  USING ("notes"."shared" = true);
```

The policies ensure:

1. Users can only access their own notes (`SELECT`, `INSERT`, `UPDATE`, `DELETE`)
2. Shared notes are visible to authenticated users
3. Data access is enforced at the database level

The paragraphs table uses similar Drizzle policies that check ownership through the parent note:

```typescript
crudPolicy({
  role: authenticatedRole,
  read: sql`(select notes.owner_id = auth.user_id() from notes where notes.id = ${table.noteId})`,
  modify: sql`(select notes.owner_id = auth.user_id() from notes where notes.id = ${table.noteId})`,
}),
pgPolicy("shared_policy", {
  for: "select",
  to: authenticatedRole,
  using: sql`(select notes.shared from notes where notes.id = ${table.noteId})`,
}),
```

**Info: About auth.user_id()**

Neon's RLS policies use the auth.user_id() function, which extracts the user's ID from the JWT (JSON Web Token) provided by your authentication provider. In this demo, [Managed Better Auth](https://neon.com/docs/auth/overview) issues the JWTs, and Neon's Data API passes them to Postgres, so RLS can enforce per-user access.

For more details on RLS with Data API, see our [Row-Level Security with Neon guide](https://neon.com/docs/guides/row-level-security).

## Data API query patterns

Now let's look at how the demo app performs CRUD operations using the Data API.

### INSERT — Creating a new note

When a user creates a new note, the app generates a unique codename-style title and inserts it into the database. Here's how it works in `src/routes/note.tsx`:

```typescript
const { data, error } = await client
  .from('notes')
  .insert({ title: generateNameNote() })
  .select('id, title, shared, owner_id, paragraphs (id, content, created_at, note_id)')
  .single();
```

The `.select()` chained after `.insert()` lets you insert a record and immediately fetch it back (along with related data from other tables) in a single query. This is a useful pattern provided by the PostgREST-compatible API.

That's why you'll see codename-style labels like "tender fuchsia" in your notes list:

![New note UI](https://neon.com/docs/data-api/new_note.png)

### SELECT — Fetching all notes

To display all notes for the current user, ordered by creation date, the app queries the database in `src/routes/index.tsx`:

```typescript
const { data, error } = await client
  .from('notes')
  .select('id, title, created_at, owner_id, shared')
  .eq('owner_id', session.data.user.id)
  .order('created_at', { ascending: false });
```

The `.eq('owner_id', session.data.user.id)` method filters results, similar to a SQL `WHERE` clause, ensuring only notes belonging to the current user are returned.

Here's what your notes list will look like:

![Notes list UI](https://neon.com/docs/data-api/all_notes.png)

> **Hint:** To get back to your main notes list, click the **"note."** heading at the top of the app.

### UPDATE — Renaming a note

You can rename any note by editing its title directly in the app. When you do, the app updates the note in the database. Here's how it works in `src/components/app/note-title.tsx`:

```typescript
const { error } = await client.from('notes').update({ title: newTitle }).eq('id', id);
```

You can chain methods like `.from()`, `.update()`, and `.eq()` to build queries. For more complex queries, refer to the [Neon TypeScript SDK documentation](https://neon.com/docs/reference/javascript-sdk#insert).

Here's how a note looks after you update its title:

![Note title updated UI](https://neon.com/docs/data-api/renamed_note.png)

### INSERT — Adding paragraphs

When you press Enter to submit a paragraph, the app inserts it into the `paragraphs` table. Here's the pattern from `src/routes/note.tsx`:

```typescript
const { data, error } = await client
  .from('paragraphs')
  .insert({
    note_id: id,
    content: previousParagraph.content.trim(),
  })
  .select('*')
  .single();
```

## Try it yourself: Adding delete functionality

If you've explored the app, you may have noticed there's no way to delete a note. This is intentional; it's a hands-on exercise to help you understand the Data API patterns.

### Step 1: Add a delete button to the note card component

Update `src/components/app/note-card.tsx` to include a delete button:

```typescript
import { Link } from "@tanstack/react-router";
import moment from "moment";
import { Trash2Icon } from "lucide-react";

export default function NoteCard({
  id,
  title,
  createdAt,
  onDelete,
}: {
  id: string;
  title: string;
  createdAt: string;
  onDelete?: () => void;
}) {
  return (
    <div className="flex justify-between items-center">
      <Link to="/note" search={{ id }} className="flex-1 flex justify-between">
        <h5>{title}</h5>
        <p className="text-sm text-foreground/70">
          {moment(createdAt).fromNow()}
        </p>
      </Link>
      {onDelete && (
        <button
          onClick={onDelete}
          className="ml-2 p-1 text-muted-foreground hover:text-red-500"
        >
          <Trash2Icon size={16} />
        </button>
      )}
    </div>
  );
}
```

### Step 2: Add the delete handler to the notes list

Update `src/components/app/notes-list.tsx` to include the delete handler:

```typescript
import NoteCard from "@/components/app/note-card";
import type { Note } from "@/lib/api";
import { useRouter } from "@tanstack/react-router";
import { PlusCircleIcon } from "lucide-react";
import { client } from "@/lib/auth";

export default function NotesList({ notes }: { notes: Note[] }) {
  const router = useRouter();

  const addNote = async () => {
    router.navigate({
      to: "/note",
      search: { id: "new-note" },
      replace: true,
    });
  };

  const handleDelete = async (id: string) => {
    const { error } = await client.from("notes").delete().eq("id", id);
    if (!error) {
      window.location.reload();
    }
  };

  return (
    <div className="flex flex-col gap-4">
      <header className="flex items-center justify-between">
        <h3>My notes</h3>
        <button
          type="button"
          className="cursor-pointer border-none bg-none hover:bg-none flex items-center gap-1.5"
          onClick={addNote}
        >
          <PlusCircleIcon className="w-4 h-4" />
        </button>
      </header>
      <main className="flex flex-col gap-1.5 ">
        {notes?.map((note) => (
          <NoteCard
            key={note.id}
            id={note.id}
            title={note.title}
            createdAt={note.created_at}
            onDelete={() => handleDelete(note.id)}
          />
        ))}
        {notes.length === 0 && (
          <div className="text-sm text-foreground/50">No notes yet</div>
        )}
      </main>
    </div>
  );
}
```

Your app now includes a delete icon next to each note:

![notes app with delete](https://neon.com/docs/data-api/app_with_delete.png)

> If you can't delete a note, it likely still has paragraphs attached. Postgres prevents deleting notes that have related paragraphs because of the foreign key relationship.

### Step 3: Enable ON DELETE CASCADE

To allow deleting a note and all its paragraphs in one go, update your schema to use `ON DELETE CASCADE` on the `paragraphs.note_id` foreign key.

You can do this in the Neon SQL editor:

```sql
ALTER TABLE paragraphs
  DROP CONSTRAINT paragraphs_note_id_notes_id_fk,
  ADD CONSTRAINT paragraphs_note_id_notes_id_fk
    FOREIGN KEY (note_id) REFERENCES notes(id) ON DELETE CASCADE;
```

If you get an error about the constraint name, your database may use a different name for the foreign key. To find it, run:

```sql
SELECT conname FROM pg_constraint WHERE conrelid = 'paragraphs'::regclass;
```

Then use the name you find in the `DROP CONSTRAINT` and `ADD CONSTRAINT` commands above.

Now test deleting a note that has paragraphs; both the note and its paragraphs should be removed from the database.

## Learn more

- [Getting started with Data API](https://neon.com/docs/data-api/get-started)
- [Generate TypeScript types](https://neon.com/docs/data-api/generate-types)
- [SQL to REST Converter](https://neon.com/docs/data-api/sql-to-rest)
- [Managed Better Auth documentation](https://neon.com/docs/auth/overview)
- [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk)
- [PostgREST documentation](https://docs.postgrest.org/en/v13/)
- [Simplify RLS with Drizzle](https://neon.com/docs/guides/rls-drizzle)

--- [Document source](https://neon.com/docs/data-api/generate-types.md) ---

> Summary: The `npx @neondatabase/neon-js gen-types` command introspects a PostgreSQL schema and writes a TypeScript definition file with `Database`, `Tables`, `TablesInsert`, and `TablesUpdate` interfaces for type-safe Data API access. Use this page to add autocomplete, query-result type inference, and compile-time error checking to `@neon/neon-js` or `@neon/postgrest-js` clients. The tool accepts `--db-url`, `--output`, and `--schema` flags and can run as a package.json script to keep generated types in sync after schema changes.

# Generate TypeScript types from your database schema

Automatically generate TypeScript types from your database schema for type-safe Data API interactions.

Last updated: 2026-09-14

**Related docs**

- [Getting started with Data API](https://neon.com/docs/data-api/get-started)
- [Building a note-taking app](https://neon.com/docs/data-api/demo)
- [SQL to REST API Translator](https://neon.com/docs/data-api/sql-to-rest)

The Neon SDK offers a CLI tool that introspects your database schema to generate a TypeScript definition file. This promotes type safety and enhances the developer experience when interacting with your database via the Data API, particularly with PostgREST clients like [`@neon/postgrest-js`](https://www.npmjs.com/package/@neon/postgrest-js) and [`@neon/neon-js`](https://www.npmjs.com/package/@neon/neon-js). Key benefits include:

- **Autocomplete** for table names and columns.
- **Type inference** for query results.
- **Compile-time error checking** for invalid queries.

## Generate types

`@neon/neon-js` doesn't include the type generator, so run it from `@neondatabase/neon-js`, the package's previous name. The generated file works with both packages. Use `npx` to run the type generator. You must provide your **Direct Connection String** (Postgres URL) so the tool can connect to and inspect your database.

```bash
npx @neondatabase/neon-js gen-types \
  --db-url "postgresql://user:pass@ep-id.region.neon.tech/neondb" \
  --output src/types/database.ts
```

### Options

| Flag                    | Alias | Description                                                                                    | Default             |
| :---------------------- | :---- | :--------------------------------------------------------------------------------------------- | :------------------ |
| `--db-url`              | -     | The PostgreSQL connection string (Required).                                                   | -                   |
| `--output`              | `-o`  | The path where the file will be saved.                                                         | `database.types.ts` |
| `--schema`              | `-s`  | Schema to introspect. Repeatable to include multiple schemas, for example `-s public -s auth`. | `public`            |
| `--postgrest-v9-compat` | -     | Disables one-to-one relationship detection.                                                    | `false`             |
| `--query-timeout`       | -     | The timeout for the schema introspection query, for example `30s` or `1m`.                     | `15s`               |

## Use generated types

Once generated, import the `Database` interface and pass it as a generic argument to `createClient`.

```typescript
// Import the generated type
import type { Database } from '@/types/database';
import { createClient } from '@neon/neon-js';

// Pass the generic to the client
const client = createClient<Database>(process.env.NEON_DATABASE_URL!);

// 3. Enjoy full type safety
const { data, error } = await client
  .from('posts') // Autocomplete: only 'posts' or existing tables
  .select('id, content') // Autocomplete: only columns in 'posts'
  .eq('is_published', true); // Type check: ensures 'is_published' expects a boolean
```

Use the HTTPS Neon database URL without credentials or query parameters for `NEON_DATABASE_URL`, for example `https://ep-example.c-2.us-east-1.aws.neon.tech/neondb`. You can find the matching Data API URL on the **Data API** page in the Neon Console or with `neon data-api get`; to get the single database URL, remove the `.apirest` hostname label and trailing `/rest/v1` path. If you start from a Managed Better Auth URL instead, remove the `.neonauth` hostname label and trailing `/auth` path. The cell label (if present), region, and database path stay the same. Prefer the older two-URL setup? See the [object-form alternative](https://neon.com/docs/reference/javascript-sdk#initializing) in the JavaScript SDK reference.

### Response types

The client automatically infers the return type based on your query.

```typescript
// 'data' is automatically typed as: { id: number; content: string }[] | null
const { data } = await client.from('posts').select('id, content');

// 'data' is automatically typed as: { id: number; content: string } | null
const { data } = await client.from('posts').select('id, content').single();
```

### Helper types

The generated file also exports utility types for working with your tables outside of queries:

```typescript
import type { Tables, TablesInsert, TablesUpdate } from '@/types/database';

// Tables<> gives you the row type (what you get back from queries)
type Note = Tables<'notes'>;

// TablesInsert<> gives you the insert type (for creating new rows)
type NewNote = TablesInsert<'notes'>;

// TablesUpdate<> gives you the update type (for partial updates)
type NoteUpdate = TablesUpdate<'notes'>;
```

These are useful when you need to type function parameters, state variables, or props separately from your queries.

## Automate with package.json

To keep your types in sync with your database schema, we recommend adding a script to your `package.json`.

```json
{
  "scripts": {
    "generate-types": "npx @neondatabase/neon-js gen-types --db-url \"$DATABASE_URL\" --output src/types/database.ts"
  }
}
```

You can now run `npm run generate-types` whenever you make schema changes (like adding a new table or column).

## Using with the Neon PostgREST Client

If you are using `@neon/postgrest-js` (without Managed Better Auth), the types work exactly the same way:

```typescript
import type { Database } from '@/types/database';
import { NeonPostgrestClient } from '@neon/postgrest-js';

const client = new NeonPostgrestClient<Database>({
  dataApiUrl: process.env.NEON_DATA_API_URL,
});
```

--- [Document source](https://neon.com/docs/data-api/get-started.md) ---

> Summary: The Neon Data API exposes your Postgres database as a REST endpoint secured by JWT authentication and Row-Level Security. Applications can query tables without a connection pool or SQL driver. Use this page to enable the API, create an RLS-protected table, and run your first queries via the @neon/neon-js client or direct HTTP requests. The API is enabled per branch for a single database and does not support projects with IP Allow or Private Networking configured.

# Getting started with Neon Data API

Learn how to enable and use the Neon Data API

Last updated: 2026-10-09

This guide walks you through enabling the Data API, creating a table with RLS, and running your first query.

**Important: Secure your data before exposing it**

The Data API has no permission layer of its own. Every request is authorized entirely by your PostgreSQL `GRANT` statements and [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security) policies, so a missing or misconfigured policy can expose a table to anyone with the endpoint URL. Before exposing data, follow [Access control & security](https://neon.com/docs/data-api/access-control) and [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial), and run the [Data API advisors](https://neon.com/docs/data-api/database-advisor) to catch misconfigurations.

## Before you begin

- The Neon Data API is enabled at the **branch** level for a single database. Each branch has its own Data API configuration, so you must select the correct branch before enabling the API.
- Neon Data API does not currently support projects with [IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow) or [Private Networking](https://neon.com/docs/guides/neon-private-networking) enabled.

## Enable the Data API

**Tip: Enable programmatically**

You can also enable the Data API from the terminal with [`neon data-api create`](https://neon.com/docs/cli/data-api#create), declaratively in `neon.ts` with [`neon config add data-api`](https://neon.com/docs/cli/config#add), using the [Neon API](https://neon.com/docs/data-api/manage#manage-via-the-neon-api), or with the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server#available-tools) (`provision_neon_data_api` tool).

### 1. Navigate to the Data API page

In the Neon Console, select your project and select **Postgres database** > **Data API**.

![Data API page with enable button](https://neon.com/docs/data-api/data_api_sidebar.png)

### 2. Configure authentication

The Data API uses JWTs for access control. Configure a provider now or later from the **Settings** tab. For public data that doesn't require login, use the [`anonymous` role](https://neon.com/docs/data-api/access-control#2-the-anonymous-role) instead.

- **Managed Better Auth**: Check the **Use Neon Auth** checkbox to enable [Managed Better Auth](https://neon.com/docs/auth/overview) as your provider. Managed Better Auth manages sign-up, login, and account access, issuing the JWTs required for API requests.
- **Other providers**: Leave the checkbox unchecked and configure your provider (such as Auth0, Clerk, or Firebase Auth) later. See [Custom authentication providers](https://neon.com/docs/data-api/custom-authentication-providers) for setup instructions.

### 3. Configure schema access (optional)

The **Grant public schema access** checkbox automatically applies database permissions so the `authenticated` role can read and write to tables in the `public` schema.

<details>

<summary>View the GRANT statements applied</summary>

```sql
-- Schema usage
GRANT USAGE ON SCHEMA public TO authenticated;

-- For existing tables
GRANT SELECT, UPDATE, INSERT, DELETE ON ALL TABLES IN SCHEMA public TO authenticated;

-- For future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT, UPDATE, INSERT, DELETE ON TABLES TO authenticated;

-- For sequences (for identity columns)
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO authenticated;
```

</details>

Enable this checkbox unless you need to manage permissions manually. If you leave it unchecked, see [Access control](https://neon.com/docs/data-api/access-control) for details on granting permissions yourself.

### 4. Enable Data API

Click **Enable Data API** to activate the Data API. Once enabled, you'll see the Data API page.

![Data API enabled view](https://neon.com/docs/data-api/data-api-enabled.png)

On the **API** tab, you'll see:

- **API URL**: Your REST API endpoint for accessing your database
- **Refresh schema cache**: A button to update the Data API when you make schema changes
- **Security section**: Options to configure authentication and enable Row-Level Security on your tables

**Warning:** If you have tables without RLS enabled, you'll see a warning that authenticated users can view all rows in those tables. We'll show you how to add RLS in the next step.

For advanced configuration options like custom authentication providers, exposed schemas, and CORS settings, see the **Settings** tab or refer to [Managing the Data API](https://neon.com/docs/data-api/manage).

Next, you'll create a table with **Row-Level Security (RLS)** policies to define which rows users can access.

## Create a table with RLS

The Data API interacts directly with your Postgres schema. Because the API is accessible over the internet, it's crucial to enforce security at the database level using PostgreSQL's **Row-Level Security (RLS)** features.

In this example, we'll create a `posts` table where users can read published posts and manage their own posts securely. **Choose the approach that matches how you manage your database schema:**

- **SQL**: Write SQL directly in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or manage migrations manually. See our [PostgreSQL RLS tutorial](https://neon.com/postgresql/postgresql-administration/postgresql-row-level-security) for more on RLS fundamentals.
- **Drizzle (crudPolicy)**: A high-level helper that generates RLS policies in one declaration. Best for simple cases where read and modify permissions follow the same pattern.
- **Drizzle (pgPolicy)**: Define policies per operation or use a single `FOR ALL` policy. Use this when you need different logic for different operations (for example, time-limited updates, different rules for INSERT vs UPDATE).

For more on Drizzle RLS, see our [Drizzle RLS guide](https://neon.com/docs/guides/rls-drizzle).

**SQL**

```sql
-- This script creates a posts table, enables RLS, and defines two policies:
-- one allows authenticated users to read published posts, and the other
-- gives users full access (read, insert, update, delete) to their own posts.

-- 1. Create the table
CREATE TABLE posts (
  id bigint GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
  user_id text DEFAULT (auth.user_id()) NOT NULL,
  content text NOT NULL,
  is_published boolean DEFAULT false,
  "created_at" timestamp with time zone DEFAULT now() NOT NULL
);

-- 2. Enable RLS
ALTER TABLE posts ENABLE ROW LEVEL SECURITY;

-- 3. Read published posts
CREATE POLICY read_published_posts ON posts
FOR SELECT TO authenticated
USING (is_published = true);

-- 4. Full access to own posts
CREATE POLICY manage_own_posts ON posts
FOR ALL TO authenticated
USING (auth.user_id() = user_id)
WITH CHECK (auth.user_id() = user_id);
```

**Drizzle (crudPolicy)**

```typescript
// This schema defines the same two-policy behavior using Drizzle ORM. The crudPolicy
// helper generates equivalent RLS: `read` allows published posts or own posts,
// and `modify` restricts insert, update, and delete to own posts.

import { sql } from 'drizzle-orm';
import { crudPolicy, authenticatedRole, authUid } from 'drizzle-orm/neon';
import { bigint, boolean, pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const posts = pgTable(
  'posts',
  {
    id: bigint({ mode: 'number' }).primaryKey(),
    userId: text('user_id')
      .notNull()
      .default(sql`(auth.user_id())`),
    content: text().notNull(),
    isPublished: boolean('is_published').notNull().default(false),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    crudPolicy({
      role: authenticatedRole,
      read: sql`is_published OR (auth.user_id() = ${table.userId})`,
      modify: authUid(table.userId),
    }),
  ]
);
```

**Drizzle (pgPolicy)**

```typescript
// This schema defines the same two-policy behavior using Drizzle ORM with pgPolicy.
// One policy allows reading published posts; the other gives full access to own posts.

import { sql } from 'drizzle-orm';
import { authenticatedRole, authUid } from 'drizzle-orm/neon';
import { bigint, boolean, pgPolicy, pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const posts = pgTable(
  'posts',
  {
    id: bigint({ mode: 'number' }).primaryKey(),
    userId: text('user_id')
      .notNull()
      .default(sql`(auth.user_id())`),
    content: text().notNull(),
    isPublished: boolean('is_published').notNull().default(false),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => [
    pgPolicy('read_published_posts', {
      to: authenticatedRole,
      for: 'select',
      using: sql`is_published = true`,
    }),
    pgPolicy('manage_own_posts', {
      to: authenticatedRole,
      for: 'all',
      using: authUid(table.userId),
      withCheck: authUid(table.userId),
    }),
  ]
);
```

**Info: What is auth.user_id() and authUid()?**

`auth.user_id()` returns the JWT `sub` claim as `text`. Use `auth.uid()` instead if your `user_id` column is `uuid`; it parses `sub` as a UUID and returns `NULL` if it's not valid. `authUid()` is a Drizzle helper for `auth.user_id()`.

## Refresh schema cache

The Data API caches your database schema for performance. When you modify your schema (adding tables, modifying columns, or changing structure, etc.), you need to refresh this cache for the changes to take effect.

**Option 1: Neon Console**

Go to **Postgres database** > **Data API** in the Neon Console and click **Refresh schema cache**.

![Data API refresh schema cache button](https://neon.com/docs/data-api/data_api_schema_refresh.png)

**Option 2: Neon API**

You can also refresh the schema cache programmatically. The `PATCH /projects/{project_id}/branches/{branch_id}/data-api/{database_name}` endpoint always refreshes the schema cache as part of the operation. Send an empty body to trigger a refresh:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/data-api/{database_name}' \
  -H 'Authorization: Bearer YOUR_NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## Connect and Query

You can connect to the Data API using a client library or direct HTTP requests.

### Option 1: Using a client library

Install a client library and run your first query. Choose the option that matches your authentication provider:

**Managed Better Auth**

Use [`@neon/neon-js`](https://www.npmjs.com/package/@neon/neon-js) if you're using [Managed Better Auth](https://neon.com/docs/auth/overview). This library handles token management automatically.

**1. Install**

```bash
npm install @neon/neon-js
```

**2. Usage**

```typescript
import { createClient } from '@neon/neon-js';

// Initialize with Managed Better Auth
// Use your Neon database URL without credentials or query parameters.
// Example: https://ep-example.c-2.us-east-1.aws.neon.tech/neondb
const client = createClient(import.meta.env.VITE_NEON_DATABASE_URL);

// Query - the JWT token is injected automatically when the user is signed in
const { data, error } = await client
  .from('posts')
  .select('*')
  .eq('is_published', true)
  .order('created_at', { ascending: false });

console.log(data);
```

**Note:** This client runs in the browser. Environment variable syntax depends on your framework: `import.meta.env.VITE_*` for Vite-based projects (Vite, SvelteKit, Astro), `process.env.NEXT_PUBLIC_*` for Next.js. The `VITE_NEON_DATABASE_URL` value is not your Postgres connection string; use the HTTPS Neon database URL shown in the example above. You can find the matching Data API URL on the **Data API** page in the Neon Console or with `neon data-api get`; to get the single database URL, remove the `.apirest` hostname label and trailing `/rest/v1` path. If you start from a Managed Better Auth URL instead, remove the `.neonauth` hostname label and trailing `/auth` path. The cell label (if present), region, and database path stay the same.

**Any authentication provider**

Use [`@neon/postgrest-js`](https://www.npmjs.com/package/@neon/postgrest-js) with any authentication provider that issues JWTs, such as [Auth0](https://auth0.com/), [Clerk](https://clerk.com/), or [Firebase Auth](https://firebase.google.com/products/auth).

**1. Install**

```bash
npm install @neon/postgrest-js
```

**2. Usage**

Provide a function that retrieves the JWT token from your authentication system. This token is included in each request to enforce RLS policies.

```typescript
import { fetchWithToken, NeonPostgrestClient } from '@neon/postgrest-js';

const getTokenFromAuthSystem = async (): Promise<string> => {
  // Retrieve the JWT token from your auth system (e.g., Auth0, Clerk, Firebase)
  return 'your-jwt-token';
};

// Get your URL from the Neon Console or run: neon data-api get
const client = new NeonPostgrestClient({
  dataApiUrl: import.meta.env.VITE_NEON_DATA_API_URL,
  options: {
    global: {
      fetch: fetchWithToken(getTokenFromAuthSystem),
    },
  },
});

// Query
const { data, error } = await client
  .from('posts')
  .select('*')
  .eq('is_published', true)
  .order('created_at', { ascending: false });

console.log(data);
```

> For detailed guidance on performing `INSERT`, `UPDATE`, `DELETE`, and advanced queries (filters, joins, stored procedures, etc.) in either case, refer to the [Neon Javascript SDK documentation](https://neon.com/docs/reference/javascript-sdk#insert).

### Option 2: Direct HTTP requests

Query the Data API directly using any HTTP client. Include the `Authorization` header with a valid JWT token from your authentication provider. The token must include a `sub` claim for RLS policies to work correctly.

**Where to get the JWT token:**

- **Your auth provider's SDK**: Retrieve the token using your provider's API (for example, `getAccessToken()` in Auth0, `getToken()` in Clerk).
- **Managed Better Auth**: Retrieve the token using `client.auth.getSession()` from the `@neon/neon-js` library (see [Get current session](https://neon.com/docs/reference/javascript-sdk#auth-getsession)), or use the Auth API reference UI for manual testing (see [Testing with Managed Better Auth](https://neon.com/docs/data-api/get-started#testing-with-neon-auth) below).

**About the `sub` claim:**

For RLS policies to work correctly, the JWT token must include a `sub` (subject) claim, which contains the user's unique identifier. The Data API uses this claim to enforce [Row-Level Security](https://neon.com/docs/guides/row-level-security) policies via the `auth.user_id()` function. Most authentication providers include this claim by default.

**Example: SELECT (GET)**

This request queries the `posts` table for all published posts, ordered by most recent first:

```bash
curl -X GET 'https://your-data-api-endpoint/rest/v1/posts?is_published=eq.true&order=created_at.desc' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json'
```

**Example: INSERT (POST)**

This request inserts a new row into the `posts` table, setting the `content` column:

```bash
curl -X POST 'https://your-data-api-endpoint/rest/v1/posts' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Hello world"}'
```

> For UPDATE, DELETE, filtering, and other operations, see the [PostgREST documentation](https://postgrest.org/en/stable/references/api.html).

## Testing with Managed Better Auth

If you're using [Managed Better Auth](https://neon.com/docs/auth/overview) and want to test the Data API without building an application first, you can obtain a JWT token using the interactive Auth API reference UI or any HTTP client (the examples below use cURL). If you're using a different provider, obtain JWT tokens through your provider's authentication flow and use them in the `Authorization: Bearer` header as shown in the [HTTP examples above](https://neon.com/docs/data-api/get-started#option-2-direct-http-requests).

**Auth API reference UI**

The Auth API reference UI is an interactive browser-based tool for exploring and testing all Managed Better Auth endpoints. It is powered by [Better Auth's OpenAPI plugin](https://www.better-auth.com/docs/plugins/open-api#usage).

1. **Open the Auth API reference:** Navigate to your Auth URL with `/reference` appended, for example, `https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth/reference`. You can find your **Auth URL** under **Settings** > **Better Auth** > **Project Info** in the Neon Console.

2. **Create a test user:** Use the UI to call `POST /sign-up/email` with a JSON body:

   ```json
   {
     "email": "test@example.com",
     "password": "your-password",
     "name": "Test User"
   }
   ```

3. **Or sign in with an existing user:** Call `POST /sign-in/email` with:

   ```json
   {
     "email": "test@example.com",
     "password": "your-password"
   }
   ```

4. **Get the JWT token:** Call `GET /get-session` and copy the JWT from the `Set-Auth-Jwt` response header.

5. **Query the Data API:** Use the JWT in your requests:

   ```bash
   curl -X GET 'https://your-data-api-endpoint/rest/v1/posts' \
     -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
     -H 'Content-Type: application/json'
   ```

**cURL**

The following steps walk through signing up, obtaining a JWT, and querying the Data API from the terminal. You can find your **Auth URL** under **Settings** > **Better Auth** > **Project Info** and your **Data API URL** on the **Data API** page in the Neon Console.

**1. Sign up (or sign in)**

Create a test user. The `-c` flag saves the session cookie returned by Managed Better Auth:

```bash
curl -X POST 'https://ep-example-auth.neonauth.us-east-1.aws.neon.tech/neondb/auth/sign-up/email' \
  -c cookies.txt \
  -H 'Content-Type: application/json' \
  -H 'Origin: http://localhost:3000' \
  -d '{"email":"test@example.com","password":"your-password","name":"Test User","callbackURL":"http://localhost:3000"}'
```

To sign in with an existing user instead, replace `/sign-up/email` with `/sign-in/email` and omit the `name` and `callbackURL` fields.

**2. Get the JWT token**

Call `get-session` using the saved cookie (`-b`). The `-D -` flag prints response headers to your terminal. Look for the `set-auth-jwt` header and copy its value:

```bash
curl 'https://ep-example-auth.neonauth.us-east-1.aws.neon.tech/neondb/auth/get-session' \
  -b cookies.txt \
  -H 'Origin: http://localhost:3000' \
  -D - -o /dev/null
```

The output will include a line like:

```
set-auth-jwt: eyJhbGci...
```

Copy the full token value.

**3. Query the Data API**

Use the JWT as a bearer token to query your table:

```bash
curl 'https://ep-example.apirest.us-east-1.aws.neon.tech/neondb/rest/v1/posts?select=*' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN'
```

**Tip: Token expiration**

JWTs expire after approximately 15 minutes. If you receive a `"JWT token has expired"` error, sign in again to get a fresh token.

## Query patterns

The Data API supports full CRUD operations and advanced queries. Here's a quick reference of the most common methods available in the [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk):

### CRUD operations

| Operation  | Method      | Example                                                         | SDK Reference                                                   |
| ---------- | ----------- | --------------------------------------------------------------- | --------------------------------------------------------------- |
| **Select** | `.select()` | `client.from('posts').select('*')`                              | [select](https://neon.com/docs/reference/javascript-sdk#select) |
| **Insert** | `.insert()` | `client.from('posts').insert({ title: 'New post' })`            | [insert](https://neon.com/docs/reference/javascript-sdk#insert) |
| **Update** | `.update()` | `client.from('posts').update({ title: 'Updated' }).eq('id', 1)` | [update](https://neon.com/docs/reference/javascript-sdk#update) |
| **Delete** | `.delete()` | `client.from('posts').delete().eq('id', 1)`                     | [delete](https://neon.com/docs/reference/javascript-sdk#delete) |
| **RPC**    | `.rpc()`    | `client.rpc('function_name', { param: 'value' })`               | [rpc](https://neon.com/docs/reference/javascript-sdk#rpc)       |

### Filters

| Filter     | Description                      | Example                                |
| ---------- | -------------------------------- | -------------------------------------- |
| `.eq()`    | Equals                           | `.eq('status', 'published')`           |
| `.neq()`   | Not equals                       | `.neq('status', 'draft')`              |
| `.gt()`    | Greater than                     | `.gt('price', 100)`                    |
| `.lt()`    | Less than                        | `.lt('price', 50)`                     |
| `.gte()`   | Greater than or equal            | `.gte('quantity', 1)`                  |
| `.lte()`   | Less than or equal               | `.lte('quantity', 10)`                 |
| `.like()`  | Pattern match (case-sensitive)   | `.like('title', '%hello%')`            |
| `.ilike()` | Pattern match (case-insensitive) | `.ilike('title', '%hello%')`           |
| `.is()`    | Is null / not null               | `.is('deleted_at', null)`              |
| `.in()`    | Value in array                   | `.in('status', ['active', 'pending'])` |

### Modifiers

| Modifier    | Description         | Example                                      |
| ----------- | ------------------- | -------------------------------------------- |
| `.order()`  | Sort results        | `.order('created_at', { ascending: false })` |
| `.limit()`  | Limit rows returned | `.limit(10)`                                 |
| `.single()` | Return single row   | `.select('*').eq('id', 1).single()`          |

For the complete list of methods and detailed examples, see the [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk).

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Managed authentication with JWTs that work natively with the Data API and Row Level Security
- [Build a note-taking app](https://neon.com/docs/data-api/demo): Hands-on tutorial with Data API queries
- [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk): All database methods: select, insert, update, delete, filters, and more
- [Generate TypeScript types](https://neon.com/docs/data-api/generate-types): Get autocomplete for table names and columns
- [SQL to REST Converter](https://neon.com/docs/data-api/sql-to-rest): Convert SQL queries to API calls
- [Row-Level Security with Neon](https://neon.com/docs/guides/row-level-security): Secure your data at the database level

--- [Document source](https://neon.com/docs/data-api/manage.md) ---

> Summary: Neon Data API management covers post-enablement configuration: registering or replacing JWT authentication providers via JWKS URL, and tuning advanced settings such as exposed schemas, anonymous role, and CORS origins. Use this page to switch auth providers, tighten security, or manage the API lifecycle programmatically via the Neon REST API.

# Manage Data API

Configure schemas, manage authentication providers, and control API access.

Last updated: 2026-09-30

**Related docs**

- [Getting started with Data API](https://neon.com/docs/data-api/get-started)
- [Access control & security](https://neon.com/docs/data-api/access-control)
- [Troubleshooting](https://neon.com/docs/data-api/troubleshooting)
- [Neon CLI: data-api command](https://neon.com/docs/cli/data-api)

This page covers managing the Data API after it is enabled. To enable via the Console, see [Getting started with Data API](https://neon.com/docs/data-api/get-started). To enable programmatically, see [Enable via the Neon API](https://neon.com/docs/data-api/manage#enable) or [Enable via the CLI](https://neon.com/docs/data-api/manage#enable-via-the-cli). To disable from the Console, scroll to **Disable** at the bottom of the **Settings** tab.

**Important: Secure your data before exposing it**

The Data API has no permission layer of its own. Every request is authorized entirely by your PostgreSQL `GRANT` statements and [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security) policies, so a missing or misconfigured policy can expose a table to anyone with the endpoint URL. Before exposing data, follow [Access control & security](https://neon.com/docs/data-api/access-control) and [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial), and run the [Data API advisors](https://neon.com/docs/data-api/database-advisor) to catch misconfigurations.

## Manage authentication providers

You can configure which authentication provider validates JWT tokens for your Data API requests. Only one provider can be configured at a time. If you enabled the Data API with [Managed Better Auth](https://neon.com/docs/auth/overview), it is already set as the default provider.

**Console**

Navigate to **Postgres database** > **Data API** and select the **Settings** tab. The **Authentication** section shows the current provider.

![Data API settings](https://neon.com/docs/data-api/data_api_advanced_settings.png)

- **Add a provider:** If no provider is currently configured, click **Add provider** and enter the JWKS URL supplied by your auth service (for example, Auth0, Clerk, or Firebase). For help finding your provider's JWKS URL, see [Custom authentication providers](https://neon.com/docs/data-api/custom-authentication-providers#supported-providers). Some providers also require a [JWT Audience](https://neon.com/docs/data-api/custom-authentication-providers#what-is-jwt-audience) value.
- **Replace a provider:** To switch to a different provider, remove the current one first, then add the new one using **Add provider**.
- **Remove a provider:** Use the provider dropdown menu to remove the current provider.

**API**

Add an external authentication provider by registering a JWKS URL:

```bash
curl -X POST 'https://console.neon.tech/api/v2/projects/{project_id}/jwks' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "jwks_url": "https://your-provider/.well-known/jwks.json",
    "provider_name": "Auth0",
    "branch_id": "{branch_id}"
  }'
```

You can also include an optional `jwt_audience` field if your provider requires it.

To remove a provider, first list the configured JWKS URLs to find the `jwks_id`:

```bash
curl -X GET 'https://console.neon.tech/api/v2/projects/{project_id}/jwks' \
  -H 'Authorization: Bearer $NEON_API_KEY'
```

Then delete it:

```bash
curl -X DELETE 'https://console.neon.tech/api/v2/projects/{project_id}/jwks/{jwks_id}' \
  -H 'Authorization: Bearer $NEON_API_KEY'
```

For the full JWKS specification, see the [Neon API Reference](https://neon.com/docs/reference/api/projects/add-project-jwks).

**Warning:** Removing an authentication provider invalidates all tokens issued by that provider. Users relying on that provider will receive `401 Unauthorized` errors until they authenticate via a valid provider.

**Tip: Auth API reference**

If you're using Managed Better Auth, there's an interactive API reference for authentication endpoints at your Auth URL with `/reference` appended (for example, `https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth/reference`). See [Testing with Managed Better Auth](https://neon.com/docs/data-api/get-started#testing-with-neon-auth) for details.

## Advanced settings

The **Advanced settings** section on the Settings tab controls the security, performance, and behavior of your Data API endpoint. After making changes, click **Save** to apply them.

### Exposed schemas

**Default:** `public`

Defines which PostgreSQL schemas are exposed as REST API endpoints. By default, only the `public` schema is accessible. If you use other schemas (for example, `api`, `v1`), select them from the drop-down list to add them.

**Note:** **Permissions apply:** Adding a schema here exposes the _endpoints_, but the database role used by the API must still have `USAGE` privileges on the schema and `SELECT` privileges on the tables. Refer to [Access control for Data API](https://neon.com/docs/data-api/access-control) for more details.

### Extra search path schemas

**Default:** `Empty`

Adds extra PostgreSQL schemas to the search path used for every Data API request. These schemas aren't exposed as REST API endpoints themselves; they're only available for database objects inside your [exposed schemas](https://neon.com/docs/data-api/manage#exposed-schemas) to reference, which is useful for schemas that hold PostgreSQL extensions. Corresponds to the `db_extra_search_path` field in the API settings object.

### Anonymous role

**Default:** `anonymous`

Specifies the database role used for **unauthenticated requests** (requests sent without an Authorization header). To allow public access to specific data, configure this role in your database using SQL `GRANT` statements.

### Maximum rows per request

**Default:** `Empty`

Enforces a hard limit on the number of rows returned in a single API response. This prevents accidental performance degradation from large queries. Clients should use pagination limits to retrieve data within this threshold. This also prevents unexpected egress costs from large data transfers.

### JWT role claim key

**Default:** `.role`

Specifies the path within the JWT token that contains the database role name. The Data API uses this role to execute queries on behalf of the authenticated user. For example, `.role` extracts the value of the top-level `role` claim from the token. Corresponds to the `jwt_role_claim_key` field in the API settings object. This field is required when updating settings via the API.

### JWT cache max lifetime

**Default:** `Empty`

Sets the maximum lifetime, in seconds, that a validated JWT is kept in the Data API's cache. Caching validated tokens reduces the number of times the Data API needs to fetch and verify keys from your authentication provider's JWKS URL. Corresponds to the `jwt_cache_max_lifetime` field in the API settings object.

### CORS allowed origins

**Default:** `Empty (Allows all origins)`

Controls which web domains are permitted to fetch data from your API via the browser.

- **Empty:** Allows `*` (any domain). Useful for development.
- **Production:** List your specific domains (for example, `https://myapp.com`) to prevent unauthorized websites from querying your API.

### OpenAPI specification

**Default:** `Disabled`

When enabled, an auto-generated OpenAPI 3 schema describing your tables, columns, and REST endpoints is available at your Data API URL with `/openapi.json` appended:

```
https://your-data-api-endpoint/rest/v1/openapi.json
```

**Important: Authentication required**

Accessing the OpenAPI spec requires a valid JWT token, just like other Data API requests. Include the `Authorization: Bearer` header when fetching the spec:

```bash
curl -X GET 'https://your-data-api-endpoint/rest/v1/openapi.json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN'
```

### Server timing headers

**Default:** `Disabled`

When enabled, the Data API includes `Server-Timing` headers in each response. These headers show how long different parts of the request took to process (for example, database execution time and internal processing time). You can use this information to debug slow queries, measure performance, and troubleshoot latency issues in your application.

## Manage via the Neon API

You can manage the Data API programmatically using the [Neon API](https://neon.com/docs/reference/api). All Data API endpoints use the following base path:

```
/projects/{project_id}/branches/{branch_id}/data-api/{database_name}
```

You can find your `project_id` and `branch_id` on the [Project settings](https://neon.com/docs/manage/projects#project-settings) page in the Neon Console. The `database_name` is the name of the database you want to expose (for example, `neondb`). You will also need an [API key](https://neon.com/docs/manage/api-keys).

### Enable

Send a POST request to [enable the Data API](https://neon.com/docs/reference/api/dataapi/create-project-branch-data-api) for a database on a branch. If the Data API is already enabled, this call returns an error.

```bash
curl -X POST 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/data-api/{database_name}' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

Response (201 Created):

```json
{
  "url": "https://ep-example.apirest.us-east-1.aws.neon.tech/neondb/rest/v1"
}
```

The empty body enables the Data API without an authentication provider. To configure authentication at enable time, change the request body:

- **Managed Better Auth:** `-d '{"auth_provider": "neon_auth", "add_default_grants": true}'`

  If Managed Better Auth is not already enabled on the branch, this automatically provisions it. The optional `add_default_grants` option grants authenticated users permissions on tables in the `public` schema, matching the default Console behavior. See [Managed Better Auth](https://neon.com/docs/auth/overview) to learn more.

- **External provider:** `-d '{"auth_provider": "external", "jwks_url": "https://your-provider/.well-known/jwks.json"}'`

  See [Custom authentication providers](https://neon.com/docs/data-api/custom-authentication-providers) for supported providers and how to find your JWKS URL.

Optional fields in the enable request body:

- **`add_default_grants`** (boolean, default `false`): When `true`, grants all permissions on tables in the `public` schema to authenticated users.
- **`settings`**: Include a [settings object](https://neon.com/docs/data-api/manage#update-configuration) to configure the Data API in a single request instead of making a separate PATCH call.

### Get Data API details

[Retrieve the current status and configuration](https://neon.com/docs/reference/api/dataapi/get-project-branch-data-api) of the Data API for a branch.

```bash
curl -X GET 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/data-api/{database_name}' \
  -H 'Authorization: Bearer $NEON_API_KEY'
```

Response (200 OK):

```json
{
  "url": "https://ep-example.apirest.us-east-1.aws.neon.tech/neondb/rest/v1",
  "status": "active",
  "settings": {
    "db_aggregates_enabled": true,
    "db_anon_role": "anonymous",
    "db_schemas": [
      "public"
    ],
    "jwt_role_claim_key": ".role"
  },
  "available_schemas": [
    "auth",
    "public"
  ]
}
```

The `settings` object reflects the current configuration (see [Advanced settings](https://neon.com/docs/data-api/manage#advanced-settings) for field descriptions). The `available_schemas` array lists the schemas in your database that can be exposed via the API.

### Update configuration

Send a PATCH request to [update the configuration](https://neon.com/docs/reference/api/dataapi/update-project-branch-data-api). This also refreshes the schema cache. The response is always an empty object (`{}`), with status 201.

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/data-api/{database_name}' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

An empty body refreshes the schema cache without changing settings. To update settings, include a `settings` object in the request body. First retrieve the current settings with a [GET request](https://neon.com/docs/data-api/manage#get-data-api-details), then send all fields with your changes:

`-d '{"settings": {"db_max_rows": 100, "db_schemas": ["public"], "jwt_role_claim_key": ".role", "db_anon_role": "anonymous", "db_aggregates_enabled": true}}'`

**Important:** The `settings` object replaces the existing settings entirely. It is not merged. Any field you omit is reset to its default. The `jwt_role_claim_key` field is required.

### Disable

[Remove the Data API](https://neon.com/docs/reference/api/dataapi/delete-project-branch-data-api) from a branch. The response is an empty object (`{}`), with status 200.

```bash
curl -X DELETE 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/data-api/{database_name}' \
  -H 'Authorization: Bearer $NEON_API_KEY'
```

**Warning: Immediate effect**

Disabling the Data API immediately terminates all active connections and blocks all incoming HTTP requests. Any applications, edge functions, or websites relying on the API will stop working instantly. Re-enabling the Data API creates a fresh instance with default settings; the previous configuration is not restored.

For the full Data API specification, see the [Neon API Reference](https://neon.com/docs/reference/api/dataapi/create-project-branch-data-api).

## Manage via the Neon CLI

You can also manage the Data API from the terminal using the [Neon CLI](https://neon.com/docs/cli). The `data-api` command requires **neon 2.22.2** or later.

### Enable via the CLI

Provision the Data API for a database. The `--auth-provider` option accepts `neon_auth` or `external`. For external providers, also pass `--jwks-url`:

```bash
neon data-api create --database neondb --auth-provider neon_auth
```

### Get Data API details

Show the current status and configuration:

```bash
neon data-api get --database neondb
```

### Update configuration

Update settings using [settings flags](https://neon.com/docs/cli/data-api#settings-flags). By default, flags are merged with the current configuration. Pass `--replace` to overwrite all settings with only the provided flags:

```bash
neon data-api update --database neondb --db-max-rows 1000
```

To refresh the schema cache without changing settings:

```bash
neon data-api refresh-schema --database neondb
```

### Disable

Remove the Data API from a database:

```bash
neon data-api delete --database neondb
```

For the full command reference including all options and flags, see [Neon CLI command: data-api](https://neon.com/docs/cli/data-api).

--- [Document source](https://neon.com/docs/data-api/overview.md) ---

> Summary: Neon Data API is a PostgREST-compatible HTTP query interface for Neon Postgres. It lets web browsers, Cloudflare Workers, Vercel Edge, and serverless functions query a database without persistent TCP connections. Standard Postgres drivers don't work in browsers or edge runtimes. The Data API solves this by accepting standard HTTP requests, validating JWTs from any auth provider, and enforcing PostgreSQL Row-Level Security policies. Each request is stateless, so the API scales to thousands of concurrent users without connection pool exhaustion.

# Neon Data API

A fully managed REST interface for your Neon database

Last updated: 2026-09-30

The Neon Data API is the HTTP query service in the Neon backend for apps and agents. It provides a secure, stateless interface to your database, letting you access and manage your data directly from web browsers, serverless functions, and edge runtimes using standard HTTP methods. Key benefits include:

- **Browser and edge compatibility.** Standard Postgres drivers don't work in web browsers and struggle in edge runtimes, so query from Cloudflare Workers, Vercel Edge, or a browser frontend over standard HTTP.
- **Connectionless scalability.** Short-lived HTTP requests replace persistent TCP connections, so you avoid connection pool exhaustion and scale to thousands of concurrent users.
- **Secure by default.** The API validates JWTs from any authentication provider and respects PostgreSQL [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security) policies, so users only access data they're permitted to see. Use [Managed Better Auth](https://neon.com/docs/auth/overview), or bring your own provider like [Auth0, Clerk, or Firebase](https://neon.com/docs/data-api/custom-authentication-providers).
- **CI/CD integration.** Test integrations in isolated branch environments with the [Neon Create Branch GitHub Action](https://github.com/marketplace/actions/neon-create-branch-github-action), which retrieves branch-specific Data API URLs for your workflows.

**Important: Secure your data before exposing it**

The Data API has no permission layer of its own. Every request is authorized entirely by your PostgreSQL `GRANT` statements and [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security) policies, so a missing or misconfigured policy can expose a table to anyone with the endpoint URL. Before exposing data, follow [Access control & security](https://neon.com/docs/data-api/access-control) and [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial), and run the [Data API advisors](https://neon.com/docs/data-api/database-advisor) to catch misconfigurations.

## PostgREST compatibility

The Neon Data API is fully compatible with [PostgREST](https://postgrest.org/en/stable/). This compatibility allows you to query your database using any standard HTTP client (such as Postman or `cURL`) or integrate easily using client libraries, including [`@neon/neon-js`](https://www.npmjs.com/package/@neon/neon-js) and [`@neon/postgrest-js`](https://www.npmjs.com/package/@neon/postgrest-js).

## Quickstart

- [Get Started](https://neon.com/docs/data-api/get-started): Learn how to enable and use the Neon Data API with step-by-step instructions.
- [Tutorial](https://neon.com/docs/data-api/demo): Explore our demo note-taking app to learn Data API queries with RLS.
- [Neon TypeScript SDK](https://neon.com/docs/reference/javascript-sdk): Complete reference for authentication and database query methods.
- [SQL to REST Converter](https://neon.com/docs/data-api/sql-to-rest): Convert SQL queries into RESTful HTTP requests.
- [Generate Types](https://neon.com/docs/data-api/generate-types): Generate TypeScript types from your database schema for type-safe queries.

--- [Document source](https://neon.com/docs/data-api/sql-to-rest.md) ---

> Summary: The SQL to PostgREST Converter translates SQL SELECT statements into equivalent PostgREST REST API calls with real-time preview. It covers filtering, sorting, pagination, joins, and aggregations. Use it to move from raw SQL to HTTP-based PostgREST queries against a Neon Data API endpoint without manually constructing URL parameters. PostgREST auto-generates a RESTful API from a PostgreSQL schema; this converter makes that translation immediate and explorable.

# SQL to PostgREST Converter

Convert SQL queries to PostgREST API calls with real-time preview

Last updated: 2026-06-05

**Related docs**

- [Getting started with Neon Data API](https://neon.com/docs/data-api/get-started)
- [Building a note-taking app](https://neon.com/docs/data-api/demo)

Enter your SQL query below and see the equivalent PostgREST API calls in real-time.
This tool supports common SELECT statements with filtering, sorting, pagination, joins, and aggregations.

## About PostgREST

PostgREST automatically generates a RESTful API from your PostgreSQL schema.
It supports filtering, sorting, pagination, joins, and many other SQL features through URL parameters.
Learn more about PostgREST at [postgrest.org](https://postgrest.org/)

--- [Document source](https://neon.com/docs/data-api/troubleshooting.md) ---

> Summary: Troubleshooting reference for the Neon Data API, with exact error messages, root causes, and fixes. Common failures covered include JWT audience mismatch, missing or expired tokens, neon_superuser permission denied, and PostgreSQL error 42501 on the authenticated role. Also addresses RLS returning unexpected rows, stale schema cache hiding new tables, and OpenAPI spec "Entry not found" errors.

# Data API troubleshooting

Common issues and solutions when using the Neon Data API

Last updated: 2026-10-09

**Related docs**

- [Getting started with Data API](https://neon.com/docs/data-api/get-started)
- [Manage Data API](https://neon.com/docs/data-api/manage)
- [Access control & security](https://neon.com/docs/data-api/access-control)

**Important: Secure your data before exposing it**

The Data API has no permission layer of its own. Every request is authorized entirely by your PostgreSQL `GRANT` statements and [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security) policies, so a missing or misconfigured policy can expose a table to anyone with the endpoint URL. Before exposing data, follow [Access control & security](https://neon.com/docs/data-api/access-control) and [Secure your app with RLS](https://neon.com/docs/guides/rls-tutorial), and run the [Data API advisors](https://neon.com/docs/data-api/database-advisor) to catch misconfigurations.

## Permission denied to create extension "pg_session_jwt"

```bash
Request failed: database CREATE permission is required for neon_superuser
```

### Why this happens

You created your database with a direct SQL query (`CREATE DATABASE foo;`) instead of using the Console UI or Neon API. The Data API requires specific database permissions that aren't automatically granted when you create databases this way.

### Fix

Grant `neon_superuser` permissions to the database you want to enable the Data API for.

```sql
GRANT ALL PRIVILEGES ON DATABASE your_database_name TO neon_superuser;
```

For future databases, create them using the Console UI or Neon API instead of direct SQL. Neon automatically sets up the required permissions when you use these methods.

**Example**

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/${projectId}/branches/${branchId}/databases" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -d '{
    "database": {
      "name": "your_database_name"
    }
  }'
```

## JWT Audience validation failed

If you've configured a **JWT Audience** value in the Data API but your tokens are being rejected, the `aud` claim in your JWT may not match the configured value.

### Fix

1. Decode your JWT token at [jwt.io](https://jwt.io) to inspect the `aud` claim
2. Ensure the `aud` value in your token exactly matches what you've configured in the Data API
3. If your provider doesn't include an `aud` claim, remove the JWT Audience value from your Data API configuration

For more information, see [What is JWT Audience?](https://neon.com/docs/data-api/custom-authentication-providers#what-is-jwt-audience)

## JWT token missing `sub` claim

The JWT token must include the `sub` claim, which identifies the user, to enable Row-Level Security (RLS) policies. Ensure your authentication system includes this claim when generating JWT tokens for the Neon Data API. An example JWT payload with the `sub` claim is shown below:

```json
{
  "iat": 1764502220,
  "createdAt": "2025-11-28T15:01:13.821Z",
  "updatedAt": "2025-11-28T15:01:13.821Z",
  "role": "authenticated",
  "id": "41a5f680-89d2-474d-ae59-e27bfbbbd293",
  "sub": "41a5f680-89d2-474d-ae59-e27bfbbbd293",
  "exp": 1764503120,
  "iss": "https://ep-spring-silence-ad3hu80n.neonauth.c-2.us-east-1.aws.neon.tech",
  "aud": "https://ep-spring-silence-ad3hu80n.neonauth.c-2.us-east-1.aws.neon.tech"
}
```

The `sub` claim in this example: `41a5f680-89d2-474d-ae59-e27bfbbbd293` represents the unique identifier for the authenticated user. This claim is used by your RLS policies to determine which data the user is allowed to access.

## How do I test the Data API without building an app?

If you're using Managed Better Auth, you can use the Auth API reference UI to create test users and obtain JWT tokens for testing with tools like Postman or cURL.

Navigate to your Auth URL with `/reference` appended (for example, `https://ep-example.neonauth.us-east-1.aws.neon.tech/neondb/auth/reference`). You can find your **Auth URL** under **Settings** > **Better Auth** > **Project Info** in the Neon Console. From there, you can:

1. Create a test user with `POST /sign-up/email`.
2. Sign in with `POST /sign-in/email`.
3. Call `GET /get-session` and copy the JWT from the `Set-Auth-Jwt` response header.
4. Use that JWT in your Data API requests.

For step-by-step instructions, see [Testing with Managed Better Auth](https://neon.com/docs/data-api/get-started#testing-with-neon-auth).

## Permission denied for table

```bash
{"code":"42501","detail":null,"hint":null,"message":"permission denied for table your_table_name"}
```

### Why this happens

The role the request runs as doesn't have GRANT permissions on the table. This commonly occurs when:

- The table was created before the Data API was enabled
- The table was created after enabling the Data API, but default privileges weren't applied
- You disabled the "Grant public schema access" option when enabling the Data API
- You're using a custom authentication provider and the token has no `role` claim. The request then runs as the `anonymous` role, which has no table grants by default, so it can't read the table even though `authenticated` can.

### Fix

Grant the `authenticated` role access to the table:

```sql
GRANT SELECT, UPDATE, INSERT, DELETE ON your_table_name TO authenticated;
```

Or grant access to all tables in the schema:

```sql
GRANT SELECT, UPDATE, INSERT, DELETE ON ALL TABLES IN SCHEMA public TO authenticated;

-- Also set default privileges for future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT, UPDATE, INSERT, DELETE ON TABLES TO authenticated;
```

If you use a custom authentication provider, also confirm the token carries a `role` claim that names a granted role. To use the `authenticated` role, issue `"role": "authenticated"`. If the claim names a custom role, see [Custom roles](https://neon.com/docs/data-api/access-control#3-custom-roles) for the grants it needs. See also [Required JWT claims](https://neon.com/docs/data-api/custom-authentication-providers#required-jwt-claims).

## I can see all rows in my table

If authenticated users can see all rows in a table regardless of ownership, Row-Level Security (RLS) is likely disabled on that table.

### Check RLS status

In the Neon Console, go to **Postgres database** > **Data API**. If a table has RLS disabled, you'll see a warning:

> "table_name has RLS disabled. All authenticated users can view all rows in this table(s)."

### Fix

1. Click the **Enable RLS** button in the Console, or run:

   ```sql
   ALTER TABLE your_table_name ENABLE ROW LEVEL SECURITY;
   ```

2. Create a policy to control access. For example, to let users see only their own rows:
   ```sql
   CREATE POLICY "Users see own data" ON your_table_name
     FOR ALL TO authenticated
     USING (auth.user_id() = user_id);
   ```

For more details, see [Row-Level Security](https://neon.com/docs/data-api/access-control#layer-2-row-level-security-rls).

## RLS is enabled but I can't see any rows

If you've enabled RLS but queries return no data, you likely haven't created any policies yet.

### Why this happens

When RLS is enabled on a table, all access is blocked by default until you create policies that grant access. This is a security feature; it ensures data is protected even if you forget to add policies.

### Fix

Create policies that define who can access what data. For example:

```sql
-- Allow users to see their own rows
CREATE POLICY "Users see own data" ON your_table_name
  FOR SELECT TO authenticated
  USING (auth.user_id() = user_id);

-- Allow users to insert their own rows
CREATE POLICY "Users insert own data" ON your_table_name
  FOR INSERT TO authenticated
  WITH CHECK (auth.user_id() = user_id);
```

See [Access control & security](https://neon.com/docs/data-api/access-control) for more examples.

## OpenAPI spec returns "Entry not found"

```bash
{"message":"Entry 'openapi.json' not found"}
```

### Why this happens

The OpenAPI schema feature is disabled in your Data API configuration.

### Fix

1. Go to **Postgres database** > **Data API** in the Neon Console
2. Open the **Settings** tab
3. Enable the **OpenAPI schema** toggle
4. Try your request again

## Can't access OpenAPI spec

If you're getting authentication errors when trying to access the OpenAPI spec, remember that it requires a valid JWT token like any other Data API request.

### Fix

Include the `Authorization` header with a valid JWT:

```bash
curl -X GET 'https://your-data-api-endpoint/rest/v1/openapi.json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN'
```

To get a JWT token for testing, see [Testing with Managed Better Auth](https://neon.com/docs/data-api/get-started#testing-with-neon-auth).

## New table not found or returns empty schema

If you've created a new table but the Data API doesn't recognize it, or the OpenAPI spec doesn't include it, the schema cache may be stale.

### Why this happens

The Data API caches your database schema for performance. When you create or modify tables, the cache doesn't automatically update.

### Fix

1. Go to **Postgres database** > **Data API** in the Neon Console
2. Click the **Refresh schema cache** button
3. Retry your request

You'll need to refresh the schema cache whenever you:

- Create new tables
- Add or remove columns
- Change column types
- Modify table structure

## JWT token has expired

```bash
{"message":"JWT token has expired (exp=...)"}
```

### Why this happens

JWT tokens have a limited lifespan (typically around 15 minutes). Once expired, they can no longer be used to authenticate requests.

### Fix

Sign in again to get a fresh token. If you're using Managed Better Auth, call `POST /sign-in/email` in the Auth API reference UI, then call `GET /get-session` and copy the new JWT from the `Set-Auth-Jwt` response header.

For programmatic token refresh, see your authentication provider's documentation on token renewal.

--- [Document source](https://neon.com/docs/data-types/array.md) ---

> Summary: The Postgres `ARRAY` type stores ordered, typed, multi-dimensional collections in a single column, letting one row hold multiple related values without a join table. Use arrays when a column needs a variable number of same-type elements such as tags, phone numbers, or sales figures, and full normalization adds unnecessary complexity. Topics include 1-based indexing, slicing, `ANY` membership tests, `unnest`, `array_agg`, `array_replace`, `||` concatenation, and GIN index support.

# Postgres Array data type

Manage collections of elements using arrays

Last updated: 2026-06-05

In Postgres, the `ARRAY` data type is used to store and manipulate collections of elements in a single column. An array can have variable length and one or more dimensions, but must hold elements of the same data type. Postgres provides a variety of functions and operators for working with arrays.

Arrays work well for storing multiple related values. For instance, they can store a list of phone numbers for a contact, product categories for an e-commerce item, or even multi-dimensional data for scientific or analytical computations.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

Arrays in Postgres are declared by specifying the element type followed by square brackets. For example,

- `INTEGER[]` defines an array of integers.
- `TEXT[][]` defines a two-dimensional array of text values.
- `NUMERIC[3]` defines an array of three numeric values. However, note that Postgres doesn't enforce the specified size of an array.

Array literals in Postgres are written within curly braces `{}` and separated by commas. For instance,

- An array of integers might look like `{1, 2, 3}`.
- Multidimensional arrays use nested curly braces, like `{{1, 2, 3}, {4, 5, 6}}`.

The `ARRAY` constructor syntax can also be used to create arrays. For example,

- `ARRAY[1, 2, 3]` creates an array of integers.
- `ARRAY[[1, 2, 3], [4, 5, 6]]` creates a two-dimensional array.

## Example usage

Say you're maintaining a product catalog for an online store. The same product may belong to multiple categories. For example, an iPad could be tagged as 'Electronics', 'Computer', or 'Mobile'. In this case, we can use an array to store the categories for each product.

First, let's create a `products` table with some sample data:

```sql
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    categories TEXT[],
    units_sold INTEGER[][]
);

INSERT INTO products (name, categories, units_sold)
VALUES
    ('Laptop', '{"Electronics","Computer","Office"}', '{{3200, 3300, 3400, 3500}, {3600, 3700, 3800, 3900}}'),
    ('Headphones', '{"Electronics","Audio"}', '{{2400, 2500, 2600, 2700}, {2800, 2900, 3000, 3100}}'),
    ('Table', '{"Furniture","Office"}', '{{900, 950, 1000, 1050}, {1100, 1150, 1200, 1250}}'),
    ('Keyboard', '{"Electronics","Accessories"}', '{{4100, 4200, 4300, 4400}, {4500, 4600, 4700, 4800}}');
```

The `units_sold` column is a two-dimensional array that stores the number of units sold for each product. The first dimension represents the year, and the second dimension represents the quarter.

Now, we can access the values in the array column `categories`, and use it in our queries. For example, the query below finds products belonging to the `Electronics` category.

```sql
SELECT name, categories
FROM products
WHERE 'Electronics' = ANY (categories);
```

Note that the `ANY` operator checks if the value specified exists in the array.
This query returns the following result:

```text
| id | name       | categories                      |
|----|------------|---------------------------------|
| 1  | Laptop     | {Electronics, Computer, Office} |
| 2  | Headphones | {Electronics, Audio}            |
| 4  | Keyboard   | {Electronics, Accessories}      |
```

## Other examples

### Indexing arrays

Elements in an array can be accessed by their index. Postgres arrays are 1-based, meaning indexing starts at 1.

For example, to get the first category of each product:

```sql
SELECT name, categories[1] AS first_category
FROM products;
```

This query returns the following result:

```text
| name       | first_category |
|------------|----------------|
| Laptop     | Electronics    |
| Headphones | Electronics    |
| Table      | Furniture      |
| Keyboard   | Electronics    |
```

Multiple elements can be accessed using the `SLICE` operator. For example, to get the first three categories of each product:

```sql
SELECT name, categories[1:3] AS first_three_categories
FROM products;
```

This query returns the following result:

```text
| name       | first_three_categories          |
|------------|---------------------------------|
| Laptop     | {Electronics, Computer, Office} |
| Headphones | {Electronics, Audio}            |
| Table      | {Furniture, Office}             |
| Keyboard   | {Electronics, Accessories}      |
```

Multidimensional arrays can be accessed using multiple indices. For example, to get the number of units sold in the last quarter of the first year for each product, we can use the query:

```sql
SELECT name, units_sold[1][4] AS units_sold_last_quarter
FROM products;
```

This query returns the following:

```text
| name       | units_sold_last_quarter |
|------------|-------------------------|
| Laptop     | 3500                    |
| Headphones | 2700                    |
| Table      | 1050                    |
| Keyboard   | 4400                    |
```

### Modifying arrays

Array values can be modified using functions or by directly indexing into the array. You can change specific elements of an array, add or remove elements, or even replace the entire array.

For example, the query below replaces the `Audio` category across all products with `Sound`.

```sql
UPDATE products
SET categories = array_replace(categories, 'Audio', 'Sound')
WHERE 'Audio' = ANY (categories)
RETURNING *;
```

This query returns the following result:

```text
| id | name       | categories            | units_sold                                   |
|----|------------|-----------------------|----------------------------------------------|
| 2  | Headphones | {Electronics,Sound}   | {{2400,2500,2600,2700},{2800,2900,3000,3100}} |
```

### Array functions and operators

Postgres provides a variety of functions and operators for working with arrays. You can find the full list of functions and operators in the [Postgres documentation](https://neon.com/docs/data-types/array#resources).

We'll look at some commonly used functions below.

**Length of an array**

We can query the number of categories each product has been tagged with:

```sql
SELECT name, array_length(categories, 1) as category_count
FROM products;
```

This query returns the following result:

```text
| name       | category_count |
|------------|----------------|
| Laptop     | 3              |
| Headphones | 3              |
| Table      | 2              |
| Keyboard   | 2              |
```

The `array_length` function returns the length of the array in the specified dimension. In this case, we specified the first dimension, which is the number of categories for each product.

**Expanding an array into rows**

We can use the `unnest` function to expand an array into rows. For example, to get the number of laptops sold in each quarter, we can use the query:

```sql
SELECT name, unnest(units_sold) AS units_sold
FROM products
WHERE name = 'Laptop';
```

This query returns the following result:

```text
| name   | units_sold |
|--------|------------|
| Laptop | 3200       |
| Laptop | 3300       |
| Laptop | 3400       |
| Laptop | 3500       |
| Laptop | 3600       |
| Laptop | 3700       |
| Laptop | 3800       |
| Laptop | 3900       |
```

We could use the output of `unnest` to calculate the total number of units sold for each product; for example:

```sql
WITH table_units AS (
  SELECT name, unnest(units_sold) AS total_units_sold
  FROM products
)
SELECT name, sum(total_units_sold)
FROM table_units
GROUP BY name;
```

This query returns the following result:

```text
| name       | sum   |
|------------|-------|
| Keyboard   | 35600 |
| Table      | 8600  |
| Laptop     | 28400 |
| Headphones | 22000 |
```

**Concatenating arrays**

We can concatenate two arrays using the `||` operator. For example, the query below produces a list of all categories across all products.

```sql
SELECT ARRAY[1,2,3] || ARRAY[4,5] as concatenated_array;
```

This query returns the following result:

```text
| concatenated_array |
|--------------------|
| {1,2,3,4,5}        |
```

**Aggregating values into an array**

We can use the `array_agg` function to produce an array from a set of rows. For example, to get a list of all products that are in the `Electronics` category, we can use the query:

```sql
SELECT array_agg(name) AS product_names
FROM products
WHERE 'Electronics' = ANY (categories);
```

This query returns the following result:

```text
| product_names                |
|------------------------------|
| {Laptop,Headphones,Keyboard} |
```

## Additional considerations

- **Performance and UX**: While arrays provide flexibility, they can be less performant than normalized data structures for large datasets. Compared to a set of rows, arrays can also be more tedious to work with for complex queries.

- **Indexing**: Postgres lets you create indexes on array elements for faster searches. Specifically, an inverted index like `GIN` creates an entry for each element in the array. This allows for fast lookups but can be expensive to maintain for large arrays.

- **No type enforcement**: Postgres supports defining the size of an array or the number of dimensions in the schema. However, Postgres does not enforce these definitions. For example, the query below works successfully:

  ```sql
  CREATE TABLE test_size (
    id SERIAL PRIMARY KEY,
    arr1 INTEGER[3]
  );
  INSERT INTO test_size (arr1)
  VALUES (ARRAY[1,2,3]), (ARRAY[1,2]);
  ```

  It is therefore up to the application to ensure data integrity.

## Resources

- [PostgreSQL documentation - Array Types](https://www.postgresql.org/docs/current/arrays.html)
- [PostgreSQL documentation - Array Functions](https://www.postgresql.org/docs/current/functions-array.html)

--- [Document source](https://neon.com/docs/data-types/boolean.md) ---

> Summary: The Postgres Boolean data type stores three-value logic (TRUE, FALSE, NULL) in a single byte. It accepts multiple text aliases such as t/f, yes/no, on/off, and 1/0. Use this type when columns represent binary states like active/inactive or paid/unpaid, and when filtering with WHERE, branching with CASE, combining with AND/OR/NOT, or aggregating with bool_and() and bool_or(). NULL indicates an unknown state and does not evaluate as FALSE in conditional expressions.

# Postgres Boolean data type

Represent truth values in Postgres

Last updated: 2026-06-05

In Postgres, the Boolean datatype is designed to store truth values. A Boolean column can hold one of three states: `true`, `false`, or `NULL` representing unknown or missing values.

For instance, Boolean values can be used in a dataset to represent the status of an order, whether a user is active, or whether a product is in stock. A Boolean value could also be produced as a result of comparisons or logical operations.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

In SQL statements, Boolean values are represented by the keywords `TRUE`, `FALSE`, and `NULL`. Postgres is flexible and allows for various textual representations of these values:

- `TRUE` can also be represented as `t`, `true`, `y`, `yes`, `on`, `1`.
- `FALSE` can also be represented as `f`, `false`, `n`, `no`, `off`, `0`.

A boolean value is stored as a single byte.

## Example usage

Consider a table of users for a web application. We can add a Boolean column to represent whether a user is active.

The query below creates a `users` table and inserts some sample data:

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username TEXT NOT NULL,
    is_active BOOLEAN,
    has_paid_subscription BOOLEAN
);

INSERT INTO users (username, is_active, has_paid_subscription)
VALUES
    ('alice', TRUE, TRUE),
    ('bob', TRUE, FALSE),
    ('charlie', FALSE, TRUE),
    ('david', NULL, NULL),
    ('eve', FALSE, FALSE);
```

Say we want to find all the users currently active on the website. The `WHERE` clause accepts a Boolean expression, so we can filter down to the rows where the `is_active` column is `TRUE`.

```sql
SELECT *
FROM users
WHERE is_active = TRUE;
```

This query returns the following:

```text
| id | username | is_active | has_paid_subscription |
|----|----------|-----------|-----------------------|
| 1  | alice    | t         | t                     |
| 2  | bob      | t         | f                     |
```

## Other examples

### Conditional logic

Boolean data types are commonly used in conditional statements like `WHERE`, `IF`, and `CASE`. For example, the `CASE` statement is a control flow structure that allows you to perform `IF-THEN-ELSE` logic in SQL.

In the query below, we categorize users based on their activity and account type.

```sql
SELECT username,
    CASE
        WHEN is_active = TRUE AND has_paid_subscription = TRUE THEN 'Active Paid'
        WHEN is_active = TRUE AND has_paid_subscription = FALSE THEN 'Active Free'
        WHEN is_active = FALSE AND has_paid_subscription = TRUE THEN 'Inactive Paid'
        WHEN is_active = FALSE AND has_paid_subscription = FALSE THEN 'Inactive Free'
        ELSE 'Unknown'
    END AS user_status
FROM users;
```

This query returns the following:

```text
| username | user_status   |
|----------|---------------|
| alice    | Active Paid   |
| bob      | Active Free   |
| charlie  | Inactive Paid |
| david    | Unknown       |
| eve      | Inactive Free |
```

### Boolean expressions

Boolean expressions combine multiple boolean values using operators like `AND`, `OR`, and `NOT`. These expressions return boolean values and are crucial in complex SQL queries.

For example, we can use a Boolean expression to find all the users who are active but don't have a paid subscription yet.

```sql
SELECT id, username
FROM users
WHERE is_active = TRUE AND has_paid_subscription = FALSE;
```

This query returns the following:

```text
| id | username |
|----|----------|
| 2  | bob      |
```

### Boolean aggregations

Postgres also supports aggregating over a set of Boolean values, using functions like `bool_and()` and `bool_or()`.

For example, we can query to check that no inactive users have a paid subscription.

```sql
SELECT bool_or(has_paid_subscription) AS inactive_paid_users
FROM users
WHERE is_active = FALSE;
```

This query returns the following:

```text
| inactive_paid_users |
|---------------------|
| t                   |
```

This indicates there is at least one inactive user with an ongoing subscription. We should probably email them a reminder to log in.

### Boolean in join conditions

Booleans can be effectively used in the `JOIN` clause to match rows across tables.

In the query below, we join the `users` table with the table containing contact information to send a promotional email to all active users.

```sql
WITH contacts (user_id, email) AS (
    VALUES
    (1, 'alice@email.com'),
    (2, 'bob@email.com'),
    (3, 'charlie@email.com'),
    (4, 'david@email.com'),
    (5, 'eve@email.com')
)
SELECT u.id, u.username, c.email
FROM users u
JOIN contacts c ON u.id = c.user_id AND u.is_active = TRUE;
```

This query returns the following:

```text
| id | username | email           |
|----|----------|-----------------|
| 1  | alice    | alice@email.com |
| 2  | bob      | bob@email.com   |
```

## Additional considerations

- **NULL**: `NULL` in boolean terms indicates an unknown state, which is neither `TRUE` nor `FALSE`. In conditional statements, `NULL` values will not equate to `FALSE`.
- **Type Casting**: Be mindful when converting Booleans to other data types. For instance, casting a Boolean to an integer results in `1` for `TRUE` and `0` for `FALSE`. This behavior is useful in aggregations or mathematical operations.
- **Indexing**: Using Booleans in indexing might not always be efficient, especially if the distribution of true and false values is uneven.

## Resources

- [PostgreSQL Boolean Type documentation](https://www.postgresql.org/docs/current/datatype-boolean.html)

--- [Document source](https://neon.com/docs/data-types/character.md) ---

> Summary: Postgres character types `CHAR(n)`, `VARCHAR(n)`, and `TEXT` store fixed-length, length-limited, and unlimited strings respectively. `CHAR(n)` space-pads shorter values; `TEXT` has no length restriction. Use `VARCHAR(n)` or `CHAR(n)` when input validation against a maximum length matters, and `TEXT` for large variable-length content such as blog posts or product descriptions.

# Postgres Character data types

Work with text data in Postgres

Last updated: 2026-06-05

In Postgres, character data types are used to store strings. There are three primary character types: `CHAR(n)`, `VARCHAR(n)`, and `TEXT`. `CHAR(n)` and `VARCHAR(n)` types are suitable for strings with known or limited length; for example, usernames and email addresses. Whereas `TEXT` is ideal for storing large variable-length strings, such as blog posts or product descriptions.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

- `VARCHAR(n)` allows storing any string up to `n` characters.
- `CHAR(n)` stores strings in a fixed length. If a string is shorter than `n`, it is padded with spaces.
- `TEXT` has no length limit, making it ideal for large texts.

Storing strings requires one or a few bytes of overhead over the actual string length. `CHAR` and `VARCHAR` columns need an extra check at input time to ensure the string length is within the specified limit. Most Postgres string functions take and return `TEXT` values.

String values are represented as literals in single quotes. For example, `'hello'` is a string literal.

## Example usage

Consider a database tracking data for a library. We have books with titles and optional descriptions. Titles are usually of a similar length, so they can be modeled with a `CHAR` type. However, descriptions can vary significantly in length, so they are assigned the `TEXT` type.

The query below creates a `books` table and inserts some sample data:

```sql
CREATE TABLE books (
    id SERIAL PRIMARY KEY,
    title CHAR(50),
    description TEXT
);

INSERT INTO books (title, description)
VALUES
    ('Postgres Guide', 'A comprehensive guide to PostgreSQL.'),
    ('Data Modeling Essentials', NULL),
    ('SQL for Professionals', 'An in-depth look at advanced SQL techniques.');
```

To find books with descriptions, you can use the following query:

```sql
SELECT title
FROM books
WHERE description IS NOT NULL;
```

This query returns the following:

```text
                       title
----------------------------------------------------
 Postgres Guide
 SQL for Professionals
```

## Other examples

### String functions and operators

Postgres provides various functions and operators for manipulating character data. For instance, the `||` operator concatenates strings.

The query below joins the title and description columns together:

```sql
SELECT title || ' - ' || description AS full_description
FROM books;
```

This query returns the following:

```text
                           full_description
----------------------------------------------------------------------
 Postgres Guide - A comprehensive guide to PostgreSQL.

 SQL for Professionals - An in-depth look at advanced SQL techniques.
```

For more string functions and operators, see [PostgreSQL String Functions and Operators](https://www.postgresql.org/docs/current/functions-string.html).

### Pattern matching

With `VARCHAR` and `TEXT`, you can use pattern matching to find specific text. The `LIKE` operator is commonly used for this purpose.

```sql
SELECT id, title
FROM books
WHERE title LIKE 'Data%';
```

This returns books whose titles start with "Data".

```text
 id |                       title
----+----------------------------------------------------
  2 | Data Modeling Essentials
```

## Additional considerations

- **Performance**: There are no significant performance differences between any of the types. Using fixed/limited length types, `CHAR` and `VARCHAR` can be useful for data validation.
- **Function Support**: All character types support a wide range of functions and operators for string manipulation and pattern matching.

## Resources

- [PostgreSQL Character Types documentation](https://www.postgresql.org/docs/current/datatype-character.html)

--- [Document source](https://neon.com/docs/data-types/date-and-time.md) ---

> Summary: Postgres date and time types (DATE, TIME, TIMESTAMP, TIMESTAMPTZ, and INTERVAL) store moments, times of day, and durations with or without time zone awareness, at 1-microsecond resolution. Use this page to choose between TIMESTAMP and TIMESTAMPTZ, understand how Postgres converts timezone-aware input to UTC internally, and write queries that filter date ranges or compute durations. Topics include arithmetic operators, the OVERLAPS predicate, and functions such as EXTRACT and AGE.

# Postgres Date and Time data types

Work with date and time values in Postgres

Last updated: 2026-06-05

Postgres offers a rich set of native data types for storing date and time values. Both moment-in-time and interval data can be stored, and Postgres provides a variety of functions to query and manipulate them.

Modeling date and time enables precise timestamping, duration calculations, and is essential in various use cases related to finance, logistics, events logging, and so on.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

There are 5 primary date/time types in Postgres:

- `DATE` - represents a date value, stored as 4 bytes. Resolution is 1 day.
- `TIME` - represents a time-of-day value, stored as 8 bytes. Resolution is 1 microsecond.
- `TIMESTAMP` - represents a combined date and time value, stored as 8 bytes. Resolution is 1 microsecond.
- `TIMESTAMPTZ` - represents a combined date and time value, along with time zone information, stored as 8 bytes. Resolution is 1 microsecond. It is stored internally as a UTC value, but is displayed in the timezone set by the client.
- `INTERVAL` - represents a duration of time, stored as 16 bytes. Resolution is 1 microsecond. Optionally, you can restrict the set of values stored to a larger unit of time (for example, `INTERVAL MONTH`).

Date/time values are specified as string literals. Postgres accepts most of the standard datetime formats. For example:

```sql
SELECT
    '2024-01-01'::DATE AS date_value,
    '09:00:00'::TIME AS time_value,
    '2024-01-01 09:00:00'::TIMESTAMP AS timestamp_value,
    '2024-01-01 09:00:00-05'::TIMESTAMPTZ AS timestamptz_value,
    '1 month'::INTERVAL AS interval_value;
```

There are also some special date/time literals that can be used in queries. Some of them are:

- `epoch` - represents the Unix epoch (1970-01-01 00:00:00 UTC)
- `infinity` - represents an infinite timestamp, greater than all other timestamps
- `-infinity` - represents an infinite timestamp, smaller than all other timestamps
- `now` - represents the current timestamp

## Example usage

Consider a conference event management system that tracks schedules for planned sessions.

The query below creates a table to store all the sessions and inserts some sample data.

```sql
CREATE TABLE conference_sessions (
    session_id SERIAL PRIMARY KEY,
    session_title TEXT NOT NULL,
    session_date DATE NOT NULL,
    start_time TIMESTAMPTZ NOT NULL,
    planned_duration INTERVAL NOT NULL,
    finish_time TIMESTAMPTZ
);

INSERT INTO conference_sessions (session_title, session_date, start_time, planned_duration, finish_time)
VALUES
    ('Keynote Speech', '2024-05-15', '2024-05-15 09:00:00+00', '2 hours', '2024-05-15 11:30:00+00'),
    ('Data Science Workshop', '2024-05-16', '2024-05-16 11:00:00+00', '3 hours', '2024-05-16 14:00:00+00'),
    ('AI Panel Discussion', '2024-05-17', '2024-05-17 14:00:00+00', '1.5 hours', '2024-05-17 15:20:00+00');
```

**Filtering on date/time values**

You can find all sessions scheduled for a specific date using a query like this:

```sql
SELECT session_title, start_time
FROM conference_sessions
WHERE session_date = '2024-05-16';
```

The query returns the following values:

```text
      session_title    |       start_time
-----------------------+------------------------
 Data Science Workshop | 2024-05-16 11:00:00+00
```

**Arithmetic operations with date/time**

You can write a query like this to find sessions that went over the planned duration:

```sql
SELECT session_title, planned_duration, finish_time - start_time AS actual_duration
FROM conference_sessions
WHERE finish_time - start_time > planned_duration;
```

The query returns the following values:

```text
 session_title  | planned_duration | actual_duration
----------------+------------------+-----------------
 Keynote Speech | 02:00:00         | 02:30:00
```

**Aggregating date/time values**

You can write a query like this to find the average duration of all sessions:

```sql
SELECT AVG(finish_time - start_time) AS avg_duration
FROM conference_sessions;
```

The query returns the following value:

```text
 avg_duration
--------------
 02:16:40
```

## Other examples

### Date and time functions

Postgres offers a variety of functions for manipulating date and time values, such as `EXTRACT`, `AGE`, `OVERLAPS`, and more.

For example, you can run this query to see if the times for any two sessions overlapped:

```sql
SELECT
    a.session_title AS session_a,
    b.session_title AS session_b,
    a.start_time as session_a_start,
    b.start_time as session_b_start
FROM conference_sessions a, conference_sessions b
WHERE a.session_id < b.session_id
AND (a.start_time, a.planned_duration) OVERLAPS (b.start_time, b.planned_duration);
```

This query returns no rows, indicating that there are no overlapping sessions.

### Handling time zones

Postgres supports adding time zone information to both time-of-day (`TIME WITH TIME ZONE`) and moment-in-time (`TIMESTAMP WITH TIME ZONE` / `TIMESTAMPTZ`) values.

- If you use a time zone unaware type (for example, `TIME` or `TIMESTAMP`), Postgres ignores any time zone information provided in the input string.
- If you use a time-zone-aware type (for example, `TIMETZ` or `TIMESTAMPTZ`), Postgres converts the input string to UTC and stores it internally. It then displays the value in the `current time zone` set for the session.

To illustrate this, you can create a table with both time-zone aware and unaware columns, and insert a sample row:

```sql
CREATE TABLE time_example (
    ts TIMESTAMP,
    tstz_utc TIMESTAMPTZ,
    tstz_pst TIMESTAMPTZ
);

INSERT INTO time_example (ts, tstz_utc, tstz_pst)
VALUES
    ('2024-01-01 09:00:00-08', '2024-01-01 09:00:00+00', '2024-01-01 09:00:00-08');
```

You can then check the current timezone set for the session:

```sql
SHOW timezone;
-- Returns 'GMT' (same as UTC)
```

Now, if you query the table:

```sql
SELECT * FROM time_example;
```

This query returns the following:

```text
         ts          |        tstz_utc        |        tstz_pst
---------------------+------------------------+------------------------
 2024-01-01 09:00:00 | 2024-01-01 09:00:00+00 | 2024-01-01 17:00:00+00
```

Postgres ignores the timezone information for the first column and returns the second and third columns in the UTC timezone.

## Additional considerations

- **Indexing**: Date/time values often involve range queries and sorting. Indexing date/time columns can thus significantly improve query performance.
- **Daylight Saving Time**: Working with time zones can be tricky, especially when dealing with daylight savings time. For additional details, refer to the [PostgreSQL Date/Time Types documentation](https://www.postgresql.org/docs/current/datatype-datetime.html).

## Resources

- [PostgreSQL documentation - Date/Time Types](https://www.postgresql.org/docs/current/datatype-datetime.html)
- [PostgreSQL documentation - Date/Time Functions](https://www.postgresql.org/docs/current/functions-datetime.html)

--- [Document source](https://neon.com/docs/data-types/decimal.md) ---

> Summary: The Postgres DECIMAL and NUMERIC types store exact numeric values using user-defined precision and scale. They are the right choice for financial and scientific data where floating-point rounding errors are unacceptable. Specify DECIMAL(precision, scale) to control digit count and fractional places, or omit both to store any precision exactly up to the implementation limit. Unlike REAL or DOUBLE PRECISION, DECIMAL/NUMERIC arithmetic never approximates, though exact-precision calculations are slower than floating-point operations.

# Postgres Decimal data types

Work with exact numerical values in Postgres

Last updated: 2026-06-05

In Postgres, decimal data types are used to represent numbers with arbitrarily high precision. They are crucial in financial applications and scientific computation, where exact precision is required for numerical calculations.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

Postgres provides a single decimal/numeric type referred to as `DECIMAL` or `NUMERIC`. It offers user-defined precision and can represent numbers exactly up to a certain number of digits.

The syntax for defining a decimal column is `DECIMAL(precision, scale)` or `NUMERIC(precision, scale)`, where:

- `precision` is the total count of significant digits in the number (both to the left and right of the decimal point).
- `scale` is the count of decimal digits in the fractional part.

Declaring a column as `NUMERIC` without specifying precision and scale, stores numbers of any precision exactly (up to the implementation limit).

We illustrate the behavior of `NUMERIC` with the following example:

```sql
SELECT 1234.56::NUMERIC(10, 4) AS num_A,
       1234.56::NUMERIC(10, 1) AS num_B,
       1234.56789::NUMERIC AS num_C;
```

This query yields the following output:

```text
num_a     | num_b  |   num_c
----------+--------+------------
1234.5600 | 1234.6 | 1234.56789
```

The number `1234.56` is represented exactly in all three cases. However, the `NUMERIC(10, 4)` type rounds the number to 4 decimal places, while `NUMERIC(10, 1)` rounds to 1 decimal place. When no precision and scale are specified, the number is stored exactly.

## Example usage

Consider a financial application managing user portfolios. Here, `DECIMAL` is ideal for storing currency values to avoid rounding errors. For example, representing the price of a stock or the total value of a portfolio.

The following SQL creates a `portfolios` table:

```sql
CREATE TABLE portfolios (
    portfolio_id SERIAL PRIMARY KEY,
    user_id INTEGER NOT NULL,
    stock_symbol TEXT NOT NULL,
    shares_owned DECIMAL(10, 4),
    price_per_share DECIMAL(10, 2)
);

INSERT INTO portfolios (user_id, stock_symbol, shares_owned, price_per_share)
VALUES
    (101, 'AAPL', 150.1234, 145.67),
    (102, 'MSFT', 200.000, 214.53);
```

## Other examples

### Arithmetic operations

Postgres allows various arithmetic operations on decimal types. These operations maintain precision and are critical in contexts where rounding errors could be costly.

For example, the following query calculates the total value of each stock holding:

```sql
SELECT price_per_share * shares_owned AS total_value
FROM portfolios;
```

This query yields the following output:

```text
total_value
--------------
21868.475678
42906.000000
```

This query calculates the total value of each stock holding with precise decimal representation.

## Differences from floating-point

It's important to differentiate `DECIMAL`/`NUMERIC` from floating-point types (`REAL`, `DOUBLE PRECISION`):

- **Precision**: `DECIMAL`/`NUMERIC` types maintain exact precision, while floating-point types are approximate and can introduce rounding errors.
- **Performance**: Operations on `DECIMAL`/`NUMERIC` types are generally slower than floating-point types due to the precision and complexity of calculations.

## Additional considerations

- **Range and Precision**: Always define `DECIMAL`/`NUMERIC` with an appropriate range and precision based on the application's requirements. Overestimating precision can lead to unnecessary storage and performance overhead.

## Resources

- [PostgreSQL documentation - Numeric Types](https://www.postgresql.org/docs/current/datatype-numeric.html)

--- [Document source](https://neon.com/docs/data-types/floating-point.md) ---

> Summary: Postgres floating-point types `REAL` (4 bytes, ~6 decimal digits) and `DOUBLE PRECISION` (8 bytes, ~15 decimal digits) store approximate numeric values for scientific, sensor, and statistical data. Use `DOUBLE PRECISION` when rounding error accumulation matters, or switch to `NUMERIC`/`DECIMAL` for exact values such as currency. Both types support special values `infinity`, `-infinity`, and `NaN`, but are subject to rounding errors that can compound across operations.

# Postgres Floating-point data types

Work with float values in Postgres

Last updated: 2026-06-05

In Postgres, floating point data types are used to represent numbers that might have a fractional part. These types are essential for situations where precision is key, such as scientific calculations, financial computations, and more.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

Postgres supports two primary floating-point types:

1. `REAL`: Also known as "single precision," `REAL` occupies 4 bytes of storage. It offers a precision of at least 6 decimal digits.
2. `DOUBLE PRECISION`: Known as "double precision," this type uses 8 bytes of storage and provides a precision of at least 15 decimal digits.

Both types are approximate numeric types, meaning they may have rounding errors and are not recommended for storing exact decimal values, like monetary data.

## Example usage

For a weather data application, `REAL` might be used for storing temperature readings, where extreme precision isn't critical, as in the following example:

```sql
CREATE TABLE weather_data (
    reading_id SERIAL PRIMARY KEY,
    temperature REAL NOT NULL,
    humidity REAL NOT NULL
);

INSERT INTO weather_data (temperature, humidity)
VALUES
    (23.5, 60.2),
    (20.1, 65.3),
    (22.8, 58.1);
```

For more complex scientific calculations involving extensive decimal data, `DOUBLE PRECISION` would be more appropriate, as in this example:

```sql
CREATE TABLE scientific_data (
    measurement_id SERIAL PRIMARY KEY,
    precise_temperature DOUBLE PRECISION NOT NULL,
    co2_levels DOUBLE PRECISION NOT NULL,
    measurement_time TIMESTAMP WITHOUT TIME ZONE NOT NULL
);

INSERT INTO scientific_data (precise_temperature, co2_levels, measurement_time)
VALUES
    (23.456789, 415.123456789, '2024-02-03 10:00:00'),
    (20.123456, 417.123789012, '2024-02-03 11:00:00'),
    (22.789012, 418.456123789, '2024-02-03 12:00:00');
```

## Other examples

### Arithmetic operations

Floating-point types support the standard arithmetic operations: addition, subtraction, multiplication, division, and modulus. However, operations like division might lead to potential rounding errors and precision loss.

```sql
SELECT 10.0 / 3.0;
```

This query yields `3.3333333333333333`, which does not represent the quantity `10 / 3` exactly, but rather rounded to the nearest representable value. When performing a series of operations, these rounding errors can accumulate and lead to significant precision loss.

### Special Floating-point values

Postgres floating-point types can represent special values like `'infinity'`, `'-infinity'`, and `'NaN'` (not a number). These values can be useful in certain mathematical or scientific computations.

Consider a table named `calculations`, which might store the results of various scientific computations, including temperature changes, pressure levels, and calculation errors that could potentially result in `'infinity'`, `'-infinity'`, or `'NaN'` values:

```sql
CREATE TABLE calculations (
    calculation_id SERIAL PRIMARY KEY,
    temperature_change DOUBLE PRECISION,
    pressure_level DOUBLE PRECISION,
    error_margin DOUBLE PRECISION
);

-- Inserting special floating-point values
INSERT INTO calculations (temperature_change, pressure_level, error_margin)
VALUES
    ('infinity', 101.325, 0.001), -- An example where temperature change is beyond measurable scale
    ('-infinity', 0.0, 0.0001),   -- An example with a negative infinite value
    ('NaN', 101.325, 'NaN');      -- Examples of undefined results or unmeasurable quantities
```

Notice that you must use single quotes to wrap these values as shown above.

## Additional considerations

- **Accuracy and rounding**: Be aware of rounding errors. For applications requiring exact decimal representation (like financial calculations), consider using `NUMERIC` or `DECIMAL` types instead.
- **Performance**: While `DOUBLE PRECISION` offers more precision, it might not be as performant due to the larger storage size.

## Resources

- [PostgreSQL documentation - Numeric Types](https://www.postgresql.org/docs/current/datatype-numeric.html)

--- [Document source](https://neon.com/docs/data-types/integer.md) ---

> Summary: Postgres integer types `SMALLINT` (2 bytes), `INTEGER` (4 bytes), and `BIGINT` (8 bytes) store whole numbers without a fractional component and do not support unsigned values. Use `SMALLINT` for small-range columns, `INTEGER` for general-purpose identifiers and counters, and `BIGINT` when values exceed the `INTEGER` limit of roughly 2.1 billion. Topics include integer arithmetic truncation and the auto-incrementing `SERIAL`, `SMALLSERIAL`, and `BIGSERIAL` pseudo-types for primary keys.

# Postgres Integer data types

Work with integers in Postgres

Last updated: 2026-06-05

In Postgres, integer data types are used for storing numerical values without a fractional component. They are useful as identifiers, counters, and many other common data modeling tasks. Postgres offers multiple integer types, catering to different ranges of values and storage sizes.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

Postgres supports three primary integer types. Choosing the appropriate integer type depends on the range of data expected.

1. `SMALLINT`: A small-range integer, occupying 2 bytes of storage. It's useful for columns with a small range of values.
2. `INTEGER`: The standard integer type, using 4 bytes of storage. It's the most commonly used since it balances storage/performance efficiency and range capacity.
3. `BIGINT`: A large-range integer, taking up 8 bytes. It's used when the range of `INTEGER` is insufficient.

Note that Postgres doesn't support unsigned integers. All integer types can store both positive and negative values.

## Example usage

Consider a database for a small online bookstore. Here, `SMALLINT` could be used for storing the number of copies of a book in stock, while `INTEGER` would be appropriate for a unique identifier for each book.

The query below creates a `books` table with these columns:

```sql
CREATE TABLE books (
    book_id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    copies_in_stock SMALLINT
);

INSERT INTO books (book_id, title, copies_in_stock)
VALUES
    (1, 'War and Peach', 50),
    (2, 'The Great Gatsby', 20),
    (3, 'The Catcher in the Rye', 100);
```

## Other examples

### Integer operations

Postgres supports various arithmetic operations on integer types, including addition, subtraction, multiplication, and division.

Note that the division of integers does not yield a fractional result; it truncates the result to an integer.

```sql
SELECT 10 / 4; -- Yields 2, not 2.5
```

## Sequences and auto-Increment

Postgres also provides `SERIAL`, which is a pseudo-type for creating auto-incrementing integers, often used for primary keys. It's effectively an `INTEGER` that automatically increments with each new row insertion.

There is also `BIGSERIAL` and `SMALLSERIAL` for auto-incrementing `BIGINT` and `SMALLINT` columns, respectively.

For example, we can create an `orders` table with an auto-incrementing `order_id` column:

```sql
CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    order_details TEXT
);

INSERT INTO orders (order_details)
VALUES ('Order 1'), ('Order 2'), ('Order 3');
RETURNING *;
```

This query returns the following:

```text
 order_id | order_details
----------+---------------
        1 | Order 1
        2 | Order 2
        3 | Order 3
```

The `order_id` column gets a unique integer value for each new order.

## Additional considerations

- **Data integrity**: Integer types strictly store numerical values. Attempting to insert non-numeric data, or a value outside the range of that particular type will result in an error.
- **Performance**: Choosing the correct integer type (`SMALLINT`, `INTEGER`, `BIGINT`) based on the expected value range can optimize storage efficiency and performance.

## Resources

- [PostgreSQL documentation - Numeric Types](https://www.postgresql.org/docs/current/datatype-numeric.html)

--- [Document source](https://neon.com/docs/data-types/introduction.md) ---

> Summary: Postgres data types hub for Neon, linking to dedicated guides for array, boolean, date and time, character, JSON, decimal, floating point, integer, tsvector, and UUID types. Use this page to find the right type guide when choosing column types or troubleshooting type-specific behavior in a Neon Postgres database.

# Postgres data types

Last updated: 2026-06-05

Get started with commonly-used Postgres data types with Neon's data type guides. For other data types that Postgres supports, visit the official Postgres [Data Types](https://www.postgresql.org/docs/current/datatype.html) documentation.

- [Array](https://neon.com/docs/data-types/array): Manage collections of elements using arrays
- [Boolean](https://neon.com/docs/data-types/boolean): Represent truth values in Postgres
- [Date and time](https://neon.com/docs/data-types/date-and-time): Work with date and time values in Postgres
- [Character](https://neon.com/docs/data-types/character): Work with text data in Postgres
- [JSON](https://neon.com/docs/data-types/json): Model JSON data in Postgres
- [Decimal](https://neon.com/docs/data-types/decimal): Work with exact numerical values in Postgres
- [Floating point](https://neon.com/docs/data-types/floating-point): Work with float values in Postgres
- [Integer](https://neon.com/docs/data-types/integer): Work with integers in Postgres
- [Tsvector](https://neon.com/docs/data-types/tsvector): Optimize full-text search in Postgres with the tsvector data type
- [UUID](https://neon.com/docs/data-types/uuid): Work with UUIDs in Postgres

--- [Document source](https://neon.com/docs/data-types/json.md) ---

> Summary: Postgres JSON and JSONB data types store semi-structured, document-like data without schema changes. JSONB uses a binary format that supports GIN indexing, containment queries with @>, and in-place field updates via jsonb_set; JSON preserves exact input whitespace and key order. Choose JSONB for most workloads where query and index performance matter; use JSON only when preserving exact input format is required. Topics include storage differences, the ->, ->>, and @> operators, nested field extraction, and GIN index creation.

# Postgres JSON data types

Model JSON data in Postgres

Last updated: 2026-06-05

Postgres supports JSON (JavaScript Object Notation) data types, providing a flexible way to store and manipulate semi-structured data. The two types are `JSON` and `JSONB`. The functions work similarly, but there are trade-offs related to data ingestion and querying performance.

`JSON` and `JSONB` are ideal for storing data that doesn't fit neatly into a traditional relational model, since new fields can be added without altering the database schema. They also work well for modeling document-like data typically stored in NoSQL databases.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

### JSON

- The `JSON` data type stores `JSON` data in text format.
- It preserves an exact copy of the original `JSON` input, including whitespace and ordering of object keys.
- An advantage over storing `JSON` data in a `TEXT` column is that Postgres validates the `JSON` data at ingestion time, ensuring it is well-formed.

### JSONB

- The `JSONB` (JSON Binary) data type stores `JSON` data in a decomposed binary format.
- Unlike `JSON`, `JSONB` does not preserve whitespace or the order of object keys. For duplicate keys, only the last value is stored.
- `JSONB` is more efficient for querying, as it doesn't require re-parsing the `JSON` data every time it is accessed.

`JSON` values can be created from string literals by casting. For example:

```sql
SELECT
    '{"name": "Alice", "age": 30}'::JSON as col_json,
    '[1, 2, "foo", null]'::JSONB as col_jsonb;
```

This query returns the following:

```text
           col_json           |      col_jsonb
------------------------------+---------------------
 {"name": "Alice", "age": 30} | [1, 2, "foo", null]
```

## Example usage

Say you're managing user profiles for a social media application. Profile data is semi-structured, with a set of fields common to all users, while other fields are optional and may vary across users. `JSONB` is a good fit for this use case.

Using the query below, we can create a table to store user profiles:

```sql
CREATE TABLE user_profiles (
    id SERIAL PRIMARY KEY,
    profile JSONB NOT NULL
);

INSERT INTO user_profiles (profile)
VALUES
    ('{"name": "Alice", "age": 30, "interests": ["music", "travel"], "settings": {"privacy": "public", "notifications": true, "theme": "light"}}'),
    ('{"name": "Bob", "age": 25, "interests": ["photography", "cooking"], "settings": {"privacy": "private", "notifications": false}, "city": "NYC"}'),
    ('{"name": "Charlie", "interests": ["music", "cooking"], "settings": {"privacy": "private", "notifications": true, "language": "English"}}');
```

With `JSONB`, we can directly query and manipulate elements within the `JSON` structure. For example, to find all the users interested in music, we can run the query:

```sql
SELECT
    id,
    profile -> 'name' as name,
    profile -> 'interests' as interests
FROM user_profiles
WHERE profile @> '{"interests":["music"]}'::JSONB;
```

The `@>` operator checks if the left `JSONB` operand contains the right `JSONB` operand as a subset. While the `->` operator extracts the value of a `JSON` key as a `JSON` value.

This query returns the following:

```text
 id |   name    |      interests
----+-----------+----------------------
  1 | "Alice"   | ["music", "travel"]
  3 | "Charlie" | ["music", "cooking"]
```

Note that the `name` values returned are still in `JSON` format. To extract the value as text, we can use the `->>` operator instead:

```sql
SELECT
    id,
    profile ->> 'name' as name
FROM user_profiles;
```

This query returns the following:

```text
 id |  name
----+---------
  1 | Alice
  2 | Bob
  3 | Charlie
```

## JSON functions and operators

Postgres implements several functions and operators for querying and manipulating `JSON` data, including these functions described in the Neon documentation:

- [json_array_elements](https://neon.com/docs/functions/json_array_elements)
- [jsonb_array_elements](https://neon.com/docs/functions/jsonb_array_elements)
- [json_build_object](https://neon.com/docs/functions/json_build_object)
- [json_each](https://neon.com/docs/functions/json_each)
- [json_extract_path](https://neon.com/docs/functions/json_extract_path)
- [json_extract_path_text](https://neon.com/docs/functions/json_extract_path_text)
- [json_object](https://neon.com/docs/functions/json_object)
- [json_populate_record](https://neon.com/docs/functions/json_populate_record)
- [json_to_record](https://neon.com/docs/functions/json_to_record)

For additional `JSON` operators and functions, refer to the [official PostgreSQL documentation](https://www.postgresql.org/docs/current/functions-json.html)

### Nested data

Postgres supports storing nested `JSON` values. For example, in the user profile table, the `settings` field is a `JSON` object itself. The nested values can be extracted by chaining the `->` operator.

For example, to access the `privacy` setting for all users, you can run the query:

```sql
SELECT
    id,
    profile -> 'name' as name,
    profile -> 'settings' ->> 'privacy' as privacy
FROM user_profiles;
```

This query returns the following:

```text
 id |   name    | privacy
----+-----------+---------
  1 | "Alice"   | public
  2 | "Bob"     | private
  3 | "Charlie" | private
```

### Modifying JSONB data

The `JSONB` type supports updating individual fields. For example, the query below sets the `privacy` setting for all public users to `friends-only`:

```sql
UPDATE user_profiles
SET profile = jsonb_set(profile, '{settings, privacy}', '"friends-only"')
WHERE profile -> 'settings' ->> 'privacy' = 'public';
```

`jsonb_set` is a Postgres function that takes a `JSONB` value, a path to the field to update, and the new value. The path is specified as an array of keys.

Field updates are not supported for the `JSON` type.

### Indexing JSONB data

Postgres supports GIN (Generalized Inverted Index) indexes for `JSONB` data, which can improve query performance significantly.

```sql
CREATE INDEX idxgin ON user_profiles USING GIN (profile);
```

This makes evaluation of `key-exists (?)` and `containment (@>)` operators efficient. For example, the query to fetch all users who have music as an interest can use this index.

```sql
SELECT *
FROM user_profiles
WHERE profile @> '{"interests":["music"]}';
```

## Additional considerations

### JSON vs JSONB

`JSONB` is the recommended data type for storing `JSON` data in Postgres for a few reasons.

- **Indexing**: `JSONB` allows for the creation of GIN (Generalized Inverted Index) indexes, which makes searching within `JSONB` columns faster.
- **Performance**: `JSONB` binary format is more efficient for querying and manipulating, as it doesn't require re-parsing the `JSON` data for each access. It also supports in-place updates to individual fields.
- **Data integrity**: `JSONB` ensures that keys in an object are unique.

There might be some legacy use cases where preserving the exact format of the `JSON` data is important. In such cases, the `JSON` data type can be used.

## Resources

- [PostgreSQL documentation - JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)
- [PostgreSQL documentation - JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/data-types/tsvector.md) ---

> Summary: The `tsvector` Postgres data type stores a document as a sorted list of normalized lexemes with positions and optional A-D weights, enabling fast full-text search via GIN indexes and the `@@` match operator. Use `to_tsvector('english', text)` instead of a raw cast when language-aware stemming and stop-word removal are required before indexing. Topics include tsvector syntax, multilingual configurations, GIN index setup, and relevance ranking with `ts_rank` and `to_tsquery`.

# Postgres tsvector data type

Optimize full-text search in Postgres with the tsvector data type

Last updated: 2026-06-05

`tsvector` is a specialized Postgres data type designed for full-text search operations. It represents a document in a form optimized for text search, where each word is reduced to its root form (lexeme) and stored with information about its position and importance.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

A `tsvector` value is a sorted list of distinct lexemes, which are words that have been normalized to merge different variants of the same word. Each lexeme can be followed by position(s) and/or weight(s).

The general syntax for a `tsvector` is:

```
'word1':1,3 'word2':2A ...
```

Where:

- `word1`, `word2`, etc., are the lexemes
- `1`, `3`, etc. are integers indicating the position of the word in the document
- positions can sometimes be followed by a letter to indicate a weight ('A', 'B', 'C' or 'D'), like `2A`. The default weight is 'D'.

For example:

- `'a':1A 'cat':2 'sat':3 'on':4 'the':5 'mat':6`

When a document is cast to `tsvector`, it doesn't perform any normalization and just splits the text into lexemes. To normalize the text, you can use the `to_tsvector` function with a specific text search configuration. For example:

```sql
SELECT
    'The quick brown fox jumps over the lazy dog.'::tsvector as colA,
    to_tsvector('english', 'The quick brown fox jumps over the lazy dog.') as colB;
```

This query produces the following output. The function `to_tsvector()` tokenizes the input document and computes the normalized lexemes based on the specified text search configuration (in this case, 'english'). The output is a `tsvector` with the normalized lexemes and their positions.

```text
                              cola                              |                         colb
----------------------------------------------------------------+-------------------------------------------------------
 'The' 'brown' 'dog.' 'fox' 'jumps' 'lazy' 'over' 'quick' 'the' | 'brown':3 'dog':9 'fox':4 'jump':5 'lazi':8 'quick':2
(1 row)
```

## Example usage

Consider a scenario where we're building a blog platform and want to implement full-text search for articles. We'll use `tsvector` to store the searchable content of each article.

The query below creates a table and inserts some sample blog data:

```sql
CREATE TABLE blog_posts (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    search_vector tsvector
);

INSERT INTO blog_posts (title, content)
VALUES
    ('PostgreSQL Full-Text Search', 'PostgreSQL offers powerful full-text search capabilities using tsvector and tsquery.'),
    ('Indexing in Databases', 'Proper indexing is crucial for database performance. It can significantly speed up query execution.'),
    ('ACID Properties', 'ACID (Atomicity, Consistency, Isolation, Durability) properties ensure reliable processing of database transactions.');

UPDATE blog_posts
SET search_vector = to_tsvector('english', title || ' ' || content);

CREATE INDEX idx_search_vector ON blog_posts USING GIN (search_vector);
```

To search for blog posts containing specific words, we can use the match operator `@@`, with a `tsquery` search expression:

```sql
SELECT title
FROM blog_posts
WHERE search_vector @@ to_tsquery('english', 'database & performance');
```

This query returns the following output:

```text
         title
-----------------------
 Indexing in Databases
(1 row)
```

## Other examples

### Use different text search configurations with `tsvector`

Postgres supports text search configurations for multiple languages. Here's an example using the 'spanish' configuration:

```sql
CREATE TABLE product_reviews (
    id SERIAL PRIMARY KEY,
    product_name TEXT NOT NULL,
    review TEXT NOT NULL,
    search_vector tsvector
);

INSERT INTO product_reviews (product_name, review)
VALUES
    ('Laptop XYZ', 'Este laptop es muy rápido y tiene una excelente batería.'),
    ('Smartphone ABC', 'La cámara del teléfono es increíble, pero la batería no dura mucho.'),
    ('Tablet 123', 'La tablet es ligera y fácil de usar, perfecta para leer libros.');

UPDATE product_reviews
SET search_vector = to_tsvector('spanish', product_name || ' ' || review);

SELECT product_name
FROM product_reviews
WHERE search_vector @@ to_tsquery('spanish', 'batería & (excelente | dura)');
```

This query returns the following output:

```text
  product_name
----------------
 Laptop XYZ
 Smartphone ABC
(2 rows)
```

### Rank the search results from a `tsvector` column

We can use the `ts_rank` function to rank search results based on relevance:

```sql
CREATE TABLE news_articles (
    id SERIAL PRIMARY KEY,
    headline TEXT NOT NULL,
    body TEXT NOT NULL,
    search_vector tsvector
);

INSERT INTO news_articles (headline, body)
VALUES
    ('Climate Change Summit Concludes', 'World leaders agreed on new measures to combat global warming at the climate summit.'),
    ('New Study on Climate Change', 'Scientists publish groundbreaking research on the effects of climate change on biodiversity.'),
    ('Tech Giant Announces Green Initiative', 'Major tech company pledges to be carbon neutral by 2030 in fight against climate change.');

UPDATE news_articles
SET search_vector = to_tsvector('english', headline || ' ' || body);

SELECT headline, ts_rank(search_vector, query) AS rank
FROM news_articles, to_tsquery('english', 'climate & change') query
WHERE search_vector @@ query
ORDER BY rank DESC;
```

This query returns the following output:

```text
               headline                |    rank
---------------------------------------+------------
 New Study on Climate Change           |  0.2532141
 Climate Change Summit Concludes       | 0.10645772
 Tech Giant Announces Green Initiative | 0.09910322
(3 rows)
```

All the articles were related to climate change, but the first article was ranked higher due to the higher relevance for the search terms.

## Additional considerations

- **Performance**: While `tsvector` enables fast full-text search, creating and updating `tsvector` columns can be computationally expensive. Consider using triggers or background jobs to update `tsvector` columns asynchronously.
- **Storage**: `tsvector` columns can significantly increase the size of your database. Monitor your database size and consider using partial indexes if full-text search is only needed for a subset of your data.
- **Language support**: PostgreSQL supports many languages out of the box, but you may need to install additional dictionaries for some languages.
- **Stemming and stop words**: The text search configuration determines how words are stemmed and which words are ignored as stop words. Choose the appropriate configuration for your use case.

## Resources

- [PostgreSQL Full Text Search documentation](https://www.postgresql.org/docs/current/textsearch.html)
- [PostgreSQL tsvector data type documentation](https://www.postgresql.org/docs/current/datatype-textsearch.html)

--- [Document source](https://neon.com/docs/data-types/uuid.md) ---

> Summary: The Postgres UUID data type stores 128-bit globally unique identifiers as 32 hex digits in 8-4-4-4-12 hyphen-separated format. Generate them natively with gen_random_uuid() or via the uuid-ossp extension's uuid_generate_v4(). UUIDs suit distributed primary keys and columns where sequential IDs would leak record counts or expose enumeration attacks. Topics include storage layout, UUID primary key patterns, the gen_random_uuid() vs uuid-ossp tradeoff, and indexing considerations.

# Postgres UUID data type

Work with UUIDs in Postgres

Last updated: 2026-06-05

`UUID` stands for `Universally Unique Identifier`. A `UUID` is a 128-bit value used to ensure global uniqueness across tables and databases.

In Postgres, the UUID data type is ideal for assigning unique identifiers to entities such as users, orders, or products. They're especially useful in distributed systems where unique keys need to be generated independently.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Storage and syntax

UUIDs are stored as 128-bit values, represented as a sequence of hexadecimal digits. They are typically formatted in five groups, of sizes 8, 4, 4, 4 and 12, separated by hyphens. For example:

- `123e4567-e89b-12d3-a456-426655440000`, or
- `a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11`

Postgres accepts UUID values in the above format, while also allowing uppercase letters and missing hyphen separators. You can also generate them using functions like `gen_random_uuid()` which is available natively in Postgres, or the `uuid_generate_v4()` function which requires the `uuid-ossp` extension.

## Example usage

Consider a scenario where we track user sessions in a web application. UUIDs are commonly used to identify sessions due to their uniqueness.

The query below creates a table and inserts some sample session data:

```sql
CREATE TABLE sessions (
    session_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id INT,
    activity TEXT
);

INSERT INTO sessions (user_id, activity)
VALUES
    (1, 'login'),
    (2, 'view'),
    (1, 'view'),
    (1, 'logout'),
    (3, 'write')
RETURNING *;
```

This query returns the following:

```text
| session_id                             | user_id | activity |
|----------------------------------------|---------|----------|
| b148aab2-5a03-4d96-a119-c32fc8a4bfaa   | 1       | login    |
| 72be2042-0072-4858-b090-cb27c31e44b1   | 2       | view     |
| e817b187-aba3-4b0d-a34e-a1d82319627c   | 1       | view     |
| a940a06a-a8d4-4e90-a90c-d8fa096e620f   | 1       | logout   |
| df56fbf8-1fcd-408a-a1c6-4e18e35b8349   | 3       | write    |
```

To retrieve a specific session, we can query by its UUID:

```sql
SELECT *
FROM sessions
WHERE session_id = 'e817b187-aba3-4b0d-a34e-a1d82319627c';
```

This query returns the following:

```text
| session_id                             | user_id | activity |
|----------------------------------------|---------|----------|
| e817b187-aba3-4b0d-a34e-a1d82319627c   | 1       | view     |
```

## Other examples

### Using UUID column as primary key

Using UUIDs as primary keys is common since the likelihood of the same UUID value being generated twice is very small. This is helpful in distributed systems or when merging data from different sources.

For example, we can create a table to store products and use a UUID column as the primary key.

```sql
CREATE TABLE products (
    product_id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name TEXT NOT NULL,
    price NUMERIC
);

INSERT INTO products (name, price)
VALUES
    ('Apple', 1.99),
    ('Banana', 2.99),
    ('Orange', 3.99)
RETURNING *;
```

This query returns the following:

```text
| product_id                             | name   | price |
|----------------------------------------|--------|-------|
| ce3b39d8-1bae-4ed3-b4db-2a74658f0d85   | Apple  | 1.99  |
| 14c18af1-a352-45e6-976e-3c194bdc6ee8   | Banana | 2.99  |
| f303866d-d08a-48a7-81c3-c30486149d87   | Orange | 3.99  |
```

### Avoiding data leakage

In systems where data security is a concern, using non-sequential IDs like UUIDs can help obscure the total number of records, preventing potential information leaks. This is in contrast to the sequential IDs provided by the `SERIAL` data type, which can inadvertently reveal information about the number of users, orders, etc.

For example, the query below creates a table that tracks users of an API with some sample data:

```sql
CREATE TABLE api_users (
    serial_id SERIAL PRIMARY KEY,
    uuid_id UUID DEFAULT gen_random_uuid(),
    username TEXT NOT NULL
);

INSERT INTO api_users (username)
VALUES
    ('user1'),
    ('user2'),
    ('user3')
RETURNING *;
```

This query returns the following:

```text
| serial_id | uuid_id                              | username |
|-----------|--------------------------------------|----------|
| 1         | e5836695-f2d0-47f4-86e8-d0dbaae4031a | user1    |
| 2         | d22ec671-806a-4db2-8c60-f0f8754f9b7b | user2    |
| 3         | 108eb93a-071e-4407-8b78-a73aabd9e803 | user3    |
```

Notice that the `serial_id` column hints at the number of rows already present in the table.

## Additional considerations

- **Randomness and uniqueness**: UUIDs are designed to be globally unique, but there's an extremely small probability of generating a duplicate UUID. If you're automatically generating UUIDs at insertion, and a duplicate UUID is generated, the insertion will fail. In the rare event that a collision occurs, applications that generate UUIDs should implement a retry mechanism.
- **Performance and indexing**: UUIDs are larger than traditional integer IDs, requiring more storage space. Index structures on UUID columns therefore consume more storage as well. However, in terms of performance for read-heavy workloads, leveraging indexed UUID columns for filtering or sorting can significantly improve query performance. In this context, you have to evaluate the tradeoff between storage efficiency and query performance.
- **Readability**: UUIDs are not human-readable, which can make debugging or manual inspection of data more challenging.

## Resources

- [PostgreSQL UUID Type documentation](https://www.postgresql.org/docs/current/datatype-uuid.html)

--- [Document source](https://neon.com/docs/extensions/btree_gin.md) ---

> Summary: The `btree_gin` extension adds GIN operator classes for scalar B-tree-indexable types such as integers, timestamps, text, and numeric. This lets a single composite GIN index cover both those types and native GIN types like arrays and JSONB. Use it when queries filter on mixed column types and a unified index would outperform separate B-tree and GIN indexes. GIN indexes built with `btree_gin` carry higher write overhead than B-tree indexes, making the extension best suited for read-heavy, multi-column filter workloads.

# The btree_gin extension

Combine GIN and B-tree indexing capabilities for efficient multi-column queries in Postgres

Last updated: 2026-06-05

The `btree_gin` extension for Postgres provides a specialized set of **GIN operator classes** that allow common, "B-tree-like" data types to be included in **GIN indexes**. Use it when you need **multicolumn GIN indexes** that combine complex data types (like arrays or JSONB) with simpler types such as integers, timestamps, or text. Ultimately, `btree_gin` extends GIN to a broader range of indexing needs, optimizing queries across diverse data structures.

Consider a scenario where an application needs to query blog posts based on a set of `tags` (an array) and a `publication_date` (a timestamp). The `btree_gin` extension allows for a single, optimized index to service both conditions, potentially offering significant performance gains over alternative indexing strategies.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `btree_gin` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS btree_gin;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## `btree_gin`: Bridging index types

A common challenge arises when queries require filtering on both B-tree friendly columns (for example, `status TEXT`, `created_at TIMESTAMP`) and GIN-friendly columns (for example, `attributes JSONB`, `tags TEXT[]`). While Postgres can use separate B-tree and GIN indexes and combine their results, this is not always the most performant approach.

The `btree_gin` extension addresses this by providing GIN **operator classes** for many standard B-tree-indexable data types. These operator classes instruct the GIN indexing mechanism on how to handle these scalar types as if they were native GIN-indexable items.

For instance, with `btree_gin`, a single GIN index can be defined on `(order_date TIMESTAMP, product_tags TEXT[])`.

```sql
-- Create the table
CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    order_date TIMESTAMP,
    product_tags TEXT[]
);

CREATE INDEX idx_orders_date_tags
ON orders
USING GIN (order_date, product_tags);
```

Postgres can then use this composite index to optimize queries filtering on both `order_date` and `product_tags` simultaneously, such as:

```sql
SELECT * FROM orders
WHERE order_date >= '2025-04-01' AND order_date < '2025-05-01'
  AND product_tags @> ARRAY['electronics'];
```

Without `btree_gin`, `order_date` could not be directly included in a GIN index in this manner.

## Usage scenarios

Let's explore some practical examples of how `btree_gin` can be applied to real-world scenarios, particularly in the context of filtering and querying data efficiently.

### Filtering posts by tags and publication date

Consider a `posts` table where queries frequently target posts with specific tags published within a defined timeframe.

#### Table schema

```sql
CREATE TABLE posts (
    post_id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    tags TEXT[],             -- GIN-friendly array
    published_at TIMESTAMPTZ -- B-tree friendly timestamp
);

INSERT INTO posts (title, tags, published_at) VALUES
('Postgres Performance Tuning', '{"postgres", "performance", "database"}', '2025-03-15 10:30:00Z'),
('Advanced Indexing Strategies', '{"sql", "indexes", "optimization"}', '2025-04-02 14:00:00Z'),
('Working with JSONB in Postgres', '{"postgres", "jsonb", "nosql"}', '2025-04-20 09:15:00Z');
```

#### `btree_gin` index creation

A composite GIN index is created to cover both `tags` and `published_at`.

```sql
CREATE INDEX idx_posts_tags_published
ON posts
USING GIN (tags, published_at);
```

#### Example query

Retrieve posts tagged 'postgres' published in April 2025.

```sql
SELECT title, tags, published_at
FROM posts
WHERE tags @> '{"postgres"}'
  AND published_at >= '2025-04-01 00:00:00Z'
  AND published_at < '2025-05-01 00:00:00Z';
```

The `idx_posts_tags_published` index enables Postgres to efficiently process both the array containment (`@>`) and timestamp range conditions.

### E-commerce product filtering by attributes and price

In an e-commerce context, users often filter products based on dynamic attributes (for example, stored in `JSONB`) and price ranges.

#### Table schema

```sql
CREATE TABLE products (
    product_id SERIAL PRIMARY KEY,
    name TEXT,
    attributes JSONB,       -- GIN-friendly JSONB (for example, {"color": "red", "material": "cotton"})
    price NUMERIC(10, 2)    -- B-tree friendly numeric
);

INSERT INTO products (name, attributes, price) VALUES
('Men''s Cotton T-Shirt', '{"color": "blue", "size": "M", "material": "cotton"}', 29.99),
('Women''s Wool Sweater', '{"color": "red", "size": "S", "material": "wool"}', 89.50),
('Unisex Denim Jeans', '{"color": "black", "size": "32/30", "material": "denim"}', 59.95);
```

#### `btree_gin` index creation

```sql
CREATE INDEX idx_products_attributes_price
ON products
USING GIN (attributes, price);
```

#### Example query

Find products made of "cotton" with a price below $50.

```sql
SELECT name, attributes, price
FROM products
WHERE attributes @> '{"material": "cotton"}' AND price < 50.00;
```

The `idx_products_attributes_price` index handles both the JSONB containment check and the numeric inequality efficiently.

## Important considerations and Best practices

- **Write performance impact:** GIN indexes, due to their structure, generally incur a higher cost for `INSERT`, `UPDATE`, and `DELETE` operations compared to B-tree indexes. This should be a consideration for write-intensive workloads.
- **Index storage size:** GIN indexes can be larger on disk than their B-tree counterparts for equivalent data.
- **Query selectivity:** The benefits of `btree_gin` are most pronounced when queries filter on multiple columns included in the index, and the combined predicate is reasonably selective.
- **Dedicated B-tree indexes:** For queries filtering _solely_ on a B-tree-indexable column, a dedicated B-tree index on that column typically offers superior performance. `btree_gin` is primarily for _combined_ criteria.

## Conclusion

The `btree_gin` extension provides a valuable mechanism for optimizing complex queries in Postgres that involve filters across both GIN-indexable and B-tree-indexable column types. By enabling the creation of unified multi-column GIN indexes, `btree_gin` can lead to more efficient query plans, reduced execution times, and a simplified indexing landscape for specific workloads.

## Resources

- [PostgreSQL `btree_gin` documentation](https://www.Postgres.org/docs/current/btree-gin.html)
- [PostgreSQL Indexes](https://neon.com/postgresql/postgresql-indexes)
- [PostgreSQL Index Types](https://neon.com/postgresql/postgresql-indexes/postgresql-index-types)

--- [Document source](https://neon.com/docs/extensions/btree_gist.md) ---

> Summary: The `btree_gist` extension adds GiST operator classes for standard B-tree data types such as integers, text, timestamps, and dates. This lets Postgres build multicolumn GiST indexes that mix GiST-native types like geometry or range types with scalar columns. Use it when queries must filter on both a spatial or range column and a scalar column, or when building exclusion constraints that combine B-tree types with range overlap operators. Without `btree_gist`, scalar types cannot participate in a GiST index, so overlap exclusion constraints cannot be enforced at the database level.

# The btree_gist extension

Combine GiST and B-tree indexing capabilities for efficient multi-column queries and constraints

Last updated: 2026-06-05

The `btree_gist` extension for Postgres provides a specialized set of **GiST operator classes**. These allow common, "B-tree-like" data types (such as integers, text, or timestamps) to be included in **GiST (Generalized Search Tree) indexes**. This is especially useful when you need to create **multicolumn GiST indexes** that combine GiST-native types (like geometric data or range types) with these simpler B-tree types. `btree_gist` also plays a key role in defining **exclusion constraints** involving standard data types.

For example, if an application needs to query for events happening within a specific geographic area (a `geometry` type) _and_ within a certain `event_time` (a timestamp), `btree_gist` allows a single, optimized GiST index to cover both conditions.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `btree_gist` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS btree_gist;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## `btree_gist`: Combining index strengths

When working with geospatial data or range types, GiST indexes are often the go-to choice due to their ability to efficiently handle complex data structures. However, many applications also rely on standard B-tree-friendly columns for filtering and sorting.

More often than not, queries need to filter on both GiST-friendly columns (for example, `location GEOMETRY`, `booking_period TSTZRANGE`) and B-tree friendly columns (for example, `status TEXT`, `created_at TIMESTAMPTZ`, `item_id INTEGER`). While Postgres can use separate indexes, a combined index can be more efficient.

The `btree_gist` extension does this by providing GiST **operator classes** for many standard B-tree-indexable data types. These operator classes tell the GiST indexing mechanism how to handle these scalar types within its framework.

For instance, with `btree_gist` (and often `postgis` for geometry types), a single GiST index can be defined on `(event_location GEOMETRY, event_timestamp TIMESTAMPTZ)`.

**Example:**

```sql
-- Ensure postgis extension is enabled
CREATE EXTENSION IF NOT EXISTS postgis; -- For GEOMETRY type

-- Create the table
CREATE TABLE scheduled_events (
    event_id SERIAL PRIMARY KEY,
    event_location GEOMETRY(Point, 4326), -- A GiST-friendly type
    event_timestamp TIMESTAMPTZ           -- A B-tree-friendly type
);

CREATE INDEX idx_events_location_time
ON scheduled_events
USING GIST (event_location, event_timestamp);
```

This composite index can then be used by Postgres to optimize queries filtering on both `event_location` and `event_timestamp` simultaneously:

```sql
SELECT * FROM scheduled_events
WHERE ST_DWithin(event_location, ST_SetSRID(ST_MakePoint(-73.985, 40.758), 4326)::geography, 1000) -- Within 1km
  AND event_timestamp >= '2025-03-01 00:00:00Z'
  AND event_timestamp < '2025-04-01 00:00:00Z';
```

Without `btree_gist`, `event_timestamp` could not be directly included in the GiST index alongside `event_location` in this straightforward manner.

## Usage scenarios

Let's explore practical examples where `btree_gist` is beneficial.

### Filtering events by location and time

Consider a `map_events` table where queries often search for events in a specific geographical bounding box and within a particular date range.

#### Table schema

```sql
-- Ensure PostGIS is enabled
-- CREATE EXTENSION IF NOT EXISTS postgis;

CREATE TABLE map_events (
    id SERIAL PRIMARY KEY,
    name TEXT,
    geom GEOMETRY(Point, 4326), -- GiST-friendly spatial data
    event_date DATE             -- B-tree friendly date
);

INSERT INTO map_events (name, geom, event_date) VALUES
('Music Festival', ST_SetSRID(ST_MakePoint(-0.1276, 51.5074), 4326), '2025-02-20'),
('Art Exhibition', ST_SetSRID(ST_MakePoint(-0.1200, 51.5000), 4326), '2025-02-22'),
('Tech Conference', ST_SetSRID(ST_MakePoint(2.3522, 48.8566), 4326), '2025-03-05');
```

#### `btree_gist` index creation

A composite GiST index covers both `geom` and `event_date`.

```sql
CREATE INDEX idx_map_events_geom_date
ON map_events
USING GIST (geom, event_date);
```

#### Example query

Find events in London (approximated by a bounding box) occurring in February 2025:

```sql
SELECT name, event_date
FROM map_events
WHERE geom && ST_MakeEnvelope(-0.5, 51.25, 0.3, 51.7, 4326) -- Approximate bounding box for London
  AND event_date >= '2025-02-01'
  AND event_date < '2025-03-01';
```

The `idx_map_events_geom_date` index allows Postgres to efficiently process both the spatial overlap (`&&`) and the date range conditions.

### Enforcing exclusion constraints for room bookings

`btree_gist` is essential for creating exclusion constraints that involve B-tree types alongside GiST-native types like ranges.

Room bookings are a classic example: you need to ensure no two bookings overlap for the same room.

#### Table schema

```sql
CREATE TABLE room_bookings (
    booking_id SERIAL PRIMARY KEY,
    room_id INTEGER,            -- B-tree friendly integer
    booking_period TSTZRANGE    -- GiST-friendly range type
);
```

#### `btree_gist` index creation for exclusion constraint

The exclusion constraint uses a GiST index. `room_id WITH =` will use `btree_gist`.

```sql
ALTER TABLE room_bookings
ADD CONSTRAINT no_overlapping_bookings
EXCLUDE USING GIST (room_id WITH =, booking_period WITH &&);
```

The `WITH =` operator for `room_id` uses `btree_gist`, and `WITH &&` (overlap) is native to range types with GiST.

#### Example operations

```sql
-- Successful booking
INSERT INTO room_bookings (room_id, booking_period)
VALUES (101, '[2025-04-10 14:00, 2025-04-10 16:00)');

-- Attempting to book the same room for an overlapping period
INSERT INTO room_bookings (room_id, booking_period)
VALUES (101, '[2025-04-10 15:00, 2025-04-10 17:00)');
-- This will fail: ERROR:  conflicting key value violates exclusion constraint "no_overlapping_bookings"

-- Booking a different room for an overlapping period is fine
INSERT INTO room_bookings (room_id, booking_period)
VALUES (102, '[2025-04-10 15:00, 2025-04-10 17:00)');
```

## Important considerations and Best practices

- **Use case specificity:** `btree_gist` is not a general replacement for B-tree indexes. It excels when combining B-tree types with GiST-specific types/features in one index or for exclusion constraints.
- **Performance:** For queries filtering _solely_ on a B-tree-indexable column (for example, `WHERE status = 'active'`), a dedicated B-tree index is typically faster and more space-efficient.
- **Index size and write overhead:** GiST indexes can be larger and have slightly higher write overhead (for `INSERT`/`UPDATE`/`DELETE`) than B-tree indexes.

## Conclusion

The `btree_gist` extension provides a vital bridge, allowing standard B-tree-indexable data types to be included in GiST indexes. This enables efficient multi-column queries across diverse data types (for example, spatial and temporal) and supports sophisticated exclusion constraints.

## Resources

- [PostgreSQL `btree_gist` documentation](https://www.postgresql.org/docs/current/btree-gist.html)
- [PostgreSQL Indexes](https://neon.com/postgresql/postgresql-indexes)
- [How and when to use btree_gist](https://neon.com/blog/btree_gist)
- [PostgreSQL Index Types](https://neon.com/postgresql/postgresql-indexes/postgresql-index-types)
- [`postgis` extension](https://neon.com/docs/extensions/postgis)

--- [Document source](https://neon.com/docs/extensions/citext.md) ---

> Summary: The `citext` extension adds a native case-insensitive text data type to Postgres. Columns using it match regardless of capitalization without calling `lower()` on every query. Use it when you need case-insensitive uniqueness or lookups on text columns and want to avoid manually wrapping comparisons in `lower()` or `upper()`. The extension supports btree indexing, regex functions, and casting back to `text` for case-sensitive operations.

# The citext Extension

Use the citext extension to handle case-insensitive data in Postgres

Last updated: 2026-06-05

The `citext` extension in Postgres provides a case-insensitive data type for text. Use it for columns where case shouldn't matter, like usernames or email addresses.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers the `citext` extension: its setup, usage, and practical examples in Postgres. For datasets where consistent text formatting isn't guaranteed, case-insensitive queries can streamline operations.

**Note:** The `citext` extension is an open-source module for Postgres. It can be easily installed and used in any Postgres database. This guide provides steps for installation and usage, with further details available in the [Postgres Documentation](https://postgresql.org/docs/current/citext.html).

## Enable the `citext` extension

You can enable `citext` by running the following `CREATE EXTENSION` statement in the Neon **SQL Editor** or from a client such as `psql` that is connected to Neon.

```sql
CREATE EXTENSION IF NOT EXISTS citext;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Example usage

**Creating a table with citext**

Consider a user registration system where the user's email should be unique, regardless of case.

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(255) UNIQUE,
    email CITEXT UNIQUE
);
```

In this table, the `email` field is of type `citext`, ensuring that email addresses are treated case-insensitively.

**Inserting data**

Insert data as you would normally. The `citext` type automatically handles case-insensitivity.

```sql
INSERT INTO users (username, email)
VALUES
  ('johnsmith', 'JohnSmith@email.com'),
  ('AliceSmith', 'ALICE@example.com'),
  ('BobJohnson', 'Bob@example.com'),
  ('EveAnderson', 'eve@example.com');
```

**Case-insensitive querying**

Queries against `citext` columns are inherently case-insensitive. Effectively, it calls the `lower()` function on both strings when comparing two values.

```sql
SELECT * FROM users WHERE email = 'johnsmith@email.com';
```

This query returns the following:

```text
| id | username   | email                  |
|----|------------|------------------------|
| 1  | johnsmith  | JohnSmith@email.com    |
```

The email address matched even though the case was different.

## More examples

**Using citext with regex functions**

The `citext` extension can be used with regular expressions and other string-matching functions, which perform string matching in a case-insensitive manner.

For example, the query below finds users whose email addresses start with 'AL'.

```sql
SELECT * FROM users WHERE regexp_match(email, '^AL', 'i') IS NOT NULL;
```

This query returns the following:

```text
| id | username    | email              |
|----|-------------|--------------------|
| 1  | AliceSmith  | ALICE@example.com  |
```

**Using citext data as TEXT**

If you do want case-sensitive behavior, you can cast `citext` data to `text` and use it as shown here:

Query:

```sql
SELECT * FROM users WHERE email::text LIKE '%EVE%';
```

This query will only return results if it finds a user with an email address containing 'EVE'.

## Benefits of Using citext

- **Query simplicity**: No need for functions like `lower()` or `upper()` to perform case-insensitive comparisons.
- **Data integrity**: Helps maintain data consistency, especially in user input scenarios.

## Performance considerations

### Indexing with citext

Indexing `citext` fields is similar to indexing regular text fields. However, it's important to note that the index will be case-insensitive.

```sql
CREATE INDEX idx_email ON users USING btree(email);
```

This index will improve the performance of queries involving the `email` field. Depending on whether the more frequent use case is case-sensitive or case-insensitive, you can choose to index the `citext` field or cast it to `text` and index that.

### Comparison with `lower()` function

`Citext` internally does an operation similar to `lower()` on both sides of the comparison, so there is not a big performance jump. However, using `citext` ensures consistent case-insensitive behavior across queries without the need for repeatedly applying the `lower()` function, which makes errors less likely.

## Conclusion

The `citext` extension helps manage case-insensitivity in text data within Postgres. It simplifies queries and ensures consistency in data handling. This guide provides an overview of using `citext`, including creating and querying case-insensitive fields.

## Resources

- [PostgreSQL citext documentation](https://www.postgresql.org/docs/current/citext.html)

--- [Document source](https://neon.com/docs/extensions/cube.md) ---

> Summary: The cube extension adds a native `cube` data type to Postgres for storing and querying n-dimensional points and hyperrectangles as 64-bit floating-point values. Use it when you need containment checks, overlap detection, or distance calculations (Euclidean, Manhattan, Chebyshev) across multiple numeric dimensions such as GIS coordinates or scientific parameter spaces. GiST indexes on `cube` columns enable fast nearest-neighbor ORDER BY queries using the `<->`, `<#>`, and `<=>` distance operators.

# The cube extension

Store and query multidimensional points and cubes in Postgres

Last updated: 2026-06-05

The cube extension for Postgres provides a specialized data type for representing multidimensional "cubes", which are, more generally, n-dimensional boxes or points. This makes it useful for applications dealing with multidimensional data, such as geographic information systems (GIS) storing coordinates (latitude, longitude, altitude), business intelligence (BI) applications analyzing data across various dimensions, or scientific computing tasks involving vector operations.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

The cube extension allows you to define points and hyperrectangles in n-dimensional space and perform various operations like distance calculations, containment checks, and overlap detection.

## Enable the `cube` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS cube;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Understanding `cube` data

The `cube` extension primarily revolves around the `cube` data type and a set of operators and functions to work with it. The `cube` data type can represent both n-dimensional points (cubes with zero volume) and n-dimensional cubes (defined by two opposite corners).

### Multidimensional points

A point is a cube where the "lower-left" and "upper-right" corners are identical.
Syntax:

- `cube(ARRAY[x1, x2, ..., xn])`
- `'(x1, x2, ..., xn)'::cube`

  ```sql
  -- A 3-dimensional point
  SELECT cube(ARRAY[1.0, 2.5, 3.0]) AS point_from_array;
  -- Result: (1,2.5,3)

  SELECT '(1.0, 2.5, 3.0)'::cube AS point_from_string;
  -- Result: (1,2.5,3)
  ```

### Multidimensional cubes (ranges/boxes)

A cube is defined by two diagonally opposite corner points. The order of corners doesn't matter on input, `cube` internally stores them in a canonical "lower-left" to "upper-right" form.
Syntax:

- `cube(ARRAY[ll_x1, ..., ll_xn], ARRAY[ur_x1, ..., ur_xn])`
- `'(ll_x1, ..., ll_xn), (ur_x1, ..., ur_xn)'::cube`

  ```sql
  -- A 2-dimensional cube (a rectangle)
  SELECT cube(ARRAY[1.0, 1.0], ARRAY[5.0, 5.0]) AS cube_from_arrays;
  -- Result: (1,1),(5,5)

  SELECT ' (1.0, 1.0), (5.0, 5.0) '::cube AS cube_from_string; -- Whitespace is ignored
  -- Result: (1,1),(5,5)

  -- A 3-dimensional cube
  SELECT cube(ARRAY[0,0,0], ARRAY[1,1,1]) AS unit_cube_3d;
  -- Result: (0,0,0),(1,1,1)
  ```

Cube values are stored internally as 64-bit floating-point numbers.

## Example usage

Let's consider a table to store information about various items, including their spatial bounding boxes or specific point locations.

### Creating a table with a `cube` column

```sql
CREATE TABLE items (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    location_or_bounds CUBE
);
```

### Inserting `cube` data

```sql
INSERT INTO items (name, location_or_bounds) VALUES
    ('Sensor A', '(10.0, 20.5, 5.0)'),            -- A 3D point location
    ('Warehouse Zone 1', '(0,0),(50,100)'),       -- A 2D rectangular area
    ('Temperature Range', '(-10.0), (40.0)'),     -- A 1D cube/interval
    ('Sensor B', '(-10.0, 40.0)'),                -- A 2D point
    ('Pressure Sensor', cube(array[15.2, 30.1, 2.3])), -- Another 3D point
    ('Shipping Box X', cube(array[0,0,0], array[1,2,1.5])); -- A 3D box
```

### Querying `cube` data

The `cube` extension provides a rich set of operators and functions for querying.

**Direct creation in SELECT statements**

You can create `cube` values on the fly:

```sql
SELECT cube(array[1,2,3]) AS point_3d, cube(0,10) AS interval_1d;
```

Output:

```text
| point_3d    | interval_1d   |
|-------------|---------------|
| (1, 2, 3)   | (0),(10)      |
```

**Containment and overlap operators**

- `@>`: Contains (does the left cube contain the right cube?)
- `<@`: Is contained by (is the left cube contained by the right cube?)
- `&&`: Overlaps (do the two cubes have any common points?)

```sql
-- Find items within a specific 2D region '(5,5),(60,120)'
SELECT name, location_or_bounds
FROM items
WHERE location_or_bounds <@ '(5,5),(60,120)';
-- No rows returned (as no item is fully contained in this region)

-- Find 2D/3D regions that contain the point (12.0, 25.0)
SELECT name, location_or_bounds
FROM items
WHERE location_or_bounds @> '(12.0, 25.0)';
-- Warehouse Zone 1 | (0,0),(50,100)

-- Find items whose bounds overlap with the 3D cube '(0,0,0),(10,10,10)'
SELECT name, location_or_bounds
FROM items
WHERE location_or_bounds && '(0,0,0),(10,10,10)';
-- Warehouse Zone 1 | (0,0),(50,100)
-- Temperature Range | (-10),(40)
-- Shipping Box X | (0,0,0),(1,2,1.5)
```

> Notice that 'Sensor B' is excluded from the last query's results, while 'Temperature Range' (a 1D interval) is included. 'Sensor B' (a 2D point) does not overlap the 3D query cube, but 'Temperature Range' does when its dimensionality is considered.

**Distance operators**

The `cube` extension provides several distance metrics:

- `<->`: Euclidean distance
- `<#>`: Taxicab (Manhattan or L-1) distance
- `<=>`: Chebyshev (L-infinity or maximum coordinate) distance

**Note: Distance metrics**

| Distance  | Description                                                                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Euclidean | The straight-line distance between two points in n-dimensional space.                                                                               |
| Taxicab   | The sum of the absolute differences of their coordinates. This is the distance a taxi would travel on a grid-like street layout.                    |
| Chebyshev | The maximum absolute difference between the coordinates of the two points. This is useful in chess-like movements where diagonal moves are allowed. |

The `cube_distance(cube1, cube2)` function is equivalent to the `<->` operator.

```sql
SELECT cube_distance('(0,0)'::cube, '(3,4)'::cube) AS euclidean_dist;
-- Output: 5 (sqrt(3^2 + 4^2))

SELECT '(0,0)'::cube <-> '(3,4)'::cube AS euclidean_dist;
-- Output: 5 (sqrt(3^2 + 4^2))

SELECT '(0,0,0)'::cube <#> '(1,2,3)'::cube AS taxicab_dist;
-- Output: 6 (1+2+3)

SELECT '(0,0)'::cube <=> '(3,-4)'::cube AS chebyshev_dist;
-- Output: 4 (max(|3-0|, |-4-0|))
```

**Note: Cube Creation: String vs. Function**

Be mindful of how you create `cube` values, as it impacts their dimensionality:

- `'(x,y)'::cube` (string casting) creates a **2D point** `(x,y)`.
- `cube(x,y)` (function call) creates a **1D interval** from `x` to `y`, effectively `(x),(y)`.

This difference will affect functions like `cube_distance`. For example:

- `cube_distance('(0,0)'::cube, '(3,4)'::cube)` is 5 (distance between 2D points).
- `cube_distance(cube(0,0), cube(3,4))` is 3 (distance between 1D point `(0)` and 1D interval `(3),(4)`).
- `cube(0,0)` is a 1D point as it has both lower and upper bounds at 0.

To create an n-dimensional point using the `cube()` function, pass an array: `cube(array[x,y,...])`.

**Coordinate extraction operators**

- `-> integer`: Extracts the N-th coordinate of a point. Returns `NULL` if the cube is not a point or has fewer than N dimensions.
- `~> integer`: Extracts coordinate from a cube's representation.
  - `N = 2*k - 1`: Lower bound of the k-th dimension.
  - `N = 2*k`: Upper bound of the k-th dimension.

```sql
-- Extract coordinates from Sensor A's location (a point)
SELECT
    location_or_bounds -> 1 AS x,
    location_or_bounds -> 2 AS y,
    location_or_bounds -> 3 AS z
FROM items WHERE name = 'Sensor A';
-- x  |    y | z
-- 10 | 20.5 | 5

-- Extract bounds of Warehouse Zone 1 (a 2D cube)
-- x_low (dim 1, lower): ~> 1
-- x_high (dim 1, upper): ~> 2
-- y_low (dim 2, lower): ~> 3
-- y_high (dim 2, upper): ~> 4
SELECT
    location_or_bounds ~> 1 AS x_low,
    location_or_bounds ~> 2 AS x_high,
    location_or_bounds ~> 3 AS y_low,
    location_or_bounds ~> 4 AS y_high
FROM items WHERE name = 'Warehouse Zone 1';
-- x_low | x_high | y_low | y_high
-- 0     | 50     | 0     | 100
```

## Functions and operators

### Utility functions

- `cube_dim(cube)`: Returns the number of dimensions of the cube.
- `cube_is_point(cube)`: Returns `true` if the cube is a point (zero volume), `false` otherwise.

  ```sql
  SELECT cube_dim('(1,2,3)'::cube); -- Result: 3
  SELECT cube_is_point('(1,2,3)'::cube); -- Result: true
  SELECT cube_is_point('(1,2)'::cube); -- Result: true
  SELECT cube_is_point(cube(1,2)); -- Result: false (cube function creates a 1D interval)
  SELECT cube_dim(cube(1,2)); -- Result: 1 (1D interval)
  SELECT cube_is_point(cube(ARRAY[1,2])); -- Result: true (array creates a 2D point)
  SELECT cube_dim(cube(ARRAY[1,2])); -- Result: 2 (2D point)
  SELECT cube_is_point('(1),(2)'::cube); -- Result: false
  ```

### Coordinate functions

- `cube_ll_coord(cube, N)`: Returns the N-th coordinate of the lower-left corner.
- `cube_ur_coord(cube, N)`: Returns the N-th coordinate of the upper-right corner.

  ```sql
  -- Get y-coordinate of lower-left corner for Warehouse Zone 1
  SELECT cube_ll_coord(location_or_bounds, 2) AS y_ll
  FROM items WHERE name = 'Warehouse Zone 1';
  -- Result: 0

  -- Get x-coordinate of upper-right corner for Shipping Box X
  SELECT cube_ur_coord(location_or_bounds, 1) AS x_ur
  FROM items WHERE name = 'Shipping Box X';
  -- Result: 1
  ```

### Union and Intersection

- `cube_union(cube1, cube2)`: Returns the smallest cube enclosing both input cubes.
- `cube_inter(cube1, cube2)`: Returns the intersection of two cubes. Returns `NULL` if they don't intersect.

  ```sql
  SELECT cube_union('(0,0),(2,2)', '(1,1),(3,3)') AS union_result;
  -- Output: (0,0),(3,3)


  SELECT cube_inter('(0,0),(2,2)', '(1,1),(3,3)') AS intersection_result;
  -- Output: (1,1),(2,2)
  ```

### Enlarging cubes

`cube_enlarge(c_in cube, r double precision, n_dims integer)`: Enlarges (or shrinks if `r` is negative) the input cube `c_in` by radius `r` in its first `n_dims` dimensions. If `n_dims` is greater than `c_in`'s dimensions and `r > 0`, new dimensions are added with `(-r, r)` ranges.

```sql
-- Enlarge a 2D point (0,0) by radius 1 in 2 dimensions
SELECT cube_enlarge('(0,0)', 1.0, 2);
-- Output: (-1,-1),(1,1)

SELECT cube_enlarge('(0,0)', 1.0, 3);
-- Output: (-1,-1,-1),(1,1,1)

-- Enlarge a 1D cube (0),(2) by 0.5, extending to 2 dimensions
SELECT cube_enlarge('(0),(2)'::cube, 0.5, 2);
-- Output: (-0.5,-0.5),(2.5,0.5)
```

### Creating cubes from subsets of dimensions

`cube_subset(target_cube cube, dim_indices integer[])`: Creates a new cube using only the dimensions specified by `dim_indices` from the `target_cube`.

```sql
SELECT cube_subset('(1,2,3),(4,5,6)', ARRAY[1,3]) AS subset_cube;
-- Output: (1,3),(4,6) (extracts 1st and 3rd dimensions)

SELECT cube_subset('(1,2,3),(4,5,6)', ARRAY[3]) AS subset_cube;
-- Output: (3),(6) (extracts only the 3rd dimension)
```

## Indexing `cube` data

For efficient querying of `cube` data, especially on large tables, [GiST indexes](https://neon.com/postgresql/postgresql-indexes/postgresql-index-types#gist-indexes) are highly recommended. They can make queries faster when using operators like `&&`, `@>`, `<@`, and the distance operators.

```sql
CREATE INDEX idx_items_location_bounds_gist ON items USING GIST (location_or_bounds);
```

**Nearest neighbor searches**

GiST indexes enable efficient nearest neighbor searches using the distance operators in an `ORDER BY` clause:

```sql
-- Find the 3 items closest to the point (5,5,5)
SELECT name, location_or_bounds, location_or_bounds <-> '(5,5,5)'::cube AS distance
FROM items
ORDER BY location_or_bounds <-> '(5,5,5)'::cube
LIMIT 3;
-- Warehouse Zone 1 | (0,0),(50,100) | 5.0
-- Shipping Box X | (0,0,0),(1,2,1.5) | 6.103277807866851
-- Temperature Range | (-10),(40) | 7.0710678118654755
```

## Practical applications

1. **Geographic Information systems (GIS)**:
   - Storing latitude/longitude/altitude points.
   - Defining bounding boxes for map features.
2. **Business Intelligence (BI) / OLAP**:
   - Representing data points in a multidimensional space (for example, sales by `product_category_id`, `region_id`, `time_id`).
   - Filtering data based on ranges in multiple dimensions.
3. **Scientific computing**: Storing points or regions in n-dimensional parameter spaces for experiments or simulations.
4. **Time-series data with multidimensional attributes**: Storing sensor readings where each reading has multiple values (for example, temperature, humidity, pressure) at a specific time.

   **Example:**

   ```sql
   CREATE TABLE sensor_log (
     ts TIMESTAMPTZ NOT NULL,
     device_id INT,
     metrics CUBE -- for example, (temperature, humidity, pressure)
   );

   INSERT INTO sensor_log (ts, device_id, metrics) VALUES
     (NOW(), 101, '(22.5, 55.2, 1013.1)');

   -- Find logs where temperature (1st dim) was between 20-25
   -- and humidity (2nd dim) was between 50-60
   SELECT * FROM sensor_log
   WHERE metrics <@ cube(array[20,50,-1e6], array[25,60,1e6]); -- We keep 3rd dim a large range
   ```

## Conclusion

The `cube` extension adds a data type for multidimensional data in Postgres. Its operators and functions, combined with GiST indexing, enable efficient storage, querying, and analysis of n-dimensional points and regions, with applications ranging from GIS to scientific computing.

## Resources

- [PostgreSQL `cube` documentation](https://www.postgresql.org/docs/current/cube.html)
- Distances:
  - [Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance)
  - [Taxicab/Manhattan geometry](https://en.wikipedia.org/wiki/Taxicab_geometry)
  - [Chebyshev distance](https://en.wikipedia.org/wiki/Chebyshev_distance)

--- [Document source](https://neon.com/docs/extensions/dblink.md) ---

> Summary: The `dblink` extension lets a Neon session connect to and query remote Postgres databases, returning results as local rows for cross-database reporting, data synchronization, and ad-hoc data pulls. Use `dblink` for a quick, session-scoped connection to another Postgres instance without persistent foreign tables. Use `postgres_fdw` instead for a structured, more secure mapping of remote tables. The extension supports multiple named connections and requires explicit column type definitions in every query result.

# The dblink extension

Connect to and query other Postgres databases from Neon using dblink

Last updated: 2026-06-05

The `dblink` extension provides the ability to connect to other Postgres databases from within your current database. This is invaluable for tasks such as data integration, cross-database querying, and building applications that span multiple database instances. `dblink` allows you to execute queries on these remote databases and retrieve the results directly into your Neon project.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide will walk you through the fundamentals of using the `dblink` extension in your Neon project. You'll learn how to enable the extension, establish connections to remote Postgres databases, execute queries against them, and retrieve the results. We'll explore different connection methods and discuss important considerations for using `dblink` effectively.

**Note:** `dblink` is a core Postgres extension and can be enabled on any Neon project. It allows direct connections to other Postgres databases. For a more structured and potentially more secure way to access data in external data sources (including non-Postgres databases), consider using [Foreign Data Wrappers](https://neon.com/docs/extensions/postgres_fdw).

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Enable the `dblink` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS dblink;
```

## Connecting to a remote database

The `dblink` extension provides the `dblink_connect` function to establish connections to remote Postgres databases. You can connect by providing the connection details directly in the function call or by using a named connection that you can reference in subsequent queries.

The most direct way to connect is by providing a connection string. This string includes all the necessary information to connect to the remote database.

### Named connections

To establish a named connection using `dblink_connect`, use the following syntax:

```sql
SELECT dblink_connect('my_remote_db', 'host=my_remote_host port=5432 dbname=my_remote_database user=my_remote_user password=my_remote_password sslmode=require&channel_binding=require');
```

In this example:

- `'my_remote_db'` is a name you assign to this connection for later use.
- The connection string specifies the host, port, database name, user, password, and SSL mode of the remote Postgres instance. **Replace these placeholders with your actual remote database credentials.**
- `sslmode=require` is recommended for security to ensure an encrypted connection.

You should receive a response like:

```text
 dblink_connect
----------------
 OK
(1 row)
```

### Unnamed connections

You can also connect without naming the connection. This is useful for one-off queries or when you don't need to reference the connection in subsequent queries.

```sql
SELECT dblink_connect('host=my_remote_host port=5432 dbname=my_remote_database user=my_remote_user password=my_remote_password sslmode=require&channel_binding=require');
```

**Tip: Did you know?**

Multiple named connections can be open at once, but only one unnamed connection is permitted at a time. The connection will persist until closed or until the database session is ended.

## Executing queries on the remote database

Once a connection is established, you can use the `dblink` function to execute queries on the remote database.

### With Named connections

```sql
SELECT *
FROM dblink('my_remote_db', 'SELECT table_name FROM information_schema.tables WHERE table_schema = ''public''')
AS remote_tables(table_name TEXT);
```

In this example:

- `'my_remote_db'` refers to the connection name established earlier.
- `'SELECT table_name FROM information_schema.tables WHERE table_schema = 'public''` is the SQL query you want to execute on the remote database.
- `AS remote_tables(table_name TEXT)` defines the structure of the returned data, specifying the column name (`table_name`) and its data type (`TEXT`). **This is crucial as `dblink` needs to know the expected structure of the results.**

You should receive a list of tables from the `public` schema of the remote database.

### With Unnamed connections

When using an unnamed connection, you can execute queries directly without referencing a named connection.

```sql
SELECT *
FROM dblink('host=my_remote_host port=5432 dbname=my_remote_database user=my_remote_user password=my_remote_password sslmode=require&channel_binding=require',
            'SELECT table_name FROM information_schema.tables WHERE table_schema = ''public''')
AS remote_tables(table_name TEXT);
```

## Retrieving data from the remote database

The results of the remote query are returned as a set of rows. You can use standard SQL to further process or integrate this data within your Neon database.

```sql
SELECT rt.table_name
FROM dblink('my_remote_db', 'SELECT table_name FROM information_schema.tables WHERE table_schema = ''public''')
AS rt(table_name TEXT)
WHERE rt.table_name LIKE 'user%';
```

This query retrieves the names of tables in the remote database that start with "user".

```sql
SELECT *
FROM dblink('my_remote_db', 'SELECT id, user_id, task, is_complete, inserted_at FROM todos')
AS rows(id int, user_id TEXT, task TEXT, is_complete BOOLEAN, inserted_at text);
```

This query retrieves the rows from a `todos` table in the remote database.

## Closing connections

It's good practice to close connections when you're finished with them to free up resources. Use the `dblink_disconnect` function.

```sql
SELECT dblink_disconnect('my_remote_db');
```

To disconnect from an unnamed connection, you can use the following:

```sql
SELECT dblink_disconnect();
```

## Using Named Connections for convenience

Naming your connections with `dblink_connect` can simplify your queries, especially if you frequently access the same remote database.

```sql
-- Connect with a name
SELECT dblink_connect('production_db', 'host=prod_host port=5432 dbname=prod_data user=reporter password=securepass sslmode=require&channel_binding=require');

-- Execute queries using the named connection
SELECT * FROM dblink('production_db', 'SELECT count(*) FROM orders') AS order_count(count int);

-- Disconnect
SELECT dblink_disconnect('production_db');
```

## Practical Examples

### Data Synchronization:

You can use `dblink` to periodically pull data from a remote database into your Neon project for reporting or analysis.

```sql
-- Using dblink to insert data from a remote table
INSERT INTO local_staging_table (col1, col2)
SELECT remote_col1, remote_col2
FROM dblink('remote_db', 'SELECT col1, col2 FROM remote_table')
AS rt(remote_col1 INTEGER, remote_col2 TEXT);
```

### Cross-Database reporting:

Generate reports that combine data from your Neon database and one or more remote Postgres databases.

```sql
SELECT l.customer_name, r.order_total
FROM customers l
JOIN dblink('orders_db', 'SELECT customer_id, sum(amount) AS order_total FROM orders GROUP BY customer_id')
AS r(customer_id INTEGER, order_total NUMERIC) ON l.customer_id = r.customer_id;
```

## Advanced `dblink` functions

The `dblink` extension provides additional functions to help manage and interact with remote databases:

- **`dblink_get_connections()`:** This function is helpful for monitoring and managing your `dblink` connections. It returns a list of the names of all currently open, named `dblink` connections in the current session. This can be useful for troubleshooting or ensuring connections are being managed correctly.

  **SQL**

  ```sql
  SELECT * FROM dblink_get_connections();
  ```

  **bash**

  ```bash
  dblink_get_connections
  ------------------
  {my_remote_db}
  ```

- **`dblink_error_message(TEXT connname)`:** When working with remote databases, errors can occur. This function allows you to retrieve the last error message associated with a specific named `dblink` connection. This is invaluable for debugging issues that arise during remote queries.

- **`dblink_send_query(TEXT connname, text sql)`:** This function sends a query to a named `dblink` connection without waiting for the result. This is useful for executing long-running queries on the remote database without blocking the current session. The return value is 1 if the query was successfully dispatched, or 0 otherwise.

- **`dblink_get_result(TEXT connname)`:** This function retrieves the result of a query that was previously sent using `dblink_send_query`. It returns the result set as a set of rows, allowing you to process the data as needed.

- **`dblink_cancel_query(TEXT connname)`:** This function tries to cancel the currently executing query on a named `dblink` connection. This can be useful if you need to stop a long-running query that is consuming resources on the remote database. The return value is 'OK' if the query was successfully canceled, or the error message as a text otherwise.

## Security considerations

- **Credentials:** Using `dblink` is inherently less secure than other methods of accessing remote data, as it requires storing credentials in the connection strings. For this reason, it may be preferable to use Foreign Data Wrappers or other secure methods.
- **Network Security:** Ensure that network access is properly configured to allow connections between your Neon project and the remote database server. Firewalls and security groups might need adjustments.
- **`sslmode`:** Always use `sslmode=require&channel_binding=require` in your connection strings to encrypt communication and ensure enhanced security against man-in-the-middle attacks.
- **Principle of Least Privilege:** Grant only the necessary permissions to the `dblink` connecting user on the remote database.

## Better alternatives: Foreign Data Wrappers

While `dblink` provides direct connectivity, Postgres' Foreign Data Wrappers (FDW) offer a more integrated and often more manageable approach for accessing external data. The `postgres_fdw` allows you to define a _foreign server_ and _foreign tables_ that represent tables in the remote database. You can learn more about FDWs in our [postgres_fdw](https://neon.com/docs/extensions/postgres_fdw) guide.

## Conclusion

`dblink` lets you connect to and query remote Postgres databases from your Neon project. It's flexible enough for one-off data pulls or complex cross-database queries. Keep security in mind when managing connections and credentials. For more structured access, see [postgres_fdw](https://neon.com/docs/extensions/postgres_fdw).

## Reference

- [PostgreSQL `dblink` Documentation](https://www.postgresql.org/docs/current/dblink.html)
- [PostgreSQL Foreign Data Wrappers](https://www.postgresql.org/docs/current/postgres-fdw.html)

--- [Document source](https://neon.com/docs/extensions/dict_int.md) ---

> Summary: The `dict_int` Postgres extension provides a dictionary template (`intdict_template`) for controlling how integers are tokenized and indexed in Full-Text Search. Configurable parameters `maxlen`, `rejectlong`, and `absval` let you truncate, reject, or normalize numeric tokens. Use it when integer-heavy data such as product IDs or serial numbers bloats your FTS index or returns irrelevant results. On Neon, the default `intdict` dictionary is superuser-owned; create a custom dictionary from `intdict_template` and bind it to a copied text search configuration.

# The dict_int extension

Control how integers are indexed in Postgres Full-Text Search to improve performance and relevance.

Last updated: 2026-08-04

[Postgres Full-Text Search (FTS)](https://neon.com/postgresql/postgresql-indexes/postgresql-full-text-search) is a powerful tool for searching through textual data. However, when this data includes a significant number of integers like product IDs, serial numbers, or document codes, default FTS behavior can sometimes lead to inefficient indexes and slower search performance.

The `dict_int` extension is designed to address this issue by providing a specialized dictionary template that optimizes how integers are tokenized and indexed. This can lead to more compact indexes and faster, more relevant searches.

Imagine searching a vast product catalog for "ID 1234567890". Without `dict_int`, FTS might break this number down in various ways, or index the entire long string, potentially creating many unique terms that aren't always useful for searching and can bloat the index. `dict_int` allows you to define rules for how these numbers are processed, ensuring they are handled efficiently.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `dict_int` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS dict_int;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Understanding `dict_int`

The `dict_int` dictionary template offers precise control over how integer strings are tokenized for full-text search. This is achieved through three key parameters that you can tailor when creating a dictionary to optimize index size and ensure that searches for numbers are both efficient and relevant to your needs. These settings dictate how numbers are processed before they even make it into the search index.

### `maxlen`

This parameter sets the maximum number of digits an integer token is allowed to have. Its default value when creating a dictionary is `6`.

- When an integer token processed by the dictionary has more digits than `maxlen`, it will either be shortened or discarded entirely, depending on the `rejectlong` setting.
- The primary purpose of `maxlen` is to help prevent extremely long, and often less significant, numerical sequences from consuming valuable index space and potentially slowing down searches.

For example, if `maxlen` is `5` in your custom dictionary and it encounters the number `1234567` (and `rejectlong` is `false`), it will be processed as `12345`.

### `rejectlong`

This parameter determines what happens to an integer token that exceeds the number of digits specified by `maxlen`. The default for `rejectlong` is `false`.

- If `rejectlong` is `false`, integers longer than `maxlen` are truncated. This means only their initial `maxlen` digits are kept and indexed.
- If `rejectlong` is set to `true`, these overlength integers are instead treated as "stop words." This effectively means they are entirely discarded by the dictionary, will not be indexed, and therefore cannot be found via full-text search.

Choosing `rejectlong = true` can be beneficial if very long numbers in your dataset are generally considered noise or are irrelevant to your typical search use cases, as it helps keep the index leaner. Conversely, if the leading portion of a long number is still important for searching, keeping `rejectlong = false` is the appropriate choice.

### `absval`

The `absval` parameter controls the handling of leading positive (`+`) or negative (`-`) signs in integer tokens. By default, `absval` is `false`.

- When `absval` is `false`, any leading signs are typically preserved as part of the token.
- If `absval` is set to `true`, any leading `+` or `-` signs are stripped from the integer _before_ the `maxlen` logic is applied. For example, if `absval` is `true` in your custom dictionary, both `-12345` and `+12345` would be normalized to `12345`.

This feature is very useful when the sign of a number isn't relevant for your search criteria, allowing, for instance, a search for `ID 789` to successfully match entries like `ID: -789` or `REF: +789` without needing to account for the sign explicitly in the search query.

## Using `dict_int`

The `dict_int` extension provides a template for creating custom integer dictionaries. This allows you to define how integers are processed during full-text search indexing and querying. A default dictionary named `intdict` is provided, which has default parameters set to `maxlen = 6`, `rejectlong = false`, and `absval = false`.

**Important: Modifying the default intdict dictionary on Neon**

The default `intdict` dictionary is owned by superuser. On Neon, you do not have permissions to directly `ALTER` this default dictionary, which can result in an "ERROR: must be owner of text search dictionary intdict".

The recommended approach is to **create your own custom dictionary** from the `intdict_template`. This gives you full control over its parameters

### Creating and configuring a custom integer dictionary

You can create new dictionaries from the `intdict_template` and specify your desired parameters.

#### Example:

Create dictionary named `my_custom_intdict` with `maxlen` set to `4`, `rejectlong` to `true`, and `absval` to `true`:

```sql
CREATE TEXT SEARCH DICTIONARY my_custom_intdict (
    TEMPLATE = intdict_template,
    MAXLEN = 4,
    REJECTLONG = true,
    ABSVAL = true
);
```

If you need to change its parameters later, you can `ALTER` the dictionary:

```sql
ALTER TEXT SEARCH DICTIONARY my_custom_intdict (
    MAXLEN = 3,
    REJECTLONG = false,
    ABSVAL = false
);
```

### Utilizing with `ts_lexize`

The `ts_lexize` function is used for testing how a dictionary processes input tokens. It shows what lexemes (if any) are produced.

To test the behavior of custom dictionary, use `ts_lexize` with the dictionary name and an integer string.

```sql
CREATE TEXT SEARCH DICTIONARY intdict_for_testing (
    TEMPLATE = intdict_template,
    MAXLEN = 3,
    REJECTLONG = false,
    ABSVAL = true
);
```

Now, test this dictionary with various integer inputs:

```sql
SELECT ts_lexize('intdict_for_testing', '123');         -- Result: {123}
SELECT ts_lexize('intdict_for_testing', '12345');       -- Result: {123} (truncated)
SELECT ts_lexize('intdict_for_testing', '-98765');      -- Result: {987} (absval applied)
SELECT ts_lexize('intdict_for_testing', '+12');         -- Result: {12}  (absval applied)
```

Test with `rejectlong` set to `true`:

```sql
ALTER TEXT SEARCH DICTIONARY intdict_for_testing (
    REJECTLONG = true
);

SELECT ts_lexize('intdict_for_testing', '1234567');     -- Result: {} (empty, rejected)
SELECT ts_lexize('intdict_for_testing', '987');       -- Result: {987} (within limit)
```

## Integrating `dict_int` into a text search configuration

For a custom integer dictionary to be used during indexing and searching, it must be associated with specific token types in a text search configuration.

**Important: Modifying default text search configurations on Neon**

Altering default text search configurations (like `english`) requires superuser privileges on Neon. If you encounter an "ERROR: must be owner of text search configuration english", you will need to first **create a copy of an existing configuration** (for example, `english`) and then modify your own copy.

Here's the recommended approach:

1. Create your custom integer dictionary (if you haven't already):

   ```sql
   CREATE TEXT SEARCH DICTIONARY my_custom_intdict (
       TEMPLATE = intdict_template,
       MAXLEN = 8, -- Example: Max 8 digits
       REJECTLONG = false, -- Example: Truncate long numbers
       ABSVAL = true -- Example: Ignore signs
   );
   ```

2. Create a copy of an existing text search configuration (for example, `english`):

   ```sql
   CREATE TEXT SEARCH CONFIGURATION public.my_app_search_config (COPY = pg_catalog.english);
   ```

   The above sql creates a new configuration named `my_app_search_config` that inherits the settings of the `english` configuration.

3. Alter the copied configuration to use custom dictionary for integer token types (`int` and `uint`):
   ```sql
   ALTER TEXT SEARCH CONFIGURATION public.my_app_search_config
       ALTER MAPPING FOR int, uint WITH my_custom_intdict;
   ```

Now, `public.my_app_search_config` is set up to use `my_custom_intdict` for processing integers. `public.my_app_search_config` can now be used in `to_tsvector` and `to_tsquery` functions to process integer tokens according to the rules defined in `my_custom_intdict`.

## Example

Let's consider a scenario where we have a `documents` table with a `version_code` field stored as text. These codes can be like "v1", "V2.0", "Rev 003", or purely numeric like "1001", "005". We want to full-text search these, focusing on the numeric parts using a custom integer dictionary and a custom text search configuration.

### Sample table and data

```sql
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    title TEXT,
    content TEXT,
    version_code TEXT
);

INSERT INTO documents (title, content, version_code) VALUES
('Intro Guide', 'Content of version 1...', '1'),
('Advanced Manual', 'More content...', '0042'),
('Internal Spec', 'Spec details...', '7654321'),
('Internal Spec v2', 'Updated spec...', '+7654321'),
('Draft Notes', 'Preliminary ideas...', 'ver003');
```

### Create custom dictionary and text search configuration

1. Create a custom integer dictionary, `doc_version_intdict`, with `maxlen` set to 4, `rejectlong` to `true`, and `absval` to `true`.

   ```sql
   CREATE TEXT SEARCH DICTIONARY doc_version_intdict (
       TEMPLATE = intdict_template,
       MAXLEN = 4,
       REJECTLONG = true,
       ABSVAL = true
   );
   ```

2. Create a copy of the `english` text search configuration, naming it `doc_search_config`.

   ```sql
   CREATE TEXT SEARCH CONFIGURATION public.doc_search_config (COPY = pg_catalog.english);
   ```

3. Alter `doc_search_config` to use `doc_version_intdict` for integers.
   ```sql
   ALTER TEXT SEARCH CONFIGURATION public.doc_search_config
       ALTER MAPPING FOR int, uint WITH doc_version_intdict;
   ```

### Add `tsvector` column and index data

Index the `version_code` column using the custom configuration. First, add a `tsvector` column to the `documents` table:

```sql
ALTER TABLE documents ADD COLUMN version_tsv TSVECTOR;

UPDATE documents
SET version_tsv = to_tsvector('public.doc_search_config', version_code); -- Use custom config
```

### Examine the indexed tokens

To see how the `version_code` values are indexed, you can query the `documents` table:

```sql
SELECT id, title, version_code, version_tsv FROM documents;
```

```text
id  |      title       | version_code | version_tsv
----+------------------+--------------+-------------
  1 | Intro Guide      | 1            | '1':1
  2 | Advanced Manual  | 0042         | '0042':1
  3 | Internal Spec    | 7654321      |
  4 | Internal Spec v2 | +7654321     |
  5 | Draft Notes      | ver003       | 'ver003':1
(5 rows)
```

In this example:

- The `version_code` "1" is indexed as `'1':1`.
- The `version_code` "0042" is indexed as `'0042':1`.
- The long version code "7654321" and "+7654321" are not indexed at all due to `maxlen` and `rejectlong`.
- The version code "ver003" is indexed as `'ver003':1` because it doesn't exceed the `maxlen` and is not purely numeric.

### Searching

Using the custom configuration, you can now search for specific version codes:

```sql
-- Find documents with version code '0042'
SELECT title, version_code FROM documents
WHERE version_tsv @@ to_tsquery('public.doc_search_config', '0042');
-- (Advanced Manual, '0042')

-- Try to find the long version code
SELECT title, version_code FROM documents
WHERE version_tsv @@ to_tsquery('public.doc_search_config', '7654321');
-- null (Expected: No results, as it was rejected)
```

## Limitations

- **Integer-specific:** `dict_int` is designed for whole numbers (integers). It does not process floating-point numbers (for example, `3.14159`). Standard FTS tokenizers will handle floating-point numbers, but `dict_int`'s logic won't apply to them.
- **Text representation:** It operates on the textual representation of numbers as tokenized by the FTS parser. If your column is of type `INTEGER` and you cast it to `TEXT` for `to_tsvector`, `dict_int` will then process that text.

## Conclusion

The `dict_int` dictionary template is a valuable tool in Postgres for fine-tuning how integer values are handled in Full-Text Search. By customizing the way integers are indexed, you can achieve several benefits:

- **Reduced index size:** Custom integer dictionaries help prevent the proliferation of unique numeric lexemes by truncating or rejecting overly long numbers and normalizing signed ones. This keeps your FTS indexes smaller and more manageable.
- **Improved search performance:** As a general rule, smaller, more optimized indexes lead to faster search query execution.
- **More relevant search results:** By tailoring how numbers are processed, you can ensure that searches for numeric data are more aligned with user expectations and less susceptible to noise from irrelevant number formats.

## Resources

- [PostgreSQL `dict_int` documentation](https://www.postgresql.org/docs/current/dict-int.html)
- [Dictionary Testing with `ts_lexize`](https://www.postgresql.org/docs/current/textsearch-debugging.html#TEXTSEARCH-DICTIONARY-TESTING)
- [PostgreSQL Full Text Search](https://neon.com/postgresql/postgresql-indexes/postgresql-full-text-search)
- [Full Text Search using tsvector with Neon Postgres](https://neon.com/guides/full-text-search)
- [Postgres tsvector data type](https://neon.com/docs/data-types/tsvector)

--- [Document source](https://neon.com/docs/extensions/earthdistance.md) ---

> Summary: The `earthdistance` extension calculates great-circle distances in Postgres using two approaches: the `earth` type with `ll_to_earth` and `earth_distance`, or the native `point` type with the `<@>` operator. Use it for location-based search, radius filtering, or nearest-neighbor queries without PostGIS. It requires the `cube` extension and supports GiST indexing via `earth_box` for efficient radius searches.

# The earthdistance extension

Calculate great-circle distances between points on Earth in Postgres

Last updated: 2026-06-05

The `earthdistance` extension for Postgres provides functions to calculate great-circle distances between points on the Earth's surface. This is essential for applications requiring geospatial distance calculations, such as location-based services, mapping applications, logistics, and any system that needs to find nearby points or calculate travel distances.

**Important: Accuracy and assumptions**

The `earthdistance` extension primarily assumes a spherical Earth model for its calculations, which provides good approximations for many use cases. It relies on the [`cube`](https://neon.com/docs/extensions/cube) extension for some of its underlying operations.

You may consider using the [`postgis` extension](https://neon.com/docs/extensions/postgis) if accurate geospatial calculations are critical for your application.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `earthdistance` extension

To use `earthdistance`, you first need to enable it and its dependency, the [`cube` extension](https://neon.com/docs/extensions/cube). You can do this by running the following `CREATE EXTENSION` statements in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client like [psql](https://neon.com/docs/connect/query-with-psql-editor):

```sql
CREATE EXTENSION IF NOT EXISTS cube;
CREATE EXTENSION IF NOT EXISTS earthdistance;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Core concepts

The `earthdistance` extension offers two main ways to represent geographic points and calculate distances:

1. **Using the `earth` type:** This approach involves converting latitude and longitude coordinates into a special `earth` data type (which is a domain over `cube`, representing a point in 3D Cartesian coordinates based on a spherical earth model). Distances are calculated in meters.
2. **Using the native `point` type:** This approach uses the built-in `point` type in Postgres, where the first component is longitude and the second is latitude. It provides a specific operator for distance calculation, which returns results in statute miles.

### The `earth` data type and associated functions

- `earth` data type

  Represents a point on the Earth's surface. It's internally a `cube` point representing a 3D Cartesian coordinate. You don't usually interact with its internal representation directly but use helper functions.

- `ll_to_earth(latitude double precision, longitude double precision)` returns `earth`

  Converts latitude and longitude (in degrees) to an `earth` data type value.

- `earth_distance(p1 earth, p2 earth)` returns double precision

  Calculates the great-circle distance in **meters** between two `earth` points.

  ```sql
  -- Distance between London and Paris
  SELECT earth_distance(
      ll_to_earth(51.5074, -0.1278), -- London
      ll_to_earth(48.8566, 2.3522)   -- Paris
  ) AS distance_meters;
  -- Output: 343942.5946120387
  ```

- `earth_box(location earth, radius_meters double precision)` returns `cube`

  Computes a bounding box (as a `cube` type) that encloses all points within the specified `radius_meters` from the given `location`. This is primarily used for optimizing radius searches with [GiST indexes](https://neon.com/postgresql/postgresql-indexes/postgresql-index-types#gist-indexes).

  ```sql
  -- Create a bounding box for a 10km radius around London
  SELECT earth_box(ll_to_earth(51.5074, -0.1278), 10000) AS search_box;
  ```

  When used in queries, you typically use the `<@` operator from the `cube` extension. The `<@` operator means "is contained by".

  The expression `ll_to_earth(lat, lon) <@ earth_box(center_point_earth, search_radius_meters)` checks if the specific geographic point (represented as an `earth` type, which is a `cube` point) is contained within the square bounding `earth_box` (also a `cube`).

  For instance, if `point_A` is `ll_to_earth(51.5, -0.1)` (a point in London) and `london_box` is `earth_box(ll_to_earth(51.5074, -0.1278), 10000)`, then `point_A <@ london_box` would be `true`.

  ```sql
  SELECT ll_to_earth(51.5, -0.1) <@ earth_box(ll_to_earth(51.5074, -0.1278), 10000) AS is_within_box;
  -- Output: true
  ```

### Using the `point` data type

- `point` data type

  A built-in Postgres type representing a 2D point in Cartesian coordinates. In the context of `earthdistance`, the first component is longitude and the second is latitude.

- `point1 <@> point2` returns double precision

  Calculates the great-circle distance in **statute miles** between two points.

  ```sql
  -- Distance between San Francisco (-122.4194 lon, 37.7749 lat)
  -- and New York (-74.0060 lon, 40.7128 lat)
  SELECT point '(-122.4194, 37.7749)' <@> point '(-74.0060, 40.7128)' AS distance_miles;
  -- Output: 2565.6899113306895
  ```

## Example usage

Now that we've seen the core functions, let's create and populate a sample table to demonstrate practical usage scenarios. This table will store location data with latitude and longitude.

```sql
CREATE TABLE locations (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    latitude DOUBLE PRECISION NOT NULL,
    longitude DOUBLE PRECISION NOT NULL
);

INSERT INTO locations (name, latitude, longitude) VALUES
  ('San Francisco', 37.7749, -122.4194),
  ('New York', 40.7128, -74.0060),
  ('Los Angeles', 34.0522, -118.2437),
  ('Chicago', 41.8781, -87.6298),
  ('London', 51.5074, -0.1278),
  ('Tokyo', 35.6895, 139.6917),
  ('Sydney', -33.8688, 151.2093);
```

## Practical usage scenarios

With our sample `locations` table, we can now explore common geospatial queries.

### Calculating distance between two specific points

Using `ll_to_earth()` and `earth_distance()`:

```sql
SELECT
    a.name AS location_a,
    b.name AS location_b,
    earth_distance(
        ll_to_earth(a.latitude, a.longitude),
        ll_to_earth(b.latitude, b.longitude)
    ) AS distance_meters
FROM locations a, locations b
WHERE a.name = 'San Francisco' AND b.name = 'New York';
```

Output:

```text
| location_a    | location_b | distance_meters     |
|---------------|------------|---------------------|
| San Francisco | New York   | 4133731.792059527   |
```

### Finding locations within a given radius

Find all locations within 8000 kilometers of London using the `earth` type functions.

```sql
SELECT
    name,
    earth_distance(
        ll_to_earth(latitude, longitude),
        ll_to_earth(51.5074, -0.1278) -- London's coordinates
    ) / 1000.0 AS distance_from_london_km -- Convert meters to km
FROM locations
WHERE earth_distance(
        ll_to_earth(latitude, longitude),
        ll_to_earth(51.5074, -0.1278)
    ) < 8000 * 1000 -- Radius in meters
ORDER BY distance_from_london_km;
```

Output:

```text
| name          | distance_from_london_km |
|---------------|-------------------------|
| London        | 0.0                     |
| New York      | 5576.4892261332425      |
| Chicago       | 6360.125481207209       |
```

## Indexing for performance

For applications with many locations that require frequent radius searches or nearest-neighbor queries, indexing is crucial. GiST indexes are used with the `earth` type functions (`ll_to_earth`, `earth_box`).

1. **Create a GiST index on the `earth` representation of your coordinates:**
   This index will be on the result of the `ll_to_earth()` function applied to your latitude and longitude columns.

   ```sql
   CREATE INDEX locations_earth_coords_idx
   ON locations
   USING GIST (ll_to_earth(latitude, longitude));
   ```

2. **Perform an indexed radius search:**

   Let's find locations within 1000 km of San Francisco `(37.7749° N, -122.4194° W)`.

   ```sql
   SELECT
       name,
       earth_distance(
           ll_to_earth(latitude, longitude),
           ll_to_earth(37.7749, -122.4194)
       ) / 1000.0 AS distance_from_sf_km
   FROM locations
   WHERE
       -- This part uses the GiST index for a fast coarse filter
       ll_to_earth(latitude, longitude) <@ earth_box(ll_to_earth(37.7749, -122.4194), 1000 * 1000) -- Radius in meters
       -- This part is the exact distance check for refinement (necessary as earth_box is a square)
       AND earth_distance(
           ll_to_earth(latitude, longitude),
           ll_to_earth(37.7749, -122.4194)
       ) < 1000 * 1000 -- Radius in meters
   ORDER BY distance_from_sf_km;
   ```

   **Explanation of the indexed query:**

   - The `ll_to_earth(latitude, longitude) <@ earth_box(...)` condition uses the GiST index. The `earth_box` function creates a square bounding box. The index quickly finds points whose `earth` representation falls within this box.
   - The second condition, `earth_distance(...) < radius`, is crucial. It performs the precise great-circle distance calculation for the candidate rows selected by the index, filtering them to the exact circular radius. This is because the `earth_box` provides a rough filter, and the `earth_distance` provides the exact filter.

## Conclusion

The `earthdistance` extension is a powerful and convenient tool in Postgres for applications dealing with geographic locations. It simplifies the calculation of great-circle distances, enabling features like location-based searching and distance filtering directly within your database. By understanding its core functions, data representations, and GiST indexing, you can build efficient geospatial queries.

## Resources

- PostgreSQL official documentation:
  - [earthdistance](https://www.postgresql.org/docs/current/earthdistance.html)
  - [cube](https://www.postgresql.org/docs/current/cube.html)
  - [point](https://www.postgresql.org/docs/current/datatype-geometric.html#DATATYPE-GEOMETRIC-POINTS)
- [Cube extension](https://neon.com/docs/extensions/cube)
- [Greater-circle distance](https://en.wikipedia.org/wiki/Great-circle_distance)

--- [Document source](https://neon.com/docs/extensions/extension-explorer.md) ---

> Summary: A category-browsable index of all Postgres extensions supported on Neon, organized into groups such as AI/ML, analytics, geospatial, search, security, and query optimization. Navigate to individual extension docs, install instructions, or the flat alphabetical list.

# Postgres extension explorer

Last updated: 2026-09-27

Browse supported Postgres extensions by category.

[List view](https://neon.com/docs/extensions/pg-extensions) | [Install an extension](https://neon.com/docs/extensions/pg-extensions#install-an-extension) | [Update an extension](https://neon.com/docs/extensions/pg-extensions#update-an-extension-version) | [Request an extension](https://neon.com/docs/extensions/pg-extensions#request-an-extension)

## AI / Machine Learning

- [pg_tiktoken](https://neon.com/docs/extensions/pg_tiktoken): Tokenize data in Postgres using the OpenAI tiktoken library
- [lakebase_vector](https://neon.com/docs/extensions/lakebase-vector): Scalable vector similarity search for RAG and semantic search
- [pgvector](https://neon.com/docs/extensions/pgvector): Store vector embeddings and perform vector similarity search in Postgres

## Analytics

- [pg_mooncake](https://neon.com/docs/extensions/pg_mooncake): Adds columnstore tables and DuckDB execution for fast analytics in Postgres.
- [hll](https://github.com/citusdata/postgresql-hll): Implements a HyperLogLog data structure as a native data type for efficient and tunable distinct value counting
- [timescaledb](https://neon.com/docs/extensions/timescaledb): Enables Postgres as a time-series database for efficient storage and retrieval of time-series data

## Auditing / Logging

- [insert_username](https://www.postgresql.org/docs/current/contrib-spi.html): Implements a trigger that stores the current user's name into a text field, useful for tracking who modified a particular row within a table
- [moddatetime](https://www.postgresql.org/docs/current/contrib-spi.html): Implements a trigger that automatically updates a timestamp column to the current timestamp whenever a row is modified
- [pgrowlocks](https://neon.com/docs/extensions/pgrowlocks): Provides a function that shows row locking information for a specified table, useful in concurrency and deadlock debugging
- [tcn](https://www.postgresql.org/docs/16/tcn.html): Provides a trigger function to notify listeners of changes to a table, allowing applications to respond to changes in the database

## Data / Transformations

- [address_standardizer](https://postgis.net/docs/Extras.html#Address_Standardizer): A single-line address parser that takes an input address and normalizes it based on a set of rules
- [address_standardizer_data_us](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables): Provides data for standardizing US addresses, for use with the address_standardizer extension
- [anon](https://neon.com/docs/extensions/postgresql-anonymizer): Provides data masking and anonymization capabilities for protecting personally identifiable information (PII) and sensitive data in Postgres databases
- [citext](https://neon.com/docs/extensions/citext): Provides a case-insensitive character string type that internally calls lower when comparing values in Postgres
- [cube](https://neon.com/docs/extensions/cube): Implements the cube data type for representing multidimensional cubes in Postgres
- [earthdistance](https://neon.com/docs/extensions/earthdistance): Provides cube-based and point-based approaches to calculating great circle distances on the surface of the Earth
- [hstore](https://neon.com/docs/extensions/hstore): Implements an hstore data type for storing and manipulating sets of key-value pairs within a single Postgres value
- [intagg](https://www.postgresql.org/docs/16/intagg.html): Provides an integer aggregator and enumerator for Postgres
- [intarray](https://neon.com/docs/extensions/intarray): Offers functions and operators for manipulating and searching arrays of integers within Postgres
- [isn](https://www.postgresql.org/docs/16/isn.html): Implements data types for international product numbering standards: EAN13, UPC, ISBN (books), ISMN (music), and ISSN (serials)
- [ltree](https://neon.com/docs/extensions/ltree): Provides data types for representing labels of data stored in a hierarchical tree-like structure and facilities for searching through label trees
- [pg_graphql](https://neon.com/docs/extensions/pg_graphql): Adds GraphQL support to Postgres, allowing you to query your database via GraphQL
- [pg_hashids](https://github.com/iCyberon/pg_hashids): Enables the generation of short, unique hash ids from integers, useful for obfuscating internal ids
- [pg_jsonschema](https://github.com/supabase/pg_jsonschema): Provides support for JSON schema validation on json and jsonb data types
- [pg_uuidv7](https://neon.com/docs/extensions/pg_uuidv7): Enables creating valid UUID Version 7 values in Postgres, enabling globally unique identifiers with temporal ordering
- [pgx_ulid](https://github.com/pksunkara/pgx_ulid): A full-featured extension for generating and working with ULID (Universally Unique Lexicographically Sortable Identifiers)
- [seg](https://www.postgresql.org/docs/16/seg.html): Implements the seg data type for storage and manipulation of line segments or floating-point ranges, useful for geometric and scientific applications
- [semver](https://pgxn.org/dist/semver): A Postgres data type for the Semantic Version format with support for btree and hash indexing
- [tablefunc](https://neon.com/docs/extensions/tablefunc): Contains functions that return tables (multiple rows), including crosstab, which can pivot row data into columns dynamically
- [unaccent](https://neon.com/docs/extensions/unaccent): A text search dictionary that removes accents from characters, simplifying text search in Postgres
- [unit](https://github.com/df7cb/postgresql-unit): Implements a data type for SI units, plus byte, for storage, manipulation, and calculation of scientific units
- [uuid-ossp](https://neon.com/docs/extensions/uuid-ossp): Provides functions to generate universally unique identifiers (UUIDs) in Postgres, supporting various UUID standards
- [wal2json](https://neon.com/docs/extensions/wal2json): A Postgres logical decoding plugin that converts Write-Ahead Log (WAL) changes into JSON objects
- [xml2](https://neon.com/docs/extensions/xml2): Enables XPath queries and XSLT functionality directly within Postgres, enabling XML data processing

## Debugging

- [moddatetime](https://www.postgresql.org/docs/current/contrib-spi.html): Automatically updates a timestamp column to the current timestamp whenever a row is modified in Postgres
- [pgrowlocks](https://neon.com/docs/extensions/pgrowlocks): Provides a function that shows row locking information for a specified table, which can aid in concurrency and deadlock debugging
- [pgTap](https://pgtap.org/documentation.html): A unit testing framework for Postgres, enabling sophisticated testing of database queries and functions
- [plpgsql_check](https://pgxn.org/dist/plpgsql_check/): Provides a linter and debugger for PL/pgSQL code, helping identify errors and optimize PL/pgSQL functions

## Geospatial

- [cube](https://neon.com/docs/extensions/cube): Implements a data type for representing multidimensional cubes in Postgres
- [earthdistance](https://neon.com/docs/extensions/earthdistance): Provides cube-based and point-based approaches to calculating great circle distances on the surface of the Earth
- [h3](https://neon.com/docs/extensions/postgis-related-extensions#h3-and-h3-postgis): Integrates Uber's H3 geospatial indexing system that combines the benefits of a hexagonal grid with S2's hierarchical subdivisions
- [h3_postgis](https://neon.com/docs/extensions/postgis-related-extensions#h3-and-h3-postgis): A PostGIS extension for H3, enabling advanced spatial analysis and indexing
- [pgrouting](https://neon.com/docs/extensions/postgis-related-extensions#pgrouting): Extends PostGIS/Postgres databases, providing geospatial routing and other network analysis functionality
- [postgis](https://neon.com/docs/extensions/postgis): Extends Postgres to allow GIS (Geographic Information Systems) objects to be stored in the database, enabling spatial queries directly in SQL
- [postgis_raster](https://postgis.net/docs/RT_reference.html): Adds support for raster data to PostGIS, enabling advanced geospatial analysis on raster images
- [postgis_sfcgal](https://neon.com/docs/extensions/postgis-related-extensions#postgis-sfcgal): Provides support for advanced 3D geometries in PostGIS, based on the SFCGAL library
- [postgis_tiger_geocoder](https://neon.com/docs/extensions/postgis-related-extensions#postgis-tiger-geocoder): Enables geocoding and reverse geocoding capabilities in PostGIS using TIGER/Line data
- [postgis_topology](https://www.postgis.net/docs/Topology.html): Extends PostGIS with support for topological data types and functions, facilitating the analysis of spatial relationships

## Index / Table optimization

- [bloom](https://www.postgresql.org/docs/16/bloom.html): Provides an index access method for Postgres based on Bloom filters
- [btree_gin](https://neon.com/docs/extensions/btree_gin): Provides GIN operator classes that implement B-tree equivalent behavior
- [btree_gist](https://neon.com/docs/extensions/btree_gist): Provides GiST index operator classes that implement B-tree equivalent behavior
- [ip4r](https://github.com/RhodiumToad/ip4r): Provides a range index type and functions for efficiently storing and querying IPv4 and IPv6 ranges and addresses in Postgres
- [pg_partman](https://github.com/pgpartman/pg_partman): A partition manager extension that enables creating and managing time-based and number-based table partition sets in Postgres
- [pg_prewarm](https://neon.com/docs/extensions/pg_prewarm): Allows manual preloading of relation data into the Postgres buffer cache, reducing access times for frequently queried tables
- [pg_repack](https://neon.com/docs/extensions/pg_repack): Lets you remove bloat from tables and indexes, and optionally restore the physical order of clustered indexes
- [pg_roaringbitmap](https://github.com/ChenHuajun/pg_roaringbitmap): Implements Roaring Bitmaps in Postgres for efficient storage and manipulation of bit sets
- [rum](https://github.com/postgrespro/rum): Provides an access method to work with a RUM index, designed to speed up full-text searches

## Metrics

- [neon](https://neon.com/docs/extensions/neon): Provides functions and views designed to gather Neon-specific metrics
- [pg_stat_statements](https://neon.com/docs/extensions/pg_stat_statements): Tracks planning and execution statistics for all SQL statements executed, aiding in performance analysis and tuning
- [pgstattuple](https://neon.com/docs/extensions/pgstattuple): Offers functions to show tuple-level statistics for tables, helping identify bloat and efficiency opportunities
- [tsm_system_rows](https://www.postgresql.org/docs/16/tsm-system-rows.html): Provides a table sampling method that selects a fixed number of table rows randomly
- [tsm_system_time](https://www.postgresql.org/docs/16/tsm-system-time.html): Offers a table sampling method based on system time, enabling consistent sample data retrieval over time

## Orchestration

- [tcn](https://www.postgresql.org/docs/16/tcn.html): Provides a trigger function to notify listeners of changes to a table, allowing applications to respond to changes in the database
- [pg_partman](https://github.com/pgpartman/pg_partman): A partition manager extension that enables creating and managing time-based and number-based table partition sets in Postgres

## Procedural languages

- [plcoffee](https://neon.com/docs/extensions/plv8): Deprecated on Neon. Was a CoffeeScript procedural language that ships with plv8; use plpgsql or app-side logic instead
- [plls](https://neon.com/docs/extensions/plv8): Deprecated on Neon. Was a LiveScript procedural language that ships with plv8; use plpgsql or app-side logic instead
- [plv8](https://neon.com/docs/extensions/plv8): Deprecated on Neon. Was a Postgres procedural language powered by V8 for JavaScript callable from SQL; use plpgsql or app-side logic instead
- [plpgsql](https://www.postgresql.org/docs/16/plpgsql.html): The default procedural language for Postgres, enabling the creation of complex functions and triggers

## Query optimization

- [hypopg](https://hypopg.readthedocs.io/en/rel1_stable/): Provides the ability to create hypothetical (virtual) indexes in Postgres for performance testing
- [pg_hint_plan](https://github.com/ossc-db/pg_hint_plan): Allows developers to influence query plans with hints in SQL comments, improving performance and control over query execution
- [online_advisor](https://neon.com/docs/extensions/online_advisor): Recommends indexes, extended statistics, and prepared statements based on your actual query workload

## Scientific computing

- [cube](https://neon.com/docs/extensions/cube): Implements the cube data type for representing multidimensional cubes in Postgres
- [rdkit](https://github.com/rdkit/rdkit): Integrates the RDKit cheminformatics toolkit with Postgres, enabling chemical informatics operations directly in the database
- [seg](https://www.postgresql.org/docs/16/seg.html): Implements the seg data type for storage and manipulation of line segments or floating-point intervals, useful for representing laboratory measurements
- [unit](https://github.com/df7cb/postgresql-unit): Implements a data type for SI units, plus byte, for storage, manipulation, and calculation of scientific units

## Search

- [citext](https://neon.com/docs/extensions/citext): Provides a case-insensitive character string type that internally calls lower when comparing values in Postgres
- [dict_int](https://neon.com/docs/extensions/dict_int): Provides a text search dictionary template for indexing integer data in Postgres
- [fuzzystrmatch](https://neon.com/docs/extensions/fuzzystrmatch): Provides several functions to determine similarities and distance between strings in Postgres
- [lakebase_text](https://neon.com/docs/extensions/lakebase-text): BM25 keyword and full-text search for Postgres, compatible with tsvector
- [pg_trgm](https://neon.com/docs/extensions/pg_trgm): Provides functions and operators for determining the similarity of alphanumeric text based on trigram matching, and index operator classes for fast string similarity search
- [prefix](https://github.com/dimitri/prefix): A prefix range module that supports efficient queries on text columns with prefix-based searching and matching capabilities
- [unaccent](https://neon.com/docs/extensions/unaccent): A text search dictionary that removes accents from characters, simplifying text search in Postgres

## Security

- [anon](https://neon.com/docs/extensions/postgresql-anonymizer): Provides data masking and anonymization capabilities for protecting personally identifiable information (PII) and sensitive data in Postgres databases
- [pg_session_jwt](https://neon.com/docs/extensions/pg_session_jwt): Handle authenticated sessions through JWTs for use with RLS policies
- [pgcrypto](https://neon.com/docs/extensions/pgcrypto): Offers cryptographic functions, allowing for encryption and hashing of data within Postgres
- [pgjwt](https://github.com/michelp/pgjwt): Implements JSON Web Tokens (JWT) in Postgres, allowing for secure token creation and verification

## Tooling / Admin

- [autoinc](https://www.postgresql.org/docs/current/contrib-spi.html): Provides an autoinc() function that stores the next value of a sequence into an integer field
- [hypopg](https://hypopg.readthedocs.io/en/rel1_stable/): Provides the ability to create hypothetical (virtual) indexes in Postgres for performance testing
- [insert_username](https://www.postgresql.org/docs/current/contrib-spi.html): Automatically inserts the username of the person executing an insert operation into a specified table in Postgres
- [lo](https://www.postgresql.org/docs/16/lo.html): Provides support for managing large objects (LOBs) in Postgres, including a data type lo and a trigger lo_manage
- [neon_utils](https://neon.com/docs/extensions/neon-utils): Provides a function for monitoring how Neon's Autoscaling feature allocates compute resources in response to workload
- [pg_cron](https://neon.com/docs/extensions/pg_cron): Lets you schedule and manage periodic jobs directly in your Postgres database
- [pgtap](https://pgtap.org/documentation.html): A unit testing framework for Postgres, enabling sophisticated testing of database queries and functions
- [refint](https://www.postgresql.org/docs/current/contrib-spi.html): Provides functions for maintaining foreign key constraints

## Remote data access

- [dblink](https://neon.com/docs/extensions/dblink): Provides functions for accessing and manipulating data in remote databases from within Postgres
- [postgres_fdw](https://neon.com/docs/extensions/postgres_fdw): Access data in remote Postgres databases as local tables

--- [Document source](https://neon.com/docs/extensions/fuzzystrmatch.md) ---

> Summary: The `fuzzystrmatch` extension adds fuzzy and phonetic string matching to Postgres using algorithms including Soundex, Levenshtein edit distance, Metaphone/Double Metaphone, and Daitch-Mokotoff Soundex. Use it when queries must tolerate typos, name misspellings, or phonetic variations such as matching "Jon Dow" against "John Doe" or deduplicating customer records. Levenshtein inputs are capped at 255 characters. Soundex and Metaphone functions are unreliable with UTF-8 multibyte encodings; use `daitch_mokotoff` or `levenshtein` for non-ASCII data.

# The fuzzystrmatch extension

Perform fuzzy string matching for names, typos, and similar-sounding words in Postgres

Last updated: 2026-06-05

The `fuzzystrmatch` extension for Postgres provides a suite of functions to determine similarities and distances between strings. This is useful for applications that need to handle misspellings, phonetic variations, or simply find "close enough" matches in text data. Whether you're building a search engine, cleaning customer data, or trying to identify duplicate records, `fuzzystrmatch` offers powerful tools to compare strings beyond exact equality.

Imagine a user searching for "John Doe" but typing "Jon Dow", or needing to match "Smith" with "Smythe". `fuzzystrmatch` provides algorithms like [Soundex](https://en.wikipedia.org/wiki/Soundex), [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance), [Metaphone](https://en.wikipedia.org/wiki/Metaphone), and [Daitch-Mokotoff Soundex](https://en.wikipedia.org/wiki/Daitch%E2%80%93Mokotoff_Soundex) to tackle these challenges.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `fuzzystrmatch` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Core functions and usage

`fuzzystrmatch` offers several algorithms, each with its strengths for different types of string comparisons.

### 1. Soundex

The Soundex system is a phonetic algorithm for indexing names by sound, as pronounced in English. It converts a string into a four-character code, where the first character is the first letter of the string, and the remaining three digits encode the consonants.

**Functions:**

- `soundex(text)` returns `text`: Computes the Soundex code of a string.
- `difference(text, text)` returns `int`: Computes the difference between the Soundex codes of two strings. The result ranges from 0 (no match) to 4 (exact match on Soundex codes).

**Examples:**

The `soundex` function generates the phonetic code, and `difference` measures how similar these codes are.
For instance, names that sound similar often share Soundex codes or have very similar ones:

- Pairs like ("Smith"/"Smythe") and ("John"/"Jon") yield the same Soundex codes (S530 and J500 respectively), indicating they sound very similar. The `difference` function confirms this with a score of 4 (an exact match on the Soundex code).
- Similarly, ("Robert"/"Rupert") both produce the Soundex code R163 and thus also have a `difference` score of 4.
- In contrast, a pair like ("Anne"/"Andrew") yields different Soundex codes (A500 vs A536) and a `difference` score of 2, reflecting a lesser degree of phonetic similarity according to Soundex.

Let's see these in action with SQL:

```sql
SELECT soundex('Smith'), soundex('Smythe');
-- s530, s530

SELECT difference('Smith', 'Smythe');
-- 4

SELECT soundex('John'), soundex('Jon');
-- J500, J500

SELECT difference('John', 'Jon');
-- 4

SELECT soundex('Robert'), soundex('Rupert');
-- R163, R163

SELECT difference('Anne', 'Andrew');
-- 2 (A500 vs A536)
```

**Use case:** Useful for matching English names that sound similar but are spelled differently. Note that Soundex is not very effective for non-English names.

### 2. Levenshtein distance

The Levenshtein distance measures the similarity between two strings by counting the minimum number of single-character edits (insertions, deletions, or substitutions) required to change one string into the other. A lower distance indicates greater similarity.

**Functions:**

- `levenshtein(source text, target text)` returns `int`: Calculates Levenshtein distance with a cost of 1 for each insertion, deletion, or substitution.
- `levenshtein(source text, target text, ins_cost int, del_cost int, sub_cost int)` returns `int`: Calculates Levenshtein distance with specified costs for operations.
- `levenshtein_less_equal(source text, target text, max_d int)` returns `int`: An accelerated version. If the actual distance is less than or equal to `max_d`, it returns the correct distance; otherwise, it returns a value greater than `max_d`. This is faster if you only care about small distances.
- `levenshtein_less_equal(source text, target text, ins_cost int, del_cost int, sub_cost int, max_d int)` returns `int`: Accelerated version with custom costs.

Both `source` and `target` strings can be any non-null strings and be up to 255 characters long.

**Examples:**

The Levenshtein distance quantifies the "edit effort" between strings. Consider these transformations:

1. To change "kitten" to "sitting":

   - Substitute 'k' with 's' (kitten -> sitten)
   - Substitute 'e' with 'i' (sitten -> sittin)
   - Insert 'g' at the end (sittin -> sitting)

   This requires 3 edits, so the Levenshtein distance is 3.

2. To change "apple" to "apply":

   - Substitute 'e' with 'y' (apple -> apply)

   This is 1 edit, giving a distance of 1.

3. If comparing "book" and "back":
   - Substitute 'o' with 'a' (book -> baok)
   - Substitute 'o' with 'c' (baok -> back)
     This requires 2 edits, resulting in a distance of 2.

The function can also take custom costs for insertion, deletion, and substitution, which can be useful for domain-specific needs.

Let's see these in action with SQL:

```sql
-- kitten to sitting (default costs: 1 for ins, del, sub)
SELECT levenshtein('kitten', 'sitting');
-- 3

-- apple to apply
SELECT levenshtein('apple', 'apply');
-- 1

-- book to back
SELECT levenshtein('book', 'back');
-- 2

-- Levenshtein distance is case-sensitive
SELECT levenshtein('book', 'Book');
-- 1

-- Example with custom costs: 1 for ins, 2 for del, 3 for sub
SELECT levenshtein('book', 'back', 1, 2, 3);
-- 6
-- Few possible paths of minimum cost:
-- 2 substitutions(o -> a, o -> c): cost = 2 x 3 (for substitution) = 6)
-- delete 2 o's and insert a c: cost = 2 x 2 (for deletion) + 2 x 1 (for insertion) = 6

-- Using levenshtein_less_equal for efficiency when only small distances matter
SELECT levenshtein_less_equal('banana', 'bandana', 1);
-- Returns 1 (correct, as only one insertion 'd' is needed)

SELECT levenshtein_less_equal('longstringexample', 'short', 2);
-- Returns a value > 2 (actual distance is much higher, so it stops early)
```

**Use case:** Excellent for general typo correction, finding strings with minor differences, and when character-level edit distance is important. Works well with various languages, including those with multibyte encodings. Remember that Levenshtein is case-sensitive.

### 3. Metaphone and double metaphone

Metaphone algorithms, like Soundex, generate phonetic codes for strings. They are generally more accurate than Soundex for English words. Double metaphone provides primary and alternate encodings, offering better support for non-English words.

**Functions:**

- `metaphone(text, max_output_length int)` returns `text`: Computes the metaphone code for a string, up to a specified maximum length.
- `dmetaphone(text)` returns `text`: Computes the primary Double metaphone code.
- `dmetaphone_alt(text)` returns `text`: Computes the alternate Double metaphone code (returns `NULL` if no alternate exists).

**Examples:**

```sql
SELECT metaphone('Michael', 8);
-- MXL

SELECT metaphone('algorithm', 10);
-- ALKR0M

SELECT dmetaphone('Smith'), dmetaphone_alt('Smith');
-- SM0, XMT

SELECT dmetaphone('Schmidt');
-- XMT

SELECT dmetaphone_alt('Schmidt');
-- SMT

-- Primary and alternate for a name with multiple pronunciations
SELECT dmetaphone('Joan'), dmetaphone_alt('Joan'); -- Spanish 'Joan Miró'
-- JN, AN
```

**Use case:** Good for matching English words phonetically. Double Metaphone is an improvement, especially with its alternate codes for handling variations in pronunciation and non-English names.

### 4. Daitch-Mokotoff Soundex

Daitch-Mokotoff (DM) Soundex is another phonetic algorithm, significantly more useful for non-English names than the original Soundex.

**Key improvements over original Soundex:**

- Codes are based on the first six meaningful letters (not four).
- Maps letters/combinations to ten possible codes (not seven).
- Multiple codes can be emitted if a letter/combination has different sounds.

**Function:**

`daitch_mokotoff(source text) returns text[]`: Generates an array of Daitch-Mokotoff Soundex codes for the input string. The result is an array because a name can have multiple plausible pronunciations.

DM codes are 6 digits long. `source` should preferably be a single word or name.

**Examples:**

```sql
SELECT daitch_mokotoff('George');
-- {595000}

SELECT daitch_mokotoff('John');
-- {160000,460000}  (Reflects 'J' vs 'Y' sound possibilities)

SELECT daitch_mokotoff('Bierschbach');
-- {794575,794574,794750,794740,745750,745740,747500,747400}
```

**Matching Daitch-Mokotoff codes:**
Since `daitch_mokotoff` returns an array, you can use the array overlap operator `&&` for matching:

```sql
CREATE TABLE surnames (name TEXT);
INSERT INTO surnames VALUES ('Peterson'), ('Petersen'), ('Pietersen');

SELECT name FROM surnames
WHERE daitch_mokotoff(name) && daitch_mokotoff('Petterson');
```

```
  name
-----------
 Peterson
 Petersen
 Pietersen
(3 rows)
```

**Use case:** Best for phonetic matching of European names, particularly when Soundex is insufficient. Works with multibyte encodings.

## Practical usage scenarios

Let's see how these functions can be applied in common scenarios.

### Finding misspelled names in a customer database

Suppose you have a `customers` table and want to find customers whose names are similar to "Jon Smithe".

```sql
CREATE TABLE customers (id INT, name TEXT);
INSERT INTO customers VALUES
  (1, 'John Smith'),
  (2, 'Jon Smythe'),
  (3, 'Jane Doe'),
  (4, 'Jonathan Smithson');

-- Using Levenshtein distance
SELECT * FROM customers
WHERE levenshtein(lower(name), lower('Jon Smithe')) <= 3;
```

```
 id |      name
----+-----------------
  1 | John Smith
  2 | Jon Smythe
(2 rows)
```

```sql
-- Using Soundex difference
SELECT * FROM customers
WHERE difference(name, 'Jon Smithe') >= 3;
```

```
 id |    name
----+------------
  1 | John Smith
  2 | Jon Smythe
  4 | Jonathan Smithson
(3 rows)
```

### Typo correction in search input

It can be useful to suggest corrections for user input. For example, if a user types "Portgeasql", you can suggest "PostgreSQL":

```sql
WITH potential_matches AS (
  SELECT 'PostgreSQL' AS term
  UNION ALL SELECT 'MySQL'
  UNION ALL SELECT 'SQLite'
)
SELECT term, levenshtein(lower(term), 'portgeasql') AS distance
FROM potential_matches
ORDER BY distance
LIMIT 1;
```

```
   term       | distance
-----------+----------
PostgreSQL |    3
(1 row)
```

Let's say the user types "sequelite" instead of "SQLite":

```sql
WITH potential_matches AS (
  SELECT 'PostgreSQL' AS term
  UNION ALL SELECT 'MySQL'
  UNION ALL SELECT 'SQLite'
)
SELECT term, levenshtein(lower(term), 'sequelite') AS distance
FROM potential_matches
ORDER BY distance
LIMIT 1;
```

```
   term       | distance
-----------+----------
 SQLite    |        3
(1 row)
```

The values can then be used to suggest corrections or alternatives to the user.

## Limitations and considerations

- **Multibyte encodings:** `soundex`, `metaphone`, `dmetaphone`, and `dmetaphone_alt` are not reliable for UTF-8 or other multibyte encodings. Use `daitch_mokotoff` or `levenshtein` for such cases.
- **Phonetic nuances:** Phonetic algorithms simplify pronunciation. They might not always align perfectly with intended pronunciations or capture all linguistic subtleties, potentially leading to false positives or negatives.
- **Computational cost:** Levenshtein distance can be resource-intensive on large datasets without `levenshtein_less_equal` or proper indexing strategies.

## Conclusion

The `fuzzystrmatch` extension is useful for tackling the common problem of inexact string matching. By understanding the strengths and weaknesses of functions like `soundex`, `levenshtein`, `metaphone`, `dmetaphone`, and `daitch_mokotoff`, you can enhance your application's ability to handle typos, phonetic variations, and find similar text data effectively. Always consider the nature of your data (especially language and encoding) and your specific matching requirements when choosing the right function.

## Resources

- [PostgreSQL `fuzzystrmatch` documentation](https://www.postgresql.org/docs/current/fuzzystrmatch.html)
- Algorithms:
  - [Soundex](https://en.wikipedia.org/wiki/Soundex)
  - [Levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance)
  - [Metaphone](https://en.wikipedia.org/wiki/Metaphone)
  - [Daitch-Mokotoff Soundex](https://en.wikipedia.org/wiki/Daitch%E2%80%93Mokotoff_Soundex)

--- [Document source](https://neon.com/docs/extensions/hstore.md) ---

> Summary: The `hstore` extension stores schema-less key-value pairs inside a single Postgres column, with operators like `->`, `?`, `@>`, and `||` for querying, filtering, and updating individual keys. Use it instead of `jsonb` when all keys and values are strings and the data model is flat. It avoids JSON overhead and supports GIN and GiST indexes for key-level filtering on large datasets.

# The hstore extension

Manage key-value pairs in Postgres using hstore

Last updated: 2026-06-05

The `hstore` extension is a flexible way to store and manipulate sets of key-value pairs within a single Postgres value. It works well for semi-structured data or data without a rigid schema.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers the basics of the `hstore` extension - how to enable it, how to store and query key-value pairs, and perform operations on hstore data with examples. `hstore` is valuable in scenarios where schema-less data needs to be stored efficiently, such as in configurations, application settings, or any situation where the data structure may evolve over time.

**Note:** `hstore` is an open-source extension for Postgres that can be installed on any compatible Postgres instance. Detailed installation instructions and compatibility information can be found at [PostgreSQL Extensions](https://www.postgresql.org/docs/current/contrib.html).

**Version availability**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date information.

## Enable the `hstore` extension

Enable the extension by running the following SQL statement in your Postgres client:

```sql
CREATE EXTENSION IF NOT EXISTS hstore;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Example usage

**Creating a table with hstore column**

Consider a table that stores the product catalog for an electronics shop. Each product has a name and a set of attributes that describe it. The attributes for each product are not fixed and may change over time. This makes `hstore` a good choice for storing this data.

```sql
CREATE TABLE product (
   id SERIAL PRIMARY KEY,
   name VARCHAR(255),
   attributes HSTORE
);
```

**Inserting data**

Inserting data into an `hstore` column is done by providing a string containing key-value pairs into the column.

```sql
INSERT INTO product (name, attributes)
VALUES
    ('Desktop', 'brand => HP, price => 900, processor => "Intel Core i5", storage => "1TB HDD"'),
    ('Tablet', 'brand => Apple, price => 500, os => iOS, screen_size => 10.5'),
    ('Smartwatch', 'brand => Garmin, price => 250, water_resistant => true, battery_life => "7 days"'),
    ('Camera', 'brand => Nikon, price => 1200, megapixels => 24, video_resolution => "4K"'),
    ('Laptop', 'brand => Dell, price => 1200, screen_size => 15.6'),
    ('Smartphone', 'brand => Samsung, price => 800, os => Android'),
    ('Headphones', 'brand => Sony, price => 150, wireless => true, color => "Black"');
```

`hstore` stores both keys and values for each record as strings (values can be nulls). For numeric attributes like price and megapixels, they are cast to strings when inserted into the table.

**Querying `hstore` data**

`hstore` columns can be referenced as regular columns in a query. To access the attributes in an `hstore` column, we use the `->` operator.

For example, to retrieve the name and brand for all products with price less than 1000, we can run the following query:

```sql
SELECT name, attributes->'brand' AS brand
FROM product
WHERE (attributes->'price')::INT < 1000;
```

Since the `price` attribute is stored as a string, we need to cast it to an integer before comparing it to 1000. This query returns the following:

```text
| name       | brand   |
|------------|---------|
| Desktop    | HP      |
| Tablet     | Apple   |
| Smartwatch | Garmin  |
| Smartphone | Samsung |
| Headphones | Sony    |
```

## Operators for `hstore` data

`hstore` offers a variety of operators for manipulating and querying key-value pairs. We go over some examples below.

**Check if a key exists**

The `?` operator is used to check if an `hstore` contains a specific key.

```sql
SELECT id, name
FROM product
WHERE attributes ? 'os';
```

This query returns the following:

```text
| id | name       |
|----|------------|
| 2  | Tablet     |
| 6  | Smartphone |
```

**Check if an hstore contains another hstore**

The `@>` operator is used to check if the `hstore` on the left contains the right operand. For example, the query below looks for products that have a `brand` attribute of `Apple`.

```sql
SELECT id, name
FROM product
WHERE attributes @> 'brand => "Apple"';
```

This query returns the following:

```text
| id | name   |
|----|--------|
| 2  | Tablet |
```

**Concatenating two hstore values**

The `||` operator is used to concatenate two `hstore` values. For example, the query below updates the attributes for the product with name `Laptop`.

```sql
UPDATE product
SET attributes = attributes || 'weight => 2.5'
WHERE name = 'Laptop' AND attributes -> 'brand' = 'Dell';
```

To verify, we can run the query below.

```sql
SELECT id, name, attributes -> 'weight' AS weight
FROM product
WHERE name = 'Laptop' AND attributes -> 'brand' = 'Dell';
```

This query returns the following:

```text
| id | name   | weight |
|----|--------|--------|
|  5 | Laptop | 2.5    |
```

**Check if a hstore contains any of the specified keys**

The `?|` operator is used to check if an `hstore` contains any of the keys specified in the right operand. For example, the query below returns all products that have either a `screen_size` or `megapixels` attribute.

```sql
SELECT id, name
FROM product
WHERE attributes ?| ARRAY['screen_size', 'megapixels'];
```

This query returns the following:

```text
| id | name   |
|----|--------|
| 2  | Tablet |
| 4  | Camera |
| 5  | Laptop |
```

## `Hstore` functions

The `hstore` extension also adds functions to manipulate the `hstore` data. We go over some examples below.

**Retrieve all keys**

The `akeys` function returns an array of all the keys in an `hstore` value. For example, the query below returns all the keys for Dell laptop products.

```sql
SELECT id, name, akeys(attributes) AS keys
FROM product
WHERE name = 'Laptop' AND attributes -> 'brand' = 'Dell';
```

This query returns the following:

```text
| id | name   | keys                             |
|----|--------|----------------------------------|
| 1  | Laptop | {brand,price,weight,screen_size} |
```

**Convert hstore to JSON**

The `hstore_to_json` function converts an `hstore` value to `JSON`. For example, the query below converts the `attributes` column to `JSON` for all products with a `brand` attribute of `Apple`.

```sql
SELECT hstore_to_json(attributes) AS attributes
FROM product
WHERE attributes -> 'brand' = 'Apple';
```

**Extract all keys and values**

The `each` function returns the set of key-value pairs for an `hstore` value. For example, the query below returns each attribute of the Nikon Camera as a separate row.

```sql
SELECT id, (each(attributes)).*
FROM product
WHERE name = 'Camera' AND attributes -> 'brand' = 'Nikon';
```

This query returns the following:

```text
| id | key              | value |
|----|------------------|-------|
| 1  | brand            | Nikon |
| 2  | price            | 1200  |
| 3  | megapixels       | 24    |
| 4  | video_resolution | 4K    |
```

## Comparing `hstore` with `JSON`

The `hstore` and `JSON` data types can be both used to store semi-structured data. `Hstore` has a flat data model; both keys and values must be strings. This makes it more efficient for simple key-value data.

In contrast, `JSON` supports a variety of data types, and can also store nested data structures. This makes it more flexible, but trades off some performance.

## Indexing and performance

Indexing can improve the performance of queries involving `hstore` data, particularly for large datasets.

`Hstore` supports the regular `btree` and `hash` indexes. However, this is only useful for equality comparisons of the entire `hstore` value, since these indexes have no knowledge of its substructure.

```sql
CREATE INDEX btree_idx_attributes ON product USING hash (attributes);
```

For queries that involve key-level filtering, like the `@>` or the `?` operators, the `GIN` and `GIST` indexes are more useful. The indexes can be created as shown in this example:

```sql
CREATE INDEX gin_idx_attributes ON product USING gin (attributes);
```

## Conclusion

The `hstore` extension is a flexible option for semi-structured data in Postgres. This guide covers creating records, querying on attributes, and the common operators and functions available for `hstore` data.

## Resources

- [PostgreSQL hstore documentation](https://www.postgresql.org/docs/current/hstore.html)

--- [Document source](https://neon.com/docs/extensions/intarray.md) ---

> Summary: The `intarray` Postgres extension adds functions and operators for NULL-free integer arrays. It enables set operations (union, intersection, overlap, containment) and a `query_int` type for boolean AND/OR/NOT searches. Use it when built-in array functions are too slow for large datasets with overlap or containment queries, common in tagging systems, access control lists, and product categorization. GiST and GIN index classes accelerate `&&`, `@>`, `<@`, and `@@` operators, with tunable parameters like `numranges` and `siglen`.

# The intarray extension

Efficiently manipulate and query integer arrays in Postgres

Last updated: 2026-06-05

The `intarray` extension for Postgres provides functions and operators for handling arrays of integers. It's particularly optimized for arrays that do not contain any `NULL` values, offering significant performance advantages for certain operations compared to Postgres's built-in array functions.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This extension is useful when you need to perform set-like operations (unions, intersections), check for containment or overlap, or conduct indexed searches on integer arrays, common in applications like tagging systems, access control lists, or product categorization.

## Enable the `intarray` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS intarray;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## `intarray` functions

The `intarray` extension provides several useful functions for array manipulation:

- `icount(integer[]) → integer`: Returns the number of elements in the array.
  ```sql
  SELECT icount('{1,2,3,2}'::integer[]);
  -- Result: 4
  ```
- `sort(integer[], dir text) → integer[]`: Sorts the array. `dir` can be 'asc' (ascending) or 'desc' (descending).
  ```sql
  SELECT sort('{1,3,2}'::integer[], 'desc');
  -- Result: {3,2,1}
  ```
- `sort_asc(integer[]) → integer[]`: Sorts the array in ascending order. (Equivalent to `sort(arr, 'asc')`).
  ```sql
  SELECT sort_asc('{11,77,44}'::integer[]);
  -- Result: {11,44,77}
  ```
- `sort_desc(integer[]) → integer[]`: Sorts the array in descending order. (Equivalent to `sort(arr, 'desc')`).
  ```sql
  SELECT sort_desc('{11,77,44}'::integer[]);
  -- Result: {77,44,11}
  ```
- `uniq(integer[]) → integer[]`: Removes _adjacent_ duplicate values from the array. To remove all duplicates, sort the array first.
  ```sql
  SELECT uniq('{1,2,2,3,1,1}'::integer[]);
  -- Result: {1,2,3,1}
  SELECT uniq(sort('{1,2,2,3,1,1}'::integer[]));
  -- Result: {1,2,3}
  ```
- `idx(integer[], item integer) → integer`: Returns the 1-based index of the first occurrence of `item` in the array, or 0 if not found.
  ```sql
  SELECT idx(array[11,22,33,22,11], 22);
  -- Result: 2
  ```
- `subarray(integer[], start_idx integer, len integer) → integer[]`: Extracts a subarray of `len` elements starting from `start_idx` (1-based).
  ```sql
  SELECT subarray('{1,2,3,4,5}'::integer[], 2, 3);
  -- Result: {2,3,4}
  ```
- `subarray(integer[], start_idx integer) → integer[]`: Extracts a subarray from `start_idx` to the end of the array.
  ```sql
  SELECT subarray('{1,2,3,4,5}'::integer[], 3);
  -- Result: {3,4,5}
  ```
- `intset(integer) → integer[]`: Creates a single-element integer array.
  ```sql
  SELECT intset(42);
  -- Result: {42}
  ```

## `intarray` Operators

`intarray` offers set of operators for comparing and manipulating integer arrays:

| Operator      | Description                                                                                                                                                                      | Example                                 | Result      |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- |
| `&&`          | Overlap: Do arrays have at least one element in common?                                                                                                                          | `'{1,2,3}'::int[] && '{3,4,5}'::int[]`  | `true`      |
| `@>`          | Contains: Does the left array contain all elements of the right array?                                                                                                           | `'{1,2,3,4}'::int[] @> '{2,3}'::int[]`  | `true`      |
| `<@`          | Is contained by: Is the left array contained within the right array?                                                                                                             | `'{2,3}'::int[] <@ '{1,2,3,4}'::int[]`  | `true`      |
| `+ integer`   | Add element: Adds an integer to the end of the array.                                                                                                                            | `'{1,2}'::int[] + 3`                    | `{1,2,3}`   |
| `+ integer[]` | Concatenate arrays.                                                                                                                                                              | `'{1,2}'::int[] + '{3,4}'::int[]`       | `{1,2,3,4}` |
| `- integer`   | Remove element: Removes all occurrences of the integer from the array.                                                                                                           | `'{1,2,3,2}'::int[] - 2`                | `{1,3}`     |
| `- integer[]` | Remove elements: Removes elements of the right array from the left array.                                                                                                        | `'{1,2,3,4}'::int[] - '{2,4,5}'::int[]` | `{1,3}`     |
| `\|`          | Union: Computes the union of the two arrays (duplicate elements included unless arrays are pre-sorted and de-duplicated). For set union, consider `uniq(sort(array1 + array2))`. | `'{1,2}'::int[] \| '{2,3}'::int[]`      | `{1,2,2,3}` |
| `&`           | Intersection: Computes the intersection of the two arrays (order and duplicates depend on input).                                                                                | `'{1,2,3}'::int[] & '{2,3,4}'::int[]`   | `{2,3}`     |
| `#` (prefix)  | Number of elements: (Same as `icount` function).                                                                                                                                 | `#'{1,2,3,4}'::int[]`                   | `4`         |
| `#` (infix)   | Index of element in 1-based indexing (Same as `idx` function).                                                                                                                   | `'{10,20,30}'::int[] # 20`              | `2`         |

### `query_int` operators

`intarray` introduces a special data type `query_int` for constructing complex search queries against integer arrays.

- `array @@ query_int → boolean`: Does the array satisfy the `query_int`?
- `query_int ~~ array → boolean`: Commutator for `@@`. Does the array satisfy the `query_int`?

A `query_int` consists of integer values combined with operators:

- `&` (AND)
- `|` (OR)
- `!` (NOT)
  Parentheses `()` can be used for grouping.

Example: `1&(2|3)` matches arrays that contain `1` AND (either `2` OR `3`).

```sql
SELECT '{1,2,7}'::integer[] @@ '1 & (2|3)'::query_int; -- true (1 is present, 2 is present)
SELECT '{1,3,8}'::integer[] @@ '1 & (2|3)'::query_int; -- true (1 is present, 3 is present)
SELECT '1 & (2|3)'::query_int ~~ '{1,3,8}'::integer[]; -- commutator version of the above
SELECT '{1,4,9}'::integer[] @@ '1 & (2|3)'::query_int; -- false (1 is present, but neither 2 nor 3)
SELECT '{2,3,5}'::integer[] @@ '1 & (2|3)'::query_int; -- false (1 is not present)
```

## Example usage

Let's create a table to store an example dataset of articles with tags represented as integer arrays.

```sql
CREATE TABLE articles (
    id SERIAL PRIMARY KEY,
    title TEXT NOT NULL,
    tag_ids INTEGER[] -- This will store an array of integer tag IDs
);

INSERT INTO articles (title, tag_ids) VALUES
    ('Postgres Performance Tips', '{1,2,3}'),
    ('Introduction to SQL', '{2,4}'),
    ('Advanced intarray Usage', '{1,3,5}'),
    ('Database Normalization', '{4,6}');
```

### Basic set operations

Find articles tagged with either tag 2 `OR` tag 5 (overlap):

```sql
SELECT title, tag_ids
FROM articles
WHERE tag_ids && '{2,5}'::integer[];
```

Output:

```text
| title                     | tag_ids |
|---------------------------|---------|
| Postgres Performance Tips | {1,2,3} |
| Introduction to SQL       | {2,4}   |
| Advanced intarray Usage   | {1,3,5} |
```

Find articles tagged with both tag `1` AND tag `2` (contains):

```sql
SELECT title, tag_ids
FROM articles
WHERE tag_ids @> '{1,2}'::integer[];
```

Output:

```text
| title                     | tag_ids |
|---------------------------|---------|
| Postgres Performance Tips | {1,2,3} |
```

Find articles whose tags are fully contained within `{1,2,3,5}` (is contained by):

```sql
SELECT title, tag_ids
FROM articles
WHERE tag_ids <@ '{1,2,3,5}'::integer[];
```

Output:

```text
| title                     | tag_ids |
|---------------------------|---------|
| Postgres Performance Tips | {1,2,3} |
| Advanced intarray Usage   | {1,3,5} |
```

### Array manipulation and combining

Get all unique tags used across articles "Postgres Performance Tips" and "Introduction to SQL":

```sql
SELECT uniq(sort(a1.tag_ids + a2.tag_ids)) AS combined_unique_tags
FROM articles a1, articles a2
WHERE a1.title = 'Postgres Performance Tips' AND a2.title = 'Introduction to SQL';
```

Output:

```text
| combined_unique_tags |
|----------------------|
| {1,2,3,4}            |
```

Find common tags between "Postgres Performance Tips" and "Advanced intarray Usage" (intersection):

```sql
SELECT a1.tag_ids & a2.tag_ids AS common_tags
FROM articles a1
CROSS JOIN articles a2
WHERE a1.title = 'Postgres Performance Tips' AND a2.title = 'Advanced intarray Usage';
```

Output:

```text
| common_tags |
|-------------|
| {1,3}       |
```

Add a new tag `7` to "Introduction to SQL":

```sql
UPDATE articles
SET tag_ids = tag_ids + 7
WHERE title = 'Introduction to SQL'
RETURNING title, tag_ids;
```

Output:

```text
| title                 | tag_ids   |
|-----------------------|-----------|
| Introduction to SQL   | {2,4,7}   |
```

Remove tag `2` from "Postgres Performance Tips":

```sql
UPDATE articles
SET tag_ids = tag_ids - 2
WHERE title = 'Postgres Performance Tips'
RETURNING title, tag_ids;
```

Output:

```text
| title                     | tag_ids |
|---------------------------|---------|
| Postgres Performance Tips | {1,3}   |
```

### Using `query_int` for complex searches

Find articles tagged with `1` AND (either `3` OR `4`):

```sql
SELECT title, tag_ids
FROM articles
WHERE tag_ids @@ '1 & (3|4)'::query_int;
```

```text
| title                     | tag_ids |
|---------------------------|---------|
| Advanced intarray Usage   | {1,3,5} |
| Postgres Performance Tips |  {1,3}  |
```

### Using `intarray` functions

Find the index of tag `3` in "Postgres Performance Tips":

```sql
SELECT title, idx(tag_ids, 3) AS index_of_tag_3
FROM articles
WHERE title = 'Postgres Performance Tips';
```

Output:

```text
| title                     | index_of_tag_3 |
|---------------------------|----------------|
| Postgres Performance Tips |       2        |
```

## Indexing with `intarray`

`intarray` provides excellent indexing capabilities for its operators, which is crucial for performance on large datasets. It supports both GiST and GIN indexes. These indexes can accelerate queries using `&&`, `@>`, `<@`, `@@`, and array equality.

### GiST Index operator classes

- `gist__int_ops`: Suitable for small to medium-sized datasets. It approximates an integer set as an array of integer ranges.
  - Optional parameter: `numranges` (default 100, range 1-253). Defines the maximum number of ranges in an index key. Larger values lead to more precise (faster) searches but larger indexes.
- `gist__intbig_ops`: Better for large datasets (columns with many distinct array values). It approximates an integer set as a bitmap signature.
  - Optional parameter: `siglen` (default 16 bytes, range 1-2024 bytes). Defines the signature length. Longer signatures mean more precise searches but larger indexes.

> GiST index doesn't benefit from `<@` operator.

**Example GiST Index:**

To create a GiST index on `tag_ids` using `gist__intbig_ops` with a signature length of 32 bytes:

```sql
CREATE INDEX idx_articles_tag_ids_gist ON articles USING GIST (tag_ids gist__intbig_ops (siglen = 32));
```

To use the `gist__int_ops`:

```sql
CREATE INDEX idx_articles_tag_ids_gist_default ON articles USING GIST (tag_ids gist__int_ops);
```

You can also specify parameters for `gist__int_ops`, for example:

```sql
CREATE INDEX idx_articles_tag_ids_gist_custom_ranges ON articles USING GIST (tag_ids gist__int_ops (numranges = 50));
```

### GIN Index operator class

`gin__int_ops`: This is a non-default GIN operator class. It supports `&&`, `@>`, `@@`, and also `<@`.

**Example GIN Index:**

```sql
CREATE INDEX idx_articles_tag_ids_gin ON articles USING GIN (tag_ids gin__int_ops);
```

## Practical applications

- **Tagging systems:** Efficiently find items associated with specific tags, combinations of tags, or overlapping tag sets.
- **Access Control Lists (ACLs):** Store group memberships or resource permissions as integer arrays and quickly check if a user (belonging to certain groups) has access to a resource.
- **Product categorization:** Manage products belonging to multiple categories and find products based on category inclusion/exclusion criteria.
- **Recommendation engines:** Identify items with similar properties by checking for overlaps in their feature ID arrays.

## Conclusion

The `intarray` extension adds functions and operators for managing and querying integer arrays in Postgres, with significant performance improvements for complex array operations.

## Resources

- [PostgreSQL `intarray` documentation](https://www.postgresql.org/docs/current/intarray.html)

--- [Document source](https://neon.com/docs/extensions/lakebase-text.md) ---

> Summary: The lakebase_text extension adds the lakebase_bm25 index type to Lakebase Postgres for BM25 full-text search. It requires no migration from PostgreSQL's built-in full-text search — standard tsvector types and tsquery operators work unchanged. Use this page to enable the extension, create a lakebase_bm25 index, query with the <@> operator and to_bm25query function, configure the default_limit and prefilter GUCs, set fallback parameters at the index level, and reference all types, operators, functions, and index parameters.

# The lakebase_text extension

BM25 full-text search for Lakebase Postgres

Last updated: 2026-07-31

The `lakebase_text` extension adds a `lakebase_bm25` index type to Postgres for [BM25](https://en.wikipedia.org/wiki/Okapi_BM25) full-text search. It is a native upgrade to PostgreSQL's built-in full-text search: standard `tsvector` type and query operators work unchanged; only the index type changes.

See [Lakebase Search](https://neon.com/docs/ai/lakebase-search) for the architecture and the companion `lakebase_vector` extension.

## Why lakebase_text?

PostgreSQL's built-in full-text search uses GIN indexes with `tsvector`. GIN works well for boolean filtering, but it has two limitations for search relevance:

- **No BM25 ranking.** GIN uses `ts_rank`, which does not use global corpus statistics, so scores degrade as data grows. BM25 is more accurate, accounting for term frequency, document length, and corpus-wide statistics together.
- **No top-K pushdown.** GIN must score all matching documents even when you only need the top 10. For large tables, this means significant unnecessary work on every query.

`lakebase_bm25` adds a first-class BM25 index with Block-Max WAND top-K pushdown: the index returns only the K most relevant results directly, without scoring the entire match set. It fully preserves standard `tsvector` types and existing query operators. No application logic changes are required.

## Enable the lakebase_text extension

Install the extension in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor):

```sql
CREATE EXTENSION IF NOT EXISTS lakebase_text;
```

`lakebase_text` requires Postgres 16 or later. It has no extension dependencies; unlike `lakebase_vector`, it does not require `pgvector`.

`lakebase_text` relies on a preloaded library that Neon enables by default. If you've customized your project's [preloaded libraries](https://neon.com/docs/extensions/pg-extensions#extensions-with-preloaded-libraries), make sure `lakebase_text` is in the list.

### Upgrade the extension and indexes

A new Lakebase Search release can add features, fixes, and performance improvements. Although Lakebase Search is released as part of Neon updates, it does not upgrade everything automatically. In `lakebase_text`, two things upgrade separately and carry version numbers that are unrelated to each other:

- **The extension version** is the version of the SQL objects that `CREATE EXTENSION lakebase_text` creates, including its data types, functions, operators, and the `lakebase_bm25` index access method. This version is reported by `SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_text'`. `ALTER EXTENSION lakebase_text UPDATE` updates this version.
- **The index storage format** is the on-disk layout of a `lakebase_bm25` index. The extension may introduce updated index storage formats in an update, unlocking more features and delivering better performance. All newly created indexes automatically use the latest storage format, while existing indexes can be upgraded to the new format using `REINDEX INDEX CONCURRENTLY` after a newer storage format is available.

Upgrading is not urgent. The extension is compatible with SQL objects and index storage formats from older versions, but staying current keeps you on the supported, best-performing path and avoids a larger migration later, so upgrade when convenient rather than deferring indefinitely.

**Note:** The latest available extension version is reported by `SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_text'`.

## Quick start

Create a table with a `tsvector` column and insert data:

```sql
CREATE TABLE documents (
    id serial PRIMARY KEY,
    passage text,
    vector tsvector
);

INSERT INTO documents (passage, vector) VALUES
('PostgreSQL is a powerful, open-source object-relational database system.', to_tsvector('english', 'PostgreSQL is a powerful, open-source object-relational database system.')),
('Full-text search is a technique for searching in plain-text documents.', to_tsvector('english', 'Full-text search is a technique for searching in plain-text documents.')),
('BM25 is a ranking function used by search engines to estimate document relevance.', to_tsvector('english', 'BM25 is a ranking function used by search engines to estimate document relevance.')),
('PostgreSQL provides advanced features like full-text search and window functions.', to_tsvector('english', 'PostgreSQL provides advanced features like full-text search and window functions.')),
('Effective ranking algorithms like BM25 improve information retrieval results.', to_tsvector('english', 'Effective ranking algorithms like BM25 improve information retrieval results.'));
```

Create a `lakebase_bm25` index on the `tsvector` column:

```sql
CREATE INDEX documents_passage_bm25 ON documents USING lakebase_bm25 (vector);
```

**Important: Create the index after inserting data**

`lakebase_bm25` computes corpus-wide statistics (document count, term frequencies) at index build time and updates them at VACUUM time. Create the index after your initial data load. After bulk-loading a large amount of new data, run `VACUUM` manually to keep BM25 scores accurate.

Set how many results the index returns and run a BM25 search:

```sql
SET lakebase_bm25.default_limit TO 5;

SELECT
  id,
  vector <@> to_bm25query(to_tsvector('english', 'PostgreSQL'), 'documents_passage_bm25') AS score
FROM documents
ORDER BY score
LIMIT 5;
```

The `<@>` operator calculates the negative BM25 score of a document against a query. Ordering by score ascending returns the most relevant documents first (lower negative score = higher relevance).

`to_bm25query` constructs a `bm25query_tsvector` value by combining the query `tsvector` with the object identifier of the BM25 index. The index identifier is required because BM25 scoring depends on corpus-wide statistics stored in the index.

**Note:** A `lakebase_bm25` index scan can omit any number of rows whose `<@>` value is exactly `0.0`. Do not rely on zero-distance rows being returned or on their order. To evaluate every row, set `lakebase_bm25.enable_scan` to `off` to use a sequential scan instead.

## Keep the index accurate

BM25 statistics are computed at index build time and updated by VACUUM. For most workloads, regular VACUUM keeps scores accurate. After bulk-loading a large amount of new data, run VACUUM manually:

```sql title="PostgreSQL"
VACUUM documents;
```

To maintain query and update performance, `VACUUM` must clean the index promptly. For a table dedicated to text search, Neon recommends setting `autovacuum_vacuum_insert_scale_factor` to `0` so the insert-triggered autovacuum threshold does not grow with the table:

```sql title="PostgreSQL"
ALTER TABLE documents SET (
  autovacuum_vacuum_insert_scale_factor = 0
);
```

With the scale factor set to `0`, `autovacuum_vacuum_insert_threshold` determines the fixed number of inserted tuples that triggers autovacuum. Tune that threshold based on your workload.

**Warning:** BM25 global statistics are not MVCC-versioned. If `VACUUM` updates the statistics while a transaction is using an older MVCC snapshot, the transaction can calculate scores using statistics newer than its row snapshot. Row visibility remains MVCC-compliant, but scores, rankings, and top-K results can change within a `REPEATABLE READ` transaction. Do not rely on snapshot-stable BM25 rankings across a concurrent `VACUUM`, including autovacuum.

## Configure default_limit

The `lakebase_bm25.default_limit` GUC controls how many results the index returns before PostgreSQL applies any `LIMIT` clause from your query. The default is `1000`.

```sql
-- Return at most 10 results from the index
SET lakebase_bm25.default_limit TO 10;
```

Setting this value to match your query's `LIMIT` avoids unnecessary work when you only need a small top-K result set.

## Fallback parameters

You can store search parameters directly in an index as storage parameters, rather than setting them per session or transaction with GUCs. This is useful when you have multiple indexes, prefer not to set GUCs, or want to configure search behavior offline.

Set `default_limit` at index creation:

```sql
CREATE INDEX documents_passage_bm25 ON documents USING lakebase_bm25 (vector)
WITH (default_limit = 5);
```

Queries against this index use `default_limit = 5` without requiring a `SET` command:

```sql
SELECT
  id,
  vector <@> to_bm25query(to_tsvector('english', 'PostgreSQL'), 'documents_passage_bm25') AS score
FROM documents
ORDER BY score
LIMIT 5;
```

Update a storage parameter on an existing index:

```sql
ALTER INDEX documents_passage_bm25 SET (default_limit = 10);
```

GUCs take precedence over index storage parameters when both are set. To avoid hard-to-diagnose behavior, use only one method at a time.

## Prefilter

In a filtered query, PostgreSQL applies `WHERE` conditions after the index scan returns results. If your filter eliminates many rows, the index may return far more results than your `LIMIT` requires.

The `lakebase_bm25.prefilter` GUC enables the index to evaluate filter conditions before computing BM25 scores, pruning the search space early:

```sql
SET lakebase_bm25.default_limit TO 5;
SET lakebase_bm25.prefilter = on;

SELECT
  id,
  vector <@> to_bm25query(to_tsvector('english', 'PostgreSQL'), 'documents_passage_bm25') AS score
FROM documents
WHERE id % 1000 = 0
ORDER BY score
LIMIT 5;
```

Prefilter is recommended when the filter is **strict** (eliminates many rows) or **unpredictable** (eliminates an unknown number of rows), and **cheap to evaluate** (much cheaper than computing BM25 scores). Enabling it for a loose or expensive filter may be slower than the default.

## Reference

### Types

| Type                 | Description                                                                                                   |
| :------------------- | :------------------------------------------------------------------------------------------------------------ |
| `bm25query_tsvector` | Combines a query `tsvector` with the object identifier of a BM25 index. Passed as the right operand to `<@>`. |

### Operators

| Operator | Arguments                        | Result   | Description                                                                                                                               |
| :------- | :------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `<@>`    | `tsvector`, `bm25query_tsvector` | `double` | Returns the negative BM25 score of a document against a query, in the context of the BM25 index. Order ascending for most-relevant-first. |

### Operator classes

| Operator class      | Default | Operator                            |
| :------------------ | :------ | :---------------------------------- |
| `tsvector_bm25_ops` | Yes     | `<@>(tsvector, bm25query_tsvector)` |

### Functions

| Function                                       | Returns              | Description                                                                                          |
| :--------------------------------------------- | :------------------- | :--------------------------------------------------------------------------------------------------- |
| `to_bm25query(query tsvector, index regclass)` | `bm25query_tsvector` | Constructs a `bm25query_tsvector` from a query `tsvector` and the object identifier of a BM25 index. |

### Index storage parameters

| Parameter       | Type    | Default | Domain       | Description                                                                      |
| :-------------- | :------ | :------ | :----------- | :------------------------------------------------------------------------------- |
| `k1`            | real    | `1.2`   | `[1.2, 2.0]` | BM25 `k1` parameter. Controls term frequency saturation.                         |
| `b`             | real    | `0.75`  | `[0.0, 1.0]` | BM25 `b` parameter. Controls document length normalization.                      |
| `default_limit` | integer | `1000`  | `[1, 65535]` | Fallback value for `lakebase_bm25.default_limit`. GUCs take precedence when set. |
| `prefilter`     | boolean | `false` | —            | Fallback value for `lakebase_bm25.prefilter`. GUCs take precedence when set.     |

### Search parameters (GUCs)

| GUC                           | Type    | Default | Description                                                                                           |
| :---------------------------- | :------ | :------ | :---------------------------------------------------------------------------------------------------- |
| `lakebase_bm25.default_limit` | integer | `1000`  | Controls how many results the index returns. Set to match your query's `LIMIT` for best performance.  |
| `lakebase_bm25.prefilter`     | boolean | `false` | Enables filter evaluation before BM25 score computation. Recommended for strict, cheap filters.       |
| `lakebase_bm25.enable_scan`   | boolean | `on`    | Enables or disables `lakebase_bm25` index scans. Set to `off` for testing to force a sequential scan. |

--- [Document source](https://neon.com/docs/extensions/lakebase-tokenizer.md) ---

> Summary: The lakebase_tokenizer extension adds configurable whole-word tokenization and Chinese, Japanese, and Korean morphological analysis to Postgres full-text search, with normalization, custom stop words, synonyms, and English stemming.

# The lakebase_tokenizer extension

Configurable tokenization for Postgres full-text search

Last updated: 2026-10-24

The `lakebase_tokenizer` extension adds configurable tokenization to Postgres full-text search, including whole-word processing and morphological analysis for Chinese, Japanese, and Korean (CJK) text. Text-search configurations built with the extension work with `to_tsvector`, the `@@` operator, ranking functions, and GIN indexes. You can also use generated `tsvector` values with [`lakebase_text`](https://neon.com/docs/extensions/lakebase-text) for BM25 ranking.

The extension provides the `tokenizer_wholeword` and `tokenizer_morph` templates through Postgres's standard text-search dictionary interface. Use `tokenizer_wholeword` for whole-word processing, including lowercase conversion, Unicode normalization, accent removal, English possessive removal, custom stop words, one-to-one synonyms, and English stemming. Use `tokenizer_morph` for CJK morphological analysis.

## Install the extension

Install the extension in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor). The examples on this page use a dedicated schema so the extension objects are easy to identify:

```sql
CREATE SCHEMA IF NOT EXISTS tokenizer_ext;
CREATE EXTENSION IF NOT EXISTS lakebase_tokenizer WITH SCHEMA tokenizer_ext;
```

`lakebase_tokenizer` requires Postgres 16 or later. The extension is relocatable. You can replace `tokenizer_ext` with another schema when you install it.

### Upgrade the extension

Neon ships new Lakebase Search releases as part of its regular updates, but it doesn't upgrade the extension in your database for you. To see which version you have and which is available:

```sql
SELECT installed_version, default_version
FROM pg_available_extensions
WHERE name = 'lakebase_tokenizer';
```

To upgrade, run:

```sql
ALTER EXTENSION lakebase_tokenizer UPDATE;
```

There's no rush. Older versions keep working, but upgrading when it's convenient keeps you on the supported version and saves you a bigger jump later.

`ALTER EXTENSION` doesn't regenerate stored `tsvector` values or rebuild GIN or `lakebase_bm25` indexes. That only matters when a release changes how text is tokenized. Upgrading from 0.1.x to 0.2.0 doesn't: 0.2.0 adds the [`tokenizer_morph`](https://neon.com/docs/extensions/lakebase-tokenizer#template-tokenizermorph) template and the built-in CJK configurations and leaves your existing configurations alone, so you don't need to reindex.

## Quick start

Choose a path based on the language of your text:

- For English and other whitespace-delimited languages, create a dictionary from the `tokenizer_wholeword` template.
- For Chinese, Japanese, or Korean text, use a built-in configuration. You don't need to create a dictionary.

### Whole-word text

The following example creates a dictionary from the `tokenizer_wholeword` template, then maps common Postgres token types to it in a text-search configuration:

```sql
CREATE TEXT SEARCH DICTIONARY documents_dict (
  TEMPLATE          = tokenizer_ext.tokenizer_wholeword,
  Lowercase         = 'true',
  StripAccents      = 'true',
  Stemmer           = 'english'
);

CREATE TEXT SEARCH CONFIGURATION documents_cfg (COPY = pg_catalog.simple);

ALTER TEXT SEARCH CONFIGURATION documents_cfg
  ALTER MAPPING FOR asciiword, word, numword, hword_numpart, hword_part, hword_asciipart
  WITH documents_dict;
```

Use the configuration to produce a `tsvector`, create a GIN index, and run full-text queries:

```sql
CREATE TABLE documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('documents_cfg', body)
  ) STORED
);

INSERT INTO documents (body) VALUES
  ('Cats are running near the café.'),
  ('A dog is sleeping in the house.');

CREATE INDEX documents_search_idx ON documents USING gin (search_vector);

SELECT id, body
FROM documents
WHERE search_vector @@ plainto_tsquery('documents_cfg', 'running café');
```

Use the same text-search configuration for documents and queries so both sides apply the same tokenization strategy and options.

### CJK text

Installing the extension creates the `tokenizer_chinese`, `tokenizer_japanese`, and `tokenizer_korean` text-search configurations. Use one of them directly to produce a `tsvector`, create a GIN index, and run full-text queries:

**Chinese**

```sql
CREATE TABLE chinese_documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('tokenizer_ext.tokenizer_chinese', body)
  ) STORED
);

INSERT INTO chinese_documents (body) VALUES
  ('现代分布式文件系统架构');

CREATE INDEX chinese_idx ON chinese_documents USING gin (search_vector);

-- Use plainto_tsquery for the built-in Chinese configuration's mixed mode.
SELECT id, body
FROM chinese_documents
WHERE search_vector @@ plainto_tsquery('tokenizer_ext.tokenizer_chinese', '现代分布式');
```

**Japanese**

```sql
CREATE TABLE japanese_documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('tokenizer_ext.tokenizer_japanese', body)
  ) STORED
);

INSERT INTO japanese_documents (body) VALUES
  ('関西国際空港へのアクセス');

CREATE INDEX japanese_idx ON japanese_documents USING gin (search_vector);

SELECT id, body
FROM japanese_documents
WHERE search_vector @@ to_tsquery('tokenizer_ext.tokenizer_japanese', '関西国際空港');
```

**Korean**

```sql
CREATE TABLE korean_documents (
  id            BIGSERIAL PRIMARY KEY,
  body          TEXT NOT NULL,
  search_vector TSVECTOR GENERATED ALWAYS AS (
    to_tsvector('tokenizer_ext.tokenizer_korean', body)
  ) STORED
);

INSERT INTO korean_documents (body) VALUES
  ('선생님께서 도서관에 갑니다');

CREATE INDEX korean_idx ON korean_documents USING gin (search_vector);

SELECT id, body
FROM korean_documents
WHERE search_vector @@ to_tsquery('tokenizer_ext.tokenizer_korean', '선생님께서');
```

## Template: `tokenizer_wholeword`

### How it works

For each token passed to the dictionary by Postgres's text-search parser, `tokenizer_wholeword` applies these operations:

1. `Lowercase`: Convert the token to lowercase.
2. `Normalize`: Apply Unicode normalization.
3. `StripAccents`: Remove accents.
4. `EnglishPossessive`: Remove an English possessive suffix when at least one character remains.
5. `Stopwords`: Emit no lexeme and stop processing if the token matches a configured stop word. The token is omitted from the generated `tsvector`.
6. `Synonyms`: Emit the configured replacement and stop processing if the token matches a synonym.
7. `Stemmer`: If no synonym matched and stemming is enabled, apply the English stemmer.

### Add stop words and synonyms

The `tokenizer_wholeword` template can load custom stop words and synonyms from the extension-managed `lakebase_tokenizer_stopwords` and `lakebase_tokenizer_synonyms` SQL tables. The `name` column groups rows into a set that you select with the `Stopwords` or `Synonyms` dictionary option.

```sql
INSERT INTO tokenizer_ext.lakebase_tokenizer_stopwords (name, word) VALUES
  ('app_stopwords', 'the'),
  ('app_stopwords', 'and'),
  ('app_stopwords', 'or');

INSERT INTO tokenizer_ext.lakebase_tokenizer_synonyms (name, word, synonym) VALUES
  ('app_synonyms', 'usa', 'united_states'),
  ('app_synonyms', 'uk', 'united_kingdom');
```

Reference the sets when you create or alter a `tokenizer_wholeword` dictionary:

```sql
ALTER TEXT SEARCH DICTIONARY documents_dict (
  Stopwords = 'app_stopwords',
  Synonyms  = 'app_synonyms'
);
```

The extension compares stop words and synonym source words with each token after applying `Lowercase`, `Normalize`, `StripAccents`, and `EnglishPossessive`, but before applying `Stemmer`. Catalog entries are not transformed automatically, so store them in the exact form produced by those enabled options:

- With `Lowercase = 'true'`, use lowercase entries. With `Lowercase = 'false'`, capitalization must match the token.
- With `Normalize` enabled, store entries in the selected Unicode normalization form.
- With `StripAccents = 'true'`, store the accent-stripped form. For example, store `cafe` to match `café`.
- Store the form before stemming. For example, with `Stemmer = 'english'`, a `run` entry does not match `running`. Add `running` to filter or replace that token.

Set names can contain up to 256 bytes. Words and synonyms can contain up to 1024 bytes. Each named stop-word or synonym set can contain up to 100,000 rows.

A synonym replacement is emitted exactly as stored and is not processed by the stemmer. Synonyms support one replacement for each source word. To represent a multiword replacement as one lexeme, use a separator such as an underscore, as in `united_states`.

After changing a set, the owner of each dictionary that references the set must run a no-op `ALTER TEXT SEARCH DICTIONARY` to force a reload:

```sql
ALTER TEXT SEARCH DICTIONARY documents_dict (dummy);
```

The `dummy` option does not exist on `tokenizer_wholeword`. Omitting a value asks Postgres to remove this nonexistent option, which invalidates the cache without changing any of the dictionary's configured options.

After reloading the dictionary, regenerate the stored `tsvector` values by rewriting the source rows:

```sql
UPDATE documents SET body = body;
```

### Roles and access

Use two roles to separate application access from tokenizer administration. The examples assume these roles already exist:

- `app_role` uses existing dictionaries. It needs `USAGE` on the relevant schemas and `SELECT` on the extension catalog tables, but it does not need to own the dictionaries.
- `tokenizer_admin` manages stop-word and synonym sets, creates and owns dictionaries and text-search configurations, and runs the reload command after changing a set.

Grant access to the extension schema and catalog tables:

```sql
GRANT USAGE ON SCHEMA tokenizer_ext TO app_role, tokenizer_admin;

GRANT SELECT ON
  tokenizer_ext.lakebase_tokenizer_stopwords,
  tokenizer_ext.lakebase_tokenizer_synonyms
TO app_role;

GRANT SELECT, INSERT, UPDATE, DELETE ON
  tokenizer_ext.lakebase_tokenizer_stopwords,
  tokenizer_ext.lakebase_tokenizer_synonyms
TO tokenizer_admin;
```

`tokenizer_admin` also needs `CREATE` on the schema where dictionaries and text-search configurations are stored. Create these objects as `tokenizer_admin`, or transfer their ownership to it. Write access to the catalog tables does not grant ownership of existing dictionaries.

### Options

Specify `tokenizer_wholeword` options in `CREATE TEXT SEARCH DICTIONARY` or `ALTER TEXT SEARCH DICTIONARY`. Option names are case-insensitive.

| Option              | Type                                    | Default | Description                                                                                                                                                                                                              |
| :------------------ | :-------------------------------------- | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Lowercase`         | boolean                                 | `true`  | Converts tokens to lowercase before applying other operations. `Stemmer = 'english'` requires `Lowercase = 'true'`.                                                                                                      |
| `Normalize`         | `NFC`, `NFD`, `NFKC`, `NFKD`, or `none` | `none`  | Applies the selected Unicode normalization form. This canonicalizes the representation but does not remove characters. For example, `NFC` makes precomposed `é` and `e` followed by a combining acute accent equivalent. |
| `EnglishPossessive` | boolean                                 | `true`  | Removes a trailing `'s`, `'s`, or `'s` when at least one character precedes the suffix. A standalone suffix remains unchanged.                                                                                           |
| `StripAccents`      | boolean                                 | `false` | Applies NFKD normalization and removes combining marks. For example, `café` becomes `cafe`. When this option is enabled, omit `Normalize` because the NFKD step makes any separate Unicode normalization redundant.      |
| `Stopwords`         | set name                                | None    | Uses the named set from `tokenizer_ext.lakebase_tokenizer_stopwords`.                                                                                                                                                    |
| `Synonyms`          | set name                                | None    | Uses the named set of one-to-one replacements from `tokenizer_ext.lakebase_tokenizer_synonyms`.                                                                                                                          |
| `Stemmer`           | `english`                               | None    | Uses the bundled Snowball 3.1.0 English stemmer. Omit this option to disable stemming. The stemmer does not include a stop-word list.                                                                                    |

### Catalog tables

| Table                          | Columns                                  | Description                                                                                        |
| :----------------------------- | :--------------------------------------- | :------------------------------------------------------------------------------------------------- |
| `lakebase_tokenizer_stopwords` | `name text`, `word text`                 | Stores named stop-word sets for `tokenizer_wholeword`. The primary key is `(name, word)`.          |
| `lakebase_tokenizer_synonyms`  | `name text`, `word text`, `synonym text` | Stores named one-to-one replacements for `tokenizer_wholeword`. The primary key is `(name, word)`. |

## Template: `tokenizer_morph`

The `tokenizer_morph` template analyzes Chinese, Japanese, and Korean text for Postgres full-text search. Use a built-in text-search configuration or define a custom one to control term generation.

### How it works

`tokenizer_morph` uses the Lindera analyzer with bundled dictionaries: Jieba for Chinese, IPADIC for Japanese, and MeCab KoDic for Korean.

For Korean parser tokens, `tokenizer_morph` first replaces `ㆍ` (U+318D) with a token boundary.

For each token passed to the dictionary by Postgres's text-search parser, `tokenizer_morph` applies these operations in order:

1. `Normalize`: Apply Unicode normalization to the parser token.
2. `Language`: Segment the parser token with the selected language analyzer.
3. Symbol filter: Discard segments that contain no letters or digits.
4. Language-specific analysis: Turn each remaining segment into zero or more terms, as described below.
5. `Lowercase`: Convert each term to lowercase.
6. `Stemmer`: If enabled, stem terms made entirely of ASCII letters with the bundled English stemmer. This step does not stem CJK terms.

The language-specific analysis step applies these rules:

**Chinese**

- Subword expansion: In `mixed` mode, add the two-character and three-character terms that the bundled dictionary contains.

**Japanese**

- Part-of-speech filtering: Discard recognized particles, auxiliary verbs, conjunctions, fillers, non-verbal sounds, non-alphabetic symbols, and segments tagged `その他,間投`.
- Base-form conversion: Use the dictionary base form of each remaining recognized segment when available. Otherwise, keep its surface form.
- Stop-word filtering: Discard terms that match the built-in list of common Japanese function words.
- Katakana stemming: Remove a trailing `ー` from a term of at least four characters whose characters all fall in the katakana block (U+30A0 to U+30FF).

**Korean**

- Decomposition: In `discard` and `mixed` modes, split a recognized compound, inflected, or preanalyzed segment when the dictionary provides its components. `discard` emits the components in place of the full term, and `mixed` emits both.
- Part-of-speech filtering: Apply filtering to the full term and to each component independently. Omit terms tagged as particles, endings, affixes, adverbs, determiners, interjections, punctuation, symbols, or unanalyzable forms.
- Hangul reading conversion: Use the dictionary's Hangul reading for a retained full term when available. Components keep their dictionary form.

Postgres's text-search parser splits text at whitespace and punctuation before calling `tokenizer_morph`. Each parser token can contain up to 2046 bytes. Longer tokens are skipped with a `NOTICE`. Most Chinese, Japanese, and Korean characters use 3 bytes in UTF-8, so a run of more than 682 of these characters without whitespace or punctuation is omitted from `to_tsvector` results.

### Supported languages and modes

The available modes depend on the language. Each example shows source text → emitted terms.

| Language | Mode      | Behavior                                                                                       | Example                                                              |
| :------- | :-------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------- |
| Chinese  | `none`    | Emits words from standard segmentation without adding shorter search terms.                    | `现代分布式文件系统架构` → `现代`, `分布式文件系统`, `架构`                                |
| Chinese  | `mixed`   | Keeps words from standard segmentation and adds shorter search terms from some longer words.   | `现代分布式文件系统架构` → `现代`, `分布式文件系统`, `分布`, `分布式`, `布式`, `文件`, `系统`, `架构` |
| Japanese | `none`    | Favors longer dictionary compounds.                                                            | `関西国際空港へのアクセス` → `関西国際空港`, `アクセス`                                    |
| Japanese | `discard` | Produces finer-grained terms for some long compounds without retaining their full form.        | `関西国際空港へのアクセス` → `関西`, `国際`, `空港`, `アクセス`                            |
| Korean   | `none`    | Keeps compound and inflected dictionary entries as whole terms.                                | `한국어 형태소 분석` → `한국어`, `형태소`, `분석`                                    |
| Korean   | `discard` | Emits the parts of a compound or inflected form instead of the full term when it can be split. | `한국어 형태소 분석` → `한국`, `어`, `형태`, `소`, `분석`                            |
| Korean   | `mixed`   | Emits both the full term and its parts when a compound or inflected form can be split.         | `한국어 형태소 분석` → `한국어`, `한국`, `어`, `형태소`, `형태`, `소`, `분석`              |

In `mixed` mode, query with `plainto_tsquery`. When one query word produces multiple lexemes, `to_tsquery`, `websearch_to_tsquery`, and `phraseto_tsquery` join them with the `<->` operator, which requires adjacent positions. `mixed` mode inserts extra positions for the additional terms, so these phrase conditions can miss expected matches. For position-based queries, define a custom configuration with `none` or `discard` mode.

### Use the built-in configurations

The extension provides these text-search configurations in its installation schema:

| Configuration        | Dictionary                | Language | Mode      |
| :------------------- | :------------------------ | :------- | :-------- |
| `tokenizer_chinese`  | `tokenizer_chinese_dict`  | Chinese  | `mixed`   |
| `tokenizer_japanese` | `tokenizer_japanese_dict` | Japanese | `discard` |
| `tokenizer_korean`   | `tokenizer_korean_dict`   | Korean   | `discard` |

All three dictionaries set `Stemmer = 'english'` and use the defaults `Normalize = 'NFKC'` and `Lowercase = 'true'`.

For end-to-end examples that use these configurations, see [CJK text](https://neon.com/docs/extensions/lakebase-tokenizer#cjk-text).

### Define a custom configuration

To choose another mode or change the default options, create a dictionary from the `tokenizer_morph` template and a text-search configuration that maps Postgres token types to it. This example uses Chinese `none` mode for phrase queries:

```sql
CREATE TEXT SEARCH DICTIONARY chinese_none_dict (
  TEMPLATE = tokenizer_ext.tokenizer_morph,
  Language = 'chinese',
  Mode = 'none',
  Stemmer = 'english'
);

CREATE TEXT SEARCH CONFIGURATION chinese_none_cfg (COPY = pg_catalog.simple);

ALTER TEXT SEARCH CONFIGURATION chinese_none_cfg
  ALTER MAPPING FOR asciiword, word, numword, hword_asciipart, hword_part, hword_numpart
  WITH chinese_none_dict;

SELECT to_tsvector('chinese_none_cfg', '现代分布式文件系统架构')
  @@ phraseto_tsquery('chinese_none_cfg', '分布式文件系统 架构');
```

### Options

Specify `tokenizer_morph` options in `CREATE TEXT SEARCH DICTIONARY` or `ALTER TEXT SEARCH DICTIONARY`. Option names are case-insensitive.

| Option      | Type                               | Default  | Description                                                                                                                                                                                      |
| :---------- | :--------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Language`  | `chinese`, `japanese`, or `korean` | Required | Selects the language-specific analyzer.                                                                                                                                                          |
| `Mode`      | `none`, `discard`, or `mixed`      | Required | Controls compound and subword output. Supported modes depend on `Language`: `none` or `mixed` for Chinese, `none` or `discard` for Japanese, and `none`, `discard`, or `mixed` for Korean.       |
| `Normalize` | `NFC`, `NFKC`, or `none`           | `NFKC`   | Normalizes text before segmentation. `NFC` preserves compatibility distinctions. For example, full-width `ＡＢＣ` is lowercased to `ａｂｃ` instead of being converted to `abc`, so it is not stemmed. |
| `Lowercase` | boolean                            | `true`   | Converts emitted lexemes to lowercase. `Stemmer = 'english'` requires `Lowercase = 'true'`.                                                                                                      |
| `Stemmer`   | `english`                          | None     | Stems only lexemes made entirely of ASCII letters. Omit this option to disable English stemming.                                                                                                 |

## Use BM25 ranking with lakebase_text

Text-search configurations built with `lakebase_tokenizer` produce standard Postgres `tsvector` values that are compatible with `lakebase_text`. To use BM25 relevance ranking and top-K retrieval, create a `lakebase_bm25` index on the same `tsvector` column. For installation, index creation, and query syntax, see [The lakebase_text extension](https://neon.com/docs/extensions/lakebase-text).

--- [Document source](https://neon.com/docs/extensions/lakebase-vector.md) ---

> Summary: The lakebase_vector extension adds the lakebase_ann index type to Lakebase Postgres for fast approximate nearest-neighbor vector search. It requires no migration from pgvector — the same vector types, distance operators, and query syntax work unchanged. Use this page to enable the extension, create a lakebase_ann index, configure build_mode, tune search with the lakebase_ann.probes, lakebase_ann.epsilon, and lakebase_ann.prefilter GUCs, and reference all operator classes and index options.

# The lakebase_vector extension

Fast approximate nearest-neighbor vector search for Lakebase Postgres

Last updated: 2026-09-09

The `lakebase_vector` extension adds the `lakebase_ann` index type to Postgres for approximate nearest-neighbor (ANN) vector search. It is a drop-in companion to `pgvector`: the same `vector` types, distance operators, and query syntax work unchanged; only the index type changes.

See [Lakebase Search](https://neon.com/docs/ai/lakebase-search) for the architecture and the companion `lakebase_text` extension.

## Why lakebase_vector?

`lakebase_ann` uses IVF (Inverted File) partitioning combined with RaBitQ quantization, an architecture built to scale beyond what HNSW can reach. HNSW indexes must fit entirely in memory and traverse the graph with random I/O at query time, which limits how far they can scale. IVF partitions the vector space into lists and searches only the most relevant ones at query time, enabling sequential I/O rather than random pointer-chasing. RaBitQ compresses vectors 4–8x, reducing the index size and enabling index builds 50–100x faster than HNSW. Together, this scales to **over 1 billion vectors on a single index** while keeping cold starts fast and query performance stable.

There is no migration involved. `lakebase_vector` inherits all `pgvector` data types and operators. You can create a `lakebase_ann` index on your existing `pgvector` columns without changing your schema or application code.

## Enable the lakebase_vector extension

Install the extension in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor):

```sql
CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;
```

`lakebase_vector` requires Postgres 16 or later. The `CASCADE` option automatically installs `pgvector` if it is not already installed, since `lakebase_vector` depends on it.

`lakebase_vector` relies on a preloaded library that Neon enables by default. If you've customized your project's [preloaded libraries](https://neon.com/docs/extensions/pg-extensions#extensions-with-preloaded-libraries), make sure `lakebase_vector` is in the list.

### Upgrade the extension and indexes

A new Lakebase Search release can add features, fixes, and performance improvements. Although Lakebase Search is released as part of Neon updates, it does not upgrade everything automatically. In `lakebase_vector`, two things upgrade separately and carry version numbers that are unrelated to each other:

- **The extension version** is the version of the SQL objects that `CREATE EXTENSION lakebase_vector` creates, including its data types, functions, operators, and the `lakebase_ann` index access method. This version is reported by `SELECT installed_version FROM pg_available_extensions WHERE name = 'lakebase_vector'`. `ALTER EXTENSION lakebase_vector UPDATE` updates this version.
- **The index storage format** is the on-disk layout of a `lakebase_ann` index. The extension may introduce updated index storage formats in an update, unlocking more features and delivering better performance. All newly created indexes automatically use the latest storage format, while existing indexes can be upgraded to the new format using `REINDEX INDEX CONCURRENTLY` after a newer storage format is available.

Upgrading is not urgent. The extension is compatible with SQL objects and index storage formats from older versions, but staying current keeps you on the supported, best-performing path and avoids a larger migration later, so upgrade when convenient rather than deferring indefinitely.

**Note:** The latest available extension version is reported by `SELECT default_version FROM pg_available_extensions WHERE name = 'lakebase_vector'`.

The latest storage format version is `_2`. The following query finds all indexes that use an older storage format. You can then rebuild them to the latest storage format with `REINDEX INDEX` or `REINDEX INDEX CONCURRENTLY`:

```sql title="PostgreSQL"
SELECT oid::regclass AS index, lakebase_ann_index_info(oid::regclass)::json ->> 'version' AS storage_format_version
FROM pg_class
WHERE relam = (SELECT oid FROM pg_am WHERE amname = 'lakebase_ann') AND relkind = 'i';
```

**Note:** `REINDEX INDEX CONCURRENTLY` allows reads and writes to continue, but it takes longer.

## Quick start

Create a table with a `vector` column and insert some data:

```sql
CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));

INSERT INTO items (embedding)
SELECT ARRAY[random(), random(), random()]::real[]
FROM generate_series(1, 1000);
```

Create a `lakebase_ann` index on the embedding column:

```sql
CREATE INDEX items_embedding_idx ON items
  USING lakebase_ann (embedding vector_l2_ops);
```

Query using the standard `pgvector` syntax:

```sql
SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;
```

## Index tuning

Set `build_mode` at index creation to control the accuracy/speed tradeoff:

- `standard` (default): balances recall and index build time. Use for most workloads.
- `quality`: improves recall but takes significantly longer to build. Use it only for tables with up to 50 million vectors.

```sql
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (build_mode = 'standard');
```

The `fast` build mode remains supported for backward compatibility.

By default, `lakebase_ann` chooses lists based on the statistics of the table and the configuration of the index. Set `lists` to control the partition layout explicitly:

```sql
CREATE INDEX ON items USING lakebase_ann (embedding vector_l2_ops)
WITH (lists = '1000');
```

Before tuning, call `lakebase_ann_index_info(index_name)` to get the index's `lists`, `default_probes`, and `default_epsilon` values.

Use `lakebase_ann.probes` at query time to control how many inverted file (IVF) partitions are searched. Higher values improve recall at the cost of latency. The default value `'auto'` provides a balanced tradeoff between them. For finer control, use `lakebase_ann_advise` to [get recommended probes values](https://neon.com/docs/extensions/lakebase-vector#get-recommended-probes-values).

The shape of `probes` must match the shape of `lists`. Call `lakebase_ann_index_info` to find your `lists` array, then set one value for a one-level index or two comma-separated values for a two-level index:

| `lists` from index info | `probes` to set |
| :---------------------- | :-------------- |
| `[]` (empty)            | `''`            |
| `[222]`                 | `'22'`          |
| `[3333, 33333]`         | `'33, 333'`     |

**Note:** On a small dataset, `lakebase_ann` uses exact (flat) search instead of IVF partitioning, and `lakebase_ann_index_info` returns empty `lists` and `default_probes`. In this case, leave `probes` set to `''`. When `lists` isn't empty, a `probes` value whose shape doesn't match `lists` causes an error.

```sql
-- Check your index's lists array first
SELECT lakebase_ann_index_info('items_embedding_idx');

-- Then set probes to match the shape of lists.
-- One-level index (single-value lists): set one value.
SET lakebase_ann.probes TO '10';

-- Two-level index: set two ascending comma-separated values, for example '10, 20'.
-- Flat index (empty lists): leave probes set to ''.

SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 10;
```

`lakebase_ann.epsilon` controls how many candidates are reranked using full-precision distances. Higher values rerank more candidates and take longer. The default value of `'auto'` works well for most workloads. During flat search on a small dataset, `epsilon` still controls full-precision reranking.

### Get recommended probes values

`lakebase_ann_advise`, `lakebase_ann_tune`, `lakebase_ann_latency`, and `lakebase_ann_sample` require `lakebase_vector` 1.1.2 and above. To check your installed version and update the extension, see [Upgrade the extension and indexes](https://neon.com/docs/extensions/lakebase-vector#upgrade-the-extension-and-indexes).

`lakebase_ann_advise` returns candidate `probes` values in increasing order of recall, from 0.5 to 0.9 in steps of 0.1 and 0.91 to 0.99 in steps of 0.01. Each row includes estimated recall and the query latency measured after warmup. Use real queries from your search workload as input. If they're unavailable, sample vectors from the indexed table with `lakebase_ann_sample`. The following examples show both options:

```sql
-- Option 1: real queries in a separate table
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
  'items_embedding_idx'::regclass,
  ARRAY(
    SELECT embedding FROM queries
    WHERE embedding IS NOT NULL
    LIMIT 512
  )
);

-- Option 2: sampled from the indexed table
-- NULL::items specifies items as the table to sample from.
SELECT probes, recall, avg_ms, p50_ms, p95_ms
FROM lakebase_ann_advise(
  'items_embedding_idx'::regclass,
  ARRAY(
    SELECT embedding FROM lakebase_ann_sample(NULL::items, 512)
    WHERE embedding IS NOT NULL
  )
);
```

| Column                       | Description                                                                     |
| :--------------------------- | :------------------------------------------------------------------------------ |
| `probes`                     | A `lakebase_ann.probes` value.                                                  |
| `recall`                     | Estimated recall\@10 for the sample queries.                                    |
| `avg_ms`, `p50_ms`, `p95_ms` | Average, median, and 95th percentile latency of a single query in milliseconds. |

Choose the fastest row that meets your recall target, then apply its `probes` value:

```sql
SET lakebase_ann.probes TO '10';
```

Recall and latency are estimated for top-10 queries with `lakebase_ann.epsilon` set to `1.9`, which can differ from your actual queries. Before you use a `probes` value in production, verify its recall and latency on your workload if possible.

If the index has empty `lists`, `lakebase_ann_advise` returns no rows because there is nothing to tune.

On large indexes, a `lakebase_ann_advise` call can take more than 20 minutes. More query vectors make the call slower. Start with 512 query vectors to balance recall accuracy and run time.

`lakebase_ann_advise` calls `lakebase_ann_tune` to get recommended `probes` values, then `lakebase_ann_latency` to measure their latency. You can also use either `lakebase_ann_tune` or `lakebase_ann_latency` on its own. See [Functions](https://neon.com/docs/extensions/lakebase-vector#functions).

`lakebase_ann_advise` and `lakebase_ann_tune` require table-level `SELECT` on the indexed table, and return an error if [row-level security (RLS)](https://neon.com/docs/guides/row-level-security) applies to your role on that table. `lakebase_ann_sample` and `lakebase_ann_latency` apply RLS policies and only read rows that your role can see.

### Prefilter

By default, Postgres applies non-vector filter conditions after the ANN index returns candidate rows. Enable `lakebase_ann.prefilter` to evaluate those conditions before full-precision distance reranking:

```sql
SET lakebase_ann.prefilter TO on;

SELECT * FROM items
WHERE id % 100 = 0
ORDER BY embedding <-> '[3,1,2]'
LIMIT 10;
```

Prefiltering works best when the filter is cheap to evaluate and removes most rows. Leave it off for filters that match many rows or require expensive calculations, since evaluating the filter inside the index can add overhead.

When you set these GUCs from application code, the `SET` and the query must run on the same session. With a connection pool or the [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver), where each statement can use a different connection, issue both in a single transaction so the `SET` applies to the query.

### Index build time

Larger `shared_buffers` can significantly reduce index build time. Neon enables this optimization only on [larger fixed-size computes](https://neon.com/docs/manage/computes#how-to-size-your-compute). Check the current value before optimizing an index build:

```sql title="PostgreSQL"
SHOW shared_buffers;
```

If `shared_buffers` is 1 GB or less, consider temporarily resizing to a larger fixed-size compute before starting the index build.

You can also speed up index creation by increasing the number of parallel workers.

The `max_parallel_maintenance_workers` configuration parameter sets the maximum number of parallel workers that can be started by a single utility command such as `CREATE INDEX`.

The `max_parallel_workers` configuration parameter sets the maximum number of workers that the compute can support for parallel operations. Values of `max_parallel_maintenance_workers` above this limit have no effect.

The `max_worker_processes` configuration parameter sets the maximum number of background processes that the compute can support. Neon [manages this setting](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size) based on compute size. Values of `max_parallel_workers` above this limit have no effect.

```sql title="PostgreSQL"
SHOW max_worker_processes;
-- Set both values to the desired parallelism minus one.
SET max_parallel_workers = 15;
SET max_parallel_maintenance_workers = 15;
```

### Concurrent index updates

`CREATE INDEX CONCURRENTLY` and `REINDEX INDEX CONCURRENTLY` allow reads and writes to continue while an index is built or rebuilt:

```sql title="PostgreSQL"
CREATE INDEX CONCURRENTLY items_embedding_idx_concurrent ON items
  USING lakebase_ann (embedding vector_l2_ops);

REINDEX INDEX CONCURRENTLY items_embedding_idx_concurrent;
```

## Prewarm an index

Use `lakebase_ann_prewarm` after a compute starts to load the frequently accessed parts of an index into memory. The `scope` argument accepts the following values:

- `search` (default): Prewarms the full hot portion used for search.
- `routing`: Prewarms only the routing structures. This option is faster and provides a better cost-performance tradeoff for large indexes.

```sql title="PostgreSQL"
-- Prewarm the full search scope
SELECT lakebase_ann_prewarm('items_embedding_idx');

-- Prewarm only routing structures
SELECT lakebase_ann_prewarm('items_embedding_idx', scope => 'routing');
```

## Reference

### Operator classes

`lakebase_ann` supports the following operator classes. Each class provides two operators:

- A **pgvector distance operator** (`<->`, `<#>`, `<=>`) that returns a distance and is used in `ORDER BY` for nearest-neighbor search.
- A **`lakebase_vector` range operator** (`<<->>`, `<<#>>`, `<<=>>`) that takes a `sphere_*` value on its right side and returns a `boolean`: true when the vector falls within the sphere's radius. Use it in a `WHERE` clause to filter by similarity. Build the sphere with the `sphere(vector, radius)` function.

| Operator class       | Distance operator (`ORDER BY`) | Range operator (`WHERE`)         |
| :------------------- | :----------------------------- | :------------------------------- |
| `vector_l2_ops`      | `<->(vector, vector)`          | `<<->>(vector, sphere_vector)`   |
| `vector_ip_ops`      | `<#>(vector, vector)`          | `<<#>>(vector, sphere_vector)`   |
| `vector_cosine_ops`  | `<=>(vector, vector)`          | `<<=>>(vector, sphere_vector)`   |
| `halfvec_l2_ops`     | `<->(halfvec, halfvec)`        | `<<->>(halfvec, sphere_halfvec)` |
| `halfvec_ip_ops`     | `<#>(halfvec, halfvec)`        | `<<#>>(halfvec, sphere_halfvec)` |
| `halfvec_cosine_ops` | `<=>(halfvec, halfvec)`        | `<<=>>(halfvec, sphere_halfvec)` |
| `rabitq8_l2_ops`     | `<->(rabitq8, rabitq8)`        | `<<->>(rabitq8, sphere_rabitq8)` |
| `rabitq8_ip_ops`     | `<#>(rabitq8, rabitq8)`        | `<<#>>(rabitq8, sphere_rabitq8)` |
| `rabitq8_cosine_ops` | `<=>(rabitq8, rabitq8)`        | `<<=>>(rabitq8, sphere_rabitq8)` |
| `rabitq4_l2_ops`     | `<->(rabitq4, rabitq4)`        | `<<->>(rabitq4, sphere_rabitq4)` |
| `rabitq4_ip_ops`     | `<#>(rabitq4, rabitq4)`        | `<<#>>(rabitq4, sphere_rabitq4)` |
| `rabitq4_cosine_ops` | `<=>(rabitq4, rabitq4)`        | `<<=>>(rabitq4, sphere_rabitq4)` |

To filter by similarity, wrap the query vector in `sphere(vector, radius)` and use the range operator in a `WHERE` clause. Rank the matches with the corresponding distance operator:

```sql
-- Rows within cosine radius 0.5 of the query vector, closest first
SELECT * FROM items
WHERE embedding <<=>> sphere('[3,1,2]'::vector, 0.5)
ORDER BY embedding <=> '[3,1,2]'
LIMIT 5;
```

The range operator returns a `boolean`, so it belongs in `WHERE`, not `ORDER BY`. Use the distance operator (`<=>` here) to order results.

The `rabitq8` and `rabitq4` types are quantization types defined by `lakebase_vector`. They offer reduced memory footprint at the cost of some precision.

Pick the operator class that matches how your embeddings were trained, and use the same metric for the index and your queries:

- **Cosine** (`vector_cosine_ops`, `<=>`) suits most text embeddings and is the common default.
- **L2 / Euclidean** (`vector_l2_ops`, `<->`) fits cases where absolute distance matters and vectors aren't normalized.
- **Inner product** (`vector_ip_ops`, `<#>`) is for vectors pre-normalized to unit length; for unit vectors it matches cosine and is typically faster.

The `halfvec`, `rabitq8`, and `rabitq4` families provide the same three metrics with smaller, quantized storage.

### Functions

| Function                                                              | Returns                                                                  | Description                                                                                                                                                                                                                                                        |
| :-------------------------------------------------------------------- | :----------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lakebase_ann_prewarm(regclass, scope text DEFAULT 'search')`         | void                                                                     | Loads frequently accessed index data into memory. Valid `scope` values are `search` and `routing`.                                                                                                                                                                 |
| `lakebase_ann_index_info(regclass)`                                   | text                                                                     | Returns index metadata as JSON text, including `version`, `lists`, `default_probes`, and `default_epsilon`.                                                                                                                                                        |
| `lakebase_ann_advise(regclass, vector[] \| halfvec[])`                | `TABLE(probes text, recall real, avg_ms real, p50_ms real, p95_ms real)` | Recommends `lakebase_ann.probes` values for the sample query vectors, with estimated recall\@10 and measured latency. Requires table-level `SELECT` on the indexed table. Not supported when RLS applies to your role. Requires `lakebase_vector` 1.1.2 and above. |
| `lakebase_ann_tune(regclass, vector[] \| halfvec[])`                  | `TABLE(probes text, recall real)`                                        | Recommends `lakebase_ann.probes` values for the sample query vectors, with estimated recall\@10. Requires table-level `SELECT` on the indexed table. Not supported when RLS applies to your role. Requires `lakebase_vector` 1.1.2 and above.                      |
| `lakebase_ann_latency(regclass, text[], vector[] \| halfvec[])`       | `TABLE(probes text, avg_ms real, p50_ms real, p95_ms real)`              | Measures the average, median, and 95th percentile query latency of the index for each `lakebase_ann.probes` value in the `text[]` array. Requires `lakebase_vector` 1.1.2 and above.                                                                               |
| `lakebase_ann_sample(NULL::<table>, sample_size integer DEFAULT 128)` | `SETOF` the table's row type                                             | Samples up to `sample_size` rows from the table specified by `NULL::<table>`. Requires `lakebase_vector` 1.1.2 and above.                                                                                                                                          |

### Index options

| Option       | Type   | Default      | Description                                                                                                                                                                                                                                                                                              |
| :----------- | :----- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build_mode` | string | `'standard'` | Controls the accuracy/speed tradeoff. Use `'quality'` for better recall at the cost of a significantly longer index build. `'fast'` remains supported for backward compatibility.                                                                                                                        |
| `lists`      | string | `'auto'`     | Sets the IVF partition layout. With `'auto'`, the extension chooses a value based on the statistics of the table and the configuration of the index. Set a single integer such as `'1000'` for a one-level index, or two ascending comma-separated integers such as `'100, 1000'` for a two-level index. |

### Search parameters

| GUC                      | Type   | Default  | Description                                                                                                                                                                 |
| :----------------------- | :----- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `lakebase_ann.probes`    | string | `'auto'` | Number of IVF partitions to scan at each level. Higher values improve recall at the cost of latency. The shape must match the `lists` array from `lakebase_ann_index_info`. |
| `lakebase_ann.epsilon`   | string | `'auto'` | Controls how many candidates are reranked using full-precision distances. Higher values rerank more candidates and take longer.                                             |
| `lakebase_ann.prefilter` | enum   | `off`    | Evaluates non-vector filters before full-precision distance reranking. Valid values are `on` and `off`. Best for cheap filters that remove most candidate rows.             |

--- [Document source](https://neon.com/docs/extensions/ltree.md) ---

> Summary: The `ltree` Postgres extension adds a native data type for storing hierarchical label paths. It provides operators like `<@` and `@>` for ancestor/descendant queries, `~` for lquery pattern matching, and functions like `nlevel()`, `subpath()`, and `lca()` for tree traversal. Use it instead of recursive CTEs or adjacency list models when querying org charts, category trees, file system paths, or any parent-child hierarchy. GiST indexes accelerate ancestor/descendant lookups; B-tree indexes suit equality comparisons on `ltree` columns.

# The ltree extension

Store and query hierarchical tree-like structures in Postgres

Last updated: 2026-06-05

The `ltree` extension provides a data type for representing labels of data stored in a hierarchical tree-like structure. It offers specialized functions and operators for efficiently traversing and searching through these tree structures, making it ideal for modeling hierarchical relationships in your data.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers the basics of the `ltree` extension - how to enable it, create hierarchical data structures, and query tree data with examples. The `ltree` extension is valuable for scenarios like organizational charts, file systems, category hierarchies, or any data that naturally fits into a parent-child relationship model.

**Note:** `ltree` is an open-source extension for Postgres that can be installed on any compatible Postgres instance. Detailed information about the extension is available in the [PostgreSQL Documentation](https://www.postgresql.org/docs/current/ltree.html).

**Version availability**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date information.

## Enable the `ltree` extension

Enable the extension by running the following SQL statement in your Postgres client:

```sql
CREATE EXTENSION IF NOT EXISTS ltree;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Understanding ltree data

The `ltree` data type represents a path of labels separated by dots, similar to file system paths. Each label consists of alphanumeric characters and underscores, with a maximum length of 255 characters.

Here are some examples of valid `ltree` values:

```
world
world.europe.uk
world.europe.uk.london
tech.database.postgres.extensions
```

The dots in these paths represent hierarchical relationships, with each segment being a label in the tree. This structure allows for efficient traversal and querying of hierarchical data.

## Example usage

Let's explore how to use the `ltree` extension with a practical example of a product category hierarchy for an e-commerce platform.

**Creating a table with ltree column**

First, let's create a table to store our product categories:

```sql
CREATE TABLE product_categories (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    path ltree NOT NULL
);
```

**Inserting hierarchical data**

Now, let's insert some sample data representing a product category hierarchy:

```sql
INSERT INTO product_categories (name, path) VALUES
    ('Electronics', 'electronics'),
    ('Computers', 'electronics.computers'),
    ('Laptops', 'electronics.computers.laptops'),
    ('Gaming Laptops', 'electronics.computers.laptops.gaming'),
    ('Business Laptops', 'electronics.computers.laptops.business'),
    ('Desktop Computers', 'electronics.computers.desktops'),
    ('Smartphones', 'electronics.smartphones'),
    ('Android Phones', 'electronics.smartphones.android'),
    ('iOS Phones', 'electronics.smartphones.ios'),
    ('Clothing', 'clothing'),
    ('Men''s Clothing', 'clothing.mens'),
    ('Women''s Clothing', 'clothing.womens'),
    ('Children''s Clothing', 'clothing.childrens');
```

## Querying ltree data

The `ltree` extension provides several operators and functions for querying hierarchical data. Let's explore some common query patterns:

**Finding all descendants of a node**

To find all subcategories under "Computers", we can use the `<@` operator, which checks if the path on the right is an ancestor of the path on the left:

```sql
SELECT id, name, path
FROM product_categories
WHERE path <@ 'electronics.computers';
```

This query returns:

```text
| id | name               | path                                   |
|----|--------------------|----------------------------------------|
| 2  | Computers          | electronics.computers                  |
| 3  | Laptops            | electronics.computers.laptops          |
| 4  | Gaming Laptops     | electronics.computers.laptops.gaming   |
| 5  | Business Laptops   | electronics.computers.laptops.business |
| 6  | Desktop Computers  | electronics.computers.desktops         |
```

**Finding all ancestors of a node**

To find all parent categories of "Gaming Laptops", we can use the `@>` operator, which checks if the path on the left is an ancestor of the path on the right:

```sql
SELECT id, name, path
FROM product_categories
WHERE path @> 'electronics.computers.laptops.gaming';
```

This query returns:

```text
| id | name           | path                                     |
|----|----------------|------------------------------------------|
| 1  | Electronics    | electronics                              |
| 2  | Computers      | electronics.computers                    |
| 3  | Laptops        | electronics.computers.laptops            |
| 4  | Gaming Laptops | electronics.computers.laptops.gaming     |
```

**Finding nodes at a specific level**

To find all categories at the second level of the hierarchy, we can use the `nlevel()` function, which returns the number of labels in an `ltree` path:

```sql
SELECT id, name, path
FROM product_categories
WHERE nlevel(path) = 2;
```

This query returns:

```text
| id | name               | path                   |
|----|--------------------|------------------------|
| 2  | Computers          | electronics.computers  |
| 7  | Smartphones        | electronics.smartphones|
| 11 | Men's Clothing     | clothing.mens          |
| 12 | Women's Clothing   | clothing.womens        |
| 13 | Children's Clothing| clothing.childrens     |
```

**Pattern matching with wildcards**

The `ltree` extension supports pattern matching using the `~` operator with a `lquery` pattern. The `lquery` syntax allows for wildcards and other pattern matching features:

```sql
-- Find all laptop categories (using * wildcard)
SELECT id, name, path
FROM product_categories
WHERE path ~ 'electronics.computers.laptops.*';
```

This query returns:

```text
| id | name             | path                                   |
|----|------------------|----------------------------------------|
| 4  | Gaming Laptops   | electronics.computers.laptops.gaming   |
| 5  | Business Laptops | electronics.computers.laptops.business |
```

You can also use more complex patterns:

```sql
-- Find categories that match a specific pattern
-- * matches zero or more labels
SELECT id, name, path
FROM product_categories
WHERE path ~ '*.*.ios'
```

This would match paths like `electronics.smartphones.ios`.

## Advanced ltree operations

The `ltree` extension provides several advanced operations for working with hierarchical data:

**Extracting subpaths**

You can extract specific parts of an `ltree` path using the `subpath()` function:

```sql
-- Extract the first two labels from the path
SELECT id, name, subpath(path, 0, 2) AS subpath
FROM product_categories
WHERE path = 'electronics.computers.laptops.gaming';
```

This query returns:

```text
| id | name           | subpath               |
|----|----------------|-----------------------|
| 4  | Gaming Laptops | electronics.computers |
```

**Finding the least common ancestor**

The `lca()` function finds the least common ancestor of a set of paths:

```sql
-- Find the least common ancestor of gaming laptops and business laptops
SELECT lca(
    'electronics.computers.laptops.gaming'::ltree,
    'electronics.computers.laptops.business'::ltree
) AS common_ancestor;
```

This query returns:

```text
| common_ancestor               |
|-------------------------------|
| electronics.computers.laptops |
```

**Calculating the distance between nodes**

You can calculate the "distance" between two nodes in the tree:

```sql
-- Calculate the distance between two categories
SELECT
    nlevel('electronics.computers.laptops.gaming'::ltree) +
    nlevel('electronics.smartphones.android'::ltree) -
    2 * nlevel(lca(
        'electronics.computers.laptops.gaming'::ltree,
        'electronics.smartphones.android'::ltree
    )) AS distance;
```

This query returns:

```text
| distance |
|----------|
| 5        |
```

The distance is calculated as the sum of the levels of both paths minus twice the level of their least common ancestor.

## Indexing ltree data

For efficient querying of `ltree` data, especially in large datasets, you should create appropriate indexes:

```sql
-- Create a GiST index for ancestor/descendant queries
CREATE INDEX idx_path_gist ON product_categories USING GIST (path);

-- Create a B-tree index for equality queries
CREATE INDEX idx_path_btree ON product_categories USING BTREE (path);
```

The GiST index is particularly useful for ancestor/descendant queries using the `@>` and `<@` operators, while the B-tree index is better for equality comparisons.

## Practical applications

The `ltree` extension is useful in many real-world scenarios:

1. **Organization charts**: Representing company hierarchies with departments, teams, and employees
2. **File systems**: Modeling directory structures
3. **E-commerce categories**: As demonstrated in our example
4. **Taxonomies**: Biological classifications, knowledge categorization
5. **Menu structures**: Website navigation hierarchies
6. **Geographic hierarchies**: Continent > Country > State > City

## Conclusion

The `ltree` extension gives you a data type and operators for hierarchical data in Postgres. It's more efficient for tree-like structures than traditional recursive queries or adjacency list models.

By using `ltree`, you can simplify complex hierarchical data operations, improve query performance, and create more maintainable code for applications that deal with nested structures.

## Resources

- [PostgreSQL ltree documentation](https://www.postgresql.org/docs/current/ltree.html)
- [Indexing strategies for ltree](https://www.postgresql.org/docs/current/ltree.html#id-1.11.7.31.7)

--- [Document source](https://neon.com/docs/extensions/migrate-pg-search-to-lakebase-text.md) ---

# Migrate from pg_search to lakebase_text

Move BM25 full-text search from the deprecated pg_search extension to the lakebase_text extension

Last updated: 2026-09-27

**Warning: pg_search is deprecated**

`pg_search` (ParadeDB) was deprecated on Neon: new installs were blocked, and existing installs were retired on **September 21, 2026**. [`lakebase_text`](https://neon.com/docs/extensions/lakebase-text) is its replacement for BM25 search.

This guide migrates your BM25 full-text search from `pg_search` to `lakebase_text`. You map your existing indexes and queries to their `lakebase_text` equivalents, verify the results, then remove `pg_search`. `lakebase_text` runs BM25 search through a `lakebase_bm25` index built on standard Postgres `tsvector` types.

## What changes

`pg_search` and `lakebase_text` both do BM25 search, but they model it differently:

|                  | `pg_search` (ParadeDB)                                                                     | `lakebase_text`                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| Index            | `USING bm25 (col1, col2) WITH (key_field='id')`: indexes raw columns, tokenizes internally | `USING lakebase_bm25 (body_tsv)`: indexes a `tsvector` column you build with `to_tsvector` |
| Query operator   | `col @@@ 'query'` (filters and ranks at once)                                              | `@@ to_tsquery('query')` to filter, `<@> to_bm25query(…, 'index_name')` to rank            |
| Ranking          | `paradedb.score(id)` with `ORDER BY score DESC` (higher = better)                          | `<@>` returns a negative score with `ORDER BY score ASC` (lower = better)                  |
| Multiple columns | one index over several columns                                                             | combine the columns into one `tsvector`                                                    |
| Tokenization     | internal (ICU, Lindera, language stemmers)                                                 | Postgres text-search configurations (`'english'`, and others)                              |

The main difference: `pg_search` indexes your columns directly, while `lakebase_text` indexes a `tsvector` that you build (usually a generated column).

## Enable lakebase_text

Before you migrate, `lakebase_text` needs to be enabled on your project. Check what's loaded:

```sql
SHOW shared_preload_libraries;
```

If `lakebase_text` is in the list, create the extension and you're ready:

```sql
CREATE EXTENSION IF NOT EXISTS lakebase_text;
```

If `lakebase_text` isn't listed, enabling it is a one-time setup: add it to your project's preloaded libraries with the Neon API, restart the compute, then create the extension. The [Get started with Lakebase Search](https://neon.com/docs/ai/lakebase-search-get-started) guide has the full steps. For this migration you need only `lakebase_text`, not `lakebase_vector`. Leave `pg_search` enabled while you migrate.

## Migrate the index

The examples below use a `mock_items(description, category)` table as a stand-in for your existing table. Substitute your own table and column names.

With `pg_search`, you create a BM25 index over your columns and designate a `key_field`:

```sql
-- pg_search
CREATE INDEX mock_items_search ON mock_items
  USING bm25 (id, description, category) WITH (key_field = 'id');
```

With `lakebase_text`, you build a `tsvector` from the same columns and index that. A `GENERATED ALWAYS` column keeps it in sync as rows change:

```sql
-- lakebase_text
ALTER TABLE mock_items ADD COLUMN search_tsv tsvector
  GENERATED ALWAYS AS (to_tsvector('english', coalesce(description, '') || ' ' || coalesce(category, ''))) STORED;

CREATE INDEX mock_items_bm25 ON mock_items USING lakebase_bm25 (search_tsv);
```

To search a single column instead of several, point `to_tsvector` at just that column. `'english'` is one of several built-in [Postgres text-search configurations](https://www.postgresql.org/docs/current/textsearch.html); list the ones available on your database with `SELECT cfgname FROM pg_ts_config;`. BM25 scores depend on corpus statistics gathered at build time, so create the index after your data is loaded, and run `VACUUM` after large bulk loads to keep scores accurate.

## Migrate your queries

`pg_search` queries a column with the `@@@` operator and ranks with `paradedb.score()`, highest first:

```sql
-- pg_search
SELECT id, description, paradedb.score(id) AS score
FROM mock_items
WHERE description @@@ 'keyboard'
ORDER BY score DESC;
```

```
 id |         description          |   score
----+------------------------------+-----------
  2 | Blue metal keyboard          | 0.8236319
  3 | Wireless ergonomic keyboard  | 0.8236319
```

`lakebase_text` does the same work with two operators instead of one: `@@` filters the matching rows, and `<@>` with `to_bm25query` ranks them. Scores are negative, so order ascending to put the best matches first:

```sql
-- lakebase_text
SELECT id, description,
  search_tsv <@> to_bm25query(to_tsvector('english', 'keyboard'), 'mock_items_bm25') AS score
FROM mock_items
WHERE search_tsv @@ to_tsquery('english', 'keyboard')
ORDER BY score
LIMIT 10;
```

```
 id |         description          |        score
----+------------------------------+---------------------
  2 | Blue metal keyboard          | -0.8374048792080783
  3 | Wireless ergonomic keyboard  | -0.8374048792080783
```

When you rewrite a query, three things change:

- **Filter with `@@`.** `<@>` only scores, it doesn't filter. Add a `WHERE search_tsv @@ to_tsquery('english', 'query')` clause, or every row comes back (non-matches at score 0).
- **Pass the index name to `to_bm25query`.** BM25 scoring reads corpus statistics from the index.
- **Reverse the sort.** `pg_search` orders `DESC`; `lakebase_text` orders ascending, because its scores are negative and a lower score is a better match.

For multi-word or user-supplied input, use `websearch_to_tsquery('english', 'your query')` in place of `to_tsquery` in both the filter and the rank. `to_tsquery` expects pre-formatted query syntax and errors on plain phrases with spaces.

## Check for feature gaps

Before you drop `pg_search`, confirm the features you rely on carry over. A few don't map one-to-one:

- **Fuzzy / typo matching** (`paradedb.match(..., distance => 1)`): no direct equivalent. Use [`pg_trgm`](https://neon.com/docs/extensions/pg_trgm) for similarity and typo-tolerant matching.
- **Highlighting** (`paradedb.snippet()`): use Postgres [`ts_headline()`](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-HEADLINE).
- **JSON query objects and advanced tokenizers** (ICU, Lindera): not supported. Use `tsquery` operators (`&`, `|`, `<->`) and [Postgres text-search](https://www.postgresql.org/docs/current/textsearch.html) configurations.

## Remove pg_search

Once your queries run on `lakebase_text` and return the results you expect, drop `pg_search` ahead of the September 21, 2026 removal:

```sql
DROP EXTENSION pg_search CASCADE;
```

`CASCADE` also drops the `bm25` indexes that depend on the extension. Confirm it's gone:

```sql
SELECT extname FROM pg_extension WHERE extname = 'pg_search';   -- returns no rows
```

Finally, restart the compute to complete the migration. In the [Neon Console](https://console.neon.tech), open the compute's **⋯** menu and select **Restart compute**, or call the [Restart compute endpoint](https://neon.com/docs/reference/api/endpoints/restart-project-endpoint) API.

Your search now runs entirely on `lakebase_text`.

## Resources

- [The lakebase_text extension](https://neon.com/docs/extensions/lakebase-text)
- [The pg_search extension](https://neon.com/docs/extensions/pg_search) (deprecated)
- [Lakebase Search](https://neon.com/docs/ai/lakebase-search)

--- [Document source](https://neon.com/docs/extensions/neon-utils.md) ---

> Summary: The `neon_utils` PostgreSQL extension provides a `num_cpus()` function that returns the current number of CPU cores allocated to a Neon compute by the Autoscaling feature. Use it to observe real-time CPU scaling during load tests or to verify that autoscaling is responding to workload as expected. `num_cpus()` rounds fractional CU values up and only returns correct results on autoscaling-enabled computes, not fixed-size computes.

# The neon_utils extension

Monitor how Neon's Autoscaling feature allocates compute resources

Last updated: 2026-09-16

The `neon_utils` extension provides a `num_cpus()` function you can use to monitor how Neon's _Autoscaling_ feature allocates CPU resources in response to workload. The function returns the current number of allocated CPU cores.

For information about Neon's _Autoscaling_ feature, see [Autoscaling](https://neon.com/docs/introduction/autoscaling).

## Install the `neon_utils` extension

Install the `neon_utils` extension by running the following `CREATE EXTENSION` statement in the Neon **SQL Editor** or from a client such as `psql` that is connected to Neon.

```sql
CREATE EXTENSION neon_utils;
```

For information about using the Neon **SQL Editor**, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Use the `num_cpus()` function

In Neon, computing capacity is measured in _Compute Units (CU)_. Each CU allocates approximately 4 GB of RAM, along with associated CPU and local SSD resources; for example, 1 CU has 4 GB of RAM, 2 CU has 8 GB of RAM, and so on. A Neon compute can have anywhere from .25 to 56 CU, but _Autoscaling_ is only supported up to 16 CU.

Defining a minimum and maximum compute size for your compute, as shown below, enables autoscaling.

![Edit compute dialog showing an autoscaling configuration](https://neon.com/docs/extensions/edit_compute_endpoint.png)

As your workload changes, computing capacity scales dynamically between the minimum and maximum settings defined in your compute configuration. To retrieve the number of allocated CPU cores at any point in time, you can run the following query:

```sql
SELECT num_cpus();
```

For autoscaling configuration instructions, see [Compute size and autoscaling configuration](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration).

## Limitations

The following limitations apply:

- The `num_cpus()` function does not return fractional CU sizes. The _Autoscaling_ feature can scale by fractional CU, but the `num_cpus()` function reports the next whole number. For example, if the current number of allocated CU is `.25` or `.5`, the `num_cpus()` function returns `1`.
- The `num_cpus()` function only works on computes that have the _Autoscaling_ feature enabled. Running the function on a fixed-size compute does not return a correct value.

## Observe autoscaling with `neon_utils` and `pgbench`

The following instructions demonstrate how you can use the `num_cpus()` function with `pgbench` to observe how Neon's _Autoscaling_ feature responds to workload.

### Prerequisites

- Ensure that autoscaling is enabled for your compute. For instructions, see [Compute size and autoscaling configuration](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration). The following example uses a minimum setting of 0.25 Compute Units (CU) and a maximum of 4.
- The [pgbench](https://www.postgresql.org/docs/current/pgbench.html) utility.

### Run the test

1. Install the `neon_utils` extension:

   ```sql
   CREATE EXTENSION IF NOT EXISTS neon_utils;
   ```

2. Create a `test.sql` file with the following queries:

   ```sql
   SELECT LOG(factorial(5000)) / LOG(factorial(2500));
   SELECT txid_current();
   ```

3. To avoid errors when running `pgbench`, initialize your database with the tables used by `pgbench`. This can be done using the `pgbench -i` command, specifying the connection string for your Neon database. You can obtain a connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

   ```bash
   pgbench -i postgresql://[user]:[password]@[neon_hostname]/[dbname]
   ```

4. Run a `pgbench` test with your `test.sql` file, specifying your connection string:

   ```bash
   pgbench -f test.sql -c 15 -T 1000 -P 1 postgresql://[user]:[password]@[neon_hostname]/[dbname]
   ```

   The test produces output similar to the following on a compute set to scale from 0.25 to 4 CUs.

   ```bash
   pgbench (15.3)
   starting vacuum...end.
   progress: 8.4 s, 0.0 tps, lat 0.000 ms stddev 0.000, 0 failed
   progress: 9.0 s, 0.0 tps, lat 0.000 ms stddev 0.000, 0 failed
   progress: 10.0 s, 4.0 tps, lat 1246.290 ms stddev 3.253, 0 failed
   progress: 11.0 s, 6.0 tps, lat 1892.455 ms stddev 446.686, 0 failed
   progress: 12.0 s, 9.0 tps, lat 2091.352 ms stddev 1068.303, 0 failed
   progress: 13.0 s, 5.0 tps, lat 1881.682 ms stddev 700.852, 0 failed
   progress: 14.0 s, 6.0 tps, lat 2660.009 ms stddev 1404.672, 0 failed
   progress: 15.0 s, 9.0 tps, lat 2354.776 ms stddev 1248.686, 0 failed
   progress: 16.0 s, 8.0 tps, lat 1770.870 ms stddev 776.465, 0 failed
   progress: 17.0 s, 7.0 tps, lat 1800.686 ms stddev 611.749, 0 failed
   progress: 18.0 s, 18.0 tps, lat 1681.841 ms stddev 1187.918, 0 failed
   progress: 19.0 s, 29.0 tps, lat 561.201 ms stddev 139.565, 0 failed
   progress: 20.0 s, 27.0 tps, lat 507.782 ms stddev 153.889, 0 failed
   progress: 21.0 s, 30.0 tps, lat 493.312 ms stddev 121.688, 0 failed
   progress: 22.0 s, 32.0 tps, lat 513.444 ms stddev 185.033, 0 failed
   progress: 23.0 s, 32.0 tps, lat 503.135 ms stddev 199.435, 0 failed
   progress: 24.0 s, 28.0 tps, lat 492.913 ms stddev 124.019, 0 failed
   progress: 25.0 s, 43.0 tps, lat 366.719 ms stddev 123.547, 0 failed
   progress: 26.0 s, 49.0 tps, lat 334.276 ms stddev 79.043, 0 failed
   progress: 27.0 s, 40.0 tps, lat 354.922 ms stddev 83.560, 0 failed
   progress: 28.0 s, 31.0 tps, lat 400.645 ms stddev 29.236, 0 failed
   progress: 29.0 s, 48.0 tps, lat 373.522 ms stddev 64.446, 0 failed
   progress: 30.0 s, 44.0 tps, lat 333.343 ms stddev 86.497, 0 failed
   progress: 31.0 s, 44.0 tps, lat 326.754 ms stddev 82.990, 0 failed
   progress: 32.0 s, 44.0 tps, lat 329.317 ms stddev 76.728, 0 failed
   progress: 33.0 s, 53.0 tps, lat 321.572 ms stddev 76.427, 0 failed
   progress: 34.0 s, 57.0 tps, lat 254.500 ms stddev 33.013, 0 failed
   progress: 35.0 s, 60.0 tps, lat 251.035 ms stddev 37.574, 0 failed
   progress: 36.0 s, 58.0 tps, lat 256.846 ms stddev 36.390, 0 failed
   progress: 37.0 s, 60.0 tps, lat 249.165 ms stddev 36.764, 0 failed
   progress: 38.0 s, 57.0 tps, lat 263.885 ms stddev 31.351, 0 failed
   progress: 39.0 s, 56.0 tps, lat 262.529 ms stddev 43.900, 0 failed
   progress: 40.0 s, 58.0 tps, lat 259.052 ms stddev 39.737, 0 failed
   ...
   ```

5. Call the `num_cpus()` function to retrieve the current number of allocated CPU cores.

   ```sql
   ​​neondb=> SELECT num_cpus();
   num_cpus
   ----------
           4
   (1 row)
   ```

--- [Document source](https://neon.com/docs/extensions/neon.md) ---

> Summary: The `neon` PostgreSQL extension exposes the `neon_stat_file_cache` view, which reports compute cache hit ratio, misses, hits, and writes for a Neon compute instance. Use it to diagnose cache efficiency and determine whether your working set fits in memory. OLTP workloads should target a `file_cache_hit_ratio` of 99% or better; a low ratio signals a need for a larger compute size. Cache statistics reset on compute restart. `EXPLAIN ANALYZE` with the `FILECACHE` and `PREFETCH` options provides per-query cache and prefetch metrics without requiring the extension.

# The neon extension

An extension for Neon-specific statistics including the compute cache hit ratio

Last updated: 2026-11-04

The `neon` extension provides functions and views designed to gather Neon-specific metrics.

- [The `neon_stat_file_cache` view](https://neon.com/docs/extensions/neon#the-neonstatfilecache-view)
- [Views for Neon internal use](https://neon.com/docs/extensions/neon#views-for-neon-internal-use)

## The neon_stat_file_cache view

The `neon_stat_file_cache` view provides insights into how effectively your Neon compute's cache is being used.

## What is the compute cache?

Neon caches frequently accessed data on the compute, which reduces latency and improves query performance by minimizing reads from database storage. This compute cache provides up to 75% of your compute's RAM in capacity and can span two tiers: Postgres [shared buffers](https://neon.com/docs/reference/glossary#shared-buffers), which are held in memory and are the fastest to read, and a larger secondary file cache on the compute's local disk that holds more data but requires disk I/O. A read checks shared buffers first, then the file cache, and only then falls through to database storage. The `neon_stat_file_cache` view reports the file-cache tier. To view the compute cache size for each Neon compute size, see [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

**Note: Large fixed-size computes**

On large fixed-size computes (18 CU and above), Neon sets `shared_buffers` to 75% of RAM (backed by huge pages) and disables the secondary file cache, so the entire compute cache is held in memory as shared buffers. The capacity is unchanged; what differs is that hot pages stay in the fastest tier instead of falling through to disk, and how you measure the cache. Because the file cache is off, `neon_stat_file_cache`, [`neon inspect db lfc-hit-rate`](https://neon.com/docs/cli/inspect#db-lfc-hit-rate), and [`neon inspect db working-set`](https://neon.com/docs/cli/inspect#db-working-set) no longer report it on these computes. Run `SHOW shared_buffers` and `SHOW huge_pages` to confirm the configuration, and use the [Compute cache hit rate](https://neon.com/docs/introduction/monitoring-page#compute-cache-hit-rate) graph, which works on every compute size. For background, see [Improving Postgres compute cache on Neon](https://neon.com/blog/improving-lakebase-compute-cache-part-1).

## Monitoring compute cache usage

You can monitor compute cache usage by installing the `neon` extension on your database and querying the [neon_stat_file_cache](https://neon.com/docs/extensions/neon#the-neonstatfilecache-view) view or [using EXPLAIN ANALYZE](https://neon.com/docs/extensions/neon#view-lfc-metrics-with-explain-analyze). Additionally, you can monitor the [Compute cache hit rate](https://neon.com/docs/introduction/monitoring-page#compute-cache-hit-rate) graph on the **Monitoring** page in the Neon console, or check it from the terminal with [`neon inspect db lfc-hit-rate`](https://neon.com/docs/cli/inspect#db-lfc-hit-rate) and [`neon inspect db working-set`](https://neon.com/docs/cli/inspect#db-working-set).

## neon_stat_file_cache view

The `neon_stat_file_cache` view includes the following metrics:

- `file_cache_misses`: The number of times the requested page block is not found in Postgres shared buffers or the compute cache. In this case, the page block is retrieved from database storage.
- `file_cache_hits`: The number of times the requested page block was not found in Postgres shared buffers but was found in the compute cache.
- `file_cache_used`: The number of times the compute cache was accessed.
- `file_cache_writes`: The number of writes to the compute cache. A write occurs when a requested page block is not found in Postgres shared buffers or the compute cache. In this case, the data is retrieved from database storage and then written to shared buffers and the compute cache.
- `file_cache_hit_ratio`: The percentage of database requests that are served from the compute cache rather than database storage. This is a measure of cache efficiency, indicating how often requested data is found in the cache. A higher cache hit ratio suggests better performance, as accessing data from memory is faster than accessing data from storage. The ratio is calculated using the following formula:

  ```
  file_cache_hit_ratio = (file_cache_hits / (file_cache_hits + file_cache_misses)) * 100
  ```

  For OLTP workloads, you should aim for a cache hit ratio of 99% or better. However, the ideal cache hit ratio depends on your specific workload and data access patterns. In some cases, a slightly lower ratio might still be acceptable, especially if the workload involves a lot of sequential scanning of large tables where caching might be less effective. If you find that your cache hit ratio is quite low, your working set may not be fully or adequately in memory. In this case, consider using a larger compute with more memory. Please keep in mind that the statistics are for the entire compute, not specific databases or tables.

### Using the neon_stat_file_cache view

To use the `neon_stat_file_cache` view, install the `neon` extension on your database:

To install the extension on a database:

```sql
CREATE EXTENSION neon;
```

To connect to your database. You can find a connection string for your database on the Neon Dashboard.

```bash
psql postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Issue the following query to view compute cache usage data for your compute:

```sql
SELECT * FROM neon_stat_file_cache;
 file_cache_misses | file_cache_hits | file_cache_used | file_cache_writes | file_cache_hit_ratio
-------------------+-----------------+-----------------+-------------------+----------------------
           2133643 |       108999742 |             607 |          10767410 |                98.08
```

**Note:** Compute cache statistics represent the lifetime of your compute, from the last time the compute started until the time you ran the query. Be aware that statistics are lost when your compute stops and gathered again from scratch when your compute restarts. You'll only want to run the cache hit ratio query after a representative workload has been run. For example, say that you increased your compute size after seeing a cache hit ratio below 99%. Changing the compute size restarts your compute, so you lose all of your current usage statistics. In this case, you should run your workload before you try the cache hit ratio query again to see if your cache hit ratio improved.

Remember that Postgres checks shared buffers first before it checks your compute cache. If you are only working with a small amount of data, queries may be served entirely from the shared buffers, resulting in no compute cache hits.

## View compute cache metrics with EXPLAIN ANALYZE

You can also use `EXPLAIN ANALYZE` with the `FILECACHE` and `PREFETCH` options to view compute cache hit and miss data, as well as prefetch statistics. Installing the `neon` extension is not required. For example, this query fetches data for a `SELECT COUNT(*)` query.

```sql {5,6,11,12,15,16,20,21}
EXPLAIN (ANALYZE,BUFFERS,PREFETCH,FILECACHE) SELECT COUNT(*) FROM pgbench_accounts;

 Finalize Aggregate  (cost=214486.94..214486.95 rows=1 width=8) (actual time=5195.378..5196.034 rows=1 loops=1)
   Buffers: shared hit=178875 read=143691 dirtied=128597 written=127346
   Prefetch: hits=0 misses=1865 expired=0 duplicates=0
   File cache: hits=141826 misses=1865
   ->  Gather  (cost=214486.73..214486.94 rows=2 width=8) (actual time=5195.366..5196.025 rows=3 loops=1)
         Workers Planned: 2
         Workers Launched: 2
         Buffers: shared hit=178875 read=143691 dirtied=128597 written=127346
         Prefetch: hits=0 misses=1865 expired=0 duplicates=0
         File cache: hits=141826 misses=1865
         ->  Partial Aggregate  (cost=213486.73..213486.74 rows=1 width=8) (actual time=5187.670..5187.670 rows=1 loops=3)
               Buffers: shared hit=178875 read=143691 dirtied=128597 written=127346
               Prefetch: hits=0 misses=1865 expired=0 duplicates=0
               File cache: hits=141826 misses=1865
               ->  Parallel Index Only Scan using pgbench_accounts_pkey on pgbench_accounts  (cost=0.43..203003.02 rows=4193481 width=0) (actual time=0.574..4928.995 rows=3333333 loops=3)
                     Heap Fetches: 3675286
                     Buffers: shared hit=178875 read=143691 dirtied=128597 written=127346
                     Prefetch: hits=0 misses=1865 expired=0 duplicates=0
                     File cache: hits=141826 misses=1865
```

### PREFETCH option

The `PREFETCH` option provides information about Neon's prefetching mechanism, which predicts which pages will be needed soon and sends prefetch requests to the page server before the page is actually requested by the executor. This helps reduce latency by having data ready when it's needed. The PREFETCH option includes the following metrics:

- `hits` - Number of pages received from the page server before actually requested by the executor. Prefetch distance is controlled by the `effective_io_concurrency` parameter. The larger this value, the more likely the page server will complete the request before it's needed. However, it should not be larger than `neon.prefetch_buffer_size`.
- `misses` - Number of accessed pages that were not prefetched. Prefetch is not implemented for all plan nodes, and even for supported nodes (like sequential scan), some mispredictions can occur.
- `expired` - Pages that were updated since the prefetch request was sent, or results that weren't used because the executor didn't need the page (for example, due to a `LIMIT` clause in the query).
- `duplicates` - Multiple prefetch requests for the same page. For some nodes like sequential scan, predicting next pages is straightforward. However, for index scans that prefetch referenced heap pages, index entries can have multiple references to the same heap page, resulting in duplicate prefetch requests.

### FILECACHE option

The `FILECACHE` option provides information about compute cache usage during query execution:

- `hits` - Number of accessed pages found in the compute cache.
- `misses` - Number of accessed pages not found in the compute cache.

## Views for Neon internal use

The `neon` extension also includes functions and views owned by the Neon system role (`cloud_admin`) that are used to collect statistics. This data helps the Neon team enhance the Neon service. The extension is installed by default in a system-owned `postgres` database in each Neon project.

--- [Document source](https://neon.com/docs/extensions/online_advisor.md) ---

> Summary: The `online_advisor` extension analyzes your live query workload using an executor hook to recommend indexes, extended statistics, and prepared statements. Use it when you want data-driven tuning suggestions based on actual query execution rather than manual analysis. The extension observes and reports but never creates indexes or statistics itself. Configurable thresholds control when recommendations surface, and system-level settings like `max_index_proposals` use fixed defaults on Neon.

# The online_advisor extension

Get index, statistics, and prepared statement recommendations based on your query workload

Last updated: 2026-06-05

The `online_advisor` extension recommends **indexes**, **extended statistics**, and **prepared statements** based on your actual query workload. It uses the same executor hook mechanism as [`auto_explain`](https://www.postgresql.org/docs/current/auto-explain.html) to collect and analyze execution data.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## What it does

- Suggests **indexes** when queries filter many rows
- Suggests **extended statistics** when the planner's row estimates are far off from actuals
- Identifies queries that could benefit from **prepared statements** when planning time is high

**Note:** `online_advisor` only makes recommendations. It does not create indexes or statistics for you.

## Requirements

- Supported on Postgres **17**
- Create the extension in every database you want to inspect
- Activate it by calling any provided function (for example, `get_executor_stats()`)

### Version availability

Please refer to the [Supported Postgres extensions](https://neon.com/docs/extensions/pg-extensions) page for the latest supported version of `online_advisor` on Neon.

## Enable the online_advisor extension

You can create the extension in each target database using `CREATE EXTENSION`:

```sql
CREATE EXTENSION online_advisor;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Start collecting recommendations

1. Activate the extension by calling any function:

   ```sql
   SELECT get_executor_stats();
   ```

2. Run your workload to collect data.

3. View recommendations:

   ```sql
   -- Proposed indexes
   SELECT * FROM proposed_indexes ORDER BY elapsed_sec DESC;

   -- Proposed extended statistics
   SELECT * FROM proposed_statistics ORDER BY elapsed_sec DESC;
   ```

## Apply accepted recommendations

Run the `create_index` or `create_statistics` statement from the views, then analyze the table:

```sql
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_customer_date ON orders(customer_id, order_date);
VACUUM (ANALYZE) orders;
```

## Configure thresholds

You can tune `online_advisor` with these settings:

| Setting                                  | Default | Description                                                                              |
| ---------------------------------------- | ------- | ---------------------------------------------------------------------------------------- |
| `online_advisor.filtered_threshold`      | `1000`  | Minimum filtered rows in a node to suggest an index.                                     |
| `online_advisor.misestimation_threshold` | `10`    | Minimum actual/estimated row ratio to flag misestimation.                                |
| `online_advisor.min_rows`                | `1000`  | Minimum returned rows before misestimation is considered.                                |
| `online_advisor.max_index_proposals`     | `1000`  | Max tracked clauses for index proposals (system-level, read-only on Neon).               |
| `online_advisor.max_stat_proposals`      | `1000`  | Max tracked clauses for extended statistics proposals (system-level, read-only on Neon). |
| `online_advisor.do_instrumentation`      | `on`    | Toggle data collection.                                                                  |
| `online_advisor.log_duration`            | `off`   | Log planning/execution time for each query.                                              |
| `online_advisor.prepare_threshold`       | `1.0`   | Planning/execution time ratio above which to suggest prepared statements.                |

**Note:** On Neon, you can only modify session-level settings using `SET`. System-level settings like `online_advisor.max_index_proposals` and `online_advisor.max_stat_proposals` use default values and cannot be changed. If you need different system-level settings, reach out to Neon Support.

Change a setting for the current session:

```sql
SET online_advisor.filtered_threshold = 2000;
```

## Check planning and execution stats

Use `get_executor_stats()` to see planning and execution times and whether prepared statements might help:

```sql
SELECT * FROM get_executor_stats(false); -- false = do not reset counters
```

Look at `avg_planning_overhead`. Values greater than `1` suggest that some queries would benefit from prepared statements.

## Combine or separate index proposals

By default, `online_advisor` tries to combine related predicates into a single compound index. To view separate recommendations for each predicate:

```sql
SELECT * FROM propose_indexes(false);
```

## Limitations

- Does not check operator ordering for compound indexes
- Does not suggest indexes for joins or `ORDER BY` clauses
- Does not estimate the benefit of adding an index; pair with [HypoPG](https://github.com/HypoPG/hypopg#) if you want to simulate usage
- Recommendations are per database

## Remove the extension

```sql
DROP EXTENSION IF EXISTS online_advisor;
```

If you're not using it anywhere, remove it from `shared_preload_libraries` and restart.

## Example workflow

```sql
-- Activate and run workload
SELECT get_executor_stats();

-- View index proposals
SELECT create_index, n_filtered, n_called, elapsed_sec
FROM proposed_indexes
ORDER BY elapsed_sec DESC
LIMIT 10;

-- View extended statistics proposals
SELECT create_statistics, misestimation, n_called, elapsed_sec
FROM proposed_statistics
ORDER BY misestimation DESC
LIMIT 10;

-- Apply a recommendation
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_orders_customer_date ON orders(customer_id, order_date);
VACUUM (ANALYZE) orders;

-- Check planning/execution times
SELECT * FROM get_executor_stats(true); -- reset after reading
```

## Resources

- [online_advisor GitHub repository](https://github.com/knizhnik/online_advisor)
- [PostgreSQL auto_explain documentation](https://www.postgresql.org/docs/current/auto-explain.html)

--- [Document source](https://neon.com/docs/extensions/pg_cron.md) ---

> Summary: pg_cron is a cron-based job scheduler that runs SQL commands and stored procedures on a schedule directly inside Lakebase Postgres, eliminating the need for external cron utilities. Enable it by setting the `cron.database_name` parameter via the Neon API, then use `cron.schedule()` with standard cron syntax to automate tasks like data archival, vacuuming, and log purging. Jobs only run when the compute is active, so pg_cron is best suited for computes with scale-to-zero disabled. `cron.schedule_in_database()` is not supported in Neon.

# The pg_cron extension

Schedule and manage cron jobs directly within your Lakebase Postgres database

Last updated: 2026-11-05

The `pg_cron` extension provides a simple, cron-based job scheduler for Postgres. It operates directly within your database, allowing you to schedule standard SQL commands or calls to stored procedures using familiar cron syntax. This eliminates the need for external cron utilities for many database maintenance and automation tasks.

**Important: Consider Function Triggers first**

For scheduled work, [scheduled Function Triggers](https://neon.com/docs/compute/functions/triggers/schedule) are usually the better choice. They run a [Neon Function](https://neon.com/docs/compute/functions/overview) on a cron schedule and fire at scale to zero. The job runs your code with the same [injected environment](https://neon.com/docs/compute/functions/environment-variables) as any function, including [Postgres](https://neon.com/docs/postgres/overview) via `DATABASE_URL`, [AI Gateway](https://neon.com/docs/ai-gateway/overview) and [Object Storage](https://neon.com/docs/storage/overview).

`pg_cron` runs only while the compute is active, so keep it for in-database maintenance on an always-on compute.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide provides an introduction to the `pg_cron` extension. You'll learn how to enable the extension, schedule jobs, understand the cron syntax, manage and monitor your scheduled tasks, and about considerations specific to the Neon environment.

## Enable the `pg_cron` extension

To install `pg_cron` on Neon, you must first enable it by setting the `cron.database_name` parameter to the name of the database where you want to install `pg_cron`. This requires making an [Update compute endpoint](https://neon.com/docs/reference/api/endpoints/update-project-endpoint) API call.

The `cron.database_name` parameter is passed to your Postgres instance through the `pg_settings` option in the endpoint settings object. The following `Update endpoint` API example shows where to specify your Neon `project_id`, `endpoint_id`, [Neon API key](https://neon.com/docs/manage/api-keys), and database name.

The `project_id` and `endpoint_id` values can be obtained from the Neon Console or [using the Neon API](https://neon.com/docs/reference/api). In the Neon Console, the `project_id` is found on your project's **Settings** page, and will look something like this: `young-sun-12345678`. The `endpoint_id` is found on the **Compute** tab on your **Branches** page, where it is referred to as the **Endpoint ID**. It will have an `ep` prefix, and look similar to this: `ep-still-rain-abcd1234`.

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/<project_id>/endpoints/<endpoint_id> \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY$' \
     --header 'content-type: application/json' \
     --data '
{
  "endpoint": {
    "settings": {
      "pg_settings": {
        "cron.database_name": "your_dbname"
      }
    }
  }
}
'
```

After setting `cron.database_name`, you must restart your compute to apply the new setting. You can do this using the [Restart compute endpoint](https://neon.com/docs/reference/api/endpoints/restart-project-endpoint) API. Specify the same `project_id` and `endpoint_id` used to set the `cron.database_name` parameter above. **Please note that restarting your compute endpoint will drop current connections to your database.**

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/<project_id>/endpoints/<endpoint_id>/restart \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

Or restart it with the Neon CLI:

```bash
neon postgres computes restart <endpoint_id> --project-id <project_id>
```

**Note:** The [Restart compute endpoint](https://neon.com/docs/reference/api/endpoints/restart-project-endpoint) API only works on an active compute. If your compute is idle, you can start it by running a query to wake it up, or with the [Start compute endpoint](https://neon.com/docs/reference/api/endpoints/start-project-endpoint) API or [`neon postgres computes start`](https://neon.com/docs/cli/postgres#computes-start). For more information and other compute restart options, see [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

You can then install the `pg_cron` extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS pg_cron;
```

If you have trouble with this setup, please reach out to [Neon Support](https://console.neon.tech/app/projects?modal=support) or find us on [Discord](https://neon.com/discord).

## `pg_cron` version availability

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Cron schedule syntax

`pg_cron` uses the standard cron syntax, with the following fields:

```
 ┌───────────── min (0 - 59)
 │ ┌────────────── hour (0 - 23)
 │ │ ┌─────────────── day of month (1 - 31) or last day of the month ($)
 │ │ │ ┌──────────────── month (1 - 12)
 │ │ │ │ ┌───────────────── day of week (0 - 6) (0 to 6 are Sunday to
 │ │ │ │ │                  Saturday, or use names; 7 is also Sunday)
 │ │ │ │ │
 │ │ │ │ │
 * * * * *
```

You can use the following special characters:

- `*`: Represents all values within the field.
- `,`: Specifies a list of values (for example, `1,3,5` for specific days).
- `-`: Specifies a range of values (for example, `10-12` for hours 10, 11, and 12).
- `/`: Specifies step values (for example, `*/15` in the minutes field means "every 15 minutes").

Additionally, `pg_cron` supports:

- Interval scheduling using `'[1-59] seconds'` (for example, `'5 seconds'`).
- `'$'` to indicate the last day of the month.

Remember that all schedules in `pg_cron` are interpreted in UTC. When scheduling jobs, ensure your cron expressions are set accordingly. You can use tools like [crontab.guru](http://crontab.guru/) and adjust for the UTC timezone.

## Schedule a job

You can schedule jobs using the `cron.schedule()` function. The basic syntax involves providing a cron schedule string and the command to execute.

Let's look at some examples to understand how to schedule jobs with `pg_cron`.

### Automating data archival

Imagine you have an `orders` table and you want to archive orders older than 90 days to a separate `orders_archive` table every Sunday at 2:00 AM UTC to maintain performance on your main table.

```sql
SELECT cron.schedule(
    'archive-old-orders',
    '0 2 * * 0',  -- Runs every Sunday at 2:00 AM UTC
    $$
        WITH OldOrders AS (
            SELECT *
            FROM orders
            WHERE order_date < NOW() - INTERVAL '90 days'
        )
        INSERT INTO orders_archive SELECT * FROM OldOrders;
        DELETE FROM orders WHERE order_id IN (SELECT order_id FROM OldOrders);
    $$
);
```

Here's a breakdown of the command:

- `'archive-old-orders'`: This is the name you're giving to this scheduled job. It helps you identify and manage the job later.
- `'0 2 * * 0'`: This is the cron schedule string.
  - `0`: The job will run when the minute is `0`.
  - `2`: The job will run when the hour is `2` (2 AM UTC).
  - `*`: The job will run every day of the month.
  - `*`: The job will run every month.
  - `0`: The job will run on Sunday (where 0 represents Sunday).
    Therefore, this job is scheduled to run at 2:00 AM UTC every Sunday.
- `$$ ... $$`: This is a way to define a string literal in PostgreSQL, especially useful for multi-line commands.
- `INSERT INTO orders_archive ...`: This is the SQL command that will be executed. It selects all rows from the `orders` table older than 90 days and inserts them into the `orders_archive` table. (A CTE is used to make sure the same rows are used for both the `INSERT` and `DELETE` commands.)
- `DELETE FROM orders ...`: This command then deletes the archived orders from the main `orders` table.

This example demonstrates how to automate a common database maintenance task, ensuring your main tables remain manageable and performant.

### Purging cron job logs

The `cron.job_run_details` table keeps a record of your scheduled job executions. Over time, this table can grow and consume storage. Regularly purging older entries is a good practice to keep its size manageable.

You can schedule a job using `pg_cron` itself to automatically delete old records from `cron.job_run_details`. Here's how you can schedule a job to purge entries older than seven days, running every day at midnight UTC:

```sql
SELECT cron.schedule(
    'purge-cron-history',
    '0 0 * * *',  -- Runs every day at midnight UTC
    $$
        DELETE FROM cron.job_run_details
        WHERE end_time < NOW() - INTERVAL '7 days';
    $$
);
```

Here's a breakdown of the command:

- **purge-cron-history**: The name of the scheduled job for purging history.

- '0 0 * * *': The cron schedule, set to run at minute 0, hour 0 (midnight), every day of the month, every month, and every day of the week (all in UTC).

- `DELETE FROM cron.job_run_details WHERE end_time < NOW() - INTERVAL '7 days'`: This is the SQL command that will be executed. It deletes all records from the `cron.job_run_details` table where the end_time is older than seven days from the current time.

### Running jobs every `n` seconds

`pg_cron` also lets you schedule a job every `n` seconds, which is not possible with traditional cron jobs. Here `n` can be any value between 1 and 59 inclusive.

For example, to run a job every 10 seconds, you can use the following command:

```sql
SELECT cron.schedule('every-10-seconds', '10 seconds', 'SELECT 1');
```

## View scheduled jobs

To see the jobs currently scheduled in your database, query the `cron.job` table:

```sql
SELECT * FROM cron.job;
```

This will show you details like the job ID, schedule, command, and the user who scheduled it.

## Unschedule jobs

You can remove scheduled jobs using the `cron.unschedule()` function, either by providing the job name or the job ID.

### Unschedule by name

Let's say you want to unschedule the job we created earlier to archive old orders:

```sql
SELECT cron.unschedule('archive-old-orders');
```

### Unschedule by ID

You can also unschedule a job by providing the job ID:

```sql
SELECT cron.unschedule(26);
```

## View job run details

The `cron.job_run_details` table provides information about the execution of scheduled jobs.

```sql
SELECT * FROM cron.job_run_details ORDER BY start_time DESC LIMIT 5;
```

This table includes details like the job ID, run ID, execution status, start and end times, and any return messages.

## Running pg_cron jobs in multiple databases

The `pg_cron` extension can only be installed in one database per Postgres cluster (each compute in a Neon project runs a Postgres instance, i.e., a Postgres cluster). If you need to schedule jobs in multiple databases, you can use the `cron.schedule_in_database()` function. This function allows you to create a cron job that runs in a specific database, even if `pg_cron` is installed in a different database.

**Warning: Function not supported in Neon**

The `cron.schedule_in_database()` function is currently not supported in Neon.

### Example: Scheduling a job in a different database

To schedule a job in another database, use `cron.schedule_in_database()` and specify the target database name:

```sql
SELECT cron.schedule_in_database(
    'my_job',                     -- Job name
    '0 * * * *',                  -- Cron schedule (every hour)
    'my_database',                 -- Target database
    'VACUUM ANALYZE my_table'      -- SQL command to run
);
```

In this example:

- The job named `my_job` runs every hour `(0 * * * *)`.
- It executes `VACUUM ANALYZE my_table` in `my_database`, even if `pg_cron` is installed in another database.

## Extension settings

`pg_cron` has several configuration parameters that influence its behavior. These settings are managed by Neon and cannot be directly modified by users. Understanding these settings can be helpful for monitoring and troubleshooting. You can view the current configuration in your Neon database using the following query:

```sql
SELECT * FROM pg_settings WHERE name LIKE 'cron.%';
```

Here are a few key `pg_cron` settings and their descriptions:

| Setting                       | Default   | Description                                                                                                                                                                                                                                      |
| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cron.launch_active_jobs`     | `on`      | When set to `off`, this setting disables all active `pg_cron` jobs without requiring a server restart.                                                                                                                                           |
| `cron.log_min_messages`       | `WARNING` | This setting determines the minimum severity level of log messages generated by the `pg_cron` launcher background worker.                                                                                                                        |
| `cron.log_run`                | `on`      | When enabled (`on`), details of each job run are logged in the `cron.job_run_details` table.                                                                                                                                                     |
| `cron.log_statement`          | `on`      | If enabled (`on`), the SQL command of each scheduled job is logged before execution.                                                                                                                                                             |
| `cron.max_running_jobs`       | `32`      | This parameter defines the maximum number of `pg_cron` jobs that can run concurrently.                                                                                                                                                           |
| `cron.timezone`               | `GMT`     | Specifies the timezone in which the `pg_cron` background worker operates. **Note:** Although this setting exists, `pg_cron` internally interprets all job schedules in UTC. Changing this parameter has no effect on how schedules are executed. |
| `cron.use_background_workers` | `off`     | When enabled (`on`), `pg_cron` uses background workers instead of direct client connections to execute jobs. This may require adjustments to the `max_worker_processes` PostgreSQL setting.                                                      |

**Note: Important: Setting Modifications in Neon**

It's important to note that because `pg_cron` is managed by Neon, modifying these settings requires superuser privileges. Therefore, you cannot directly alter these `pg_cron` configuration parameters yourself. If you have a specific need to adjust any of these settings, please [open a support ticket](https://console.neon.tech/app/projects?modal=support). **After Neon support implements the requested configuration change, you will need to [restart your Neon compute](https://neon.com/docs/manage/computes#restart-a-compute) for the new settings to take effect.**

## Conclusion

You have successfully learned how to enable and use the `pg_cron` extension within your Lakebase Postgres environment. You can now schedule routine database tasks directly within your database, simplifying automation and maintenance. Remember that `pg_cron` schedules are interpreted in UTC and will only run when your compute is active.

## Resources

- [pg_cron GitHub Repository](https://github.com/citusdata/pg_cron)
- [crontab.guru](http://crontab.guru/)

--- [Document source](https://neon.com/docs/extensions/pg_graphql.md) ---

> Summary: The `pg_graphql` Postgres extension auto-generates a GraphQL API by introspecting your SQL schema and exposing it through `graphql.resolve()`, with no external GraphQL server required. Use it to add GraphQL querying, mutations, filtering, pagination, or relationship traversal to a Neon Postgres database without deploying separate middleware. The extension enforces existing Postgres role permissions and row-level security policies, and supports customization via `@graphql` comment directives.

# The pg_graphql extension

Instantly create a GraphQL API for your Postgres database

Last updated: 2026-06-05

The `pg_graphql` extension adds a GraphQL API layer directly to your Postgres database. It introspects your SQL schema, tables, columns, relationships, and functions and automatically generates a corresponding GraphQL schema. This allows you to query your database using GraphQL through a single SQL function call, `graphql.resolve()`, eliminating the need for external GraphQL servers or middleware.

With `pg_graphql`, you get GraphQL's flexibility for data fetching while keeping your data and API logic tightly coupled within Postgres. It respects existing Postgres roles ensuring data access remains secure and consistent.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `pg_graphql` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS pg_graphql;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Core concepts

### The `graphql.resolve()` function

The `graphql.resolve()` function is the main entry point for executing GraphQL queries against your Postgres database. It acts as a bridge between your SQL schema and the GraphQL API. You pass your GraphQL query string (and optionally, variables and an operation name) to this function. It executes the query against the auto-generated GraphQL schema based on your database structure and returns the result as a JSONB object.

**Basic signature:**

```sql
graphql.resolve(query TEXT, variables JSONB DEFAULT '{}') RETURNS JSONB;
```

### Schema reflection

`pg_graphql` automatically creates a GraphQL schema from your SQL schema:

- **Tables and views**: Become GraphQL object types.
- **Columns**: Become fields on those types.
- **Foreign keys**: Define relationships between types.
- **Primary keys**: Essential for a table/view to be included. Each type gets a globally unique `nodeId: ID!` field.

### The `Node` interface

`pg_graphql` implements the GraphQL Global Object Identification Specification. Every table type with a primary key implements the `Node` interface and gets a `nodeId: ID!` field. This `nodeId` is a globally unique, opaque identifier for a record, useful for client-side caching and refetching specific objects.

## Querying data (`Query` type)

The `Query` type is the entry point for all read operations.

### Collections

For each accessible table (for example, `Book`), `pg_graphql` creates a collection field (for example, `bookCollection`) on the `Query` type. Collections allow you to fetch multiple records and support pagination, filtering, and sorting.

#### Basic collection fetch

Create a `Book` table:

```sql
CREATE TABLE "Book" (
  id SERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  author TEXT,
  published_year INT
);

INSERT INTO "Book" (title, author, published_year) VALUES
('The Great Gatsby', 'F. Scott Fitzgerald', 1925),
('To Kill a Mockingbird', 'Harper Lee', 1960),
('1984', 'George Orwell', 1949);
```

**Info: Inflection**

To convert `snake_case` SQL names to `camelCase` (fields) / `PascalCase` (types) GraphQL names, use the `@graphql` comment directive on the schema:

```sql
COMMENT ON SCHEMA public IS '@graphql({"inflect_names": true})';
```

This will convert all table and column names to their GraphQL equivalents. For example:

- `book` table becomes `Book` type
- `book_collection` becomes `bookCollection` field
- `book_authors` table becomes `BookAuthors` type
- `published_at` column becomes `publishedAt` field
- `published_year` column becomes `publishedYear` field

It is optional to use this directive, but it is recommended for consistency and readability. The guide uses the inflected names for clarity. Learn more about Inflection in the [pg_graphql documentation](https://supabase.github.io/pg_graphql/configuration/#inflection).

#### Fetch all books

To fetch all books, use the `bookCollection` field on the `Query` type. The result is a connection type with `edges` and `node` fields.

Run the following SQL query to fetch all books:

```sql
SELECT graphql.resolve($$
  query GetAllBooks {
    bookCollection {
      edges {
        node {
          id
          title
          author
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "bookCollection": {
      "edges": [
        { "node": { "id": 1, "title": "The Great Gatsby", "author": "F. Scott Fitzgerald" } },
        { "node": { "id": 2, "title": "To Kill a Mockingbird", "author": "Harper Lee" } },
        { "node": { "id": 3, "title": "1984", "author": "George Orwell" } }
      ]
    }
  }
}
```

#### Pagination

Use `first` to limit results and `after` with a cursor for pagination.

```sql
SELECT graphql.resolve($$
  query PaginateBooks {
    bookCollection(first: 1) { # Get the first book
      edges {
        cursor # Use this cursor for the 'after' argument next time
        node {
          title
        }
      }
      pageInfo {
        endCursor
        hasNextPage
      }
    }
  }
$$);
```

```json
{
  "data": {
    "bookCollection": {
      "edges": [{ "node": { "title": "The Great Gatsby" }, "cursor": "<opaqueCursorString>" }],
      "pageInfo": { "endCursor": "<opaqueCursorString>", "hasNextPage": true }
    }
  }
}
```

To get the next page, you'd take `endCursor` from the `pageInfo` and use it as the `after` argument in a subsequent query: `bookCollection(first: 1, after: "opaqueCursorString")`.

#### Filtering

Use the `filter` argument. Filterable fields and operators (`eq`, `gt`, `lt`, `contains`, `and`, `or`, `not`) are generated based on column types.

Find books by George Orwell published after 1940:

```sql
SELECT graphql.resolve($$
  query FilteredBooks {
    bookCollection(filter: {
      and: [
        { author: { eq: "George Orwell" } },
        { publishedYear: { gt: 1940 } }
      ]
    }) {
      edges {
        node {
          title
          publishedYear
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "bookCollection": { "edges": [{ "node": { "title": "1984", "published_year": 1949 } }] }
  }
}
```

#### Sorting

Use the `orderBy` argument. The `orderBy` clause takes a list of fields to sort by, each with a direction. Common direction enums are `AscNullsFirst`, `AscNullsLast`, `DescNullsFirst`, and `DescNullsLast`.

```sql
SELECT graphql.resolve($$
  query SortedBooks {
    bookCollection(orderBy: [{ publishedYear: DescNullsLast }]) {
      edges {
        node {
          title
          publishedYear
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "bookCollection": {
      "edges": [
        { "node": { "title": "To Kill a Mockingbird", "publishedYear": 1960 } },
        { "node": { "title": "1984", "publishedYear": 1949 } },
        { "node": { "title": "The Great Gatsby", "publishedYear": 1925 } }
      ]
    }
  }
}
```

## Modifying data (`Mutation` type)

The `Mutation` type is the entry point for write operations.

### Inserting records

Use `insertInto<Table>Collection`.

```sql
SELECT graphql.resolve($$
  mutation AddNewBook {
    insertIntoBookCollection(
      objects: [{ title: "Brave New World", author: "Aldous Huxley", publishedYear: 1932 }]
    ) {
      affectedCount
      records { # Returns the inserted records
        id
        title
      }
    }
  }
$$);
```

```json
{
  "data": {
    "insertIntoBookCollection": {
      "records": [{ "id": 4, "title": "Brave New World" }],
      "affectedCount": 1
    }
  }
}
```

### Updating records

Use `update<Table>Collection`. Requires a `filter` to specify which records, a `set` clause for new values, and `atMost` as a safety limit.

```sql
SELECT graphql.resolve($$
  mutation UpdateBookTitle {
    updateBookCollection(
      filter: { id: { eq: 1 } },
      set: { title: "The Great Gatsby (Revised Edition)" },
      atMost: 1
    ) {
      affectedCount
      records {
        id
        title
      }
    }
  }
$$);
```

```json
{
  "data": {
    "updateBookCollection": {
      "records": [{ "id": 1, "title": "The Great Gatsby (Revised Edition)" }],
      "affectedCount": 1
    }
  }
}
```

### Deleting records

Use `deleteFrom<Table>Collection`. Requires a `filter` and `atMost`.

```sql
SELECT graphql.resolve($$
  mutation DeleteBook {
    deleteFromBookCollection(
      filter: { id: { eq: 1 } },
      atMost: 1
    ) {
      affectedCount
      records { # Returns the deleted records
        id
        title
      }
    }
  }
$$);
```

```json
{
  "data": {
    "deleteFromBookCollection": {
      "records": [{ "id": 1, "title": "The Great Gatsby (Revised Edition)" }],
      "affectedCount": 1
    }
  }
}
```

## Relationships

`pg_graphql` automatically infers relationships from foreign key constraints.

**Example: Authors and Books**

```sql
CREATE TABLE "Author" (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL
);

CREATE TABLE "Book" (
  id SERIAL PRIMARY KEY,
  title TEXT NOT NULL,
  author_id INT REFERENCES "Author"(id) -- Foreign key
);

INSERT INTO "Author" (name) VALUES ('George Orwell');
INSERT INTO "Book" (title, author_id) VALUES ('1984', 1), ('Animal Farm', 1);
```

Query books and their author:

```sql
SELECT graphql.resolve($$
  query BooksWithAuthors {
    bookCollection {
      edges {
        node {
          title
          author { # Field for related Author
            name
          }
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "bookCollection": {
      "edges": [
        { "node": { "title": "1984", "author": { "name": "George Orwell" } } },
        { "node": { "title": "Animal Farm", "author": { "name": "George Orwell" } } }
      ]
    }
  }
}
```

Query authors and their books:

```sql
SELECT graphql.resolve($$
  query AuthorsWithBooks {
    authorCollection {
      edges {
        node {
          name
          bookCollection { # Collection of related Books
            edges {
              node {
                title
              }
            }
          }
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "authorCollection": {
      "edges": [
        {
          "node": {
            "name": "George Orwell",
            "bookCollection": {
              "edges": [{ "node": { "title": "1984" } }, { "node": { "title": "Animal Farm" } }]
            }
          }
        }
      ]
    }
  }
}
```

## Computed fields

You can add fields that are not directly stored columns.

### Postgres generated columns

```sql
CREATE TABLE "User" (
  id SERIAL PRIMARY KEY,
  first_name TEXT,
  last_name TEXT,
  full_name TEXT GENERATED ALWAYS AS (first_name || ' ' || last_name) STORED
);

INSERT INTO "User" (first_name, last_name) VALUES ('John', 'Doe');
```

`full_name` will automatically appear in the `User` GraphQL type.

```sql
SELECT graphql.resolve($$
  query UserFullName {
    userCollection {
      edges {
        node {
          firstName
          lastName
          fullName # Computed field
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "userCollection": {
      "edges": [{ "node": { "lastName": "Doe", "firstName": "John", "fullName": "John Doe" } }]
    }
  }
}
```

### SQL functions

For more complex logic, create an SQL function that takes the table's row type as input.

```sql
CREATE FUNCTION get_user_initials(u "User")
RETURNS TEXT
STABLE LANGUAGE SQL
AS $$
  SELECT substr(u.first_name, 1, 1) || substr(u.last_name, 1, 1);
$$;
```

This would (by default) add a `getUserInitials` field to the `User` type. Naming can be customized.

**Example:**

```sql
SELECT graphql.resolve($$
  query UserInitials {
    userCollection {
      edges {
        node {
          firstName
          lastName
          getUserInitials # Custom field
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "userCollection": {
      "edges": [{ "node": { "lastName": "Doe", "firstName": "John", "getUserInitials": "JD" } }]
    }
  }
}
```

## Configuration via comment directives

Customize `pg_graphql` behavior using comments on SQL objects.
Format: `COMMENT ON ... IS '@graphql({"key": "value"})';`

### Renaming

You can rename tables, columns, and types in the GraphQL schema using the `@graphql` directive.

```sql
COMMENT ON TABLE "Book" IS '@graphql({"name": "Publication"})'; -- Book table -> Publication type
COMMENT ON COLUMN "Book".title IS '@graphql({"name": "headline"})'; -- Book.title -> Publication.headline
```

```sql
SELECT graphql.resolve($$
  query RenamedTypes {
    publicationCollection {
      edges {
        node {
          headline
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "publicationCollection": {
      "edges": [{ "node": { "headline": "1984" } }, { "node": { "headline": "Animal Farm" } }]
    }
  }
}
```

### Descriptions

You can add descriptions to tables, columns, and types using the `@graphql` directive. This is useful for documentation and introspection.

```sql
COMMENT ON TABLE "Book" IS '@graphql({"description": "Represents a literary work."})';
```

```sql
SELECT graphql.resolve($$
  query BookDescription {
    __type(name: "Book") {
      description
    }
  }
$$);
```

```json
{ "data": { "__type": { "description": "Represents a literary work." } } }
```

### `totalCount` on collections

Enable the `totalCount` field on a connection type.

```sql
COMMENT ON TABLE "Book" IS '@graphql({"totalCount": {"enabled": true}})';
```

Now `bookCollection` will have `totalCount`.

```sql
SELECT graphql.resolve($$
  query BookTotalCount {
    bookCollection {
      totalCount
    }
  }
$$);
```

```json
{ "data": { "bookCollection": { "totalCount": 2 } } }
```

## Views and foreign tables

Views (and materialized views, foreign tables) can be exposed if they have a "virtual" primary key defined via a comment directive:

```sql
CREATE VIEW "NewUsers" AS
SELECT * FROM "User"; -- optional WHERE clause as per the view definition

COMMENT ON VIEW "NewUsers" IS '@graphql({"primary_key_columns": ["id"]})';
```

Now `NewUsers` will be queryable via GraphQL.

```sql
SELECT graphql.resolve($$
  query NewUsers {
    newUsersCollection {
      edges {
        node {
          id
          firstName
          lastName
        }
      }
    }
  }
$$);
```

```json
{
  "data": {
    "newUsersCollection": {
      "edges": [{ "node": { "id": 1, "lastName": "Doe", "firstName": "John" } }]
    }
  }
}
```

## Security considerations

`pg_graphql` fully respects Postgres's native security:

- **Role permissions**: A user querying via `pg_graphql` can only see/interact with tables, columns, and functions they have SQL permissions for. If a role lacks `SELECT` on a table, that table won't appear in their GraphQL schema.
- **Row-Level Security (RLS)**: All RLS policies are automatically applied.

While this guide provides a solid foundation, `pg_graphql` offers a rich set of advanced features not covered here. For a deeper dive into capabilities like exposing complex SQL functions as queries or mutations, advanced filtering techniques including nested logical operators and array operations, fine-tuning schema generation with more comment directives (for example, for computed relationships on views or custom naming for all elements), handling transactions, performance optimization strategies, and detailed guides for integrating with client libraries like Apollo and Relay, please refer to the official [`pg_graphql` documentation](https://supabase.github.io/pg_graphql/).

## Conclusion

`pg_graphql` offers an efficient way to generate a GraphQL API directly from your Postgres database. By understanding its schema reflection, the `graphql.resolve()` function, and basic configuration, you can quickly expose your data for flexible querying without needing an external GraphQL server.

## Resources

- [`pg_graphql` official documentation](https://supabase.github.io/pg_graphql/)
- [GraphQL official documentation](https://graphql.org/learn/)

--- [Document source](https://neon.com/docs/extensions/pg_mooncake.md) ---

> Summary: pg_mooncake is a Postgres extension that adds native columnstore tables with DuckDB-powered vectorized execution, storing data as Parquet files in S3, R2, or GCP object storage with Iceberg or Delta Lake metadata. Use it to run analytical queries on large datasets directly from Postgres without a separate OLAP system. The extension requires `SET neon.allow_unstable_extensions='true'` before installation.

# The pg_mooncake extension

Fast analytics in Postgres with columnstore tables and DuckDB execution

Last updated: 2026-10-14

The [pg_mooncake](https://github.com/Mooncake-Labs/pg_mooncake) extension enables fast analytic workloads in Postgres by adding native columnstore tables and vectorized execution (DuckDB).

Columnstore tables improve analytical queries by storing data vertically, enabling compression and efficient column-specific retrieval with vectorized execution.

`pg_mooncake` columnstore tables are designed so that only metadata is stored in Postgres, while data is stored in an object store as Parquet files with [Iceberg](https://iceberg.apache.org/) or [Delta Lake](https://delta.io/) metadata.

Queries on `pg_mooncake` columnstore tables are executed by DuckDB.

The extension is maintained by [Mooncake Labs](https://www.mooncake.dev/).

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

You can create and use `pg_mooncake` columnstore tables like regular Postgres heap tables to run:

- Transactional `INSERT`, `SELECT`, `UPDATE`, `DELETE`, and `COPY` operations
- Joins with regular Postgres tables

In addition, you can:

- Load Parquet, CSV, and JSON files into columnstore tables
- Load Hugging Face datasets
- Run DuckDB specific aggregate functions like `approx_count_distinct`
- Read existing Iceberg and Delta Lake tables
- Write Delta Lake tables from Postgres tables

**Note:** `pg_mooncake` is an open-source extension for Postgres that can be installed on any Neon Project using the instructions below.

## Use cases for pg_mooncake

`pg_mooncake` supports several use cases, including:

1. Analytics on Postgres data
2. Time Series & Log Analytics
3. Exporting Postgres tables to your Lake or Lakehouse
4. Querying and updating existing Lakehouse tables and Parquet files directly in Postgres

This guide provides a quickstart to the `pg_mooncake` extension.

## Enable the extension

**Note:** The `pg_mooncake` extension is experimental in Neon. A separate, dedicated Neon project is recommended when using an experimental extension. For additional guidance, see [Experimental extensions](https://neon.com/docs/extensions/pg-extensions#experimental-extensions).

Because the `pg_mooncake` extension is experimental, you need to explicitly allow it to be used on Neon before you can install it. To do so, connect to your Neon database via an SQL client like [psql](https://neon.com/docs/connect/query-with-psql-editor) or the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) and run the `SET` command shown below.

```sql
SET neon.allow_unstable_extensions='true';
```

Install the extension:

```sql
CREATE EXTENSION pg_mooncake;
```

## Set up your object store

Run the commands outlined in the following steps on your Neon database to setup your object store.

_If you don't have an object storage bucket, you can get a free S3 express bucket [here](https://s3.pgmooncake.com/). When using the free s3 bucket, the `SELECT` and `SET` statements defined below are generated for you, which you can copy and run._

Add your object storage credentials. In this case, S3:

```sql
SELECT mooncake.create_secret('<name>', 'S3', '<key_id>',
        '<secret>', '{"REGION": "<s3-region>"}');
```

Set your default bucket:

```sql
SET mooncake.default_bucket = 's3://<bucket>';
```

**Note: R2 and GCP buckets also supported**

The `pg_mooncake` extension also supports R2 and GCP buckets. For set up instructions, refer to **pg_mooncake's** [cloud storage docs](https://pgmooncake.com/docs/cloud-storage).

In the future, you will not have to bring your own bucket to use `pg_mooncake` with Neon.

## Create a columnstore table with `USING columnstore`

Run the following SQL statement on your Neon database to create a columnstore table:

```sql
CREATE TABLE reddit_comments(
    author TEXT,
    body TEXT,
    controversiality BIGINT,
    created_utc BIGINT,
    link_id TEXT,
    score BIGINT,
    subreddit TEXT,
    subreddit_id TEXT,
    id TEXT
) using columnstore;
```

## Load data

You can find a list of data sources [here](https://pgmooncake.com/docs/load-data).
This dataset has 13 million rows and may take a few minutes to load.

```sql
INSERT INTO reddit_comments
(SELECT author, body, controversiality, created_utc, link_id, score, subreddit, subreddit_id, id
FROM mooncake.read_parquet('hf://datasets/fddemarco/pushshift-reddit-comments/data/RC_2012-01.parquet')
AS (author TEXT, body TEXT, controversiality BIGINT, created_utc BIGINT, link_id TEXT, score BIGINT, subreddit TEXT, subreddit_id TEXT, id TEXT));
```

## Query the table

Queries on columnstore tables are executed by DuckDB. For example, this aggregate query runs in ~200 milliseconds on 13 million rows:

```sql
-- Top commenters (excluding [deleted] users)
SELECT
    author,
    COUNT(*) as comment_count,
    AVG(score) as avg_score,
    SUM(score) as total_score
FROM reddit_comments
WHERE author != '[deleted]'
GROUP BY author
ORDER BY comment_count DESC
LIMIT 10;
```

## References

- [Repository](https://github.com/Mooncake-Labs/pg_mooncake)
- [Documentation](https://pgmooncake.com/docs)
- [Architecture](https://www.mooncake.dev/blog/how-we-built-pgmooncake)
- [YouTube demo](https://youtu.be/QDNsxw_3ris?feature=shared\&t=2048)

--- [Document source](https://neon.com/docs/extensions/pg_partman.md) ---

> Summary: pg_partman is a Postgres extension that automates time-based and number-based range partition creation and maintenance on large tables, removing the need for manual partition DDL or an external cron scheduler. Use it when a table grows too large for full-table scans and you need automatic partition creation, retention policies, and background worker maintenance. The page covers enabling the extension, partitioning new and existing tables with `create_parent()`, setting retention policies, and uniqueness constraint rules for partitioned tables.

# The pg_partman extension

Manage large Postgres tables using the PostgreSQL Partition Manager extension

Last updated: 2026-06-05

`pg_partman` is a Postgres extension that simplifies the management of partitioned tables. Partitioning refers to splitting a single table into smaller pieces called `partitions`. This is done based on the values in a key column or set of columns. Even though partitions are stored as separate physical tables, the partitioned table can still be queried as a single logical table. This can significantly enhance query performance and also help you manage the data lifecycle of tables that grow very large.

While Postgres natively supports partitioning a table, `pg_partman` helps set up and manage partitioned tables:

- **Automated partition creation**: `pg_partman` automatically creates new partitions as new records are inserted, based on a specified interval for the partition key.
- **Automated maintenance**: `pg_partman` bundles a background worker process that manages maintenance tasks without needing an external scheduler or cron job. For example, it can automatically detach old partitions from the main table based on a retention policy, run `analyze` on partitions to update statistics, and more.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers how to set up `pg_partman` with Neon: why partitioning helps, how to enable the extension, how to create partitioned tables, and how to automate partition maintenance.

**Note:** `pg_partman` is an open-source Postgres extension that can be installed in any Neon project using the instructions below. Detailed installation instructions and compatibility information can be found in the [pg_partman](https://github.com/pgpartman/pg_partman) documentation.

## Enable the `pg_partman` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the Neon **SQL Editor** or from a client such as `psql` that is connected to Neon. Creating a `partman` schema is optional (but recommended) and you can name the schema whatever you like, but it cannot be changed after installation.

```sql
CREATE SCHEMA partman;
CREATE EXTENSION pg_partman SCHEMA partman;
```

The `pg_partman` extension does not require a superuser to run, but it's recommended to create a dedicated role for running `pg_partman` functions and to act as the owner of all partition sets that `pg_partman` will maintain.

Here is a sample SQL script to create a dedicated role with the minimum required privileges, assuming that `pg_partman` is installed to the `partman` schema and the dedicated role is named `partman_user`:

```sql
CREATE ROLE partman_user WITH LOGIN;
ALTER ROLE partman_user WITH PASSWORD '{PASSWORD_FOR_PARTMAN_USER}';

GRANT ALL ON SCHEMA partman TO partman_user;
GRANT ALL ON ALL TABLES IN SCHEMA partman TO partman_user;
GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA partman TO partman_user;
GRANT EXECUTE ON ALL PROCEDURES IN SCHEMA partman TO partman_user;
GRANT ALL ON SCHEMA '{WORKING_SCHEMA_NAME}' TO partman_user;
GRANT TEMPORARY ON DATABASE '{WORKING_DATABASE_NAME}' to partman_user; -- allow creation of temp tables to move data out of default
```

If the role needs to create schemas, you'll have to grant `CREATE` on the database as well. This is only required if you give the role above the `CREATE` privilege on pre-existing schemas that will contain partition sets.

```sql
GRANT CREATE ON DATABASE '{WORKING_DATABASE_NAME}' TO partman_user;
```

When you create a new `Neon` project, the default database name is `neondb` and the default schema name is `public`. Replace `{WORKING_DATABASE_NAME}` and `{WORKING_SCHEMA_NAME}` with the actual database and schema names you want to manage the partitioned tables in. To find out more about the privileges needed to run `pg_partman`, refer to the [pg_partman documentation](https://github.com/pgpartman/pg_partman).

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

**Version Compatibility:**

`pg_partman` works with Postgres 14 and above, complementing the native partitioning features introduced in these versions.

## Why partition your data?

For tables that grow very large, partitioning offers several benefits:

- **Faster queries:** Partitioning allows Postgres to quickly locate and retrieve data within a specific partition, rather than scanning the entire table.
- **Scalability:** Partitioning makes database administration simpler. For example, smaller partitions are easier to load and delete or back up and recover.
- **Managing the data lifecycle:** Easier management of the data lifecycle by archiving or purging old partitions, which can be moved to cheaper storage options without affecting the active dataset.

### Native partitioning vs pg_partman

Postgres supports partitioning tables natively, with the following strategies to divide the data:

- **List partitioning**: Data is distributed across partitions based on a list of values, such as a category or location.
- **Range partitioning**: Data is distributed across partitions based on ranges of values, such as dates or numerical ranges.

With native partitioning, you need to manually create and manage partitions for your table.

```sql
CREATE TABLE measurement (
    city_id         int not null,
    logdate         date not null,
    peaktemp        int
) PARTITION BY RANGE (logdate);

-- Create a partition for each month of logged data.
-- Records with `logdate` in this range are automatically routed to this partition table
CREATE TABLE measurement_y2006m02 PARTITION OF measurement
    FOR VALUES FROM ('2006-02-01') TO ('2006-03-01');

-- Moving older data to a different table.
-- Queries against the main table will not include the data in the detached partition
ALTER TABLE measurement DETACH PARTITION measurement_y2005m10;
```

`pg_partman` supports creating partitions that are number or time-based, with each partition covering a range of values. It's designed for cases where partitions need to be created automatically as new records come in. So, list partitioning isn't applicable since the partition key values are not known in advance.

## Example: Partitioning user-activity data

Consider a social media platform that tracks user interactions in their website application, such as likes, comments, and shares. The data is stored in a table called `user_activities`, where `activity_type` stores the type of activity and the other columns store additional information about the activity.

### Setting up a new partitioned table

Given the large volume of data generated by user interactions, partitioning the `user_activities` table can help keep queries manageable. Recent activity data is typically the most interesting for both the platform and its users, so `activity_time` is a good candidate to partition on.

We can create the partitioned table using the following SQL statement, similar to defining a native partitioned table:

```sql
CREATE TABLE user_activities (
    activity_id serial,
    activity_time TIMESTAMPTZ NOT NULL,
    activity_type TEXT NOT NULL,
    content_id INT NOT NULL,
    user_id INT NOT NULL
)
PARTITION BY RANGE (activity_time);
```

To create a partition for each week of activity data, you can run the following query:

```sql
SELECT create_parent('public.user_activities', 'activity_time', '1 week');
```

This will create a new partition for each week of data in the `user_activities` table. We can insert some sample data into the table:

```sql
INSERT INTO user_activities (activity_time, activity_type, content_id, user_id)
VALUES
    ('2024-03-15 10:00:00', 'like', 1001, 101),
    ('2024-03-16 15:30:00', 'comment', 1002, 102),
    ('2024-03-17 09:45:00', 'share', 1003, 103),
    ('2024-03-18 18:20:00', 'like', 1004, 104),
    ('2024-03-19 12:10:00', 'comment', 1005, 105),
    ('2024-03-20 08:00:00', 'like', 1006, 106),
    ('2024-03-21 14:15:00', 'share', 1007, 107),
    ('2024-03-22 11:30:00', 'like', 1008, 108),
    ('2024-03-23 16:45:00', 'comment', 1009, 109),
    ('2024-03-24 20:00:00', 'share', 1010, 110),
    ('2024-03-25 09:30:00', 'like', 1011, 111),
    ('2024-03-26 13:45:00', 'comment', 1012, 112),
    ('2024-03-27 17:00:00', 'share', 1013, 113),
    ('2024-03-28 11:15:00', 'like', 1014, 114),
    ('2024-03-29 15:30:00', 'comment', 1015, 115);
```

### Querying partitioned tables

We can query against the `user_activities` table as if it were a single table, and Postgres will automatically route the query to the correct partition(s) based on the `activity_time` column.

```sql
SELECT * FROM user_activities WHERE activity_time BETWEEN '2024-03-20' AND '2024-03-25';
```

This query returns the following results:

```text
 activity_id |     activity_time      | activity_type | content_id | user_id
-------------+------------------------+---------------+------------+---------
          16 | 2024-03-20 08:00:00+00 | like          |       1006 |     106
          17 | 2024-03-21 14:15:00+00 | share         |       1007 |     107
          18 | 2024-03-22 11:30:00+00 | like          |       1008 |     108
          19 | 2024-03-23 16:45:00+00 | comment       |       1009 |     109
          20 | 2024-03-24 20:00:00+00 | share         |       1010 |     110
(5 rows)
```

To see the list of all partitions created for the `user_activities` table, you can run the following query:

```sql
SELECT table_name FROM information_schema.tables WHERE table_schema = 'public' AND table_name LIKE 'user_activities_%';
```

This will return the following results:

```text
        table_name
---------------------------
 user_activities_p20240329
 user_activities_p20240405
 user_activities_p20240315
 user_activities_p20240322
 user_activities_p20240412
 user_activities_p20240419
 user_activities_p20240426
 user_activities_default
 user_activities_p20240301
 user_activities_p20240308
(10 rows)
```

`pg_partman` automatically created tables for weekly intervals close to the current data. As more data is inserted, it will create new partitions. Additionally, there is a `user_activities_default` table that stores data that doesn't fit into any of the existing partitions.

### Data retention policies

To make sure that old data is automatically removed from the main table, you can set up a retention policy:

```sql
UPDATE part_config
SET retention = '4 weeks', retention_keep_table = true
WHERE parent_table = 'public.user_activities';
```

The background worker process that comes bundled with `pg_partman` automatically detaches the old partitions that are older than 4 weeks from the main table. Since we've set `retention_keep_table` to `true`, the old partitions are kept as separate tables, and not dropped from the database.

## Additional considerations

### Partitioning an existing table with `pg_partman`

If you have an existing table that you want to partition, you can use `pg_partman` for it. However, it isn't straightforward since it can't be directly altered into the parent table for a partition set. Instead, you need to create a new partitioned table and copy the data from the existing table into the new partitioned table.

We describe the `offline` method here, where queries to the existing table are stopped while the data is being copied over to the new partitioned table. It is also possible to achieve this while keeping the existing table operational, but it involves more complex steps. For more details, refer to the [pg_partman documentation](https://github.com/pgpartman/pg_partman/blob/master/doc/pg_partman_howto.md).

#### Example: Partitioning an existing table

To illustrate, we recreate the `test_user_activities` table from the previous example but without specifying partitioning:

```sql
CREATE TABLE public.test_user_activities (
  activity_id serial,
  activity_time TIMESTAMPTZ NOT NULL,
  activity_type TEXT NOT NULL,
  content_id INT NOT NULL,
  user_id INT NOT NULL
);

INSERT INTO test_user_activities (activity_time, activity_type, content_id, user_id)
VALUES
    ('2024-03-15 10:00:00', 'like', 1001, 101),
    ('2024-03-16 15:30:00', 'comment', 1002, 102),
    ('2024-03-17 09:45:00', 'share', 1003, 103),
    ('2024-03-18 18:20:00', 'like', 1004, 104),
    ('2024-03-19 12:10:00', 'comment', 1005, 105),
    ('2024-03-20 08:00:00', 'like', 1006, 106),
    ('2024-03-21 14:15:00', 'share', 1007, 107),
    ('2024-03-22 11:30:00', 'like', 1008, 108),
    ('2024-03-23 16:45:00', 'comment', 1009, 109),
    ('2024-03-24 20:00:00', 'share', 1010, 110),
    ('2024-03-25 09:30:00', 'like', 1011, 111),
    ('2024-03-26 13:45:00', 'comment', 1012, 112),
    ('2024-03-27 17:00:00', 'share', 1013, 113),
    ('2024-03-28 11:15:00', 'like', 1014, 114),
    ('2024-03-29 15:30:00', 'comment', 1015, 115);
```

Now, we'll partition the existing `test_user_activities` table using `pg_partman`.

1. Rename the original table so that the partitioned table can be created with the original table's name:

```sql
ALTER TABLE public.test_user_activities RENAME TO old_user_activities;
```

2. Create a new table with the same name as the original table, but with partitioning enabled:

```sql
CREATE TABLE public.test_user_activities (
  activity_id serial,
  activity_time TIMESTAMPTZ NOT NULL,
  activity_type TEXT NOT NULL,
  content_id INT NOT NULL,
  user_id INT NOT NULL
)
PARTITION BY RANGE (activity_time);
```

We were using a `SERIAL` column for `activity_id` in the original table. If you want to keep the same sequence for the new table, you can set the sequence value to the last value of the original table:

```sql
SELECT setval('public.test_user_activities_activity_id_seq', (SELECT MAX(activity_id) FROM public.old_user_activities));
```

In general, we also need to ensure other properties from the old table, such as privileges, constraints, defaults, indexes, etc. are also applied to the new table.

3. Use the `create_parent()` function provided by `pg_partman` to set up partitioning on the new table:

```sql
SELECT partman.create_parent(
  p_parent_table := 'public.test_user_activities',
  p_control := 'activity_time',
  p_interval := '1 week'
);
```

4. Now, we can migrate data from the old table to the new partitioned table in smaller batches:

```sql
CALL partman.partition_data_proc(
  p_parent_table := 'public.test_user_activities',
  p_loop_count := 200,
  p_interval := '1 day',
  p_source_table := 'public.old_user_activities'
);
```

This will move the data from `old_user_activities` to the new `test_user_activities` table in daily intervals, committing after each batch. The `p_interval` parameter specifies the interval of values to select in each batch, and `p_loop_count` specifies the total number of batches to move.

5. After the data migration is complete, the old table should be empty, and the new partitioned table should contain all the data and child tables. You can verify this by counting the number of rows in both the tables:

```sql
SELECT COUNT(*) FROM public.test_user_activities
UNION ALL
SELECT COUNT(*) FROM public.old_user_activities;
```

This should return 15 and 0 rows, respectively.

6. Finally, run `VACUUM ANALYZE` on the new partitioned table to update statistics:

```sql
VACUUM ANALYZE public.test_user_activities;
```

The `test_user_activities` table is now successfully partitioned using `pg_partman`, with the data migrated from the old table to the new partitioned structure.

### Uniqueness constraints for partitioned tables

This section applies to partitioned tables created natively in Postgres, as well as those created using `pg_partman`.

Postgres doesn't support indexes or unique constraints that span multiple tables. Since a partitioned table is made up of multiple physical tables, you can't create a unique constraint that spans all the partitions. For example, the following query will fail:

```sql
ALTER TABLE user_activities ADD CONSTRAINT unique_activity UNIQUE (activity_id);
```

It returns the following error:

```text
ERROR:  unique constraint on partitioned table must include all partitioning columns
DETAIL:  UNIQUE constraint on table "user_activities" lacks column "activity_time" which is part of the partition key.
```

However, when the unique constraint involves partition key columns, Postgres can guarantee uniqueness across all partitions. In this way, different partitions cannot share the same values for the partition key columns, which allows unique constraints to be enforced.

For example, including the `activity_time` column in the unique constraint will work because `activity_time` is a partition key column:

```sql
ALTER TABLE user_activities ADD CONSTRAINT unique_activity UNIQUE (activity_id, activity_time);
```

## Conclusion

By leveraging `pg_partman`, you can significantly enhance the native partitioning functionality of Postgres, particularly for large-scale and time-series datasets. The extension simplifies partition management, automates retention and archival tasks, and improves query performance.

## Reference

- [pg_partman Documentation](https://github.com/pgpartman/pg_partman)
- [PostgreSQL Partitioning Documentation](https://www.postgresql.org/docs/current/ddl-partitioning.html)

--- [Document source](https://neon.com/docs/extensions/pg_prewarm.md) ---

> Summary: The `pg_prewarm` extension loads table and index data directly into the Postgres shared buffer cache before queries run, eliminating cold-read latency after a restart. Use it when predictable post-restart performance matters or before heavy read operations on infrequently accessed indexes. Call `pg_prewarm('relation_name')` to load one relation at a time; effectiveness depends on available shared_buffers memory.

# The pg_prewarm extension

Load data into your Postgres buffer cache with the pg_prewarm extension

Last updated: 2026-06-05

You can use the `pg_prewarm` extension to preload data into the Postgres buffer cache after a restart. Doing so improves query response times by ensuring that your data is readily available in memory. Otherwise, data must be loaded into the buffer cache from disk on-demand, which can result in slower query response times.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers the `pg_prewarm` extension: how to enable it and how to use it to prewarm your Postgres buffer cache.

**Note:** The `pg_prewarm` extension is open-source and can be installed on any Postgres setup. Detailed information about the extension is available in the [PostgreSQL Documentation](https://www.postgresql.org/docs/current/pgprewarm.html).

**Version availability**

Please refer to the [list of extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for information about the version of `pg_prewarm` that Neon supports.

## Enable the `pg_prewarm` extension

Enable the `pg_prewarm` extension by running the `CREATE EXTENSION` statement in your Postgres client:

```sql
CREATE EXTENSION IF NOT EXISTS pg_prewarm;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Basic usage

To prewarm a specific table, simply use the `pg_prewarm` function with the name of the table you want to cache.

```sql
SELECT pg_prewarm('table_name');
```

Replace `table_name` with the actual name of your table.

The output of `SELECT pg_prewarm()` is the number of blocks from the specified table that was loaded into the Postgres buffer cache. The default block size in Postgres is 8192 bytes (8KB).

The `pg_prewarm` function does not support specifying multiple table names in a single command. It's designed to work with a single table at a time. If you want to prewarm multiple tables, you would need to call `pg_prewarm` separately for each.

## Running pg_prewarm on indexes

Running `pg_prewarm` on frequently-used indexes can help improve query performance after a Postgres restart. You might also run `pg_prewarm` on indexes that are not frequently used but will be involved in upcoming heavy read operations.

Running `pg_prewarm` on an index is similar to running it on a table, but you specify the index's fully qualified name (schema name plus index name) or OID (Object Identifier) instead.

Here's an example that demonstrates how to use `pg_prewarm` to preload an index into memory:

```sql
SELECT pg_prewarm('schema_name.index_name');
```

Replace `schema_name.index_name` with the actual schema and index name you want to prewarm. If you're not sure about the index name or want to list all indexes for a specific table, you can use the `pg_indexes` view to find out. Here's how you might query for index names:

```sql
SELECT indexname FROM pg_indexes WHERE tablename = 'your_table_name';
```

Replace `your_table_name` with the name of the table whose indexes you're interested in. Once you have the index name, you can then use `pg_prewarm` as shown above.

Additionally, if you prefer to use the index's OID, you can find it using the `pg_class` system catalog. Here's how to find an index's OID:

```sql
SELECT oid FROM pg_class WHERE relname = 'index_name';
```

Then, you can use the OID with `pg_prewarm` like so:

```sql
SELECT pg_prewarm(your_index_oid);
```

## Check the proportion of a table loaded into memory

In this example, you create a table, check its data size, run `pg_prewarm`, and then check to see how much of the table's data was loaded into memory.

1. First, create a table and populate it with some data:

   ```sql
   CREATE TABLE t_test AS
   SELECT * FROM generate_series(1, 1000000) AS id;
   ```

2. Check the size of the table:

   ```sql
   SELECT pg_size_pretty(pg_relation_size('t_test')) AS table_size_pretty,
       pg_relation_size('t_test') AS table_size_bytes;
   ```

   This command returns the size of the table in both MB and bytes.

   ```sql
    table_size_pretty | table_size_bytes
   -------------------+------------------
   35 MB              |         36700160
   ```

3. Load the table data into the Postgres buffer cache using `pg_prewarm`:

   ```sql
   SELECT pg_prewarm('public.t_test') AS blocks_loaded;
   ```

   This will output the number of blocks that were loaded:

   ```sql
   blocks_loaded
   ---------------
           4480
   ```

4. To understand the calculation that follows, check the block size of your Postgres instance:

   ```sql
   SHOW block_size;
   ```

   The default block size in Postgres is 8192 bytes (8KB). We'll use this value in the next step.

   ```sql
   block_size
   ------------
   8192
   ```

5. Calculate the total size of the data loaded into the cache using the block size and the number of blocks loaded:

   ```sql
   -- Assuming 4480 blocks were loaded (replace with your actual number from pg_prewarm output)
   SELECT 4480 * 8192 AS loaded_data_bytes;
   ```

   You can now compare this value with the size of your table.

   ```sql
    loaded_data_bytes
   -------------------
           36700160
   ```

   **Note:** The values for the size of the table and the size of the data loaded into the buffer cache as shown in the example above match exactly, which is an ideal scenario. However, there are cases where these values might not match, indicating that not all the data was loaded into the buffer cache; for example, this can happen if `pg_prewarm` only partially loads the table into the buffer cache due to lack of memory availability. Concurrent data modifications could also cause sizes to differ.

   To understand how much memory is available to your Postgres instance on Neon, see [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

## Demonstrating the effect of pg_prewarm

This example shows how preloading data can improve query performance. We'll create two tables with the same data, preload one table, and then run `EXPLAIN ANALYZE` to compare execution time results.

1. Create two sample tables with the same data for comparison:

   ```sql
   CREATE TABLE tbl_transactions_1
   (
       tran_id_ SERIAL,
       transaction_date TIMESTAMPTZ,
       transaction_name TEXT
   );

   INSERT INTO tbl_transactions_1
   (transaction_date, transaction_name)
   SELECT x, 'dbrnd'
   FROM generate_series('2010-01-01 00:00:00'::timestamptz, '2018-02-01 00:00:00'::timestamptz, '1 minutes'::interval) a(x);
   ```

   ```sql
   CREATE TABLE tbl_transactions_2
   (
       tran_id_ SERIAL,
       transaction_date TIMESTAMPTZ,
       transaction_name TEXT
   );

   INSERT INTO tbl_transactions_2
   (transaction_date, transaction_name)
   SELECT x, 'dbrnd'
   FROM generate_series('2010-01-01 00:00:00'::timestamptz, '2018-02-01 00:00:00'::timestamptz, '1 minutes'::interval) a(x);
   ```

2. Restart your Postgres instance to clear the cache. On Neon, you can do this by [restarting your compute](https://neon.com/docs/manage/computes#restart-a-compute).

3. Prewarm the first sample table:

   ```sql
   SELECT pg_prewarm('tbl_transactions_1') AS blocks_loaded;
   ```

   This will output the number of blocks that were loaded into the cache:

   ```sql
   blocks_loaded
   ---------------
           27805
   ```

4. Now, compare the execution plan of the prewarmed table vs. a non-prewarmed table to see the performance improvement.

   ```sql
   EXPLAIN ANALYZE SELECT * FROM tbl_transactions_1;
   ```

   ```sql
   EXPLAIN ANALYZE SELECT * FROM tbl_transactions_2;
   ```

   The execution time for the prewarmed table should be significantly lower than for the table that has not been prewarmed, as shown here:

   ```sql
   EXPLAIN ANALYZE SELECT * FROM tbl_transactions_1;
                                                         QUERY PLAN
   -------------------------------------------------------------------------------------------------------------------------------
   Seq Scan on tbl_transactions_1  (cost=0.00..69608.21 rows=4252321 width=18) (actual time=0.017..228.995 rows=4252321 loops=1)
   Planning Time: 1.134 ms
   Execution Time: 344.028 ms
   (3 rows)

   EXPLAIN ANALYZE SELECT * FROM tbl_transactions_2;
                                                           QUERY PLAN
   ---------------------------------------------------------------------------------------------------------------------------------
   Seq Scan on tbl_transactions_2  (cost=0.00..69608.21 rows=4252321 width=18) (actual time=2.251..11859.232 rows=4252321 loops=1)
   Planning Time: 0.216 ms
   Execution Time: 11994.066 ms
   (3 rows)
   ```

## Conclusion

Prewarming your table data and indexes can help improve read performance, especially after a database restart or for indexes that are not frequently used but will be involved in upcoming heavy read operations. However, it's important to use this feature cautiously, especially on systems with limited memory, to avoid potential negative impacts on overall performance.

## Resources

- [PostgreSQL pg_prewarm documentation](https://www.postgresql.org/docs/current/pgprewarm.html)
- [How to size your compute in Neon](https://neon.com/docs/manage/computes#how-to-size-your-compute)

--- [Document source](https://neon.com/docs/extensions/pg_repack.md) ---

> Summary: pg_repack rewrites bloated tables and indexes online, reclaiming dead-tuple space without the exclusive locks required by VACUUM FULL or CLUSTER. Use it on Neon when frequent updates and deletes have degraded query performance or inflated storage. Always pass `--no-superuser-check` (`-k`) since Neon users are not superusers. Repacking temporarily doubles storage and increases WAL history for the duration of your PITR window.

# The pg_repack extension

Remove bloat from your tables and indexes with minimal locking

Last updated: 2026-09-16

Postgres, like any database system, can accumulate bloat over time due to frequent updates and deletes. Bloat refers to wasted space within your tables and indexes, which can lead to decreased query performance and increased storage usage. `pg_repack` is a powerful Postgres extension that allows you to efficiently remove this bloat by rewriting tables and indexes online, with minimal locking. Unlike `VACUUM FULL` or `CLUSTER`, `pg_repack` avoids exclusive locks, ensuring your applications remain available during the reorganization process.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers the `pg_repack` extension and how to use it in your Neon database. You'll learn how to install and use `pg_repack` to reclaim disk space and improve database performance by removing bloat from your tables and indexes.

**Important:** Before using `pg_repack` on Neon, review the [Storage impact on Neon](https://neon.com/docs/extensions/pg_repack#best-practices-and-considerations) section to understand how repack operations temporarily increase your project storage due to WAL generation and your [history window](https://neon.com/docs/introduction/history-window) setting.

## Enable the `pg_repack` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS pg_repack;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Understanding `pg_repack` and bloat

Before using `pg_repack`, it's helpful to understand what causes bloat and how `pg_repack` addresses it.

### What is Bloat?

In Postgres, when rows in a table are updated or deleted, the space they occupied isn't immediately reclaimed. Instead, Postgres uses a mechanism called Multi-Version Concurrency Control (MVCC). While MVCC is essential for concurrency and transactional integrity, it can lead to **dead tuples** – outdated row versions that are no longer needed but still occupy space. Indexes also become bloated as they point to these dead tuples or become fragmented over time. This unused space is known as bloat.

### Why remove bloat?

Bloat can negatively impact your database in several ways:

- **Reduced query performance:** Postgres has to scan through bloated tables and indexes, increasing I/O operations and slowing down queries.
- **Increased storage usage:** Bloat consumes disk space, leading to higher storage costs in the long run, especially in a cloud environment like Neon.
- **Inefficient vacuuming:** While regular `VACUUM` helps, it doesn't fully reclaim space from bloat. `VACUUM FULL` does, but it requires an exclusive lock, causing downtime.

### How `pg_repack` works

`pg_repack` provides an online solution to defragment tables and indexes. It works by creating a new copy of the table and indexes, efficiently copying data from the original table to the new one, and then atomically replacing the old table with the new one.

Key features of `pg_repack` include:

- **Online operation:** It operates without requiring exclusive locks for most of the process, minimizing downtime.
- **Minimal locking:** Only short `ACCESS EXCLUSIVE` locks are needed at the beginning and end of the repack process.
- **Bloat removal:** Effectively removes bloat from both tables and indexes, reclaiming disk space and improving performance.
- **Reordering options:** Allows you to optionally reorder table rows based on a clustered index or specified columns, further optimizing data access.
- **Index repack:** You can repack indexes independently of the table, which can be useful for index-specific bloat issues.

**Important:** `pg_repack` requires the target table to have a `PRIMARY KEY` or at least a `UNIQUE` index on a `NOT NULL` column. Ensure your table meets this requirement before running `pg_repack`.

## Understanding `pg_repack` Syntax

While `psql` allows you to run commands directly within the SQL environment, `pg_repack` is a command-line tool that you execute from your terminal. If you haven't installed it yet, you'll find installation instructions on the [pg_repack GitHub repository](https://reorg.github.io/pg_repack/#download). The general syntax is as follows:

**Note:** Make sure to install the correct version of `pg_repack` that is being used in your Neon environment. Currently, Neon uses `pg_repack` version 1.5.2

```bash
pg_repack [OPTIONS]... [DBNAME]
```

Let's break down the key components:

- **`pg_repack`**: This is the command itself, invoking the `pg_repack` executable. Ensure that `pg_repack` is installed and accessible in your system's `PATH`.
- **`[OPTIONS]...`**: These are command-line options that modify the behavior of `pg_repack`. Options are typically provided in the format `--option-name=value` or `-short-option value`. You can specify multiple options to customize the repack operation.
- **`[DBNAME]`**: This is the name of the Postgres database you want to connect to. You can also specify the database connection details using connection options (see below), in which case you might omit `DBNAME` here.

### Common `pg_repack` options

`pg_repack` offers a variety of options to control its behavior. Here are some of the most commonly used options:

### Reorganization options

- **`-t TABLE`, `--table=TABLE`**: Specifies the table to be reorganized. You can reorganize multiple tables by using this option multiple times (for example, `-t table1 -t table2`). By default, all eligible tables in the target databases are reorganized.
- **`-I TABLE`, `--parent-table=TABLE`**: Reorganize both the specified table(s) and its inheritors.
- **`-c SCHEMA`, `--schema=SCHEMA`**: Repacks all eligible tables within the specified schema(s).
- **`-o COLUMNS [,...]`, `--order-by=COLUMNS [,...]`**: Reorders the table rows based on the specified column(s). This performs an online `CLUSTER`.
- **`-n`, `--no-order`**: Performs an online `VACUUM FULL` instead of a `CLUSTER` operation, even for clustered tables. This is the default for non-clustered tables since `pg_repack` 1.2.
- **`-x`, `--only-indexes`**: Repacks only the indexes of the specified table(s). Requires using `-t` or `-I` to specify the target table.
- **`-i INDEX`, `--index=INDEX`**: Repacks only the specified index. You can specify multiple indexes with multiple `-i` options.
- **`-j NUM`, `--jobs=NUM`**: Uses multiple parallel jobs (connections) to speed up index rebuilding. Useful for servers with multiple CPU cores and sufficient I/O capacity.
- **`-N`, `--dry-run`**: Performs a "dry run," listing the actions `pg_repack` _would_ take without actually executing them. Useful for previewing the operation.
- **`-Z`, `--no-analyze`**: Skips running `ANALYZE` on the repacked table(s) at the end of the process. By default, `pg_repack` runs `ANALYZE`.
- **`-k`, `--no-superuser-check`**: **Crucially important for Neon!** Skips the superuser check. You must use this option when running `pg_repack` against Neon, as Neon users are not superusers.

### Connection options

These options specify how `pg_repack` connects to your database. You can often omit the `DBNAME` from the main command if you provide these connection options.

- **`-d DBNAME`, `--dbname=DBNAME`**: Specifies the database name to connect to.
- **`-h HOSTNAME`, `--host=HOSTNAME`**: Specifies the hostname of your Neon endpoint. You can find this by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.
- **`-p PORT`, `--port=PORT`**: Specifies the port. For Neon, this is always `5432`.
- **`-U USERNAME`, `--username=USERNAME`**: Specifies your Neon username. You can find this by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.
- **`-W`, `--password`**: Forces `pg_repack` to prompt for your password.

### Generic options

- **`-e`, `--echo`**: Prints the SQL commands executed by `pg_repack` to the terminal. Useful for debugging or understanding the process.
- **`-E LEVEL`, `--elevel=LEVEL`**: Sets the output message level (for example, `DEBUG`, `INFO`, `WARNING`, `ERROR`). Defaults to `INFO`.
- `--help`: Displays help information about `pg_repack` and its options.
- `--version`: Displays the version of `pg_repack`.

## Key use cases for `pg_repack`

`pg_repack` is a versatile tool that can address various performance and maintenance challenges. Here are some common use cases where `pg_repack` can be beneficial:

### Reclaim space from bloated tables

Over time, tables can accumulate bloat from updates and deletes, wasting storage and impacting performance. `pg_repack` rewrites tables to remove dead rows and reclaim unused space, similar to `VACUUM FULL`, but crucially, **without blocking write operations**. This is essential for maintaining application availability.

```bash
-- Repack a single table (performs online VACUUM FULL)
pg_repack --no-order --table orders;
```

### Reorder data by an index for optimized queries

If you frequently query your data based on a specific index, physically reordering the table rows according to that index can significantly improve query performance. This is similar to the `CLUSTER` command, but `pg_repack` performs this reordering **online**, minimizing disruption.

```bash
-- Reorder the 'orders' table by 'order_date' in descending order
pg_repack --table orders --order-by "order_date DESC";
```

### Rebuild indexes online to improve scan performance

Indexes can become fragmented over time, leading to less efficient index scans. `pg_repack` can rebuild indexes **online**, creating fresh, optimized indexes to improve query performance without locking the table for writes.

```bash
-- Rebuild all indexes of the 'orders' table
pg_repack --table orders --only-indexes;
```

### Example syntax

Here are a few examples of how to use `pg_repack` with different options:

### Basic repack of a table

```bash
pg_repack -k -h <your_neon_host> -p 5432 -d <your_neon_database> -U <your_neon_username> --table your_table_name
```

### Reordering a table by a column

```bash
pg_repack -k -h <your_neon_host> -p 5432 -d <your_neon_database> -U <your_neon_username> --table your_table_name --order-by "indexed_column DESC"
```

### Repacking only indexes of a table

```bash
pg_repack -k -h <your_neon_host> -p 5432 -d <your_neon_database> -U <your_neon_username> --table your_table_name --only-indexes
```

### Dry run to preview repack operations

```bash
pg_repack -k -N -h <your_neon_host> -p 5432 -d <your_neon_database> -U <your_neon_username> --table your_table_name
```

## Using `pg_repack` to reorganize tables

Let's walk through a practical example of using `pg_repack` to reorganize a table in your Neon database.

### Connect to your Neon Database

Ensure you are connected to your Neon database using [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor). You can find your connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

### Create a sample table with bloat (Optional)

For demonstration purposes, let's create a sample table and introduce some bloat. If you already have a table you want to repack, you can skip this step.

```sql
CREATE TABLE public.bloated_table (
    id SERIAL PRIMARY KEY,
    data TEXT
);

-- Insert some initial data
INSERT INTO public.bloated_table (data)
SELECT md5(random()::text)
FROM generate_series(1, 100000);

-- Delete a significant portion of the data to simulate bloat
DELETE FROM public.bloated_table WHERE id % 2 = 0;
```

### Verify table size before `pg_repack`

Let's check the size of the table before running `pg_repack`. You can use the `\dt+` command in `psql` or query `pg_relation_size` in SQL.

In `psql`:

```psql
\dt+ bloated_table
```

Or in SQL:

```sql
SELECT pg_size_pretty(pg_relation_size('bloated_table'));
```

Note the size of the table before repack.

### Run `pg_repack`

Now, execute the `pg_repack` command from your terminal

```bash
pg_repack -k -h <your_neon_host> -p 5432 -d <your_neon_database> -U <your_neon_username> --table bloated_table
```

Replace the placeholders with your Neon connection details.

- `-h <your_neon_host>`: Your Neon hostname.
- `-p 5432`: The port (always 5432 for Lakebase Postgres).
- `-d <your_neon_database>`: Your Neon database name.
- `-U <your_neon_username>`: Your Neon username.
- `--table bloated_table`: Specifies the table to repack.

You will be prompted to enter your Neon password after running the command.

### Verify table size after `pg_repack`

After `pg_repack` completes successfully, check the table size again using the same command as before.
You should observe a reduction in the table size, indicating that `pg_repack` has successfully removed bloat.

**Example Output (Size Reduction)**

Before `pg_repack`:

```text
 Schema |      Name       | Type  |    Owner     | Persistence | Access method |   Size   | Description
--------+-----------------+-------+--------------+-------------+---------------+----------+-------------
 public | bloated_table   | table | neondb_owner | permanent   | heap          | 8192 kB  |
(1 row)
```

After `pg_repack`:

```text
 Schema |      Name       | Type  |    Owner     | Persistence | Access method |   Size   | Description
--------+-----------------+-------+--------------+-------------+---------------+----------+-------------
 public | bloated_table   | table | neondb_owner | permanent   | heap          | 4096 kB  |
(1 row)
```

In this example, the table size was reduced from 8MB to 4MB after running `pg_repack`. The actual size reduction will depend on the amount of bloat present in your table.

## Best Practices and Considerations

While `pg_repack` generally works well with Neon, here are a few things to keep in mind:

- **`-k` / `--no-superuser-check` flag:** Always use the `-k` / `--no-superuser-check` flag when running `pg_repack` against your Neon database.
- **Resource usage:** While `pg_repack` is designed to be online, it does consume resources (CPU, I/O) during operation. Consider running it during off-peak hours for very resource-intensive operations, especially on production databases.

**Important: Storage impact on Neon**

Running `pg_repack` can temporarily **increase** your Neon project's storage size. This happens because `pg_repack` creates a new copy of the target table that generates  Write-Ahead Log (WAL) data during the rewriting process.

**Key points to understand:**

- **Disk space during operation:** `pg_repack` requires temporary disk space roughly double the size of the table being repacked. For example, repacking a 1GB table requires an additional ~2GB of free space during the operation.
- **History storage increase:** All writes generated by `pg_repack` are stored in your [history window](https://neon.com/docs/introduction/history-window) (also known as your Point-in-Time Recovery or PITR window). This can significantly increase your project storage. See [Instant restore pricing](https://neon.com/docs/introduction/plans#instant-restore) for cost details on paid plans.
- **Storage remains elevated:** The increased storage persists until the writes age out of your [history window](https://neon.com/docs/introduction/history-window). For example, if you have a 7-day history window, the storage increase from a repack operation will remain for up to 7 days.

**Recommendations:**

- Monitor your project storage before and after running `pg_repack` to understand the impact, but be aware that the increase in storage may not show up immediately due to reporting delays of up to one hour.
- Consider your [history window](https://neon.com/docs/introduction/history-window) duration when planning repack operations, especially if running them frequently. Different [Neon plans](https://neon.com/docs/introduction/plans#history-window) support different history window limits.
- For daily or weekly repack schedules on large tables, factor in the cumulative storage costs during your [history window](https://neon.com/docs/introduction/history-window) period.
- If minimizing storage costs is critical, consider adjusting your history window setting or scheduling repack operations less frequently.

## Conclusion

`pg_repack` is an invaluable tool for maintaining the health and performance of your database. By enabling you to remove bloat online and with minimal locking, it helps ensure your database remains efficient, responsive, and cost-effective. Regularly using `pg_repack`, especially on tables with frequent updates and deletes, can help you reclaim disk space, improve query performance, and optimize your database.

## References

- [pg_repack GitHub Repository](https://github.com/reorg/pg_repack)
- [pg_repack Documentation on PGXN](https://pgxn.org/dist/pg_repack/)
- [Investigating Postgres Query Performance](https://neon.com/blog/postgres-support-recap-investigating-postgres-query-performance)

--- [Document source](https://neon.com/docs/extensions/pg_search.md) ---

> Summary: The `pg_search` extension by ParadeDB added BM25 full-text search to Postgres. It was deprecated for new Neon projects on March 19, 2026, and retired from existing projects on September 21, 2026. Its replacement for BM25 search is the `lakebase_text` extension; other alternatives include tsvector, pg_trgm, and pgvector.

# The pg_search extension

Deprecated BM25 full-text search extension (ParadeDB)

Last updated: 2026-09-27

**Warning: Neon's support for pg_search has been removed.**

`pg_search` was deprecated for new Neon projects on March 19, 2026.

**If you used `pg_search`:** the extension was retired from existing projects on September 21, 2026. Its replacement for BM25 search on Neon is `lakebase_text`; see [Migrate from pg_search to lakebase_text](https://neon.com/docs/extensions/migrate-pg-search-to-lakebase-text).

Depending on your use case, consider these alternatives:

- **Full-text search**: PostgreSQL's built-in [`tsvector`/`tsquery`](https://www.postgresql.org/docs/current/textsearch.html)
- **Fuzzy search**: [`pg_trgm`](https://www.postgresql.org/docs/current/pgtrgm.html) for similarity and pattern matching
- **Semantic/vector search**: [`pgvector`](https://neon.com/docs/extensions/pgvector) for embedding-based search
- **BM25 search**: [`lakebase_text`](https://neon.com/docs/extensions/lakebase-text), a BM25 index for Neon, fully compatible with `tsvector`; or [ParadeDB](https://www.paradedb.com/) for continued `pg_search` functionality

The `pg_search` extension by [ParadeDB](https://www.paradedb.com/) added BM25 full-text search to Postgres, using inverted indexes and the `@@@` operator to run keyword, phrase, fuzzy, and faceted search through SQL and a JSON query DSL. It's no longer available on Neon.

To replace `pg_search` with `lakebase_text` on Neon, see [Migrate from pg_search to lakebase_text](https://neon.com/docs/extensions/migrate-pg-search-to-lakebase-text). For the full `pg_search` feature reference, see the [ParadeDB documentation](https://docs.paradedb.com/welcome/introduction).

--- [Document source](https://neon.com/docs/extensions/pg_session_jwt.md) ---

> Summary: The `pg_session_jwt` Postgres extension validates JWT tokens using a JWK and exposes `auth.user_id()`, `auth.session()`, and `auth.uid()` to extract the `sub` claim for use in Row-Level Security policies. It powers the Neon Data API, which installs and configures the extension automatically; without a JWK it falls back to PostgREST-compatible `request.jwt.claims`. Use this page when building custom auth setups outside the Data API or writing RLS policies that filter rows by authenticated user identity.

# The pg_session_jwt extension

Handle authenticated sessions through JWTs in Postgres

Last updated: 2026-06-05

**Related resources**

- [Neon Data API](https://neon.com/docs/data-api/overview)
- [Custom authentication providers](https://neon.com/docs/data-api/custom-authentication-providers)
- [Row-Level Security (RLS)](https://neon.com/docs/guides/row-level-security)

**Source code**

- [pg_session_jwt on GitHub](https://github.com/neondatabase/pg_session_jwt)

**Important:** The `pg_session_jwt` extension is automatically installed when you enable the [Neon Data API](https://neon.com/docs/data-api/overview) for a branch. Do not install this extension manually.

The `pg_session_jwt` extension is a Postgres extension designed to handle authenticated sessions through JSON Web Tokens (JWTs). When configured with a JWK (JSON Web Key), it verifies JWT authenticity. When operating without a JWK, it falls back to using PostgREST-compatible JWT claims.

This extension powers the [Neon Data API](https://neon.com/docs/data-api/overview), enabling secure session management and Row-Level Security (RLS) based on user identity.

## Features

- **JWT session initialization** using a JWK (JSON Web Key) for secure JWT validation
- **Flexible authentication modes**: use either JWK-validated JWTs or PostgREST-compatible JWT claims
- **User ID retrieval** directly from the database for use in RLS policies
- **JSONB-based storage** and retrieval of session information

## How it works

The extension can operate in two modes:

### With JWK validation

When a JWK is configured, the extension validates JWT signatures and extracts user information from verified tokens. This is the mode used by the Neon Data API.

### With PostgREST-compatible JWT claims

When operating without a JWK, the extension works with PostgREST-compatible JWT claims via the `request.jwt.claims` parameter. This provides compatibility with PostgREST's JWT handling.

## Functions

The `pg_session_jwt` extension provides functions in the `auth` schema:

### auth.user_id()

Returns the user ID (`sub` claim) from the current session's JWT.

```sql
SELECT auth.user_id();
```

This function is commonly used in RLS policies to filter data by the authenticated user:

```sql
CREATE POLICY "Users can only see their own data"
  ON todos
  FOR SELECT
  USING (user_id = auth.user_id());
```

### auth.session()

Returns the entire JWT payload as JSONB, giving you access to all claims in the token.

```sql
SELECT auth.session();
```

### auth.jwt()

Alias for `auth.session()`.

### auth.uid()

Similar to `auth.user_id()` but returns UUID type. Expects the `sub` claim to be a valid UUID, otherwise returns NULL.

```sql
SELECT auth.uid();
```

## Usage with Neon Data API

The `pg_session_jwt` extension is automatically configured when you enable the [Neon Data API](https://neon.com/docs/data-api/overview). The Data API handles JWT validation using your configured authentication provider's JWKS URL.

When making requests to the Data API, include your JWT in the `Authorization` header:

```http
GET https://your-project.data.neon.tech/v1/todos
Authorization: Bearer <your-jwt-token>
```

The Data API validates the token and makes the user identity available via `auth.user_id()` for your RLS policies.

## Usage with custom setups

For custom implementations outside of the Neon Data API, you can configure the extension manually:

### Initialize with JWK

Set the JWK at connection time using libpq options:

```bash
export PGOPTIONS="-c pg_session_jwt.jwk=$MY_JWK"
```

Then in your session:

```sql
-- Initialize the session with the configured JWK
SELECT auth.init();

-- Set the JWT for the current session
SELECT auth.jwt_session_init('your.jwt.token');

-- Now you can use auth functions
SELECT auth.user_id();
```

### Using PostgREST-compatible claims

When no JWK is configured, set claims via the `request.jwt.claims` parameter:

```sql
SET request.jwt.claims = '{"sub": "user-123", "role": "authenticated"}';
SELECT auth.user_id();  -- Returns 'user-123'
```

**Warning:** When using the fallback mode without JWK validation, `request.jwt.claims` is a regular Postgres parameter that can be modified by any database user. Ensure your application sets these claims securely before executing user queries.

## References

- [pg_session_jwt on GitHub](https://github.com/neondatabase/pg_session_jwt)
- [Neon Data API documentation](https://neon.com/docs/data-api/overview)
- [Custom authentication providers](https://neon.com/docs/data-api/custom-authentication-providers)
- [Row-Level Security guide](https://neon.com/docs/guides/row-level-security)

--- [Document source](https://neon.com/docs/extensions/pg_stat_statements.md) ---

> Summary: The `pg_stat_statements` extension records per-query execution counts, total and mean execution times, and row counts in a queryable view. Use it to identify slow queries, high-frequency queries, and cache inefficiency without external tooling. On Neon, statistics reset whenever the compute suspends or scales to zero. Only `neon_superuser` roles can call `pg_stat_statements_reset()` to clear accumulated stats manually.

# The pg_stat_statements extension

Track planning and execution statistics for all SQL statements

Last updated: 2026-11-04

The `pg_stat_statements` extension provides a detailed statistical view of SQL statement execution within a Postgres database. It tracks information such as execution counts, total and average execution times, and more, helping database administrators and developers analyze and optimize SQL query performance.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers:

- [Enabling pg_stat_statements](https://neon.com/docs/extensions/pg_stat_statements#enable-the-pgstatstatements-extension)
- [Usage examples](https://neon.com/docs/extensions/pg_stat_statements#usage-examples)
- [Resetting statistics](https://neon.com/docs/extensions/pg_stat_statements#reset-statistics)

**Note:** `pg_stat_statements` is an open-source extension for Postgres that can be installed on any Neon project using the instructions below.

### Version availability

The version of `pg_stat_statements` available on Neon depends on the version of Postgres you select for your Neon project. For supported extension versions, see [Supported Postgres extensions](https://neon.com/docs/extensions/pg-extensions).

### Data persistence

In Neon, statistics collected by the `pg_stat_statements` extension are not retained when your Neon compute (where Postgres runs) is suspended or restarted. For example, if your compute scales down to zero due to inactivity, any existing statistics are lost. New statistics will be gathered once your compute restarts. For more details about the lifecycle of a Neon compute, see [Compute lifecycle](https://neon.com/docs/introduction/compute-lifecycle). For information about configuring Neon's scale to zero behavior, see [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero).

## Enable the `pg_stat_statements` extension

The Console's [Query performance](https://neon.com/docs/introduction/monitor-query-performance) view works without this step. To query `pg_stat_statements` yourself, or to use commands such as `neon inspect db outliers`, install the extension in your database by running the following `CREATE EXTENSION` statement in the Neon **SQL Editor** or from a client such as `psql` that is connected to Neon.

```sql
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Usage examples

This section provides `pg_stat_statements` usage examples.

### Query the pg_stat_statements view

The main interface is the `pg_stat_statements` view, which contains one row per distinct database query, showing various statistics.

```sql
SELECT * FROM pg_stat_statements LIMIT 10;
```

The view contains details like those shown below:

```
| userid | dbid  | queryid               | query                 | calls |
|--------|-------|-----------------------|-----------------------|-------|
| 16391  | 16384 | -9047282044438606287  | SELECT * FROM users;  | 10    |
```

For a complete list of `pg_stat_statements` columns and descriptions, see [The pg_stat_statements View](https://www.postgresql.org/docs/current/pgstatstatements.html#PGSTATSTATEMENTS-PG-STAT-STATEMENTS).

Let's explore some example usage patterns.

### Find the most frequently executed queries

The most frequently run queries are often critical paths and optimization candidates.

This query retrieves details about the most frequently executed queries, ordered by the number of calls. Only the top 10 rows are returned (`LIMIT 10`):

```sql
SELECT
  userid,
  query,
  calls,
  (total_exec_time / 1000 / 60) as total_min,
  mean_exec_time as avg_ms
FROM pg_stat_statements
ORDER BY 3 DESC
LIMIT 10;
```

As an alternative to writing SQL, the Neon CLI wraps these two queries as [`neon inspect db calls`](https://neon.com/docs/cli/inspect#db-calls) and [`neon inspect db outliers`](https://neon.com/docs/cli/inspect#db-outliers).

### Monitor slow queries

A high average runtime can indicate an inefficient query.

The query below uses the `query`, `mean_exec_time` (average execution time per call), and `calls` columns. The condition `WHERE mean_exec_time > 1` filters out queries with an average execution time greater than 1 unit (you may adjust this threshold as needed).

```sql
SELECT
    query,
    mean_exec_time,
    calls
FROM
    pg_stat_statements
WHERE
    mean_exec_time > 1
ORDER BY
    mean_exec_time DESC;
```

This query returns the following results:

```
| Query                                         | Mean Time | Calls |
|-----------------------------------------------|-----------|-------|
| SELECT p.*, c.name AS category FROM products  | 250.60ms  |  723  |
```

This query retrieves the top 10 queries with the highest average execution time, focusing on queries run more than 500 times, for the current user.

```sql
WITH statements AS (
    SELECT *
    FROM pg_stat_statements pss
    JOIN pg_roles pr ON (pss.userid = pr.oid)
    WHERE pr.rolname = current_user
)
SELECT
    calls,
    mean_exec_time,
    query
FROM statements
WHERE
    calls > 500
    AND shared_blks_hit > 0
ORDER BY
    mean_exec_time DESC
LIMIT 10;
```

This query returns the 10 longest-running queries for the current user, focusing on those executed over 500 times and with some cache usage. It orders queries by frequency and cache efficiency to highlight potential areas for optimization.

```sql
WITH statements AS (
    SELECT *
    FROM pg_stat_statements pss
    JOIN pg_roles pr ON (pss.userid = pr.oid)
    WHERE pr.rolname = current_user
)
SELECT
    calls,
    shared_blks_hit,
    shared_blks_read,
    shared_blks_hit / (shared_blks_hit + shared_blks_read)::NUMERIC * 100 AS hit_cache_ratio,
    query
FROM statements
WHERE
    calls > 500
    AND shared_blks_hit > 0
ORDER BY
    calls DESC,
    hit_cache_ratio ASC
LIMIT 10;
```

This query retrieves the top 10 longest-running queries (in terms of mean execution time), focusing on queries executed more than 500 times, for the current user.

```sql
WITH statements AS (
    SELECT *
    FROM pg_stat_statements pss
    JOIN pg_roles pr ON (userid = oid)
    WHERE rolname = current_user
)
SELECT
    calls,
    min_exec_time,
    max_exec_time,
    mean_exec_time,
    stddev_exec_time,
    (stddev_exec_time / mean_exec_time) AS coeff_of_variance,
    query
FROM statements
WHERE calls > 500
AND shared_blks_hit > 0
ORDER BY mean_exec_time DESC
```

### Find queries that return many rows

To identify queries that return a lot of rows, you can select the `query` and `rows` columns, representing the SQL statement and the number of rows returned by each statement, respectively.

```sql
SELECT
    query,
    rows
FROM
    pg_stat_statements
ORDER BY
    rows DESC
LIMIT
    10;
```

This query returns results similar to the following:

```
| Query                                             | Rows    |
|---------------------------------------------------|---------|
| SELECT * FROM products;                           | 112,394 |
| SELECT * FROM users;                              | 98,723  |
| SELECT p.*, c.name AS category FROM products      | 23,984  |
```

### Find the most time-consuming queries

The following query returns details about the most time-consuming queries, ordered by execution time.

```sql
SELECT
  userid,
  query,
  calls,
  total_exec_time,
  rows
FROM
  pg_stat_statements
ORDER BY
  total_exec_time DESC
LIMIT 10;
```

## Reset statistics

When executed, the `pg_stat_statements_reset()` function resets the accumulated statistical data, such as execution times and counts for SQL statements, to zero. Use it when you want to start fresh with performance statistics collection.

**Note:** In Neon, only [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) roles have the privilege required to execute this function. The default role created with a Neon project and roles created in the Neon Console, CLI, and API are granted membership in the `neon_superuser` role.

```sql
SELECT pg_stat_statements_reset();
```

## Resources

- [PostgreSQL documentation for pg_stat_statements](https://www.postgresql.org/docs/current/pgstatstatements.html)

--- [Document source](https://neon.com/docs/extensions/pg_tiktoken.md) ---

> Summary: The `pg_tiktoken` Postgres extension tokenizes text and counts tokens inside SQL queries using OpenAI's tiktoken library, exposing `tiktoken_encode` and `tiktoken_count`. Use it to enforce OpenAI model token limits in database queries without moving data to application code. Supported encodings include cl100k_base (ChatGPT, text-embedding-ada-002), p50k_base (Codex, text-davinci-002/003), and r50k_base (GPT-3/davinci).

# The pg_tiktoken extension

Efficiently tokenize data in your Postgres database using OpenAI's `tiktoken` library

Last updated: 2026-06-05

The `pg_tiktoken` extension enables fast and efficient tokenization of data in your Postgres database using OpenAI's [tiktoken](https://github.com/openai/tiktoken) library.

This topic provides guidance on installing the extension, utilizing its features for tokenization and token management, and integrating the extension with ChatGPT models.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## What is a token?

Language models process text in units called tokens. A token can be as short as a single character or as long as a complete word, such as "a" or "apple." In some languages, tokens may comprise less than a single character or even extend beyond a single word.

For example, consider the sentence "Neon is serverless Postgres." It can be divided into seven tokens: `["Ne", "on", "is", "server", "less", "Post", "gres"]`.

## `pg_tiktoken` functions

The `pg_tiktoken` offers two functions:

- `tiktoken_encode`: Accepts text inputs and returns tokenized output.
- `tiktoken_count`: Counts the number of tokens in a given text. This feature helps you adhere to text length limits, such as those set by OpenAI's language models.

## Install the `pg_tiktoken` extension

You can install the `pg_tiktoken` extension by running the following `CREATE EXTENSION` statement in the Neon **SQL Editor** or from a client such as `psql` that is connected to Neon.

```sql
CREATE EXTENSION pg_tiktoken
```

For information about using the Neon **SQL Editor**, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Use the `tiktoken_encode` function

The `tiktoken_encode` function tokenizes text input and returns a tokenized output. The function accepts encoding names and OpenAI model names as the first argument and the text you want to tokenize as the second argument, as shown:

```sql
SELECT tiktoken_encode('text-davinci-003', 'The universe is a vast and captivating mystery, waiting to be explored and understood.');

tiktoken_encode
--------------------------------------------------------------------------------
 {464,6881,318,257,5909,290,3144,39438,10715,11,4953,284,307,18782,290,7247,13}
(1 row)
```

The function tokenizes text using the [Byte Pair Encoding (BPE)](https://en.wikipedia.org/wiki/Byte_pair_encoding) algorithm.

## Use the `tiktoken_count` function

The `tiktoken_count` function counts the number of tokens in a text. The function accepts encoding names and OpenAI model names as the first argument and text as the second argument, as shown:

```sql
neondb=> SELECT tiktoken_count('text-davinci-003', 'The universe is a vast and captivating mystery, waiting to be explored and understood.');

 tiktoken_count
----------------
             17
(1 row)
```

## Supported models

The `tiktoken_count` and `tiktoken_encode` functions accept both encoding and OpenAI model names as the first argument:

```text
tiktoken_count(<encoding or model>,<text>)
```

The following models are supported:

| Encoding name        | OpenAI model                                                          |
| :------------------- | :-------------------------------------------------------------------- |
| cl100k\_base         | ChatGPT models, text-embedding-ada-002                                |
| p50k\_base           | Code models, text-davinci-002, text-davinci-003                       |
| p50k\_edit           | Use for edit models like text-davinci-edit-001, code-davinci-edit-001 |
| r50k\_base (or gpt2) | GPT-3 models like davinci                                             |

## Integrate `pg_tiktoken` with ChatGPT models

The `pg_tiktoken` extension allows you to store chat message history in a Postgres database and retrieve messages that comply with OpenAI's model limitations.

For example, consider the `message` table below:

```sql
CREATE TABLE message (
  role VARCHAR(50) NOT NULL, -- equals to 'system', 'user' or 'assistant'
  content TEXT NOT NULL,
  created TIMESTAMP NOT NULL DEFAULT NOW(),
  n_tokens INTEGER -- number of content tokens
);
```

The [gpt-3.5-turbo chat model](https://platform.openai.com/docs/guides/chat/introduction) requires specific parameters:

```json
{
  "model": "gpt-3.5-turbo",
  "messages": [
    { "role": "system", "content": "You are a helpful assistant." },
    { "role": "user", "content": "Who won the world series in 2020?" },
    { "role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020." }
  ]
}
```

The `messages` parameter is an array of message objects, with each object containing two pieces of information: The `role` of the message sender (either `system`, `user`, or `assistant`) and the actual message `content`. Conversations can be brief, with just one message, or span multiple pages as long as the combined message tokens do not exceed the 4096-token limit.

To insert `role`, `content`, and the number of tokens into the database, use the following query:

```sql
INSERT INTO message (role, content, n_tokens)
VALUES ('user', 'Hello, how are you?', tiktoken_count('text-davinci-003','Hello, how are you?'));
```

## Manage text tokens

When a conversation contains more tokens than a model can process (for example, over 4096 tokens for `gpt-3.5-turbo`), you will need to truncate the text to fit within the model's limit.

Additionally, lengthy conversations may result in incomplete replies. For example, if a `gpt-3.5-turbo` conversation spans 4090 tokens, the response will be limited to just six tokens.

The following query retrieves messages up to your desired token limits:

```sql
WITH cte AS (
  SELECT role, content, created, n_tokens,
         SUM(tokens) OVER (ORDER BY created DESC) AS cumulative_sum
  FROM message
)

SELECT role, content, created, n_tokens, cumulative_sum
FROM cte
WHERE cumulative_sum <= <MAX_HISTORY_TOKENS>;
```

`<MAX_HISTORY_TOKENS>` represents the conversation history you want to keep for chat completion, following this formula:

```text
MAX_HISTORY_TOKENS = MODEL_MAX_TOKENS – NUM_SYSTEM_TOKENS – NUM_COMPLETION_TOKENS
```

For example, assume the desired completion length is 100 tokens (`NUM_COMPLETION_TOKENS=90`).

```text
MAX_HISTORY_TOKENS = 4096 – 6 – 90 = 4000
```

```json
{
  "model": "gpt-3.5-turbo", // MODEL_MAX_TOKENS = 4096
  "messages": [
         {"role": "system", "content": "You are a helpful assistant."}, // NUM_SYSTEM_TOKENS = 6
         {"role": "user", "content": "Who won the world series in 2020?"},
         {"role": "assistant", "content": "The Los Angeles Dodgers won the World Series in 2020."},
         {"role": ...}
         .
         .
         .
         {"role": "user", "content": "Great! Have a great day."}  // MAX_HISTORY_TOKENS = 4000
    ]
}
```

## Conclusion

In conclusion, the `pg_tiktoken` extension is a valuable tool for tokenizing text data and managing tokens within Postgres databases. By leveraging OpenAI's tiktoken library, it simplifies the process of tokenization and working with token limits, enabling you to integrate more easily with OpenAI's language models.

As you explore the capabilities of the `pg_tiktoken extension`, we encourage you to provide feedback and suggest features you'd like to see added in future updates. We look forward to seeing the innovative natural language processing applications you create using `pg_tiktoken`.

## Resources

- [Open AI tiktoken source code on GitHub](https://github.com/openai/tiktoken)
- [pg_tiktoken source code on GitHub](https://github.com/kelvich/pg_tiktoken)

--- [Document source](https://neon.com/docs/extensions/pg_trgm.md) ---

> Summary: The `pg_trgm` Postgres extension breaks strings into three-character trigrams to compute similarity scores, enabling fuzzy text search, proximity matching, and tolerance for misspellings beyond what LIKE and ILIKE support. Use it when queries must match approximate or misspelled input against large text columns without full-text search infrastructure. Supports GiST and GIN indexes, a configurable similarity threshold, and functions including `similarity`, `word_similarity`, and `strict_word_similarity`.

# The pg_trgm extension

Improve Postgres text searches with the pg_trgm extension

Last updated: 2026-06-05

The `pg_trgm` extension enhances Postgres' ability to perform text searches by using trigram matching. Trigrams are groups of three consecutive characters taken from a string. By breaking down text into trigrams, Postgres can perform more efficient and flexible searches, such as similarity and proximity searches.

It's especially useful for fuzzy string matching and searching large bodies of text.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers how to enable `pg_trgm`, use it for text searches, and optimize queries.

**Note:** The `pg_trgm` extension is open-source and can be installed on any Postgres setup. Detailed information about the extension is available in the [PostgreSQL Documentation](https://www.postgresql.org/docs/current/pgtrgm.html).

**Version availability**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date information.

## Enable the `pg_trgm` extension

Activate `pg_trgm` by running the `CREATE EXTENSION` statement in your Postgres client:

```sql
CREATE EXTENSION IF NOT EXISTS pg_trgm;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Example usage

Let's say you're developing a database of books and you want to find books with similar titles. We first create a test table and insert some sample data, using the query below.

```sql
CREATE TABLE books (
    id SERIAL PRIMARY KEY,
    title TEXT
);

INSERT INTO books (title)
VALUES
    ('The Great Gatsby'),
    ('The Grapes of Wrath'),
    ('Great Expectations'),
    ('War and Peace'),
    ('Pride and Prejudice'),
    ('To Kill a Mockingbird'),
    ('1984');
```

**Basic string matching**

The `pg_trgm` extension can help you do fuzzy matches on strings.

For example, the query below looks for titles that are similar to the misspelled phrase "Grate Expectation". The `%` operator, provided by `pg_trgm`, measures similarity between two strings based on trigrams, and returns results if the similarity is above a certain threshold.

```sql
SELECT *
FROM books
WHERE title % 'Grate Expectation';
```

This query returns the following:

```text
| id | title               |
|----|---------------------|
| 1  | Great Expectations  |
```

The similarity threshold can be adjusted by setting the `pg_trgm.similarity_threshold` parameter (default value is `0.3`).

## Trigrams

### Counting trigrams

The `pg_trgm` module makes these assumptions about how to count trigrams in a text string:

- Only alphanumeric characters are considered.
- The string is lowercased before counting trigrams.
- Each word is assumed to be prefixed with two spaces and suffixed with one space.
- The set of trigrams output is deduplicated.

We can use the `show_trgm` function to see how `pg_trgm` counts trigrams in a string. Here is an example:

```sql
SELECT show_trgm('War and Peace'); -- {" a"," p"," w"," an"," pe"," wa",ace,and,"ar ","ce ",eac,"nd ",pea,war}
```

### Computing similarity

Given the set of trigrams for two strings `A` and `B`, `pg_trgm` computes the similarity score as the size of the intersection of the two sets divided by the size of the union of the two sets.

Here is an example.

```sql
SELECT show_trgm('War'), show_trgm('Bar'), similarity('War', 'Bar');
```

This query returns the following:

```text
| show_trgm              | show_trgm              | similarity |
|------------------------|------------------------|------------|
| {" w"," wa","ar ",war} | {" b"," ba","ar ",bar} | 0.14285715 |
```

There are 7 distinct trigrams across the two input strings and 1 trigram in common. So the similarity score comes out to be 1/7 (0.14285715).

## Advanced text searching

`pg_trgm` offers powerful tools for more complex text search requirements.

**Proximity search**

The `similarity` function provided by `pg_trgm`, returns a number between 0 and 1, representing how similar the two strings are. By filtering on the similarity score, you can search for strings that are within the specified threshold.

```sql
SELECT title
FROM books
WHERE SIMILARITY(title, 'War and') > 0.3;
```

This query returns the following:

```text
| title         |
|---------------|
| War and Peace |
```

**Substring matching**

`pg_trgm` also provides functionality to match the input text value against substrings within the target string. The query below illustrates this:

```sql
SELECT
    word_similarity('apple', 'green apples'),
    strict_word_similarity('apple', 'green apples');
```

This query returns the following:

```text
| word_similarity | strict_word_similarity |
|-----------------|------------------------|
| 0.8333333       | 0.625                  |
```

The `word_similarity` function returns the maximum similarity score between the input string and any substring of the target string. The similarity score is still computed using trigrams. In this example, the first string `apple` matches with the substring `apple` in the target.

In contrast, the `strict_word_similarity` function only considers a subset of substrings from the target, namely only sequences of full words in the target string. That is, the first string `apple` matches the substring `apples` in the target, hence the lower score.

**Distance scores**

There are operators to calculate the `distance` between two strings, i.e., one minus the similarity score.

```sql
SELECT similarity('Hello', 'Halo') AS similarity, 'Hello' <-> 'Halo' AS distance;
```

This query returns the following:

```text
| similarity | distance  |
|------------|-----------|
| 0.22222222 | 0.7777778 |
```

Similarly, there are operators to compute the distance based on the `word_similarity` and `strict_word_similarity` functions.

## Performance considerations

While `pg_trgm` enhances text search capabilities, computing similarity can get expensive when matching against a large set of strings. Here are a couple of tips to improve performance:

- **Indexing**: Using `pg_trgm`, you can create a `GiST` or `GIN` index to speed up similarity search queries. This also helps regular expression-based searches, such as with `LIKE` and `ILIKE` operators.

  ```sql
  CREATE INDEX trgm_idx_gist ON books USING GIST (title gist_trgm_ops);
  -- or
  CREATE INDEX trgm_idx_gin ON books USING GIN (title gin_trgm_ops);
  ```

- **Limiting results**: Use `LIMIT` to restrict the number of rows returned for more efficient querying.

## Conclusion

`pg_trgm` offers a versatile set of tools for text processing and searching in Postgres. We went over the basics of the extension, including how to enable it and how to use it for fuzzy string matching and proximity searches.

## Resources

- [PostgreSQL pg_trgm documentation](https://www.postgresql.org/docs/current/pgtrgm.html)
- [PostgreSQL Text Search](https://www.postgresql.org/docs/current/textsearch.html)

--- [Document source](https://neon.com/docs/extensions/pg_uuidv7.md) ---

> Summary: The `pg_uuidv7` extension generates time-ordered UUIDv7 values in Postgres by embedding a Unix millisecond timestamp in the leading bits, keeping B-tree index insertions sequential and reducing page splits compared to random UUIDv4. Use it when you need globally unique identifiers that also support efficient time-range queries, chronological sorting, or high-insert-rate primary keys without a separate timestamp column. Key functions are `uuid_generate_v7()`, `uuid_v7_to_timestamptz()`, and `uuid_timestamptz_to_v7()`. The last function supports zeroed random bits for boundary UUID generation in range scans.

# The pg_uuidv7 extension

Generate and manage time-ordered version 7 UUIDs in Postgres

Last updated: 2026-08-11

The `pg_uuidv7` extension allows you to generate and work with version 7 Universally Unique Identifiers (UUIDs) in Postgres. UUIDv7 is a newer UUID format designed to be time-ordered and sortable, which offers significant benefits for database performance, especially when used as primary keys or in time-series data.

Unlike traditional random UUIDs (like Version 4), UUIDv7 embeds a Unix timestamp in its leading bits, followed by random bits. This structure ensures that newly generated UUIDs are roughly sequential, which is highly beneficial for database indexing (for example, B-trees) and can improve data locality, leading to faster queries and insertions.

**Note: PostgreSQL 18 includes native UUIDv7 support**

PostgreSQL 18 and later include the built-in `uuidv7()` function for generating UUIDv7 values. If you're using PostgreSQL 18 or later and only need to generate UUIDv7 values, you don't need to install the `pg_uuidv7` extension. See [Native UUIDv7 support in PostgreSQL 18](https://neon.com/docs/extensions/pg_uuidv7#native-uuidv7-support-in-postgresql-18) for differences between the native implementation and this extension.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `pg_uuidv7` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS pg_uuidv7;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Core functions

The `pg_uuidv7` extension provides a concise set of functions for generating and manipulating version 7 UUIDs.

### `uuid_generate_v7()`

This is the primary function for generating new version 7 UUIDs. It creates a UUID incorporating the current Unix timestamp (with millisecond precision) in its most significant bits, followed by randomly generated bits for the remainder.

```sql
SELECT uuid_generate_v7();
-- 0196ce37-0758-736d-a33b-ad3f017359e3 (example output)
```

### `uuid_v7_to_timestamptz(uuid_v7 UUID)`

This function extracts the embedded timestamp from a version 7 UUID and returns it as a `TIMESTAMPTZ` (timestamp with time zone) value.

```sql
SELECT uuid_v7_to_timestamptz('0196ce37-0758-736d-a33b-ad3f017359e3');
-- 2025-05-14 09:53:55.032+00
```

### `uuid_timestamptz_to_v7(ts TIMESTAMPTZ, zero_random_bits BOOLEAN DEFAULT false)`

This function converts a given `TIMESTAMPTZ` value into a version 7 UUID. It takes two arguments:

1. `ts TIMESTAMPTZ`: The timestamp to embed in the UUID.
2. `zero_random_bits BOOLEAN` (optional, defaults to `false`):
   - If `false` (default), the random bits portion of the UUID will be filled with new random data. This is useful for creating a UUID tied to a specific past or future time but still unique.
   - If `true`, the random bits portion of the UUID will be set to all zeros. Use this to create boundary UUIDs for time-range queries (for example, the earliest possible UUID for a given timestamp).

#### Generating a UUID for a specific timestamp with random bits

```sql
SELECT uuid_timestamptz_to_v7('2025-05-14 10:53:55.032+00');
```

Example output (random part will vary):

```text
 uuid_timestamptz_to_v7
--------------------------------------
 0196ce6d-f5d8-7a89-8e7a-06b371fc5d70
(1 row)
```

#### Generating a boundary UUID for a specific timestamp (random bits zeroed)

```sql
SELECT uuid_timestamptz_to_v7('2025-05-14 10:53:55.032+00', true);
```

Example output (random part will be fixed):

```text
 uuid_timestamptz_to_v7
--------------------------------------
  0196ce6d-f5d8-7000-8000-000000000000
(1 row)
```

## Key advantages of UUIDv7

Using version 7 UUIDs in your database schema can provide several advantages over traditional UUIDs, especially in scenarios where time-based ordering is important. Here are some key benefits:

1. **Improved Indexing performance:** Because UUIDv7s are time-ordered, new entries are typically inserted towards the end of an index (for example, a B-tree index on a UUIDv7 primary key). This leads to better data locality, reduced page splits, and less index fragmentation compared to random UUIDs (like v4). This can significantly boost insert performance and make range scans more efficient.
2. **Natural sortability:** UUIDv7s can be sorted chronologically by their value, which is useful for ordering records by creation time without needing a separate timestamp column for this purpose.
3. **Distributed systems friendliness:** Like all UUIDs, v7 can be generated independently across multiple nodes without coordination, ensuring global uniqueness. The time-ordered property adds benefits for distributed databases that might later need to merge or sort data by generation time.

## Example usage

Let's explore some common use cases for `pg_uuidv7`.

### Using UUIDv7 as a primary key

UUIDv7 is an excellent candidate for primary keys, especially for tables where data is often queried or inserted based on time.

```sql
CREATE TABLE events (
    event_id UUID PRIMARY KEY DEFAULT uuid_generate_v7(),
    event_type TEXT NOT NULL,
    event_data JSONB
);

INSERT INTO events (event_type, event_data) VALUES
    ('user_login', '{"user_id": 101, "ip": "192.168.1.10"}'),
    ('page_view', '{"user_id": 101, "url": "/products/awesome-widget"}'),
    ('purchase', '{"user_id": 205, "item_id": "XYZ123", "amount": 99.99}')
RETURNING event_id, event_type;
```

Example output:

```text
               event_id                              | event_type
--------------------------------------+------------
 0196e801-a0d6-7af7-a308-13057189ef3f | user_login
 0196e801-a0ec-7cf7-a4f2-2a4a73c58688 | page_view
 0196e801-a0ed-7fdb-9858-dcd601cadc26 | purchase
(3 rows)
```

Notice how the `event_id` values are largely sequential, reflecting their insertion order.

### Time-range queries

The ability to convert timestamps to UUIDv7s (especially with zeroed random bits) is very useful for performing efficient time-range queries directly on the UUIDv7 primary key.

Suppose we want to find all events that occurred between May 14, 2025, and May 24, 2025. We can use the `uuid_timestamptz_to_v7()` function to create boundary UUIDs for our query:

```sql
SELECT *
FROM events
WHERE
    event_id >= uuid_timestamptz_to_v7('2025-05-14', true) -- Start of May 14th
  AND
    event_id < uuid_timestamptz_to_v7('2025-05-24', true); -- Start of May 24th
```

This query can efficiently use an index on `event_id` to find matching records.

## Native UUIDv7 support in PostgreSQL 18

PostgreSQL 18 introduced native support for UUIDv7. The built-in `uuidv7()` function generates time-ordered UUIDv7 values without requiring an extension.

For example:

```sql
SELECT uuidv7();
-- 019ff097-80cb-7d78-8694-93b9e1a973d2 (example output; the random bits vary)
```

PostgreSQL 18 also provides `uuid_extract_timestamp()` for extracting the timestamp from a UUIDv7 value.

The native PostgreSQL implementation doesn't provide everything `pg_uuidv7` does. In particular, `pg_uuidv7` provides `uuid_timestamptz_to_v7()`, which lets you construct a UUIDv7 value from a timestamp. It can also zero the UUID's random bits, which is useful for constructing UUID boundaries for time-based range queries.

For example:

```sql
SELECT uuid_timestamptz_to_v7(
  '2026-01-01 00:00:00+00',
  true
);
```

With the random bits zeroed, this returns the same boundary UUID every time:

```text
        uuid_timestamptz_to_v7
--------------------------------------
 019b76da-a800-7000-8000-000000000000
(1 row)
```

If you only need to generate UUIDv7 values on PostgreSQL 18 or later, use the built-in `uuidv7()` function. Use `pg_uuidv7` if your application depends on its additional functions or if you need the same UUIDv7 API across PostgreSQL versions that don't provide native UUIDv7 generation.

## Comparison with UUID4

UUIDv4 is purely random. While excellent for uniqueness, its randomness leads to poor index locality and fragmentation when used as a primary key for time-sensitive data. UUIDv7 directly addresses this by being time-ordered.

## Conclusion

The `pg_uuidv7` extension gives you a clean way to work with version 7 UUIDs in Postgres. By embedding a timestamp, UUIDv7s offer the global uniqueness of traditional UUIDs while also being chronologically sortable. This makes them an excellent choice for primary keys and indexed columns in applications where time-ordering and query performance on time-based data are critical.

## Resources

- [fboulnois/pg_uuidv7 GitHub repository](https://github.com/fboulnois/pg_uuidv7)
- [UUID version 7](https://datatracker.ietf.org/doc/html/draft-ietf-uuidrev-rfc4122bis#name-uuid-version-7).
- [uuid-ossp](https://neon.com/docs/extensions/uuid-ossp)

--- [Document source](https://neon.com/docs/extensions/pg-extensions.md) ---

> Summary: Neon's supported Postgres extensions reference lists every available extension with version numbers by Postgres version, so you can confirm availability before running CREATE EXTENSION. Use this page to check which extensions are supported, install or update them with ALTER EXTENSION, request new ones, configure shared_preload_libraries via the API, or understand the experimental extension opt-in policy.

# Postgres extensions

Last updated: 2026-11-04

Neon supports the Postgres extensions shown below. Extension versions may differ by Postgres version. A dash (`-`) indicates an extension is not yet supported for that version.

[Explore by category](https://neon.com/docs/extensions/extension-explorer) | [Install an extension](https://neon.com/docs/extensions/pg-extensions#install-an-extension) | [Update an extension](https://neon.com/docs/extensions/pg-extensions#update-an-extension-version) | [Request an extension](https://neon.com/docs/extensions/pg-extensions#request-an-extension)

| Extension                                                                                                      |   PG14 |   PG15 |   PG16 |   PG17 |   PG18 | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :------------------------------------------------------------------------------------------------------------- | -----: | -----: | -----: | -----: | -----: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [address\_standardizer](https://postgis.net/docs/Extras.html#Address_Standardizer)                             | 3.3.10 | 3.3.10 | 3.3.10 |  3.5.7 |  3.6.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [address\_standardizer\_data\_us](https://postgis.net/docs/Extras.html#Address_Standardizer_Tables)            | 3.3.10 | 3.3.10 | 3.3.10 |  3.5.7 |  3.6.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [anon](https://neon.com/docs/extensions/postgresql-anonymizer)                                                 |  2.5.1 |  2.5.1 |  2.5.1 |  2.5.1 |  2.5.1 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [autoinc (spi)](https://www.postgresql.org/docs/current/contrib-spi.html)                                      |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [bloom](https://www.postgresql.org/docs/16/bloom.html)                                                         |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [btree\_gin](https://neon.com/docs/extensions/btree_gin)                                                       |    1.3 |    1.3 |    1.3 |    1.3 |    1.3 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [btree\_gist](https://neon.com/docs/extensions/btree_gist)                                                     |    1.6 |    1.7 |    1.7 |    1.7 |    1.8 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [citext](https://neon.com/docs/extensions/citext)                                                              |    1.6 |    1.6 |    1.6 |    1.6 |    1.8 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [cube](https://neon.com/docs/extensions/cube)                                                                  |    1.5 |    1.5 |    1.5 |    1.5 |    1.5 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [dblink](https://neon.com/docs/extensions/dblink)                                                              |    1.2 |    1.2 |    1.2 |    1.2 |    1.2 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [dict\_int](https://neon.com/docs/extensions/dict_int)                                                         |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [earthdistance](https://neon.com/docs/extensions/earthdistance)                                                |    1.1 |    1.1 |    1.2 |    1.2 |    1.2 | To use `earthdistance`, you first need to install its dependency, the [`cube` extension](https://neon.com/docs/extensions/cube). Run: `CREATE EXTENSION IF NOT EXISTS cube; CREATE EXTENSION IF NOT EXISTS earthdistance`;                                                                                                                                                                                                                                     |
| [fuzzystrmatch](https://neon.com/docs/extensions/fuzzystrmatch)                                                |    1.1 |    1.1 |    1.2 |    1.2 |    1.2 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [h3](https://neon.com/docs/extensions/postgis-related-extensions#h3-and-h3-postgis)                            |  4.1.3 |  4.1.3 |  4.1.3 |  4.1.3 |  4.2.3 | Some components have been split out into the `h3_postgis` extension. Install both the `h3` and `h3_postgis` extensions.                                                                                                                                                                                                                                                                                                                                        |
| [h3\_postgis](https://neon.com/docs/extensions/postgis-related-extensions#h3-and-h3-postgis)                   |  4.1.3 |  4.1.3 |  4.1.3 |  4.1.3 |  4.2.3 | Install with `CREATE EXTENSION h3_postgis CASCADE;` (requires `postgis` and `postgis_raster`)                                                                                                                                                                                                                                                                                                                                                                  |
| [hll](https://github.com/citusdata/postgresql-hll)                                                             |   2.21 |   2.21 |   2.21 |   2.21 |   2.21 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [hstore](https://neon.com/docs/extensions/hstore)                                                              |    1.8 |    1.8 |    1.8 |    1.8 |    1.8 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [hypopg](https://hypopg.readthedocs.io/en/rel1_stable/)                                                        |  1.4.3 |  1.4.3 |  1.4.3 |  1.4.3 |  1.4.3 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [insert\_username (spi)](https://www.postgresql.org/docs/current/contrib-spi.html)                             |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [intagg](https://www.postgresql.org/docs/16/intagg.html)                                                       |    1.1 |    1.1 |    1.1 |    1.1 |    1.1 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [intarray](https://neon.com/docs/extensions/intarray)                                                          |    1.5 |    1.5 |    1.5 |    1.5 |    1.5 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [ip4r](https://github.com/RhodiumToad/ip4r)                                                                    |    2.4 |    2.4 |    2.4 |    2.4 |    2.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [isn](https://www.postgresql.org/docs/16/isn.html)                                                             |    1.2 |    1.2 |    1.2 |    1.2 |    1.3 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [lakebase\_text](https://neon.com/docs/extensions/lakebase-text)                                               |      - |      - |  0.1.3 |  0.1.3 |  0.1.3 | See [Lakebase Search](https://neon.com/docs/ai/lakebase-search).                                                                                                                                                                                                                                                                                                                                                                                               |
| [lakebase\_tokenizer](https://neon.com/docs/extensions/lakebase-tokenizer)                                     |      - |      - |  0.2.1 |  0.2.1 |  0.2.1 | See [Lakebase Search](https://neon.com/docs/ai/lakebase-search).                                                                                                                                                                                                                                                                                                                                                                                               |
| [lakebase\_vector](https://neon.com/docs/extensions/lakebase-vector)                                           |      - |      - |  1.1.2 |  1.1.2 |  1.1.2 | See [Lakebase Search](https://neon.com/docs/ai/lakebase-search).                                                                                                                                                                                                                                                                                                                                                                                               |
| [lo](https://www.postgresql.org/docs/16/lo.html)                                                               |    1.1 |    1.1 |    1.1 |    1.1 |    1.2 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [ltree](https://neon.com/docs/extensions/ltree)                                                                |    1.2 |    1.2 |    1.2 |    1.3 |    1.3 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [moddatetime (spi)](https://www.postgresql.org/docs/current/contrib-spi.html)                                  |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [neon](https://neon.com/docs/extensions/neon)                                                                  |   1.25 |   1.25 |   1.25 |   1.25 |   1.25 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [neon\_utils](https://neon.com/docs/extensions/neon-utils)                                                     |    1.1 |    1.1 |    1.1 |    1.1 |    1.1 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [online\_advisor](https://neon.com/docs/extensions/online_advisor)                                             |      - |      - |      - |    1.0 |      - |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_cron](https://neon.com/docs/extensions/pg_cron)                                                           |    1.6 |    1.6 |    1.6 |    1.6 |    1.6 | Prefer [scheduled Function Triggers](https://neon.com/docs/compute/functions/triggers/schedule); `pg_cron` runs only while the compute is active, so it needs [scale to zero](https://neon.com/docs/introduction/scale-to-zero) disabled.                                                                                                                                                                                                                      |
| [pg\_graphql](https://neon.com/docs/extensions/pg_graphql)                                                     | 1.5.11 | 1.5.11 | 1.5.11 | 1.5.11 | 1.5.12 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_hashids](https://github.com/iCyberon/pg_hashids)                                                          |  1.2.1 |  1.2.1 |  1.2.1 |  1.2.1 |  1.2.1 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_hint\_plan](https://github.com/ossc-db/pg_hint_plan)                                                      |  1.4.1 |  1.5.0 |  1.6.0 |  1.7.0 |  1.8.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_ivm](https://github.com/sraoss/pg_ivm)                                                                    |    1.9 |    1.9 |    1.9 |    1.9 |   1.12 | **Not available for new installs.** Existing databases that already installed `pg_ivm` are unaffected. On PG14–17, use `SELECT create_immv(...)` (function in `pg_catalog`). On PG18, use `SELECT pgivm.create_immv(...)` or add `pgivm` to your `search_path`. For new projects, use standard [materialized views](https://neon.com/postgresql/views/materialized-views).                                                                                     |
| [pg\_jsonschema](https://github.com/supabase/pg_jsonschema)                                                    |  0.3.3 |  0.3.3 |  0.3.3 |  0.3.3 |  0.3.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_mooncake](https://neon.com/docs/extensions/pg_mooncake)                                                   |  0.1.3 |  0.1.3 |  0.1.3 |  0.1.3 |      - | This extension is **experimental**. Using a separate, dedicated Neon project is recommended. Run `SET neon.allow_unstable_extensions='true';` before installing. See the [YouTube demo](https://youtu.be/QDNsxw_3ris?feature=shared\&t=2048) and the [pg\_mooncake documentation](https://pgmooncake.com/docs).                                                                                                                                                |
| [pg\_partman](https://github.com/pgpartman/pg_partman)                                                         |  5.1.0 |  5.1.0 |  5.1.0 |  5.1.0 |  5.1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_prewarm](https://neon.com/docs/extensions/pg_prewarm)                                                     |    1.2 |    1.2 |    1.2 |    1.2 |    1.2 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_repack](https://neon.com/docs/extensions/pg_repack)                                                       |  1.5.2 |  1.5.2 |  1.5.2 |  1.5.2 |  1.5.2 | Available only on paid Neon plans. To install `pg_repack`, it must first be enabled by Neon Support. [Open a support ticket](https://console.neon.tech/app/projects?modal=support) with your endpoint ID and database name to request it. After it's enabled, you'll need to restart your compute before running `CREATE EXTENSION pg_repack;` To use `pg_repack`, you will need to [install the pg\_repack CLI](https://reorg.github.io/pg_repack/#download). |
| [pg\_roaringbitmap](https://github.com/ChenHuajun/pg_roaringbitmap)                                            |    1.2 |    1.2 |    1.2 |    1.2 |    1.2 | Install with `CREATE EXTENSION roaringbitmap;`                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [pg\_session\_jwt](https://neon.com/docs/extensions/pg_session_jwt)                                            |  0.5.0 |  0.5.0 |  0.5.0 |  0.5.0 |  0.5.0 | This extension provides JWT session management functionality used by the [Data API](https://neon.com/docs/data-api/overview).                                                                                                                                                                                                                                                                                                                                  |
| [pg\_stat\_statements](https://neon.com/docs/extensions/pg_stat_statements)                                    |    1.9 |   1.10 |   1.10 |   1.11 |   1.12 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_tiktoken](https://neon.com/docs/extensions/pg_tiktoken)                                                   |  0.0.1 |  0.0.1 |  0.0.1 |  0.0.1 |  0.0.1 | The [neon\_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role has `EXECUTE` privilege on the `pg_stat_statements_reset()` function.                                                                                                                                                                                                                                                                                                    |
| [pg\_trgm](https://neon.com/docs/extensions/pg_trgm)                                                           |    1.6 |    1.6 |    1.6 |    1.6 |    1.6 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pg\_uuidv7](https://neon.com/docs/extensions/pg_uuidv7)                                                       |    1.6 |    1.6 |    1.6 |    1.6 |    1.6 | PostgreSQL 18 and later include the built-in `uuidv7()` function. If you only need to generate UUIDv7 values on Postgres 18+, you don't need this extension. See [Native UUIDv7 support in PostgreSQL 18](https://neon.com/docs/extensions/pg_uuidv7#native-uuidv7-support-in-postgresql-18).                                                                                                                                                                  |
| [pgcrypto](https://neon.com/docs/extensions/pgcrypto)                                                          |    1.3 |    1.3 |    1.3 |    1.3 |    1.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pgjwt](https://github.com/michelp/pgjwt)                                                                      |  0.2.0 |  0.2.0 |  0.2.0 |  0.2.0 |  0.2.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pgrag](https://neon.com/docs/extensions/pgrag)                                                                |  0.0.0 |  0.0.0 |  0.0.0 |  0.0.0 |  0.0.0 | **Deprecated.** For search and RAG, see [Lakebase Search](https://neon.com/docs/ai/lakebase-search).                                                                                                                                                                                                                                                                                                                                                           |
| [pgrouting](https://neon.com/docs/extensions/postgis-related-extensions#pgrouting)                             |  3.4.2 |  3.4.2 |  3.4.2 |  3.6.2 |  3.8.0 | The PostGIS extension must be installed first.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| [pgrowlocks](https://neon.com/docs/extensions/pgrowlocks)                                                      |    1.2 |    1.2 |    1.2 |    1.2 |    1.2 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pgstattuple](https://neon.com/docs/extensions/pgstattuple)                                                    |    1.5 |    1.5 |    1.5 |    1.5 |    1.5 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pgtap](https://pgtap.org/documentation.html)                                                                  |  1.3.3 |  1.3.3 |  1.3.3 |  1.3.3 |  1.3.3 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [pgvector](https://neon.com/docs/extensions/pgvector)                                                          |  0.8.0 |  0.8.0 |  0.8.0 |  0.8.0 |  0.8.6 | Install with `CREATE EXTENSION vector;`                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [pg\_search](https://neon.com/docs/extensions/pg_search)                                                       |      - |      - |      - |      - |      - | **Unavailable.** For full text search, see [Lakebase Search](https://neon.com/docs/ai/lakebase-search).                                                                                                                                                                                                                                                                                                                                                        |
| [pgx\_ulid](https://github.com/pksunkara/pgx_ulid)                                                             |  0.1.5 |  0.1.5 |  0.1.5 |  0.2.0 |  0.2.2 | Install with `CREATE EXTENSION ulid;` on Postgres 14, 15, 16. Install with `CREATE EXTENSION pgx_ulid;` on Postgres 17 and 18.                                                                                                                                                                                                                                                                                                                                 |
| [plcoffee](https://coffeescript.org/)                                                                          | 3.1.10 | 3.1.10 | 3.1.10 |      - |      - | **Deprecated.** Ships with plv8. See [The plv8 extension](https://neon.com/docs/extensions/plv8).                                                                                                                                                                                                                                                                                                                                                              |
| [plls](https://livescript.net/)                                                                                | 3.1.10 | 3.1.10 | 3.1.10 |      - |      - | **Deprecated.** Ships with plv8. See [The plv8 extension](https://neon.com/docs/extensions/plv8).                                                                                                                                                                                                                                                                                                                                                              |
| [plpgsql](https://www.postgresql.org/docs/16/plpgsql.html)                                                     |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 | Pre-installed with Postgres.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| [plpgsql\_check](https://pgxn.org/dist/plpgsql_check/)                                                         |  2.8.2 |  2.8.2 |  2.8.2 |  2.8.2 |  2.8.2 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [plv8](https://neon.com/docs/extensions/plv8)                                                                  | 3.1.10 | 3.1.10 | 3.1.10 |  3.2.3 |      - | **Deprecated.** New installs are blocked for security reasons. See [The plv8 extension](https://neon.com/docs/extensions/plv8).                                                                                                                                                                                                                                                                                                                                |
| [postgis](https://neon.com/docs/extensions/postgis)                                                            | 3.3.10 | 3.3.10 | 3.3.10 |  3.5.7 |  3.6.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [postgis\_raster](https://postgis.net/docs/RT_reference.html)                                                  | 3.3.10 | 3.3.10 | 3.3.10 |  3.5.7 |  3.6.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [postgis\_sfcgal](https://neon.com/docs/extensions/postgis-related-extensions#postgis-sfcgal)                  | 3.3.10 | 3.3.10 | 3.3.10 |  3.5.7 |  3.6.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [postgis\_tiger\_geocoder](https://neon.com/docs/extensions/postgis-related-extensions#postgis-tiger-geocoder) | 3.3.10 | 3.3.10 | 3.3.10 |  3.5.7 |  3.6.4 | Cannot be installed using the Neon SQL Editor. Use your `psql` user credentials to install this extension.                                                                                                                                                                                                                                                                                                                                                     |
| [postgis\_topology](https://www.postgis.net/docs/Topology.html)                                                | 3.3.10 | 3.3.10 | 3.3.10 |  3.5.7 |  3.6.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [postgres\_fdw](https://neon.com/docs/extensions/postgres_fdw)                                                 |    1.1 |    1.1 |    1.1 |    1.1 |    1.2 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [prefix](https://github.com/dimitri/prefix)                                                                    |  1.2.0 |  1.2.0 |  1.2.0 |  1.2.0 |  1.2.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [rdkit](https://github.com/rdkit/rdkit)                                                                        |  4.3.0 |  4.3.0 |  4.3.0 |  4.6.0 |  4.8.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [refint (spi)](https://www.postgresql.org/docs/current/contrib-spi.html)                                       |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [rum](https://github.com/postgrespro/rum)                                                                      |    1.3 |    1.3 |    1.3 |    1.3 |      - |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [seg](https://www.postgresql.org/docs/16/seg.html)                                                             |    1.4 |    1.4 |    1.4 |    1.4 |    1.4 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [semver](https://pgxn.org/dist/semver)                                                                         | 0.32.1 | 0.32.1 | 0.32.1 | 0.40.0 | 0.40.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [tablefunc](https://neon.com/docs/extensions/tablefunc)                                                        |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [tcn](https://www.postgresql.org/docs/16/tcn.html)                                                             |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [timescaledb](https://neon.com/docs/extensions/timescaledb)                                                    | 2.10.1 | 2.10.1 | 2.13.0 | 2.17.1 | 2.24.0 | Only Apache-2 licensed features are supported. Compression is not supported.                                                                                                                                                                                                                                                                                                                                                                                   |
| [tsm\_system\_rows](https://www.postgresql.org/docs/16/tsm-system-rows.html)                                   |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [tsm\_system\_time](https://www.postgresql.org/docs/16/tsm-system-time.html)                                   |    1.0 |    1.0 |    1.0 |    1.0 |    1.0 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [unaccent](https://neon.com/docs/extensions/unaccent)                                                          |    1.1 |    1.1 |    1.1 |    1.1 |    1.1 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [unit](https://github.com/df7cb/postgresql-unit)                                                               |      7 |      7 |      7 |      7 |      - |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| [uuid-ossp](https://neon.com/docs/extensions/uuid-ossp)                                                        |    1.1 |    1.1 |    1.1 |    1.1 |    1.1 | Double-quote the extension name when installing: `CREATE EXTENSION "uuid-ossp"`                                                                                                                                                                                                                                                                                                                                                                                |
| [wal2json](https://neon.com/docs/extensions/wal2json)                                                          |    2.6 |    2.6 |    2.6 |    2.6 |    2.6 | `CREATE EXTENSION` not required. This decoder plugin is available by default but requires enabling [logical replication](https://neon.com/docs/guides/logical-replication-guide) in Neon.                                                                                                                                                                                                                                                                      |
| [xml2](https://neon.com/docs/extensions/xml2)                                                                  |    1.1 |    1.1 |    1.1 |    1.1 |    1.2 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

## Install an extension

Unless otherwise noted, supported extensions can be installed using [CREATE EXTENSION](https://www.postgresql.org/docs/16/sql-createextension.html) syntax.

```sql
CREATE EXTENSION <extension_name>;
```

You can install extensions from the Neon SQL Editor or from a client such as `psql` that permits running SQL queries. For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Update an extension version

Neon updates supported extensions as new versions become available. Version updates are communicated in the [Changelog](https://neon.com/docs/changelog). To check the current version of extensions you have installed, query the `pg_extension` table:

```bash
SELECT * FROM pg_extension;
```

You can update an extension to the latest version using `ALTER EXTENSION <extension_name> UPDATE TO <new_version>` syntax. For example:

```sql
ALTER EXTENSION vector UPDATE TO '0.7.0';
```

**Important:** When Neon releases a new extension or new extension version, a compute restart is required to make the new extension or extension version available for installation or update. A compute restart may occur on its own due to Neon's default [scale to zero](https://neon.com/docs/introduction/scale-to-zero) behavior or when Neon applies a regular compute [update](https://neon.com/docs/manage/updates) for Postgres upgrades, security patches, and similar changes. However, if your compute never restarts because you disabled scale to zero or because your compute is constantly active, you may need to force a restart. To force a restart, you can issue [Restart endpoint](https://neon.com/docs/reference/api/endpoints/restart-project-endpoint) API call. Please be aware that restarting a compute temporarily interrupts any connections currently using the compute.

Extensions installations and updates are automatically applied to any read replica computes on the same branch as your primary compute the next time the read replica compute restarts.

## Request an extension

> **Request a new extension**
>
> Looking for a specific Postgres extension in Neon? Submit a request through [Neon support](https://neon.com/docs/introduction/support) or let us know in the [Neon Discord](https://neon.com/discord).

_We appreciate all extension requests. While we can't guarantee support, we regularly review requests and prioritize them based on factors like user demand, popularity in the Postgres ecosystem, and Neon's product direction. Some extensions are simple to add, while others require significant integration work._

## Extension support

Neon supports a large number of Postgres extensions. When we say an extension is "supported," we mean that it's available for you to enable and use in your project.

We don't actively maintain third-party extension code. If you run into an issue or discover a bug with an extension, we recommend reporting it to the extension's upstream maintainers. If a fix is released, we're happy to update to the latest version of the extension.

For the extension versions that Neon supports, refer to the [Supported extensions table](https://neon.com/docs/extensions/pg-extensions) above. You can request support for a new version of an extension by opening a [support ticket](https://console.neon.tech/app/projects?modal=support) or by reaching out to us on [Discord](https://neon.com/discord).

## Experimental extensions

Neon occasionally adds support for extensions that are in early stages of development or undergoing validation. These extensions require an explicit opt-in and are not recommended for production use.

To run these extensions, you'll be required to configure the following session variable before installing the extension:

```sql
SET neon.allow_unstable_extensions = 'true';
```

**Note:** "Unstable" doesn't mean the extension is buggy. It means that we have not yet met service level expectations for the extension, often related to testing and Neon integration requirements.

**Things to know about experimental extensions:**

- **Use with caution:** We recommend trying experimental extensions in a separate project, not in the Neon project you use for production.
- **Limited support:** Experimental extensions aren't covered by Neon support. If an extension causes your database to fail or prevents it from starting, we'll help you disable it if possible, but we can't guarantee more than that.
- **No guarantees:** An experimental extension might never become fully supported. It could require significant work from Neon or the extension's maintainers before it's ready for general use.
- **Subject to change or removal:** Experimental extensions may be updated at any time, including breaking changes. They can also be removed, especially if they pose security or operational risks.

If you're experimenting with an extension and run into trouble, we recommend checking with the extension's maintainers or community for support.

## Extensions with preloaded libraries

A preloaded library in Postgres is a shared library that must be loaded into memory when the Postgres server starts. These libraries are specified in your Postgres server's startup configuration using the `shared_preload_libraries` parameter and cannot be added dynamically after the server has started.

Some Postgres extensions require preloaded libraries but most do not. Lakebase Postgres servers preload libraries for certain extensions by default. You can view **currently enabled** libraries by running the following command.

```sql
SHOW shared_preload_libraries;
neon,pg_stat_statements,timescaledb,pg_cron,pg_partman_bgw,rag_bge_small_en_v15,rag_jina_reranker_v1_tiny_en
```

### Viewing available libraries

You can view **available** libraries by running [List preloaded libraries](https://neon.com/docs/reference/api/projects/get-available-preload-libraries) API:

```bash
curl --request GET \
     --url https://console.neon.tech/api/v2/projects/your_project_id/available_preload_libraries \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

The response body lists available libraries and whether the libraries are enabled by default. Response body attributes include:

- `library_name`: library name, typically named for the associated extension
- `description`: a description of the extension
- `is_default`: whether the library is enabled by default
- `is_experimental`: whether the extensions is [experimental](https://neon.com/docs/extensions/pg-extensions#experimental-extensions)
- `version`: the extension version

<details>

<summary>Response body</summary>

For attribute definitions, find the [List preloaded libraries](https://neon.com/docs/reference/api/projects/get-available-preload-libraries) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "libraries": [
    {
      "library_name": "timescaledb",
      "description": "Enables scalable inserts and complex queries for time-series data.",
      "is_default": true,
      "is_experimental": false,
      "version": "2.17.1"
    },
    {
      "library_name": "pg_cron",
      "description": "pg_cron is a cron-like job scheduler for PostgreSQL.",
      "is_default": true,
      "is_experimental": false,
      "version": "1.6.4"
    },
    {
      "library_name": "pg_partman_bgw",
      "description": "pg_partman_bgw is a background worker for pg_partman.",
      "is_default": true,
      "is_experimental": false,
      "version": "5.1.0"
    },
    {
      "library_name": "rag_bge_small_en_v15,rag_jina_reranker_v1_tiny_en",
      "description": "Deprecated. Shared libraries for the pgrag extension. Not for new projects; see the pgrag extension docs.",
      "is_default": true,
      "is_experimental": true,
      "version": "0.0.0"
    },
    {
      "library_name": "pgx_ulid",
      "description": "pgx_ulid is a PostgreSQL extension for ULID generation.",
      "is_default": false,
      "is_experimental": false,
      "version": "0.2.0"
    },
    {
      "library_name": "pg_mooncake",
      "description": "Columnstore Table in Postgres",
      "is_default": false,
      "is_experimental": false,
      "version": "0.1.1"
    },
    {
      "library_name": "pg_search",
      "description": "Deprecated. Full text search using BM25. Not for new projects; see Neon pg_search extension docs.",
      "is_default": false,
      "is_experimental": false,
      "version": "0.15.12"
    },
    {
      "library_name": "anon",
      "description": "Anonymization & Data Masking for PostgreSQL",
      "is_default": false,
      "is_experimental": false,
      "version": "2.5.1"
    },
    {
      "library_name": "lakebase_vector",
      "description": "High-performance vector index, fully compatible with pgvector.",
      "is_default": true,
      "is_experimental": false,
      "version": "1.0.0-dev"
    },
    {
      "library_name": "lakebase_text",
      "description": "High-performance BM25 full-text search.",
      "is_default": true,
      "is_experimental": false,
      "version": "0.1.0-dev"
    }
  ]
}
```

</details>

Important notes about libraries for Postgres extensions:

- Available libraries and those enabled by default may differ by Postgres version
- Neon does not enable libraries for all extensions that have them

### Enabling preloaded libraries

You can enable available libraries using the `preloaded_libraries` object in a [Create project](https://neon.com/docs/reference/api/projects/create-project) or [Update project](https://neon.com/docs/reference/api/projects/update-project) API call. For example, this `Update project` call enables the specified libraries for the Neon project. When running this call, you have to provide a [Neon project ID](https://neon.com/docs/reference/glossary#project-id) and a [Neon API key](https://neon.com/docs/manage/api-keys).

```bash
curl --request PATCH \
    --url https://console.neon.tech/api/v2/projects/<your_project_id> \
    --header 'accept: application/json' \
    --header 'authorization: Bearer $NEON_API_KEY' \
    --header 'content-type: application/json' \
    --data '
{
  "project": {
    "settings": {
      "preload_libraries": {
        "enabled_libraries": [
          "neon","pg_stat_statements","timescaledb","pg_cron","pg_partman_bgw","lakebase_vector","lakebase_text"
        ]
      }
    }
  }
}
'
```

When running a `Create project` or `Update project` API call to enable libraries:

- Specify library names as an array of quoted strings.
- Specify all libraries that should be enabled. If a library is not included in the API call, it will not be enabled.
- Setting `use_defaults` to `true` overrides `enabled_libraries` and enables only the default libraries.
- Include `lakebase_vector` and `lakebase_text` if you use [Lakebase Search](https://neon.com/docs/ai/lakebase-search). They're enabled by default, but a custom list replaces the defaults, so leaving them out disables them. Queries that use their indexes then fail with an error like `lakebase_vector must be loaded via shared_preload_libraries`.
- The `neon` and `pg_stat_statements` libraries will remain enabled whether you include them in your API call or not; they're used by a Neon system-managed database.
- If you do not use one of the libraries enabled by default, you can exclude it from your API call.
- The `pgrag` libraries (`"rag_bge_small_en_v15,rag_jina_reranker_v1_tiny_en"`) are **deprecated**; leave them out of your API call. For search and RAG, see [Lakebase Search](https://neon.com/docs/ai/lakebase-search).
- The `pg_search` library is **deprecated**; do not add it for new projects. Existing projects that still preload it should plan migration; see [The pg_search extension](https://neon.com/docs/extensions/pg_search).
- The **`plv8`** extension and its companion **`plcoffee`** and **`plls`** extensions are **deprecated**; **`CREATE EXTENSION`** is rejected for each. See [The plv8 extension](https://neon.com/docs/extensions/plv8).

## Extension notes

- Neon supports the `uuid-ossp` extension for generating UUIDs instead of the `uuid` extension.
- The `sslinfo` extension is not supported. Neon handles connections via a proxy that checks SSL.
- The `file_fdw` extension is not supported. Files would not remain accessible when Neon scales to zero.

--- [Document source](https://neon.com/docs/extensions/pgcrypto.md) ---

> Summary: The pgcrypto extension adds SQL-callable functions for encryption, decryption, password hashing, and HMAC generation directly inside Postgres, removing the need for an external cryptographic library. Use it to store passwords with salted Blowfish hashing via crypt() and gen_salt(), encrypt sensitive columns with OpenPGP symmetric or public-key functions (pgp_sym_encrypt, pgp_pub_encrypt), or produce SHA-256 digests and secure random bytes in standard SQL queries. The page covers enabling pgcrypto on Neon, all major function groups, and security best practices for key management and algorithm selection.

# The pgcrypto extension

Secure your data with cryptographic functions in Postgres

Last updated: 2026-06-05

The `pgcrypto` extension offers a range of cryptographic functions within Postgres. These functions enable encryption, decryption, and hashing operations through standard SQL queries. This can reduce reliance on external cryptographic tools for data security tasks in a Postgres environment.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide covers how to enable `pgcrypto` on Neon, use its core cryptographic functions, and follow best practices for data security.

## Enable the `pgcrypto` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS pgcrypto;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Cryptographic functions

The `pgcrypto` extension provides a wide range of cryptographic functions that can be used directly within SQL queries. These functions can be broadly categorized into the following groups:

### General hashing functions

`pgcrypto` provides functions for generating one-way hashes, crucial for verifying data integrity and securely comparing data without revealing the original content.

- **`digest(data, type)`**:

  The `digest` function computes a binary hash of the input `data` using the algorithm specified by `type`. This function supports a wide range of algorithms, including [`md5`](https://en.wikipedia.org/wiki/MD5), [`sha1`](https://en.wikipedia.org/wiki/SHA1), and the [SHA-2](https://en.wikipedia.org/wiki/SHA2) family (`sha224`, `sha256`, `sha384`, `sha512`), as well as any other digest algorithm supported by the underlying OpenSSL library.

  ```sql
  SELECT digest('Sensitive Information', 'sha256');
  -- \x7daa83aa2e4618c8de40eb6642dbde3bceead971c322c66ed47676897a1b31c1 (binary output)
  ```

- **`hmac(data, key, type)`**:

  The `hmac` function calculates a keyed hash, also known as a Hash-based Message Authentication Code. It incorporates a secret `key` into the hashing process, ensuring that only parties with knowledge of the key can verify the hash. This provides both data integrity and authenticity.

  ```sql
  SELECT hmac('Data to Authenticate', 'shared_secret_key', 'sha256');
  -- \x261415730795bccaedb60061af12bf8fdb0833b4bad7735214dc78789e233257 (binary output)
  ```

### Password hashing functions

`pgcrypto` includes specialized functions designed for securely hashing passwords, essential for protecting user credentials.

- **`crypt(password text, salt text)`**:

  The `crypt` function implements a crypt(3)-style hashing algorithm, specifically tailored for password security. It takes the `password` to be hashed and a `salt` value as input.

  ```sql
  SELECT crypt('user_password', gen_salt('md5'));
  -- $1$bPYjhtip$NT.UC/6xLeoj8leDs7Neh0 (example hashed password output)
  ```

- **`gen_salt(type text [, iter_count integer ])`**:

  The `gen_salt` function generates new, random salt values for use with the `crypt()` function. The `type` parameter specifies the hashing algorithm (for example, `bf` for Blowfish, `md5`, `xdes`, `des`). For algorithms like [Blowfish](https://en.wikipedia.org/wiki/Blowfish_\(cipher\)) and [Extended DES](https://en.wikipedia.org/wiki/Data_Encryption_Standard) (`xdes`), you can specify `iter_count` to control the number of iterations, increasing the computational cost and security.

  ```sql
  SELECT gen_salt('bf'); -- Generate a Blowfish salt
  -- $2a$06$KlIoNEoix2oKbLwMimhQpu (example output)
  SELECT gen_salt('bf', 10); -- Generate Blowfish salt with 2^10 iterations
  -- $2a$10$nnHUvyZckh1VBh5zWNEFKO (example output)
  ```

### PGP encryption functions

For general-purpose encryption needs, `pgcrypto` implements the encryption part of the OpenPGP standard, providing functions for both symmetric-key and public-key encryption.

- **`pgp_sym_encrypt(data, psw [, options ])`**:

  The `pgp_sym_encrypt` function encrypts `data` using symmetric-key encryption with a provided password `psw`. Symmetric encryption uses the same key for both encryption and decryption.

  ```sql
  SELECT pgp_sym_encrypt('Confidential Data', 'encryption_password');
  -- \xc30d040703029c3eba2b3565a3937bd2420120ae6792f663bd35977d21a5a8e13de9a8a8e5a9212ef06f8b056dcc31e0b48096915ddac66f14ab403ea671a8b4c740a198d32bcc5b804a30ef7e9aeacd7c1246 (binary output)
  ```

- **`pgp_sym_decrypt(msg, psw [, options ])`**:

  The `pgp_sym_decrypt` function decrypts a message `msg` that was encrypted using symmetric-key encryption with the password `psw`.

  ```sql
  SELECT pgp_sym_decrypt(encrypted_message, 'encryption_password');
  -- SELECT pgp_sym_decrypt('\xc30d040703029c3eba2b3565a3937bd2420120ae6792f663bd35977d21a5a8e13de9a8a8e5a9212ef06f8b056dcc31e0b48096915ddac66f14ab403ea671a8b4c740a198d32bcc5b804a30ef7e9aeacd7c1246', 'encryption_password');
  -- Confidential Data (plaintext output)
  ```

- **`pgp_pub_encrypt(data, key [, options ])`**:

  The `pgp_pub_encrypt` function encrypts `data` using public-key encryption with a provided public `key`. Public-key encryption uses separate keys for encryption (public key) and decryption (private key).

  ```sql
  SELECT pgp_pub_encrypt('Secret Message', 'public_key_here');
  -- encrypted_message (binary output)
  ```

- **`pgp_pub_decrypt(msg, key [, psw [, options ]])`**:

  The `pgp_pub_decrypt` function decrypts a message `msg` that was encrypted using public-key encryption. It requires the private `key` corresponding to the public key used for encryption. If the private key is password-protected, the `psw` is also required.

  ```sql
  SELECT pgp_pub_decrypt(encrypted_message, 'private_key_here', 'private_key_password');
  -- Secret Message (plaintext output)
  ```

### Random data functions

`pgcrypto` provides functions for generating cryptographically secure random data, essential for various security operations.

- **`gen_random_bytes(count integer)`**:

  The `gen_random_bytes` function generates a specified number of cryptographically strong random bytes. These bytes can be used as salts, initialization vectors, or for other security-sensitive purposes.

  ```sql
  SELECT gen_random_bytes(16); -- Generate 16 random bytes
  -- \xc9259a991537e3d730db78133f208e94 (example binary output)
  ```

- **`gen_random_uuid()`**:

  The `gen_random_uuid()` function generates a version 4 universally unique identifier (UUID) based on random numbers. This is functionally equivalent to PostgreSQL's built-in [`gen_random_uuid()`](https://neon.com/postgresql/postgresql-tutorial/postgresql-uuid#generating-uuid-values).

  ```sql
  SELECT gen_random_uuid();
  -- 90d18ac7-4af7-458d-8f7a-a7211b5d3eee (example output)
  ```

## Practical applications

`pgcrypto` offers a wide range of practical applications for enhancing data security within your Postgres environment:

- **Secure password storage**: Use `crypt()` and `gen_salt()` to securely store user passwords as hashes, protecting them from exposure in case of a data breach.
- **Data encryption at rest (Column-Level)**: Employ `pgp_sym_encrypt()` or `pgp_pub_encrypt()` to encrypt sensitive data columns within your tables, ensuring data confidentiality even if the database is compromised.
- **Data anonymization**: Leverage encryption functions to pseudonymize or anonymize sensitive data for non-production environments or for compliance purposes.

## Example: Secure password storage

Let's walk through a practical example of using `pgcrypto` to securely store and verify user passwords in a Postgres database.

1. Hash and salt a password using `crypt()` and `gen_salt()`

   Suppose you want to hash the password `"mypassword"`. You'll use `gen_salt()` to generate a salt and `crypt()` to hash the password with the salt. For this example, we'll use the Blowfish algorithm with 4 rounds (iterations):

   ```sql
   SELECT crypt('mypassword', gen_salt('bf', 4));
   -- $2a$04$vVVrQ777SjxyQKuFp7z6ue (example hashed password output)
   ```

   The output is the hashed password, which includes the salt and algorithm identifier. **You should store this entire hashed password string in your database, not the original password.**

2. Store the hashed password:

   Create a table to store usernames and their hashed passwords.

   ```sql
   CREATE TABLE users (
       username VARCHAR(50) PRIMARY KEY,
       password_hash TEXT NOT NULL
   );

   INSERT INTO users (username, password_hash) VALUES
   ('testuser', '$2a$04$vVVrQ777SjxyQKuFp7z6ue'); -- Replace with the hash from the previous step
   ```

3. Verify a password during login:

   When a user attempts to log in, you'll receive the password they entered (for example, `"mypassword"` again). To verify it, you'll use `crypt()` again, passing the entered password and the stored `password_hash` from the database.

   ```sql
   SELECT password_hash = crypt('mypassword', password_hash) AS password_match
   FROM users
   WHERE username = 'testuser';
   -- password_match
   -- --------------
   -- t
   -- (1 row)
   ```

   If the passwords match, `crypt()` will return the same stored hash (or a hash that compares as equal), and the query will return `t` (true).

4. Incorrect password attempt:

   If the user enters an incorrect password (for example, `"wrongpassword"`), the verification will fail:

   ```sql
   SELECT password_hash = crypt('wrongpassword', password_hash) AS password_match
   FROM users
   WHERE username = 'testuser';
   -- password_match
   -- --------------
   -- f
   -- (1 row)
   ```

   In this case, the query returns `f` (false), indicating an incorrect password.

By following these steps, you can securely store and verify user passwords using `pgcrypto` in your Postgres database.

## Performance Implications

While `pgcrypto` provides strong security features, consider the performance implications of cryptographic operations:

- **Computational overhead**: Encryption, decryption, and hashing operations inherently require computational resources. The extent of the overhead depends on the chosen algorithms, data size, and frequency of operations.
- **Password hashing**: Password hashing algorithms, like those used in `crypt()`, are intentionally designed to be slow to resist brute-force attacks. This can introduce a slight delay during user authentication processes.

## Security Considerations

When using `pgcrypto`, it's crucial to adhere to security best practices:

- **Key management**: Securely manage encryption keys. Store them outside the database if possible, and implement key rotation policies. Never store keys in plaintext within the database as that would defeat the purpose of encryption.
- **Algorithm selection**: Choose appropriate cryptographic algorithms based on your security requirements. For password hashing, use strong algorithms like Blowfish with sufficient iteration counts. For data encryption, select well-vetted algorithms like AES.

## Conclusion

`pgcrypto` brings a broad set of cryptographic functions into Postgres, covering password hashing, data encryption, and general-purpose hashing, all available through standard SQL queries.

## Resources

- [`pgcrypto` extension in the PostgreSQL Documentation](https://www.postgresql.org/docs/current/pgcrypto.html)

--- [Document source](https://neon.com/docs/extensions/pgrag.md) ---

> Summary: pgrag is a deprecated experimental Postgres extension for building Retrieval-Augmented Generation (RAG) pipelines in SQL. It uses small local embedding and reranking models and is not recommended for new projects. For search and RAG on Neon, use Lakebase Search with AI Gateway embeddings instead.

# The pgrag extension

Deprecated experimental RAG extension

Last updated: 2026-09-27

**Warning: The pgrag extension is deprecated**

`pgrag` is a deprecated experimental extension and is not recommended for new projects. It runs small local models directly on your Postgres server: `rag_bge_small_en_v15` for embedding and `rag_jina_reranker_v1_tiny_en` for reranking.

For search and RAG on Neon, use these instead:

- **[Lakebase Search](https://neon.com/docs/ai/lakebase-search)**: vector, keyword, and hybrid search for Postgres, built on the `lakebase_vector` and `lakebase_text` extensions. Start with the [Get started guide](https://neon.com/docs/ai/lakebase-search-get-started).
- **[AI Gateway embeddings](https://neon.com/docs/ai-gateway/embeddings)**: generate high-quality embeddings from frontier and open-source models through a single API.

The `pgrag` extension was an experimental way to build end-to-end Retrieval-Augmented Generation (RAG) pipelines in SQL, using local models for embedding and reranking alongside `pgvector` for storage. It remains available on existing projects, but it's no longer recommended for new work.

## Source code

The `pgrag` source remains available in the [pgrag GitHub repository](https://github.com/neondatabase-labs/pgrag).

--- [Document source](https://neon.com/docs/extensions/pgrowlocks.md) ---

> Summary: The `pgrowlocks` extension exposes a `pgrowlocks(relation text)` function that returns a real-time snapshot of active row-level locks on a Postgres table, including the locked row's TID, transaction XID, lock mode, and backend PIDs. Use it to diagnose lock contention and identify which sessions are blocking concurrent writes when `pg_locks` alone does not reveal row-level detail. The function takes an `AccessShareLock` on the target table and scans every row, so performance degrades on large tables. Combine with `pg_stat_activity` to map PIDs to queries and users.

# The pgrowlocks extension

Display row-level locking information for a specific table in Postgres

Last updated: 2026-06-05

The `pgrowlocks` extension provides a function to inspect active row-level locks for a specified table within your Postgres database. This is invaluable for diagnosing lock contention issues, understanding which specific rows are currently locked, and identifying the transactions or processes holding these locks. By offering a detailed, real-time view of row locks, `pgrowlocks` helps developers and database administrators troubleshoot performance bottlenecks related to concurrent data access.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `pgrowlocks` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS pgrowlocks;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## The `pgrowlocks()` function

`pgrowlocks` offers a single primary function to inspect row locks.

### Analyzing row locks with `pgrowlocks()`

The `pgrowlocks(relation text)` function provides detailed information about currently held row-level locks on a specified table.

```sql
SELECT * FROM pgrowlocks('your_table_name');
```

Key columns in the output include:

- `locked_row` (`tid`): The Tuple ID (physical location) of the locked row.
- `locker` (`xid`): The Transaction ID (or Multixact ID if `multi` is true) of the transaction holding the lock
- `multi` (`boolean`): True if `locker` is a Multixact ID (indicating multiple transactions might be involved, for example, for shared locks).
- `xids` (`xid[]`): An array of Transaction IDs that are holding locks on this specific row. This is particularly informative when `multi` is true.
- `modes` (`text[]`): An array listing the lock modes held by the corresponding `xids` on the row. Common modes include `For Key Share`, `For Share`, `For No Key Update`, `For Update`, and `Update`.
- `pids` (`integer[]`): An array of Process IDs (PIDs) of the backend database sessions holding the locks. This helps identify the specific connections.

**Example: Observing active row locks**

Let's set up a scenario to demonstrate `pgrowlocks`. First, create a simple `accounts` table:

```sql
CREATE TABLE accounts (
    account_id SERIAL PRIMARY KEY,
    owner_name TEXT,
    balance NUMERIC(10, 2)
);

INSERT INTO accounts (owner_name, balance) VALUES
('Alice', 1000.00),
('Bob', 500.00),
('Charlie', 750.00);
```

Now, to create some row locks, you would typically use multiple database sessions.

**Scenario setup (to be performed in separate `psql` sessions or database connections):**

1. **In Session 1:** Start a transaction and update Alice's account (for example, her balance), but do not commit. This will place an exclusive lock on Alice's row.

   ```sql
   -- In Session 1
   BEGIN;
   UPDATE accounts SET balance = balance - 100 WHERE account_id = 1;
   -- Do not COMMIT or ROLLBACK yet
   ```

2. **In Session 2:** Start a transaction and select Bob's account with `FOR UPDATE`. This will place an exclusive lock on Bob's row.
   ```sql
   -- In Session 2
   BEGIN;
   SELECT * FROM accounts WHERE account_id = 2 FOR UPDATE;
   -- Do not COMMIT or ROLLBACK yet
   ```

Now, **in a third session**, query `pgrowlocks` for the `accounts` table:

```sql
-- In Session 3
SELECT * FROM pgrowlocks('accounts');
```

Example output (the `locker` XIDs and `pids` will vary in your environment, and lock modes can differ based on the exact operations):

```text
 locked_row  | locker | multi | xids  |       modes       |  pids
------------+--------+-------+-------+-------------------+--------
 (0,1)      |    767 | f     | {767} | {"No Key Update"} | {1076}
 (0,2)      |    768 | f     | {768} | {"For Update"}    | {429}
(2 rows)
```

**Interpretation of the output:**

- Row `(0,1)` is locked by transaction `767` (from Session 1), associated with process ID `1076`. The `modes` column shows `{"No Key Update"}`. This lock mode is often used by `UPDATE` statements when the update does **not** modify any columns that are part of a primary key or unique constraint. In our example, updating only the `balance` column would result in this lock mode. It's an exclusive lock preventing other modifications but is slightly less restrictive than `For Update` in some internal aspects.
- Row `(0,2)` (Bob's account) is locked by transaction `768` (from Session 2), associated with process ID `429`. The `modes` column shows `{"For Update"}`. This lock mode is typically acquired by `SELECT ... FOR UPDATE` statements or by `UPDATE`/`DELETE` statements when key columns are involved or stronger locking is required.
- `multi` is `f` (false) in both cases, indicating these are straightforward locks by single transactions.

This output clearly shows which specific rows are locked, by which transactions, the precise mode of the lock, and the process IDs of the sessions holding the locks.

**Note: Data Transience**

The information from `pgrowlocks` is a real-time snapshot. It reflects the locks present at the exact moment of execution and does not store historical data.

## Practical usage examples

### Viewing the content of locked rows

`pgrowlocks` shows which rows are locked (`locked_row` TID) but not their data. To see the actual data of the locked rows, you can join the `pgrowlocks` output with the table itself using the system column `ctid`.

```sql
SELECT
    a.*, -- Select all columns from your table
    p.locker AS locking_transaction_id,
    p.modes AS lock_modes,
    p.pids AS locking_process_ids
FROM
    accounts AS a,
    pgrowlocks('accounts') AS p
WHERE
    p.locked_row = a.ctid;
```

**Example output:**

```text
 account_id  | owner_name | balance | locking_transaction_id |    lock_modes     | locking_process_ids
------------+------------+---------+------------------------+-------------------+---------------------
          1 | Alice      | 1000.00 |                   1027 | {"No Key Update"} | {405}
          2 | Bob        |  500.00 |                   1028 | {"For Update"}    | {419}
(2 rows)
```

**Warning: Performance Impact**

This query can be very inefficient, especially on large tables, as `pgrowlocks` itself scans the table, and the join might add further overhead. Use it cautiously in production environments.

### Identifying blocking sessions and queries

One of the most powerful uses of `pgrowlocks` is to help diagnose lock contention. By combining its output with `pg_stat_activity`, you can find out exactly which queries and users are involved in holding or waiting for row locks.

```sql
SELECT
    p.locked_row,
    p.locker AS locking_transaction_id,
    p.modes AS lock_modes,
    act.pid AS locker_pid,
    act.usename AS locker_user,
    act.query AS locker_query,
    act.state AS locker_state,
    act.wait_event_type AS locker_wait_type,
    act.wait_event AS locker_wait_event
FROM
    pgrowlocks('accounts') AS p
JOIN
    pg_stat_activity AS act ON act.pid = ANY(p.pids);
```

The query above shows the details of the session(s) directly holding the row locks identified by `pgrowlocks`. To find sessions _blocked_ by these row locks, you would typically query `pg_locks` where `granted = false` and correlate the `transactionid`, `relation`, and potentially tuple information.

**Example output:**

```text
 locked_row | locking_transaction_id |    lock_modes     | locker_pid | locker_user  |                           locker_query                            |    locker_state     | locker_wait_type | locker_wait_event
------------+------------------------+-------------------+------------+--------------+-------------------------------------------------------------------+---------------------+------------------+-------------------
 (0,1)      |                   1029 | {"No Key Update"} |       1601 | neondb_owner | UPDATE accounts SET balance = balance - 100 WHERE account_id = 1; | idle in transaction | Client           | ClientRead
 (0,2)      |                   1030 | {"For Update"}    |       1629 | neondb_owner | SELECT * FROM accounts WHERE account_id = 2 FOR UPDATE;           | idle in transaction | Client           | ClientRead
(2 rows)
```

This output provides a comprehensive view of the locking situation, including the user and query that are holding the locks. You can use this information to effectively communicate with your team or take action to resolve the contention.

> You can now `COMMIT` or `ROLLBACK` the transactions in Session 1 and Session 2 to release their locks.

## Important considerations and limitations

- **Lock acquisition**: `pgrowlocks` takes an `AccessShareLock` on the target table to read its rows.
- **Blocking**: If an `ACCESS EXCLUSIVE` lock is held on the table (for example, by an `ALTER TABLE` operation), `pgrowlocks` will be blocked until that exclusive lock is released.
- **Performance**: `pgrowlocks` reads each row of the table to check for locks. This can be slow and resource-intensive on very large tables.

## Conclusion

The `pgrowlocks` extension is a vital tool to diagnose row-level locking contention. By providing a clear view of which rows are locked, by whom, and in what mode, it helps developers and DBAs to quickly identify and resolve performance issues caused by concurrent data access patterns. While it should be used judiciously on large tables due to its scanning nature, its insights are invaluable for troubleshooting complex locking scenarios.

## Resources

- [PostgreSQL `pgrowlocks` documentation](https://www.postgresql.org/docs/current/pgrowlocks.html)
- [Monitor active queries on Neon: powered by `pg_stat_activity`](https://neon.com/docs/introduction/monitor-active-queries)
- [MultiXacts in PostgreSQL: usage, side effects, and monitoring](https://aws.amazon.com/blogs/database/multixacts-in-postgresql-usage-side-effects-and-monitoring/)

--- [Document source](https://neon.com/docs/extensions/pgstattuple.md) ---

> Summary: The `pgstattuple` extension inspects Postgres physical storage at the tuple level, reporting dead tuple counts, dead tuple percentages, free space, and B-tree leaf density needed to measure table and index bloat. Use it when you need to quantify bloat caused by unvacuumed DELETE or UPDATE operations and decide whether to run VACUUM, VACUUM FULL, or REINDEX. Functions include `pgstattuple()` for exact full-scan stats, `pgstattuple_approx()` for faster visibility-map-based estimates on large tables, and `pgstatindex()` for B-tree fragmentation metrics. GIN and hash index stats are covered by `pgstatginindex()` and `pgstathashindex()`.

# The pgstattuple extension

Analyze table, index bloat, and fragmentation in Postgres

Last updated: 2026-07-22

The `pgstattuple` extension provides a suite of functions to inspect the physical storage of Postgres tables and indexes at a detailed, tuple (row) level. It offers insights into issues like table and index bloat, fragmentation, and overall space utilization, which are crucial for performance tuning and storage management.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `pgstattuple` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS pgstattuple;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## `pgstattuple` functions

`pgstattuple` offers several functions to inspect different aspects of your database storage.

### Analyzing table statistics with `pgstattuple()`

The `pgstattuple(relation regclass)` function provides detailed statistics about a table's physical storage. It performs a full scan of the relation.

```sql
SELECT * FROM pgstattuple('your_table_name');
```

Key columns in the output include:

- `table_len`: Total size of the table on disk in bytes.
- `tuple_count`: Number of live (visible) tuples.
- `tuple_len`: Total length of live tuples in bytes.
- `tuple_percent`: Percentage of space occupied by live tuples.
- `dead_tuple_count`: Number of dead tuples (not yet vacuumed).
- `dead_tuple_len`: Total length of dead tuples in bytes.
- `dead_tuple_percent`: Percentage of space occupied by dead tuples. This is a direct indicator of bloat due to dead rows.
- `free_space`: Total free space available within allocated pages in bytes (usable for future `INSERT`s/`UPDATE`s without extending the table).
- `free_percent`: Percentage of total table space that is free.

**Example: Observing table statistics and bloat**

Let's create a `customers` table, populate it, delete some rows to create bloat, and then observe the statistics using `pgstattuple`.

```sql
-- Create the customers table
CREATE TABLE customers (
    customer_id SERIAL PRIMARY KEY,
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    email VARCHAR(255),
    phone VARCHAR(20),
    address VARCHAR(255),
    city VARCHAR(100),
    state VARCHAR(100),
    zip_code VARCHAR(20),
    created_at TIMESTAMP WITHOUT TIME ZONE DEFAULT NOW()
);

-- Insert 10,000 rows into the customers table
INSERT INTO customers (first_name, last_name, email, phone, address, city, state, zip_code, created_at)
SELECT
    CASE (i % 10) WHEN 0 THEN 'John' WHEN 1 THEN 'Jane' WHEN 2 THEN 'Peter' WHEN 3 THEN 'Mary' WHEN 4 THEN 'Robert' WHEN 5 THEN 'Patricia' WHEN 6 THEN 'Michael' WHEN 7 THEN 'Linda' WHEN 8 THEN 'William' ELSE 'Elizabeth' END || '_' || i::TEXT,
    CASE (i % 10) WHEN 0 THEN 'Smith' WHEN 1 THEN 'Johnson' WHEN 2 THEN 'Williams' WHEN 3 THEN 'Jones' WHEN 4 THEN 'Brown' WHEN 5 THEN 'Davis' WHEN 6 THEN 'Miller' WHEN 7 THEN 'Wilson' WHEN 8 THEN 'Moore' ELSE 'Taylor' END || '_' || i::TEXT,
    'customer' || i::TEXT || '@example.com',
    '555-' || LPAD((i % 10000)::TEXT, 4, '0'),
    (i * 10)::TEXT || ' Main St',
    CASE (i % 5) WHEN 0 THEN 'New York' WHEN 1 THEN 'Los Angeles' WHEN 2 THEN 'Chicago' WHEN 3 THEN 'Houston' ELSE 'Phoenix' END,
    CASE (i % 5) WHEN 0 THEN 'NY' WHEN 1 THEN 'CA' WHEN 2 THEN 'IL' WHEN 3 THEN 'TX' ELSE 'AZ' END,
    LPAD((i % 99999)::TEXT, 5, '0'),
    NOW() - (random() * INTERVAL '365 days')
FROM generate_series(1, 10000) AS s(i);

 -- Delete half of the rows to create dead tuples
DELETE FROM customers WHERE customer_id % 2 = 0;

-- Check the table statistics before vacuuming
SELECT * FROM pgstattuple('customers');
```

Example output:

```text
table_len | tuple_count | tuple_len | tuple_percent | dead_tuple_count | dead_tuple_len | dead_tuple_percent | free_space | free_percent
-----------+-------------+-----------+----------------+------------------+----------------+--------------------+------------+--------------
 1343488   |    5000     |   638144  |      47.5      |       5000       |     645432     |       48.04        |   15320    |     1.14
```

The output above (your values may vary) shows `dead_tuple_count` of 5000 and `dead_tuple_percent` around 48%. This high percentage of dead tuples indicates significant table bloat caused by the `DELETE` operation. Neon performs automatic `VACUUM` operations, but for immediate analysis or specific needs, you can run `VACUUM` manually.

To reclaim the space occupied by these dead tuples for reuse within the table, run:

```sql
VACUUM customers;
```

Now, let's check the statistics again:

```sql
SELECT * FROM pgstattuple('customers');
```

Example output (after `VACUUM`):

```text
table_len | tuple_count | tuple_len | tuple_percent | dead_tuple_count | dead_tuple_len | dead_tuple_percent | free_space | free_percent
-----------+-------------+-----------+----------------+------------------+----------------+--------------------+------------+--------------
 1343488   |    5000     |   638144  |      47.5      |       0          |     0          |       0            |   661080    |     49.21
```

After `VACUUM`, `dead_tuple_count` is 0, and `dead_tuple_percent` is 0. The `free_space` (and `free_percent`) has increased significantly, indicating that the space previously occupied by dead tuples is now available for reuse by future `INSERT` or `UPDATE` operations on the `customers` table.

**Note: Page Overhead**

The `table_len` will always be greater than the sum of `tuple_len`, `dead_tuple_len`, and `free_space`. The difference accounts for page headers, per-page tuple pointers, and padding required for data alignment.

### Estimating table statistics with `pgstattuple_approx()`

The `pgstattuple_approx(relation regclass)` function offers a faster way to get approximate table statistics. It tries to avoid full table scans by using the visibility map (VM) to skip pages known to contain only live tuples. For such pages, it estimates live tuple data from free space map information. Dead tuple statistics reported by this function are exact.

```sql
SELECT * FROM pgstattuple_approx('your_table_name');
```

Use this function for large tables where a full `pgstattuple()` scan would be too slow or resource-intensive for frequent checks. - Output columns are similar to `pgstattuple()`, but with `approx_` prefixes for estimated values (for example, `approx_tuple_count`, `approx_free_space`). - `dead_tuple_count` and `dead_tuple_len` are exact.

### Analyzing B-tree index statistics with `pgstatindex()`

The `pgstatindex(index regclass)` function provides statistics for B-tree indexes.

```sql
SELECT * FROM pgstatindex('your_index_name');
```

Key columns in the output include:

- `version`: B-tree version number.
- `tree_level`: Level of the B-tree (0 for an empty index, 1 for a root page with leaves, etc.).
- `index_size`: Total size of the index on disk in bytes.
- `leaf_pages`: Number of leaf pages (where actual index entries pointing to table rows are stored).
- `internal_pages`: Number of internal (non-leaf) pages.
- `empty_pages`: Number of completely empty pages within the index.
- `deleted_pages`: Number of pages marked as deleted but not yet reclaimed.
- `avg_leaf_density`: Average fullness of leaf pages as a percentage. Lower values can indicate bloat or inefficient space usage.
- `leaf_fragmentation`: A measure of logical fragmentation of leaf pages. Higher values indicate that logically sequential leaf pages might be physically distant on disk, which can impact scan performance.

**Example: Observing Index statistics**

```sql
-- Create an index on the customers table
CREATE INDEX idx_customers_first_name ON customers (first_name);

-- Check index statistics
SELECT * FROM pgstatindex('idx_customers_first_name');
```

Example output (your values may vary):

```text
version | tree_level | index_size | root_block_no | internal_pages | leaf_pages | empty_pages | deleted_pages | avg_leaf_density | leaf_fragmentation
---------+------------+------------+----------------+----------------+------------+-------------+---------------+------------------+-------------------
       4 |          1 |      180224 |              3 |              1 |         20 |           0 |             0 |            86.14 |                 0
```

**Note: Other Index Types**

The `pgstattuple` extension also provides `pgstatginindex()` for GIN indexes and `pgstathashindex()` for HASH indexes. While these functions also report on storage characteristics, the specific metrics returned are tailored to the internal structure of GIN and HASH indexes, respectively.

## Practical usage examples

### Detecting and managing table bloat

Table bloat occurs primarily when `UPDATE` or `DELETE` operations are performed. `UPDATE` operations in Postgres internally perform a `DELETE` of the old row version and an `INSERT` of the new row version. The space occupied by these "dead" (old or deleted) tuples is not immediately reclaimed by the operating system. Instead, it remains within the table's allocated pages, potentially leading to larger table sizes than necessary and reduced query performance due to scanning more pages. `pgstattuple` helps quantify this bloat.

In our `customers` table example:

1. We inserted 10,000 rows.
2. We then deleted half of these rows (`DELETE FROM customers WHERE customer_id % 2 = 0;`). These 5,000 deleted rows become "dead tuples".

The `pgstattuple('customers')` output _before_ running `VACUUM` was:

```text
table_len | tuple_count | tuple_len | tuple_percent | dead_tuple_count | dead_tuple_len | dead_tuple_percent | free_space | free_percent
-----------+-------------+-----------+----------------+------------------+----------------+--------------------+------------+--------------
 1343488   |    5000     |   638144  |      47.5      |       5000       |     645432     |       48.04        |   15320    |     1.14
```

Here's how to interpret this:

- `dead_tuple_count` is 5000, matching the number of rows we deleted.
- `dead_tuple_percent` is 48.04%, indicating that nearly half the space within the data pages (excluding page overhead and existing free space) is occupied by these dead tuples. This is a clear sign of significant bloat.
- `free_percent` is low (1.14%), meaning there isn't much readily available space within the existing pages for new data _before_ a `VACUUM`.

Upon identifying bloat, `VACUUM` is the standard command to reclaim this space _for reuse by Postgres_. A standard `VACUUM` marks the space occupied by dead tuples as free, making it available for future `INSERT`s and `UPDATE`s on the same table. It typically does not shrink the table file on disk (i.e., `table_len` often remains the same).

After running `VACUUM customers;`, the `pgstattuple('customers')` output showed:

```text
table_len | tuple_count | tuple_len | tuple_percent | dead_tuple_count | dead_tuple_len | dead_tuple_percent | free_space | free_percent
-----------+-------------+-----------+----------------+------------------+----------------+--------------------+------------+--------------
 1343488   |    5000     |   638144  |      47.5      |       0          |     0          |       0            |   661080    |     49.21
```

Observations:

- `dead_tuple_count` and `dead_tuple_percent` are now 0, confirming the dead tuples have been processed.
- `free_percent` has increased dramatically to 49.21%. This space, previously held by dead tuples, is now marked as free and can be reused by new rows or updates to existing rows in the `customers` table without requiring Postgres to request more disk space from the OS for this table immediately.
- `table_len` (1343488) remained the same, which is typical for a standard `VACUUM`. To return space to the operating system and reduce `table_len`, you would need `VACUUM FULL` or tools like `pg_repack`, but these come with different locking implications.

To run `VACUUM FULL`, which compacts the table and returns space to the OS, you would use:

```sql
VACUUM FULL customers;
```

**Warning:** `VACUUM FULL` requires an exclusive lock on the table, which can block other operations. Use it judiciously, especially in production environments.

Running the `pgstattuple('customers')` again after `VACUUM FULL` would show a reduced `table_len`, indicating that the space has been returned to the operating system.

```sql
SELECT * FROM pgstattuple('customers');
```

**Example output (after `VACUUM FULL`)**:

```text
 table_len | tuple_count | tuple_len | tuple_percent | dead_tuple_count | dead_tuple_len | dead_tuple_percent | free_space | free_percent
-----------+-------------+-----------+---------------+------------------+----------------+--------------------+------------+--------------
    671744 |        5000 |    638144 |            95 |                0 |              0 |                  0 |      11304 |         1.68
(1 row)
```

### Identifying top bloated tables

You can query `pg_class` and use `pgstattuple` functions to find the most bloated tables in your database. This query focuses on the actual space occupied by dead tuples.

```sql
SELECT
    c.relname AS table_name,
    pg_size_pretty(s.table_len) AS total_table_size,
    round(s.dead_tuple_percent::numeric, 2) AS dead_tuple_percentage,
    pg_size_pretty(s.dead_tuple_len) AS space_occupied_by_dead_tuples,
    round(s.free_percent::numeric, 2) AS free_space_percentage
FROM
    pg_class c
JOIN
    pg_namespace n ON n.oid = c.relnamespace
CROSS JOIN LATERAL pgstattuple(c.oid::regclass) s -- For better performance on large DBs, consider pgstattuple_approx(c.oid::regclass) s
WHERE
    c.relkind IN ('r', 'm') -- r = ordinary table, m = materialized view
    AND n.nspname NOT IN ('pg_catalog', 'information_schema') -- Exclude system schemas
    AND n.nspname NOT LIKE 'pg_toast%' -- Exclude TOAST tables
    AND n.nspname NOT LIKE 'pg_temp_%' -- Exclude temporary schemas
    AND s.dead_tuple_len > 0 -- Only consider tables with some dead tuple space
ORDER BY
    s.dead_tuple_len DESC -- Order by the tables with the most space taken by dead tuples
LIMIT 10;
```

**Warning: Resource Intensive Query**

Running `pgstattuple()` for every table can be very resource-intensive. For larger databases, consider using `pgstattuple_approx()` in the `CROSS JOIN LATERAL` subquery or filtering tables by size first (for example, adding `AND pg_total_relation_size(c.oid) > '1GB'` to the `WHERE` clause).

For a lighter-weight estimate that needs no extension, [`neon inspect db bloat`](https://neon.com/docs/cli/inspect#db-bloat) reports the top bloated tables from the Neon CLI.

### Diagnosing and resolving index bloat and fragmentation

For B-tree indexes, low `avg_leaf_density` or high `leaf_fragmentation` can indicate performance issues.

```sql
SELECT
    index_size,
    leaf_pages,
    avg_leaf_density,
    leaf_fragmentation
FROM pgstatindex('idx_customers_first_name');
```

If `avg_leaf_density` is low (for example, < 60-70%) or `leaf_fragmentation` is high (for example, > 20-30% for frequently scanned indexes), the index might benefit from rebuilding.

To rebuild an index:

```sql
REINDEX INDEX idx_customers_first_name;
```

After reindexing, check `pgstatindex` again; you should see improved `avg_leaf_density` (closer to 90%) and reduced `leaf_fragmentation`.

## Best practices

- **Resource Intensive:** `pgstattuple()` performs a full table/index scan, which can be I/O and CPU intensive, especially on large objects. `pgstattuple_approx()` is faster but still reads a portion of the table.
- **Run off-peak:** Schedule `pgstattuple` analysis during low-traffic periods to minimize impact on production workloads.
- **Target specific objects:** Instead of scanning all tables/indexes, focus on known large or frequently modified objects, or those identified as problematic by other monitoring tools.
- **Combine with `pg_repack`:** For online table and index reorganization to remove bloat without extensive locking (unlike `VACUUM FULL` or `REINDEX`), consider the [`pg_repack` extension](https://neon.com/docs/extensions/pg_repack).

## Conclusion

The `pgstattuple` extension helps you understand the physical storage characteristics of your Postgres database. Use it to identify and quantify table and index bloat and fragmentation, which informs maintenance strategies, autovacuum tuning, and storage optimization.

## Resources

- [PostgreSQL documentation for pgstattuple](https://www.postgresql.org/docs/current/pgstattuple.html)

--- [Document source](https://neon.com/docs/extensions/pgvector.md) ---

> Summary: The pgvector extension adds vector embedding storage and similarity search to Lakebase Postgres, supporting exact and approximate nearest-neighbor queries with L2, cosine, inner product, L1, Hamming, and Jaccard distance operators. Use this page when building AI or NLP applications that store embeddings from models such as OpenAI text-embedding-3-small and need to choose between HNSW and IVFFlat indexes, tune build performance, or pick a vector type (vector, halfvec, bit, sparsevec). HNSW supports up to 2,000 dimensions for vector, 4,000 for halfvec, and 64,000 for bit; IVFFlat shares the same limits.

# The pgvector extension

Enable Postgres as a vector store with the pgvector extension

Last updated: 2026-11-06

The `pgvector` extension enables you to store vector embeddings and perform vector similarity search in Postgres. It's a natural fit for natural language processing applications, including those built on top of OpenAI's GPT models.

`pgvector` supports:

- Exact and approximate nearest neighbor search
- Single-precision, half-precision, binary, and sparse vectors
- L2 distance, inner product, cosine distance, L1 distance, Hamming distance, and Jaccard distance
- Any language with a Postgres client
- ACID compliance, point-in-time recovery, JOINs, and all other Postgres features

This topic describes how to enable the `pgvector` extension in Neon and how to create, store, and query vectors.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the pgvector extension

You can enable the `pgvector` extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to Neon.

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

`pgvector` is available on every Neon plan with no add-on or paid tier required. The extension is installed per database, not per project, so run this statement once in each database where you want to store vectors. If you have multiple databases on a branch, enable it in each one.

To confirm the extension is installed and check its version:

```sql
SELECT extname, extversion FROM pg_extension WHERE extname = 'vector';
```

## Use a previous version of pgvector

Neon allows you to install the previous version of `pgvector`, which is one version behind the latest supported version.

For example, if Neon's latest supported `pgvector` version is 0.8.0, you can install the prior version, 0.7.4, by specifying the version number:

```sql
CREATE EXTENSION vector VERSION '0.7.4';
```

To check the latest supported `pgvector` version on Neon, visit our [Postgres extensions page](https://neon.com/docs/extensions/pg-extensions). You can install one version back from that version.

For a full version history, see the [pgvector changelog](https://github.com/pgvector/pgvector/blob/master/CHANGELOG.md). Note that `pgvector` versions are not always sequential; for example, version 0.7.4 was followed by 0.8.0.

## Create a table to store vectors

To create a table for storing vectors, you would use an SQL command similar to the following. Embeddings are stored in the `VECTOR` type column. You can adjust the number of dimensions as needed.

```sql
CREATE TABLE items (
  id BIGSERIAL PRIMARY KEY,
  embedding VECTOR(3)
);
```

**Note:** The `pgvector` extension supports some specialized types other than `VECTOR` for storing embeddings. See [HNSW vector types](https://neon.com/docs/extensions/pgvector#hnsw-vector-types), and [IVFFlat vector types](https://neon.com/docs/extensions/pgvector#ivfflat-vector-types).

This command generates a table named `items` with an `embedding` column capable of storing vectors with 3 dimensions. OpenAI's `text-embedding-3-small` model supports 1536 dimensions by default for each piece of text, which creates more accurate embeddings for natural language processing tasks. However, using larger embeddings generally costs more and consumes more compute, memory, and storage than using smaller embeddings. To learn more about embeddings and the cost-performance tradeoff, see [Embeddings](https://platform.openai.com/docs/guides/embeddings/what-are-embeddings), in the _OpenAI documentation_.

## Storing embeddings

After generating embeddings using a service like the [Neon AI Gateway](https://neon.com/docs/ai-gateway/embeddings) or [OpenAI's Embeddings API](https://platform.openai.com/docs/api-reference/embeddings), you can store them in your database. The gateway serves embedding models with the same Neon credential you use for the rest of your project. Using a Postgres client library in your preferred programming language, you can execute an `INSERT` statement similar to the following to store embeddings.

- Insert two new rows into the `items` table with the provided embeddings.

  ```sql
  INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');
  ```

- Load vectors in bulk using the `COPY` command:

  ```sql
  COPY items (embedding) FROM STDIN WITH (FORMAT BINARY);
  ```

  **Tip:** For a Python script that loads embeddings in bulk, refer to this [Bulk loading with COPY](https://github.com/pgvector/pgvector-python/blob/master/examples/loading/example.py) example provided in the `pgvector` GitHub repository.

- Upsert vectors:

  ```sql
  INSERT INTO items (id, embedding) VALUES (1, '[1,2,3]'), (2, '[4,5,6]')
     ON CONFLICT (id) DO UPDATE SET embedding = EXCLUDED.embedding;
  ```

- Update vectors:

  ```sql
  UPDATE items SET embedding = '[1,2,3]' WHERE id = 1;
  ```

- Delete vectors:

  ```sql
  DELETE FROM items WHERE id = 1;
  ```

## Querying vectors

To retrieve vectors and calculate similarity, use `SELECT` statements and the distance function operators supported by `pgvector`.

- Get the nearest neighbor to a vector by L2 distance:

  ```sql
  SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 5;
  ```

- Get the nearest neighbor to a row by L2 distance:

  ```sql
  SELECT * FROM items WHERE id != 1 ORDER BY embedding <-> (SELECT embedding FROM items WHERE id = 1) LIMIT 5;
  ```

- Get rows within a certain distance by L2 distance:

  ```sql
  SELECT * FROM items WHERE embedding <-> '[3,1,2]' < 5;
  ```

  **Note:** To use an index with a query, include `ORDER BY` and `LIMIT` clauses, as shown in the second query example above.

### Distance function operators

- `<->` - L2 distance
- `<#>` - (negative) inner product
- `<=>` - cosine distance
- `<+>` - L1 distance

**Note:** The inner product operator (`<#>`) returns the negative inner product since Postgres only supports `ASC` order index scans on operators.

### Distance queries

- Get the distances:

  ```sql
  SELECT embedding <-> '[3,1,2]' AS distance FROM items;
  ```

- For inner product, multiply by `-1` (since `<#>` returns the negative inner product):

  ```sql
  SELECT (embedding <#> '[3,1,2]') * -1 AS inner_product FROM items;
  ```

- For cosine similarity, use `1 -` cosine distance:

  ```sql
  SELECT 1 - (embedding <=> '[3,1,2]') AS cosine_similarity FROM items;
  ```

### Aggregate queries

- To average vectors:

  ```sql
  SELECT AVG(embedding) FROM items;
  ```

- To average groups of vectors:

  ```sql
  SELECT category_id, AVG(embedding) FROM items GROUP BY category_id;
  ```

## Indexing vectors

By default, `pgvector` performs exact nearest neighbor search, providing perfect recall. Adding an index on the vector column can improve query performance with a minor cost in recall. Unlike typical indexes, you will see different results for queries after adding an approximate index.

Supported index types include:

- [HNSW](https://neon.com/docs/extensions/pgvector#hnsw)
- [IVFFLAT](https://neon.com/docs/extensions/pgvector#ivfflat)

### HNSW

An HNSW index creates a multilayer graph. It has better query performance than an IVFFlat index (in terms of speed-recall tradeoff), but has slower build times and uses more memory. Also, an HNSW index can be created without any data in the table since there isn't a training step like there is for an IVFFlat index.

#### HNSW vector types

HNSW indexes are supported with the following vector types:

- `vector` - up to 2,000 dimensions
- `halfvec` - up to 4,000 dimensions
- `bit` - up to 64,000 dimensions
- `sparsevec` - up to 1,000 non-zero elements

**Note:** Notice how indexes are defined differently depending on the distance function being used. For example `vector_l2_ops` is specified for L2 distance, `vector_ip_ops` for inner product, and so on. Make sure you define your index according to the distance function you intend to use.

- L2 distance:

  ```sql
  CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);
  ```

- Inner product:

  ```sql
  CREATE INDEX ON items USING hnsw (embedding vector_ip_ops);
  ```

- Cosine distance:

  ```sql
  CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);
  ```

- L1 distance:

  ```sql
  CREATE INDEX ON items USING hnsw (embedding vector_l1_ops);
  ```

- Hamming distance:

  ```sql
  CREATE INDEX ON items USING hnsw (embedding bit_hamming_ops);
  ```

- Jaccard distance:

  ```sql
  CREATE INDEX ON items USING hnsw (embedding bit_jaccard_ops);
  ```

#### HNSW index build options

- `m` - the max number of connections per layer (16 by default)
- `ef_construction` - the size of the dynamic candidate list for constructing the graph (`64` by default)

This example demonstrates how to set the parameters:

```sql
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64);
```

A higher value of `ef_construction` provides better recall at the cost of index build time and insert speed.

#### HNSW index query options

You can specify the size of the candidate list for search. The size is `40` by default.

```sql
SET hnsw.ef_search = 100;
```

A higher value provides better recall at the cost of speed.

This query shows how to use `SET LOCAL` inside a transaction to set `ef_search` for a single query:

```sql
BEGIN;
SET LOCAL hnsw.ef_search = 100;
SELECT ...
COMMIT;
```

#### HNSW index build time

To optimize index build time, consider configuring the `maintenance_work_mem` and `max_parallel_maintenance_workers` session variables before building an index:

**Note:** Like other index types, it's faster to create an index after loading your initial data.

- `maintenance_work_mem`

  Indexes build significantly faster when the graph fits into Postgres `maintenance_work_mem`.

  A notice is shown when the graph no longer fits:

  ```text
  NOTICE:  hnsw graph no longer fits into maintenance_work_mem after 100000 tuples
  DETAIL:  Building will take significantly more time.
  HINT:  Increase maintenance_work_mem to speed up builds.
  ```

  In Postgres, the `maintenance_work_mem` setting determines the maximum memory allocation for tasks such as `CREATE INDEX`. The default `maintenance_work_mem` value in Neon is set according to your Neon [compute size](https://neon.com/docs/manage/computes#how-to-size-your-compute).

  To optimize `pgvector` index build time, you can increase the `maintenance_work_mem` setting for the current session with a command similar to the following:

  ```sql
  SET maintenance_work_mem='10 GB';
  ```

  The recommended setting is your working set size (the size of your tuples for vector index creation). However, your `maintenance_work_mem` setting should not exceed 50 to 60 percent of your compute's available RAM. For example, the `maintenance_work_mem='10 GB'` setting shown above has been successfully tested on a 7 CU compute, which has 28 GB of RAM, as 10 GB is less than 50% of the RAM available for that compute size.

- `max_parallel_maintenance_workers`

  You can also speed up index creation by increasing the number of parallel workers. The default is `2`.

  The `max_parallel_maintenance_workers` sets the maximum number of parallel workers that can be started by a single utility command such as `CREATE INDEX`. By default, the `max_parallel_maintenance_workers` setting is `2`. For efficient parallel index creation, you can increase this setting. Parallel workers are taken from the pool of processes established by `max_worker_processes` (`10`), limited by `max_parallel_workers` (`8`).

  You can increase the `maintenance_work_mem` setting for the current session with a command similar to the following:

  ```sql
  SET max_parallel_maintenance_workers = 7
  ```

  For example, if you have a 7 CU compute size, you could set `max_parallel_maintenance_workers` to 7, before index creation, to make use of all of the available CPU cores.

  For a large number of workers, you may also need to increase the Postgres `max_parallel_workers`, which is `8` by default.

#### Check indexing progress

You can check indexing progress with the following query:

```sql
SELECT phase, round(100.0 * blocks_done / nullif(blocks_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;
```

The phases for HNSW are:

1. initializing
2. loading tuples

For related information, see [CREATE INDEX Progress Reporting](https://www.postgresql.org/docs/current/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING), in the _PostgreSQL documentation_.

### IVFFlat

An IVFFlat index divides vectors into lists and searches a subset of those lists that are closest to the query vector. It has faster build times and uses less memory than HNSW, but has lower query performance with respect to the speed-recall tradeoff.

Keys to achieving good recall include:

- Creating the index after the table has some data
- Choosing an appropriate number of lists. A good starting point is rows/1000 for up to 1M rows and `sqrt(rows)` for over 1M rows.
- Specifying an appropriate number of [probes](https://neon.com/docs/extensions/pgvector#hnsw-query-options) when querying. A higher number is better for recall, and a lower is better for speed. A good starting point is `sqrt(lists)`.

#### IVFFlat vector types

IVFFlat indexes are supported with the following vector types:

- `vector` - up to 2,000 dimensions
- `halfvec` - up to 4,000 dimensions (added in 0.7.0)
- `bit` - up to 64,000 dimensions (added in 0.7.0)

The following examples show how to add an index for each distance function:

**Note:** Notice how indexes are defined differently depending on the distance function being used. For example `vector_l2_ops` is specified for L2 distance, `vector_cosine_ops` for cosine distance, and so on.

The following examples show how to add an index for each distance function:

- L2 distance

  ```sql
  CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100);
  ```

  **Note:** Use `halfvec_l2_ops` for halfvec (and similar with the other distance functions).

- Inner product

  ```sql
  CREATE INDEX ON items USING ivfflat (embedding vector_ip_ops) WITH (lists = 100);
  ```

- Cosine distance

  ```sql
  CREATE INDEX ON items USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
  ```

- Hamming distance

  ```sql
  CREATE INDEX ON items USING ivfflat (embedding bit_hamming_ops) WITH (lists = 100);
  ```

#### IVFFlat query options

You can specify the number of probes, which is `1` by default.

```sql
SET ivfflat.probes = 10;
```

A higher value provides better recall at the cost of speed. You can set the value to the number of lists for exact nearest neighbor search, at which point the planner won't use the index.

You can also use `SET LOCAL` inside a transaction to set the number of probes for a single query:

```sql
BEGIN;
SET LOCAL ivfflat.probes = 10;
SELECT ...
COMMIT;
```

#### IVFFlat index build time

To optimize index build time, consider configuring the `maintenance_work_mem` and `max_parallel_maintenance_workers` session variables before building an index:

**Note:** Like other index types, it's faster to create an index after loading your initial data.

**Note:** Like other index types, it's faster to create an index after loading your initial data.

- `maintenance_work_mem`

  In Postgres, the `maintenance_work_mem` setting determines the maximum memory allocation for tasks such as `CREATE INDEX`. The default `maintenance_work_mem` value in Neon is set according to your Neon [compute size](https://neon.com/docs/manage/computes#how-to-size-your-compute). For a table that shows the `maintenance_work_mem` setting by compute size, see [Parameter settings that differ by compute size](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size).

  To optimize `pgvector` index build time, you can increase the `maintenance_work_mem` setting for the current session with a command similar to the following:

  ```sql
  SET maintenance_work_mem='10 GB';
  ```

  The recommended setting is your working set size (the size of your tuples for vector index creation). However, your `maintenance_work_mem` setting should not exceed 50 to 60 percent of your compute's available RAM. For example, the `maintenance_work_mem='10 GB'` setting shown above has been successfully tested on a 7 CU compute, which has 28 GB of RAM, as 10 GB is less than 50% of the RAM available for that compute size.

- `max_parallel_maintenance_workers`

  You can also speed up index creation by increasing the number of parallel workers. The default is `2`.

  The `max_parallel_maintenance_workers` sets the maximum number of parallel workers that can be started by a single utility command such as `CREATE INDEX`. By default, the `max_parallel_maintenance_workers` setting is `2`. For efficient parallel index creation, you can increase this setting. Parallel workers are taken from the pool of processes established by `max_worker_processes` (`10`), limited by `max_parallel_workers` (`8`).

  You can increase the `maintenance_work_mem` setting for the current session with a command similar to the following:

  ```sql
  SET max_parallel_maintenance_workers = 7
  ```

  For example, if you have a 7 CU compute size, you could set `max_parallel_maintenance_workers` to 7, before index creation, to make use of all of the available CPU cores.

  For a large number of workers, you may also need to increase the Postgres `max_parallel_workers`, which is `8` by default.

#### Check indexing progress

You can check indexing progress with the following query:

```sql
SELECT phase, round(100.0 * blocks_done / nullif(blocks_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;
```

The phases for HNSW are:

1. initializing
2. loading tuples

For related information, see [CREATE INDEX Progress Reporting](https://www.postgresql.org/docs/current/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING), in the _PostgreSQL documentation_.

## Filtering

There are a few ways to index nearest neighbor queries with a `WHERE` clause:

```sql
SELECT * FROM items WHERE category_id = 123 ORDER BY embedding <-> '[3,1,2]' LIMIT 5;
```

Create an index on one or more of the `WHERE` columns for exact search"

```sql
CREATE INDEX ON items (category_id);
```

Create a [partial index](https://www.postgresql.org/docs/current/indexes-partial.html) on the vector column for approximate search:

```sql
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WHERE (category_id = 123);
```

Use [partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html) for approximate search on many different values of the `WHERE` columns:

```sql
CREATE TABLE items (embedding vector(3), category_id int) PARTITION BY LIST(category_id);
```

## Half-precision vectors

Half-precision vectors enable the storage of vector embeddings using 16-bit floating-point numbers, or half-precision, which reduces both storage size and memory usage by nearly half compared 32-bit floats. This efficiency comes with minimal loss in precision, making half-precision vectors beneficial for applications dealing with large datasets or facing memory constraints.

When integrating OpenAI's embeddings, you can take advantage of half-precision vectors by storing embeddings in a compressed format. For instance, OpenAI's high-dimensional embeddings can be effectively stored with half-precision vectors, achieving high levels of accuracy, such as a 98% rate. This approach optimizes memory usage while maintaining performance.

You can use the `halfvec` type to store half-precision vectors, as shown here:

```sql
CREATE TABLE items (id bigserial PRIMARY KEY, embedding halfvec(3));
```

## Binary vectors

Binary vector embeddings are a form of vector representation where each component is encoded as a binary digit, typically 0 or 1. For example, the word "cat" might be represented as `[0, 1, 0, 1, 1, 0, 0, 1, ...],` with each position in the vector being binary.

These embeddings are advantageous for their efficiency in both storage and computation. Because they use only one bit per dimension, binary embeddings require less memory compared to traditional embeddings that use floating-point numbers. This makes them useful when there is limited memory or when dealing with large datasets. Additionally, operations with binary values are generally quicker than those involving real numbers, leading to faster computations.

However, the trade-off with binary vector embeddings is a potential loss in accuracy. Unlike denser embeddings, which have real-valued entries and can represent subtleties in the data, binary embeddings simplify the representation. This can result in a loss of information and may not fully capture the intricacies of the data they represent.

Use the `bit` type to store binary vector embeddings:

```sql
CREATE TABLE items (id bigserial PRIMARY KEY, embedding bit(3));
INSERT INTO items (embedding) VALUES ('000'), ('111');
```

Get the nearest neighbors by Hamming distance (added in 0.7.0)

```sql
SELECT * FROM items ORDER BY embedding <~> '101' LIMIT 5;
```

Or (before 0.7.0)

```sql
SELECT * FROM items ORDER BY bit_count(embedding # '101') LIMIT 5;
```

Jaccard distance (`<%>`) is also supported with binary vector embeddings.

## Binary quantization

Binary quantization is a process that transforms dense or sparse embeddings into binary representations by thresholding vector dimensions to either 0 or 1.

Use expression indexing for binary quantization:

```sql
CREATE INDEX ON items USING hnsw ((binary_quantize(embedding)::bit(3)) bit_hamming_ops);
```

Get the nearest neighbors by Hamming distance:

```sql
SELECT * FROM items ORDER BY binary_quantize(embedding)::bit(3) <~> binary_quantize('[1,-2,3]') LIMIT 5;
```

Re-rank by the original vectors for better recall:

```sql
SELECT * FROM (
    SELECT * FROM items ORDER BY binary_quantize(embedding)::bit(3) <~> binary_quantize('[1,-2,3]') LIMIT 20
) ORDER BY embedding <=> '[1,-2,3]' LIMIT 5;
```

## Sparse vectors

Sparse vectors have a large number of dimensions, where only a small proportion are non-zero.

Use the `sparsevec` type to store sparse vectors:

```sql
CREATE TABLE items (id bigserial PRIMARY KEY, embedding sparsevec(5));
```

Insert vectors:

```sql
INSERT INTO items (embedding) VALUES ('{1:1,3:2,5:3}/5'), ('{1:4,3:5,5:6}/5');
```

The format is `{index1:value1,index2:value2}/dimensions` and indices start at 1 like SQL arrays.

Get the nearest neighbors by L2 distance:

```sql
SELECT * FROM items ORDER BY embedding <-> '{1:3,3:1,5:2}/5' LIMIT 5;
```

## Differences in behaviour between pgvector 0.5.1 and 0.7.0

Differences in behavior in the following corner cases were found during our testing of `pgvector` 0.7.0:

### Distance between a valid and NULL vector

The distance between a valid and `NULL` vector (`NULL::vector`) with `pgvector` 0.7.0 differs from `pgvector` 0.5.1 when using an HNSW or IVFFLAT index, as shown in the following examples:

**HNSW**

For the following script, comparing the `NULL::vector` to non-null vectors the resulting output changes:

```sql
SET enable_seqscan = off;

CREATE TABLE t (val vector(3));
INSERT INTO t (val) VALUES ('[0,0,0]'), ('[1,2,3]'), ('[1,1,1]'), (NULL);
CREATE INDEX ON t USING hnsw (val vector_l2_ops);

INSERT INTO t (val) VALUES ('[1,2,4]');

SELECT * FROM t ORDER BY val <-> (SELECT NULL::vector);
```

`pgvector` 0.7.0 output:

```
   val
---------
 [1,1,1]
 [1,2,4]
 [1,2,3]
 [0,0,0]
```

`pgvector` 0.5.1 output:

```
   val
---------
 [0,0,0]
 [1,1,1]
 [1,2,3]
 [1,2,4]
```

**IVFFLAT**

For the following script, comparing the `NULL::vector` to non-null vectors the resulting output changes:

```sql
SET enable_seqscan = off;

CREATE TABLE t (val vector(3));
INSERT INTO t (val) VALUES ('[0,0,0]'), ('[1,2,3]'), ('[1,1,1]'), (NULL);
CREATE INDEX ON t USING ivfflat (val vector_l2_ops) WITH (lists = 1);

INSERT INTO t (val) VALUES ('[1,2,4]');

SELECT * FROM t ORDER BY val <-> (SELECT NULL::vector);
```

`pgvector` 0.7.0 output:

```sql
   val
---------
 [0,0,0]
 [1,2,3]
 [1,1,1]
 [1,2,4]
```

`pgvector` 0.5.1 output:

```sql
   val
---------
[0,0,0]
[1,1,1]
[1,2,3]
[1,2,4]
```

### Error messages improvement for invalid literals

If you use an invalid literal value for the `vector` data type, you will now see the following error message:

```sql
SELECT '[4e38,1]'::vector;
ERROR:  "4e38" is out of range for type vector
LINE 1: SELECT '[4e38,1]'::vector;
```

## Resources

- `pgvector` source code: [https://github.com/pgvector/pgvector](https://github.com/pgvector/pgvector)
- [Vector search in Postgres](https://neon.com/guides/vector-search)
- [Building semantic search with AI embeddings, Neon, and pgvector](https://neon.com/guides/ai-embeddings-postgres-search)

--- [Document source](https://neon.com/docs/extensions/plv8.md) ---

> Summary: plv8, the Postgres extension for writing stored procedures and functions in JavaScript via the V8 engine, is deprecated on Neon and blocked from new installs due to security risks from embedding V8 inside Postgres. Use this page to understand what is blocked (CREATE EXTENSION plv8 returns a deprecation error) and what migration paths exist. Recommended alternatives include rewriting JavaScript-in-SQL logic in plpgsql or moving it to application or worker code outside the database.

# The plv8 extension (deprecated)

JavaScript procedural language for Postgres — no longer available on Neon

Last updated: 2026-06-05

**Warning: The plv8 extension is deprecated on Neon.**

**plv8** is deprecated because of **security risks** tied to embedding the V8 JavaScript engine inside Postgres. Neon blocks **`CREATE EXTENSION plv8`** with an explicit deprecation message (same mechanism as other deprecated extensions).

The **`plcoffee`** (CoffeeScript) and **`plls`** (LiveScript) extensions ship with plv8 on Postgres 14, 15, and 16 and run on the same V8 engine, so they're deprecated too. Neon also blocks **`CREATE EXTENSION plcoffee`** and **`CREATE EXTENSION plls`**. Databases that already have them keep working until you drop them.

**If you use plv8 today:** move business logic out of JavaScript-in-SQL—for example rewrite functions in **[plpgsql](https://www.postgresql.org/docs/current/plpgsql.html)** or run JavaScript in your **application** or **worker** layer—and then drop **`plv8`** from databases that still have it. See also [Supported Postgres extensions](https://neon.com/docs/extensions/pg-extensions).

**Alternatives:**

- **SQL and built-in languages:** [plpgsql](https://www.postgresql.org/docs/current/plpgsql.html) (Postgres default procedural language); [plpgsql_check](https://pgxn.org/dist/plpgsql_check/) for optional validation in CI
- **Calling external services:** use **`http`** patterns from app code, queues, or **`pg_net`** / HTTP from Postgres where appropriate for your stack

Upstream project (reference only): [plv8 on GitHub](https://github.com/plv8/plv8).

Neon previously shipped **plv8** so you could write Postgres functions in JavaScript via the V8 engine. That capability is **no longer offered** on new installs.

--- [Document source](https://neon.com/docs/extensions/postgis-related-extensions.md) ---

> Summary: PostGIS companion extensions supported by Neon (pgrouting, H3/H3_PostGIS, PostGIS SFCGAL, and PostGIS Tiger Geocoder) add network routing, hexagonal geospatial indexing, 3D solid geometry, and US address geocoding on top of the base PostGIS install. Use this page when you need geospatial capabilities beyond what PostGIS alone provides, such as Dijkstra shortest-path queries, H3 cell aggregation, ST_Extrude volume calculations, or address normalization with normalize_address. Each extension section includes a CREATE EXTENSION statement and working SQL examples.

# PostGIS-related extensions

Improve geospatial functionality with additional PostGIS extensions

Last updated: 2026-07-31

PostGIS adds support for geospatial data in PostgreSQL, providing both data types and functions to store and analyze it effectively. The Postgres ecosystem includes multiple extensions built on top of PostGIS, to further enhance its capabilities. This guide introduces you to some of these extensions supported by Neon:

- [pgrouting](https://neon.com/docs/extensions/postgis-related-extensions#pgrouting)
- [H3_PostGIS](https://neon.com/docs/extensions/postgis-related-extensions#h3-and-h3-postgis)
- [PostGIS SFCGAL](https://neon.com/docs/extensions/postgis-related-extensions#postgis-sfcgal)
- [PostGIS Tiger Geocoder](https://neon.com/docs/extensions/postgis-related-extensions#postgis-tiger-geocoder)

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

These extensions offer specialized functionality for routing, hierarchical geospatial indexing, advanced geometric operations, and geocoding. We'll explore how to enable these extensions and provide examples of common use cases.

**Note:** These extensions are open-source and can be installed on any Neon Project using the instructions below. For detailed installation instructions, please refer to the documentation for each extension.

**Version availability:**

For up-to-date information on supported versions for each extension, refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon.

## Enable the PostGIS extension

The extensions listed below typically need `PostGIS` to be installed first, or work in conjunction with it. You can enable `PostGIS` by running the following `CREATE EXTENSION` statement in the Neon **SQL Editor** or from a client such as `psql` that is connected to Neon.

```sql
CREATE EXTENSION IF NOT EXISTS postgis;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## pgrouting

`pgrouting` extends PostGIS to provide geospatial routing and network analysis functionality. It's useful for applications involving transportation networks, logistics planning, and urban mobility analysis.

### Enable the pgrouting extension

Enable the extension by running the following SQL statement:

```sql
CREATE EXTENSION IF NOT EXISTS pgrouting;
```

### Example usage

Let's consider a scenario where we need to find the shortest path between two points in a road network.

**Create a table with road network data**

```sql
-- Create a table to store road network data
DROP TABLE IF EXISTS road_network;
CREATE TABLE road_network (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    source INTEGER,
    target INTEGER,
    cost FLOAT,
    reverse_cost FLOAT,
    geom GEOMETRY(LINESTRING, 4326)
);

-- Insert sample data, representing a simplified road network
INSERT INTO road_network (name, source, target, cost, reverse_cost, geom) VALUES
    ('Main St', 1, 2, 0.5, 0.5, ST_GeomFromText('LINESTRING(-73.98 40.75, -73.97 40.75)', 4326)),
    ('Broadway', 2, 3, 0.8, 0.8, ST_GeomFromText('LINESTRING(-73.97 40.75, -73.96 40.76)', 4326)),
    ('5th Ave', 4, 5, 0.7, 0.7, ST_GeomFromText('LINESTRING(-73.97 40.77, -73.98 40.76)', 4326)),
    ('Central Park W', 5, 1, 0.9, 0.9, ST_GeomFromText('LINESTRING(-73.98 40.76, -73.98 40.75)', 4326)),
    ('3rd Ave', 2, 5, 1.3, 1.3, ST_GeomFromText('LINESTRING(-73.97 40.75, -73.98 40.76)', 4326)),
    ('Park Dr N', 4, 1, 1.4, 1.4, ST_GeomFromText('LINESTRING(-73.97 40.77, -73.98 40.75)', 4326));
```

This dataset represents a simplified road network with 6 road segments connecting 5 intersections.

**Use pgrouting to find the shortest path between nodes**

We can use pgrouting's `pgr_dijkstra` function to find the shortest path between two nodes:

```sql
SELECT
    seq,
    node,
    edge,
    route.cost,
    agg_cost,
    rn.name AS road_name
FROM pgr_dijkstra(
    'SELECT id, source, target, cost FROM road_network',
    2, -- start node
    4, -- end node
    directed := false
) AS route
LEFT JOIN road_network rn ON route.edge = rn.id
ORDER BY seq;
```

This query returns the sequence of edges that form the shortest path from node 2 to node 4.

```text
 seq | node | edge | cost | agg_cost | road_name
-----+------+------+------+----------+-----------
   1 |    2 |    1 |  0.5 |        0 | Main St
   2 |    1 |    6 |  1.4 |      0.5 | Park Dr N
   3 |    4 |   -1 |    0 |      1.9 |
```

**Use pgrouting to find alternative routes**

For navigation applications, we might need to find multiple alternative routes. We can use the `pgr_ksp` function to find the K-shortest paths between two nodes:

```sql
SELECT
    route.path_id,
    route.path_seq,
    route.node,
    route.edge,
    route.cost,
    route.agg_cost,
    rn.name AS road_name
FROM pgr_ksp(
    'SELECT id, source, target, cost, reverse_cost FROM road_network',
    1, -- start node
    4, -- end node
    2, -- number of alternative paths
    directed := false,
    heap_paths := false
) AS route
LEFT JOIN road_network rn ON route.edge = rn.id
ORDER BY route.path_id, route.path_seq;
```

This query returns two sequence of edges, that can be used to go from node 1 to node 4.

```text
 path_id | path_seq | node | edge | cost | agg_cost |   road_name
---------+----------+------+------+------+----------+----------------
       1 |        1 |    1 |    6 |  1.4 |        0 | Park Dr N
       1 |        2 |    4 |   -1 |    0 |      1.4 |
       2 |        1 |    1 |    4 |  0.9 |        0 | Central Park W
       2 |        2 |    5 |    3 |  0.7 |      0.9 | 5th Ave
       2 |        3 |    4 |   -1 |    0 |      1.6 |
```

## H3 and H3 PostGIS

H3 is a hierarchical geospatial indexing system. It divides the earth's surface into hexagonal cells at multiple resolutions, and provides a unique addressing system for location data. It is used for applications like optimizing delivery zones and service areas, geospatial aggregation, and analytics.

The H3 functionality is split into two extensions: `h3` and `h3_postgis`.

### Enable the H3 and H3_PostGIS extensions

Enable these extensions by running the following SQL statements:

```sql
CREATE EXTENSION IF NOT EXISTS h3 CASCADE;
CREATE EXTENSION IF NOT EXISTS h3_postgis CASCADE;
```

### Example usage

We will show how to use H3 to analyze ride-sharing data in a large city, focusing on the distribution of pickup locations.

**Create a table with pickup location data**

```sql
DROP TABLE IF EXISTS ride_pickups;
CREATE TABLE ride_pickups (
    id SERIAL PRIMARY KEY,
    pickup_time TIMESTAMP,
    pickup_location GEOMETRY(POINT, 4326)
);

-- Insert sample data
INSERT INTO ride_pickups (pickup_time, pickup_location) VALUES
    ('2023-06-15 08:30:00', ST_SetSRID(ST_MakePoint(-73.9812, 40.7657), 4326)),
    ('2023-06-15 09:15:00', ST_SetSRID(ST_MakePoint(-73.9815, 40.7659), 4326)),
    ('2023-06-15 10:00:00', ST_SetSRID(ST_MakePoint(-73.9810, 40.7655), 4326)),
    ('2023-06-15 11:30:00', ST_SetSRID(ST_MakePoint(-73.9934, 40.7505), 4326)),
    ('2023-06-15 12:45:00', ST_SetSRID(ST_MakePoint(-73.9937, 40.7508), 4326)),
    ('2023-06-15 14:00:00', ST_SetSRID(ST_MakePoint(-74.0060, 40.7128), 4326)),
    ('2023-06-15 15:30:00', ST_SetSRID(ST_MakePoint(-73.9619, 40.7681), 4326)),
    ('2023-06-15 17:00:00', ST_SetSRID(ST_MakePoint(-73.9622, 40.7683), 4326)),
    ('2023-06-15 18:30:00', ST_SetSRID(ST_MakePoint(-73.9840, 40.7549), 4326)),
    ('2023-06-15 20:00:00', ST_SetSRID(ST_MakePoint(-73.9887, 40.7229), 4326));
```

This dataset represents the pickup locations for a ride-sharing service in a large city.

**Convert points to H3 indexes**

We can use the `h3_lat_lng_to_cell` function to convert lat/long coordinates to H3 indexes:

```sql
SELECT
    h3_lat_lng_to_cell(pickup_location, 9) AS h3_index
FROM ride_pickups
ORDER BY RANDOM()
LIMIT 5;
```

This query converts each pickup location to an H3 index at resolution 9.

```text
    h3_index
-----------------
 892a100d2cbffff
 892a1072893ffff
 892a100d693ffff
 892a100d2cbffff
 892a100d66bffff
(5 rows)
```

**Aggregate data by H3 cells**

Let's aggregate the pickup data into H3 cells at resolution 8 (average hexagon edge length of ~461 meters) to identify hotspots:

```sql
SELECT
    h3_lat_lng_to_cell(pickup_location, 8) AS h3_index,
    COUNT(*) AS pickup_count,
    MIN(pickup_time) AS earliest_pickup,
    MAX(pickup_time) AS latest_pickup
FROM ride_pickups
GROUP BY 1
ORDER BY pickup_count DESC;
```

This query groups the dataset by the H3 index, and then provides a count of pickups, as well as the earliest and latest pickup times for each cell.

```text
    h3_index     | pickup_count |   earliest_pickup   |    latest_pickup
-----------------+--------------+---------------------+---------------------
 882a100d65fffff |            3 | 2023-06-15 08:30:00 | 2023-06-15 10:00:00
 882a100d2dfffff |            2 | 2023-06-15 11:30:00 | 2023-06-15 12:45:00
 882a100d69fffff |            2 | 2023-06-15 15:30:00 | 2023-06-15 17:00:00
 882a107289fffff |            1 | 2023-06-15 14:00:00 | 2023-06-15 14:00:00
 882a1072cbfffff |            1 | 2023-06-15 20:00:00 | 2023-06-15 20:00:00
 882a100d67fffff |            1 | 2023-06-15 18:30:00 | 2023-06-15 18:30:00
(6 rows)
```

**Compute neighbour H3 cells**

For cells with high demand, you might want to identify neighboring cells to recommend the areas to cover. The `h3_grid_disk` function can be used to fetch neighboring cells within `k` distance from the given cell:

```sql
WITH top_cell AS (
    SELECT
        h3_lat_lng_to_cell(pickup_location, 9) AS h3_index,
        COUNT(*) AS pickup_count
    FROM ride_pickups
    GROUP BY 1
    ORDER BY pickup_count DESC
    LIMIT 1
)
SELECT
    h3_cell_to_lat_lng(neighbor) AS neighbor_centroid
FROM top_cell, h3_grid_disk(h3_index, 1) AS neighbor
WHERE neighbor != h3_index;
```

This query identifies the hexagon cell for the top pickup location and then fetches the neighboring cells adjacent to it.

```text
            neighbor_centroid
-----------------------------------------
 (-73.98431385752089,40.76847107223484)
 (-73.98634907959108,40.76577167962788)
 (-73.984106944923,40.7631879413235)
 (-73.9798298121748,40.76330338643407)
 (-73.97779433265362,40.766002576302085)
 (-73.98003624329262,40.7685865237991)
(6 rows)
```

## PostGIS SFCGAL

PostGIS SFCGAL provides advanced 2D and 3D spatial operations using the SFCGAL library. It's useful for complex geometric calculations, 3D operations, and working with solid objects.

### Enable the PostGIS SFCGAL extension

Enable the extension by running the following SQL statement:

```sql
CREATE EXTENSION IF NOT EXISTS postgis_sfcgal CASCADE;
```

### Example usage

We will illustrate the use of SFCGAL to perform some urban planning tasks.

**Create a table with building data**

```sql
CREATE TABLE buildings (
    id SERIAL PRIMARY KEY,
    name TEXT,
    height FLOAT,
    footprint GEOMETRY(POLYGON, 4326)
);

-- Insert sample data (simplified for brevity)
INSERT INTO buildings (name, height, footprint) VALUES
    ('Office Tower', 100, ST_GeomFromText('POLYGON((0 0, 0 50, 30 50, 30 0, 0 0))', 4326)),
    ('Shopping Mall', 20, ST_GeomFromText('POLYGON((100 0, 100 80, 150 80, 150 0, 100 0))', 4326)),
    ('Residential Block', 45, ST_GeomFromText('POLYGON((200 0, 200 40, 240 40, 240 0, 200 0))', 4326));
```

This query creates a table to store building footprints and heights.

**Use SFCGAL to calculate volumes**

We can use SFCGAL to calculate the volume of buildings by extruding their footprints:

```sql
SELECT
    name,
    height,
    ST_Area(footprint) AS base_area,
    ST_Volume(ST_Extrude(footprint, 0, 0, height)) AS volume
FROM buildings;
```

This query calculates the volume of each building by extruding its 2D footprint to its height, and then calculating the volume of the resulting 3D object.

```text
       name        | height | base_area | volume
-------------------+--------+-----------+--------
 Office Tower      |    100 |      1500 | 150000
 Shopping Mall     |     20 |      4000 |  80000
 Residential Block |     45 |      1600 |  72000
(3 rows)
```

**Use SFCGAL to perform 3D intersection**

SFCGAL can be used to perform 3D intersections. For example, an important urban planning task is to examine how buildings might obstruct views from one another.

We can use SFCGAL to create 3D models of our buildings and then check for intersections between these models and sight lines.

```sql
WITH building_centroids AS (
    SELECT
        id,
        name,
        ST_Centroid(footprint) AS centroid
    FROM buildings
),
sight_lines AS (
    SELECT
        a.id AS id_a,
        a.name AS name_a,
        b.id AS id_b,
        b.name AS name_b,
        ST_MakeLine(a.centroid, b.centroid) AS sight_line
    FROM building_centroids a
    CROSS JOIN building_centroids b
    WHERE a.id < b.id
)
SELECT
    s.name_a,
    s.name_b,
    CASE
        WHEN EXISTS (
            SELECT 1
            FROM buildings c
            WHERE c.id NOT IN (s.id_a, s.id_b)
              AND ST_3DIntersects(
                  ST_Extrude(c.footprint, 0, 0, c.height),
                  ST_Extrude(s.sight_line, 0, 0, GREATEST(
                      (SELECT height FROM buildings WHERE id = s.id_a),
                      (SELECT height FROM buildings WHERE id = s.id_b)
                  ))
              )
        ) THEN 'Potential view obstruction'
        ELSE 'Clear view'
    END AS view_status
FROM sight_lines s;
```

This query does the following:

1. It creates 3D models of all buildings using `ST_Extrude`.
2. For each pair of buildings, it creates a line from the center of one building to the center of another, representing a potential sight line.
3. It uses `ST_3DIntersects` to check if this sight line intersects with any 3D building model (other than the buildings at the endpoints of the line).
4. If there's an intersection, it indicates a potential view obstruction.

It returns the following output:

```text
    name_a     |      name_b       |        view_status
---------------+-------------------+----------------------------
 Office Tower  | Shopping Mall     | Clear view
 Office Tower  | Residential Block | Potential view obstruction
 Shopping Mall | Residential Block | Clear view
(3 rows)
```

This example demonstrates how SFCGAL's 3D capabilities can be used to analyze spatial relationships between buildings in three dimensions, which is useful for urban planning and architectural design.

## PostGIS Tiger Geocoder

PostGIS Tiger Geocoder provides address normalization and geocoding functionality using TIGER (Topologically Integrated Geographic Encoding and Referencing) data. This extension is useful for address validation, normalization, and conversion of addresses to geographic coordinates.

### Enable the PostGIS Tiger Geocoder extension

Enable the extension by running the following SQL statement:

```sql
CREATE EXTENSION IF NOT EXISTS postgis_tiger_geocoder CASCADE;
```

### Example usage

**Use Tiger Geocoder to normalize an address**

Address normalization is crucial for ensuring consistency in address data. We can use the `normalize_address` function to standardize address formats.

```sql
WITH addresses AS (
  SELECT '123 Main St, New York, NY 10001' AS address
  UNION ALL
  SELECT '1600 Pennsylvania Avenue, Washington, DC'
  UNION ALL
  SELECT '100 Universal City Plaza, Universal City, CA 91608'
)
SELECT
    (normalize_address(address)).*
FROM addresses;
```

This query returns a normalized version of the input addresses.

```text
 address | predirabbrev |   streetname   | streettypeabbrev | postdirabbrev | internal |    location    | stateabbrev |  zip  | parsed | zip4 | address_alphanumeric
---------+--------------+----------------+------------------+---------------+----------+----------------+-------------+-------+--------+------+----------------------
     123 |              | Main           | St               |               |          | New York       | NY          | 10001 | t      |      | 123
    1600 |              | Pennsylvania   | Ave              |               |          | Washington     | DC          |       | t      |      | 1600
     100 |              | Universal City | Plz              |               |          | Universal City | CA          | 91608 | t      |      | 100
(3 rows)
```

## Conclusion

These examples provide a quick introduction to using other extensions in the PostGIS ecosystem. They can significantly expand the geospatial capabilities of your database.

For further information, refer to the official documentation for each extension.

## Resources

- [pgrouting Documentation](https://docs.pgrouting.org/)
- [H3 Postgres Reference](https://github.com/zachasme/h3-pg/blob/main/docs/api.md)
- [PostGIS SFCGAL Reference](https://postgis.net/docs/manual-dev/reference_sfcgal.html)
- [PostGIS Tiger Geocoder Documentation](https://postgis.net/docs/Extras.html#Tiger_Geocoder)

--- [Document source](https://neon.com/docs/extensions/postgis.md) ---

> Summary: PostGIS extends Postgres with GEOMETRY and GEOGRAPHY data types, spatial functions (ST_DWithin, ST_Intersects, ST_Buffer, ST_Distance), and GiST indexing for querying coordinates, polygons, and location-based data. Use this page to enable PostGIS on Neon with CREATE EXTENSION, store and query spatial data, and tune performance for large geospatial datasets. For related extensions such as pgRouting, PostGIS SFCGAL, and PostGIS Tiger Geocoder, see the PostGIS-related extensions page.

# The postgis extension

Work with geospatial data in Postgres using PostGIS

Last updated: 2026-06-05

The `postgis` extension provides support for spatial data - coordinates, maps and polygons, encompassing geographical and location-based information. It introduces new data types, functions, and operators to manage and analyze spatial data effectively.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide introduces you to the `postgis` extension - how to enable it, store and query spatial data, and perform geospatial analysis with real-world examples. Geospatial data is crucial in fields like urban planning, environmental science, and logistics.

**Note:** PostGIS is an open-source extension for Postgres that can be installed on any Neon Project using the instructions below. Detailed installation instructions and compatibility information can be found at [PostGIS Documentation](https://postgis.net/documentation/).

For information about PostGIS-related extensions, including `pgrouting`, H3_PostGIS, PostGIS SFCGAL, and PostGIS Tiger Geocoder, see [PostGIS-related extensions](https://neon.com/docs/extensions/postgis-related-extensions).

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date information.

## Enable the `postgis` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the Neon **SQL Editor** or from a client such as `psql` that is connected to Neon.

```sql
CREATE EXTENSION IF NOT EXISTS postgis;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Example usage

**Create a table with spatial data**

Suppose you're managing a city's public transportation system. You can create a table to store the locations of bus stops.

```sql
CREATE TABLE bus_stops (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255),
    location GEOGRAPHY(Point)
);
```

Here, the location column is of type `GEOGRAPHY(Point)`, which is a spatial data type provided by the `postgis` extension and used to store points on the Earth's surface.

**Inserting data**

Data can be inserted into the table using regular `INSERT` statements.

```sql
INSERT INTO bus_stops (name, location)
VALUES
    ('Main St & 3rd Ave', ST_Point(-73.935242, 40.730610)),
    ('Elm St & 5th Ave', ST_Point(-73.991070, 40.730824));
```

The `ST_Point` function is used to create a point from the specified longitude and latitude.

**Querying spatial data**

Now, we can perform spatial queries using the built-in functions provided by `PostGIS`. For example, below we try to find points within a certain distance from a reference.

Query:

```sql
SELECT name FROM bus_stops
WHERE ST_DWithin(location, ST_Point(-73.95, 40.7305)::GEOGRAPHY, 2000);
```

This query returns the following:

```text
| name               |
|--------------------|
| Main St & 3rd Ave  |
```

The `ST_DWithin` function returns true if the distance between two points is less than or equal to the specified distance (when used with the `GEOGRAPHY` type, the unit is meters).

## Spatial data types

PostGIS extends Postgres data types to handle spatial data. The primary spatial types are:

- **GEOMETRY**: A flexible type for spatial data, supporting various shapes. It models shapes in the cartesian coordinate plane. Each `GEOMETRY` value is also associated with a spatial reference system (SRS), which defines the coordinate system and units of measurement.
- **GEOGRAPHY**: Specifically designed for large-scale spatial operations on the Earth's surface, factoring in the Earth's curvature. The coordinates for a `GEOGRAPHY` shape are specified in degrees of longitude and latitude.

The actual shapes are stored as a set of coordinates. For example, a point is stored as a pair of coordinates, a line as a set of points, and a polygon as a set of lines.

## Longer example

PostGIS provides a number of other functions for spatial analysis - area, distance, intersection, and more. To illustrate, we'll create dataset representing a small set of landmarks and roads in a fictional city and run spatial queries on it.

**Creating the test dataset**

```sql
CREATE TABLE landmarks (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255),
    location GEOMETRY(Point)
);

CREATE TABLE roads (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255),
    path GEOMETRY(LineString)
);

INSERT INTO landmarks (name, location)
VALUES
    ('Park', ST_Point(100, 200)),
    ('Museum', ST_Point(200, 300)),
    ('Library', ST_Point(300, 200));

INSERT INTO roads (name, path)
VALUES
    ('Main Street', ST_MakeLine(ST_Point(100, 200), ST_Point(200, 300))),
    ('Second Street', ST_MakeLine(ST_Point(200, 300), ST_Point(300, 200)));
```

**Nearest landmark to a given point**

Finding the nearest places to a given point is a common spatial query. We can use the `ST_Distance` function to find the distance between two points and order the results by distance.

```sql
SELECT name, ST_Distance(location, ST_GeomFromText('POINT(150 250)')) AS distance
FROM landmarks
ORDER BY distance
LIMIT 1;
```

This query returns the following:

```text
| name   | distance |
|--------|----------|
| Park   | 70.7107  |
```

**Intersection of Roads**

We can use the `ST_Intersects` function to find if two roads intersect. To ensure we don't get duplicate pairs of roads, we filter out pairs where the first road has a higher `id` than the second road.

```sql
SELECT a.name, b.name
FROM roads a AS name_A, roads b AS name_B
WHERE a.id < b.id AND ST_Intersects(a.path, b.path);
```

This query returns the following:

```text
| name_A         | name_B         |
|----------------|----------------|
| Main Street    | Second Street  |
```

**Buffer zone around a landmark**

Say, the municipal council wants to create a buffer zone of 50 units around landmarks and check which roads intersect these zones. `ST_Buffer` computes an area around the given point with the specified radius.

```sql
SELECT l.name AS landmark, r.name AS road
FROM landmarks l, roads r
WHERE ST_Intersects(r.path, ST_Buffer(l.location, 50));
```

This query returns the following:

```text
| landmark | road          |
|----------|---------------|
| Park     | Main Street   |
| Museum   | Main Street   |
| Museum   | Second Street |
| Library  | Second Street |
```

**Line of Sight Between Landmarks**

To check if there's a direct line of sight (no roads intersecting) between two landmarks, we can combine two `postgis` functions.

```sql
SELECT
    'No direct line of sight' AS info
FROM
    landmarks l1, landmarks l2, roads r
WHERE
    l1.name = 'Park' AND l2.name = 'Library' AND
    ST_Intersects(ST_MakeLine(l1.location, l2.location), r.path)
LIMIT 1;
```

This query returns the following:

```text
| info                     |
|--------------------------|
| No direct line of sight  |
```

This tells us there's no direct line of sight between the Park and the Library.

## Performance considerations

When working with PostGIS, thinking about performance is crucial, especially when dealing with large datasets or complex spatial queries.

### Indexing

**GIST** (Generalized Search Tree) is the default spatial index in PostGIS. GiST indexes are well-suited for multidimensional data, like points, lines, and polygons. It can significantly improve query performance, especially for spatial search operations and joins.

```sql
CREATE INDEX spatial_index_name ON landmarks USING GIST(location);
```

### Query optimization

- **Unnecessary Casting**: `GEOMETRY` and `GEOGRAPHY` are the two primary data types in `postgis`, and a lot of functions are overloaded to work with both. However, casting between the two types can be expensive, so it's best to store data in the more frequently used type.
- **Use Appropriate Precision**: Reducing the precision of coordinates can often improve performance without significantly impacting the results.

## Conclusion

These examples provide a quick introduction to handling and analyzing spatial data in PostgresQL. We saw how to create tables with spatial data, insert data, and perform spatial queries using the `postgis` extension. It offers a powerful set of tools, with functions for calculating distances, identifying spatial relationships, and aggregating spatial data.

## Resources

- [PostGIS Documentation](https://postgis.net/documentation)
- [PostGIS Intro Workshop](https://postgis.net/workshops/postgis-intro/)

--- [Document source](https://neon.com/docs/extensions/postgres_fdw.md) ---

> Summary: The `postgres_fdw` Foreign Data Wrapper extension lets Neon databases query tables in external Postgres servers in place, using foreign servers, user mappings, and foreign tables that translate SQL queries transparently across the network. Use it when you need to join or read remote Postgres data without migrating it, such as for data residency compliance or cross-database reporting, and prefer it over `dblink` for DML support and better query planning. The extension supports SELECT, INSERT, UPDATE, and DELETE on foreign tables, but does not support `ON CONFLICT DO UPDATE`; unpooled connection strings are required when the foreign server is also a Neon database.

# The postgres_fdw extension

Access data in remote Postgres databases from Neon using postgres_fdw

Last updated: 2026-09-16

The `postgres_fdw` (Foreign Data Wrapper) extension provides a powerful and standards-compliant way to access data stored in external Postgres databases from your Neon project. For compliance or regulatory reasons, you might need to keep sensitive data on-premises or within a specific jurisdiction; `postgres_fdw` lets you query this data directly from your Neon database without migrating it, maintaining data residency. This lets you use Neon's features while adhering to data storage policies, simplifying data integration and enabling cross-database querying across different Postgres deployments.

This guide will walk you through the essentials of using the `postgres_fdw` extension in Neon. You'll learn how to enable the extension, establish connections to remote Postgres servers, define foreign tables that map to tables on those servers, and execute queries that span across your Neon database and remote instances. We will also cover important considerations for performance and security when working with `postgres_fdw`.

**Note:** `postgres_fdw` is a core Postgres extension that can be installed on any Neon project using the instructions below. It provides a standardized way to access external Postgres databases and is widely used for data integration and cross-database querying.

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Enable the `postgres_fdw` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS postgres_fdw;
```

## Key concepts

Before diving into the practical steps, let's understand the key components involved in using `postgres_fdw`:

- **Foreign server:** Represents the connection details to the external Postgres server. This includes information like the host, port, and database name of the remote server.
- **User mapping:** Defines the authentication credentials used to connect to the foreign server. This maps a local Neon user to a user on the remote server.
- **Foreign table:** A locally defined object in your Neon database that represents a table located on the foreign server. Queries against the foreign table are transparently executed on the remote server.

## Connecting to a remote Postgres database

The process of connecting to a remote Postgres database involves two main steps: creating a foreign server and setting up a user mapping.

### Create a foreign server

The `CREATE SERVER` command is used to define the connection parameters for the remote Postgres server.

```sql
CREATE SERVER my_remote_server
FOREIGN DATA WRAPPER postgres_fdw
OPTIONS (host '<remote_host>', port '<remote_port>', dbname '<remote_database>');
```

**Important:** When setting up `postgres_fdw` with a Neon database as the foreign server, make sure to use the hostname from an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string). Pooled connection strings will result in connection errors. You can find the unpooled connection string by clicking **Connect** in the Console nav and ensuring the **Connection pooling** toggle is disabled.

Replace the placeholders with the actual details of your remote Postgres server:

- `<remote_host>`: The hostname or IP address of the remote server.
- `<remote_port>`: The port number the remote Postgres server is listening on (usually 5432).
- `<remote_database>`: The name of the database on the remote server you want to access.

For example:

```sql
CREATE SERVER production_db
FOREIGN DATA WRAPPER postgres_fdw
OPTIONS (host 'db.example.com', port '5432', dbname 'analytics');
```

### Create a user mapping

The `CREATE USER MAPPING` command specifies the credentials to use when connecting to the foreign server. This maps a user in your Neon database to a user on the remote server.

```sql
CREATE USER MAPPING FOR <neon_user>
SERVER my_remote_server
OPTIONS (user '<remote_user>', password '<remote_password>');
```

Replace the placeholders with the appropriate values:

- `<neon_user>`: The username of the user in your Neon database that will be accessing the foreign server. Use `PUBLIC` if you want to allow all users to access the foreign server with the same credentials.
- `my_remote_server`: The name of the foreign server you created in the previous step.
- `<remote_user>`: The username on the remote Postgres server.
- `<remote_password>`: The password for the remote user.

For example, to map the current Neon user to the `read_only_user` user on the `production_db` server:

```sql
CREATE USER MAPPING FOR CURRENT_USER
SERVER production_db
OPTIONS (user 'read_only_user', password 'secure_password');
```

## Defining foreign tables

Once the connection to the remote server is established, you need to define foreign tables in your Neon database that correspond to the tables you want to access on the remote server. There are two primary ways to do this: creating foreign tables manually or importing the schema.

### Create foreign tables manually

The `CREATE FOREIGN TABLE` command allows you to explicitly define the structure of a remote table in your Neon database. You need to specify the column names and data types, which must match the remote table's schema.

```sql
CREATE FOREIGN TABLE <local_table_name> (
    <column1_name> <data_type>,
    <column2_name> <data_type>,
    ...
)
SERVER my_remote_server
OPTIONS (schema_name '<remote_schema>', table_name '<remote_table>');
```

Replace the placeholders with the appropriate details:

- `<local_table_name>`: The name you want to give the foreign table in your Neon database.
- `<column_name>` and `<data_type>`: The names and data types of the columns, matching the remote table.
- `my_remote_server`: The name of the foreign server you created.
- `<remote_schema>`: The schema name where the table resides on the remote server (often `public`).
- `<remote_table>`: The name of the table on the remote server.

For example, to create a foreign table named `remote_users` that maps to the `users` table in the `public` schema of the `production_db` server:

```sql
CREATE FOREIGN TABLE remote_users (
    id integer,
    username text,
    email text,
    created_at timestamp with time zone
)
SERVER production_db
OPTIONS (schema_name 'public', table_name 'users');
```

### Import foreign schema

The `IMPORT FOREIGN SCHEMA` command provides a convenient way to automatically create foreign tables for all or a subset of tables within a schema on the remote server.

```sql
IMPORT FOREIGN SCHEMA <remote_schema>
FROM SERVER my_remote_server
INTO <local_schema>;
```

- `<remote_schema>`: The name of the schema on the remote server you want to import.
- `my_remote_server`: The name of the foreign server.
- `<local_schema>`: The schema in your Neon database where the foreign tables will be created. If the schema doesn't exist, you'll need to create it first.

For example, to import all tables from the `analytics` schema of the `production_db` server into a local schema named `imported_data`:

```sql
CREATE SCHEMA IF NOT EXISTS imported_data;
IMPORT FOREIGN SCHEMA analytics
FROM SERVER production_db
INTO imported_data;
```

You can also selectively import tables using the `LIMIT TO` or `EXCEPT` clauses:

**Import specific tables:**

```sql
IMPORT FOREIGN SCHEMA analytics
LIMIT TO (users, products)
FROM SERVER production_db
INTO imported_data;
```

**Import all tables except specific ones:**

```sql
IMPORT FOREIGN SCHEMA analytics
EXCEPT (staging_table, temporary_data)
FROM SERVER production_db
INTO imported_data;
```

## Querying foreign tables

Once foreign tables are defined, you can query them using standard SQL `SELECT` statements, just like regular local tables. The `postgres_fdw` extension handles the communication with the remote server and retrieves the data transparently.

To select all the users from the `remote_users` table:

```sql
SELECT * FROM remote_users WHERE created_at > NOW() - INTERVAL '1 week';
```

You can perform joins between local tables and foreign tables, aggregate data from remote sources, and use any other SQL features supported by Postgres.

```sql
SELECT r.username, o.order_id, o.order_date
FROM remote_users r
JOIN imported_data.orders o ON r.id = o.user_id
WHERE o.order_date > '2025-01-01';
```

## Modifying data in foreign tables

`postgres_fdw` also supports data modification operations on foreign tables, including `INSERT`, `UPDATE`, and `DELETE`. However, it's important to understand the limitations and potential performance implications.

**Inserting Data:**

```sql
INSERT INTO remote_users (id, username, email) VALUES (101, 'newuser', 'new@example.com');
```

**Updating Data:**

```sql
UPDATE remote_users SET email = 'updated@example.com' WHERE id = 101;
```

**Deleting Data:**

```sql
DELETE FROM remote_users WHERE id = 101;
```

**Note:** `postgres_fdw` currently lacks full support for `INSERT` statements with an `ON CONFLICT DO UPDATE` clause. However, the `ON CONFLICT DO NOTHING` clause is supported.

## Optimizing queries with `postgres_fdw`

Querying foreign tables can sometimes be slower than querying local tables due to network latency and the overhead of communicating with the remote server. Here are some strategies to optimize performance:

- **`use_remote_estimate`:** You can instruct `postgres_fdw` to request cost estimates from the remote server. This can help the query planner make better decisions, especially for complex queries. Set this option at the server or table level:

  ```sql
  ALTER SERVER production_db OPTIONS (ADD use_remote_estimate 'true');
  ALTER FOREIGN TABLE remote_users OPTIONS (ADD use_remote_estimate 'true');
  ```

- **`ANALYZE` Foreign Tables:** Running `ANALYZE` on foreign tables collects statistics about the remote data and stores them locally. This helps the query planner generate more efficient execution plans. However, remember that these statistics can become stale if the remote data changes frequently.

  ```sql
  ANALYZE remote_users;
  ```

- **Materialized Views:** For frequently accessed data from foreign tables, consider creating materialized views in your Neon database. Materialized views store a snapshot of the remote data locally, which can significantly improve query performance. You can refresh materialized views periodically to keep the data relatively up-to-date.

  ```sql
  CREATE MATERIALIZED VIEW local_users_snapshot AS
  SELECT * FROM remote_users WHERE created_at > NOW() - INTERVAL '1 month';

  REFRESH MATERIALIZED VIEW local_users_snapshot;
  ```

- **Filtering and Projections:** When querying foreign tables, try to apply filters (`WHERE` clause) and select only the necessary columns to reduce the amount of data transferred over the network.

## Advanced `postgres_fdw` functions

The `postgres_fdw` extension provides several utility functions to manage connections established with remote Postgres servers. These functions allow you to monitor active connections and explicitly disconnect from foreign servers.

- **`postgres_fdw_get_connections()`:** This function provides insights into the active connections established by `postgres_fdw` from your current Neon session to remote servers. It returns a set of records, with each record containing the foreign server name and a boolean indicating the validity of the connection. A connection is considered invalid if the foreign server or user mapping associated with it has been changed or dropped while the connection is being used in the current transaction. Invalid connections will be closed at the end of the transaction.

  ```sql
  SELECT * FROM postgres_fdw_get_connections() ORDER BY server_name;
  ```

  The output will resemble:

  ```text
   server_name | valid
  -------------+-------
   production_db   | t
   staging_db      | f
  (2 rows)
  ```

  In this example, there are two open connections. The connection to `production_db` is valid (`t`), while the connection to `staging_db` is invalid (`f`), likely due to a change on the remote server or user mapping.

- **`postgres_fdw_disconnect(server_name text)`:** This function allows you to explicitly close open connections established by `postgres_fdw` to a specific foreign server. It takes the name of the foreign server as an argument. Note that if there are multiple connections to the same server using different user mappings, this function will attempt to disconnect all of them. If any of the connections to the specified server are currently in use within the ongoing transaction, they will not be disconnected, and warning messages will be issued. The function returns `true` if at least one connection was successfully disconnected and `false` otherwise. An error is raised if no foreign server with the given name is found.

  ```sql
  SELECT postgres_fdw_disconnect('staging_db');
  ```

  The output will be:

  ```text
   postgres_fdw_disconnect
  -------------------------
   t
  (1 row)
  ```

- **`postgres_fdw_disconnect_all()`:** This function provides a way to close all open connections established by `postgres_fdw` from your current Neon session to any foreign server. Similar to `postgres_fdw_disconnect`, connections in use within the current transaction will not be closed, and warnings will be generated. The function returns `true` if at least one connection was disconnected and `false` otherwise.

These functions offer greater control over `postgres_fdw` connections, allowing you to manage resources and ensure connections are closed when no longer needed. Using `postgres_fdw_get_connections` can be helpful for monitoring and troubleshooting connection issues, while the disconnect functions can be used for cleanup or in scenarios where you need to force a reconnection with updated credentials or server configurations.

## Security considerations

When working with `postgres_fdw`, security is paramount. Keep the following points in mind:

- **Network security:** Ensure that network access is properly configured to allow connections between your Neon project and the remote Postgres server. Firewalls and security groups might need adjustments.
- **Principle of Least Privilege:** Grant only the necessary permissions to the user mapped to the remote database. Avoid using superuser accounts for `postgres_fdw` connections.
- **SSL encryption:** Ensure that the connection to the remote Postgres server is encrypted using SSL. This is often the default behavior for Postgres connections, but it's worth verifying the configuration.

## `postgres_fdw` vs. `dblink`

While both `postgres_fdw` and `dblink` allow you to connect to remote Postgres databases, `postgres_fdw` is generally the preferred choice for the following reasons:

- **SQL standards compliance:** `postgres_fdw` adheres more closely to SQL standards for accessing external data.
- **Performance:** `postgres_fdw` often provides better performance due to its more efficient implementation.
- **Feature set:** `postgres_fdw` offers a richer feature set, including support for data modification operations and more sophisticated query planning.
- **Maintainability:** Using a standardized approach like `postgres_fdw` can lead to more maintainable and portable code.

`dblink` might be suitable for simple, one-off tasks, but for robust and scalable integration with remote Postgres databases, `postgres_fdw` is the recommended solution.

## Conclusion

The `postgres_fdw` extension is a valuable tool for Neon users who need to access and integrate data from remote Postgres databases. By establishing connections to foreign servers, defining foreign tables, and executing queries that span across local and remote databases, you can build applications that query data from multiple sources.

## Reference

- [PostgreSQL Foreign Data Wrappers](https://www.postgresql.org/docs/current/postgres-fdw.html)
- [PostgreSQL `dblink` Documentation](https://www.postgresql.org/docs/current/dblink.html)

--- [Document source](https://neon.com/docs/extensions/postgresql-anonymizer.md) ---

> Summary: The `anon` extension (PostgreSQL Anonymizer) adds static data masking and anonymization to Postgres, letting you permanently replace PII with faked, pseudonymized, randomized, or nullified values using `SECURITY LABEL` rules. Use this page when you need to enable the extension in Neon, understand its built-in masking function types, or work within its current constraint that only static masking is supported. The extension is experimental in Neon, requires `SET neon.allow_unstable_extensions='true'` before installation, and is distinct from `pg_anon`.

# The anon extension

Protecting sensitive data in Postgres databases

Last updated: 2026-06-05

The `anon` extension ([PostgreSQL Anonymizer](https://postgresql-anonymizer.readthedocs.io)) provides data masking and anonymization capabilities to protect sensitive data in Postgres databases. It helps protect personally identifiable information (PII) and other sensitive data, facilitating compliance with regulations such as [GDPR](https://gdpr-info.eu/).

**Note:** This extension comes from the [PostgreSQL Anonymizer](https://postgresql-anonymizer.readthedocs.io) open source project (`postgresql_anonymizer`). This is distinct from other tools such as `pg_anon`. The extension is installed using `CREATE EXTENSION anon`.

**Tip: Looking for a practical guide?**

For complete step-by-step workflows on anonymizing data in Neon branches, including manual procedures and GitHub Actions automation, see [data anonymization](https://neon.com/docs/workflows/data-anonymization).

## Enable the extension

**Note:** This extension is currently [experimental](https://neon.com/docs/extensions/pg-extensions#experimental-extensions) and may change in future releases.

When using the Neon Console or API for anonymization workflows, the extension is enabled automatically. It can also be enabled manually using SQL commands.

### Enable via SQL

When working with SQL-based workflows (such as using `psql` or other SQL clients), enable the `anon` extension in your Neon database by following these steps:

1. Connect to your Neon database using either the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or an SQL client like [psql](https://neon.com/docs/connect/query-with-psql-editor)

2. Enable experimental extensions:

   ```sql
   SET neon.allow_unstable_extensions='true';
   ```

3. Install the extension:

   ```sql
   CREATE EXTENSION IF NOT EXISTS anon;
   ```

**Tip:** When using the Neon Console or API to create branches, the extension is enabled automatically. See the [data anonymization workflow guide](https://neon.com/docs/workflows/data-anonymization) for details.

## Masking rules

Masking rules define which data to mask and how to mask it using SQL syntax. These rules are applied using `SECURITY LABEL` SQL commands and stored within the database schema to implement the privacy by design principle.

## Masking functions

PostgreSQL Anonymizer provides [built-in functions](https://postgresql-anonymizer.readthedocs.io/en/latest/masking_functions/) for different anonymization requirements, including but not limited to:

| Function Type      | Description                                           | Example                                                                                         |
| ------------------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Faking             | Generate realistic data                               | `anon.fake_first_name()` and `anon.lorem_ipsum()`                                               |
| Pseudonymization   | Create consistent and reversible fake data            | `anon.pseudo_email(seed)`                                                                       |
| Randomization      | Generate random values                                | `anon.random_int_between(10, 100)` and `anon.random_in_enum(enum_column)`                       |
| Partial scrambling | Hide portions of strings                              | `anon.partial(ip_address, 8, ''XXX.XXX'', 0)` would change `192.168.1.100` to `192.168.XXX.XXX` |
| Nullification      | Replace with static values or `NULL`                  | `MASKED WITH VALUE 'CONFIDENTIAL'`                                                              |
| Noise addition     | Alter numerical values while maintaining distribution | `anon.noise(salary, 0.1)` adds `+/- 10%` noise to the `salary` column                           |
| Generalization     | Replace specific values with broader categories       | `anon.generalize_int4range(age, 10)` would change `54` to `[50,60)`                             |

## Static masking

Static masking permanently modifies the original data in your tables. This approach is useful for creating anonymized copies of data when:

- Migrating production data to development branches
- Creating sanitized datasets for testing
- Archiving data with sensitive information removed
- Distributing data to third parties

### Branch operations and static masking

When using Neon's branch features with static masking:

- Creating a child branch copies all data as-is from the parent
- Resetting a branch from the parent replaces all branch data with the parent's current state
- In both cases, any previous anonymization is lost and must be reapplied

## Practical examples

For complete implementation examples showing how to apply these masking functions in real workflows, see the [data anonymization guide](https://neon.com/docs/workflows/data-anonymization), which covers:

- Creating and anonymizing development branches
- Applying different masking strategies to protect sensitive data
- Automating anonymization with GitHub Actions
- Best practices and safety tips

## Limitations

- Neon currently only supports static masking with this extension
- With static masking, branch reset operations restore original data, requiring anonymization to be run again
- Additional `pg_catalog` functions cannot be declared as `TRUSTED` in Neon's implementation

## Conclusion

This extension provides a toolkit for protecting sensitive data in Postgres databases.
By defining appropriate masking rules, you can create anonymized datasets that maintain usability while protecting individual privacy.

## Reference

- [Data anonymization workflow guide](https://neon.com/docs/workflows/data-anonymization) - Practical guide for anonymizing data in Neon branches
- [PostgreSQL Anonymizer Repository](https://gitlab.com/dalibo/postgresql_anonymizer)
- [Official Documentation](https://postgresql-anonymizer.readthedocs.io/en/latest/)
- [Masking Functions Reference](https://postgresql-anonymizer.readthedocs.io/en/latest/masking_functions/)

--- [Document source](https://neon.com/docs/extensions/tablefunc.md) ---

> Summary: The `tablefunc` PostgreSQL extension provides three functions for reshaping and traversing data: `crosstab()` pivots long-format rows into wide columns (cross-tabulation / pivot table), `normal_rand()` generates Gaussian-distributed random numbers, and `connectby()` walks parent-child hierarchies such as org charts or category trees. Use this page when you need to convert row-per-category data into a columnar summary, populate test datasets with normally distributed values, or traverse a self-referencing table without recursive CTEs. Enable the extension with `CREATE EXTENSION tablefunc` on any Lakebase Postgres database.

# The tablefunc extension

Reshape data with pivot tables and navigate hierarchical structures in Postgres

Last updated: 2026-07-31

The `tablefunc` extension for Postgres provides a powerful set of functions for transforming data directly within your database. Its primary capabilities include creating pivot tables (also known as cross-tabulations) to reshape data, generating sets of normally distributed random numbers, and querying hierarchical or tree-like data structures.

For instance, you can use `tablefunc` to transform a list of quarterly product sales into a summary table where each product is a row and each quarter is a column. Or, you could explore an employee reporting structure to visualize an organization chart.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `tablefunc` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS tablefunc;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Key functions and usage

The `tablefunc` extension provides the following key functions:

1. **`normal_rand()`**: Generates a series of random numbers following a normal (Gaussian) distribution.
2. **`crosstab()`**: Transforms data from a "long" format to a "wide" format, creating pivot tables.
3. **`connectby()`**: Traverses hierarchical data, such as organizational charts or bill-of-materials structures.

Let's explore each function in detail.

### `normal_rand()`

The `normal_rand()` function is useful for creating sample datasets that mimic real-world measurements often clustering around an average value (mean) with a certain spread (standard deviation).

**Function signature:**

```sql
normal_rand(count INTEGER, mean FLOAT8, stddev FLOAT8) RETURNS SETOF FLOAT8
```

- `count`: The number of random values to generate.
- `mean`: The central value (average) of the distribution.
- `stddev`: The standard deviation, indicating the spread of the numbers.

**Example:**

To generate 5 random numbers with a mean of 10.0 and a standard deviation of 2.0:

```sql
SELECT * FROM normal_rand(5, 10.0, 2.0);
```

**Example output:**

```
 normal_rand
-------------
  9.32020692360359
  11.495399206878934
  7.738467056884886
  9.672348520651616
  7.734973342540705
(5 rows)
```

> Output will vary each time you run the function due to the random nature of the data.

**Use case:** Populating tables with realistic-looking sample data for testing or analysis.

### `crosstab()`

The `crosstab()` function is used for reshaping data, particularly for creating pivot tables. It allows you to summarize and reorganize data by transforming rows into columns, making it easier to analyze and visualize.

#### Basic `crosstab()` (single SQL argument)

This version of `crosstab` takes a single SQL query string as input. This query must produce exactly three columns: row identifier, category, and value.

Consider a `product_sales_long` table:

| product | quarter | sales |
| :------ | :------ | :---- |
| Apple   | Q1      | 100   |
| Apple   | Q2      | 120   |
| Banana  | Q1      | 80    |
| Apple   | Q3      | 110   |
| Banana  | Q2      | 95    |

We want to transform it into:

| product | Q1\_sales | Q2\_sales | Q3\_sales |
| :------ | :-------- | :-------- | :-------- |
| Apple   | 100       | 120       | 110       |
| Banana  | 80        | 95        | (null)    |

**Query:**

```sql
CREATE TABLE product_sales_long (
  product TEXT,
  quarter TEXT,
  sales INT
);

INSERT INTO product_sales_long (product, quarter, sales) VALUES
  ('Apple', 'Q1', 100),
  ('Apple', 'Q2', 120),
  ('Banana', 'Q1', 80),
  ('Apple', 'Q3', 110),
  ('Banana', 'Q2', 95);

-- Using crosstab to pivot the product_sales_long table
SELECT *
FROM crosstab(
  'SELECT product, quarter, sales FROM product_sales_long ORDER BY 1, 2'
) AS ct(product TEXT, Q1_sales INT, Q2_sales INT, Q3_sales INT);
```

**Breaking down the query:**

1. **`crosstab('source_sql_query_as_string')`**:

   The `source_sql_query_as_string` must return three columns:

   - **Row identifier**: Values in this column become distinct rows in the output (for example, `product`).
   - **Category**: Values in this column become new column headers in the output (for example, `quarter`).
   - **Value**: Values in this column populate the cells of the new pivot table (for example, `sales`).

   Crucially, this source query **must** be sorted by the first column, then the second (`ORDER BY 1, 2`). This ensures `crosstab` processes data correctly (for example, `Q1` comes before `Q2`).

2. **`AS ct(column_definitions)`**:
   - Because `crosstab` returns a generic `SETOF record`, you must explicitly define the structure of the output table.
   - `ct`: An alias for the resulting table.
   - `product TEXT`: Corresponds to the first column of the `source_sql_query`. Its data type should match.
   - `Q1_sales INT, Q2_sales INT, Q3_sales INT`: These are the new columns derived from the unique values in the 'category' (second) column of your `source_sql_query`. Their data types must match the 'value' (third) column of the `source_sql_query`.
   - If a row identifier/category combination doesn't exist in the source data (for example, Banana for `Q3`), the corresponding cell in the pivot table will be `NULL`.
   - If the source data contains categories not defined in the `AS ct(...)` clause, those categories will be ignored.

#### `crosstab()` with fixed columns (using two SQL queries)

This version of `crosstab` is used when you know exactly which categories you want as your new columns, and you want them to appear in a specific order. It's perfect for reports where the column layout is fixed, even if some rows don't have data for every column.

Imagine you have a table of `student_test_scores`:

| student\_name | subject | score |
| :------------ | :------ | :---- |
| Alice         | Math    | 90    |
| Alice         | Science | 85    |
| Bob           | Math    | 78    |
| Alice         | English | 92    |
| Bob           | Science | 88    |
| Carol         | Math    | 95    |
| Carol         | English | 89    |

We want to transform this into a table where each student is a row, and their scores for 'Math', 'Science', 'English', and 'History' are in separate columns.

**Desired Output:**

| student\_name | math\_score | science\_score | english\_score | history\_score |
| :------------ | :---------- | :------------- | :------------- | :------------- |
| Alice         | 90          | 85             | 92             | _(null)_       |
| Bob           | 78          | 88             | _(null)_       | _(null)_       |
| Carol         | 95          | _(null)_       | 89             | _(null)_       |

> Notice we want a 'History' column even if no one has a score for it yet – it will just show `(null)`.

**Here's how we do it with `crosstab()`:**

```sql
-- Create the student_test_scores table
CREATE TABLE student_test_scores (
    student_name TEXT,
    subject TEXT,
    score INT
);

INSERT INTO student_test_scores (student_name, subject, score) VALUES
    ('Alice', 'Math', 90),
    ('Alice', 'Science', 85),
    ('Bob', 'Math', 78),
    ('Alice', 'English', 92),
    ('Bob', 'Science', 88),
    ('Carol', 'Math', 95),
    ('Carol', 'English', 89);

-- Now, the crosstab query
SELECT *
FROM crosstab(
  -- Query 1: This is our source data.
  -- It needs: row_identifier, category_for_new_columns, value_for_cells
  'SELECT student_name, subject, score
   FROM student_test_scores
   ORDER BY 1', -- IMPORTANT: Order by the row_identifier (student_name)

  -- Query 2: This query defines our new column headers, in the order we want them.
  -- It must return one column with the list of categories.
  $$SELECT s FROM unnest(ARRAY['Math', 'Science', 'English', 'History']) AS s$$
) AS ct(
    student TEXT,          -- This matches 'student_name' from Query 1
    math_score INT,        -- This matches 'Math' from Query 2
    science_score INT,     -- This matches 'Science' from Query 2
    english_score INT,     -- This matches 'English' from Query 2
    history_score INT      -- This matches 'History' from Query 2
);
```

> `unnest()` is a Postgres function that expands an array into a set of rows. In this case, it generates the list of subjects to be used as column headers in the pivot table. The `ARRAY[...]` syntax creates an array of the specified values, and `unnest()` converts it into a set of rows. This allows you to dynamically define the categories for the pivot table based on the contents of the array. Learn more about the `unnest()` function here: [Expanding an array into rows](https://neon.com/docs/data-types/array#array-functions-and-operators:~:text=Expanding%20an%20array%20into%20rows)

**How the `crosstab(source_sql, category_sql)` works:**

1. **`source_sql` (the first query string):**
   - This query fetches your raw data.
   - It must provide:
     1. The column(s) that will identify each row in your final table (here, `student_name`).
     2. The column whose values will become your new column headers (here, `subject`).
     3. The column whose values will fill the cells of your new table (here, `score`).
   - It's very important to `ORDER BY` the row identifier column(s) (for example, `ORDER BY student_name` or `ORDER BY 1`).

2. **`category_sql` (the second query string):**
   - This query's job is to produce a single column containing the exact list of categories you want as your new column headers.
   - The order of categories returned by this query determines the order of your new columns in the final pivot table.
   - In our example, `$$SELECT s FROM unnest(ARRAY['Math', 'Science', 'English', 'History']) AS s$$` provides the list: 'Math', then 'Science', then 'English', then 'History'.

3. **`AS ct(student TEXT, math_score INT, ...)`:**
   - This part defines the structure of your final output table.
   - The first column(s) here (`student TEXT`) must match the type and number of your row identifier columns from `source_sql`.
   - The following columns (`math_score INT`, `science_score INT`, etc.) must match, in order, the categories produced by `category_sql`. Their data type should match the `value` column from `source_sql` (the `score` column, which is `INT`).

This two-argument version of `crosstab` is powerful because it guarantees your output table will always have the columns 'Math', 'Science', 'English', and 'History' in that order, filling in `(null)` where a student doesn't have a score for a particular subject.

#### `crosstabN()` functions

For common scenarios where the row identifier is text and you need a fixed number of text value columns (2, 3, or 4), `tablefunc` offers `crosstab2()`, `crosstab3()`, and `crosstab4()`. These are simplified wrappers around the main `crosstab` function, providing predefined output structures for common text-based pivot tables, saving you from writing the full `AS (...)` definition.

These functions are most useful when your source query provides a text row identifier, text categories, and text values (or values castable to text). The `crosstabN` function then produces an output table with a `row_name TEXT` column and `N` additional `category_X TEXT` columns.

For instance, if you use `crosstab3()`, the output table structure will implicitly be:
`(row_name TEXT, category_1 TEXT, category_2 TEXT, category_3 TEXT)`

No explicit `AS (...)` clause is needed. Remember that the source SQL query provided to `crosstabN` must still:

1. Return three columns: `row_identifier`, `category`, `value`.
2. Be sorted using `ORDER BY 1, 2`.
3. The `value` column (third column of the source query) should be `TEXT` or cast to `TEXT`, as it populates the `category_X TEXT` output columns. The `row_identifier` (first column) also populates the `row_name TEXT` output column.

**Example using `crosstab3()`:**

Let's use our `product_sales_long` table again:

| product | quarter | sales |
| :------ | :------ | :---- |
| Apple   | Q1      | 100   |
| Apple   | Q2      | 120   |
| Banana  | Q1      | 80    |
| Apple   | Q3      | 110   |
| Banana  | Q2      | 95    |

To pivot this using `crosstab3()`, ensuring sales are treated as text for the output:

```sql
SELECT *
FROM crosstab3(
  $$SELECT product, quarter, sales::TEXT  -- Cast sales to TEXT
    FROM product_sales_long
    ORDER BY 1, 2$$  -- Important: ORDER BY row_id, category
);
```

**Expected Output:**

The output columns will be `row_name`, `category_1`, `category_2`, and `category_3`. The values from the `quarter` column (`Q1`, `Q2`, `Q3` in sorted order) will determine which `category_X` column receives the sales data.

| row\_name | category\_1 | category\_2 | category\_3 |
| :-------- | :---------- | :---------- | :---------- |
| Apple     | 100         | 120         | 110         |
| Banana    | 80          | 95          | (null)      |

**Explanation:**

- `crosstab3` automatically defines the output columns as `row_name TEXT`, `category_1 TEXT`, `category_2 TEXT`, and `category_3 TEXT`.
- The `product` column from the source query populates the `row_name` output column. The sorted `quarter` values (`Q1`, `Q2`, `Q3`) correspond to `category_1`, `category_2`, and `category_3` respectively.
- The `ORDER BY 1, 2` clause in the source query is essential for correct processing and mapping of quarter data to category columns.
- `Banana` has sales data only for `Q1` and `Q2`, so its third value column (`category_3`, corresponding to `Q3` for Banana if it existed) is `NULL`.

### `connectby()`

The `connectby()` function is designed to traverse tree-like or hierarchical data structures, such as product category trees, organizational charts, or bill-of-materials.

Consider a `product_categories` table that defines a hierarchy of product categories:

| category\_id | category\_name | parent\_category\_id |
| :----------- | :------------- | :------------------- |
| 1            | Electronics    | NULL                 |
| 2            | Computers      | 1                    |
| 3            | Laptops        | 2                    |
| 4            | Desktops       | 2                    |
| 5            | Phones         | 1                    |
| 6            | Smartphones    | 5                    |
| 7            | Books          | NULL                 |
| 8            | Fiction        | 7                    |

We want to display the hierarchy starting from the 'Electronics' category (ID 1).

**Query:**

```sql
CREATE TABLE product_categories (
  category_id INT PRIMARY KEY,
  category_name TEXT,
  parent_category_id INT
);

INSERT INTO product_categories (category_id, category_name, parent_category_id) VALUES
    (1, 'Electronics', NULL),
    (2, 'Computers', 1),
    (3, 'Laptops', 2),
    (4, 'Desktops', 2),
    (5, 'Phones', 1),
    (6, 'Smartphones', 5),
    (7, 'Books', NULL),
    (8, 'Fiction', 7);

-- Using connectby to traverse the product category hierarchy
SELECT *
FROM connectby(
  'product_categories',   -- 1. Table name
  'category_id',          -- 2. Key field column name
  'parent_category_id',   -- 3. Parent key field column name
  '1',                    -- 4. Start row's key value (for example, 'Electronics' category_id)
  0,                      -- 5. Maximum depth (0 for all levels)
  '>'                     -- 6. Branch delimiter string for the branch_path
) AS t(
    current_category_id INT, -- Output: Current item's key field
    parent_id INT,           -- Output: Parent item's key field
    level INT,               -- Output: Depth in the hierarchy (0 for start_with row)
    branch_path TEXT         -- Output: Text path from root to current item
);
```

**How `connectby()` works:**

- **Parameters:**
  1. `table_name TEXT`: Name of the table containing the hierarchy.
  2. `key_field TEXT`: Name of the column storing the unique ID for each item.
  3. `parent_key_field TEXT`: Name of the column storing the ID of the parent item.
  4. `start_with_value TEXT`: The `key_field` value of the item from which to start the traversal (must be provided as text).
  5. `max_depth INTEGER`: Maximum number of levels to traverse (0 means no limit).
  6. `branch_delimiter TEXT`: A string used to construct the `branch_path` output column.

- **Output Definition `AS t(...)`**:
  You must define the structure of the output table:
  - `key_field_alias <type>`: The key of the current item. Its data type should match the `key_field` in the source table (for example, `current_category_id INT`).
  - `parent_key_field_alias <type>`: The key of the parent item. Its data type should match the `parent_key_field` (or `key_field`) in the source table (for example, `parent_id INT`).
  - `level <INTEGER>`: The depth of the current item in the hierarchy (0 for the starting item, 1 for its direct children, and so on).
  - `branch_path <TEXT>`: If the `branch_delimiter` argument is provided to `connectby`, this column will contain a text representation of the path from the starting item to the current item, using the specified delimiter.

**Example output:**

| current\_category\_id | parent\_id | level | branch\_path |
| :-------------------- | :--------- | :---- | :----------- |
| 1                     | (null)     | 0     | 1            |
| 2                     | 1          | 1     | 1>2          |
| 3                     | 2          | 2     | 1>2>3        |
| 4                     | 2          | 2     | 1>2>4        |
| 5                     | 1          | 1     | 1>5          |
| 6                     | 5          | 2     | 1>5>6        |

- This output shows `Electronics` (ID 1) at `level` 0 with a `branch_path` of `1`.
- `Computers` (ID 2) is a sub-category of `Electronics`, at `level` 1, with `branch_path` `1>2`.
- `Laptops` (ID 3) is a sub-category of `Computers`, at `level` 2, with `branch_path` `1>2>3`, and so on.

## Important considerations

- **`crosstab()` output definition**: You must always define the output columns and their types using the `AS (...)` clause when calling `crosstab()`. The number and types of these columns must match what your pivoted data will look like.
- **`crosstab()` category ordering**: The order of columns generated by the single-argument `crosstab` depends on the `ORDER BY` clause of your source query and the natural sort order of the category values. For explicit column ordering and to ensure all desired categories appear, use the two-argument version of `crosstab`.
- **Data types**: Pay close attention to data types. The types defined in the `AS (...)` clause for `crosstab` must match the 'value' column of the source query (for the pivoted value columns) and the row identifier column(s). For `connectby`, the key and parent key alias types in the `AS t(...)` clause must match the source table's corresponding column types.

## Conclusion

The `tablefunc` extension gives you functions for reshaping and analyzing data in Postgres: `normal_rand()` for generating random numbers, `crosstab()` for pivot tables, and `connectby()` for traversing hierarchical data.

## Resources

- [PostgreSQL `tablefunc` documentation](https://www.postgresql.org/docs/current/tablefunc.html)

--- [Document source](https://neon.com/docs/extensions/timescaledb.md) ---

> Summary: The `timescaledb` extension adds time-series storage to Postgres by partitioning data into hypertables and chunks, enabling efficient querying of large timestamped datasets such as IoT sensor readings and financial data. Choose this page to install `timescaledb` on Neon, convert tables to hypertables, and run hyperfunctions like `time_bucket`, `first`, `last`, and `histogram` for time-oriented analysis. Only Apache-2 licensed features are supported on Neon; compression is not available.

# The timescaledb extension

Work with time-series data in Postgres with the timescaledb extension

Last updated: 2026-11-06

`timescaledb` enables the efficient storage and retrieval of time-series data. Time-series data is a sequential collection of observations or measurements recorded over time. For example, IoT devices continuously generate data points with timestamps, representing measurements or events. `timescaledb` is designed to handle large volumes of time-stamped data and provides SQL capabilities on top of a time-oriented data model such as IoT data, sensor readings, financial market data, and other time-series datasets.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide provides an introduction to the `timescaledb` extension. You'll learn how to enable the extension in Neon, create hypertables, run simple queries, and analyze data using `timescaledb` functions. Finally, you'll see how to delete data to free up space.

**Note:** `timescaledb` is an open-source extension for Postgres that can be installed on any Neon Project using the instructions below.

**Version availability:** For version availability, refer to our [Postgres extensions](https://neon.com/docs/extensions/pg-extensions) page, which includes a table of supported extension versions by Postgres version.

_Only [Apache-2](https://docs.timescale.com/about/latest/timescaledb-editions/) licensed features are supported. Compression is not supported._

## Enable the `timescaledb` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the Neon **SQL Editor** or from a client such as `psql` that is connected to Neon.

```sql
CREATE EXTENSION IF NOT EXISTS timescaledb;
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Create a hypertable

`timescaledb` hypertables are a high-level abstraction, extending traditional Postgres tables to manage temporal data more effectively. A hypertable simplifies the organization and retrieval of time-series information by providing built-in partitioning based on time intervals.

To begin with, create a SQL table for temperature data:

```sql
CREATE TABLE weather_conditions (
 time        TIMESTAMP WITH TIME ZONE NOT NULL,
 device_id   TEXT,
 temperature  NUMERIC,
 humidity     NUMERIC
);
```

Convert it to a hypertable using the [`create_hypertable`](https://docs.timescale.com/api/latest/hypertable/create_hypertable/) function:

```sql
SELECT create_hypertable('weather_conditions', 'time');
```

You should receive the following output:

```text
|       create_hypertable         |
|---------------------------------|
| (3,public,weather_conditions,t) |
```

It is possible to use both standard SQL commands and `timescaledb` functions (which will be covered later).

To use an SQL query to insert data in the `weather_conditions` table:

```sql
INSERT INTO weather_conditions
VALUES
   (NOW(), 'weather-pro-000002', 72.0, 52.0),
   (NOW(), 'weather-pro-000003', 71.5, 51.5),
   (NOW(), 'weather-pro-000004', 73.0, 53.2);
```

To retrieve the data by time in descending order:

```sql
SELECT * FROM weather_conditions ORDER BY time DESC;
```

You should receive the following output:

```text
|             time              |     device_id      | temperature | humidity |
|-------------------------------|--------------------|-------------|----------|
| 2024-01-15 13:30:27.464107+00 | weather-pro-000002 |      72.0   |   52.0   |
| 2024-01-15 13:30:27.464107+00 | weather-pro-000003 |      71.5   |   51.5   |
| 2024-01-15 13:30:27.464107+00 | weather-pro-000004 |      73.0   |   53.2   |
```

## Load weather data

You can use the [sample weather dataset from TimescaleDB](https://assets.timescale.com/docs/downloads/weather_small.tar.gz) and load it into your Neon database using [psql](https://neon.com/docs/connect/query-with-psql-editor).

Download the weather data:

```shell
curl https://assets.timescale.com/docs/downloads/weather_small.tar.gz -o weather_small.tar.gz

tar -xvzf weather_small.tar.gz
```

Load the data into Neon database - enter the username, password, host and database name. You can find these details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

```shell
psql 'postgresql://<username>:<password>@<host>/<database_name>?sslmode=require&channel_binding=require' -c "\COPY weather_conditions FROM weather_small_conditions.csv CSV"
```

You should receive the following output:

```text
COPY 1000000
```

## Use hyperfunctions to analyze data

You can now start using `timescaledb` functions to analyze the data.

[**first()**](https://docs.timescale.com/api/latest/hyperfunctions/first/)

Get the first temperature reading for each location:

```sql
SELECT
device_id,
first(temperature, time) AS first_temperature
FROM weather_conditions
GROUP BY device_id
LIMIT 10;
```

The aggregate function [`first`](https://docs.timescale.com/api/latest/hyperfunctions/first/) was used to get the earliest `temperature` value based on `time` within an aggregate group.

You should receive the following output:

```text
|     device_id      | first_temperature  |
|--------------------|--------------------|
| weather-pro-000000 |               39.9 |
| weather-pro-000001 |               32.4 |
| weather-pro-000002 |               39.8 |
| weather-pro-000003 |               36.8 |
| weather-pro-000004 |               71.8 |
| weather-pro-000005 |               71.8 |
| weather-pro-000006 |                 37 |
| weather-pro-000007 |                 72 |
| weather-pro-000008 |               31.3 |
| weather-pro-000009 |               84.4 |
```

[**last()**](https://docs.timescale.com/api/latest/hyperfunctions/last/)

Get the latest temperature reading for each location:

```sql
SELECT
device_id,
last(temperature, time) AS first_temperature
FROM weather_conditions
GROUP BY device_id
LIMIT 10;
```

The aggregate function [`last`](https://docs.timescale.com/api/latest/hyperfunctions/last/) was used to get the latest `temperature` value based on `time` within an aggregate group.

You should receive the following output:

```text
|     device_id      | first_temperature |
|--------------------|-------------------|
| weather-pro-000000 |                42 |
| weather-pro-000001 |                42 |
| weather-pro-000002 |              72.0 |
| weather-pro-000003 |              71.5 |
| weather-pro-000004 |              73.0 |
| weather-pro-000005 | 70.3              |
| weather-pro-000006 |                42 |
| weather-pro-000007 | 69.9              |
| weather-pro-000008 |                42 |
| weather-pro-000009 |                91 |
```

[**time_bucket()**](https://docs.timescale.com/api/latest/hyperfunctions/time_bucket/)

Calculate the average temperature per hour for a specific device:

```sql
SELECT
time_bucket('1 hour', time) AS bucket_time,
AVG(temperature) AS avg_temperature
FROM weather_conditions
WHERE device_id = 'weather-pro-000001'
GROUP BY bucket_time
ORDER BY bucket_time
LIMIT 10;
```

The query uses the [`time_bucket`](https://docs.timescale.com/api/latest/hyperfunctions/time_bucket/) hyperfunction to group timestamps into one-hour intervals, calculating the average temperature for each interval from the table for a specific device, and then displays the results for the top 10 intervals.

You should receive the following output:

```text
|      bucket_time       |   avg_temperature   |
|------------------------|---------------------|
| 2016-11-15 12:00:00+00 | 32.76               |
| 2016-11-15 13:00:00+00 | 33.60               |
| 2016-11-15 14:00:00+00 | 34.83               |
| 2016-11-15 15:00:00+00 | 36.26               |
| 2016-11-15 16:00:00+00 | 37.19               |
| 2016-11-15 17:00:00+00 | 38.12               |
| 2016-11-15 18:00:00+00 | 39.02               |
| 2016-11-15 19:00:00+00 | 40.03               |
| 2016-11-15 20:00:00+00 | 40.87               |
| 2016-11-15 21:00:00+00 | 41.93               |
```

[**histogram()**](https://docs.timescale.com/api/latest/hyperfunctions/histogram/)

Bucket device humidity data:

```sql
SELECT device_id, histogram(humidity, 40, 60, 5)
FROM weather_conditions
GROUP BY device_id
LIMIT 10;
```

Here, we use the [`histogram`](https://docs.timescale.com/api/latest/hyperfunctions/histogram/) function to create a distribution of humidity values within specified buckets (`40` to `60` with a size of `5`) for each `device_id`.

You should receive the following output:

```text
|     device_id      |      histogram      |
|--------------------|---------------------|
| weather-pro-000000 | {0,0,0,710,290,0,0} |
| weather-pro-000001 | {0,0,0,805,186,9,0} |
| weather-pro-000002 | {0,0,0,217,784,0,0} |
| weather-pro-000003 | {0,0,0,510,491,0,0} |
| weather-pro-000004 | {0,0,0,1000,1,0,0} |
| weather-pro-000005 | {0,0,0,1000,0,0,0} |
| weather-pro-000006 | {0,0,0,999,1,0,0}  |
| weather-pro-000007 | {0,0,0,1000,0,0,0} |
| weather-pro-000008 | {0,0,0,834,166,0,0} |
| weather-pro-000009 | {0,0,0,0,0,0,1000} |
```

[**approximate_row_count()**](https://docs.timescale.com/api/latest/hyperfunctions/approximate_row_count/)

Use the [`approximate_row_count`](https://docs.timescale.com/api/latest/hyperfunctions/approximate_row_count/) function to get the approximate number of rows in `weather_conditions` hypertable:

```sql
SELECT approximate_row_count('weather_conditions');
```

You should receive the following output:

```text
| approximate_row_count |
|-----------------------|
|             1000000   |
```

## Working with chunks

Chunks are fundamental storage units within hypertables. Instead of storing the entire time-series dataset as a single monolithic table, `timescaledb` breaks it down into smaller, manageable chunks. Each chunk represents a distinct time interval, making data retrieval and maintenance more efficient.

[**show_chunks()**](https://docs.timescale.com/api/latest/hypertable/show_chunks/)

The [`show_chunks`](https://docs.timescale.com/api/latest/hypertable/show_chunks/) function can be used to understand the underlying structure and organization of your time-series data and provides insights into how your hypertable is partitioned.

```sql
SELECT show_chunks('weather_conditions');
```

You should receive the following output:

```text
|               show_chunks               |
|-----------------------------------------|
| _timescaledb_internal._hyper_7_24_chunk |
| _timescaledb_internal._hyper_7_25_chunk |
```

`show_chunks` output indicates the presence of two internal chunks within your hypertable. To show detailed chunks information:

```sql
SELECT * FROM chunks_detailed_size('weather_conditions') ORDER BY chunk_name;
```

You should receive the following output:

```text
|     chunk_schema      |    chunk_name     | table_bytes | index_bytes | toast_bytes | total_bytes | node_name |
|-----------------------|-------------------|-------------|-------------|-------------|-------------|-----------|
| _timescaledb_internal | _hyper_7_24_chunk |        8192 |       16384 |        8192 |       32768 |           |
| _timescaledb_internal | _hyper_7_25_chunk |    82190336 |     8249344 |        8192 |    90447872 |           |
```

[**drop_chunks()**](https://docs.timescale.com/api/latest/hypertable/drop_chunks/)

You can use the [`drop_chunks`](https://docs.timescale.com/api/latest/hypertable/drop_chunks/) function to remove data chunks whose time range falls completely before (or after) a specified time.

```sql
SELECT drop_chunks('temperature_data', INTERVAL '1 days');
```

It returns a list of the chunks that were dropped.

You should receive the following output:

```text
|               drop_chunks               |
|-----------------------------------------|
| _timescaledb_internal._hyper_4_19_chunk |
| _timescaledb_internal._hyper_4_20_chunk |
```

## Data deletion

You may run into space concerns as data accumulates in timescaledb hypertables. While Neon's Postgres service does not support compression, deleting old data is an option if you don't need to hold on to it for long periods of time.

You can use the [`drop_chunks`](https://docs.timescale.com/api/latest/hypertable/drop_chunks/#:~:text=drop_chunks\(\),always%20before%20the%20end%20time.) function outlined above to easily delete outdated chunks from a hypertable. For example, to delete all chunks older than 3 months:

```sql
SELECT drop_chunks('temperature_data', INTERVAL '3 months');
```

The query deletes any chunks that contain only data older than 3 months.

To automatically run this deletion periodically, you can setup a cron task. For example, adding this line to the crontab will run the deletion query every day at 1AM:

```sql
0 1 * * * psql -c "SELECT drop_chunks('temperature_data', INTERVAL '3 months')"
```

**Note:** Please be aware that Neon's [Scale to Zero](https://neon.com/docs/guides/scale-to-zero-guide) feature may affect the running of scheduled jobs. It may be necessary to start the compute before running a job.

This will help ensure the hypertable size is managed by deleting old unneeded data. Tune the interval passed to drop_chunks and the cron schedule based on your data retention needs.

## Conclusion

You were able to configure the timescaledb extension in Neon and create a hypertable to store `weather` data. Then you executed simple queries and analyzed data using a combination of standard SQL and `timescaledb` functions before finally using `drop_chunks()` to delete data.

## Reference

- [TimescaleDB editions](https://docs.timescale.com/about/latest/timescaledb-editions/)
- [TimesscaleDB hyperfunctions](https://docs.timescale.com/api/latest/hyperfunctions/)
- [Timeseries data in Postgres](https://neon.com/guides/timeseries-data)

--- [Document source](https://neon.com/docs/extensions/unaccent.md) ---

> Summary: The `unaccent` extension is a Postgres text search dictionary that strips accent marks and diacritical characters from text strings, enabling accent-insensitive comparisons, ILIKE searches, and full-text search configurations. Use it when multilingual users search without consistent accent usage, such as typing "cafe" to find "café", so queries return relevant results regardless of diacritic variations. Creating indexes on `unaccent()` requires an IMMUTABLE wrapper function; on Neon, customizing `unaccent.rules` requires opening a support ticket.

# The unaccent extension

Remove accents and diacritics for effective text searching in Postgres

Last updated: 2026-06-05

The `unaccent` extension for Postgres enables handling of text data in a more user-friendly and language-tolerant way. It allows you to remove [accents/stress](https://en.wikipedia.org/wiki/Stress_\(linguistics\)) ([diacritic signs](https://en.wikipedia.org/wiki/Diacritic)) from text strings, making it easier to perform searches and comparisons that are insensitive to accents. Use it in multilingual applications where users might not consistently use accents when typing search queries.

Imagine a user searching for "Hôtel" but only typing "Hotel". Without `unaccent`, the database might not find the intended results. With `unaccent`, you can ensure that searches are more forgiving and return relevant results regardless of accent variations.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide will walk you through the essentials of using the `unaccent` extension. You'll learn how to enable the extension on Neon, understand its key concepts, use it in queries, optimize performance with indexing, and consider its limitations.

## Enable the `unaccent` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS unaccent;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## Removing accents with `unaccent()`

The primary function provided by the `unaccent` extension is `unaccent()`. This function takes a text input and returns the same text with accents removed.

Let's see it in action with a few examples:

```sql
SELECT unaccent('Hôtel');
-- Hotel

SELECT unaccent('cliché');
-- cliche

SELECT unaccent('naïve');
-- naive

SELECT unaccent('café');
-- cafe

SELECT unaccent('Déjà vu');
-- Deja vu
```

As you can see, `unaccent()` effectively strips the diacritics, transforming words with accents into their unaccented counterparts. This transformation is based on a set of rules that are configurable, allowing for customization to suit specific language needs.

## Practical usage examples

`unaccent` is most commonly used to enhance text searching, making it more forgiving and user-friendly. Let's explore some typical use cases:

### Basic accent-insensitive searching

Imagine you have a product catalog and want users to be able to search for products regardless of whether they use accents or not. For instance, a user might search for "cafe" or "café" and expect to find products containing "café".

Consider a `products` table with the following data:

```sql
CREATE TABLE products (
  id SERIAL PRIMARY KEY,
  name TEXT
);

INSERT INTO products (name) VALUES
  ('cafe'),
  ('café'),
  ('Café'),
  ('Café au lait');
```

Without `unaccent`, a simple `WHERE` clause would differentiate between accented and unaccented characters:

```sql
SELECT * FROM products WHERE name = 'café';
```

```
id  | name
----|------
 2  | café
```

```sql
SELECT * FROM products WHERE name = 'cafe';
```

```
id  | name
----|------
 1  | cafe
```

By applying `unaccent()` to both the column and the search term, you can achieve accent-insensitive matching:

```sql
SELECT * FROM products WHERE unaccent(name) = unaccent('cafe');
```

```
id | name
---|------
 1 | cafe
 2 | café
```

### Case-insensitive and accent-insensitive searching with `ILIKE`

For even more flexible searching, you can combine `unaccent()` with the [`ILIKE`](https://neon.com/postgresql/postgresql-tutorial/postgresql-like#postgresql-extensions-of-the-like-operator) operator for case-insensitive and accent-insensitive searches. This comes in handy for free-text search scenarios.

```sql
SELECT * FROM product WHERE unaccent(name) ILIKE unaccent('%cafe%');
```

```
id | name
---+------
 1 | cafe
 2 | café
 3 | Café
 4 | Café au lait
```

In this example, `ILIKE` handles case-insensitivity (matching 'cafe', 'Cafe', etc.), and `unaccent()` ensures that accents are ignored during the comparison. Applying `unaccent()` to both sides of the `ILIKE` condition is crucial for this to work effectively.

### Integration with Full-Text search

While `unaccent()` can be used directly in `WHERE` clauses, its true power for search applications is realized when integrated into with Postgres full-text search capabilities. `unaccent` is designed as a text search dictionary. By incorporating it into your text search configurations, you can ensure that indexing and searching operations automatically handle accent removal.

This involves creating or modifying text search configurations to include the `unaccent` dictionary in the analysis process. When text is indexed and queried using such a configuration, accents are automatically stripped, leading to efficient and accent-insensitive full-text searches.

**Note: Configuration Modifications in Neon**

It's important to note that because `unaccent` is managed by Neon, modifying the default `unaccent.rules` file or other configuration settings requires administrative privileges that are not available to Neon users.  If you have specific needs for customized `unaccent` rules or configurations, please [open a support ticket](https://console.neon.tech/app/projects?modal=support) to discuss your requirements with Neon support.

## Performance and Indexing Considerations

Using `unaccent()` in queries can have performance implications, especially in large tables. Applying functions in `WHERE` clauses often prevents the database from efficiently using standard indexes.

### Indexing with `unaccent()`

Directly indexing an expression like `unaccent(column)` typically doesn't work efficiently because, by default, `unaccent()` is not marked as an `IMMUTABLE` function. Postgres requires functions used in index expressions to be `IMMUTABLE` to guarantee consistent index usage.

To enable indexing with `unaccent()`, you can create an `IMMUTABLE` wrapper function around it. This wrapper function essentially tells Postgres that the function's output will always be the same for a given input, allowing it to be used in index expressions.

Here's an example of creating an `IMMUTABLE` wrapper function:

```sql
CREATE OR REPLACE FUNCTION f_unaccent(text) RETURNS text
AS $$
  SELECT public.unaccent('public.unaccent', $1);
$$ LANGUAGE sql IMMUTABLE PARALLEL SAFE STRICT;
```

**Explanation:**

- `CREATE OR REPLACE FUNCTION f_unaccent(text) RETURNS text`: This defines a new function named `f_unaccent` that takes text as input and returns text.
- `AS $$ ... $$ LANGUAGE sql IMMUTABLE PARALLEL SAFE STRICT`: This is the function body, written in SQL, and the important part is declaring it `IMMUTABLE`.
- `SELECT public.unaccent('public.unaccent', $1);`: Inside the wrapper, we are calling the original `unaccent` function, making sure to schema-qualify it as `public.unaccent` for robustness.

Once you have this `IMMUTABLE` wrapper function, you can create indexes on it:

```sql
CREATE INDEX idx_products_name_unaccent ON products (f_unaccent(name));
```

Now, queries using `f_unaccent(name)` in the `WHERE` clause can use this index, significantly improving performance for accent-insensitive searches.

```sql
SELECT * FROM products WHERE f_unaccent(name) = f_unaccent('cafe');
-- This query can now use the 'idx_products_name_unaccent' index
```

**Alternative: Generated columns**

Another strategy for optimizing performance is to use generated columns. You can add a new column to your table that stores the unaccented version of your text data. This column can then be indexed directly and queried efficiently.

```sql
ALTER TABLE products ADD COLUMN name_unaccented text
GENERATED ALWAYS AS (f_unaccent(name)) STORED;

CREATE INDEX idx_products_name_unaccent_generated ON products (name_unaccented);

SELECT * FROM products WHERE name_unaccented = 'cafe';
-- This query will use the 'idx_products_name_unaccent_generated' index to find rows where unaccented 'name' matches 'cafe'
```

Generated columns add storage overhead but can offer performance benefits for read-heavy workloads.

## Limitations

While `unaccent` is very useful, it's important to be aware of its limitations:

- **Rule-based:** `unaccent` operates based on a predefined set of rules defined in its configuration file (`unaccent.rules`). The effectiveness of accent removal depends on the completeness and accuracy of these rules for your target languages.
- **Language specificity:** The default rules are primarily geared towards European languages. For languages with different diacritic systems or complex character transformations, the default rules might not be sufficient, and customization of the `unaccent.rules` file might be required.
- **No contextual understanding:** `unaccent` performs a character-by-character transformation based on its rules. It does not understand the context or meaning of words. In some cases, this might lead to over-simplification or loss of subtle distinctions in meaning that accents might convey in certain languages.

## Conclusion

The `unaccent` extension is a valuable tool for handling text data in Postgres, especially in multilingual applications where accent-insensitive searching is essential. By enabling `unaccent`, you can ensure that your database is more user-friendly and tolerant of accent variations in search queries.

## Resources

- [`unaccent` Extension in PostgreSQL Documentation](https://www.postgresql.org/docs/current/unaccent.html)

--- [Document source](https://neon.com/docs/extensions/uuid-ossp.md) ---

> Summary: The `uuid-ossp` Postgres extension provides UUID generation functions for time-based, multicast, MD5 name-based, random, and SHA-1 name-based variants, plus nil and namespace constants. Use it over the built-in `gen_random_uuid()` when you need deterministic name-based UUIDs or time-ordered primary keys for distributed systems. Privacy trade-offs for v1 MAC-address embedding, index fragmentation from random v4 UUIDs, and storage costs are also covered.

# The uuid-ossp extension

Generate Universally Unique Identifiers (UUIDs) in your Postgres database

Last updated: 2026-06-05

The `uuid-ossp` extension provides a suite of functions for generating Universally Unique Identifiers (UUIDs) directly within your Postgres database. UUIDs are essential for ensuring data uniqueness across distributed systems and are widely used as primary keys and for various other applications requiring unique IDs. This extension offers a variety of UUID generation methods, including time-based, random, and name-based UUIDs, providing flexibility for different use cases.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide provides an introduction to the `uuid-ossp` extension. You'll learn how to enable the extension on Neon, explore the functions for generating different types of UUIDs, understand common use cases where UUIDs are beneficial, and consider important aspects like performance and security.

**Note:** `uuid-ossp` is a widely-used Postgres extension that offers a range of UUID generation methods beyond the basic built-in functions. It is particularly valuable when you need specific types of UUIDs or require deterministic, name-based UUIDs for consistent identifiers.

## Enable the `uuid-ossp` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

## UUID Functions

The `uuid-ossp` extension offers a range of functions for generating UUIDs, each with unique characteristics. Let's explore each function in detail:

### Version 1 UUIDs (time-based)

The version 1 UUID generation functions in `uuid-ossp` are based on the time of creation and the MAC address of the generating machine. These UUIDs are suitable for scenarios where time-based ordering is important, and uniqueness across distributed systems is required.

- `uuid_generate_v1()`:

  The `uuid_generate_v1()` function generates UUIDs based on the [version 1 algorithm](https://datatracker.ietf.org/doc/html/rfc4122#section-4.2.2). Version 1 UUIDs are time-based, meaning they incorporate the current timestamp and the MAC address of the computer where the UUID is generated. This approach uses hardware identifiers and precise timestamps to create UUIDs that are likely to be unique across different systems and over time.

  ```sql
  SELECT uuid_generate_v1();
  -- 506a753c-02fe-11f0-9122-6f83fcb8d092 (example output)
  ```

  **Important: Privacy and Security Considerations for Version 1 UUIDs**

  It's crucial to be aware that Version 1 UUIDs embed the MAC address of the generating computer. This can present privacy and security concerns because:

  - **Machine identification:** The MAC address can potentially be used to identify the specific machine that generated the UUID, raising privacy issues if this information should remain confidential.
  - **Predictability:** The time component and the structure of Version 1 UUIDs make them somewhat predictable, which could be a security risk in certain applications where UUIDs are used for security-sensitive purposes.

  If privacy or predictability is a concern, consider using `uuid_generate_v1mc()` or version 4 UUIDs instead which are discussed below.

- **`uuid_generate_v1mc()`: Version 1 UUIDs with multicast MAC address**

  The `uuid_generate_v1mc()` function is similar to `uuid_generate_v1()` but addresses the privacy concerns by using a randomly generated multicast MAC address instead of the actual MAC address of the computer.

  ```sql
  SELECT uuid_generate_v1mc();
  -- 8b119520-02ff-11f0-9d55-6761ef62a796 (example output)
  ```

### Version 3 UUIDs (name-based, MD5 hash)

- `uuid_generate_v3(namespace uuid, name text)`:

  The `uuid_generate_v3(namespace uuid, name text)` function generates version 3 UUIDs. These UUIDs are name-based and deterministic, meaning they are generated by hashing an input `name` using the [MD5 algorithm](https://en.wikipedia.org/wiki/MD5) within a specified `namespace`. For the same `namespace` UUID and input `name`, this function will always produce the exact same UUID.

  ```sql
  SELECT uuid_generate_v3(uuid_ns_url(), 'https://example.com');
  -- 68794df6-5e20-385f-ab08-bb73f8a433cb (always the same for 'https://example.com')
  ```

  Here, `uuid_ns_url()` is a predefined UUID constant representing the URL namespace, which is used as the `namespace` argument for generating UUIDs based on URLs.

  Available predefined namespace UUIDs are discussed in the [UUID Constants](https://neon.com/docs/extensions/uuid-ossp#uuid-constants) section below.

  **Use cases:**

  - Generating consistent identifiers for entities based on a name, such as creating a UUID for a URL, DNS name, or any other string identifier.
  - Scenarios where you need to ensure that generating a UUID for the same entity (identified by name within a namespace) always results in the same UUID across different systems or over time.
  - Content Management Systems where stable identifiers for content pieces are required, regardless of access time or location.

### Version 4 UUIDs (random)

- `uuid_generate_v4()`:

  The `uuid_generate_v4()` function generates version 4 UUIDs, which are derived entirely from random numbers. These are the most common type of UUIDs due to their simplicity and strong guarantee of uniqueness. Postgres also provides the built-in function [`gen_random_uuid()`](https://neon.com/postgresql/postgresql-tutorial/postgresql-uuid#generating-uuid-values) which is functionally equivalent to `uuid_generate_v4()`.

  ```sql
  SELECT uuid_generate_v4();
  -- 08e776b5-0652-431e-a841-5840616b500b (example output)
  ```

  **Key characteristics of Version 4 UUIDs:**

  - **Randomly generated:** Based on high-quality random number generators.
  - **High uniqueness probability:** Extremely low probability of collision, making them suitable for most applications requiring unique identifiers.

  **Use Cases:**

  - General-purpose unique identifiers where predictability or specific ordering is not required.
  - Primary keys for database tables, especially in distributed systems.
  - Identifying records in systems where high randomness and uniqueness are paramount.
  - Simplifying UUID generation when deterministic or time-based approaches are not necessary.

### Version 5 UUIDs (name-based, SHA-1 hash)

- `uuid_generate_v5(namespace uuid, name text)`:

  The `uuid_generate_v5(namespace uuid, name text)` function is similar to `uuid_generate_v3()` but uses the [SHA-1 hashing algorithm](https://en.wikipedia.org/wiki/SHA-1) instead of MD5. Version 5 UUIDs are also name-based and deterministic, producing the same UUID for the same input namespace and name.

  ```sql
  SELECT uuid_generate_v5(uuid_ns_dns(), 'example.com');
  -- cfbff0d1-9375-5685-968c-48ce8b15ae17 (always the same for 'example.com')
  ```

  **Tip: Version 3 vs. Version 5 UUIDs**

  While both Version 3 and Version 5 provide deterministic, name-based UUIDs, Version 5 is generally recommended due to the use of SHA-1 hashing, which is considered more secure than MD5. If security is a significant concern for your application, Version 5 is the better choice.

### UUID constants

`uuid-ossp` also provides functions to return predefined UUID constants. These are the standard namespace identifiers used for Version 3 and Version 5 UUID generation:

- **`uuid_nil()`: The Nil UUID constant**

  The `uuid_nil()` function returns the predefined "nil" UUID constant: `'00000000-0000-0000-0000-000000000000'`.

  ```sql
  SELECT uuid_nil();
  ```

  **Purpose of the Nil UUID:**

  - **Representing absence:** Similar to `NULL` for other data types, the nil UUID is often used to indicate the absence of a UUID value or as a default placeholder.
  - **Special value:** It does not correspond to any real-world generated UUID and is a specific, non-existent UUID value for particular use cases.

  **Use cases:**

  - Initializing UUID columns when a valid UUID is not yet available.
  - Using it as a sentinel value in code or database operations to represent "no UUID".

- **Namespace UUID constants (`uuid_ns_dns()`, `uuid_ns_url()`, `uuid_ns_oid()`, `uuid_ns_x500()`):**

  These functions return constant UUIDs that are specifically designated as namespaces for different identifier types, as per the UUID specification. They are intended to be used as the `namespace` argument in `uuid_generate_v3()` and `uuid_generate_v5()` functions.

  - `uuid_ns_dns()`

    Represents the DNS namespace, intended for generating UUIDs from DNS names.

    ```sql
    SELECT uuid_generate_v5(uuid_ns_dns(), 'example.com');
    -- cfbff0d1-9375-5685-968c-48ce8b15ae17 (always the same for 'example.com')
    SELECT uuid_generate_v3(uuid_ns_dns(), 'example.com');
    -- 9073926b-929f-31c2-abc9-fad77ae3e8eb (always the same for 'example.com')
    ```

  - `uuid_ns_url()`

    Represents the URL namespace, for generating UUIDs from URLs.

    ```sql
    SELECT uuid_generate_v3(uuid_ns_url(), 'https://example.com');
    -- 68794df6-5e20-385f-ab08-bb73f8a433cb (always the same for 'https://example.com')
    ```

  - `uuid_ns_oid()`

    Represents the ISO Object Identifier (OID) namespace. Note that these OIDs refer to the ASN.1 standard and are distinct from PostgreSQL's internal OIDs.

    ```sql
    SELECT uuid_generate_v5(uuid_ns_oid(), '12345');
    -- bf547c8b-0674-5afe-97ad-d6e7556e56fa (always the same for '12345')
    ```

  - `uuid_ns_x500()`

    Represents the X.500 Distinguished Name (DN) namespace.

    ```sql
    SELECT uuid_generate_v5(uuid_ns_x500(), 'CN=John Doe, DC=example, DC=com');
    -- e9ba549f-a675-5490-b054-ad862cb8c1d2 (always the same for 'CN=John Doe, DC=example, DC=com')
    ```

  **Usage of namespace UUID constants:**

  These constants are crucial for generating deterministic UUIDs based on specific namespaces, ensuring consistent UUIDs for the same input name across different systems.

## Performance and storage considerations

While UUIDs offer significant advantages, it's important to be aware of potential performance and storage implications:

- **Storage size:** UUIDs are 128-bit values (16 bytes), which are larger than typical integer primary keys (4 bytes for `integer`, 8 bytes for `bigint`). This increased size can lead to higher storage requirements, especially in tables with a very large number of rows.

- **Indexing performance:** Randomly generated UUIDs (version 4) can lead to less efficient indexing compared to sequential integer IDs. Inserting rows with random UUIDs as primary keys can cause index fragmentation, as new entries are inserted at random locations in the index. This can slow down write operations and potentially affect read query performance, especially in very large tables and under high write loads. However, using sequential or time-ordered UUIDs (like version 1) can mitigate this issue.

## Conclusion

The `uuid_ossp` extension is a valuable tool for UUID generation in Postgres. It offers diverse functions for creating UUIDs tailored to various needs: random, name-based, or time-based.

To effectively use `uuid_ossp`, remember these key recommendations:

- **For general use, version 4 UUIDs (`uuid_generate_v4()` or `gen_random_uuid()`) are ideal for random unique IDs.**
- **For deterministic IDs, choose version 5 (`uuid_generate_v5()`) over version 3 (`uuid_generate_v3()`) for better security.**
- **Use version 1 UUIDs (`uuid_generate_v1()` or `uuid_generate_v1mc()`) only when time-based ordering is essential, keeping privacy implications in mind.**

By selecting the appropriate UUID version based on your requirements, you can ensure the uniqueness and consistency of identifiers in your Postgres database.

## Resources

- [`uuid-ossp` on PostgreSQL Documentation](https://www.postgresql.org/docs/current/uuid-ossp.html)
- [RFC 4122 - A Universally Unique IDentifier (UUID) URN Namespace](https://www.rfc-editor.org/rfc/rfc4122)

--- [Document source](https://neon.com/docs/extensions/wal2json.md) ---

> Summary: wal2json is a Postgres logical decoding output plugin, pre-installed in Neon, that decodes Write-Ahead Log (WAL) changes into JSON for CDC pipelines, auditing, and event-driven architectures. Use this page when you need to capture INSERT, UPDATE, and DELETE events as structured JSON using a replication slot, choosing between format version 1 (one JSON object per transaction) or version 2 (one JSON object per row). The page also covers enabling logical replication in Neon, REPLICA IDENTITY settings for tables without primary keys, and replication slot management.

# The wal2json plugin

Convert Postgres Write-Ahead Log (WAL) changes to JSON format

Last updated: 2026-10-09

The `wal2json` plugin is a logical replication decoding output plugin for Postgres. It lets you convert the Write-Ahead Log (WAL) changes into JSON format, making it easier to consume and process database changes in various applications, such as data replication, auditing, event-driven services, and real-time analytics.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide describes the `wal2json` plugin — how to enable it in Neon, configure its output, and use it to capture and process database changes in JSON format. WAL decoding is crucial for building robust data pipelines, implementing Change Data Capture (CDC) systems, and maintaining data consistency across distributed systems.

**Note:** The `wal2json` plugin is included in your Neon project and doesn't require a separate installation.

**Version availability:**

The `wal2json` plugin is available in all Postgres versions supported by Neon. For the most up-to-date information on supported versions, please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon.

## Enable logical replication

Before using the `wal2json` plugin, you need to enable logical replication for your Neon project. In the Neon Console, go to your project's **Settings** > **Postgres** page, find **Logical Replication**, and click **Enable**.

**Note:** Once enabled for a project, logical replication cannot be reverted. This action triggers a restart of all active compute endpoints in your Neon project. Any active connections will be dropped and have to reconnect.

To verify that logical replication is enabled, navigate to the `SQL Editor` and verify the output of the following query:

```sql
SHOW wal_level;

 wal_level
-----------
 logical
(1 row)
```

For information about using the Neon SQL Editor, see [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). For information about using the `psql` client with Neon, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Create a replication slot

To start using `wal2json`, you first need to create a replication slot that explicitly specifies `wal2json` as the decoder plugin. You can do this by running the following query:

```sql
SELECT 'start' FROM pg_create_logical_replication_slot('test_slot', 'wal2json');
```

This creates a replication slot named `test_slot` using the `wal2json` plugin. Now, we can query this slot to listen for changes to any tables in the database.

## Example - use `wal2json` to capture changes to a table

Suppose we have a table named `inventory` that stores information about products for a retail store. We want to capture changes to this table in real-time and process them using `wal2json`.

Run the following query to create the `inventory` table, and insert some sample data:

```sql
CREATE TABLE inventory (
    id SERIAL PRIMARY KEY,
    product_name VARCHAR(100),
    quantity INTEGER,
    last_updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO inventory (product_name, quantity) VALUES
    ('Widget A', 100),
    ('Gadget B', 50),
    ('Gizmo C', 75);
```

With logical decoding enabled, Postgres streams changes to the `inventory` table to the `test_slot` replication slot. Run the following query to observe the messages that have been published to it:

```sql
SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'pretty-print', 'on');
```

This query returns the changes in JSON format. Each change will be represented as a separate JSON object.

```plaintext
    lsn    | xid  |                                                          data
-----------+------+-------------------------------------------------------------------------------------------------------------------------
 0/24E7950 | 2055 | {                                                                                                                      +
           |      |         "change": [                                                                                                    +
           |      |         ]                                                                                                              +
           |      | }
 0/24E7D60 | 2056 | {                                                                                                                      +
           |      |         "change": [                                                                                                    +
           |      |                 {                                                                                                      +
           |      |                         "kind": "insert",                                                                              +
           |      |                         "schema": "public",                                                                            +
           |      |                         "table": "inventory",                                                                          +
           |      |                         "columnnames": ["id", "product_name", "quantity", "last_updated"],                             +
           |      |                         "columntypes": ["integer", "character varying(100)", "integer", "timestamp without time zone"],+
           |      |                         "columnvalues": [1, "Widget A", 100, "2024-07-30 09:53:26.078749"]                             +
           |      |                 }                                                                                                      +
           |      |                 ,{                                                                                                     +
           |      |                         "kind": "insert",                                                                              +
           |      |                         "schema": "public",                                                                            +
           |      |                         "table": "inventory",                                                                          +
           |      |                         "columnnames": ["id", "product_name", "quantity", "last_updated"],                             +
           |      |                         "columntypes": ["integer", "character varying(100)", "integer", "timestamp without time zone"],+
           |      |                         "columnvalues": [2, "Gadget B", 50, "2024-07-30 09:53:26.078749"]                              +
           |      |                 }                                                                                                      +
           |      |                 ,{                                                                                                     +
           |      |                         "kind": "insert",                                                                              +
           |      |                         "schema": "public",                                                                            +
           |      |                         "table": "inventory",                                                                          +
           |      |                         "columnnames": ["id", "product_name", "quantity", "last_updated"],                             +
           |      |                         "columntypes": ["integer", "character varying(100)", "integer", "timestamp without time zone"],+
           |      |                         "columnvalues": [3, "Gizmo C", 75, "2024-07-30 09:53:26.078749"]                               +
           |      |                 }                                                                                                      +
           |      |         ]                                                                                                              +
           |      | }
(2 rows)
```

There are two rows in the query output above. The first row corresponds to the `CREATE TABLE` statement that we ran earlier. Logical decoding only captures information about DML (data manipulation) events — `INSERT`, `UPDATE`, and `DELETE` statements, hence this row is empty. The second row corresponds to the `INSERT` statement that added rows to the `inventory` table.

Next, we update an existing row in the `inventory` table:

```sql
UPDATE inventory SET quantity = quantity + 100 WHERE product_name = 'Widget A';
```

We can now query the `test_slot` replication slot again to see the new information published as a result of the update:

```sql
SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'pretty-print', 'on');
```

This query returns a single row in JSON format, corresponding to the row updated.

```plaintext
    lsn    | xid  |                                                          data
-----------+------+-------------------------------------------------------------------------------------------------------------------------
 0/24EC940 | 2057 | {                                                                                                                      +
           |      |         "change": [                                                                                                    +
           |      |                 {                                                                                                      +
           |      |                         "kind": "update",                                                                              +
           |      |                         "schema": "public",                                                                            +
           |      |                         "table": "inventory",                                                                          +
           |      |                         "columnnames": ["id", "product_name", "quantity", "last_updated"],                             +
           |      |                         "columntypes": ["integer", "character varying(100)", "integer", "timestamp without time zone"],+
           |      |                         "columnvalues": [1, "Widget A", 200, "2024-07-30 09:53:26.078749"],                            +
           |      |                         "oldkeys": {                                                                                   +
           |      |                                 "keynames": ["id"],                                                                    +
           |      |                                 "keytypes": ["integer"],                                                               +
           |      |                                 "keyvalues": [1]                                                                       +
           |      |                         }                                                                                              +
           |      |                 }                                                                                                      +
           |      |         ]                                                                                                              +
           |      | }
(1 row)
```

## Format versions: 1 vs 2

The `wal2json` plugin supports two different output format versions.

The default format version is 1, which produces a JSON object per transaction. All new and old tuples are available within this single JSON object. This format is useful when you need to process entire transactions as atomic units.

Format version 2 produces a JSON object per tuple (row), with optional JSON objects for the beginning and end of each transaction. This format is more granular and can be useful when you need to process changes on a row-by-row basis. Both formats support various options to include additional properties such as transaction timestamps, schema-qualified names, data types, and transaction IDs.

To use format version 2, you need to specify it explicitly:

```sql
SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'format-version', '2');
```

To illustrate, we add a couple more product entries to the `inventory` table:

```sql
INSERT INTO inventory (product_name, quantity) VALUES
    ('Widget D', 200),
    ('Gizmo E', 75);
```

Now, we can query the `test_slot` replication slot again to see the new information published as a result of the update:

```sql
SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'pretty-print', 'on', 'format-version', '2');
```

The output of this query appears as follows. You can see that there is a separate JSON object for each row inserted.

```plaintext
    lsn    | xid  |                                                                                                                                                                  data
-----------+------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 0/24F18D8 | 3078 | {"action":"B"}
 0/24F1940 | 3078 | {"action":"I","schema":"public","table":"inventory","columns":[{"name":"id","type":"integer","value":8},{"name":"product_name","type":"character varying(100)","value":"Widget D"},{"name":"quantity","type":"integer","value":200},{"name":"last_updated","type":"timestamp without time zone","value":"2024-07-30 10:27:45.428407"}]}
 0/24F1A48 | 3078 | {"action":"I","schema":"public","table":"inventory","columns":[{"name":"id","type":"integer","value":9},{"name":"product_name","type":"character varying(100)","value":"Gizmo E"},{"name":"quantity","type":"integer","value":75},{"name":"last_updated","type":"timestamp without time zone","value":"2024-07-30 10:27:45.428407"}]}
 0/24F1B10 | 3078 | {"action":"C"}
(4 rows)
```

## Use `wal2json` with tables without a primary key

`REPLICA IDENTITY` is a table property that determines what information is written to the WAL when a row is updated or deleted. This property is crucial for `wal2json` when working with tables that don't have a primary key.

`REPLICA IDENTITY` has four possible settings:

1. `DEFAULT`: Only primary key columns are logged for `UPDATE` and `DELETE` operations.
2. `USING INDEX`: A specified index's columns are logged for `UPDATE` and `DELETE` operations.
3. `FULL`: All columns are logged for `UPDATE` and `DELETE` operations.
4. `NOTHING`: No information is logged for `UPDATE` and `DELETE` operations.

Tables use the `DEFAULT` setting by default. For tables without a primary key, this means no information is logged for updates and deletes. Let's create a table without a primary key and see how `wal2json` behaves:

```sql
CREATE TABLE products_no_pk (
    product_name VARCHAR(100),
    quantity INTEGER,
    price DECIMAL(10, 2)
);

INSERT INTO products_no_pk (product_name, quantity, price) VALUES ('Widget', 100, 19.99);
UPDATE products_no_pk SET quantity = 90 WHERE product_name = 'Widget';
```

The `wal2json` output for this update operation will not contain any information about the updated row due to the lack of a primary key and the `DEFAULT REPLICA IDENTITY` setting.

```plaintext
WARNING:  table "products_no_pk" without primary key or replica identity is nothing
    lsn    | xid  |        data
-----------+------+---------------------
 0/256D6C8 | 6151 | {                  +
           |      |         "change": [+
           |      |         ]          +
           |      | }
(1 row)
```

To capture changes for tables without a primary key, we can change the `REPLICA IDENTITY` to `FULL`:

```sql
ALTER TABLE products_no_pk REPLICA IDENTITY FULL;
UPDATE products_no_pk SET price = 21.99 WHERE product_name = 'Widget';
```

Now, the `wal2json` output will include both the old and new values for all columns, which can be used to identify the changed row. To verify, we can query the `test_slot` replication slot again:

```sql
SELECT * FROM pg_logical_slot_get_changes('test_slot', NULL, NULL, 'pretty-print', 'on');
```

The output of this query appears as follows:

```plaintext
    lsn    | xid  |                                                data
-----------+------+-----------------------------------------------------------------------------------------------------
 0/256E228 | 6152 | {                                                                                                  +
           |      |         "change": [                                                                                +
           |      |         ]                                                                                          +
           |      | }
 0/256E310 | 6153 | {                                                                                                  +
           |      |         "change": [                                                                                +
           |      |                 {                                                                                  +
           |      |                         "kind": "update",                                                          +
           |      |                         "schema": "public",                                                        +
           |      |                         "table": "products_no_pk",                                                 +
           |      |                         "columnnames": ["product_name", "quantity", "price"],                      +
           |      |                         "columntypes": ["character varying(100)", "integer", "numeric(10,2)"],     +
           |      |                         "columnvalues": ["Widget", 90, 21.99],                                     +
           |      |                         "oldkeys": {                                                               +
           |      |                                 "keynames": ["product_name", "quantity", "price"],                 +
           |      |                                 "keytypes": ["character varying(100)", "integer", "numeric(10,2)"],+
           |      |                                 "keyvalues": ["Widget", 90, 19.99]                                 +
           |      |                         }                                                                          +
           |      |                 }                                                                                  +
           |      |         ]                                                                                          +
           |      | }
(2 rows)
```

## Performance considerations

When working with `wal2json`, keep the following performance considerations in mind:

1. **Replication slot management**: Unused replication slots can prevent WAL segments from being removed, potentially causing disk space issues. Regularly monitor and clean up unused slots.
2. **Batch processing**: Instead of processing each change individually, consider batching changes for more efficient processing.
3. **Resource usage**: Be mindful of network bandwidth usage, especially when dealing with high-volume changes or when replicating over a wide area network. Additionally, decoding WAL to JSON can be CPU-intensive. Monitor your system's CPU usage and consider scaling your resources if needed.

## Conclusion

The `wal2json` plugin is a powerful tool for capturing and processing database changes in JSON format. We've seen how to enable it, configure its output, and use it in various scenarios. Whether you're implementing a data replication system, building an audit trail, or creating an event-driven architecture, `wal2json` provides a flexible and efficient way to work with the Postgres Write-Ahead Log (WAL).

## Resources

- [wal2json GitHub Repository](https://github.com/eulerto/wal2json)
- [PostgreSQL Logical Decoding](https://www.postgresql.org/docs/current/logicaldecoding.html)
- [Manage logical replication in Neon - Decoder plugins](https://neon.com/docs/guides/logical-replication-manage#decoder-plugins)

--- [Document source](https://neon.com/docs/extensions/xml2.md) ---

> Summary: The xml2 Postgres extension adds XPath querying and XSLT transformation functions, letting you parse XML, extract typed values with xpath_string, xpath_number, and xpath_bool, and pivot XML documents into relational rows using xpath_table. Use it when your Neon database stores XML and you need to query or transform that data inside SQL rather than in application code. The extension predates the SQL/XML standard and is enabled with CREATE EXTENSION IF NOT EXISTS xml2.

# The xml2 extension

Perform XPath querying and XSLT transformations on XML data in Postgres.

Last updated: 2026-06-05

The `xml2` extension for Postgres provides functions to parse XML data, evaluate XPath queries against it, and perform XSLT transformations. This can be useful for applications that need to process or extract information from XML documents stored within the database.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Enable the `xml2` extension

You can enable the extension by running the following `CREATE EXTENSION` statement in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your Neon database.

```sql
CREATE EXTENSION IF NOT EXISTS xml2;
```

**Version availability:**

Please refer to the [list of all extensions](https://neon.com/docs/extensions/pg-extensions) available in Neon for up-to-date extension version information.

**Note:** The `xml2` extension was developed to provide robust XML processing capabilities within Postgres before the SQL/XML standard features were fully integrated. While it offers useful functions for XPath querying and XSLT, the SQL/XML standard now provides a more comprehensive and standardized approach to XML manipulation.

## `xml2` functions

The `xml2` module provides functions for XML parsing, XPath querying, and XSLT transformations.

### XML parsing and validation

- **`xml_valid(document text) → boolean`**
  Parses the given XML document string and returns `true` if it is well-formed XML, `false` otherwise.

  ```sql
  SELECT xml_valid('<book><title>My Book</title></book>');
  -- true

  SELECT xml_valid('<book><title>My Book</title>');
  -- false (not well-formed)
  ```

### XPath querying functions

These functions evaluate an XPath expression on a given XML document.

- **`xpath_string(document text, query text) → text`**
  Evaluates the XPath query and casts the result to a text string.

  ```sql
  SELECT xpath_string('<book><title>My Adventures</title></book>', '/book/title/text()');
  -- My Adventures
  ```

- **`xpath_number(document text, query text) → real`**
  Evaluates the XPath query and casts the result to a real number.

  ```sql
  SELECT xpath_number('<book><price>19.95</price></book>', '/book/price/text()');
  -- 19.95
  ```

- **`xpath_bool(document text, query text) → boolean`**
  Evaluates the XPath query and casts the result to a boolean.

  ```sql
  SELECT xpath_bool('<book available="true"></book>', '/book/@available="true"');
  -- true
  ```

- **`xpath_nodeset(document text, query text, toptag text, itemtag text) → text`**
  Evaluates the query and wraps the resulting nodeset in the specified `toptag` and `itemtag` XML tags. If `toptag` or `itemtag` is an empty string, the respective tag is omitted.
  There are also two-argument and three-argument versions:

  - `xpath_nodeset(document text, query text)`: Omits both `toptag` and `itemtag`.
  - `xpath_nodeset(document text, query text, itemtag text)`: Omits `toptag`.

  ```sql
  SELECT xpath_nodeset(
      '<books><book><title>Book A</title></book><book><title>Book B</title></book></books>',
      '//title',
      'results',
      'entry'
  );
  -- <results><entry><title>Book A</title></entry><entry><title>Book B</title></entry></results>

  SELECT xpath_nodeset(
      '<books><book><title>Book A</title></book></books>',
      '//title/text()'
  );
  -- Book A

  -- To get XML nodes:
  SELECT xpath_nodeset(
      '<books><book><title>Book A</title></book><book><title>Book B</title></book></books>',
      '//title'
  );
  -- <title>Book A</title><title>Book B</title>
  ```

- **`xpath_list(document text, query text, separator text) → text`**
  Evaluates the query and returns multiple text values separated by the specified `separator`.
  There is also a two-argument version `xpath_list(document text, query text)` which uses a comma (`,`) as the separator.

  ```sql
  SELECT xpath_list(
      '<books><book><author>Author 1</author><author>Author 2</author></book></books>',
      '//author/text()',
      '; '
  );
  -- Author 1; Author 2
  ```

### `xpath_table` function

The `xpath_table` function is a powerful tool for extracting data from a set of XML documents and returning it as a relational table.

`xpath_table(key text, document text, relation text, xpaths text, criteria text) returns setof record`

**Parameters:**

- `key`: The name of the "key" field from the source table. This field identifies the record from which each output row came and is returned as the first column.
- `document`: The name of the field in the source table containing the XML document.
- `relation`: The name of the table or view containing the XML documents.
- `xpaths`: One or more XPath expressions, separated by `|`, to extract data.
- `criteria`: The content of a `WHERE` clause to filter rows from the `relation`. This cannot be omitted; use `true` to process all rows.

The function constructs and executes a SQL `SELECT` statement internally. The `key` and `document` parameters must resolve to exactly two columns in this internal select.

`xpath_table` must be used in a `FROM` clause, and an `AS` clause is required to define the output column names and types. The first column in the `AS` clause corresponds to the `key`.

**Example:**

Suppose you have a table `catalog_items`:

```sql
CREATE TABLE catalog_items (
    item_sku TEXT PRIMARY KEY,
    item_details XML,
    added_on_date DATE
);

INSERT INTO catalog_items (item_sku, item_details, added_on_date) VALUES
('WDGT-001', XMLPARSE(DOCUMENT '<item><name>Super Widget</name><stock_level>150</stock_level><category>Gadgets</category></item>'), '2025-03-10'),
('TOOL-005', XMLPARSE(DOCUMENT '<item><name>Mega Wrench</name><stock_level>75</stock_level><category>Tools</category></item>'), '2025-04-02');
```

You can use `xpath_table` to extract data:

```sql
SELECT * FROM
    xpath_table(
        'item_sku',         -- The key column from catalog_items
        'item_details',     -- The XML column from catalog_items
        'catalog_items',    -- The source table
        '/item/name/text()|/item/stock_level/text()|/item/category/text()', -- XPath expressions
        'added_on_date >= ''2025-01-01'''  -- Criteria for filtering
    ) AS extracted_data(     -- Alias for the output table and its columns
        product_sku TEXT,
        product_name TEXT,
        current_stock INTEGER,
        product_category TEXT
    );
```

**Output:**

| product\_sku | product\_name | current\_stock | product\_category |
| :----------- | :------------ | :------------- | :---------------- |
| WDGT-001     | Super Widget  | 150            | Gadgets           |
| TOOL-005     | Mega Wrench   | 75             | Tools             |

**Data type conversion:**
`xpath_table` internally deals with string representations of XPath results. When you specify a data type (for example, `INTEGER`) in the `AS` clause, Postgres attempts to convert the string to that type. If conversion fails (for example, an empty string or non-numeric text to `INTEGER`), an error occurs. It might be safer to extract as `TEXT` and then cast explicitly if data quality is uncertain.

### XSLT functions

The `xml2` extension provides functions for XSLT (Extensible Stylesheet Language Transformations).

- **`xslt_process(document text, stylesheet text, paramlist text) returns text`**
  Applies the XSL `stylesheet` to the XML `document` and returns the transformed text. The `paramlist` argument accepts a string containing parameter assignments for the transformation, formatted as key-value pairs separated by commas (for example, `'name=value,debug=1'`). It's important to note that due to the straightforward parsing mechanism, individual parameter values within this list cannot themselves contain commas.

- **`xslt_process(document text, stylesheet text) returns text`**
  A two-parameter version that applies the stylesheet without passing any external parameters.

**Example:**

Let's say you have an XML document `my_data.xml`:

```xml
<data><item>Hello</item></data>
```

And `my_stylesheet.xsl` contains an XSLT to transform `<data><item>Hello</item></data>` into `<message>Hello</message>`:

```xml
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="/data/item">
    <message><xsl:value-of select="."/></message>
  </xsl:template>
</xsl:stylesheet>
```

You can apply the XSLT transformation using `xslt_process`. Here's an example of how to do this in Postgres:

```sql
DO $$
DECLARE
  xml_doc TEXT := '<data><item>Hello</item></data>';
  xslt_style TEXT := '<?xml version="1.0"?><xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"><xsl:output omit-xml-declaration="yes"/><xsl:template match="/data/item"><message><xsl:value-of select="."/></message></xsl:template></xsl:stylesheet>';
  transformed_xml TEXT;
BEGIN
  transformed_xml := xslt_process(xml_doc, xslt_style);
  RAISE NOTICE '%', transformed_xml;
END $$;
-- Output: <message>Hello</message>
```

## Conclusion

The `xml2` extension lets you parse, query, and transform XML documents using XPath and XSLT directly within Postgres.

## Resources

- [PostgreSQL `xml2` documentation](https://www.Postgres.org/docs/current/xml2.html)
- [PostgreSQL XML Data Type](https://neon.com/postgresql/postgresql-tutorial/postgresql-xml-data-type)

--- [Document source](https://neon.com/docs/functions/age.md) ---

> Summary: The Postgres `age()` function computes the symbolic difference between two timestamps as a years-months-days interval, or between a single timestamp and the current date at midnight. Use it to calculate a person's age, elapsed time since an event, or the duration of a subscription or project. The function has two signatures: `age(timestamp, timestamp)` and `age(timestamp)`; extract specific units with `EXTRACT(YEAR/MONTH/DAY FROM age(...))` and combine with `CURRENT_DATE` for live countdown calculations.

# Postgres age() function

Calculate the difference between timestamps or between a timestamp and the current date/time

Last updated: 2026-06-05

The Postgres `age()` function calculates the difference between two timestamps or the difference between a timestamp and the current date and time.

Use it for calculating ages, durations, or time intervals. For example, you can use it to determine a person's age, calculate the time elapsed since an event, or find the duration of a process or subscription.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signatures

The `age()` function has two forms:

```sql
age(timestamp, timestamp) -> interval
```

This form produces an interval by subtracting the second timestamp from the first.

- First argument: The end timestamp
- Second argument: The start timestamp

```sql
age(timestamp) -> interval
```

This form subtracts the given timestamp from the timestamp for the current date (at midnight).

## Example usage

Let's consider a table called `employees` that stores employee information, including their birth dates. We can use the `age()` function to calculate the age of employees.

```sql
CREATE TABLE employees (
  id SERIAL PRIMARY KEY,
  name TEXT,
  birth_date DATE,
  hire_date DATE
);

INSERT INTO employees (name, birth_date, hire_date) VALUES
  ('John Doe', '1985-05-15', '2010-03-01'),
  ('Jane Smith', '1990-08-22', '2015-07-10'),
  ('Bob Johnson', '1978-12-03', '2005-11-15');

SELECT
  name,
  birth_date,
  age(birth_date) AS age
FROM employees;
```

This query calculates the age of each employee based on their birth date.

```
    name     | birth_date |           age
-------------+------------+-------------------------
 John Doe    | 1985-05-15 | 39 years 1 mon 10 days
 Jane Smith  | 1990-08-22 | 33 years 10 mons 3 days
 Bob Johnson | 1978-12-03 | 45 years 6 mons 22 days
(3 rows)
```

We can also use the `age()` function with two timestamps to calculate the duration of employment for each employee:

```sql
SELECT
  name,
  hire_date,
  age(CURRENT_DATE, hire_date) AS employment_duration
FROM employees;
```

This query calculates how long each employee has been with the company.

```text
    name     | hire_date  |   employment_duration
-------------+------------+-------------------------
 John Doe    | 2010-03-01 | 14 years 3 mons 24 days
 Jane Smith  | 2015-07-10 | 8 years 11 mons 15 days
 Bob Johnson | 2005-11-15 | 18 years 7 mons 10 days
(3 rows)
```

## Advanced examples

### Use `age()` for time-based calculations

The `age()` function can be useful for various time-based calculations. For example, consider a `projects` table that tracks the start date and deadline for projects. We can use `age()` to calculate project durations and remaining time:

```sql
WITH projects(name, start_date, deadline) AS (
    VALUES
        ('Project A', '2023-01-15'::DATE, '2024-06-30'::DATE),
        ('Project B', '2023-05-01'::DATE, '2023-12-31'::DATE),
        ('Project C', '2024-03-01'::DATE, '2025-02-28'::DATE)
)

SELECT
  name,
  start_date,
  deadline,
  age(deadline, start_date) AS total_duration,
  age(deadline, CURRENT_DATE) AS remaining_time
FROM projects;
```

This query calculates the total duration of each project and the time remaining until the deadline.

```text
   name    | start_date |  deadline  |    total_duration     |  remaining_time
-----------+------------+------------+-----------------------+------------------
 Project A | 2023-01-15 | 2024-06-30 | 1 year 5 mons 15 days | 5 days
 Project B | 2023-05-01 | 2023-12-31 | 7 mons 30 days        | -5 mons -25 days
 Project C | 2024-03-01 | 2025-02-28 | 11 mons 27 days       | 8 mons 3 days
(3 rows)
```

### Extract specific units from age intervals

You can extract specific units of time (like years, months, or days) from the interval returned by the `age()` function. Here's an example that breaks down the age into years, months, and days:

```sql
WITH sample_dates(name, birth_date) AS (
  VALUES
    ('Alice', '1990-03-15'::DATE),
    ('Bob', '1985-11-30'::DATE),
    ('Charlie', '1995-07-22'::DATE)
)
SELECT
  name,
  birth_date,
  EXTRACT(YEAR FROM age(birth_date)) AS years,
  EXTRACT(MONTH FROM age(birth_date)) AS months,
  EXTRACT(DAY FROM age(birth_date)) AS days
FROM sample_dates;
```

This query provides a detailed breakdown of each employee's age in years, months, and days.

```text
  name   | birth_date | years | months | days
---------+------------+-------+--------+------
 Alice   | 1990-03-15 |    34 |      3 |   10
 Bob     | 1985-11-30 |    38 |      6 |   25
 Charlie | 1995-07-22 |    28 |     11 |    3
(3 rows)
```

## Additional considerations

### Negative intervals

The `age()` function can return negative intervals if the end timestamp is earlier than the start timestamp. Be mindful of this when using `age()` in calculations or comparisons.

### Alternative functions

- `-` operator — Can be used to subtract two dates or timestamps, returning an interval. This is equivalent to using the `age()` function with two timestamps.
- `current_date` — Returns the current date (without the time component). Can be used with the `-` operator to calculate an age or duration.

## Resources

- [PostgreSQL documentation: Date/Time Functions and Operators](https://www.postgresql.org/docs/current/functions-datetime.html)
- [PostgreSQL documentation: Date/Time Types](https://www.postgresql.org/docs/current/datatype-datetime.html)

--- [Document source](https://neon.com/docs/functions/array_agg.md) ---

> Summary: `array_agg()` is a PostgreSQL aggregate function that collects values from multiple rows into a single array, supporting ORDER BY, DISTINCT, and FILTER clauses within the aggregation. Use it to denormalize one-to-many relationships into a single row, build comma-separated or JSON-ready lists, or group related values without a separate join table. The function holds all aggregated values in memory before producing the array, so large datasets may need pagination; alternatives include `string_agg()` for delimited strings and `json_agg()` for JSON arrays.

# Postgres array_agg() function

Aggregate values into an array

Last updated: 2026-06-05

The Postgres `array_agg()` function collects values from multiple rows into a single array.

Use it for denormalizing data, creating comma-separated lists, or preparing data for JSON output. For example, you can use it to list all products in a category from a products catalog table or all orders for a customer from an orders table.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `array_agg()` function has this simple form:

```sql
array_agg(expression) -> anyarray
```

- `expression`: The value to be aggregated into an array. This can be a column or expression of any data type.

```sql
array_agg(expression ORDER BY sort_expression [ASC | DESC] [NULLS { FIRST | LAST }]) -> anyarray
```

- `expression`: The value to be aggregated into an array.
- `ORDER BY`: Specifies the order in which the values should be aggregated.
- `sort_expression`: The expression to sort by.
- `ASC | DESC`: Specifies ascending or descending order (default is ASC).
- `NULLS { FIRST | LAST }`: Specifies whether nulls should be first or last in the ordering (default depends on ASC or DESC).

## Example usage

Consider an `orders` table with columns `order_id`, `product_id`, and `quantity`. You can use `array_agg()` to list all the product IDs for each order.

```sql
WITH orders AS (
  SELECT 1 AS order_id, 101 AS product_id, 2 AS quantity
  UNION ALL SELECT 1, 102, 1
  UNION ALL SELECT 2, 103, 3
  UNION ALL SELECT 2, 104, 1
  UNION ALL SELECT 3, 101, 1
)
SELECT
  order_id,
  array_agg(product_id) AS products
FROM orders
GROUP BY order_id
ORDER BY order_id;
```

This query groups the orders by `order_id` and aggregates the `product_id` values into an array for each order.

```text
 order_id | products
----------+-----------
        1 | {101,102}
        2 | {103,104}
        3 | {101}
(3 rows)
```

## Advanced examples

### Ordered array aggregation

You can specify an order for the elements in the resulting array:

```sql
WITH employees AS (
  SELECT 1 AS emp_id, 'John' AS name, 'SQL' AS skill
  UNION ALL SELECT 1, 'John', 'Python'
  UNION ALL SELECT 1, 'John', 'Java'
  UNION ALL SELECT 2, 'Jane', 'C++'
  UNION ALL SELECT 2, 'Jane', 'Ruby'
)
SELECT
  emp_id,
  name,
  array_agg(skill ORDER BY skill) AS skills
FROM employees
GROUP BY emp_id, name
ORDER BY emp_id;
```

This query aggregates the listed skills for each employee into an alphabetically ordered array.

```text
 emp_id | name |      skills
--------+------+-------------------
      1 | John | {Java,Python,SQL}
      2 | Jane | {C++,Ruby}
(2 rows)
```

### Combining with other aggregate functions

`array_agg()` can be used in combination with other aggregate functions:

```sql
WITH sales(category, product, price, sale_date) AS (
  VALUES
    ('Electronics', 'Laptop', 1200, '2023-01-15'::date),
    ('Electronics', 'Smartphone', 800, '2023-01-20'::date),
    ('Electronics', 'Tablet', 500, '2023-02-10'::date),
    ('Books', 'Novel', 20, '2023-02-05'::date),
    ('Books', 'Textbook', 100, '2023-02-15'::date),
    ('Books', 'Cookbook', 30, '2023-03-01'::date)
)
SELECT
  category,
  array_agg(
    (SELECT product || ': ' || SUM(price)::text
     FROM sales s2
     WHERE s2.category = s1.category AND s2.product = s1.product
     GROUP BY s2.product)
  ) AS product_sales
FROM sales s1
GROUP BY category;
```

This query aggregates products into an array with their total sales, for each category.

```text
  category   |                  product_sales
-------------+--------------------------------------------------
 Electronics | {"Laptop: 1200","Smartphone: 800","Tablet: 500"}
 Books       | {"Novel: 20","Textbook: 100","Cookbook: 30"}
(2 rows)
```

### Using array_agg() with DISTINCT

You can use `DISTINCT` with `array_agg()` to remove duplicates from the output array:

```sql
WITH user_logins AS (
  SELECT 1 AS user_id, 'Chrome' AS browser
  UNION ALL SELECT 1, 'Firefox'
  UNION ALL SELECT 1, 'Chrome'
  UNION ALL SELECT 2, 'Safari'
  UNION ALL SELECT 2, 'Chrome'
)
SELECT
  user_id,
  array_agg(DISTINCT browser ORDER BY browser) AS browsers_used
FROM user_logins
GROUP BY user_id;
```

This query creates an array of the browsers used by each user, without duplicates and in alphabetical order.

```text
 user_id |  browsers_used
---------+------------------
       1 | {Chrome,Firefox}
       2 | {Chrome,Safari}
(2 rows)
```

## Additional considerations

### Performance implications

While `array_agg()` is powerful, it can be memory-intensive for large datasets. The function needs to hold all the aggregated values in memory before creating the final array. For very large result sets, consider using pagination or limiting the number of rows before aggregating.

### NULL handling

By default, `array_agg()` includes NULL values in the resulting array. If you want to exclude NULL values, you can use it in combination with `FILTER`:

```sql
SELECT array_agg(column_name) FILTER (WHERE column_name IS NOT NULL)
FROM table_name;
```

### Alternative functions

- `string_agg()`: Concatenates string values into a single string, separated by a delimiter.
- `json_agg()`: Aggregates values into a JSON array.

## Resources

- [PostgreSQL documentation: Aggregate Functions](https://www.postgresql.org/docs/current/functions-aggregate.html)
- [PostgreSQL documentation: Array Functions and Operators](https://www.postgresql.org/docs/current/functions-array.html)

--- [Document source](https://neon.com/docs/functions/array_length.md) ---

> Summary: The Postgres `array_length(anyarray, int)` function returns the number of elements along a specified dimension of an array, returning NULL when the dimension does not exist or the input is NULL. Use it to filter rows by array size in WHERE clauses, enforce array size with CHECK constraints, or inspect multi-dimensional arrays by querying each dimension separately. Differs from `cardinality()`, which counts all elements across all dimensions, and from `array_dims()`, which returns dimension bounds as text.

# Postgres array_length() function

Determine the length of an array

Last updated: 2026-06-05

The Postgres `array_length()` function is used to determine the length of an array along a specified dimension.

Use it when working with multi-dimensional arrays or when you need to perform operations based on the size of an array. Examples include data analysis where you might need to filter rows based on the number of elements in an array column. Another use case might be application development where you need to validate the size of array inputs since Postgres doesn't natively have a fixed-size array data type.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `array_length()` function has the following signature:

```sql
array_length(anyarray, int) -> int
```

- `anyarray`: The input array to measure.
- `int`: The array dimension to measure (1-based index).

## Example usage

Consider a `products` table with a `categories` column that contains arrays of product categories. We can use `array_length()` to find out how many categories each product belongs to.

```sql
WITH products(product_name, categories) AS (
  VALUES
    ('Laptop', ARRAY['Electronics', 'Computers']),
    ('Coffee Maker', ARRAY['Appliances', 'Kitchen', 'Electronics']),
    ('Book', ARRAY['Books'])
)
SELECT
  product_name,
  categories,
  array_length(categories, 1) AS category_count
FROM products;
```

This query returns the product name, the array of categories it is listed in, and the count of categories for each product.

```text
 product_name |            categories            | category_count
--------------+----------------------------------+----------------
 Laptop       | {Electronics,Computers}          |              2
 Coffee Maker | {Appliances,Kitchen,Electronics} |              3
 Book         | {Books}                          |              1
(3 rows)
```

## Advanced examples

### Filter rows based on array length

You can use `array_length()` in a `WHERE` clause to filter rows based on the size of an array.

```sql
WITH orders(order_id, items) AS (
  VALUES
    (1, ARRAY['Shirt', 'Pants', 'Shoes']),
    (2, ARRAY['Book']),
    (3, ARRAY['Laptop', 'Mouse', 'Keyboard', 'Monitor'])
)
SELECT *
FROM orders
WHERE array_length(items, 1) > 2;
```

This query selects all orders that contain more than two items.

```text
 order_id |              items
----------+---------------------------------
        1 | {Shirt,Pants,Shoes}
        3 | {Laptop,Mouse,Keyboard,Monitor}
(2 rows)
```

### Use with multi-dimensional arrays

`array_length()` can be used with multi-dimensional arrays by specifying the dimension to measure.

```sql
WITH matrix AS (
  SELECT ARRAY[[1, 2, 3], [4, 5, 6]] AS data
)
SELECT
  array_length(data, 1) AS rows,
  array_length(data, 2) AS columns,
  array_length(data, 3) AS depth
FROM matrix;
```

This query returns the number of rows and columns in a 2D array. There is no third dimension in this case, so `array_length(data, 3)` returns NULL.

```text
 rows | columns | depth
------+---------+-------
    2 |       3 |
(1 row)
```

### Use in a CHECK constraint

You can use `array_length()` in a `CHECK` constraint to enforce a condition based on the size of an array column. For example, consider a table that stores the starting lineup of basketball teams as an array.

```sql
CREATE TABLE basketball_team (
  team_name TEXT PRIMARY KEY,
  starting_lineup TEXT[],
  CONSTRAINT check_starting_lineup CHECK (array_length(starting_lineup, 1) = 5)
);
```

This constraint ensures that the `starting_lineup` array column always contains exactly five elements.

```sql
INSERT INTO basketball_team (team_name, starting_lineup)
VALUES ('Lakers', ARRAY['LeBron James', 'Anthony Davis', 'Russell Westbrook', 'Carmelo Anthony', 'Dwight Howard']);
-- Success

INSERT INTO basketball_team (team_name, starting_lineup)
VALUES ('Warriors', ARRAY['Stephen Curry', 'Klay Thompson', 'Draymond Green']);
-- ERROR:  new row for relation "basketball_team" violates check constraint "check_starting_lineup"
-- DETAIL:  Failing row contains (Warriors, {"Stephen Curry","Klay Thompson","Draymond Green"}).
```

## Additional considerations

### Null handling

`array_length()` returns NULL if the input array is NULL or if the specified dimension does not exist. Always handle potential NULL values in your queries to avoid unexpected results.

### Indexing

Note that Postgres array dimensions are indexed starting from 1, not 0. If you specify a dimension less than 1, `array_length()` returns NULL.

```sql
SELECT array_length(ARRAY[1, 2, 3], 0);
```

### Performance implications

`array_length()` is generally efficient, but be cautious when using it in `WHERE` clauses on large tables. Consider creating a function index on the array length if you frequently filter based on this condition.

### Alternative functions

- `cardinality()` - Returns the total number of elements in an array, or NULL if the array is NULL. It's equivalent to `array_length(anyarray, 1)` for one-dimensional arrays.
- `array_dims()` - Returns a text representation of the array's dimensions.
- `array_upper()` and `array_lower()` - Return the upper and lower bounds of the specified array dimension.

## Resources

- [PostgreSQL documentation: Array Functions and Operators](https://www.postgresql.org/docs/current/functions-array.html)
- [PostgreSQL documentation: Arrays](https://www.postgresql.org/docs/current/arrays.html)

--- [Document source](https://neon.com/docs/functions/array_to_json.md) ---

> Summary: The `array_to_json(anyarray [, pretty_bool])` function converts a PostgreSQL array into a JSON array, making SQL array data consumable by web services and APIs without manual serialization. Use it when you need to export array columns as JSON, combine it with `array_agg` and `row_to_json` to build nested JSON structures from query results, or rely on its native `null` passthrough for arrays containing NULL values. The optional `pretty_bool` parameter adds line breaks between top-level elements for readable output; for finer JSON construction, `json_build_array` and `json_build_object` offer more control.

# Postgres array_to_json() function

Converts an SQL array to a JSON array

Last updated: 2026-06-05

You can use the `array_to_json` function to convert a Postgres array into its `JSON` representation, transforming an array of values into a `JSON` array. This makes it easier to integrate with web services, APIs, and web frameworks that rely on `JSON`.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
array_to_json(anyarray [, pretty_bool])
```

Line feeds will be added between dimension 1 elements if `pretty_bool` is true.

## `array_to_json` example

Let's consider a scenario where an e-commerce platform stores customer preferences as an array of string values in a `customers` table.

**customers**

```sql
CREATE TABLE customers (
 id SERIAL PRIMARY KEY,
 name TEXT NOT NULL,
 preferences TEXT[]
);

INSERT INTO customers (name, preferences)
VALUES ('John Doe', '{clothing, electronics}');

INSERT INTO customers (name, preferences)
VALUES ('Jane Doe', '{books, music, travel}');
```

```
 id  |   name   |      preferences
----+----------+------------------------
  1 | John Doe | {clothing,electronics}
  2 | Jane Doe | {books,music,travel}
```

You can use the `array_to_json` function as shown to transform the array of string values into a `JSON` array:

```sql
SELECT id, name, array_to_json(preferences) AS json_preferences
FROM customers;
```

This query returns the following result:

```
 id  |   name   |      json_preferences
----+----------+----------------------------
  1 | John Doe | ["clothing","electronics"]
  2 | Jane Doe | ["books","music","travel"]
```

## Advanced examples

Let's now take a look at a few advanced examples.

### Use `array_to_json` with `array_agg`

Imagine you have an e-commerce website with user's shopping cart items, as shown in the following `cart_items` table:

**cart_items**

```sql
CREATE TABLE cart_items (
 id SERIAL PRIMARY KEY,
 user_id INTEGER NOT NULL,
 product_id INTEGER NOT NULL,
 quantity INTEGER NOT NULL
);

INSERT INTO cart_items (user_id, product_id, quantity)
VALUES (1, 123, 1), (1, 456, 2), (1, 789, 3);


INSERT INTO cart_items (user_id, product_id, quantity)
VALUES (2, 123, 2), (2, 456, 3), (2, 789, 4);
```

```
 id  | user_id | product_id | quantity
----+---------+------------+----------
  1 |       1 |        123 |        1
  2 |       1 |        456 |        2
  3 |       1 |        789 |        3
  4 |       2 |        123 |        2
  5 |       2 |        456 |        3
  6 |       2 |        789 |        4
```

Use `array_to_json` to create a `JSON` representation of the cart contents for a specific user.

In the example below, the `row_to_json` function converts each row of the result set into a `JSON` object.

The `array_agg` function is an aggregate function that aggregates multiple values into an array. It is used here to aggregate the `JSON` objects created by `row_to_json` into a `JSON` array.

```sql
SELECT array_to_json(
 array_agg(row_to_json(t))
) AS items
FROM (
     SELECT product_id, quantity FROM cart_items WHERE user_id = 1
   ) t;
```

This query returns the following result:

```shell
                                               items
---------------------------------------------------------------------------------------------------
 [{"product_id":123,"quantity":1},{"product_id":456,"quantity":2},{"product_id":789,"quantity":3}]
```

And this is the resulting `JSON` structure:

```json
[
  {
    "product_id": 123,
    "quantity": 1
  },
  {
    "product_id": 456,
    "quantity": 2
  },
  {
    "product_id": 789,
    "quantity": 3
  }
]
```

### Handling `NULL` in `array_to_json`

The `array_to_json` function handles `NULL` values gracefully, representing them as `JSON` `null` within the resulting array.

Let's consider a `survey_responses` table representing a survey where each participant can provide multiple responses to different questions. Some participants may not answer all questions, leading to `NULL` values in the data.

```sql
CREATE TABLE survey_responses (
   participant_id SERIAL PRIMARY KEY,
   participant_name VARCHAR(50),
   responses VARCHAR(50)[]
);

-- Insert sample data with NULL responses
INSERT INTO survey_responses (participant_name, responses) VALUES
   ('Participant A', ARRAY['Yes', 'No', 'Maybe']),
   ('Participant B', ARRAY['Yes', NULL, 'No']),
   ('Participant C', ARRAY[NULL, 'No', 'Yes']),
   ('Participant D', ARRAY['Yes', 'No', NULL]);
```

```
 participant_id  | participant_name |   responses
----------------+------------------+----------------
              1 | Participant A    | {Yes,No,Maybe}
              2 | Participant B    | {Yes,NULL,No}
              3 | Participant C    | {NULL,No,Yes}
              4 | Participant D    | {Yes,No,NULL}
```

The output correctly represents `NULL` values as `JSON` `null` in the `responses_json` array.

```sql
SELECT
   participant_id,
   participant_name,
   array_to_json(COALESCE(responses, ARRAY[]::VARCHAR[])) AS responses_json
FROM
   survey_responses;
```

This query returns the following result:

```
participant_id | participant_name | responses_json
---------------+-----------------=+---------------------
             1 | Participant A    | ["Yes","No","Maybe"]
             2 | Participant B    | ["Yes",null,"No"]
             3 | Participant C    | [null,"No","Yes"]
             4 | Participant D    | ["Yes","No",null]
```

## Additional considerations

This section outlines additional considerations when using the `array_to_json` function.

### JSON functions

In scenarios where more control over the `JSON` structure is required, consider using the `json_build_array` and `json_build_object` functions. These functions allow for a more fine-grained construction of `JSON` objects and arrays.

### Formatting `array_to_json` output with `pretty_bool`

The `pretty_bool` parameter, when set to `true`, instructs `array_to_json` to format the output with indentation and line breaks for improved readability.

Execute the earlier query with `pretty_bool` as `true`:

```sql
SELECT array_to_json(
 array_agg(row_to_json(t)), true
) AS items
FROM (
     select product_id, quantity from cart_items WHERE user_id = 1
   ) t;
```

This query returns the following result:

```
               items
-----------------------------------
 [{"product_id":123,"quantity":1},+
  {"product_id":456,"quantity":2},+
  {"product_id":789,"quantity":3}]
```

**Note:** The output displayed in `psql` might be truncated or wrap long lines for visual clarity.

## Resources

- [PostgreSQL documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/avg.md) ---

> Summary: The Postgres `avg()` function computes the arithmetic mean of a numeric column or expression, returning `numeric` for integer/numeric inputs and `double precision` for floating-point inputs. Use it when you need grouped averages with `GROUP BY`, conditional averages with `FILTER`, moving averages as a window function, or row-vs-mean comparisons via subquery. `avg()` automatically skips NULL values and works as both an aggregate and a window function.

# Postgres avg() function

Calculate the average value of a set of numbers

Last updated: 2026-06-05

The Postgres `avg()` function calculates the arithmetic mean of a set of numeric values.

Use it when you need to understand typical values in a dataset, compare different groups, or identify trends over time. For example, you might use it to calculate the average order value for an e-commerce platform, the average response time for a web service, or the mean of sensor readings over time.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `avg()` function has the simple form:

```sql
avg(expression) -> numeric type
```

- `expression`: Any numeric expression or column name whose average you want to calculate.

The `avg()` function returns an output of the type `numeric` when applied to integer or numeric values. When used with floating-point values, the output type is `double precision`.

## Example usage

Consider a table `weather_data` tracking the temperature readings for different cities. It has the columns `date`, `city` and `temperature`. We will use the `avg()` function to analyze this data.

```sql
CREATE TABLE weather_data (
  date DATE,
  city TEXT,
  temperature NUMERIC
);

INSERT INTO weather_data (date, city, temperature) VALUES
  ('2024-03-01', 'New York', 5.5),
  ('2024-03-01', 'Los Angeles', 22.0),
  ('2024-03-01', 'Chicago', 2.0),
  ('2024-03-02', 'New York', 7.0),
  ('2024-03-02', 'Los Angeles', 23.5),
  ('2024-03-02', 'Chicago', 3.5),
  ('2024-03-03', 'New York', 6.5),
  ('2024-03-03', 'Los Angeles', 21.5),
  ('2024-03-03', 'Chicago', 1.0);
```

### Calculating the average temperature

To calculate the average temperature reading across all cities and dates, you can use the following query:

```sql
SELECT avg(temperature) AS avg_temperature
FROM weather_data;
```

This query computes the average of all values in the `temperature` column.

```text
   avg_temperature
---------------------
 10.2777777777777778
(1 row)
```

### Calculating the average temperature by city

You can use `avg()` with a `GROUP BY` clause to calculate averages for different cities:

```sql
SELECT city, avg(temperature) AS avg_temperature
FROM weather_data
GROUP BY city
ORDER BY avg_temperature DESC;
```

This query returns the average temperature recorded for each city, ordered by the highest average temperature:

```text
    city     |   avg_temperature
-------------+---------------------
 Los Angeles | 22.3333333333333333
 New York    |  6.3333333333333333
 Chicago     |  2.1666666666666667
(3 rows)
```

## Advanced examples

### Using avg() with a FILTER clause

Postgres allows you to use a `FILTER` clause with aggregate functions to selectively include rows in the calculation:

```sql
SELECT
  city,
  avg(temperature) as avg_temperature,
  avg(temperature) FILTER (WHERE date >= '2024-03-03') AS avg_temperature_since_3rd
FROM weather_data
GROUP BY city;
```

This query calculates the average temperature for each city and the average temperature since March 3rd, 2024.

```text
    city     |   avg_temperature   | avg_temperature_since_3rd
-------------+---------------------+---------------------------
 Chicago     |  2.1666666666666667 |    1.00000000000000000000
 Los Angeles | 22.3333333333333333 |       21.5000000000000000
 New York    |  6.3333333333333333 |        6.5000000000000000
(3 rows)
```

### Using avg() in a subquery

You can use `avg()` in a subquery to compare individual values against the average:

```sql
WITH temp_diff AS (
  SELECT
    date,
    city,
    temperature,
    temperature - (SELECT avg(temperature) FROM weather_data) AS temp_diff_from_avg
  FROM weather_data
)
SELECT *
FROM temp_diff
ORDER BY abs(temp_diff_from_avg) DESC
LIMIT 5;
```

This query calculates the difference between each temperature reading and the overall average temperature, and returns the top 5 records with the largest deviations:

```text
    date    |    city     | temperature | temp_diff_from_avg
------------+-------------+-------------+---------------------
 2024-03-02 | Los Angeles |        23.5 | 13.2222222222222222
 2024-03-01 | Los Angeles |        22.0 | 11.7222222222222222
 2024-03-03 | Los Angeles |        21.5 | 11.2222222222222222
 2024-03-02 | New York    |         7.0 | -3.2777777777777778
 2024-03-03 | New York    |         6.5 | -3.7777777777777778
(5 rows)
```

### Calculating a moving average

We can use `avg()` as a window function to calculate a moving average over the specified window of rows.

```sql
SELECT
  date,
  city,
  temperature,
  avg(temperature) OVER (
    PARTITION BY city
    ORDER BY date
    ROWS BETWEEN 2 PRECEDING AND CURRENT ROW
  ) AS moving_avg_temp
FROM weather_data
ORDER BY city, date;
```

This query calculates a 3-day moving average of temperature readings for each city, alongside the current temperature:

```text
    date    |    city     | temperature |   moving_avg_temp
------------+-------------+-------------+---------------------
 2024-03-01 | Chicago     |         2.0 |  2.0000000000000000
 2024-03-02 | Chicago     |         3.5 |  2.7500000000000000
 2024-03-03 | Chicago     |         1.0 |  2.1666666666666667
 2024-03-01 | Los Angeles |        22.0 | 22.0000000000000000
 2024-03-02 | Los Angeles |        23.5 | 22.7500000000000000
 2024-03-03 | Los Angeles |        21.5 | 22.3333333333333333
 2024-03-01 | New York    |         5.5 |  5.5000000000000000
 2024-03-02 | New York    |         7.0 |  6.2500000000000000
 2024-03-03 | New York    |         6.5 |  6.3333333333333333
(9 rows)
```

## Additional considerations

### Handling NULL values

The `avg()` function automatically ignores NULL values in its calculations. If all values are NULL, it returns NULL.

### Precision and rounding

The `avg()` function returns a numeric value with the maximum precision and scale of any argument. You may want to use the `round()` function to control the number of decimal places in the result:

```sql
SELECT round(avg(temperature), 2) AS avg_temperature
FROM weather_data;
```

### Performance implications

When working with large datasets, calculating averages can be resource-intensive, especially when combined with complex `GROUP BY` clauses or subqueries. Consider using materialized views or pre-aggregating data for frequently used averages for analytics applications.

## Alternative functions

- `percentile_cont()`: Calculates a continuous percentile value. It can be used to compute the median or other percentiles. Note that it is an ordered-set aggregate function and requires a `WITHIN GROUP` clause.
- `mode()`: Returns the most frequent value in a set. It is also an ordered-set aggregate function.

## Resources

- [PostgreSQL documentation: Aggregate Functions](https://www.postgresql.org/docs/current/functions-aggregate.html)
- [PostgreSQL documentation: Mathematical Functions and Operators](https://www.postgresql.org/docs/current/functions-math.html)

--- [Document source](https://neon.com/docs/functions/concat.md) ---

> Summary: The Postgres `concat()` function is a variadic string function that joins two or more strings or values into a single string, automatically converting numeric arguments and silently treating NULL inputs as empty strings. Use it instead of the `||` operator when NULL values should be ignored rather than propagate through the result. The function accepts either individual arguments or a variadic array form (`concat(variadic arr)`), covering use cases such as combining column values, generating composite keys, and building dynamic labels.

# Postgres concat() function

Concatenate strings in Postgres with the concat() function

Last updated: 2026-06-05

The `concat()` function in Postgres is used to concatenate two or more strings into a single string. It is a variadic function, meaning it can accept any number of arguments.

It is useful for combining data from multiple columns, generating custom identifiers or labels, or constructing dynamic SQL statements.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `concat()` function has two forms:

```sql
concat(str "any" [, str "any" [, ...] ]) → text
```

- `str`: The strings/values to concatenate. Numeric values are automatically converted to strings, while `NULL` values are treated as empty strings.

```sql
concat(variadic str "any"[]) → text
```

- `variadic str`: An array of strings/values to concatenate. This form is useful when you have an array of strings to concatenate.

## Example usage

Consider a table `customers` with `first_name` and `last_name` columns. We can use `concat()` to combine these into a full name.

```sql
WITH customers AS (
  SELECT 'John' AS first_name, 'Doe' AS last_name
  UNION ALL
  SELECT 'Jane' AS first_name, 'Smith' AS last_name
)
SELECT concat(first_name, ' ', last_name) AS full_name
FROM customers;
```

This query concatenates the `first_name`, a space character, and the `last_name` to generate the `full_name`.

```text
  full_name
-------------
 John Doe
 Jane Smith
(2 rows)
```

We can concatenate more than two strings by providing additional arguments.

```sql
WITH products AS (
  SELECT 'Laptop' AS name, 'A' AS variant, 100 AS price
  UNION ALL
  SELECT 'Kindle' AS name, NULL AS variant, 200 AS price
  UNION ALL
  SELECT 'Table' AS name, 'C' AS variant, 300 AS price
)
SELECT concat(name, CASE WHEN variant IS NOT NULL THEN ' - Variant ' ELSE '' END, variant, ' ($', price, ')') AS product_info
FROM products;
```

This query generates a descriptive `product_info` string by concatenating the `name`, `variant`, and `price` columns along with some constant text. We used a `CASE` statement to conditionally include the variant in the output.

```text
       product_info
---------------------------
 Laptop - Variant A ($100)
 Kindle ($200)
 Table - Variant C ($300)
(3 rows)
```

## Advanced examples

### Concatenate an array of strings

You can use the `variadic` form of `concat()` to concatenate an array of strings.

```sql
WITH data AS (
  SELECT ARRAY['apple', 'banana', 'cherry'] AS fruits
)
SELECT concat(variadic fruits) AS fruit_string
FROM data;
```

This query concatenates the elements of the `fruits` array into a single string.

```text
  fruit_string
----------------
 applebananacherry
(1 row)
```

### Concatenate columns to generate custom keys

`concat()` can be used to generate custom identifiers as keys, which you can use for further processing or analysis.

```sql
WITH page_interactions AS (
  SELECT 1 AS user_id, '/home' AS page, '2023-06-01 10:00:00' AS ts
  UNION ALL
  SELECT 1 AS user_id, '/products' AS page, '2023-06-01 10:30:00' AS ts
  UNION ALL
  SELECT 2 AS user_id, '/home' AS page, '2023-06-01 11:00:00' AS ts
  UNION ALL
  SELECT 1 AS user_id, '/home' AS page, '2023-06-01 12:00:00' AS ts
)
SELECT unique_visit, count(*) AS num_interactions
FROM (
    SELECT ts, concat(user_id, ':', page) AS unique_visit
    FROM page_interactions
)
GROUP BY unique_visit;
```

This query generates a unique identifier for each page visit by concatenating the `user_id` and `page` columns. We then count the number of interactions for each unique visit.

```text
 unique_visit | num_interactions
--------------+------------------
 1:/home      |                2
 2:/home      |                1
 1:/products  |                1
(3 rows)
```

## Additional considerations

### Handling NULL values

Any null arguments to `concat()` are treated as empty strings in the output. This is in contrast to the behavior of the `||` operator, which treats `NULL` values as `NULL`.

```sql
SELECT
    concat('Hello', NULL, 'World') AS join_concat,
    'Hello' || NULL || 'World' AS join_operator;
```

Pick the right function based on how you want to handle `NULL` values.

```text
 join_concat | join_operator
-------------+---------------
 HelloWorld  |
(1 row)
```

### Alternative functions

- `concat_ws`: Concatenates strings with a separator string between each element.
- `string_agg`: An aggregation function that combines strings from a column into a single string with a separator.
- `||` operator: Can also be used to concatenate strings. It treats `NULL` values differently than `concat()`.

## Resources

- [PostgreSQL documentation: String functions](https://www.postgresql.org/docs/current/functions-string.html)

--- [Document source](https://neon.com/docs/functions/count.md) ---

> Summary: The Postgres `COUNT()` aggregate function counts rows or non-null values in a result set, returning a `bigint` via `COUNT(*)`, `COUNT(column)`, or `COUNT(DISTINCT column)`. Use it to tally total records, skip NULL values, or find unique values within a column, and combine it with `GROUP BY`, `HAVING`, `FILTER`, and `CASE` for conditional counts. `COUNT(*)` is faster on large tables because it skips null-checking; for approximate distinct counts at scale, use extensions like `postgresql-hll` or estimate from `pg_class.reltuples`.

# Postgres COUNT() function

Count rows or non-null values in a result set

Last updated: 2026-06-05

The Postgres `COUNT()` function counts the number of rows in a result set or the number of non-null values in a specific column.

It's useful for data analysis, reporting, and understanding the size and composition of your datasets. Some common use cases include calculating the total number of records in a table, finding the number of distinct values in a column, or determining how many rows meet certain conditions.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signatures

The `COUNT()` function has two main forms:

```sql
COUNT(*) -> bigint
```

- Counts the total number of rows in the result set.

```sql
COUNT([DISTINCT] expression) -> bigint
```

- Counts the number of rows where the input expression is not NULL.
- `DISTINCT` is an optional keyword, that removes duplicate values before counting.

## Example usage

Consider an `orders` table that tracks orders placed by customers of an online store. It has columns `order_id`, `customer_id`, `product_id`, and `order_date`. We'll use the `COUNT()` function to analyze this data.

```sql
CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INTEGER NOT NULL,
    product_id INTEGER,
    order_amount DECIMAL(10, 2) NOT NULL,
    order_date TIMESTAMP NOT NULL
);

INSERT INTO orders (customer_id, product_id, order_amount, order_date)
VALUES
    (1, 101, 150.00, '2023-01-15 10:30:00'),
    (2, 102, 75.50, '2023-01-16 11:45:00'),
    (1, 103, 200.00, '2023-02-01 09:15:00'),
    (3, 104, 50.25, '2023-02-10 14:20:00'),
    (2, 105, 125.75, '2023-03-05 16:30:00'),
    (4, NULL, 90.00, '2023-03-10 13:00:00'),
    (1, 106, 180.50, '2023-04-02 11:10:00'),
    (3, 107, 60.25, '2023-04-15 10:45:00'),
    (5, 108, 110.00, '2023-05-01 15:20:00'),
    (2, 109, 95.75, '2023-05-20 12:30:00');
```

### Count all rows

To get the total number of orders, you can use `COUNT(*)`:

```sql
SELECT COUNT(*) AS total_orders
FROM orders;
```

This query will return the total number of rows in the `orders` table.

```text
 total_orders
--------------
           10
(1 row)
```

### Count non-null values

To count how many orders have a `product_id` (assuming some orders might not have a product associated):

```sql
SELECT COUNT(product_id) AS orders_with_product
FROM orders;
```

This query will return the number of orders where `product_id` is not NULL.

```text
 orders_with_product
---------------------
                   9
(1 row)
```

### Count distinct values

To find out how many unique customers have placed orders:

```sql
SELECT COUNT(DISTINCT customer_id) AS unique_customers
FROM orders;
```

This query will return the number of distinct `customer_id` values in the `orders` table.

```text
 unique_customers
------------------
                5
(1 row)
```

## Advanced examples

We use the `orders` table created in the previous section to demonstrate more use cases of the `COUNT()` function.

### Combine COUNT() with GROUP BY

You can use `COUNT()` with `GROUP BY` to get counts for different categories:

```sql
SELECT
  DATE_TRUNC('month', order_date) AS month,
  COUNT(*) AS orders_per_month
FROM orders
GROUP BY DATE_TRUNC('month', order_date)
ORDER BY month;
```

This query counts the number of orders for each month.

```text
        month        | orders_per_month
---------------------+------------------
 2023-01-01 00:00:00 |                2
 2023-02-01 00:00:00 |                2
 2023-03-01 00:00:00 |                2
 2023-04-01 00:00:00 |                2
 2023-05-01 00:00:00 |                2
(5 rows)
```

### Use COUNT() in a subquery

You can use `COUNT()` in a subquery to filter based on counts:

```sql
SELECT customer_id, COUNT(*) AS order_count
FROM orders
GROUP BY customer_id
HAVING COUNT(*) > (
  SELECT AVG(order_count)
  FROM (
    SELECT COUNT(*) AS order_count
    FROM orders
    GROUP BY customer_id
  ) AS customer_order_counts
);
```

This query finds customers who have placed more orders than the average number of orders per customer.

```text
 customer_id | order_count
-------------+-------------
           2 |           3
           1 |           3
(2 rows)
```

### Combine COUNT() with CASE

You can use `COUNT()` with `CASE` statements to only count rows that meet specific conditions:

```sql
SELECT
  COUNT(*) AS total_orders,
  COUNT(CASE WHEN order_amount > 100 THEN 1 END) AS high_value_orders,
  COUNT(CASE WHEN order_amount <= 100 THEN 1 END) AS low_value_orders
FROM orders;
```

This query counts the total number of orders, as well as the number of high-value and low-value orders.

```text
 total_orders | high_value_orders | low_value_orders
--------------+-------------------+------------------
           10 |                 5 |                5
(1 row)
```

### Use COUNT() with FILTER clause

Postgres also allows using a `FILTER` clause with aggregate functions, which can be more readable than `CASE` statements:

```sql
SELECT
  COUNT(*) AS total_orders,
  COUNT(*) FILTER (WHERE order_date >= '2023-04-01') AS recent_orders
FROM orders;
```

This query counts the total number of orders, as well as the number of orders placed after April 1, 2023.

```text
 total_orders | recent_orders
--------------+---------------
           10 |             4
(1 row)
```

## Additional considerations

### Performance implications

`COUNT(*)` is generally faster than `COUNT(column)` or `COUNT(DISTINCT column)` because it doesn't need to check for NULL values or uniqueness. However, on very large tables, even `COUNT(*)` can be slow if it needs to scan the entire table.

For frequently used counts, consider maintaining a separate counter table or using materialized views to improve performance.

### NULL handling

Both `COUNT(column)` and `COUNT(DISTINCT column)` expressions do not count NULL values. If you need to include NULL values in your count, use `COUNT(*)` or `COUNT(COALESCE(column, 0))`.

### Alternative approaches

- For approximate counts of distinct values in very large datasets, consider using the `pg_stat_statements` extension or the `HyperLogLog` algorithm (available through extensions like `postgresql-hll`).
- For faster counts on large tables, consider using estimate counts based on table statistics with `pg_class.reltuples`.

## Resources

- [PostgreSQL documentation: Aggregate Functions](https://www.postgresql.org/docs/current/functions-aggregate.html)
- [PostgreSQL documentation: FILTER Clause for Aggregate Functions](https://www.postgresql.org/docs/current/sql-expressions.html#SYNTAX-AGGREGATES)

--- [Document source](https://neon.com/docs/functions/current_timestamp.md) ---

> Summary: The Postgres `current_timestamp` function returns the current date and time as a `timestamp with time zone`, captured at transaction start, with an optional precision argument (0-6 fractional digits) and `now()` as an alias. Use it to auto-populate audit columns, filter recent rows with interval arithmetic, or drive update triggers that keep `created_at` and `updated_at` in sync. Unlike `clock_timestamp()`, `current_timestamp` stays fixed for the life of the transaction, which matters for consistent multi-row inserts.

# Postgres current_timestamp() function

Get the current date and time

Last updated: 2026-06-05

The Postgres `current_timestamp()` function returns the current date and time with timezone. The `now()` function is an alias.

Use it for timestamping database entries, calculating time differences, or implementing time-based business logic. For example, you can use it to record the time a user logs in, or when the status of a purchase order changes. Fetching the current time information can also be used to calculate time-based metrics and schedule periodic tasks.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `current_timestamp()` function has two forms:

```sql
current_timestamp -> timestamp with timezone
```

This form returns the current timestamp with timezone at the start of the current transaction. Note that there are no parentheses in this form.

```sql
current_timestamp(precision) -> timestamp with timezone
```

- `precision` (optional): An integer specifying the number of fractional digits in the seconds field. It can range from 0 to 6. If omitted, the result has the full available precision.

## Example usage

Let's consider a table called `user_logins` that tracks user login activity. We can use `current_timestamp` to record the exact time a user logs in.

```sql
CREATE TABLE user_logins (
  user_id INT,
  login_time TIMESTAMP WITH TIME ZONE
);
```

This `INSERT` query adds a new login record with the current timestamp.

```sql
INSERT INTO user_logins (user_id, login_time)
VALUES (1, current_timestamp);

SELECT * FROM user_logins;
```

The `SELECT` query retrieves the login record, showing the user ID and the timestamp of the login.

```text
 user_id |          login_time
---------+------------------------------
       1 | 2024-06-25 07:31:32.85829+00
(1 row)
```

We can also specify `current_timestamp` as the default value for a timestamp column when creating the table. For example, consider the query below, where we set up a table to track purchase orders and add some records:

```sql
CREATE TABLE purchase_orders (
  order_id SERIAL PRIMARY KEY,
  order_date TIMESTAMP WITH TIME ZONE DEFAULT current_timestamp
);

INSERT INTO purchase_orders (order_id)
VALUES (1);
INSERT INTO purchase_orders (order_id)
VALUES (2);
```

This query creates a table to store purchase orders, with the `order_date` column set to the current timestamp by default. When inserting new records, the `order_date` column will automatically be populated with the current timestamp.

```sql
SELECT * FROM purchase_orders;
```

This query retrieves all purchase orders, showing the order ID and the timestamp when each order was created.

```text
 order_id |          order_date
----------+-------------------------------
        1 | 2024-06-25 07:39:15.241256+00
        2 | 2024-06-25 07:39:15.307045+00
(2 rows)
```

## Advanced examples

### Use `current_timestamp` to query recent data

We can use `current_timestamp` in a `SELECT` statement to compare with stored timestamps and fetch recent records. For example, to retrieve all login records from the past 6 hours, you can use `current_timestamp` in the `WHERE` clause:

```sql
WITH user_logins(user_id, login_time) AS (
  VALUES
    (1, current_timestamp - INTERVAL '2 hours'),
    (2, current_timestamp - INTERVAL '12 hours'),
    (3, current_timestamp - INTERVAL '23 hours'),
    (4, current_timestamp - INTERVAL '1 day 2 hours'),
    (5, current_timestamp - INTERVAL '30 minutes'),
    (1, current_timestamp - INTERVAL '45 minutes'),
    (2, current_timestamp - INTERVAL '18 hours'),
    (6, current_timestamp - INTERVAL '5 minutes')
)
SELECT
  user_id,
  login_time,
  current_timestamp - login_time AS time_since_login
FROM user_logins
WHERE login_time > current_timestamp - INTERVAL '6 hours';
```

This query retrieves all logins from the past 6 hours and calculates how long ago each login occurred.

```text
 user_id |          login_time           | time_since_login
---------+-------------------------------+------------------
       1 | 2024-06-25 05:48:53.094862+00 | 02:00:00
       5 | 2024-06-25 07:18:53.094862+00 | 00:30:00
       1 | 2024-06-25 07:03:53.094862+00 | 00:45:00
       6 | 2024-06-25 07:43:53.094862+00 | 00:05:00
(4 rows)
```

### Specify timestamp precision for `current_timestamp`

You can specify the precision of the timestamp when needed:

```sql
SELECT
    current_timestamp(3) AS ts_with_milliseconds,
    current_timestamp(6) AS ts_with_microseconds,
    current_timestamp(0) AS ts_without_fraction;
```

This query computes the current timestamp value with different levels of precision: milliseconds, microseconds, and without fractional seconds.

```text
    ts_with_milliseconds    |     ts_with_microseconds      |  ts_without_fraction
----------------------------+-------------------------------+------------------------
 2024-06-25 07:52:14.903+00 | 2024-06-25 07:52:14.903483+00 | 2024-06-25 07:52:15+00
(1 row)
```

### Use `current_timestamp` with triggers

You can use `current_timestamp` in combination with a default value and an update trigger to automatically maintain creation and modification timestamps for records. For example, run the following query to create a table storing articles for a blog:

```sql
CREATE TABLE articles (
  id SERIAL PRIMARY KEY,
  title TEXT,
  content TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT current_timestamp(3),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT current_timestamp(3)
);

CREATE OR REPLACE FUNCTION update_modified_column()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_at = current_timestamp(3);
    RETURN NEW;
END;
$$ language 'plpgsql';

CREATE TRIGGER update_article_modtime
BEFORE UPDATE ON articles
FOR EACH ROW
EXECUTE FUNCTION update_modified_column();

INSERT INTO articles (title, content) VALUES ('First Article', 'Content here');
INSERT INTO articles (title, content) VALUES ('Second Article', 'Content here');
```

This query creates a table to store articles, with columns for the title, content, and creation and update timestamps. It also defines a trigger that updates the `updated_at` column whenever an article is modified. To verify, run the following query that updates the content for the first article:

```sql
SELECT pg_sleep(1); -- simulate some delay before update

UPDATE articles SET content = 'Updated content' WHERE id = 1;
SELECT * FROM articles;
```

This query returns the following output, showing the updated content and the update timestamp for the first article:

```text
 id |     title      |     content     |         created_at         |         updated_at
----+----------------+-----------------+----------------------------+----------------------------
  2 | Second Article | Content here    | 2024-06-25 08:04:50.343+00 | 2024-06-25 08:04:50.343+00
  1 | First Article  | Updated content | 2024-06-25 08:04:50.277+00 | 2024-06-25 08:04:57.297+00
(2 rows)
```

## Additional considerations

### Timezone awareness

`current_timestamp` returns a value in the timezone of the current session, which defaults to the server's timezone unless explicitly set in the session. This is important to note when working with timestamps across different timezones.

### Alternative functions

- `now()` - An alias for `current_timestamp`.
- `transaction_timestamp()` - Returns the current timestamp at the start of the current transaction. Equivalent to `current_timestamp`.
- `statement_timestamp()` - Returns the current timestamp at the start of the current statement.
- `clock_timestamp()` - Returns the current timestamp, changing even within a single SQL statement.

## Resources

- [PostgreSQL documentation: Date/Time Functions and Operators](https://www.postgresql.org/docs/current/functions-datetime.html)
- [PostgreSQL documentation: Date/Time Types](https://www.postgresql.org/docs/current/datatype-datetime.html)

--- [Document source](https://neon.com/docs/functions/date_trunc.md) ---

> Summary: The Postgres `date_trunc()` function truncates a timestamp or interval to a named precision level, zeroing all less-significant fields. It's the standard way to group time-series data by hour, day, week, month, quarter, year, or other supported units. Use it to bucket events for aggregation, generate periodic reports, or filter rows by calendar period without manual date arithmetic. The optional time_zone parameter controls which local day or week boundary is used for truncation. The function also accepts interval values, though truncation to calendar units (month, year) only works when the interval stores those components explicitly.

# Postgres date_trunc() function

Truncate date and time values to a specified precision

Last updated: 2026-06-05

The Postgres `date_trunc()` function truncates a timestamp or interval to a specified precision.

Use it for grouping time-series data and performing time-based calculations. For example, it can be used to generate monthly reports, analyze hourly trends, or group events by time period.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `date_trunc()` function has the following form:

```sql
date_trunc(field, source [, time_zone ]) -> timestamp / interval
```

- `field`: A string literal specifying the precision to which to truncate the input value. Valid values include `microseconds`, `milliseconds`, `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`, `decade`, `century`, and `millennium`.
- `source`: The timestamp or interval value to be truncated.
- `time_zone` (optional): The timezone in which to perform the truncation. Otherwise, the default timezone is used.

The function returns a timestamp or interval value truncated to the specified precision, i.e., fields less significant than the specified precision are set to zero.

## Example usage

Let's consider a table called `sales` that tracks daily sales data. We can use `date_trunc` to group sales by different time periods.

```sql
CREATE TABLE sales (
  sale_date TIMESTAMP WITH TIME ZONE,
  amount DECIMAL(10, 2)
);

INSERT INTO sales (sale_date, amount) VALUES
  ('2024-03-01 08:30:00+00', 100.50),
  ('2024-03-01 14:45:00+00', 200.75),
  ('2024-03-02 10:15:00+00', 150.25),
  ('2024-04-15 09:00:00+00', 300.00),
  ('2024-05-20 16:30:00+00', 250.50);

-- Group sales by month
SELECT
  date_trunc('month', sale_date) AS month,
  SUM(amount) AS total_sales
FROM sales
GROUP BY date_trunc('month', sale_date)
ORDER BY month;
```

This query groups sales by month, summing the total sales for each month.

```text
         month          | total_sales
------------------------+-------------
 2024-03-01 00:00:00+00 |      451.50
 2024-04-01 00:00:00+00 |      300.00
 2024-05-01 00:00:00+00 |      250.50
(3 rows)
```

We can further refine the output by extracting the month and year from the truncated timestamp:

```sql
SELECT
  EXTRACT(YEAR FROM date_trunc('month', sale_date)) AS year,
  EXTRACT(MONTH FROM date_trunc('month', sale_date)) AS month,
  SUM(amount) AS total_sales
FROM sales
GROUP BY year, month
ORDER BY year, month;
```

This query groups sales by year and month, providing a more readable output:

```text
 year | month | total_sales
------+-------+-------------
 2024 |     3 |      451.50
 2024 |     4 |      300.00
 2024 |     5 |      250.50
(3 rows)
```

## Advanced examples

### Use `date_trunc` with different precisions

We can use `date_trunc` with different precision levels to analyze data at each granularity:

```sql
WITH sample_data(event_time) AS (
  VALUES
    ('2024-03-15 14:30:45.123456+00'::TIMESTAMP WITH TIME ZONE),
    ('2024-06-22 09:15:30.987654+00'::TIMESTAMP WITH TIME ZONE),
    ('2024-11-07 23:59:59.999999+00'::TIMESTAMP WITH TIME ZONE)
)
SELECT
  event_time,
  date_trunc('year', event_time) AS year_trunc,
  date_trunc('quarter', event_time) AS quarter_trunc,
  date_trunc('month', event_time) AS month_trunc,
  date_trunc('week', event_time) AS week_trunc,
  date_trunc('day', event_time) AS day_trunc,
  date_trunc('hour', event_time) AS hour_trunc,
  date_trunc('minute', event_time) AS minute_trunc,
  date_trunc('second', event_time) AS second_trunc,
  date_trunc('millisecond', event_time) AS millisecond_trunc
FROM sample_data;
```

This query demonstrates how `date_trunc` works with different precision levels, from year down to millisecond.

```text
          event_time           |       year_trunc       |     quarter_trunc      |      month_trunc       |       week_trunc       |       day_trunc        |       hour_trunc       |      minute_trunc      |      second_trunc      |     millisecond_trunc
-------------------------------+------------------------+------------------------+------------------------+------------------------+------------------------+------------------------+------------------------+------------------------+----------------------------
 2024-03-15 14:30:45.123456+00 | 2024-01-01 00:00:00+00 | 2024-01-01 00:00:00+00 | 2024-03-01 00:00:00+00 | 2024-03-11 00:00:00+00 | 2024-03-15 00:00:00+00 | 2024-03-15 14:00:00+00 | 2024-03-15 14:30:00+00 | 2024-03-15 14:30:45+00 | 2024-03-15 14:30:45.123+00
 2024-06-22 09:15:30.987654+00 | 2024-01-01 00:00:00+00 | 2024-04-01 00:00:00+00 | 2024-06-01 00:00:00+00 | 2024-06-17 00:00:00+00 | 2024-06-22 00:00:00+00 | 2024-06-22 09:00:00+00 | 2024-06-22 09:15:00+00 | 2024-06-22 09:15:30+00 | 2024-06-22 09:15:30.987+00
 2024-11-07 23:59:59.999999+00 | 2024-01-01 00:00:00+00 | 2024-10-01 00:00:00+00 | 2024-11-01 00:00:00+00 | 2024-11-04 00:00:00+00 | 2024-11-07 00:00:00+00 | 2024-11-07 23:00:00+00 | 2024-11-07 23:59:00+00 | 2024-11-07 23:59:59+00 | 2024-11-07 23:59:59.999+00
(3 rows)
```

### Use `date_trunc` with timezones

The `date_trunc` function can be used with specific timezones:

```sql
SELECT
  date_trunc('day', '2024-03-15 23:30:00+00'::TIMESTAMP WITH TIME ZONE) AS utc_trunc,
  date_trunc('day', '2024-03-15 23:30:00+00'::TIMESTAMP WITH TIME ZONE, 'America/New_York') AS ny_trunc,
  date_trunc('day', '2024-03-15 23:30:00+00'::TIMESTAMP WITH TIME ZONE, 'Asia/Tokyo') AS tokyo_trunc;
```

This query shows how `date_trunc` behaves differently when truncating to the day in different timezones.

```text
       utc_trunc        |        ny_trunc        |      tokyo_trunc
------------------------+------------------------+------------------------
 2024-03-15 00:00:00+00 | 2024-03-15 04:00:00+00 | 2024-03-15 15:00:00+00
(1 row)
```

### Use `date_trunc` for time-based analysis

Below, we use `date_trunc` to analyze user activity patterns for a hypothetical social media application:

```sql
CREATE TABLE user_activities (
  user_id INT,
  activity_type VARCHAR(50),
  activity_time TIMESTAMP WITH TIME ZONE
);

INSERT INTO user_activities (user_id, activity_type, activity_time) VALUES
  (1, 'login', '2024-03-01 08:30:00+00'),
  (2, 'login', '2024-03-01 12:30:00+00'),
  (2, 'post', '2024-03-03 09:15:00+00'),
  (1, 'comment', '2024-03-05 10:45:00+00'),
  (3, 'login', '2024-03-08 14:00:00+00'),
  (2, 'logout', '2024-03-08 16:30:00+00'),
  (1, 'logout', '2024-03-12 18:00:00+00'),
  (3, 'post', '2024-03-15 19:30:00+00'),
  (3, 'logout', '2024-03-18 20:45:00+00');


-- Analyze daily activity pattern
SELECT
  date_trunc('day', activity_time) AS day,
  activity_type,
  COUNT(*) AS activity_count
FROM user_activities
GROUP BY date_trunc('day', activity_time), activity_type
ORDER BY day, activity_type;
```

This query uses `date_trunc` to group user activities by each day.

```text
          day           | activity_type | activity_count
------------------------+---------------+----------------
 2024-03-01 00:00:00+00 | login         |              2
 2024-03-03 00:00:00+00 | post          |              1
 2024-03-05 00:00:00+00 | comment       |              1
 2024-03-08 00:00:00+00 | login         |              1
 2024-03-08 00:00:00+00 | logout        |              1
 2024-03-12 00:00:00+00 | logout        |              1
 2024-03-15 00:00:00+00 | post          |              1
 2024-03-18 00:00:00+00 | logout        |              1
(8 rows)
```

### Use `date_trunc` with interval types

The `date_trunc` function can also be used with interval data:

```sql
SELECT
  date_trunc('hour', INTERVAL '2 days 3 hours 40 minutes') AS truncated_interval,
  date_trunc('day', '2024-03-15 23:30:00+00'::TIMESTAMPTZ - '2023-09-14 11:20:00+00'::TIMESTAMPTZ) AS truncated_day;
```

This query truncates the first interval to the nearest hour, while the second column truncates the difference between two timestamps to the nearest day.

```text
 truncated_interval | truncated_day
--------------------+---------------
 2 days 03:00:00    | 183 days
(1 row)
```

## Additional considerations

### Timezone awareness

When using `date_trunc` with timestamps, the function uses the default timezone of the session, or that specified in the input. As shown in the previous section, the truncation result can vary depending on the timezone.

### Truncating intervals

When truncating intervals, the `date_trunc` function rounds the interval to the nearest value based on the specified precision. However, note that the output might not be intuitive and depends on how the interval is defined.

For example, the query below attempts to truncate a month from an interval specified as some number of days.

```sql
SELECT
    date_trunc('month', '183 days'::INTERVAL) AS colA,
    date_trunc('month', '2 years 3 months'::INTERVAL) AS colB;
```

This query outputs the following:

```text
   cola   |      colb
----------+----------------
 00:00:00 | 2 years 3 mons
(1 row)
```

The first input interval didn't have a month component, so even with the number of days being bigger than a month, the output is zero. The second input interval has a month component, so the output is the input interval truncated to the month.

### Performance considerations

When using `date_trunc` in WHERE clauses or for grouping large datasets, consider creating an index on the truncated values to improve query performance:

```sql
CREATE INDEX idx_sales_month ON sales (date_trunc('month', sale_date));
```

This creates an index on the monthly truncated sale dates, which can speed up queries that group or filter by month.

## Resources

- [PostgreSQL documentation: Date/Time Functions and Operators](https://www.postgresql.org/docs/current/functions-datetime.html)
- [PostgreSQL documentation: Date/Time Types](https://www.postgresql.org/docs/current/datatype-datetime.html)

--- [Document source](https://neon.com/docs/functions/dense_rank.md) ---

> Summary: The PostgreSQL `dense_rank()` window function assigns consecutive integer ranks to rows within an ordered partition, giving tied rows the same rank and never skipping rank values, unlike `rank()` which leaves gaps after ties. Use `dense_rank()` when you need contiguous rankings for leaderboards, scoring systems, or top-N filtering via a CTE. The function accepts `PARTITION BY` to reset ranking within groups, and pairs with aggregate functions such as `COUNT`, `SUM`, and `AVG`.

# Postgres dense_rank() function

Returns the rank of the current row without gaps

Last updated: 2026-06-05

You can use the `dense_rank` function to assign a rank to each distinct row within a result set. It provides a non-gapped ranking of values which is the right choice when ties need to be acknowledged without leaving gaps in the ranking sequence.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
dense_rank() OVER (
   [PARTITION BY partition_expression, ... ]
   ORDER BY sort_expression [ASC | DESC], ...
)
```

## `dense_rank` example

Let's say we have a `student_scores` table of students along with their name and score:

```sql
CREATE TABLE student_scores (
   student_id SERIAL PRIMARY KEY,
   student_name VARCHAR(50) NOT NULL,
   score INT NOT NULL
);

INSERT INTO student_scores (student_name, score) VALUES
   ('Alice', 85),
   ('Bob', 92),
   ('Charlie', 78),
   ('David', 92),
   ('Eve', 85),
   ('Frank', 78);
```

**student_scores**

```
| student_id | student_name | score |
|------------|--------------|-------|
| 1          | Alice        | 85    |
| 2          | Bob          | 92    |
| 3          | Charlie      | 78    |
| 4          | David        | 92    |
| 5          | Eve          | 85    |
| 6          | Frank        | 78    |
```

You can use `dense_rank` to assign a rank to each row in the result set:

```sql
SELECT
   student_id,
   student_name,
   score,
   dense_rank() OVER (ORDER BY score DESC) AS rank
FROM
   student_scores;
```

This query returns the following values:

```
| student_id | student_name | score | rank |
|------------|--------------|-------|------|
| 2          | Bob          | 92    | 1    |
| 4          | David        | 92    | 1    |
| 1          | Alice        | 85    | 2    |
| 5          | Eve          | 85    | 2    |
| 3          | Charlie      | 78    | 3    |
| 6          | Frank        | 78    | 3    |
```

## Advanced examples

This section shows advanced usage examples for the `dense_rank` function.

### `dense_rank` with `PARTITION BY` and `ORDER BY` clause

Let's modify the previous example to include a `class_id` column to represent different classes:

**student_scores_by_class**

```sql
CREATE TABLE student_scores_by_class (
   student_id SERIAL PRIMARY KEY,
   student_name VARCHAR(50) NOT NULL,
   score INT NOT NULL,
   class_id INT NOT NULL
);

INSERT INTO student_scores_by_class (student_name, score, class_id) VALUES
   ('Alice', 85, 1),
   ('Bob', 92, 1),
   ('Charlie', 78, 1),
   ('David', 92, 2),
   ('Eve', 85, 2),
   ('Frank', 78, 2);
```

```
| student_id | student_name | score | class_id |
|------------|--------------|-------|----------|
| 1          | Alice        | 85    | 1        |
| 2          | Bob          | 92    | 1        |
| 3          | Charlie      | 78    | 1        |
| 4          | David        | 92    | 2        |
| 5          | Eve          | 85    | 2        |
| 6          | Frank        | 78    | 2        |
```

The `PARTITION BY` clause below is used in conjunction with ranking function to divide the result set into partitions based on one or more columns. Within each partition, the ranking function operates independently.

```sql
SELECT
   student_id,
   student_name,
   score,
   class_id,
   dense_rank() OVER (PARTITION BY class_id ORDER BY score DESC) AS rank_within_class
FROM
   student_scores_by_class;
```

This query returns the following values:

```
| student_id | student_name | score | class_id | rank_within_class |
|------------|--------------|-------|----------|-------------------|
| 2          | Bob          | 92    | 1        | 1                 |
| 1          | Alice        | 85    | 1        | 2                 |
| 3          | Charlie      | 78    | 1        | 3                 |
| 4          | David        | 92    | 2        | 1                 |
| 5          | Eve          | 85    | 2        | 2                 |
| 6          | Frank        | 78    | 2        | 3                 |
```

This partitions the result set into two groups based on the `class_id` column, and the ranking is performed independently within each class. As a result, students are ranked within their respective classes, and the ranking starts fresh for each class.

### Filter `dense_rank` results in `WHERE` clause

To filter on `dense_rank` results in a `WHERE` clause, move the function into a common table expression (CTE).

Let's say you want to find the dense rank for the top two scores within each class:

```sql
WITH RankedScores AS (
   SELECT
       student_id,
       student_name,
       score,
       class_id,
       dense_rank() OVER (PARTITION BY class_id ORDER BY score DESC) AS dense_rank
   FROM
       student_scores_by_class
)
SELECT
   student_id,
   student_name,
   score,
   class_id,
   dense_rank
FROM
   RankedScores
WHERE
   dense_rank <= 2;
```

This query returns the following values:

```
| student_id | student_name | score | class_id | dense_rank |
|------------|--------------|-------|----------|------------|
| 2          | Bob          | 92    | 1        | 1          |
| 1          | Alice        | 85    | 1        | 2          |
| 4          | David        | 92    | 2        | 1          |
| 5          | Eve          | 85    | 2        | 2          |
```

## Additional considerations

This section covers additional considerations for the `dense_rank` function.

### How is `dense_rank` different from the `rank` function?

The `rank` function assigns a unique rank to each distinct row in the result set and leaves gaps in the ranking sequence when there are ties.
If two or more rows have the same values and are assigned the same rank, the next rank will be skipped.

```sql
SELECT
   student_id,
   student_name,
   score,
   rank() OVER (ORDER BY score DESC) AS rank
FROM
   student_scores;
```

This query returns the following values:

```
| student_id | student_name | score | rank |
|------------|--------------|-------|------|
| 2          | Bob          | 92    | 1    |
| 4          | David        | 92    | 1    |
| 1          | Alice        | 85    | 3    |
| 5          | Eve          | 85    | 3    |
| 3          | Charlie      | 78    | 5    |
| 6          | Frank        | 78    | 5    |
```

Alice and Eve, who share the second-highest score, have ranks 3 and 5, and there is a gap in the ranking sequence. When using `dense_rank`, Alice and Eve, who share the second-highest score, both have a rank of 2, and there is no gap in the ranking sequence.

### Aggregations

You can combine `dense_rank` with other functions like `COUNT`, `SUM`, `AVG` for aggregations.

Use with `COUNT`:

```sql
SELECT class_id, dense_rank() OVER (ORDER BY COUNT(*) DESC) AS student_count_rank, COUNT(*) AS student_count
FROM student_scores_by_class
GROUP BY class_id;
```

This query returns the following values:

```text
| class_id | student_count_rank | student_count   |
|-----------|---------------------|---------------|
|     2     |          1          |       3       |
|     1     |          1          |       3       |
```

Use with `SUM`:

```sql
SELECT class_id, dense_rank() OVER (ORDER BY SUM(score) DESC) AS total_score_rank, SUM(score) AS total_score
FROM student_scores_by_class
GROUP BY class_id;
```

This query ranks the classes based on their total scores, assigning the highest rank to the class with the highest total score.

This query returns the following values:

```
| class_id | total_score_rank   | total_score |
|-----------|-------------------|-------------|
|     2     |         1         |     255     |
|     1     |         1         |     255     |
```

Use with `AVG`:

```sql
SELECT class_id, dense_rank() OVER (ORDER BY AVG(score) DESC) AS average_score_rank, AVG(score) AS average_score
FROM student_scores_by_class
GROUP BY class_id;
```

This query ranks the classes based on their average scores, assigning the highest rank to the class with the highest average score.

This query returns the following values:

```
| class_id  | average_score_rank  |    average_score    |
|-----------|---------------------|---------------------|
|     2     |          1          | 85.0000000000000000 |
|     1     |          1          | 85.0000000000000000 |
```

### Indexing

Creating indexes on the columns specified in the `ORDER BY` (sorting) and `PARTITION BY` (partitioning) clauses can significantly improve performance. In this case, queries on the `student_scores` table would benefit from creating indexes on `class_id` and `score` columns.

## Resources

- [PostgreSQL documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/extract.md) ---

> Summary: The Postgres `extract()` function returns a single numeric date/time component (year, month, day, hour, quarter, epoch, isodow, milliseconds, and others) from a timestamp, date, time, or interval value. Use it when you need to group, filter, or aggregate rows by a specific date part, such as counting events per quarter, analyzing registration patterns by hour, or computing age from a birth date. For non-normalized intervals, the function returns the remainder after converting to the next higher unit, so `EXTRACT(MONTH FROM INTERVAL '32 months')` returns 8, not 32.

# Postgres extract() function

Extract date and time components from timestamps and intervals

Last updated: 2026-06-05

The Postgres `extract()` function retrieves specific components (such as year, month, or day) from date/time values where the source is of the type `timestamp`, `date`, `time` or `interval`.

Use it for data analysis, reporting, and manipulating date and time data. For example, it can be used to group data by year, filter records for specific months, or calculate age based on birth dates.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `extract()` function has the following form:

```sql
extract(field FROM source) -> numeric
```

- `field`: A string literal specifying the component to extract. Valid values include `century`, `day`, `decade`, `dow`, `doy`, `epoch`, `hour`, `isodow`, `isoyear`, `microseconds`, `millennium`, `milliseconds`, `minute`, `month`, `quarter`, `second`, `timezone`, `timezone_hour`, `timezone_minute`, `week`, and `year`.
- `source`: The date, time, timestamp, or interval value from which to extract the component.

The function returns a numeric value representing the extracted component.

## Example usage

Let's consider a table called `events` that tracks various events with their timestamps. We can use `extract()` to analyze different aspects of these events.

```sql
CREATE TABLE events (
  event_id SERIAL PRIMARY KEY,
  event_name VARCHAR(100),
  event_timestamp TIMESTAMP WITH TIME ZONE
);

INSERT INTO events (event_name, event_timestamp) VALUES
  ('Conference A', '2024-03-15 09:00:00+00'),
  ('Workshop B', '2024-06-22 14:30:00+00'),
  ('Seminar C', '2024-09-10 11:15:00+00'),
  ('Conference D', '2024-12-05 10:00:00+00'),
  ('Workshop E', '2025-02-18 13:45:00+00');

-- Extract year and month from event timestamps
SELECT
  event_name,
  EXTRACT(YEAR FROM event_timestamp) AS event_year,
  EXTRACT(MONTH FROM event_timestamp) AS event_month
FROM events
ORDER BY event_timestamp;
```

This query extracts the year and month from each event's timestamp.

```text
  event_name  | event_year | event_month
--------------+------------+-------------
 Conference A |       2024 |           3
 Workshop B   |       2024 |           6
 Seminar C    |       2024 |           9
 Conference D |       2024 |          12
 Workshop E   |       2025 |           2
(5 rows)
```

You can use the extracted components for further analysis, filtering, or grouping. For example, we can count the number of events by quarter:

```sql
-- Count events by quarter
SELECT
  EXTRACT(YEAR FROM event_timestamp) AS year,
  EXTRACT(QUARTER FROM event_timestamp) AS quarter,
  COUNT(*) AS event_count
FROM events
GROUP BY year, quarter
ORDER BY year, quarter;
```

This query groups events by year and quarter, providing a count of events for each period.

```text
 year | quarter | event_count
------+---------+-------------
 2024 |       1 |           1
 2024 |       2 |           1
 2024 |       3 |           1
 2024 |       4 |           1
 2025 |       1 |           1
(5 rows)
```

## Advanced examples

### Use `extract()` with different fields

You can use `extract()` with various fields to analyze different components of timestamps:

```sql
WITH sample_data(event_time) AS (
  VALUES
    ('2024-03-15 14:30:45.123456+00'::TIMESTAMP WITH TIME ZONE),
    ('2024-06-22 09:15:30.987654+00'::TIMESTAMP WITH TIME ZONE),
    ('2024-11-07 23:59:59.999999+00'::TIMESTAMP WITH TIME ZONE)
)
SELECT
  event_time,
  EXTRACT(CENTURY FROM event_time) AS century,
  EXTRACT(DECADE FROM event_time) AS decade,
  EXTRACT(YEAR FROM event_time) AS year,
  EXTRACT(QUARTER FROM event_time) AS quarter,
  EXTRACT(MONTH FROM event_time) AS month,
  EXTRACT(WEEK FROM event_time) AS week,
  EXTRACT(DAY FROM event_time) AS day,
  EXTRACT(HOUR FROM event_time) AS hour,
  EXTRACT(MINUTE FROM event_time) AS minute,
  EXTRACT(SECOND FROM event_time) AS second,
  EXTRACT(MILLISECONDS FROM event_time) AS milliseconds,
  EXTRACT(MICROSECONDS FROM event_time) AS microseconds
FROM sample_data;
```

This query demonstrates how `extract()` works with different fields, ranging from `century` to `microseconds`.

```text
          event_time           | century | decade | year | quarter | month | week | day | hour | minute |  second   | milliseconds | microseconds
-------------------------------+---------+--------+------+---------+-------+------+-----+------+--------+-----------+--------------+--------------
 2024-03-15 14:30:45.123456+00 |      21 |    202 | 2024 |       1 |     3 |   11 |  15 |   14 |     30 | 45.123456 |    45123.456 |     45123456
 2024-06-22 09:15:30.987654+00 |      21 |    202 | 2024 |       2 |     6 |   25 |  22 |    9 |     15 | 30.987654 |    30987.654 |     30987654
 2024-11-07 23:59:59.999999+00 |      21 |    202 | 2024 |       4 |    11 |   45 |   7 |   23 |     59 | 59.999999 |    59999.999 |     59999999
(3 rows)
```

### Use `extract()` with interval data

When working with the `INTERVAL` type, the `extract()` function allows you to pull out specific parts of the interval, such as the number of years, months, days, hours, minutes, seconds, and so on.

```sql
SELECT
  EXTRACT(DAYS FROM INTERVAL '2 years 3 months 15 days') AS days,
  EXTRACT(HOURS FROM INTERVAL '36 hours 30 minutes') AS hours,
  EXTRACT(MINUTES FROM INTERVAL '2 hours 45 minutes 30 seconds') AS minutes;
```

This query extracts the specified parts from the interval. Note that the `extract` function extracts only the value for the specified part in the interval. For example, `EXTRACT(DAYS FROM INTERVAL '2 years 3 months 15 days')` returns `15` for days, not the total number of days in the interval.

```text
 days | hours | minutes
------+-------+---------
   15 |    36 |      45
(1 row)
```

Additionally, it should be noted that for non-normalized intervals, the extracted values may not be as expected.

A **normalized interval** automatically converts large units into their equivalent higher units. For example, an interval of `14 months` is normalized to `1 year 2 months` because 12 months make a year.

A **non-normalized interval** keeps the units as specified, without converting to higher units. This is useful when you want to keep intervals in the same unit (like months or minutes) for easier manipulation or calculation.

When extracting values from non-normalized intervals, Postgres returns the remainder after converting to the next higher unit. This can lead to results that might seem counter-intuitive if you expect direct conversion without accounting for normalization.

For example, consider this query and its output:

```sql
SELECT
    EXTRACT(MONTH FROM INTERVAL '32 months') AS months,
    EXTRACT(MINUTE FROM INTERVAL '80 minutes') AS minutes;
```

```text
 months | minutes
--------+---------
      8 |      20
(1 row)
```

**Interval '32 months'**:

- A year is composed of 12 months.
- 32 months can be broken down into 2 years and 8 months (since 32 ÷ 12 = 2 years with a remainder of 8 months).
- When you `EXTRACT(MONTH FROM INTERVAL '32 months')`, it returns 8 because that's the remaining months after accounting for the full years.

**Interval '80 minutes'**:

- An hour is composed of 60 minutes.
- 80 minutes can be broken down into 1 hour and 20 minutes (since 80 ÷ 60 = 1 hour with a remainder of 20 minutes).
- When you `EXTRACT(MINUTE FROM INTERVAL '80 minutes')`, it returns 20 because that's the remaining minutes after accounting for the full hour.

### Use `extract()` for time-based analysis

Let's use `extract()` to analyze user registration patterns for a hypothetical social media application:

```sql
CREATE TABLE user_registrations (
  user_id SERIAL PRIMARY KEY,
  username VARCHAR(50),
  registration_time TIMESTAMP WITH TIME ZONE
);

INSERT INTO user_registrations (username, registration_time) VALUES
  ('user1', '2024-03-15 08:30:00+00'),
  ('user2', '2024-03-15 08:45:00+00'),
  ('user3', '2024-03-15 14:20:00+00'),
  ('user4', '2024-03-16 09:15:00+00'),
  ('user5', '2024-03-16 09:30:00+00'),
  ('user6', '2024-03-16 14:30:00+00'),
  ('user7', '2024-03-17 08:45:00+00'),
  ('user8', '2024-03-17 14:10:00+00'),
  ('user9', '2024-03-17 14:25:00+00'),
  ('user10', '2024-03-17 14:50:00+00');

-- Analyze registration patterns by day of week and hour
SELECT
  EXTRACT(ISODOW FROM registration_time) AS day_of_week,
  EXTRACT(HOUR FROM registration_time) AS hour_of_day,
  COUNT(*) AS registration_count
FROM user_registrations
GROUP BY day_of_week, hour_of_day
ORDER BY day_of_week, hour_of_day;
```

This query uses `extract()` to analyze user registration patterns by day of week and hour of day.

```text
 day_of_week | hour_of_day | registration_count
-------------+-------------+--------------------
           5 |           8 |                  2
           5 |          14 |                  1
           6 |           9 |                  2
           6 |          14 |                  1
           7 |           8 |                  1
           7 |          14 |                  3
(6 rows)
```

## Additional considerations

### Performance considerations

For large datasets, consider creating indexes on frequently extracted components to improve query performance:

```sql
CREATE INDEX idx_events_year_month ON events (EXTRACT(YEAR FROM event_timestamp), EXTRACT(MONTH FROM event_timestamp));
```

This creates an index on the year and month components of the event timestamp, which can speed up queries that filter or group by these components.

## Resources

- [PostgreSQL documentation: Date/Time Functions and Operators](https://www.postgresql.org/docs/current/functions-datetime.html)
- [PostgreSQL documentation: Date/Time Types](https://www.postgresql.org/docs/current/datatype-datetime.html)

--- [Document source](https://neon.com/docs/functions/introduction.md) ---

> Summary: Postgres functions index for Neon, linking to individual guides for aggregate (array_agg, avg, count, max, sum), array, date/time, JSON and JSONB, math, string, and window functions. Use this page as the entry point to find the right built-in function guide rather than searching individual function pages.

# Postgres functions

Last updated: 2026-10-02

_Looking for serverless functions on your Neon branch? See [Neon Functions](https://neon.com/docs/compute/functions/overview)._

Get started with commonly-used Postgres functions with Neon's function guides. For other functions that Postgres supports, visit the official Postgres [Functions and Operators](https://www.postgresql.org/docs/current/functions.html) documentation.

## Aggregate functions

- [array_agg()](https://neon.com/docs/functions/array_agg): Aggregate elements into an array
- [avg()](https://neon.com/docs/functions/avg): Calculate the average of a set of values
- [count()](https://neon.com/docs/functions/count): Count rows or non-null values in a result set
- [max()](https://neon.com/docs/functions/max): Find the maximum value in a set of values
- [sum()](https://neon.com/docs/functions/sum): Calculate the sum of a set of values

## Array functions

- [array_length()](https://neon.com/docs/functions/array_length): Determine the length of an array

## Date / Time functions

- [age()](https://neon.com/docs/functions/age): Calculate the difference between timestamps or between a timestamp and the current date/time
- [current_timestamp](https://neon.com/docs/functions/current_timestamp): Get the current date and time
- [date_trunc()](https://neon.com/docs/functions/date_trunc): Truncate date/time values to a specified precision
- [extract()](https://neon.com/docs/functions/extract): Extract date and time components from timestamps and intervals
- [now()](https://neon.com/docs/functions/now): Get the current date and time

## JSON functions

- [array_to_json()](https://neon.com/docs/functions/array_to_json): Convert an SQL array to a JSON array
- [json()](https://neon.com/docs/functions/json): Transform JSON data into relational views
- [json_agg()](https://neon.com/docs/functions/json_agg): Aggregate values into a JSON array
- [json_array_elements()](https://neon.com/docs/functions/json_array_elements): Expand a JSON array into a set of rows
- [jsonb_array_elements()](https://neon.com/docs/functions/jsonb_array_elements): Expand a JSONB array into a set of rows
- [json_build_object()](https://neon.com/docs/functions/json_build_object): Build a JSON object out of a variadic argument list
- [json_each()](https://neon.com/docs/functions/json_each): Expand JSON into a record per key-value pair
- [json_exists()](https://neon.com/docs/functions/json_exists): Check for Values in JSON Data Using SQL/JSON Path Expressions
- [json_extract_path()](https://neon.com/docs/functions/json_extract_path): Extract a JSON sub-object at the specified path
- [json_extract_path_text()](https://neon.com/docs/functions/json_extract_path_text): Extract a JSON sub-object at the specified path as text
- [json_object()](https://neon.com/docs/functions/json_object): Create a JSON object from key-value pairs
- [json_populate_record()](https://neon.com/docs/functions/json_populate_record): Cast a JSON object to a record
- [json_query()](https://neon.com/docs/functions/json_query): Extract and Transform JSON Values with SQL/JSON Path Expressions
- [json_scalar()](https://neon.com/docs/functions/json_scalar): Convert Text and Binary Data to JSON Values
- [json_serialize()](https://neon.com/docs/functions/json_serialize): Convert JSON Values to Text or Binary Format
- [json_table()](https://neon.com/docs/functions/json_table): Transform JSON data into relational views
- [json_to_record()](https://neon.com/docs/functions/json_to_record): Convert a JSON object to a record
- [json_value()](https://neon.com/docs/functions/json_value): Extract and Convert JSON Scalar Values
- [jsonb_each()](https://neon.com/docs/functions/jsonb_each): Expand JSONB into a record per key-value pair
- [jsonb_extract_path()](https://neon.com/docs/functions/jsonb_extract_path): Extract a JSONB sub-object at the specified path
- [jsonb_extract_path_text()](https://neon.com/docs/functions/jsonb_extract_path_text): Extract a JSONB sub-object at the specified path as text
- [jsonb_object()](https://neon.com/docs/functions/jsonb_object): Create a JSONB object from key-value pairs
- [jsonb_populate_record()](https://neon.com/docs/functions/jsonb_populate_record): Cast a JSONB object to a record
- [jsonb_to_record()](https://neon.com/docs/functions/jsonb_to_record): Convert a JSONB object to a record

## Mathematical functions

- [abs()](https://neon.com/docs/functions/math-abs): Calculate the absolute value of a number
- [random()](https://neon.com/docs/functions/math-random): Generate a random number between 0 and 1
- [round()](https://neon.com/docs/functions/math-round): Round numbers to a specified precision

## String functions

- [concat()](https://neon.com/docs/functions/concat): Concatenate strings
- [lower()](https://neon.com/docs/functions/lower): Convert a string to lowercase
- [substring()](https://neon.com/docs/functions/substring): Extract a substring from a string
- [regexp_match()](https://neon.com/docs/functions/regexp_match): Extract substrings matching a regular expression pattern
- [regexp_replace()](https://neon.com/docs/functions/regexp_replace): Replace substrings matching a regular expression pattern
- [trim()](https://neon.com/docs/functions/trim): Remove leading and trailing characters from a string

## Window functions

- [dense_rank()](https://neon.com/docs/functions/dense_rank): Return the rank of the current row without gaps
- [lag()](https://neon.com/docs/functions/window-lag): Access values from previous rows in a result set
- [lead()](https://neon.com/docs/functions/window-lead): Access values from subsequent rows in a result set
- [rank()](https://neon.com/docs/functions/window-rank): Assign ranks to rows within a result set

--- [Document source](https://neon.com/docs/functions/json_agg.md) ---

> Summary: The Postgres `json_agg()` aggregate function collects values from multiple rows and returns them as a single JSON array, enabling row-to-array denormalization inside a GROUP BY query. Use it when you need to nest related rows as a JSON array within a parent record, such as embedding order items or product reviews for API responses. Related alternatives include `jsonb_agg()` for binary JSON output, `array_agg()` for native Postgres arrays, and `json_agg_strict()` to skip NULL values during aggregation.

# Postgres json_agg() function

Aggregate values into a JSON array

Last updated: 2026-06-05

The Postgres `json_agg()` function is an aggregate function that collects values from multiple rows and returns them as a single JSON array.

Use it when you need to denormalize data for performance or prepare data for front-end applications and APIs. For example, you might use it to aggregate product reviews for an e-commerce application or collect all posts by a user on a social media platform.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `json_agg()` function has this simple form:

```sql
json_agg(expression) -> json
```

- `expression`: The value to be aggregated into a JSON array. This can be a column, a complex expression, or even a subquery.

When used in this manner, the order of the values in the resulting JSON array is not guaranteed. Postgres supports an extended syntax for aggregating values in a specific order.

```sql
json_agg(expression ORDER BY sort_expression [ASC | DESC] [NULLS { FIRST | LAST }]) -> json
```

- `expression`: The value to be aggregated into a JSON array.
- `ORDER BY`: Specifies the order in which the values should be aggregated.
- `sort_expression`: The expression to sort by.
- `ASC | DESC`: Specifies ascending or descending order (default is ASC).
- `NULLS { FIRST | LAST }`: Specifies whether nulls should be first or last in the ordering (default depends on `ASC` or `DESC`).

## Example usage

Consider an `orders` table with columns `order_id`, `product_name`, and `quantity`. We can use `json_agg()` to create a JSON array of all products in each order.

```sql
WITH orders AS (
    SELECT *
    FROM (
        VALUES
            (1, 'Widget A', 2),
            (1, 'Widget B', 1),
            (2, 'Widget C', 3),
            (2, 'Widget D', 2)
    ) AS t(order_id, product_name, quantity)
)
SELECT
  order_id,
  json_agg(json_build_object('product', product_name, 'quantity', quantity)) AS products
FROM orders
GROUP BY order_id;
```

This query groups the orders by `order_id` and creates a JSON array of products for each order.

```text
 order_id |                                       products
----------+--------------------------------------------------------------------------------------
        1 | [{"product" : "Widget A", "quantity" : 2}, {"product" : "Widget B", "quantity" : 1}]
        2 | [{"product" : "Widget C", "quantity" : 3}, {"product" : "Widget D", "quantity" : 2}]
(2 rows)
```

## Advanced examples

### Ordered aggregation

You can specify an order for the aggregated values, as suggested in the function signature section. Here's an example:

```sql
WITH reviews AS (
  SELECT 1 AS product_id, 'Great product!' AS comment, 5 AS rating, '2023-01-15'::date AS review_date
  UNION ALL SELECT 1, 'Could be better', 3, '2023-02-01'::date
  UNION ALL SELECT 1, 'Awesome!', 5, '2023-01-20'::date
  UNION ALL SELECT 2, 'Not bad', 4, '2023-01-10'::date
)
SELECT
  product_id,
  json_agg(
    comment || ' (' || rating || ' stars)'
    ORDER BY review_date DESC
  ) AS reviews
FROM reviews
GROUP BY product_id;
```

This query aggregates product reviews into a JSON array, ordered by the review date in descending order.

```text
 product_id |                                     reviews
------------+---------------------------------------------------------------------------------
          1 | ["Could be better (3 stars)", "Awesome! (5 stars)", "Great product! (5 stars)"]
          2 | ["Not bad (4 stars)"]
(2 rows)
```

### Combining with other JSON functions

`json_agg()` can be combined with other JSON functions for more complex transformations:

```sql
WITH sales AS (
  SELECT 'North' AS region, 'Q1' AS quarter, 100000 AS amount
  UNION ALL SELECT 'North', 'Q2', 120000
  UNION ALL SELECT 'South', 'Q1', 80000
  UNION ALL SELECT 'South', 'Q2', 90000
)
SELECT
    region,
    json_agg(
        (SELECT json_build_object('quarter', quarter, 'amount', amount))
        ORDER BY quarter DESC
    ) AS quarterly_sales
FROM sales
GROUP BY region;
```

This query uses `json_build_object()` in combination with `json_agg()` to create an array of quarterly sales data, for each region.

```text
 region |                                quarterly_sales
--------+--------------------------------------------------------------------------------
 North  | [{"quarter" : "Q2", "amount" : 120000}, {"quarter" : "Q1", "amount" : 100000}]
 South  | [{"quarter" : "Q2", "amount" : 90000}, {"quarter" : "Q1", "amount" : 80000}]
(2 rows)
```

## Additional considerations

### Performance implications

While `json_agg()` is powerful for creating JSON structures, it can be memory-intensive for large datasets since its output size linearly increases with the number of rows. When working with very large tables, consider using pagination or limiting the number of rows aggregated.

### Alternative functions

- `array_agg()`: Aggregates values into a Postgres array instead of a JSON array.
- `jsonb_agg()`: Similar to `json_agg()`, but returns a `jsonb` type, which is more efficient for storage and processing.
- `json_agg_strict()`: Aggregates values into a JSON array, skipping over the NULL values.

## Resources

- [PostgreSQL documentation: Aggregate Functions](https://www.postgresql.org/docs/current/functions-aggregate.html)
- [PostgreSQL documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/json_array_elements.md) ---

> Summary: `json_array_elements(json)` is a PostgreSQL set-returning function that unpacks a JSON array into one row per element, returning each element as a JSON value rather than plain text. Use it to JOIN, filter, or aggregate across array elements stored in a JSON column inside the database, avoiding the cost of shipping full JSON payloads to application code for processing. For binary jsonb columns, `jsonb_array_elements` gives better performance; use `json_array_elements_text` when plain-text output is needed instead of JSON values.

# Postgres json_array_elements() function

Expand a JSON array into a set of rows

Last updated: 2026-06-05

You can use `json_array_elements` function to expand a `JSON` array into a set of rows, each containing one element of the array. It is a simpler option compared to complex looping logic. It is also more efficient than executing the same operation on the application side by reducing data transfer and processing overhead.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
json_array_elements(json)
```

## `json_array_elements` example

Suppose you have a `developers` table with information about developers:

**developers**

```sql
CREATE TABLE developers (
 id INT PRIMARY KEY,
 name TEXT,
 skills JSON
);

INSERT INTO developers (id, name, skills) VALUES
 (1, 'Alice', '["Java", "Python", "SQL"]'),
 (2, 'Bob', '["C++", "JavaScript"]'),
 (3, 'Charlie', '["HTML", "CSS", "React"]');
```

```text
| id |  name   |          skills
|----|---------|---------------------------
| 1  | Alice   | ["Java", "Python", "SQL"]
| 2  | Bob     | ["C++", "JavaScript"]
| 3  | Charlie | ["HTML", "CSS", "React"]
```

Now, let's say you want to extract a row for each skill from the skills `JSON` array. You can use `json_array_elements` to do that:

```sql
SELECT id, name, skill
FROM developers,
    json_array_elements(skills) AS skill;
```

This query returns the following result:

```text
| id |  name   |    skill     |
|----|---------|--------------|
| 1  | Alice   | "Java"       |
| 1  | Alice   | "Python"     |
| 1  | Alice   | "SQL"        |
| 2  | Bob     | "C++"        |
| 2  | Bob     | "JavaScript" |
| 3  | Charlie | "HTML"       |
| 3  | Charlie | "CSS"        |
| 3  | Charlie | "React"      |
```

## Advanced examples

This section shows advanced `json_array_elements` examples.

### `json_array_elements` with nested data

Let's consider a scenario where we have a `products` table storing information about products. The table schema and data are provided below.

**products**

```sql
CREATE TABLE products (
 id INTEGER PRIMARY KEY,
 name TEXT,
 details JSON
);

INSERT INTO products (id, name, details) VALUES
 (1, 'T-Shirt', '{"sizes": ["S", "M", "L", "XL"], "colors": ["Red", "Blue", "Green"]}'),
 (2, 'Hoodie', '{"sizes": ["XS", "S", "M", "L", "XL"], "colors": ["Black", "Gray"]}'),
 (3, 'Dress', '{"sizes": ["S", "M", "L"], "colors": ["Pink", "Purple", "Black"]}'),
 (4, 'Jeans', '{"sizes": ["28", "30", "32", "34"], "colors": ["Blue", "Black"]}'),
 (5, 'Jacket', '{"sizes": ["S", "M", "L", "XL"], "colors": ["Black", "Brown", "Navy"]}');
```

```text
| id |  name   |                                details                                 |
|----|---------|------------------------------------------------------------------------|
| 1  | T-Shirt | {"sizes": ["S", "M", "L", "XL"], "colors": ["Red", "Blue", "Green"]}   |
| 2  | Hoodie  | {"sizes": ["XS", "S", "M", "L", "XL"], "colors": ["Black", "Gray"]}    |
| 3  | Dress   | {"sizes": ["S", "M", "L"], "colors": ["Pink", "Purple", "Black"]}      |
| 4  | Jeans   | {"sizes": ["28", "30", "32", "34"], "colors": ["Blue", "Black"]}       |
| 5  | Jacket  | {"sizes": ["S", "M", "L", "XL"], "colors": ["Black", "Brown", "Navy"]} |
```

The `json_array_elements` function can be used to get all the combinations of size and color for a specific product. For example:

```sql
SELECT
 id,
 name,
 size,
 color
FROM products AS p,
 json_array_elements(p.details -> 'sizes') AS size,
 json_array_elements(p.details -> 'colors') AS color
WHERE name = 'T-Shirt';
```

This query returns the following values:

```text
| id |  name   | size | color  |
|----|---------|------|--------|
| 1  | T-Shirt | "S"  | "Red"  |
| 1  | T-Shirt | "S"  | "Blue" |
| 1  | T-Shirt | "S"  | "Green"|
| 1  | T-Shirt | "M"  | "Red"  |
| 1  | T-Shirt | "M"  | "Blue" |
| 1  | T-Shirt | "M"  | "Green"|
| 1  | T-Shirt | "L"  | "Red"  |
| 1  | T-Shirt | "L"  | "Blue" |
| 1  | T-Shirt | "L"  | "Green"|
| 1  | T-Shirt | "XL" | "Red"  |
| 1  | T-Shirt | "XL" | "Blue" |
| 1  | T-Shirt | "XL" | "Green"|
```

## Filtering `json_array_elements`

You can use the `json_array_elements` function to extract the sizes from the `JSON` data and then filter the products based on a specific color (or size), as in this example:

```sql
SELECT *
FROM products
WHERE 'Blue' IN (
    SELECT json_array_elements_text(details->'colors')
);
```

This query returns the following values:

```text
| id |   name   |                               details                                |
|----|----------|----------------------------------------------------------------------|
|  1 | T-Shirt  | {"sizes": ["S", "M", "L", "XL"], "colors": ["Red", "Blue", "Green"]} |
|  4 | Jeans    | {"sizes": ["28", "30", "32", "34"], "colors": ["Blue", "Black"]}     |
```

## Handling `NULL` in `json_array_elements`

This example updates the table to insert another product (`Socks`) with one of the values in the `sizes` as `null`:

**products**

```sql
INSERT INTO products (id, name, details) VALUES (6, 'Socks', '{"sizes": ["S", null, "L", "XL"], "colors": ["White", "Black", "Gray"]}');
```

```text
| id |  name   |                                 details                                 |
|----|---------|-------------------------------------------------------------------------|
|  6 | Socks   | {"sizes": ["S", null, "L", "XL"], "colors": ["White", "Black", "Gray"]} |
```

Querying for `Socks` shows how `null` values in an array are handled:

```sql
SELECT
 id,
 name,
 size
FROM products AS p,
 json_array_elements(p.details -> 'sizes') AS size
WHERE name = 'Socks';
```

This query returns the following values:

```text
| id | name  | size |
|----|-------|------|
|  6 | Socks | "S"  |
|  6 | Socks | null |
|  6 | Socks | "L"  |
|  6 | Socks | "XL" |
```

### Nested arrays in `json_array_elements`

You can also handle nested arrays with `json_array_elements`.

Consider a scenario where each product has multiple variants, and each variant has an array of sizes and an array of colors. This example uses an `elecronics_products` table, shown below.

**electronics_products**

```sql
CREATE TABLE electronics_products (
 id INTEGER PRIMARY KEY,
 name TEXT,
 details JSON
);

INSERT INTO electronics_products (id, name, details) VALUES
 (1, 'Laptop', '{"variants": [{"model": "A", "sizes": ["13 inch", "15 inch"], "colors": ["Silver", "Black"]}, {"model": "B", "sizes": ["15 inch", "17 inch"], "colors": ["Gray", "White"]}]}'),
 (2, 'Smartphone', '{"variants": [{"model": "X", "sizes": ["5.5 inch", "6 inch"], "colors": ["Black", "Gold"]}, {"model": "Y", "sizes": ["6.2 inch", "6.7 inch"], "colors": ["Blue", "Red"]}]}');
```

```text
| id |    name    |                                                                                   details                                                                                    |
|----|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|  1 | Laptop     | {"variants": [{"model": "A", "sizes": ["13 inch", "15 inch"], "colors": ["Silver", "Black"]}, {"model": "B", "sizes": ["15 inch", "17 inch"], "colors": ["Gray", "White"]}]} |
|  2 | Smartphone | {"variants": [{"model": "X", "sizes": ["5.5 inch", "6 inch"], "colors": ["Black", "Gold"]}, {"model": "Y", "sizes": ["6.2 inch", "6.7 inch"], "colors": ["Blue", "Red"]}]}   |
```

To handle the nested arrays and extract information about each variant, you can use the `json_array_elements` function like this:

```sql
SELECT
 id,
 name,
 variant->>'model' AS model,
 size,
 color
FROM
 electronics_products,
  json_array_elements(details->'variants') AS variant,
  json_array_elements_text(variant->'sizes') AS t1(size),
  json_array_elements_text(variant->'colors') AS t2(color);
```

This query returns the following values:

```text
| id |    name    | model |   size   | color  |
|----|------------|-------|----------|--------|
|  1 | Laptop     | A     | 13 inch  | Silver |
|  1 | Laptop     | A     | 13 inch  | Black  |
|  1 | Laptop     | A     | 15 inch  | Silver |
|  1 | Laptop     | A     | 15 inch  | Black  |
|  1 | Laptop     | B     | 15 inch  | Gray   |
|  1 | Laptop     | B     | 15 inch  | White  |
|  1 | Laptop     | B     | 17 inch  | Gray   |
|  1 | Laptop     | B     | 17 inch  | White  |
|  2 | Smartphone | X     | 5.5 inch | Black  |
|  2 | Smartphone | X     | 5.5 inch | Gold   |
|  2 | Smartphone | X     | 6 inch   | Black  |
|  2 | Smartphone | X     | 6 inch   | Gold   |
|  2 | Smartphone | Y     | 6.2 inch | Blue   |
|  2 | Smartphone | Y     | 6.2 inch | Red    |
|  2 | Smartphone | Y     | 6.7 inch | Blue   |
|  2 | Smartphone | Y     | 6.7 inch | Red    |
```

## Additional considerations

This section outlines additional considerations including alternative functions and `JSON` array order.

### Alternates to `json_array_elements`

- `jsonb_array_elements` - Consider this variant for performance benefits with `jsonb` data. `jsonb_array_elements` only accepts `jsonb` data, while `json_array_elements` works with both `json` and `jsonb`. It is typically faster, especially for larger arrays, due to its optimization for the binary `jsonb` format.
- `json_array_elements_text` - While `json_array_elements` returns each extracted element as a `JSON` value, `json_array_elements_text` returns each extracted element as a plain text _string_.

### Ordering `json_array_elements` output using `WITH ORDINALITY`

If the order of the elements is important, consider using the `WITH ORDINALITY` option:

```sql
SELECT
   id,
   name,
   skill,
   ordinality
FROM
   developers,
   json_array_elements(skills) WITH ORDINALITY AS t(skill, ordinality);
```

This query returns the following values:

```text
| id |  name   |    skill     | ordinality |
|----|---------|--------------|------------|
|  1 | Alice   | "Java"       |          1 |
|  1 | Alice   | "Python"     |          2 |
|  1 | Alice   | "SQL"        |          3 |
|  2 | Bob     | "C++"        |          1 |
|  2 | Bob     | "JavaScript" |          2 |
|  3 | Charlie | "HTML"       |          1 |
|  3 | Charlie | "CSS"        |          2 |
|  3 | Charlie | "React"      |          3 |
```

The `WITH ORDINALITY` option in the query adds an `ordinality` column representing the original order of the skills in the array.

## Resources

- [PostgreSQL documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/json_build_object.md) ---

> Summary: `json_build_object` is a variadic Postgres function that constructs a JSON object from alternating key-value arguments inside a SQL query, avoiding round-trips to application code for JSON serialization. Use it when you need to shape query results into JSON directly in the database, including nested objects, grouped aggregates, and ordered output. For write-heavy or indexed workloads, prefer `jsonb_build_object`, which returns the more efficient `jsonb` type.

# Postgres json_build_object() function

Builds a JSON object out of a variadic argument list

Last updated: 2026-06-05

`json_build_object` is used to construct a JSON object from a set of key-value pairs, creating a JSON representation of a row or set of rows. This has potential performance benefits compared to converting query results to JSON on the application side.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
json_build_object ( VARIADIC "any" ) → json
```

## `json_build_object` example

Let's consider a scenario where we have a table storing information about users:

**users**

```text
| id |   name   | age |   city
|----|----------|-----|----------
| 1  | John Doe |  30 | New York |
| 2  | Jane Doe |  25 | London   |
```

Create the `users` table and insert some data into it:

```sql
CREATE TABLE users (
 id SERIAL PRIMARY KEY,
 name TEXT NOT NULL,
 age INTEGER,
 city TEXT
);

INSERT INTO users (name, age, city)
VALUES ('John Doe', 30, 'New York'),
      ('Jane Doe', 25, 'London');
```

Use `json_build_object` to create a JSON structure with user information:

```sql
SELECT id,
 json_build_object(
   'name', name,
   'age', age,
   'city', city
 ) AS user_data
FROM users;
```

This query returns the following results:

```text
| id |                       user_data
|----|--------------------------------------------------------
| 1  | {"name" : "John Doe", "age" : 30, "city" : "New York"}
| 2  | {"name" : "Jane Doe", "age" : 25, "city" : "London"}
```

## Advanced examples

### Nested objects with `json_build_object`

Let's say we have a table of products with an `attributes` column containing JSON data:

**products**

```text
| id |    name    | price |            description            | category |                     attributes
|----|------------|-------|-----------------------------------|----------|----------------------------------------------------
| 1  | T-Shirt    | 25.99 | A comfortable cotton T-Shirt      | Clothing | {"size": "Medium", "color": "Blue", "rating": 4.5}
| 2  | Coffee Mug | 12.99 | A ceramic mug with a funny design | Kitchen  | {"size": "Small", "color": "White", "rating": 3.8}
| 3  | Sneakers   | 49.99 | Sporty sneakers for everyday use  | Footwear | {"size": "10", "color": "Black", "rating": 4.2}
```

Create the `products` table and insert some data into it:

```sql
CREATE TABLE products (
   id SERIAL PRIMARY KEY,
   name TEXT NOT NULL,
   price DECIMAL(5, 2) NOT NULL,
   description TEXT,
   category TEXT,
   attributes JSON
);

INSERT INTO products (name, price, description, category, attributes)
VALUES
   ('T-Shirt', 25.99, 'A comfortable cotton T-Shirt', 'Clothing', json_build_object(
       'color', 'Blue',
       'size', 'Medium',
       'rating', 4.5
   )),
   ('Coffee Mug', 12.99, 'A ceramic mug with a funny design', 'Kitchen', json_build_object(
       'color', 'White',
       'size', 'Small',
       'rating', 3.8
   )),
   ('Sneakers', 49.99, 'Sporty sneakers for everyday use', 'Footwear', json_build_object(
       'color', 'Black',
       'size', '10',
       'rating', 4.2
   ));
```

Use `json_build_object` to build a nested JSON object that represents the details of individual products:

```sql
SELECT
   id,
   name,
   price,
   json_build_object(
       'category', category,
       'description', description,
       'attributes', json_build_object(
           'color', attributes->>'color',
           'size', attributes->>'size'
       )
   ) AS details
FROM products;
```

This query returns the following results:

```text
| id |    name     | price |                                                               details
|----|-------------|-------|-------------------------------------------------------------------------------------------------------------------------------------
| 1  | T-Shirt     | 25.99 | {"category" : "Clothing", "description" : "A comfortable cotton T-Shirt", "attributes" : {"color" : "Blue", "size" : "Medium"}}
| 2  | Coffee Mug  | 12.99 | {"category" : "Kitchen", "description" : "A ceramic mug with a funny design", "attributes" : {"color" : "White", "size" : "Large"}}
```

### Order `json_build_object` output

Combine `json_build_object` with `ORDER BY` to sort the results based on a specific attribute within the JSON structure.

For example, you can build a `JSON` structure with `json_build_object` from the contents of the above `products` table, and then order the results based on `rating`.

```sql
SELECT
   id,
   name,
   price,
   json_build_object(
       'category', category,
       'description', description,
       'attributes', json_build_object(
           'color', attributes->>'color',
           'size', attributes->>'size',
           'rating', attributes->>'rating'
       )
   ) AS details
FROM products_with_rating
ORDER BY (attributes->>'rating')::NUMERIC DESC;
```

`ORDER BY` was to order the results based on the descending order of rating.

This query returns the following results:

```text
| id |    name    | price |                                                                        details
|----|------------|-------|-------------------------------------------------------------------------------------------------------------------------------------------------------
| 1  | T-Shirt    | 25.99 | {"category" : "Clothing", "description" : "A comfortable cotton T-Shirt", "attributes" : {"color" : "Blue", "size" : "Medium", "rating" : "4.5"}}
| 3  | Sneakers   | 49.99 | {"category" : "Footwear", "description" : "Sporty sneakers for everyday use", "attributes" : {"color" : "Black", "size" : "10", "rating" : "4.2"}}
| 2  | Coffee Mug | 12.99 | {"category" : "Kitchen", "description" : "A ceramic mug with a funny design", "attributes" : {"color" : "White", "size" : "Small", "rating" : "3.8"}}
```

### Grouped `json_build_object` output

To create a `JSON` object that groups the total price for each category of products in the products table:

```sql
SELECT
   category,
   json_build_object(
       'total_price', sum(price)
   ) AS category_total_price
FROM products
GROUP BY category;
```

This query returns the following results:

```text
| category |  category_total_price
|----------|-------------------------
| Kitchen  | {"total_price" : 12.99}
| Clothing | {"total_price" : 25.99}
```

## Additional considerations

### Performance and indexing

The performance of the `json_build_object` depends on various factors including the number of key-value pairs, nested levels (deeply nested objects can be more expensive to build). Consider using `JSONB` data type with `jsonb_build_object` for better performance.

If your `JSON` objects have nested structures, indexing on specific paths within the nested data can be beneficial for targeted queries.

### Alternative functions

Depending on your requirements, you might want to consider similar functions:

- [json_object](https://neon.com/docs/functions/json_object) - Builds a JSON object out of a text array.
- `json_agg` - Aggregates values, as a JSON array.
- `row_to_json` - Returns a row as a JSON object.
- `json_object_agg` - Aggregates key-value pairs into a JSON object.

## Resources

- [PostgreSQL documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/json_each.md) ---

> Summary: `json_each(json)` expands a JSON object into one row per top-level key, returning each key as `text` and its value as `json`, making it the right choice for iterating over a JSON object with an unknown or dynamic schema in SQL. Use it instead of `jsonb_each` when the input column is typed `json` rather than `jsonb`, and instead of `json_each_text` when preserving the JSON type on values matters. For large JSON objects, the row-expansion carries performance overhead; `json_object_keys` is lighter when only the keys are needed.

# Postgres json_each() function

Expands JSON into a record per key-value pair

Last updated: 2026-06-05

The `json_each` function in Postgres is used to expand a `JSON` object into a set of key-value pairs.

It is useful when you need to iterate over a `JSON` object's keys and values, such as when you're working with dynamic `JSON` structures where the schema is not fixed. Another important use case is performing data transformations and analytics.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
json_each(json JSON) -> SETOF record(key text, value json)
```

The function returns a set of rows, each containing a key and the corresponding value for each field in the input `JSON` object. The key is of type `text`, while the value is of type `json`.

## Example usage

Consider a `JSON` object representing a user's profile information. The `JSON` data will have multiple attributes and might look like this:

```json
{
  "username": "johndoe",
  "age": 30,
  "email": "johndoe@example.com"
}
```

We can go over all the fields in the profile `JSON` object using `json_each`, and produce a row for each key-value pair.

```sql
SELECT key, value
FROM json_each('{"username": "johndoe", "age": 30, "email": "johndoe@example.com"}');
```

This query returns the following results:

```text
| key      | value                 |
|----------|-----------------------|
| username | "johndoe"             |
| age      | 30                    |
| email    | "johndoe@example.com" |
```

## Advanced examples

### `json_each` custom column names

You can use `AS` to specify custom column names for the key and value columns.

```sql
SELECT attr_name, attr_value
FROM json_each('{"username": "johndoe", "age": 30, "email": "johndoe@example.com"}')
AS user_data(attr_name, attr_value);
```

This query returns the following results:

```text
| attr_name | attr_value            |
|-----------|-----------------------|
| username  | "johndoe"             |
| age       | 30                    |
| email     | "johndoe@example.com" |
```

### Use `json_each` as a table or row source

Since `json_each` returns a set of rows, you can use it as a table source in a `FROM` clause. This lets us join the expanded `JSON` data in the output with other tables.

Here, we're joining each row in the `user_data` table with the output of `json_each`:

```sql
CREATE TABLE user_data (
    id INT,
    profile JSON
);
INSERT INTO user_data (id, profile)
VALUES
    (123, '{"username": "johndoe", "age": 30, "email": "johndoe@example.com"}'),
    (140, '{"username": "mikesmith", "age": 40, "email": "mikesmith@example.com"}');

SELECT id, key, value
FROM user_data, json_each(user_data.profile);
```

This query returns the following results:

```text
| id  | key      | value                   |
|-----|----------|-------------------------|
| 123 | username | "johndoe"               |
| 123 | age      | 30                      |
| 123 | email    | "johndoe@example.com"   |
| 140 | username | "mikesmith"             |
| 140 | age      | 40                      |
| 140 | email    | "mikesmith@example.com" |
```

## Additional considerations

### Performance implications

When working with large `JSON` objects, `json_each` may lead to performance overhead, as it expands each key-value pair into a separate row.

### Alternative functions

- `json_each_text` - Similar functionality to `json_each` but returns the value as a text type instead of `JSON`.
- `json_object_keys` - It returns only the set of keys in the `JSON` object, without the values.
- `jsonb_each` - It provides the same functionality as `json_each`, but accepts `JSONB` input instead of `JSON`.

## Resources

- [PostgreSQL documentation: JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/json_exists.md) ---

> Summary: `JSON_EXISTS()` is a PostgreSQL 17 SQL/JSON function that returns a boolean indicating whether a SQL/JSON path expression matches any value in a JSON or JSONB input. Use it to validate required JSON fields, filter rows by JSON content, or enforce structure in CHECK constraints without extracting values. Supports a `PASSING` clause for dynamic path variables and an `ON ERROR` clause with `TRUE`, `FALSE`, `UNKNOWN`, or `ERROR` options.

# Postgres JSON_EXISTS() Function

Check for Values in JSON Data Using SQL/JSON Path Expressions

Last updated: 2026-06-05

The `JSON_EXISTS()` function introduced in PostgreSQL 17 provides a powerful way to check for the existence of values within `JSON` data using `SQL/JSON` path expressions. Use it for validating `JSON` structure and implementing conditional logic based on the presence of specific `JSON` elements.

Use `JSON_EXISTS()` when you need to:

- Validate the presence of specific `JSON` paths
- Implement conditional logic based on `JSON` content
- Filter `JSON` data based on complex conditions
- Verify `JSON` structure before processing

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `JSON_EXISTS()` function uses the following syntax:

```sql
JSON_EXISTS(
    context_item,                    -- JSON/JSONB input
    path_expression                  -- SQL/JSON path expression
    [ PASSING { value AS varname } [, ...] ]
    [{ TRUE | FALSE | UNKNOWN | ERROR } ON ERROR ]
) → boolean
```

Parameters:

- `context_item`: `JSON` or `JSONB` input to evaluate
- `path_expression`: `SQL/JSON` path expression to check
- `PASSING`: Optional clause to pass variables for use in the path expression
- `ON ERROR`: Controls behavior when path evaluation fails (defaults to `FALSE`)

## Example usage

Let's explore various ways to use the `JSON_EXISTS()` function with different scenarios and options.

### Basic existence checks

```sql
-- Check if a simple key exists
SELECT JSON_EXISTS('{"name": "Alice", "age": 30}', '$.name');
```

```text
# | json_exists
--------------
1 | t
```

```sql
-- Check for a nested key
SELECT JSON_EXISTS(
    '{"user": {"details": {"email": "alice@example.com"}}}',
    '$.user.details.email'
);
```

```text
# | json_exists
--------------
1 | t
```

### Array operations

```sql
-- Check if array contains any elements
SELECT JSON_EXISTS('{"numbers": [1,2,3,4,5]}', '$.numbers[*]');
```

```text
# | json_exists
--------------
1 | t
```

```sql
-- Check for specific array element
SELECT JSON_EXISTS('{"tags": ["postgres", "json", "database"]}', '$.tags[3]');
```

```text
# | json_exists
--------------
1 | f
```

### Conditional checks

```sql
-- Check for values meeting a condition
SELECT JSON_EXISTS(
    '{"scores": [85, 92, 78, 95]}',
    '$.scores[*] ? (@ > 90)'
);
```

```text
# | json_exists
--------------
1 | t
```

### Using PASSING clause

```sql
-- Check using a variable
SELECT JSON_EXISTS(
    '{"temperature": 25}',
    'strict $.temperature ? (@ > $threshold)'
    PASSING 30 AS threshold
);
```

```text
# | json_exists
--------------
1 | f
```

### Error handling

```sql
-- Default behavior (returns FALSE)
SELECT JSON_EXISTS(
    '{"data": [1,2,3]}',
    'strict $.data[5]'
);
```

```text
# | json_exists
--------------
1 | f
```

```sql
-- Using ERROR ON ERROR
SELECT JSON_EXISTS(
    '{"data": [1,2,3]}',
    'strict $.data[5]'
    ERROR ON ERROR
);
```

```text
ERROR: jsonpath array subscript is out of bounds (SQLSTATE 22033)
```

```sql
-- Using UNKNOWN ON ERROR
SELECT JSON_EXISTS(
    '{"data": [1,2,3]}',
    'strict $.data[5]'
    UNKNOWN ON ERROR
);
```

```text
# | json_exists
--------------
1 |
```

## Practical applications

### Data validation

```sql
-- Validate required fields before insertion
CREATE TABLE user_profiles (
    id SERIAL PRIMARY KEY,
    data JSONB NOT NULL,
    CONSTRAINT valid_profile CHECK (
        JSON_EXISTS(data, '$.email') AND
        JSON_EXISTS(data, '$.username')
    )
);

-- This insert will succeed
INSERT INTO user_profiles (data) VALUES (
    '{"email": "user@example.com", "username": "user123"}'::jsonb
);

-- This insert will fail
INSERT INTO user_profiles (data) VALUES (
    '{"username": "user123"}'::jsonb
);
```

```text
ERROR: new row for relation "user_profiles" violates check constraint "valid_profile" (SQLSTATE 23514)
```

### Conditional queries

```sql
-- Filter records based on JSON content
SELECT *
FROM user_profiles
WHERE JSON_EXISTS(
    data,
    '$.preferences.notifications ? (@ == true)'
);
```

## Best practices

1. Error handling:
   - Use appropriate `ON ERROR` clauses based on your requirements
   - Consider `UNKNOWN ON ERROR` for nullable conditions
   - Use `ERROR ON ERROR` when validation is critical

2. Performance optimization:
   - Create _GIN_ indexes on `JSONB` columns for better performance
   - Use strict mode when path is guaranteed to exist
   - Combine with other `JSON` functions for complex operations

3. Path expressions:
   - Use _lax_ mode (default) for optional paths
   - Leverage path variables with `PASSING` clause for dynamic checks

## Learn more

- [PostgreSQL JSON functions documentation](https://www.postgresql.org/docs/current/functions-json.html)
- [SQL/JSON path language](https://www.postgresql.org/docs/current/functions-json.html#FUNCTIONS-SQLJSON-PATH)

--- [Document source](https://neon.com/docs/functions/json_extract_path_text.md) ---

> Summary: `json_extract_path_text(from_json json, VARIADIC path_elems text[])` navigates a JSON value by a variadic path of text keys and array indexes, returning the result cast to TEXT rather than JSON. Use this function instead of `json_extract_path` when the extracted value will be compared, concatenated, or joined as a string, since the text cast avoids an extra explicit conversion. For binary jsonb columns, prefer `jsonb_extract_path_text`, which offers the same interface with better index support.

# Postgres json_extract_path_text() Function

Extracts a JSON sub-object at the specified path as text

Last updated: 2026-06-05

The `json_extract_path_text` function is designed to simplify extracting text from `JSON` data in Postgres. This function is similar to `json_extract_path`; it also produces the value at the specified path from a `JSON` object but casts it to plain text before returning. This makes it more straightforward for text manipulation and comparison operations.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
json_extract_path_text(from_json json, VARIADIC path_elems text[]) -> TEXT
```

The function accepts a `JSON` object and a variadic list of elements that specify the path to the desired value.

## Example usage

Let's consider a `users` table with a `JSON` column named `profile` containing various user details.

Here's how we can create the table and insert some sample data:

```sql
CREATE TABLE users (
    id INT,
    profile JSON
);

INSERT INTO users (id, profile)
VALUES
    (1, '{"name": "Alice", "contact": {"email": "alice@example.com", "phone": "1234567890"}, "hobbies": ["reading", "cycling", "hiking"]}'),
    (2, '{"name": "Bob", "contact": {"email": "bob@example.com", "phone": "0987654321"}, "hobbies": ["gaming", "cooking"]}');
```

To extract and view the email addresses of all users, we can run the following query:

```sql
SELECT id, json_extract_path_text(profile, 'contact', 'email') as email
FROM users;
```

This query returns the following:

```text
| id | email              |
|----|--------------------|
| 1  | alice@example.com  |
| 2  | bob@example.com    |
```

## Advanced examples

### Use `json_extract_path_text` in Joins

Let's say we have another table, `hobbies`, that includes additional information such as difficulty level and the average cost to practice each hobby.

We can create the `hobbies` table with some sample data with the following statements:

```sql
CREATE TABLE hobbies (
   hobby_id SERIAL PRIMARY KEY,
   hobby_name VARCHAR(255),
   difficulty_level VARCHAR(50),
   average_cost VARCHAR(50)
);

INSERT INTO hobbies (hobby_name, difficulty_level, average_cost)
VALUES
    ('Reading', 'Easy', 'Low'),
    ('Cycling', 'Moderate', 'Medium'),
    ('Gaming', 'Variable', 'High'),
    ('Cooking', 'Variable', 'Low');
```

The `users` table we created previously has a `JSON` column named `profile` that contains information about each user's preferred hobbies. A fun exercise could be to find if a user has any hobbies that are easy to get started with. Then we can recommend they engage with it more often.

To fetch this list, we can run the query below.

```sql
SELECT
  json_extract_path_text(u.profile, 'name') as user_name,
  h.hobby_name
FROM users u
JOIN hobbies h
ON json_extract_path_text(u.profile, 'hobbies') LIKE '%' || lower(h.hobby_name) || '%'
WHERE h.difficulty_level = 'Easy';
```

We use `json_extract_path_text` to extract the list of hobbies for each user, and then check if the name of an easy hobby is present in the list.

This query returns the following:

```text
| user_name | hobby_name |
|-----------|------------|
| Alice     | Reading    |
```

### Extracting values from JSON arrays with `json_extract_path_text`

`json_extract_path_text` can also be used to extract values from `JSON` arrays.

For instance, to extract the first and second hobbies for everyone, we can run the following query:

```sql
SELECT
    json_extract_path_text(profile, 'name') as name,
    json_extract_path_text(profile, 'hobbies', '0') as first_hobby,
    json_extract_path_text(profile, 'hobbies', '1') as second_hobby
FROM users;
```

This query returns the following:

```text
| name  | first_hobby | second_hobby |
|-------|-------------|--------------|
| Alice | reading     | cycling      |
| Bob   | gaming      | cooking      |
```

## Additional considerations

### Performance and indexing

Performance considerations for `json_extract_path_text` are similar to those for `json_extract_path`. It is efficient for extracting data but can be impacted by large `JSON` objects or complex queries. Indexing `JSON` fields can improve performance in some cases.

### Alternative functions

- [json_extract_path](https://neon.com/docs/functions/json_extract_path) - This is a similar function that can extract data from a `JSON` object at the specified path. The difference is that it returns a `JSON` object, while `json_extract_path_text` always returns text. The right function to use depends on what you want to use the output data for.
- [jsonb_extract_path_text](https://neon.com/docs/functions/jsonb_extract_path_text) - This is a similar function that can extract data from a `JSON` object at the specified path. It is more efficient but works only with data of the type `JSONB`.

## Resources

- [PostgreSQL Documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL Documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/json_extract_path.md) ---

> Summary: The `json_extract_path(from_json, path_elems...)` function extracts a nested sub-object from a Postgres `json` column by following a variadic text path, returning the result as a `json` value rather than plain text. Use it instead of `json_extract_path_text` when the extracted value must remain a `json` type for further JSON operations, or over application-side parsing to keep extraction in the database. For `jsonb` columns or large, deeply nested structures where performance matters, prefer `jsonb_extract_path`.

# Postgres json_extract_path() function

Extracts a JSON sub-object at the specified path

Last updated: 2026-06-05

You can use the `json_extract_path` function to extract the value at a specified path within a `JSON` document. This approach is performant compared to querying the entire `JSON` payload and processing it on the application side. Use it when dealing with nested `JSON` structures.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
json_extract_path(from_json JSON, VARIADIC path_elems TEXT[]) -> JSON
```

## Example usage

To illustrate the `json_extract_path` function in Postgres, let's consider a scenario where we have a table storing information about books. Each book has a `JSON` column containing details such as `title`, `author`, and publication `year`. You can create the `book` table using the SQL statements shown below.

**books**

```sql
CREATE TABLE books (
 id INT,
 info JSON
);

INSERT INTO books (id, info) VALUES
 (1, '{"title": "The Catcher in the Rye", "author": "J.D. Salinger", "year": 1951}'),
 (2, '{"title": "To Kill a Mockingbird", "author": "Harper Lee", "year": 1960}'),
 (3, '{"title": "1984", "author": "George Orwell", "year": 1949}');
```

```text
| id | info                                                                         |
|----|------------------------------------------------------------------------------|
| 1  | {"title": "The Catcher in the Rye", "author": "J.D. Salinger", "year": 1951} |
| 2  | {"title": "To Kill a Mockingbird", "author": "Harper Lee", "year": 1960}     |
| 3  | {"title": "1984", "author": "George Orwell", "year": 1949}                   |
```

Now, let's use the `json_extract_path` function to extract the `title` and `author` of each book:

```sql
SELECT id,
      json_extract_path(info, 'title') as title,
      json_extract_path(info, 'author') as author
FROM books;
```

This query returns the following values:

```text
| id | title                    | author           |
|----|--------------------------|------------------|
| 1  | "The Catcher in the Rye" | "J.D. Salinger"  |
| 2  | "To Kill a Mockingbird"  | "Harper Lee"     |
| 3  | "1984"                   | "George Orwell"  |
```

## Advanced examples

Consider a `products` table that stores information about products in an e-commerce system. The table schema and data are outlined below.

**products**

```sql
CREATE TABLE products (
 id INT,
 attributes JSON
);

INSERT INTO products (id, attributes) VALUES
 (1, '{"name": "Laptop", "specs": {"brand": "Dell", "RAM": "16GB", "storage": {"type": "SSD", "capacity": "512GB"}}, "tags": ["pc"]}'),
 (2, '{"name": "Smartphone", "specs": {"brand": "Google", "RAM": "8GB", "storage": {"type": "UFS", "capacity": "256GB"}}, "tags": ["android",
 "pixel"]}'),
 (3, '{"name": "Smartphone", "specs": {"brand": "Apple", "RAM": "8GB", "storage": {"type": "UFS", "capacity": "128GB"}}, "tags": ["ios", "iphone"]}');
```

```text
| id     | attributes                                                                                                                                        |
|--------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| 1      | {"name": "Laptop", "specs": {"brand": "Dell", "RAM": "16GB", "storage": {"type": "SSD", "capacity": "512GB"}}, "tags": ["pc"]}                    |
| 2      | {"name": "Smartphone", "specs": {"brand": "Google", "RAM": "8GB", "storage": {"type": "UFS", "capacity": "256GB"}}, "tags": ["android", "pixel"]} |
| 3      | {"name": "Smartphone", "specs": {"brand": "Apple", "RAM": "8GB", "storage": {"type": "UFS", "capacity": "128GB"}}, "tags": ["ios", "iphone"]}     |
```

### Extract from nested JSON objects with `json_extract_path`

Let's use `json_extract_path` to retrieve information about the storage type and capacity for each product, demonstrating how to extract values from a nested `JSON` object.

```sql
SELECT
 id,
 json_extract_path(attributes, 'specs', 'storage', 'type') as storage_type,
 json_extract_path(attributes, 'specs', 'storage', 'capacity') as storage_capacity
FROM products;
```

This query returns the following values:

```text
| id | storage_type | storage_capacity |
|----|--------------|------------------|
| 1  | "SSD"        | "512GB"          |
| 2  | "UFS"        | "256GB"          |
| 3  | "UFS"        | "128GB"          |
```

### Extract from array with `json_extract_path`

Now, let's use `json_extract_path` to extract information about the associated tags as well, demonstrating how to extract values from a `JSON` array.

```sql
SELECT
 id,
 json_extract_path(attributes, 'specs', 'storage', 'type') as storage_type,
 json_extract_path(attributes, 'specs', 'storage', 'capacity') as storage_capacity,
 json_extract_path(attributes, 'tags', '0') as first_tag,
 json_extract_path(attributes, 'tags', '1') as second_tag
FROM products;
```

This query returns the following values:

```text
| id | storage_type | storage_capacity | first_tag | second_tag |
|----|--------------|------------------|-----------|------------|
| 1  | "SSD"        | "512GB"          | "pc"      |  null      |
| 2  | "UFS"        | "256GB"          | "android" | "pixel"    |
| 3  | "UFS"        | "128GB"          | "ios"     | "iphone"   |
```

### Use `json_extract_path` in Joins

Let's say you have two tables, `employees` and `departments`, and the `employees` table has a `JSON` column named `details` that contains information about each employee's department. You want to join these tables based on the department information stored in the `JSON` column. The table schemas and data used in this example are shown below.

**departments**

```sql
CREATE TABLE departments (
   department_id SERIAL PRIMARY KEY,
   department_name VARCHAR(255)
);

INSERT INTO departments (department_name) VALUES
   ('IT'),
   ('HR'),
   ('Marketing');
```

```text
| department_id | department_name  |
|---------------|------------------|
|             1 | IT               |
|             2 | HR               |
|             3 | Marketing        |
```

**employees**

```sql
CREATE TABLE employees (
   employee_id SERIAL PRIMARY KEY,
   employee_name VARCHAR(255),
   details JSON
);

INSERT INTO employees (employee_name, details) VALUES
   ('John Doe', '{"department": "IT"}'),
   ('Jane Smith', '{"department": "HR"}'),
   ('Bob Johnson', '{"department": "Marketing"}');
```

```text
| employee_id | employee_name |           details           |
|-------------|---------------|-----------------------------|
|           1 | John Doe      | {"department": "IT"}        |
|           2 | Jane Smith    | {"department": "HR"}        |
|           3 | Bob Johnson   | {"department": "Marketing"} |
```

You can use `JOIN` with `json_extract_path` to retrieve information:

```sql
SELECT
   employees.employee_name,
   departments.department_name
FROM
   employees
JOIN
   departments ON TRIM(BOTH '"' FROM json_extract_path(employees.details, 'department')::TEXT) = departments.department_name;
```

This query returns the following values:

```test
| employee_name | department_name  |
|---------------|------------------|
| John Doe      | IT               |
| Jane Smith    | HR               |
| Bob Johnson   | Marketing        |
```

The `json_extract_path` function extracts the value of the `department` key from the `JSON` column in the `employees` table. The `JOIN` is then performed based on matching department names.

## Additional considerations

### Performance and Indexing

The `json_extract_path` function performs well when extracting data from `JSON` documents, especially compared to extracting data in application code. It allows performing the extraction directly in the database, avoiding transferring entire `JSON` documents to the application.

However, performance can degrade with highly nested `JSON` structures and very long text strings. In those cases, using the binary `JSONB` data type and the `jsonb_extract_path` function will likely offer better performance.

Indexing `JSON` documents can also significantly improve `json_extract_path` query performance when filtering data based on values extracted from `JSON`.

### Alternative functions

- [json_extract_path_text](https://neon.com/docs/functions/json_extract_path_text) - The regular `json_extract_path` function returns the extracted value as a `JSON` object or array, preserving its `JSON` structure, whereas the alternative `json_extract_path_text` function returns the extracted value as a plain text string, casting any `JSON` objects or arrays to their string representations.

  Use the regular `json_extract_path` function when you need to apply `JSON`-specific functions or operators to the extracted value, requiring `JSON` data types. The alternative `json_extract_path_text` function is preferable if you need to work directly with the extracted value as a string, for text processing, concatenation, or comparison.

- `jsonb_extract_path` - The `jsonb_extract_path` function works with the `jsonb` data type, which offers a binary representation of `JSON` data. This alternative function is generally faster than `json_extract_path` for most operations, as it's optimized for the binary `jsonb` format. This difference in performance is often more pronounced with larger `JSON` structures and frequent path extractions.

{/*
  This example does not work. It returns empty values.

  ### Invalid paths

  `json_extract_path` handles an invalid path by returning `NULL`, as in the following example:

  ```sql
  SELECT
  id,
  json_extract_path(attributes, 'speks') as storage_type
  FROM products;
  ```

  The query above, which specifies an invalid path (`'speks'` instead of `'specs'`), returns `NULL` as shown:

  ```text
  | id | storage_type |
  |----|--------------|
  |  1 |   (null)     |
  |  2 |   (null)     |
  |  3 |   (null)     |
  ```

  */}

## Resources

- [PostgreSQL documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/json_object.md) ---

> Summary: The Postgres `json_object` function constructs a JSON object from two parallel text arrays (keys and values) or a single interleaved text array, returning a `JSON` value per row. Use it when you need to shape relational columns into a JSON object at query time without writing application-side serialization code. Unlike `json_build_object`, which accepts a variable argument list of any type, `json_object` requires text arrays and casts all values to text; use `jsonb_object` for the binary JSONB equivalent.

# Postgres json_object() function

Creates a JSON object from key-value pairs

Last updated: 2026-06-05

The `json_object` function in Postgres is used to create a `JSON` object from a set of key-value pairs. Use it when you need to generate `JSON` data dynamically from existing table data or input parameters.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
json_object(keys TEXT[], values TEXT[]) -> JSON
-- or --
json_object(keys_values TEXT[]) -> JSON
```

This function takes two text arrays as input: one for keys and one for values. Both arrays must have the same number of elements, as each key is paired with the corresponding value to construct the `JSON` object.

Alternatively, you can pass a single text array containing both keys and values. In this case, alternate elements in the array are treated as keys and values, respectively.

## Example usage

Consider a scenario where you run a library and have a table that tracks details for each book.

The table with some sample data can be set up as shown:

```sql
-- Test database table for a bookstore inventory
CREATE TABLE book_inventory (
    book_id INT,
    title TEXT,
    author TEXT,
    price NUMERIC,
    genre TEXT
);

-- Inserting some test data into `book_inventory`
INSERT INTO book_inventory VALUES
(101, 'The Great Gatsby', 'F. Scott Fitzgerald', 18.99, 'Classic'),
(102, 'Invisible Man', 'Ralph Ellison', 15.99, 'Novel');
```

When querying this dataset, the frontend client might want to present the data in a different way. Say you want the catalog information just as the list of book names while combining the rest of the fields into a single `metadata` attribute. You can do so as shown here:

```sql
SELECT book_id, title, json_object(
  ARRAY['author', 'genre'],
  ARRAY[author, genre]
) AS metadata
FROM book_inventory;
```

This query returns the following result:

```text
| book_id | title            | metadata                                   |
|---------|------------------|--------------------------------------------|
| 101     | The Great Gatsby | {"author" : "F. Scott Fitzgerald",         |
|         |                  |  "genre" : "Classic"}                      |
| 102     | Invisible Man    | {"author" : "Ralph Ellison",               |
|         |                  |  "genre" : "Novel"}                        |
```

## Advanced examples

### Creating nested JSON objects with `json_object`

You could use `json_object` to create nested `JSON` objects for representing more complex data. However, since `json_object` only expects text values for each key, we will need to combine it with other `JSON` functions like `json_build_object`. For example:

```sql
SELECT json_build_object(
  'title', title,
  'author', json_object(ARRAY['name', 'genre'], ARRAY[author, genre])
) AS book_info
FROM book_inventory;
```

This query returns the following result:

```text
| book_info                                                                                        |
|--------------------------------------------------------------------------------------------------|
| {"title" : "The Great Gatsby", "author" : {"name" : "F. Scott Fitzgerald", "genre" : "Classic"}} |
| {"title" : "Invisible Man", "author" : {"name" : "Ralph Ellison", "genre" : "Novel"}}            |
```

## Additional considerations

### Gotchas and footguns

- Ensure both keys and values arrays have the same number of elements. Mismatched arrays will result in an error. Or, if passing in a single key-value array, ensure that the array has an even number of elements.
- Be aware of data type conversions. Since `json_object` expects text arrays, you may need to explicitly cast non-text data types to text.

### Alternative functions

- [jsonb_object](https://www.postgresql.org/docs/current/functions-json.html) - Same functionality as `json_object`, but returns a `JSONB` object instead of `JSON`.
- [row_to_json](https://www.postgresql.org/docs/current/functions-json.html) - It can be used to create a `JSON` object from a table row (or a row of a composite type) without needing to specify keys and values explicitly. Although, it is less flexible than `json_object` since all fields in the row are included in the `JSON` object.
- [json_build_object](https://neon.com/docs/functions/json_build_object) - Similar to `json_object`, but allows for more flexibility in constructing the `JSON` object, as it can take a variable number of arguments in the form of key-value pairs.
- [json_object_agg](https://www.postgresql.org/docs/current/functions-json.html) - It is used to aggregate the key-value pairs from multiple rows into a single `JSON` object. In contrast, `json_object` outputs a `JSON` object for each row.

## Resources

- [PostgreSQL documentation: JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/json_populate_record.md) ---

> Summary: `json_populate_record(base_record, json)` maps a JSON object onto a pre-defined PostgreSQL composite type or table row, returning a single typed record with JSON values merged in. Use it instead of `json_to_record` when the row type is already defined and you need missing JSON keys to fall back to values from the base record rather than NULL. For JSONB input, use `jsonb_populate_record`; for multiple rows from a JSON array, use `json_populate_recordset`.

# Postgres json_populate_record() function

Casts a JSON object to a record

Last updated: 2026-06-05

The `json_populate_record` function is used to populate a record type with values from a `JSON` object. It is useful for parsing `JSON` data received from external sources, particularly when merging it into an existing record.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
json_populate_record(base_record ANYELEMENT, json JSON)
```

This function takes two arguments: a base record of a row type (which can even be a `NULL` record) and a `JSON` object. It returns the record updated with the `JSON` values.

## Example usage

Consider a database table that tracks employee information. When you receive employee information as `JSON` records, you can use `json_populate_record` to ingest the data into the table.

Here we create the `employees` table with some sample data.

```sql
CREATE TABLE employees (
    id INT,
    name TEXT,
    department TEXT,
    salary NUMERIC
);
```

To illustrate, we start with a `NULL` record and cast the input `JSON` payload to the `employees` record type.

```sql
INSERT INTO employees
SELECT *
FROM json_populate_record(
    NULL::employees,
    '{"id": "123", "name": "John Doe", "department": "Engineering", "salary": "75000"}'
)
RETURNING *;
```

This query returns the following result:

```text
| id | name     | department  | salary |
|----|----------|-------------|--------|
| 123| John Doe | Engineering | 75000  |
```

## Advanced examples

### Handling partial data with `json_populate_record`

For data points where the `JSON` objects have missing keys, `json_populate_record` can still cast them into legible records.

Say we receive records for a bunch of employees who are known to be in Sales, but the `department` field is missing from the `JSON` payload. We can use `json_populate_record` with the default value specified for a field while the other fields are populated from the `JSON` payload, as in this example:

```sql
INSERT INTO employees
SELECT *
FROM json_populate_record(
    (1, 'ABC', 'Sales', 0)::employees,
    '{"id": "124", "name": "Jane Smith", "salary": "68000"}'
)
RETURNING *;
```

This query returns the following:

```text
| id | name       | department | salary |
|----|------------|------------|--------|
| 124| Jane Smith | Sales      | 68000  |
```

### Working with custom types in `json_populate_record`

The base record doesn't need to have the type of a table row and can be a [custom Postgres type](https://www.postgresql.org/docs/current/sql-createtype.html) too. For example, here we first define a custom type `address` and use `json_populate_record` to cast a `JSON` object to it:

```sql
CREATE TYPE address AS (
    street TEXT,
    city TEXT,
    zip TEXT
);

SELECT *
FROM json_populate_record(
    NULL::address,
    '{"street": "123 Main St", "city": "San Francisco", "zip": "94105"}'
);
```

This query returns the following result:

```text
| street     | city          | zip   |
|------------|---------------|-------|
| 123 Main St| San Francisco | 94105 |
```

## Additional considerations

### Alternative options

- [json_to_record](https://neon.com/docs/functions/json_to_record) - It can be used similarly, with a couple differences. `json_populate_record` can be used with a base record of a pre-defined type, whereas `json_to_record` needs the record type defined inline in the `AS` clause. Further, `json_populate_record` can specify default values for missing fields through the base record, whereas `json_to_record` must assign them NULL values.
- `json_populate_recordset` - It can be used similarly to parse `JSON`, the difference being that it returns a set of records instead of a single record. For example, if you have an array of `JSON` objects, you can use `json_populate_recordset` to convert each object into a new row.
- [jsonb_populate_record](https://neon.com/docs/functions/jsonb_populate_record) - It has the same functionality to `json_populate_record`, but accepts `JSONB` input instead of `JSON`.

## Resources

- [Postgres documentation: JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/json_query.md) ---

> Summary: JSON_QUERY(), added in PostgreSQL 17, extracts JSON or JSONB fragments using SQL/JSON path expressions and returns jsonb. Unlike JSON_VALUE(), it supports multi-value results through WITHOUT, WITH CONDITIONAL, and WITH UNCONDITIONAL WRAPPER modes. Use it when a query must return a JSON object or array rather than a scalar, or when you need OMIT QUOTES, PASSING variables, or ON EMPTY / ON ERROR fallback behavior. It accepts any JSON or JSONB input, supports a RETURNING clause for type conversion, and raises SQLSTATE 22034 when multiple values are returned without a wrapper.

# Postgres JSON_QUERY() Function

Extract and Transform JSON Values with SQL/JSON Path Expressions

Last updated: 2026-06-05

The `JSON_QUERY()` function introduced in PostgreSQL 17 provides a powerful way to extract and transform `JSON` values using `SQL/JSON` path expressions. This function offers fine-grained control over how `JSON` values are extracted and formatted in the results.

Use `JSON_QUERY()` when you need to:

- Extract specific values from complex `JSON` structures
- Handle multiple values in results
- Control `JSON` string formatting
- Handle empty results and errors gracefully

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `JSON_QUERY()` function uses the following syntax:

```sql
JSON_QUERY(
    context_item,                    -- Input JSON/JSONB data
    path_expression                  -- SQL/JSON path expression
    [ PASSING { value AS varname } [, ...] ]
    [ RETURNING data_type [ FORMAT JSON [ ENCODING UTF8 ] ] ]
    [ { WITHOUT | WITH { CONDITIONAL | [UNCONDITIONAL] } } [ ARRAY ] WRAPPER ]
    [ { KEEP | OMIT } QUOTES [ ON SCALAR STRING ] ]
    [ { ERROR | NULL | EMPTY { [ ARRAY ] | OBJECT } | DEFAULT expression } ON EMPTY ]
    [ { ERROR | NULL | EMPTY { [ ARRAY ] | OBJECT } | DEFAULT expression } ON ERROR ]
) → jsonb
```

## Understanding Wrappers and Quotes

### Wrapper Behavior

By default, `JSON_QUERY()` does not wrap results (equivalent to `WITHOUT WRAPPER`). There are three wrapper modes:

1. `WITHOUT WRAPPER` (default):
   - Returns unwrapped values
   - Throws an error if multiple values are returned
2. `WITH UNCONDITIONAL WRAPPER` (same as `WITH WRAPPER`):
   - Always wraps results in an array
   - Even single values are wrapped
3. `WITH CONDITIONAL WRAPPER`:
   - Only wraps results when multiple values are present
   - Single values remain unwrapped

### Quote Behavior

For scalar string results:

- By default, values are surrounded by quotes (making them valid `JSON`)
- `KEEP QUOTES`: Explicitly keeps quotes (same as default)
- `OMIT QUOTES`: Removes quotes from the result
- Cannot use `OMIT QUOTES` with any `WITH WRAPPER` option

## Example usage

Let's explore these behaviors using a sample dataset:

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    data JSONB
);

INSERT INTO users (data) VALUES
('{
    "profile": {
        "name": "John Doe",
        "contacts": {
            "email": ["john@example.com", "john.doe@work.com"],
            "phone": "+1-555-0123"
        }
    }
}');
```

### Working with single values

```sql
-- Default behavior (unwrapped, quoted)
SELECT JSON_QUERY(
    data,
    '$.profile.contacts.email[0]'
) FROM users;
```

```text
# |        json_query
------------------------
1 | "john@example.com"
```

```sql
-- With unconditional wrapper
SELECT JSON_QUERY(
    data,
    '$.profile.contacts.email[0]'
    WITH WRAPPER
) FROM users;
```

```text
# |        json_query
------------------------
1 | ["john@example.com"]
```

### Working with multiple values

```sql
-- Must use wrapper for multiple values
SELECT JSON_QUERY(
    data,
    '$.profile.contacts.email[*]'
    WITH WRAPPER
) FROM users;
```

```text
# |                        json_query
-----------------------------------------------------
1 | ["john@example.com", "john.doe@work.com"]
```

```sql
-- This will error (multiple values without wrapper)
SELECT JSON_QUERY(
    data,
    '$.profile.contacts.email[*]'
    ERROR ON ERROR
) FROM users;
```

```text
ERROR: JSON path expression in JSON_QUERY should return single item without wrapper (SQLSTATE 22034)
HINT: Use the WITH WRAPPER clause to wrap SQL/JSON items into an array.
```

### Using conditional wrapper

```sql
-- Single value with conditional wrapper
SELECT JSON_QUERY(
    data,
    '$.profile.contacts.phone'
    WITH CONDITIONAL WRAPPER
) FROM users;
```

```text
# |     json_query
-------------------
1 | "+1-555-0123"
```

```sql
-- Multiple values with conditional wrapper
SELECT JSON_QUERY(
    data,
    '$.profile.contacts.email[*]'
    WITH CONDITIONAL WRAPPER
) FROM users;
```

```text
# |                        json_query
-----------------------------------------------------
1 | ["john@example.com", "john.doe@work.com"]
```

### Quote handling

```sql
-- Default (quoted)
SELECT JSON_QUERY(
    data,
    '$.profile.contacts.phone'
) FROM users;
```

```text
# |     json_query
-------------------
1 | "+1-555-0123"
```

```sql
-- Without quotes (must not use with wrapper)
SELECT JSON_QUERY(
    data,
    '$.profile.contacts.phone'
    RETURNING TEXT
    OMIT quotes
) FROM users;
```

```text
# | json_query
-------------
1 | +1-555-0123
```

### Using the PASSING clause

```sql
-- Extract array element using a variable
SELECT JSON_QUERY(
    '[1, [2, 3], null]',
    'lax $[*][$idx]'
    PASSING 1 AS idx
    WITH CONDITIONAL WRAPPER
);
```

```text
# | json_query
-------------
1 | 3
```

### Handling empty results

```sql
-- Return custom value when path doesn't match
SELECT JSON_QUERY(
    '{"a": 1}',
    '$.b'
    DEFAULT '{"status": "not_found"}' ON EMPTY
);
```

```text
# |           json_query
--------------------------------
1 | {"status": "not_found"}
```

```sql
-- Return empty array when path doesn't match
SELECT JSON_QUERY(
    '{"a": 1}',
    '$.b[*]'
    EMPTY ARRAY ON EMPTY
);
```

```text
# | json_query
-------------
1 | []
```

### Error handling examples

```sql
-- Handle type conversion errors
SELECT JSON_QUERY(
    '{"value": "not_a_number"}',
    '$.value'
    RETURNING numeric
    NULL ON ERROR
);
```

```text
# | json_query
-------------
1 |
```

```sql
-- Raise error on invalid path
SELECT JSON_QUERY(
    '{"a": 1}',
    'invalid_path'
    ERROR ON ERROR
);
```

```text
ERROR: syntax error at end of jsonpath input (SQLSTATE 42601)
```

## Common use cases

### Data transformation

```sql
-- Transform and validate JSON data
CREATE TABLE events (
    id SERIAL PRIMARY KEY,
    event_data JSONB
);

INSERT INTO events (event_data) VALUES
('{
    "type": "user_login",
    "timestamp": "2024-12-04T10:30:00Z",
    "details": {
        "user_id": "U123",
        "device": "mobile",
        "location": {"city": "London", "country": "UK"}
    }
}');

-- Extract specific fields with custom formatting
SELECT
    JSON_QUERY(event_data, '$.type' RETURNING TEXT OMIT QUOTES) as event_type,
    JSON_QUERY(event_data, '$.details.location' WITH WRAPPER) as location
FROM events;
```

```text
# | event_type | location
-------------------------------------
1 | user_login | [{"city": "London", "country": "UK"}]
```

## Performance considerations

1. Use appropriate options:
   - Use `RETURNING TEXT` with `OMIT QUOTES` when JSON formatting is not required
   - Choose `CONDITIONAL WRAPPER` over `UNCONDITIONAL` when possible
   - Consider using `DEFAULT` expressions for better error recovery

2. Optimization tips:
   - Create indexes on frequently queried `JSON` paths
   - Use specific path expressions instead of wildcards when possible

## Learn more

- [PostgreSQL JSON functions documentation](https://www.postgresql.org/docs/current/functions-json.html)
- [SQL/JSON path language](https://www.postgresql.org/docs/current/datatype-json.html#DATATYPE-JSONPATH)

--- [Document source](https://neon.com/docs/functions/json_scalar.md) ---

> Summary: The `json_scalar()` function, introduced in PostgreSQL 17, converts a single SQL scalar value (integer, float, boolean, text, timestamp, or NULL) into its corresponding JSON scalar type with correct formatting. Use it when building JSON output with `json_build_object()` or `json_build_array()` and you need explicit, type-safe conversion rather than implicit casting. Numbers map to JSON numbers, booleans to JSON booleans, timestamps to ISO 8601 strings with timezone, and NULL to SQL NULL.

# Postgres json_scalar() Function

Convert SQL Scalar Values to JSON Scalar Values

Last updated: 2026-06-05

The `json_scalar()` function introduced in PostgreSQL 17 provides a straightforward way to convert `SQL` scalar values into their `JSON` equivalents. Use it when you need to ensure proper type conversion and formatting of individual values for `JSON` output.

Use `json_scalar()` when you need to:

- Convert `SQL` numbers to `JSON` numbers
- Format timestamps as JSON strings
- Convert `SQL` booleans to `JSON` booleans
- Ensure proper null handling in `JSON` context

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `json_scalar()` function uses the following syntax:

```sql
json_scalar(expression) → json
```

Parameters:

- `expression`: Any `SQL` scalar value to be converted to a `JSON` scalar value

## Example usage

Let's explore various ways to use the `json_scalar()` function with different types of input values.

### Numeric values

```sql
-- Convert integer
SELECT json_scalar(42);
```

```text
# | json_scalar
---------------
1 | 42
```

```sql
-- Convert floating-point number
SELECT json_scalar(123.45);
```

```text
# | json_scalar
---------------
1 | 123.45
```

### String values

```sql
-- Convert text
SELECT json_scalar('Hello, World!');
```

```text
# |     json_scalar
--------------------
1 | "Hello, World!"
```

### Date and timestamp values

```sql
-- Convert timestamp
SELECT json_scalar(CURRENT_TIMESTAMP);
```

```text
# |            json_scalar
---------------------------------------
1 | "2024-12-04T06:19:14.458444+00:00"
```

```sql
-- Convert date
SELECT json_scalar(CURRENT_DATE);
```

```text
# |  json_scalar
----------------
1 | "2024-12-04"
```

### Boolean values

```sql
-- Convert boolean true
SELECT json_scalar(true);
```

```text
# | json_scalar
--------------
1 | true
```

### NULL handling

```sql
-- Convert NULL value
SELECT json_scalar(NULL);
```

```text
# | json_scalar
--------------
1 |
```

## Common use cases

### Building JSON objects

```sql
-- Create a JSON object with properly formatted values
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT,
    created_at TIMESTAMP WITH TIME ZONE
);

INSERT INTO users (name, created_at)
VALUES
    ('Alice', '2024-12-04T14:30:45.000000+00:00'),
    ('Bob', '2024-12-04T15:30:45.000000+00:00');

SELECT json_build_object(
    'id', json_scalar(id),
    'name', json_scalar(name),
    'created_at', json_scalar(created_at)
)
FROM users;
```

```text
# |                              json_build_object
-----------------------------------------------------------------------------------
1 | {"id" : 3, "name" : "Alice", "created_at" : "2024-12-04T14:30:45.000000+00:00"}
2 | {"id" : 4, "name" : "Bob", "created_at" : "2024-12-04T15:30:45.000000+00:00"}
```

### Data type conversion

```sql
-- Convert mixed data types in a single query
SELECT json_build_array(
    json_scalar(42),
    json_scalar('text'),
    json_scalar(CURRENT_TIMESTAMP),
    json_scalar(NULL)
);
```

```text
# |                 json_build_array
----------------------------------------------------------
1 | [42, "text", "2024-12-04T06:25:29.928376+00:00", null]
```

## Type conversion rules

The function follows these conversion rules:

1. `NULL` -> `SQL NULL`
2. Numbers → JSON numbers (preserving exact value)
3. Booleans → JSON booleans
4. All other types → JSON strings with appropriate formatting:
   - Timestamps include timezone when available
   - Text is properly escaped according to JSON standards

## Learn more

- [json_build_object() function documentation](https://neon.com/docs/functions/json_build_object)
- [PostgreSQL JSON functions documentation](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL data type formatting](https://www.postgresql.org/docs/current/datatype.html)

--- [Document source](https://neon.com/docs/functions/json_serialize.md) ---

> Summary: `json_serialize()` is a PostgreSQL 17 function that converts a JSON value into text (`text`) or binary (`bytea`) output, with an optional `RETURNING` clause to control the output type. Use it when you need to serialize JSON for storage, transmission, or export in a specific format, as opposed to `json()`, which converts text or binary into a JSON value. The function returns `text` by default and raises `SQLSTATE 22P02` on invalid JSON input.

# Postgres json_serialize() Function

Convert JSON Values to Text or Binary Format

Last updated: 2026-06-05

The `json_serialize()` function introduced in PostgreSQL 17 provides a flexible way to convert `JSON` values into text or binary format. Use it when you need to control the output format of `JSON` data or prepare it for transmission or storage in specific formats.

Use `json_serialize()` when you need to:

- Convert `JSON` values to specific text formats
- Transform `JSON` into binary representation
- Ensure consistent `JSON` string formatting
- Prepare `JSON` data for external systems or storage

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `json_serialize()` function uses the following syntax:

```sql
json_serialize(
    expression                              -- Input JSON expression
    [ FORMAT JSON [ ENCODING UTF8 ] ]       -- Optional input format specification
    [ RETURNING data_type                   -- Optional return type specification
      [ FORMAT JSON [ ENCODING UTF8 ] ] ]   -- Optional output format specification
) → text | bytea
```

Parameters:

- `expression`: Input `JSON` value or expression to serialize
- `FORMAT JSON`: Explicitly specifies `JSON` format for input (optional)
- `ENCODING UTF8`: Specifies `UTF8` encoding for input/output (optional)
- `RETURNING data_type`: Specifies the desired output type (optional, defaults to text)

## Example usage

Let's explore various ways to use the `json_serialize()` function with different inputs and output formats.

### Basic serialization

```sql
-- Serialize a simple JSON object to text
SELECT json_serialize('{"name": "Alice", "age": 30}');
```

```text
# |       json_serialize
--------------------------------
1 | {"name": "Alice", "age": 30}
```

```sql
-- Serialize a JSON array
SELECT json_serialize('[1, 2, 3, "four", true, null]');
```

```text
# |      json_serialize
----------------------------------
1 | [1, 2, 3, "four", true, null]
```

### Binary serialization

```sql
-- Convert JSON to binary format
SELECT json_serialize(
    '{"id": 1, "data": "test"}'
    RETURNING bytea
);
```

```text
# |                   json_serialize
--------------------------------------------------------
1 | \x7b226964223a20312c202264617461223a202274657374227d
```

### Working with complex structures

```sql
-- Serialize nested JSON structures
SELECT json_serialize('{
    "user": {
        "name": "Bob",
        "settings": {
            "theme": "dark",
            "notifications": true
        },
        "tags": ["admin", "active"]
    }
}');
```

```text
# |                                  json_serialize
---------------------------------------------------------------------------------------------------------------------
1 | { "user": { "name": "Bob", "settings": { "theme": "dark", "notifications": true }, "tags": ["admin", "active"] } }
```

## Comparison with `json()` function

While both `json_serialize()` and `json()` work with `JSON` data, they serve different purposes:

- `json()` converts text or binary data into `JSON` values
- `json_serialize()` converts `JSON` values into text or binary format
- `json()` focuses on input validation (for example, `WITH UNIQUE` keys)
- `json_serialize()` focuses on output format control

Think of them as complementary functions:

```sql
-- json() for input conversion
SELECT json('{"name": "Alice"}');  -- Text to JSON

-- json_serialize() for output conversion
SELECT json_serialize('{"name": "Alice"}'::json);  -- JSON to Text
```

## Common use cases

### Data export preparation

```sql
-- Create a table with JSON data
CREATE TABLE events (
    id SERIAL PRIMARY KEY,
    event_data json
);

-- Insert sample data
INSERT INTO events (event_data) VALUES
    ('{"type": "login", "user_id": 123}'),
    ('{"type": "purchase", "amount": 99.99}');

-- Export data in specific format
SELECT id, json_serialize(event_data RETURNING text)
FROM events;
```

## Error handling

The function handles various error conditions:

```sql
-- Invalid JSON input (raises error)
SELECT json_serialize('{"invalid": }');
```

```text
ERROR: invalid input syntax for type json (SQLSTATE 22P02)
```

## Learn more

- [json() function documentation](https://neon.com/docs/functions/json)
- [PostgreSQL JSON functions documentation](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL data type formatting functions](https://www.postgresql.org/docs/current/functions-formatting.html)

--- [Document source](https://neon.com/docs/functions/json_table.md) ---

> Summary: The `JSON_TABLE` function, introduced in PostgreSQL 17, converts JSON and JSONB documents into queryable virtual tables using SQL/JSON path expressions and a COLUMNS clause. Use it when you need to flatten nested JSON objects or arrays into rows, join JSON data with relational tables, or apply SQL aggregation and filtering to JSON structures. Column-level error handling with `ON EMPTY` and `ON ERROR` clauses controls NULL and default-value behavior; GIN indexes on JSONB columns improve query performance.

# Postgres JSON_TABLE() function

Transform JSON data into relational views

Last updated: 2026-06-05

The `JSON_TABLE` function transforms JSON data into relational views, allowing you to query JSON data using standard SQL operations. Added in PostgreSQL 17, this feature helps you work with complex JSON data by presenting it as a virtual table which you can access with regular SQL queries.

Use `JSON_TABLE` when you need to:

- Extract specific fields from complex JSON structures
- Convert JSON arrays into rows
- Join JSON data with regular tables
- Apply SQL operations like filtering and aggregation to JSON data

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

`JSON_TABLE` uses the following syntax:

```sql
JSON_TABLE(
    json_doc,           -- JSON/JSONB input
    path_expression     -- SQL/JSON path expression
    COLUMNS (
        column_definition [, ...]
    )
) AS alias
```

Parameters:

- `json_doc`: JSON or JSONB data to process
- `path_expression`: SQL/JSON path expression that identifies rows to generate
- `COLUMNS`: Defines the schema of the virtual table
- `column_definition`: Specifies how to extract values for each column
- `alias`: Name for the resulting virtual table

## Example usage

Let's explore `JSON_TABLE` using a library management system example. We'll store book information including reviews, borrowing history, and metadata in JSON format.

### Create a test database

```sql
-- Test database table for a library management system
CREATE TABLE library_books (
    book_id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    data JSONB NOT NULL
);

-- Insert sample data
INSERT INTO library_books (title, data) VALUES
(
    'The Art of Programming',
    '{
        "isbn": "978-0123456789",
        "author": {
            "name": "Jane Smith",
            "email": "jane.smith@example.com"
        },
        "publication": {
            "year": 2023,
            "publisher": "Tech Books Inc"
        },
        "metadata": {
            "genres": ["Programming", "Computer Science"],
            "tags": ["algorithms", "python", "best practices"],
            "edition": "2nd"
        },
        "reviews": [
            {
                "user": "john_doe",
                "rating": 5,
                "comment": "Excellent book for beginners!",
                "date": "2024-01-15"
            },
            {
                "user": "mary_jane",
                "rating": 4,
                "comment": "Good examples, could use more exercises",
                "date": "2024-02-20"
            }
        ],
        "borrowing_history": [
            {
                "user_id": "U123",
                "checkout_date": "2024-01-01",
                "return_date": "2024-01-15",
                "condition": "good"
            },
            {
                "user_id": "U456",
                "checkout_date": "2024-02-01",
                "return_date": "2024-02-15",
                "condition": "fair"
            }
        ]
    }'::jsonb
),
(
    'Database Design Fundamentals',
    '{
        "isbn": "978-0987654321",
        "author": {
            "name": "Robert Johnson",
            "email": "robert.j@example.com"
        },
        "publication": {
            "year": 2024,
            "publisher": "Database Press"
        },
        "metadata": {
            "genres": ["Database", "Computer Science"],
            "tags": ["SQL", "design patterns", "normalization"],
            "edition": "1st"
        },
        "reviews": [
            {
                "user": "alice_wonder",
                "rating": 5,
                "comment": "Comprehensive coverage of database concepts",
                "date": "2024-03-01"
            }
        ],
        "borrowing_history": [
            {
                "user_id": "U789",
                "checkout_date": "2024-03-01",
                "return_date": null,
                "condition": "excellent"
            }
        ]
    }'::jsonb
);
```

### Query examples

#### Extract basic book information

This query extracts core book details from the JSON structure into a relational format.

```sql
SELECT b.book_id, b.title, jt.*
FROM library_books b,
JSON_TABLE(
    data,
    '$'
    COLUMNS (
        isbn text PATH '$.isbn',
        author_name text PATH '$.author.name',
        publisher text PATH '$.publication.publisher',
        pub_year int PATH '$.publication.year'
    )
) AS jt;
```

Result:

| book\_id | title                        | isbn           | author\_name   | publisher      | pub\_year |
| -------- | ---------------------------- | -------------- | -------------- | -------------- | --------- |
| 1        | The Art of Programming       | 978-0123456789 | Jane Smith     | Tech Books Inc | 2023      |
| 2        | Database Design Fundamentals | 978-0987654321 | Robert Johnson | Database Press | 2024      |

#### Analyze book reviews

This query flattens the reviews array into rows, making it easy to analyze reader feedback.

```sql
SELECT
    b.title,
    jt.*
FROM library_books b,
JSON_TABLE(
    data,
    '$.reviews[*]'
    COLUMNS (
        reviewer text PATH '$.user',
        rating int PATH '$.rating',
        review_date date PATH '$.date',
        comment text PATH '$.comment'
    )
) AS jt
ORDER BY review_date DESC;
```

Result:

| title                        | reviewer      | rating | review\_date | comment                                     |
| ---------------------------- | ------------- | ------ | ------------ | ------------------------------------------- |
| Database Design Fundamentals | alice\_wonder | 5      | 2024-03-01   | Comprehensive coverage of database concepts |
| The Art of Programming       | mary\_jane    | 4      | 2024-02-20   | Good examples, could use more exercises     |
| The Art of Programming       | john\_doe     | 5      | 2024-01-15   | Excellent book for beginners!               |

#### Track borrowing history

This query helps track book loans and current borrowing status.

```sql
WITH book_loans AS (
    SELECT
        b.title,
        jt.*
    FROM library_books b,
    JSON_TABLE(
        data,
        '$.borrowing_history[*]'
        COLUMNS (
            user_id text PATH '$.user_id',
            checkout_date date PATH '$.checkout_date',
            return_date date PATH '$.return_date',
            condition text PATH '$.condition'
        )
    ) AS jt
)
SELECT
    title,
    user_id,
    checkout_date,
    COALESCE(return_date::text, 'Still borrowed') as return_status,
    condition
FROM book_loans
ORDER BY checkout_date DESC;
```

Result:

| title                        | user\_id | checkout\_date | return\_status | condition |
| ---------------------------- | -------- | -------------- | -------------- | --------- |
| Database Design Fundamentals | U789     | 2024-03-01     | Still borrowed | excellent |
| The Art of Programming       | U456     | 2024-02-01     | 2024-02-15     | fair      |
| The Art of Programming       | U123     | 2024-01-01     | 2024-01-15     | good      |

### Advanced usage

#### Aggregate review data

Use this query to calculate review statistics for each book.

```sql
WITH book_ratings AS (
    SELECT
        b.title,
        jt.rating
    FROM library_books b,
    JSON_TABLE(
        data,
        '$.reviews[*]'
        COLUMNS (
            rating int PATH '$.rating'
        )
    ) AS jt
)
SELECT
    title,
    COUNT(*) as num_reviews,
    ROUND(AVG(rating), 2) as avg_rating,
    MIN(rating) as min_rating,
    MAX(rating) as max_rating
FROM book_ratings
GROUP BY title;
```

Result

| title                        | num\_reviews | avg\_rating | min\_rating | max\_rating |
| ---------------------------- | ------------ | ----------- | ----------- | ----------- |
| Database Design Fundamentals | 1            | 5.00        | 5           | 5           |
| The Art of Programming       | 2            | 4.50        | 4           | 5           |

#### Process arrays and metadata

This query extracts array fields and metadata into queryable columns.

```sql
SELECT
    b.title,
    jt.*
FROM library_books b,
JSON_TABLE(
    data,
    '$'
    COLUMNS (
        genres json FORMAT JSON PATH '$.metadata.genres',
        tags json FORMAT JSON PATH '$.metadata.tags',
        edition text PATH '$.metadata.edition'
    )
) AS jt;
```

Result:

| title                        | genres                               | tags                                         | edition |
| ---------------------------- | ------------------------------------ | -------------------------------------------- | ------- |
| The Art of Programming       | \["Programming", "Computer Science"] | \["algorithms", "python", "best practices"]  | 2nd     |
| Database Design Fundamentals | \["Database", "Computer Science"]    | \["SQL", "design patterns", "normalization"] | 1st     |

## Error handling

`JSON_TABLE` returns NULL for missing values by default. You can modify this behavior with error handling clauses:

```sql
SELECT title, jt.*
FROM library_books,
JSON_TABLE(
    data,
    '$'
    COLUMNS (
        author_name text PATH '$.author.name',
        metadata TEXT PATH '$.metadata' DEFAULT '{}' ON ERROR,
        edition text PATH '$.metadata.edition' DEFAULT 'Unknown' ON EMPTY DEFAULT 'Unknown' ON ERROR
    )
) AS jt;
```

This example shows how to handle errors when extracting JSON data. There is an error here because the `metadata` field is not of type `TEXT`.

| title                        | author\_name   | metadata | edition |
| ---------------------------- | -------------- | -------- | ------- |
| The Art of Programming       | Jane Smith     | \{}      | 2nd     |
| Database Design Fundamentals | Robert Johnson | \{}      | 1st     |

## Performance tips

1. Create GIN indexes on JSONB columns:

   ```sql
   CREATE INDEX idx_library_books_data ON library_books USING GIN (data);
   ```

2. Consider these optimizations:
   - Place filters on regular columns before JSON operations
   - Use JSON operators (`->`, `->>`, `@>`) when possible
   - Materialize frequently accessed JSON paths into regular columns
   - Break large JSON documents into smaller pieces to manage memory usage

## Learn more

- [PostgreSQL JSON_TABLE documentation](https://www.postgresql.org/docs/current/functions-json.html#FUNCTIONS-SQLJSON-TABLE)
- [PostgreSQL JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/json_to_record.md) ---

> Summary: The `json_to_record` function expands a single JSON object into a typed PostgreSQL row using an inline column definition list supplied via the `AS` clause. Use it when you need to parse a JSON payload from an API or file upload into strongly typed columns without pre-defining a named composite type. Missing keys become NULL, nested objects map via custom composite types, and it differs from `json_populate_record` (requires a pre-existing record type) and `jsonb_to_record` (accepts JSONB input).

# Postgres json_to_record() function

Converts a JSON object to a record

Last updated: 2026-06-05

You can use the `json_to_record` function to convert a top-level `JSON` object into a row, with the type specified by the `AS` clause.

This function is useful when you need to parse `JSON` data received from external sources, such as APIs or file uploads, and store it in a structured format. By using `json_to_record`, you can easily extract values from `JSON` and map them to the corresponding columns in your database table.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
json_to_record(json JSON) AS (column_name column_type [, ...])
```

The function's definition includes a column definition list, where you specify the name and data type of each column in the resulting record.

## Example usage

Consider a scenario in which you have `JSON` data representing employee information, and you want to ingest it for easier processing later. The `JSON` data looks like this:

```json
{
  "id": "123",
  "name": "John Doe",
  "department": "Engineering",
  "salary": "75000"
}
```

The table you want to insert data into is defined as follows:

```sql
CREATE TABLE employees (
    id INT,
    name TEXT,
    department TEXT,
    salary NUMERIC
);
```

Using `json_to_record`, you can insert the input data into the `employees` table as shown:

```sql
INSERT INTO employees
SELECT *
FROM json_to_record('{"id": "123", "name": "John Doe", "department": "Engineering", "salary": "75000"}') AS x(id INT, name TEXT, department TEXT, salary NUMERIC);
```

To verify the data was inserted, you can run the following query:

```sql
SELECT * FROM employees;
```

This query returns the following result:

```text
| id | name     | department   | salary |
|----|----------|--------------|--------|
| 123| John Doe | Engineering  | 75000  |
```

## Advanced examples

This section provides advanced `json_to_record` examples.

### Handling partial data with `json_to_record`

For datapoints where the `JSON` objects have missing keys, `json_to_record` can still cast them into records, producing `NULL` values for the unmatched columns. For example:

```sql
INSERT INTO employees
SELECT *
FROM json_to_record('{
  "id": "124",
  "name": "Jane Smith"
}') AS x(id INT, name TEXT, department TEXT, salary NUMERIC)
RETURNING *;
```

This query returns the following result:

```
| id | name       | department   | salary |
|----|------------|--------------|--------|
| 124| Jane Smith |              |        |
```

### Handling nested data with `json_to_record`

`json_to_record` can also be used to handle nested `JSON` input data (i.e., keys with values that are `JSON` objects themselves). You need to first define a [custom Postgres type](https://www.postgresql.org/docs/current/sql-createtype.html). The newly created type can then be used in the column definition list along with the other columns.

In the following example, we handle the `address` field by creating an `ADDRESS_TYPE` type first.

```sql
CREATE TYPE ADDRESS_TYPE AS (
  street TEXT,
  city TEXT
);

SELECT *
FROM json_to_record('{
  "id": "125",
  "name": "Emily Clark",
  "department": "Marketing",
  "salary": "68000",
  "address": {
    "street": "123 Elm St",
    "city": "Springfield"
  }
}') AS x(id INT, name TEXT, department TEXT, salary NUMERIC, address ADDRESS_TYPE);
```

This query returns the following result:

```text
| id | name        | department | salary | address                     |
|----|-------------|------------|--------|-----------------------------|
| 1  | Emily Clark | Marketing  | 68000  | ("123 Elm St", Springfield) |
```

### Alternative functions

- [json_populate_record](https://neon.com/docs/functions/json_populate_record): This function can also be used to create records using values from a `JSON` object. The difference is that `json_populate_record` requires the record type to be defined beforehand, while `json_to_record` needs the type definition inline.
- [json_to_recordset](https://www.postgresql.org/docs/current/functions-json.html): This function can be used similarly to parse `JSON`, the difference being that it returns a set of records instead of a single record. For example, if you have an array of `JSON` objects, you can use `json_to_recordset` to convert each object into a new row.
- [jsonb_to_record](https://www.postgresql.org/docs/current/functions-json.html): This function provides the same functionality as `json_to_record`, but accepts `JSONB` input instead of `JSON`. In cases where the input payload type isn't exactly specified, either of the two functions can be used. For example, take this `json_to_record` query:

  ```sql
  SELECT *
  FROM json_to_record('{"id": "123", "name": "John Doe", "department": "Engineering"}')
  AS x(id INT, name TEXT, department TEXT);
  ```

  It works just as well as this `JSONB` variant (below) since Postgres casts the literal `JSON` object to `JSON` or `JSONB` depending on the context.

  ```sql
  SELECT *
  FROM jsonb_to_record('{"id": "123", "name": "Sally", "department": "Engineering"}')
  AS x(id INT, name TEXT, department TEXT);
  ```

## Resources

- [PostgreSQL documentation: JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/json_value.md) ---

> Summary: JSON_VALUE(), introduced in PostgreSQL 17, extracts a single scalar value from a JSON or JSONB input using a SQL/JSON path expression, with optional type conversion via RETURNING and configurable ON EMPTY and ON ERROR clauses. Use it instead of JSON_QUERY() when you need a plain text or typed scalar result (number, date, boolean) rather than a JSON object or array, and when missing or invalid values must return a default instead of raising an error.

# Postgres JSON_VALUE() Function

Extract and Convert JSON Scalar Values

Last updated: 2026-06-05

The `JSON_VALUE()` function introduced in PostgreSQL 17 provides a specialized way to extract single scalar values from `JSON` data with type conversion capabilities. Use it when you need to extract and potentially convert individual values from `JSON` structures while ensuring type safety and proper error handling.

Use `JSON_VALUE()` when you need to:

- Extract single scalar values from `JSON`
- Convert `JSON` values to specific PostgreSQL data types
- Ensure strict type safety when working with `JSON` data
- Handle missing or invalid `JSON` values gracefully

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `JSON_VALUE()` function uses the following syntax:

```sql
JSON_VALUE(
    context_item,                    -- JSON input
    path_expression                  -- SQL/JSON path expression
    [ PASSING { value AS varname } [, ...] ]
    [ RETURNING data_type ]         -- Optional type conversion
    [ { ERROR | NULL | DEFAULT expression } ON EMPTY ]
    [ { ERROR | NULL | DEFAULT expression } ON ERROR ]
) → text
```

Parameters:

- `context_item`: `JSON/JSONB` input to process
- `path_expression`: `SQL/JSON` path expression that identifies the value to extract
- `PASSING`: Optional clause to pass variables into the path expression
- `RETURNING`: Specifies the desired output data type (defaults to text)
- `ON EMPTY`: Handles cases where no value is found
- `ON ERROR`: Handles extraction or conversion errors

## Example usage

Let's explore various ways to use the `JSON_VALUE()` function with different scenarios and options.

### Basic value extraction

```sql
-- Extract a simple string value
SELECT JSON_VALUE('{"name": "Alice"}', '$.name');
```

```text
# |  json_value
--------------
1 | Alice
```

```sql
-- Extract a numeric value
SELECT JSON_VALUE('{"age": 30}', '$.age');
```

```text
# | json_value
-------------
1 | 30
```

### Type conversion with RETURNING

```sql
-- Convert string to float
SELECT JSON_VALUE(
    '"123.45"',
    '$'
    RETURNING float
);
```

```text
# | json_value
-------------
1 | 123.45
```

```sql
-- Convert string to date
SELECT JSON_VALUE(
    '"2024-12-04"',
    '$'
    RETURNING date
);
```

```text
# | json_value
-------------
1 | 2024-12-04
```

### Using variables with PASSING

```sql
-- Extract array element using variable
SELECT JSON_VALUE(
    '[1, 2, 3, 4, 5]',
    'strict $[$index]'
    PASSING 2 AS index
);
```

```text
# | json_value
-------------
1 | 3
```

### Error handling

```sql
-- Handle missing values with DEFAULT
SELECT JSON_VALUE(
    '{"data": null}',
    '$.missing_field'
    DEFAULT 'Not Found' ON EMPTY
);
```

```text
# |  json_value
---------------
1 | Not Found
```

```sql
-- Handle conversion errors
SELECT JSON_VALUE(
    '{"value": "not a number"}',
    '$.value'
    RETURNING numeric
    DEFAULT 0 ON ERROR
);
```

```text
# | json_value
-------------
1 | 0
```

### Working with nested structures

```sql
-- Extract from nested object
SELECT JSON_VALUE(
    '{
        "user": {
            "contact": {
                "email": "alice@example.com"
            }
        }
    }',
    '$.user.contact.email'
);
```

```text
# |      json_value
----------------------
1 | alice@example.com
```

## Common use cases

### Data validation

```sql
-- Validate email format
CREATE TABLE user_emails (
    id SERIAL PRIMARY KEY,
    user_data jsonb,
    CONSTRAINT valid_email CHECK (
        JSON_VALUE(user_data, '$.email' RETURNING text)
        ~ '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$'
    )
);

-- This insert will succeed
INSERT INTO user_emails (user_data)
VALUES (
    '{"name": "John Doe", "email": "john.doe@example.com"}'
);

-- This insert will fail
INSERT INTO user_emails (user_data)
VALUES (
    '{"name": "Alice", "email": "invalid-email"}'
);

```

## Error handling

The function provides several ways to handle errors:

1. Using `ON EMPTY`:
   - `ERROR`: Raises an error (default)
   - `NULL`: Returns `NULL`
   - `DEFAULT expression`: Returns specified value

2. Using `ON ERROR`:
   - `ERROR`: Raises an error (default)
   - `NULL`: Returns `NULL`
   - `DEFAULT expression`: Returns specified value

## JSON_VALUE vs JSON_QUERY

The `JSON_VALUE()` function is designed for extracting scalar values from `JSON` data, while `JSON_QUERY()` is used for extracting `JSON` structures (objects, arrays, or scalar values). Here's a comparison of the two functions:

### Purpose and Return Types

`JSON_VALUE()`:

- Designed specifically for extracting scalar values (numbers, strings, booleans)
- Always returns a single scalar value as text (or specified type via `RETURNING`)
- Removes quotes from string values by default
- Throws an error if the result is an object or array

`JSON_QUERY()`:

- Designed for extracting `JSON` structures (objects, arrays, or scalar values)
- Returns valid `JSON/JSONB` output
- Preserves quotes on string values by default
- Can handle multiple values using wrapper options

### Example Comparisons

```sql
-- Working with scalar string values
SELECT
    JSON_VALUE('{"name": "Alice"}', '$.name') as value_result,
    JSON_QUERY('{"name": "Alice"}', '$.name') as query_result;
```

```text
# | value_result | query_result
--------------------------------
1 | Alice        | "Alice"
```

```sql
-- Working with arrays (JSON_VALUE will error and give null by default)
SELECT
    JSON_VALUE('{"tags": ["sql", "json"]}', '$.tags' NULL ON ERROR) as value_result,
    JSON_QUERY('{"tags": ["sql", "json"]}', '$.tags') as query_result;
```

```text
# |  value_result |       query_result
---------------------------------------
1 |               | ["sql", "json"]
```

## Additional considerations

1. Type safety:
   - Always use `RETURNING` when specific data types are expected
   - Implement appropriate error handling for type conversions

2. Performance considerations:
   - Use indexes on frequently queried `JSON` paths

## Learn more

- [PostgreSQL JSON functions documentation](https://www.postgresql.org/docs/current/functions-json.html)
- [SQL/JSON path language](https://www.postgresql.org/docs/current/datatype-json.html#DATATYPE-JSONPATH)

--- [Document source](https://neon.com/docs/functions/json.md) ---

> Summary: The PostgreSQL `json()` function converts text strings or UTF8-encoded bytea data into JSON values, with optional `WITH UNIQUE` enforcement to reject duplicate object keys and `FORMAT JSON ENCODING UTF8` for explicit bytea parsing. Use `json()` instead of a cast or `to_json()` when you need structural validation or need to control duplicate-key behavior at parse time. Supported parameters include `expression`, `FORMAT JSON`, `ENCODING UTF8`, and `WITH | WITHOUT UNIQUE [KEYS]`.

# Postgres json() Function

Convert Text and Binary Data to JSON Values

Last updated: 2026-06-05

The `json()` function provides a robust way to convert text or binary data into `JSON` values. This new function offers enhanced control over `JSON` parsing, including options for handling duplicate keys and encoding specifications.

Use `json()` when you need to:

- Convert text strings into `JSON` values
- Parse UTF8-encoded binary data as `JSON`
- Validate `JSON` structure during conversion
- Control handling of duplicate object keys

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `json()` function uses the following syntax:

```sql
json(
    expression                              -- Input text or bytea
    [ FORMAT JSON [ ENCODING UTF8 ]]        -- Optional format specification
    [ { WITH | WITHOUT } UNIQUE [ KEYS ]]   -- Optional duplicate key handling
) → json
```

Parameters:

- `expression`: Input text or bytea string to convert
- `FORMAT JSON`: Explicitly specifies `JSON` format (optional)
- `ENCODING UTF8`: Specifies UTF8 encoding for bytea input (optional)
- `WITH|WITHOUT UNIQUE [KEYS]`: Controls duplicate key handling (optional)

## Example usage

Let's explore various ways to use the `json()` function with different inputs and options.

### Basic JSON conversion

```sql
-- Convert a simple string to JSON
SELECT json('{"name": "Alice", "age": 30}');
```

```text
# |        json
--------------------------------
1 | {"name": "Alice", "age": 30}
```

```sql
-- Convert a JSON array
SELECT json('[1, 2, 3, "four", true, null]');
```

```text
# |           json
--------------------------------
1 | [1, 2, 3, "four", true, null]
```

```sql
-- Convert nested JSON structures
SELECT json('{
    "user": {
        "name": "Bob",
        "contacts": {
            "email": "bob@example.com",
            "phone": "+1-555-0123"
        }
    },
    "active": true
}');
```

```text
# | json
---------------------------------------------------------------------------------------------------------------------
1 | { "user": { "name": "Bob", "contacts": { "email": "bob@example.com", "phone": "+1-555-0123" } }, "active": true }
```

### Handling duplicate keys

```sql
-- Without UNIQUE keys (allows duplicates)
SELECT json('{"a": 1, "b": 2, "a": 3}' WITHOUT UNIQUE);
```

```text
# |           json
----------------------------
1 | {"a": 1, "b": 2, "a": 3}
```

```sql
-- With UNIQUE keys
SELECT json('{"a": 1, "b": 2, "c": 3}' WITH UNIQUE);
```

```text

# |           json
----------------------------
1 | {"a": 1, "b": 2, "c": 3}
```

```sql
-- This will raise an error due to duplicate 'a' key
SELECT json('{"a": 1, "b": 2, "a": 3}' WITH UNIQUE);
```

```text
ERROR: duplicate JSON object key value (SQLSTATE 22030)
```

### Working with binary data

```sql
-- Convert UTF8-encoded bytea to JSON
SELECT json(
    '\x7b226e616d65223a22416c696365227d'::bytea
    FORMAT JSON
    ENCODING UTF8
);
```

```text
# |       json
---------------------
1 | {"name": "Alice"}
```

```sql
-- Convert bytea with explicit format and uniqueness check
SELECT json(
    '\x7b226964223a312c226e616d65223a22426f62227d'::bytea
    FORMAT JSON
    ENCODING UTF8
    WITH UNIQUE
);
```

```text
# |           json
----------------------------
1 | {"id": 1, "name": "Bob"}
```

### Combining with other JSON functions:

```sql
-- Convert and extract
SELECT json('{"users": [{"id": 1}, {"id": 2}]}')->'users'->0->>'id' AS user_id;
```

```text
# | user_id
-----------
1 | 1
```

```sql
-- Convert and check structure
SELECT json_typeof(json('{"a": [1,2,3]}')->'a');
```

```text
# | json_typeof
---------------
1 | array
```

## Error handling

The `json()` function performs validation during conversion and can raise several types of errors:

```sql
-- Invalid JSON syntax (raises error)
SELECT json('{"name": "Alice" "age": 30}');
```

```text
ERROR: invalid input syntax for type json (SQLSTATE 22P02)
```

```sql
-- Invalid UTF8 encoding (raises error)
SELECT json('\xFFFFFFFF'::bytea FORMAT JSON ENCODING UTF8);
```

```text
ERROR: invalid byte sequence for encoding "UTF8": 0xff (SQLSTATE 22021)
```

## Common use cases

### Data validation

```sql
-- Validate JSON structure before insertion
CREATE TABLE user_profiles (
    id SERIAL PRIMARY KEY,
    profile_data json
);

-- Insert with validation
INSERT INTO user_profiles (profile_data)
VALUES (
    json('{
        "name": "Alice",
        "age": 30,
        "interests": ["reading", "hiking"]
    }' WITH UNIQUE)
);
```

## Additional considerations

1. Use appropriate input validation:
   - Use `WITH UNIQUE` when duplicate keys should be prevented
   - Consider `FORMAT JSON` for explicit parsing requirements

2. Error handling best practices:
   - Implement proper error handling for invalid JSON
   - Validate input before bulk operations

## Learn more

- [PostgreSQL JSON functions documentation](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/jsonb_array_elements.md) ---

> Summary: `jsonb_array_elements(jsonb)` is a PostgreSQL set-returning function that explodes a JSONB array into one row per element, preserving each element as a JSONB value rather than plain text. Use it when you need to unnest a JSONB array for filtering, joining against other tables, or further JSON operations; choose `jsonb_array_elements_text` instead when you need plain-text output for string aggregation or text functions. Also covered: ordering output with `WITH ORDINALITY`, SQL NULL values inside arrays, nested JSONB arrays, and `jsonb_path_query` for path-based filtering.

# Postgres jsonb_array_elements() function

Expands a JSONB array into a set of rows

Last updated: 2026-06-05

You can use the `jsonb_array_elements` function to expand a `JSONB` array into a set of rows, each containing one element of the array. It is a simpler option compared to complex looping logic. It is also more efficient than executing the same operation on the application side by reducing data transfer and processing overhead.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
jsonb_array_elements(json)
```

## `jsonb_array_elements` example

Suppose you have a table with information about developers:

**developers**

```sql
CREATE TABLE developers (
 id INT PRIMARY KEY,
 name TEXT,
 skills JSONB
);

INSERT INTO developers (id, name, skills) VALUES
 (1, 'Alice', '["Java", "Python", "SQL"]'),
 (2, 'Bob', '["C++", "JavaScript"]'),
 (3, 'Charlie', '["HTML", "CSS", "React"]');
```

```
| id |  name   |          skills
|----|---------|---------------------------
| 1  | Alice   | ["Java", "Python", "SQL"]
| 2  | Bob     | ["C++", "JavaScript"]
| 3  | Charlie | ["HTML", "CSS", "React"]
```

Now, let's say you want to extract each individual skill from the skills `JSON` array. You can use `jsonb_array_elements` for that:

```sql
SELECT id, name, skill
FROM developers,
    jsonb_array_elements(skills) AS skill;
```

This query returns the following values:

```text
| id |  name   |    skill
|----|---------|--------------
| 1  | Alice   | "Java"
| 1  | Alice   | "Python"
| 1  | Alice   | "SQL"
| 2  | Bob     | "C++"
| 2  | Bob     | "JavaScript"
| 3  | Charlie | "HTML"
| 3  | Charlie | "CSS"
| 3  | Charlie | "React"
```

## Advanced examples

This section shows advanced `jsonb_array_elements` examples.

## Filtering `jsonb_array_elements`

You can use the `jsonb_array_elements` function to extract the sizes from the `JSON` data and then filter the products based on a specific color (or size):

```sql
SELECT *
FROM products
WHERE 'Blue' IN (
 SELECT REPLACE(jsonb_array_elements(details->'colors')::text, '"', '')::text
);
```

This query returns the following values:

```text
| id |   name   |                               details                                  |
|----|----------|------------------------------------------------------------------------|
|  1 | T-Shirt  | {"sizes": ["S", "M", "L", "XL"], "colors": ["Red", "Blue", "Green"]}   |
|  4 | Jeans    | {"sizes": ["28", "30", "32", "34"], "colors": ["Blue", "Black"]}       |
```

## Handling `NULL` in `jsonb_array_elements`

This example updates the table to insert another product (`Socks`) with one of the values in the `sizes` as `null`:

**products**

```text
| id |  name   |                                 details                                 |
|----|---------|-------------------------------------------------------------------------|
|  6 | Socks   | {"sizes": ["S", null, "L", "XL"], "colors": ["White", "Black", "Gray"]} |
```

```sql
INSERT INTO products (id, name, details) VALUES (6, 'Socks', '{"sizes": ["S", null, "L", "XL"], "colors": ["White", "Black", "Gray"]}');
```

Querying for `Socks` shows how null values in an array are handled:

```sql
SELECT
 id,
 name,
 size
FROM products AS p,
 jsonb_array_elements(p.details -> 'sizes') AS size
WHERE name = 'Socks';
```

This query returns the following values:

```
| id | name  | size |
|----|-------|------|
|  6 | Socks | "S"  |
|  6 | Socks | null |
|  6 | Socks | "L"  |
|  6 | Socks | "XL" |
```

### Ordering `json_array_elements` output using `WITH ORDINALITY`

Let's consider a scenario where you have a table named `workflow` with a `JSONB` column `steps` representing sequential steps in a workflow:

**workflow**

```sql
CREATE TABLE workflow (
   id SERIAL PRIMARY KEY,
   workflow_name TEXT,
   steps JSONB
);

INSERT INTO workflow (workflow_name, steps) VALUES
   ('Employee Onboarding', '{"tasks": ["Submit Resume", "Interview", "Background Check", "Offer", "Orientation"]}'),
   ('Project Development', '{"tasks": ["Requirement Analysis", "Design", "Implementation", "Testing", "Deployment"]}'),
   ('Order Processing', '{"tasks": ["Order Received", "Payment Verification", "Packing", "Shipment", "Delivery"]}');
```

```
| id |    workflow_name    |                                          steps                                          |
|----|---------------------|-----------------------------------------------------------------------------------------|
|  1 | Employee Onboarding | {"tasks": ["Submit Resume", "Interview", "Background Check", "Offer", "Orientation"]}   |
|  2 | Project Development | {"tasks": ["Requirement Analysis", "Design", "Implementation", "Testing", "Deployment"]}|
|  3 | Order Processing    | {"tasks": ["Order Received", "Payment Verification", "Packing", "Shipment", "Delivery"]}|
```

Each workflow consists of a series of tasks, and you want to extract and display the tasks along with their order in the workflow.

```sql
SELECT
   workflow_name,
   task.value AS task_name,
   task.ordinality AS task_order
FROM
   workflow,
   jsonb_array_elements(steps->'tasks') WITH ORDINALITY AS task;
```

This query returns the following values:

```
|    workflow_name    |       task_name        | task_order |
|---------------------|------------------------|------------|
| Employee Onboarding | "Submit Resume"        |          1 |
| Employee Onboarding | "Interview"            |          2 |
| Employee Onboarding | "Background Check"     |          3 |
| Employee Onboarding | "Offer"                |          4 |
| Employee Onboarding | "Orientation"          |          5 |
| Project Development | "Requirement Analysis" |          1 |
| Project Development | "Design"               |          2 |
| Project Development | "Implementation"       |          3 |
| Project Development | "Testing"              |          4 |
| Project Development | "Deployment"           |          5 |
| Order Processing    | "Order Received"       |          1 |
| Order Processing    | "Payment Verification" |          2 |
| Order Processing    | "Packing"              |          3 |
| Order Processing    | "Shipment"             |          4 |
| Order Processing    | "Delivery"             |          5 |
```

### Nested arrays in `jsonb_array_elements`

You can also handle nested arrays with `jsonb_array_elements`.

Consider a scenario where each product in an `electronics_products` table has multiple variants, and each variant has an array of sizes and an array of colors.

**electronics_products**

```sql
CREATE TABLE electronics_products (
 id INTEGER PRIMARY KEY,
 name TEXT,
 details JSONB
);


INSERT INTO electronics_products (id, name, details) VALUES
 (1, 'Laptop', '{"variants": [{"model": "A", "sizes": ["13 inch", "15 inch"], "colors": ["Silver", "Black"]}, {"model": "B", "sizes": ["15 inch", "17 inch"], "colors": ["Gray", "White"]}]}'),
 (2, 'Smartphone', '{"variants": [{"model": "X", "sizes": ["5.5 inch", "6 inch"], "colors": ["Black", "Gold"]}, {"model": "Y", "sizes": ["6.2 inch", "6.7 inch"], "colors": ["Blue", "Red"]}]}');
```

```text
| id |    name    |                                                                                   details
|----|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|  1 | Laptop     | {"variants": [{"model": "A", "sizes": ["13 inch", "15 inch"], "colors": ["Silver", "Black"]}, {"model": "B", "sizes": ["15 inch", "17 inch"], "colors": ["Gray", "White"]}]}
|  2 | Smartphone | {"variants": [{"model": "X", "sizes": ["5.5 inch", "6 inch"], "colors": ["Black", "Gold"]}, {"model": "Y", "sizes": ["6.2 inch", "6.7 inch"], "colors": ["Blue", "Red"]}]}
```

To handle the nested arrays and extract information about each variant, you can run this query using the `jsonb_array_elements` function:

```sql
SELECT
 id,
 name,
 variant->>'model' AS model,
 size,
 color
FROM
 electronics_products,
  jsonb_array_elements(details->'variants') AS variant,
  jsonb_array_elements_text(variant->'sizes') AS t1(size),
  jsonb_array_elements_text(variant->'colors') AS t2(color);
```

This query returns the following values:

```text
| id |    name    | model |   size   | color  |
|----|------------|-------|----------|--------|
|  1 | Laptop     | A     | 13 inch  | Silver |
|  1 | Laptop     | A     | 13 inch  | Black  |
|  1 | Laptop     | A     | 15 inch  | Silver |
|  1 | Laptop     | A     | 15 inch  | Black  |
|  1 | Laptop     | B     | 15 inch  | Gray   |
|  1 | Laptop     | B     | 15 inch  | White  |
|  1 | Laptop     | B     | 17 inch  | Gray   |
|  1 | Laptop     | B     | 17 inch  | White  |
|  2 | Smartphone | X     | 5.5 inch | Black  |
|  2 | Smartphone | X     | 5.5 inch | Gold   |
|  2 | Smartphone | X     | 6 inch   | Black  |
|  2 | Smartphone | X     | 6 inch   | Gold   |
|  2 | Smartphone | Y     | 6.2 inch | Blue   |
|  2 | Smartphone | Y     | 6.2 inch | Red    |
|  2 | Smartphone | Y     | 6.7 inch | Blue   |
|  2 | Smartphone | Y     | 6.7 inch | Red    |
```

### `jsonb_array_elements` with joins

Let's assume you want to retrieve a list of users along with their roles in each organization. The data is stored in an `organizations` table and a `users` table.

**organizations**

```
| id |                           members                            |
|----|--------------------------------------------------------------|
|  1 | [{"id": 23, "role": "admin"}, {"id": 24, "role": "default"}] |
|  2 | [{"id": 23, "role": "user"}]                                 |
|  3 | [{"id": 24, "role": "admin"}, {"id": 25, "role": "default"}] |
|  4 | [{"id": 25, "role": "user"}]                                 |
```

**users**

```
| id  | name  |      email       |
|-----|-------|------------------|
| 23  | Max   | max@gmail.com    |
| 24  | Joe   | joe@gmail.com    |
| 25  | Alice | alice@gmail.com  |
```

```sql
CREATE TABLE organizations (
   id SERIAL PRIMARY KEY,
   members JSONB
);

CREATE TABLE users (
   id INTEGER PRIMARY KEY,
   name TEXT,
   email TEXT
);

INSERT INTO organizations (members) VALUES
   ('[{ "id": 23, "role": "admin" }, { "id": 24, "role": "default" }]'),
   ('[{ "id": 23, "role": "user" }]'),
   ('[{ "id": 24, "role": "admin" }, { "id": 25, "role": "default" }]'),
   ('[{ "id": 25, "role": "user" }]');

INSERT INTO users (id, name, email) VALUES
   (23, 'Max', 'max@gmail.com'),
   (24, 'Joe', 'joe@gmail.com'),
   (25, 'Alice', 'alice@gmail.com');
```

You can use the `jsonb_array_elements` function to extract the `members` from the `JSONB` array in the `organizations` table and then join with the `users` table.

```sql
SELECT
   o.id AS organization_id,
   u.id AS user_id,
   u.name AS user_name,
   u.email AS user_email,
   m->>'role' AS member_role
FROM
   organizations o
JOIN jsonb_array_elements(o.members) AS m ON true
JOIN users u ON m->>'id' = u.id::TEXT;
```

This query returns the following values:

```
| organization_id | user_id | user_name |   user_email    | member_role |
|-----------------|---------|-----------|-----------------|-------------|
|               2 |      23 | Max       | max@gmail.com   | user        |
|               1 |      23 | Max       | max@gmail.com   | admin       |
|               3 |      24 | Joe       | joe@gmail.com   | admin       |
|               1 |      24 | Joe       | joe@gmail.com   | default     |
|               4 |      25 | Alice     | alice@gmail.com | user        |
|               3 |      25 | Alice     | alice@gmail.com | default     |
```

## Additional considerations

This section outlines additional considerations including alternative functions.

### Alternatives to `jsonb_array_elements`

Use `jsonb_array_elements` when you need to maintain the `JSON` structure of the elements for further `JSON`-related operations or analysis and `jsonb_array_elements_text` if you need to work with the extracted elements as plain text for string operations, text analysis, or integration with text-based functions.

If you want to create a comma-separated list of all skills for each developer in the `developers` table, `jsonb_array_elements_text` can be used along with `string_agg`.

```sql
SELECT name, string_agg(skill, ',') AS skill_list
FROM developers, jsonb_array_elements_text(skills) AS skill
GROUP BY name;
```

This query returns the following values:

```
|  name   |   skill_list    |
|---------|-----------------|
|  Alice  | Java,Python,SQL |
|   Bob   | C++,JavaScript  |
| Charlie | HTML,CSS,React  |
```

Using `jsonb_array_elements` would result in an error because it returns `JSONB` values, which cannot be directly concatenated with the string operator.

```sql
SELECT name, string_agg(skill, ',') AS skill_list
FROM developers, jsonb_array_elements(skills) AS skill
GROUP BY name;
```

**jsonb_path_query**

`jsonb_path_query` uses `JSON` Path expressions for flexible navigation and filtering within `JSONB` structures and returns a `JSONB` array containing matching elements. It supports filtering within the path expression itself, enabling complex conditions and excels at navigating and extracting elements from nested arrays and objects.

If your query involves navigating through multiple levels of nesting, complex filtering conditions, or updates to `JSONB` data, `jsonb_path_query` is often the preferred choice.

Consider a simple example: to extract the first skill of each developer in the `developers` table:

```sql
SELECT jsonb_path_query(skills, '$[0]') AS first_skill
FROM developers;
```

This query returns the following values:

```
| first_skill |
|-------------|
|   "Java"    |
|   "C++"     |
|   "HTML"    |
```

## Resources

- [PostgreSQL documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/jsonb_each.md) ---

> Summary: `jsonb_each()` is a Postgres set-returning function that expands a JSONB object into one row per key-value pair, returning key as text and value as jsonb. Use it when you need to iterate over a JSONB object with a dynamic or unknown schema, or when you want to join expanded JSONB key-value pairs against other tables in a FROM clause. Choose `jsonb_each_text()` instead when you need the value as plain text, or `json_each()` when the input is JSON rather than JSONB.

# Postgres jsonb_each() function

Expands JSONB into a record per key-value pair

Last updated: 2026-06-05

The `jsonb_each` function in Postgres is used to expand a `JSONB` object into a set of key-value pairs.

It is useful when you need to iterate over a `JSONB` object's keys and values, such as when you're working with dynamic `JSONB` structures where the schema is not fixed. Another important use case is performing data transformations and analytics.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
jsonb_each(json JSON) -> SETOF record(key text, value json)
```

The function returns a set of rows, each containing a key and the corresponding value for each field in the input `JSONB` object. The key is of type `text`, while the value is of type `JSONB`.

## Example usage

Consider a `JSONB` object representing a user's profile information. The `JSONB` data will have multiple attributes and might look like this:

```json
{
  "username": "johndoe",
  "age": 30,
  "email": "johndoe@example.com"
}
```

We can go over all the fields in the profile `JSONB` object using `jsonb_each`, and produce a row for each key-value pair.

```sql
SELECT key, value
FROM jsonb_each('{"username": "johndoe", "age": 30, "email": "johndoe@example.com"}');
```

This query returns the following results:

```text
| key      | value                 |
|----------|-----------------------|
| username | "johndoe"             |
| age      | 30                    |
| email    | "johndoe@example.com" |
```

## Advanced examples

### Assign custom names to columns output by `jsonb_each`

You can use `AS` to specify custom column names for the key and value columns.

```sql
SELECT attr_name, attr_value
FROM jsonb_each('{"username": "johndoe", "age": 30, "email": "johndoe@example.com"}')
AS user_data(attr_name, attr_value);
```

This query returns the following results:

```text
| attr_name | attr_value            |
|-----------|-----------------------|
| username  | "johndoe"             |
| age       | 30                    |
| email     | "johndoe@example.com" |
```

### Use `jsonb_each` output as a table or row source

Since `jsonb_each` returns a set of rows, you can use it as a table source in a `FROM` clause. This lets us join the expanded `JSONB` data in the output with other tables.

Here, we're joining each row in the `user_data` table with the output of `jsonb_each`:

```sql
CREATE TABLE user_data (
    id INT,
    profile JSON
);
INSERT INTO user_data (id, profile)
VALUES
    (123, '{"username": "johndoe", "age": 30, "email": "johndoe@example.com"}'),
    (140, '{"username": "mikesmith", "age": 40, "email": "mikesmith@example.com"}');

SELECT id, key, value
FROM user_data, jsonb_each(user_data.profile);
```

This query returns the following results:

```text
| id  | key      | value                   |
|-----|----------|-------------------------|
| 123 | username | "johndoe"               |
| 123 | age      | 30                      |
| 123 | email    | "johndoe@example.com"   |
| 140 | username | "mikesmith"             |
| 140 | age      | 40                      |
| 140 | email    | "mikesmith@example.com" |
```

## Additional considerations

### Performance implications

When working with large `JSONB` objects, `jsonb_each` may lead to performance overhead, as it expands each key-value pair into a separate row.

### Alternative functions

- `jsonb_each_text` - Similar functionality to `jsonb_each` but returns the value as a text type instead of `JSONB`.
- `jsonb_object_keys` - It returns only the set of keys in the `JSONB` object, without the values.
- [json_each](https://neon.com/docs/functions/json_each) - It provides the same functionality as `jsonb_each`, but accepts `JSON` input instead of `JSONB`.

## Resources

- [PostgreSQL documentation: JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/jsonb_extract_path_text.md) ---

> Summary: `jsonb_extract_path_text(from_json, path_elems...)` extracts a value from a Postgres JSONB object at a variadic key path and returns it as plain `TEXT`, unlike `jsonb_extract_path` which returns JSONB. Use it when you need to compare or pattern-match JSONB field values directly in `WHERE`, `JOIN`, or `LIKE` clauses without a separate cast. The function accepts numeric string indices to traverse JSONB arrays, and GIN indexing on the source column can improve query performance.

# Postgres jsonb_extract_path_text() Function

Extracts a JSON sub-object at the specified path as text

Last updated: 2026-06-05

The `jsonb_extract_path_text` function is designed to simplify extracting text from `JSONB` data in Postgres. This function is similar to `jsonb_extract_path`; it also produces the value at the specified path from a `JSONB` object but casts it to plain text before returning. This makes it more straightforward for text manipulation and comparison operations.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
jsonb_extract_path_text(from_json JSONB, VARIADIC path_elems text[]) -> TEXT
```

The function accepts a `JSONB` object and a variadic list of elements that specify the path to the desired value.

## Example usage

Let's consider a `users` table with a `JSONB` column named `profile` containing various user details.

Here's how we can create the table and insert some sample data:

```sql
CREATE TABLE users (
    id INT,
    profile JSONB
);

INSERT INTO users (id, profile)
VALUES
    (1, '{"name": "Alice", "contact": {"email": "alice@example.com", "phone": "1234567890"}, "hobbies": ["reading", "cycling", "hiking"]}'),
    (2, '{"name": "Bob", "contact": {"email": "bob@example.com", "phone": "0987654321"}, "hobbies": ["gaming", "cooking"]}');
```

To extract and view the email addresses of all users, we can run the following query:

```sql
SELECT id, jsonb_extract_path_text(profile, 'contact', 'email') as email
FROM users;
```

This query returns the following:

```text
| id | email              |
|----|--------------------|
| 1  | alice@example.com  |
| 2  | bob@example.com    |
```

## Advanced examples

### Use output of `jsonb_extract_path_text` in a `JOIN` clause

Let's say we have another table, `hobbies`, that includes additional information such as difficulty level and the average cost to practice each hobby.

We can create the `hobbies` table with some sample data with the following statements:

```sql
CREATE TABLE hobbies (
   hobby_id SERIAL PRIMARY KEY,
   hobby_name VARCHAR(255),
   difficulty_level VARCHAR(50),
   average_cost VARCHAR(50)
);

INSERT INTO hobbies (hobby_name, difficulty_level, average_cost)
VALUES
    ('Reading', 'Easy', 'Low'),
    ('Cycling', 'Moderate', 'Medium'),
    ('Gaming', 'Variable', 'High'),
    ('Cooking', 'Variable', 'Low');
```

The `users` table we created previously has a `JSONB` column named `profile` that contains information about each user's preferred hobbies. A fun exercise could be to find if a user has any hobbies that are easy to get started with. Then we can recommend they engage with it more often.

To fetch this list, we can run the query below.

```sql
SELECT
  jsonb_extract_path_text(u.profile, 'name') as user_name,
  h.hobby_name
FROM users u
JOIN hobbies h
ON jsonb_extract_path_text(u.profile, 'hobbies') LIKE '%' || lower(h.hobby_name) || '%'
WHERE h.difficulty_level = 'Easy';
```

We use `jsonb_extract_path_text` to extract the list of hobbies for each user, and then check if the name of an easy hobby is present in the list.

This query returns the following:

```text
| user_name | hobby_name |
|-----------|------------|
| Alice     | Reading    |
```

### Extract values from JSON array with `jsonb_extract_path_text`

`jsonb_extract_path_text` can also be used to extract values from `JSONB` arrays.

For instance, to extract the first and second hobbies for everyone, we can run the following query:

```sql
SELECT
    jsonb_extract_path_text(profile, 'name') as name,
    jsonb_extract_path_text(profile, 'hobbies', '0') as first_hobby,
    jsonb_extract_path_text(profile, 'hobbies', '1') as second_hobby
FROM users;
```

This query returns the following:

```text
| name  | first_hobby | second_hobby |
|-------|-------------|--------------|
| Alice | reading     | cycling      |
| Bob   | gaming      | cooking      |
```

## Additional considerations

### Performance and indexing

Performance considerations for `jsonb_extract_path_text` are similar to those for `json_extract_path`. It is efficient for extracting data but can be impacted by large `JSONB` objects or complex queries. Indexing the `JSONB` column can improve performance in some cases.

### Alternative functions

- [jsonb_extract_path](https://neon.com/docs/functions/jsonb_extract_path) - This is a similar function that can extract data from a `JSONB` object at the specified path. The difference is that it returns a `JSONB` object, while `jsonb_extract_path_text` always returns text. The right function to use depends on what you want to use the output data for.
- [json_extract_path_text](https://neon.com/docs/functions/json_extract_path_text) - This is a similar function that can extract data from a `JSON` object, (instead of `JSONB`) at the specified path.

## Resources

- [PostgreSQL Documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL Documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/jsonb_extract_path.md) ---

> Summary: `jsonb_extract_path(from_json, path_elems...)` extracts a nested value from a JSONB document by following a variadic text key path and returns the result as JSONB, making it faster than fetching and parsing the full document in application code. Use it instead of `jsonb_extract_path_text` when the extracted value must stay JSONB for further JSON operators or functions, and instead of `json_extract_path` when your column is JSONB rather than JSON. Invalid paths return NULL rather than an error, and GIN indexes on the JSONB column can improve performance when filtering on extracted values.

# Postgres jsonb_extract_path() function

Extracts a JSONB sub-object at the specified path

Last updated: 2026-06-05

You can use the `jsonb_extract_path` function to extract the value at a specified path within a `JSONB` document. This approach is more performant compared to querying the entire `JSONB` payload and processing it on the application side. Use it when dealing with nested `JSONB` structures.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
jsonb_extract_path(from_json JSONB, VARIADIC path_elems TEXT[]) -> JSONB
```

## Example usage

To illustrate the `jsonb_extract_path` function in Postgres, let's consider a scenario where we have a table storing information about books. Each book has a `JSONB` column containing details such as `title`, `author`, and publication `year`. You can create the `book` table using the SQL statements shown below.

**books**

```sql
CREATE TABLE books (
    id INT,
    info JSONB
);

INSERT INTO books (id, info)
VALUES
    (1, '{"title": "The Catcher in the Rye", "author": "J.D. Salinger", "year": 1951}'),
    (2, '{"title": "To Kill a Mockingbird", "author": "Harper Lee", "year": 1960}'),
    (3, '{"title": "1984", "author": "George Orwell", "year": 1949}');
```

```text
| id | info                                                                         |
|----|------------------------------------------------------------------------------|
| 1  | {"title": "The Catcher in the Rye", "author": "J.D. Salinger", "year": 1951} |
| 2  | {"title": "To Kill a Mockingbird", "author": "Harper Lee", "year": 1960}     |
| 3  | {"title": "1984", "author": "George Orwell", "year": 1949}                   |
```

Now, let's use the `jsonb_extract_path` function to extract the `title` and `author` of each book:

```sql
SELECT
    id,
    jsonb_extract_path(info, 'title') as title,
    jsonb_extract_path(info, 'author') as author
FROM books;
```

This query returns the following values:

```text
| id | title                    | author           |
|----|--------------------------|------------------|
| 1  | "The Catcher in the Rye" | "J.D. Salinger"  |
| 2  | "To Kill a Mockingbird"  | "Harper Lee"     |
| 3  | "1984"                   | "George Orwell"  |
```

## Advanced examples

Consider a `products` table that stores information about the products in an e-commerce system. The table schema and data are outlined below.

**products**

```sql
CREATE TABLE products (
    id INT,
    attributes JSONB
);

INSERT INTO products (id, attributes)
VALUES
    (1, '{"name": "Laptop", "specs": {"brand": "Dell", "RAM": "16GB", "storage": {"type": "SSD", "capacity": "512GB"}}, "tags": ["pc"]}'),
    (2, '{"name": "Smartphone", "specs": {"brand": "Google", "RAM": "8GB", "storage": {"type": "UFS", "capacity": "256GB"}}, "tags": ["android",
    "pixel"]}'),
    (3, '{"name": "Smartphone", "specs": {"brand": "Apple", "RAM": "8GB", "storage": {"type": "UFS", "capacity": "128GB"}}, "tags": ["ios", "iphone"]}');
```

```text
| id     | attributes                                                                                                                                        |
|--------|---------------------------------------------------------------------------------------------------------------------------------------------------|
| 1      | {"name": "Laptop", "specs": {"brand": "Dell", "RAM": "16GB", "storage": {"type": "SSD", "capacity": "512GB"}}, "tags": ["pc"]}                    |
| 2      | {"name": "Smartphone", "specs": {"brand": "Google", "RAM": "8GB", "storage": {"type": "UFS", "capacity": "256GB"}}, "tags": ["android", "pixel"]} |
| 3      | {"name": "Smartphone", "specs": {"brand": "Apple", "RAM": "8GB", "storage": {"type": "UFS", "capacity": "128GB"}}, "tags": ["ios", "iphone"]}     |
```

### Extract value from nested JSONB object with `jsonb_extract_path`

Let's use `jsonb_extract_path` to retrieve information about the storage type and capacity for each product, demonstrating how to extract values from a nested `JSONB` object.

```sql
SELECT
    id,
    jsonb_extract_path(attributes, 'specs', 'storage', 'type') as storage_type,
    jsonb_extract_path(attributes, 'specs', 'storage', 'capacity') as storage_capacity
FROM products;
```

This query returns the following values:

```text
| id | storage_type | storage_capacity |
|----|--------------|------------------|
| 1  | "SSD"        | "512GB"          |
| 2  | "UFS"        | "256GB"          |
| 3  | "UFS"        | "128GB"          |
```

### Extract values from JSON array with `jsonb_extract_path`

Now, let's use `jsonb_extract_path` to extract information about the associated tags as well, demonstrating how to extract values from a `JSONB` array.

```sql
SELECT
    id,
    jsonb_extract_path(attributes, 'specs', 'storage', 'type') as storage_type,
    jsonb_extract_path(attributes, 'specs', 'storage', 'capacity') as storage_capacity,
    jsonb_extract_path(attributes, 'tags', '0') as first_tag,
    jsonb_extract_path(attributes, 'tags', '1') as second_tag
FROM products;
```

This query returns the following values:

```text
| id | storage_type | storage_capacity | first_tag | second_tag |
|----|--------------|------------------|-----------|------------|
| 1  | "SSD"        | "512GB"          | "pc"      |  null      |
| 2  | "UFS"        | "256GB"          | "android" | "pixel"    |
| 3  | "UFS"        | "128GB"          | "ios"     | "iphone"   |
```

### Joining data with values extracted using `jsonb_extract_path`

Let's say you have two tables, `employees` and `departments`, and the `employees` table has a `JSONB` column named `details` that contains information about each employee's department. You want to join these tables based on the department information stored in the `JSONB` column.

The table schemas and data used in this example are shown below.

**departments**

```sql
CREATE TABLE departments (
    department_id SERIAL PRIMARY KEY,
    department_name VARCHAR(255)
);

INSERT INTO departments (department_name)
VALUES
    ('IT'),
    ('HR'),
    ('Marketing');
```

```text
| department_id | department_name  |
|---------------|------------------|
|             1 | IT               |
|             2 | HR               |
|             3 | Marketing        |
```

**employees**

```sql
CREATE TABLE employees (
    employee_id SERIAL PRIMARY KEY,
    employee_name VARCHAR(255),
    details JSONB
);

INSERT INTO employees (employee_name, details)
VALUES
    ('John Doe', '{"department": "IT"}'),
    ('Jane Smith', '{"department": "HR"}'),
    ('Bob Johnson', '{"department": "Marketing"}');
```

```text
| employee_id | employee_name |           details           |
|-------------|---------------|-----------------------------|
|           1 | John Doe      | {"department": "IT"}        |
|           2 | Jane Smith    | {"department": "HR"}        |
|           3 | Bob Johnson   | {"department": "Marketing"} |
```

You can use `JOIN` with `jsonb_extract_path` to retrieve the value to join on:

```sql
SELECT
    employees.employee_name,
    departments.department_name
FROM
    employees
JOIN
    departments ON TRIM(BOTH '"' FROM jsonb_extract_path(employees.details, 'department')::TEXT) = departments.department_name;
```

This query returns the following values:

```test
| employee_name | department_name  |
|---------------|------------------|
| John Doe      | IT               |
| Jane Smith    | HR               |
| Bob Johnson   | Marketing        |
```

The `jsonb_extract_path` function extracts the value of the `department` key from the `JSONB` column in the `employees` table. The `JOIN` is then performed based on matching department names.

### Handling invalid path inputs to `jsonb_extract_path`

`jsonb_extract_path` handles an invalid path by returning `NULL`, as in the following example:

```sql
SELECT
    id,
    jsonb_extract_path(attributes, 'speks') as storage_type
FROM products;
```

The query above, which specifies an invalid path (`'speks'` instead of `'specs'`), returns `NULL` as shown:

```text
 id | storage_type
----+--------------
  1 |
  2 |
  3 |
```

## Additional considerations

### Performance and Indexing

The `jsonb_extract_path` function performs well when extracting data from `JSONB` documents, especially compared to extracting data in application code. It allows performing the extraction directly in the database, avoiding transferring entire `JSONB` documents to the application.

Indexing `JSONB` documents can also significantly improve `jsonb_extract_path` query performance when filtering data based on values extracted from `JSON`.

### Alternative functions

- [jsonb_extract_path_text](https://neon.com/docs/functions/jsonb_extract_path_text) - The regular `jsonb_extract_path` function returns the extracted value as a `JSONB` object or array, preserving its `JSON` structure, whereas the alternative `jsonb_extract_path_text` function returns the extracted value as a plain text string, casting any `JSONB` objects or arrays to their string representations.

  Use the regular `jsonb_extract_path` function when you need to apply `JSONB`-specific functions or operators to the extracted value, requiring `JSONB` data types. The alternative `jsonb_extract_path_text` function is preferable if you need to work directly with the extracted value as a string, for text processing, concatenation, or comparison.

- [json_extract_path](https://neon.com/docs/functions/json_extract_path) - The `jsonb_extract_path` function works with the `JSONB` data type, which offers a binary representation of `JSON` data, whereas `json_extract_path` takes a `JSON` value as an input and returns `JSON` too. The `JSONB` variant is typically more performant at query time, which is even more pronounced with larger `JSON` data payloads and frequent path extractions.

## Resources

- [PostgreSQL documentation: JSON Functions and Operators](https://www.postgresql.org/docs/current/functions-json.html)
- [PostgreSQL documentation: JSON Types](https://www.postgresql.org/docs/current/datatype-json.html)

--- [Document source](https://neon.com/docs/functions/jsonb_object.md) ---

> Summary: The `jsonb_object` function in Postgres constructs a JSONB object from two parallel text arrays (keys and values) or a single interleaved text array, returning binary JSONB rather than text JSON. Use it when you need to build a JSONB object row-by-row from column data or query parameters, as opposed to `json_object` (returns JSON) or `jsonb_object_agg` (aggregates across rows). Both input arrays must be the same length and contain text values; non-text columns require an explicit cast to TEXT.

# Postgres jsonb_object() function

Creates a JSONB object from key-value pairs

Last updated: 2026-06-05

The `jsonb_object` function in Postgres is used to create a `JSONB` object from a set of key-value pairs. Use it when you need to generate `JSONB` data dynamically from existing table data or input parameters.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
jsonb_object(keys TEXT[], values TEXT[]) -> JSONB
-- or --
jsonb_object(keys_values TEXT[]) -> JSONB
```

This function takes two text arrays as input: one for keys and one for values. Both arrays must have the same number of elements, as each key is paired with the corresponding value to construct the `JSONB` object.

Alternatively, you can pass a single text array containing both keys and values. In this case, alternate elements in the array are treated as keys and values, respectively.

## Example usage

Consider a scenario where you run a library and have a table that tracks details for each book.

The table with some sample data can be set up as shown:

```sql
-- Test database table for a bookstore inventory
CREATE TABLE book_inventory (
    book_id INT,
    title TEXT,
    author TEXT,
    price NUMERIC,
    genre TEXT
);

-- Inserting some test data into `book_inventory`
INSERT INTO book_inventory VALUES
(101, 'The Great Gatsby', 'F. Scott Fitzgerald', 18.99, 'Classic'),
(102, 'Invisible Man', 'Ralph Ellison', 15.99, 'Novel');
```

When querying this dataset, the frontend client might want to present the data in a different way. Say you want the catalog information just as the list of book names while combining the rest of the fields into a single `metadata` attribute. You can do so as shown here:

```sql
SELECT book_id, title, jsonb_object(
  ARRAY['author', 'genre'],
  ARRAY[author, genre]
) AS metadata
FROM book_inventory;
```

This query returns the following result:

```text
| book_id | title            | metadata                                   |
|---------|------------------|--------------------------------------------|
| 101     | The Great Gatsby | {"author" : "F. Scott Fitzgerald",         |
|         |                  |  "genre" : "Classic"}                      |
| 102     | Invisible Man    | {"author" : "Ralph Ellison",               |
|         |                  |  "genre" : "Novel"}                        |
```

## Advanced examples

### Creating nested JSON objects with `jsonb_object`

You could use `jsonb_object` to create nested `JSONB` objects for representing more complex data. However, since `jsonb_object` only expects text values for each key, we will need to combine it with other `JSONB` functions like `jsonb_build_object`. For example:

```sql
SELECT jsonb_build_object(
  'title', title,
  'author', jsonb_object(ARRAY['name', 'genre'], ARRAY[author, genre])
) AS book_info
FROM book_inventory;
```

This query returns the following result:

```text
| book_info                                                                                        |
|--------------------------------------------------------------------------------------------------|
| {"title" : "The Great Gatsby", "author" : {"name" : "F. Scott Fitzgerald", "genre" : "Classic"}} |
| {"title" : "Invisible Man", "author" : {"name" : "Ralph Ellison", "genre" : "Novel"}}            |
```

## Additional considerations

### Gotchas

- Ensure both keys and values arrays have the same number of elements. Mismatched arrays will result in an error. Or, if passing in a single key-value array, ensure that the array has an even number of elements.
- Be aware of data type conversions. Since `jsonb_object` expects text arrays, you may need to explicitly cast non-text data types to text.

### Alternative options

- [json_object](https://neon.com/docs/functions/json_object) - Same functionality as `jsonb_object`, but returns a `JSON` object instead of `JSONB`.
- [to_jsonb](https://www.postgresql.org/docs/current/functions-json.html) - It can be used to create a `JSONB` object from a table row (or a row of a composite type) without needing to specify keys and values explicitly. Although, it is less flexible than `jsonb_object` since all fields in the row are included in the `JSONB` object.
- [jsonb_build_object](https://www.postgresql.org/docs/current/functions-json.html) - Similar to `jsonb_object`, but allows for more flexibility in constructing the `JSONB` object, as it can take a variable number of arguments in the form of key-value pairs.
- [jsonb_object_agg](https://www.postgresql.org/docs/current/functions-json.html) - It is used to aggregate the key-value pairs from multiple rows into a single `JSONB` object. In contrast, `jsonb_object` outputs a `JSONB` object for each row.

## Resources

- [PostgreSQL documentation: JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/jsonb_populate_record.md) ---

> Summary: `jsonb_populate_record(base_record, json)` casts a JSONB object onto a pre-defined Postgres row type or custom composite type, returning a single typed record with missing keys filled from the base record's values rather than NULL. Choose it over `jsonb_to_record` when the target type already exists as a table row or CREATE TYPE and partial JSONB payloads should inherit default field values from a supplied base record. For JSON input use `json_populate_record`; for converting a JSONB array into multiple rows use `jsonb_populate_recordset`.

# Postgres jsonb_populate_record() function

Casts a JSONB object to a record

Last updated: 2026-06-05

The `jsonb_populate_record` function is used to populate a record type with values from a `JSONB` object. It is useful for parsing `JSONB` data received from external sources, particularly when merging it into an existing record.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
jsonb_populate_record(base_record ANYELEMENT, json JSONB) -> ANYELEMENT
```

This function takes two arguments: a base record of a row type (which can even be a `NULL` record) and a `JSONB` object. It returns the record updated with the `JSONB` values.

## Example usage

Consider a database table that tracks employee information. When you receive employee information as `JSONB` records, you can use `jsonb_populate_record` to ingest the data into the table.

Here we create the `employees` table with some sample data.

```sql
CREATE TABLE employees (
    id INT,
    name TEXT,
    department TEXT,
    salary NUMERIC
);
```

To illustrate, we start with a `NULL` record and cast the input `JSONB` payload to the `employees` record type.

```sql
INSERT INTO employees
SELECT *
FROM jsonb_populate_record(
    NULL::employees,
    '{"id": "123", "name": "John Doe", "department": "Engineering", "salary": "75000"}'
)
RETURNING *;
```

This query returns the following result:

```text
| id | name     | department  | salary |
|----|----------|-------------|--------|
| 123| John Doe | Engineering | 75000  |
```

## Advanced examples

### Handling partial data with `jsonb_populate_record`

For data points where the `JSONB` objects have missing keys, `jsonb_populate_record` can still cast them into legible records.

Say we receive records for a bunch of employees who are known to be in Sales, but the `department` field is missing from the `JSONB` payload. We can use `jsonb_populate_record` with the default value specified for a field while the other fields are populated from the `JSONB` payload, as in this example:

```sql
INSERT INTO employees
SELECT *
FROM jsonb_populate_record(
    (1, 'ABC', 'Sales', 0)::employees,
    '{"id": "124", "name": "Jane Smith", "salary": "68000"}'
)
RETURNING *;
```

This query returns the following:

```text
| id | name       | department | salary |
|----|------------|------------|--------|
| 124| Jane Smith | Sales      | 68000  |
```

### Using `jsonb_populate_record` with custom types

The base record doesn't need to have the type of a table row and can be a [custom Postgres type](https://www.postgresql.org/docs/current/sql-createtype.html) too. For example, here we first define a custom type `address` and use `jsonb_populate_record` to cast a `JSONB` object to it:

```sql
CREATE TYPE address AS (
    street TEXT,
    city TEXT,
    zip TEXT
);

SELECT *
FROM jsonb_populate_record(
    NULL::address,
    '{"street": "123 Main St", "city": "San Francisco", "zip": "94105"}'
);
```

This query returns the following result:

```text
| street     | city          | zip   |
|------------|---------------|-------|
| 123 Main St| San Francisco | 94105 |
```

## Additional considerations

### Alternative options

- [jsonb_to_record](https://neon.com/docs/functions/jsonb_to_record) - It can be used similarly, with a couple differences. `jsonb_populate_record` can be used with a base record of a pre-defined type, whereas `jsonb_to_record` needs the record type defined inline in the `AS` clause. Further, `jsonb_populate_record` can specify default values for missing fields through the base record, whereas `jsonb_to_record` must assign them NULL values.
- `jsonb_populate_recordset` - It can be used similarly to parse `JSONB`, the difference being that it returns a set of records instead of a single record. For example, if you have an array of `JSONB` objects, you can use `jsonb_populate_recordset` to convert each object into a new row.
- [json_populate_record](https://neon.com/docs/functions/json_populate_record) - It has the same functionality to `jsonb_populate_record`, but accepts `JSON` input instead of `JSONB`.

## Resources

- [Postgres documentation: JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/jsonb_to_record.md) ---

> Summary: The `jsonb_to_record` function converts a single JSONB object into a typed row using an inline column definition list in the AS clause, mapping JSON keys to typed columns and producing NULL for missing keys. Use it when ingesting JSONB from external sources such as APIs or file uploads and you need to parse one record at a time without pre-defining a named type. It differs from `jsonb_populate_record`, which requires a pre-existing record type, and from `jsonb_to_recordset`, which expands a JSONB array into multiple rows.

# Postgres jsonb_to_record() function

Convert a JSONB object to a record

Last updated: 2026-06-05

You can use the `jsonb_to_record` function to convert a top-level `JSONB` object into a row, with the type specified by the `AS` clause.

This function is useful when you need to parse `JSONB` data received from external sources, such as APIs or file uploads, and store it in a structured format. By using `jsonb_to_record`, you can easily extract values from `JSONB` and map them to the corresponding columns in your database table.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

```sql
jsonb_to_record(json JSONB) AS (column_name column_type [, ...])
```

The function's definition includes a column definition list, where you specify the name and data type of each column in the resulting record.

## Example usage

Consider a scenario in which you have `JSONB` data representing employee information, and you want to ingest it for easier processing later. The `JSONB` data looks like this:

```json
{
  "id": "123",
  "name": "John Doe",
  "department": "Engineering",
  "salary": "75000"
}
```

The table you want to insert data into is defined as follows:

```sql
CREATE TABLE employees (
    id INT,
    name TEXT,
    department TEXT,
    salary NUMERIC
);
```

Using `jsonb_to_record`, you can insert the input data into the `employees` table as shown:

```sql
INSERT INTO employees
SELECT *
FROM jsonb_to_record('{"id": "123", "name": "John Doe", "department": "Engineering", "salary": "75000"}') AS x(id INT, name TEXT, department TEXT, salary NUMERIC);
```

Note that the string representation of the JSON object didn't need to be explicitly cast to `JSONB`. Postgres automatically casts it to `JSONB` when the function is called.

To verify the data was inserted, you can run the following query:

```sql
SELECT * FROM employees;
```

This query returns the following result:

```text
| id | name     | department   | salary |
|----|----------|--------------|--------|
| 123| John Doe | Engineering  | 75000  |
```

## Advanced examples

This section provides advanced `jsonb_to_record` examples.

### Handling partial data with `jsonb_to_record`

For datapoints where the `JSONB` objects have missing keys, `jsonb_to_record` can still cast them into records, producing `NULL` values for the unmatched columns. For example:

```sql
INSERT INTO employees
SELECT *
FROM jsonb_to_record('{
  "id": "124",
  "name": "Jane Smith"
}') AS x(id INT, name TEXT, department TEXT, salary NUMERIC)
RETURNING *;
```

This query returns the following result:

```
| id | name       | department   | salary |
|----|------------|--------------|--------|
| 124| Jane Smith |              |        |
```

### Handling nested data with `jsonb_to_record`

`jsonb_to_record` can also be used to handle nested `JSONB` input data (i.e., keys with values that are `JSONB` objects themselves). You need to first define a [custom Postgres type](https://www.postgresql.org/docs/current/sql-createtype.html). The newly created type can then be used in the column definition list along with the other columns.

In the following example, we handle the `address` field by creating an `ADDRESS_TYPE` type first.

```sql
CREATE TYPE ADDRESS_TYPE AS (
  street TEXT,
  city TEXT
);

SELECT *
FROM jsonb_to_record('{
  "id": "125",
  "name": "Emily Clark",
  "department": "Marketing",
  "salary": "68000",
  "address": {
    "street": "123 Elm St",
    "city": "Springfield"
  }
}') AS x(id INT, name TEXT, department TEXT, salary NUMERIC, address ADDRESS_TYPE);
```

This query returns the following result:

```text
| id | name        | department | salary | address                     |
|----|-------------|------------|--------|-----------------------------|
| 1  | Emily Clark | Marketing  | 68000  | ("123 Elm St", Springfield) |
```

### Alternative functions

- [jsonb_populate_record](https://neon.com/docs/functions/jsonb_populate_record): This function can also be used to create records using values from a `JSONB` object. The difference is that `jsonb_populate_record` requires the record type to be defined beforehand, while `jsonb_to_record` needs the type definition inline.
- [jsonb_to_recordset](https://www.postgresql.org/docs/current/functions-json.html): This function can be used similarly to parse `JSONB`, the difference being that it returns a set of records instead of a single record. For example, if you have an array of `JSONB` objects, you can use `jsonb_to_recordset` to convert each object into a new row.
- [json_to_record](https://neon.com/docs/functions/json_to_record): This function provides the same functionality as `json_to_record`, but accepts `JSON` input instead of `JSONB`. In cases where the input payload type isn't exactly specified, either of the two functions can be used.

  For example, take this `json_to_record` query:

  ```sql
  SELECT *
  FROM json_to_record('{"id": "123", "name": "John Doe", "department": "Engineering"}')
  AS x(id INT, name TEXT, department TEXT);
  ```

  It works just as well as this `JSONB` variant (below) since Postgres casts the literal `JSON` object to `JSON` or `JSONB` depending on the context.

  ```sql
  SELECT *
  FROM jsonb_to_record('{"id": "123", "name": "Sally", "department": "Engineering"}')
  AS x(id INT, name TEXT, department TEXT);
  ```

## Resources

- [PostgreSQL documentation: JSON functions](https://www.postgresql.org/docs/current/functions-json.html)

--- [Document source](https://neon.com/docs/functions/lower.md) ---

> Summary: The Postgres lower() function converts any text string to all-lowercase characters, enabling case-insensitive comparisons and consistent storage of values such as email addresses and usernames. Use lower() in WHERE clauses for case-insensitive search, or build a functional index on lower(column) to keep query performance high on large tables without altering stored data. The function respects the database locale for language-specific case rules and pairs with upper() and initcap() for broader text normalization workflows.

# Postgres lower() function

Convert strings to lowercase

Last updated: 2026-06-05

The `lower()` function in Postgres is used to convert a string to lowercase.

It's commonly used for search functionality where you want case-insensitivity or when you need to standardize user input for storage or comparison purposes. For example, `lower()` can be used to normalize email addresses or usernames in a user management system.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `lower()` function has a simple signature:

```sql
lower(string text) -> text
```

- `string`: The input string to be converted to lowercase.

## Example usage

Consider a table `products` with a `product_name` column that contains product names with inconsistent capitalization. We can use `lower()` to standardize these names for comparison or display purposes.

```sql
WITH products AS (
    SELECT *
    FROM (
        VALUES
            ('LAPTOP Pro X'),
            ('SmartPhone Y'),
            ('Tablet ULTRA 2')
    ) AS t(product_name)
)
SELECT lower(product_name) AS standardized_name
FROM products;
```

This query converts all product names to lowercase, making them consistent regardless of their original capitalization. Note that non-alphabetic characters are left unchanged.

```text
 standardized_name
-------------------
 laptop pro x
 smartphone y
 tablet ultra 2
(3 rows)
```

## Advanced examples

### Case-insensitive search

You can use `lower()` in a `WHERE` clause to perform case-insensitive searches:

```sql
WITH customers AS (
  SELECT 'John Doe' AS name, 'JOHN.DOE@EXAMPLE.COM' AS email
  UNION ALL
  SELECT 'Jane Smith' AS name, 'jane.smith@example.com' AS email
  UNION ALL
  SELECT 'Bob Johnson' AS name, 'Bob.Johnson@Example.com' AS email
)
SELECT name, email
FROM customers
WHERE lower(email) LIKE lower('%John.%');
```

This query will find the customer regardless of how the email address was capitalized in the database or search term.

```text
   name   |        email
----------+----------------------
 John Doe | JOHN.DOE@EXAMPLE.COM
(1 row)
```

### Combining with other string functions

`lower()` can be combined with other string functions for more complex operations:

```sql
WITH user_data AS (
  SELECT 'JOHN_DOE_123' AS username
  UNION ALL
  SELECT 'JANE_SMITH_456' AS username
  UNION ALL
  SELECT 'BOB_JOHNSON_789' AS username
)
SELECT
  lower(split_part(username, '_', 1)) AS first_name,
  lower(split_part(username, '_', 2)) AS last_name,
  split_part(username, '_', 3) AS user_id
FROM user_data;
```

This query splits the username into parts, converts the name parts to lowercase, and keeps the user ID as-is.

### Using `lower()` to create indexes

Postgres supports creating a _functional index_ based on the result of a function applied to a column. To optimize case-insensitive searches, we can create an index using the `lower()` function:

```sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL
);

CREATE INDEX idx_users_name_lower ON users (lower(name));
```

This index will improve the performance of queries that use `lower(name)` to filter data.

### Normalizing data for uniqueness constraints

When you want to enforce uniqueness regardless of case, you can use `lower()` to create a unique index on the column.

```sql
CREATE TABLE organizations (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL
);

CREATE UNIQUE INDEX idx_organizations_name_lower ON organizations (lower(name));

INSERT INTO organizations (name) VALUES ('Acme Corp');
INSERT INTO organizations (name) VALUES ('Bailey Inc.');
```

Trying to insert a duplicate organization name with different capitalization will raise an error:

```sql
INSERT INTO organizations (name) VALUES ('ACME CORP');
-- ERROR:  duplicate key value violates unique constraint "idx_organizations_name_lower"
-- DETAIL:  Key (lower(name))=(acme corp) already exists.
```

## Additional considerations

### Performance implications

While `lower()` is generally fast, using it in `WHERE` clauses or `JOIN` conditions on large tables can impact performance, as it prevents the use of standard indexes directly. In such cases, consider using functional indexes as shown in the earlier example.

### Locale considerations

The `lower()` function uses the database's locale setting for its case conversion rules. If your application needs to handle multiple languages, you may need to consider using the `lower()` function with specific collations or implementing custom case-folding logic.

### Alternative functions

- `upper()` - Converts a string to uppercase.
- `initcap()` - Converts the first letter of each word to uppercase and the rest to lowercase.

## Resources

- [PostgreSQL documentation: String functions and operators](https://www.postgresql.org/docs/current/functions-string.html)
- [PostgreSQL documentation: Indexes on expressions](https://www.postgresql.org/docs/current/indexes-expressional.html)

--- [Document source](https://neon.com/docs/functions/math-abs.md) ---

> Summary: The Postgres `abs()` function returns the non-negative magnitude of any numeric input (integer, float, or decimal) by removing the sign without altering the value. Use it when you need to compare magnitudes, calculate distances, measure forecast discrepancies, or sort rows by size regardless of positive or negative sign. The `@` operator is a Postgres alias for `abs()`, and a functional index on `abs(column)` can speed up queries that filter large datasets by absolute value.

# Postgres abs() function

Calculate the absolute value of a number

Last updated: 2026-06-05

The Postgres `abs()` function is used to compute the absolute value of a number. The absolute value is the non-negative value of a number without regard to its sign.

It's useful in multiple scenarios when working with numbers, such as calculating distances, comparing magnitudes regardless of direction, or ensuring non-negative values in financial calculations.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `abs()` function has a simple form:

```sql
abs(number) -> number
```

- `number`: The input value for which you want to calculate the absolute value. It can be of any numeric data type - integer, floating-point, or decimal.

## Example usage

Consider a table `transactions` with an `amount` column that contains both positive (deposits) and negative (withdrawals) values. We can use `abs()` to order the transactions by their magnitude.

```sql
WITH transactions(id, amount) AS (
  VALUES
    (1, 100.50),
    (2, -75.25),
    (3, 200.00),
    (4, -150.75)
)
SELECT id, amount
FROM transactions
ORDER BY abs(amount) DESC;
```

This query retrieves the transaction IDs and amounts, ordering them by the absolute value of the amount, in descending order.

```text
 id | amount
----+---------
  3 |  200.00
  4 | -150.75
  1 |  100.50
  2 |  -75.25
(4 rows)
```

## Other examples

### Using abs() for distance calculations

The `abs()` function is also frequently used for distance calculations, where the direction is not relevant. Suppose we have a table of geographical coordinates and we want to find points within a certain range of a reference point.

```sql
WITH locations(name, latitude, longitude) AS (
  VALUES
    ('Point A', 40.7128, -74.0060),
    ('Point B', 40.7484, -73.9857),
    ('Point C', 41.6892, -74.0445),
    ('Reference', 40.7300, -73.9950)
)
SELECT
  name,
  abs(latitude - 40.7300) AS lat_diff,
  abs(longitude - (-73.9950)) AS long_diff
FROM locations
WHERE
  abs(latitude - 40.7300) <= 0.05 AND
  abs(longitude - (-73.9950)) <= 0.05;
```

This query finds all points within 0.05 degrees (approximately 5.5 km) of the reference point (40.7300, -73.9950) in both latitude and longitude.

```
   name    | lat_diff | long_diff
-----------+----------+-----------
 Point A   |   0.0172 |    0.0110
 Point B   |   0.0184 |    0.0093
 Reference |   0.0000 |    0.0000
(4 rows)
```

### Combining abs() with other functions

We can combine `abs()` with other functions for more complex calculations. For example, to measure the percentage discrepancy between forecasted and actual sales, we can use `abs()` to calculate the size of the difference and then divide it by the forecasted value.

```sql
WITH sales_data(product, forecast, actual) AS (
  VALUES
    ('Product A', 1000, 1100),
    ('Product B', 500, 450),
    ('Product C', 750, 725),
    ('Product D', 300, 400)
)
SELECT
  product,
  forecast,
  actual,
  round(abs(actual - forecast) / forecast::numeric * 100, 2) AS percentage_difference
FROM sales_data
ORDER BY percentage_difference DESC;
```

This query orders the products by the percentage difference between the forecasted and actual sales.

```
  product  | forecast | actual | percentage_difference
-----------+----------+--------+-----------------------
 Product D |      300 |    400 |                 33.33
 Product A |     1000 |   1100 |                 10.00
 Product B |      500 |    450 |                 10.00
 Product C |      750 |    725 |                  3.33
(4 rows)
```

## Additional considerations

### Performance implications

The `abs()` function is pretty quick, as it's a simple mathematical operation. However, if you frequently filter or join a large dataset based on absolute values, consider creating a functional index using `abs()` to speed up queries.

### Alternative functions and operators

- The `@` operator: Postgres provides the `@` operator as an alternative to the `abs()` function. It performs the same operation (calculating the absolute value) and can be used interchangeably with `abs()`. For example, `@ -5` is equivalent to `abs(-5)`.

## Resources

- [PostgreSQL documentation: Mathematical Functions and Operators](https://www.postgresql.org/docs/current/functions-math.html)
- [PostgreSQL documentation: Numeric Types](https://www.postgresql.org/docs/current/datatype-numeric.html)

--- [Document source](https://neon.com/docs/functions/math-random.md) ---

> Summary: The Postgres `random()` function returns a uniformly distributed double-precision float between 0.0 (inclusive) and 1.0 (exclusive). Starting with Postgres 17, the overloaded `random(min, max)` form generates random integers, bigints, or numerics within a caller-specified inclusive range. Use it for test data generation, statistical sampling, simulations, and any query that needs non-deterministic row selection. For reproducible sequences across sessions, pair `random()` with `setseed(value)` where value is between 0 and 1.

# Postgres random() function

Generate random values between 0 and 1

Last updated: 2026-06-05

The Postgres `random()` function generates random floating point values between 0.0 and 1.0. Starting with Postgres 17, it also supports generating random integers or decimals within a specified range using `random(min, max)` syntax.

Use it for sample data, simulations, or introducing randomness in queries for statistical sampling and testing algorithms.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signatures

The `random()` function has the following signatures:

```sql
random() -> double precision
random(min integer, max integer) -> integer      -- Added in Postgres 17
random(min bigint, max bigint) -> bigint        -- Added in Postgres 17
random(min numeric, max numeric) -> numeric      -- Added in Postgres 17
```

The first form returns a uniformly distributed random value between 0.0 (inclusive) and 1.0 (exclusive).

Starting from Postgres 17, the function also accepts range parameters:

- For integer types, it returns a random integer between min and max (inclusive)
- For numeric types, it returns a random decimal number between min and max (inclusive). The result will have the same number of decimal places as the input parameter with the highest precision.

## Example usage

```sql

SELECT random(); -- Generates a random floating point number between 0.0 and 1.0
-- 0.555470146570157

SELECT random(1, 6); -- Generates a random integer between 1 and 6
-- 4

SELECT random(1.5, 3.54); -- Generates a random decimal number between 1.5 and 3.54 with 2 decimal places precision
-- 2.66

```

### Basic random number generation

Let's create a table of simulated sensor readings with random values:

```sql
CREATE TABLE sensor_readings (
  id SERIAL PRIMARY KEY,
  sensor_name TEXT,
  temperature NUMERIC(5,2),
  humidity NUMERIC(5,2),
  timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO sensor_readings (sensor_name, temperature, humidity)
SELECT
  'Sensor-' || generate_series,
  20 + (random() * 15)::NUMERIC(5,2),  -- Temperature between 20°C and 35°C
  40 + (random() * 40)::NUMERIC(5,2)   -- Humidity between 40% and 80%
FROM generate_series(1, 5);

SELECT * FROM sensor_readings;
```

The `generate_series()` function is used to generate a series of integers from 1 to 5, which is then used to create the sensor names. Then, `random()` is used to generate random temperature and humidity values within specific ranges.

```text
 id | sensor_name | temperature | humidity |         timestamp
----+-------------+-------------+----------+----------------------------
  1 | Sensor-1    |       26.16 |    76.85 | 2024-06-23 10:34:03.627556
  2 | Sensor-2    |       31.49 |    44.88 | 2024-06-23 10:34:03.627556
  3 | Sensor-3    |       30.62 |    49.94 | 2024-06-23 10:34:03.627556
  4 | Sensor-4    |       23.32 |    79.20 | 2024-06-23 10:34:03.627556
  5 | Sensor-5    |       34.33 |    50.39 | 2024-06-23 10:34:03.627556
(5 rows)
```

### Random integer within a range

Let's simulate a dice game where each player rolls two dice, and we calculate the total:

```sql
CREATE TABLE dice_rolls (
  roll_id SERIAL PRIMARY KEY,
  player_name TEXT,
  die1 INTEGER,
  die2 INTEGER,
  total INTEGER
);

INSERT INTO dice_rolls (player_name, die1, die2, total)
SELECT
  'Player-' || generate_series,
  random(1, 6),  -- Random integer between 1 and 6
  random(1, 6),  -- Random integer between 1 and 6
  0  -- We'll update this next
FROM generate_series(1, 5);

UPDATE dice_rolls
SET total = die1 + die2;

SELECT * FROM dice_rolls;
```

This simulates 5 players each rolling two dice, with random values between 1 and 6 for each die. Notice how we can now use the simpler `random(1, 6)` syntax instead of the more complex `1 + floor(random() * 6)::INTEGER` typically used in earlier versions of Postgres.

```text
 roll_id | player_name | die1 | die2 | total
---------+-------------+------+------+-------
       1 | Player-1    |    6 |    1 |     7
       2 | Player-2    |    1 |    3 |     4
       3 | Player-3    |    5 |    1 |     6
       4 | Player-4    |    6 |    2 |     8
       5 | Player-5    |    5 |    6 |    11
(5 rows)
```

## Other examples

### Using random() for sampling

Suppose we have a large table of customer data and want to select a random sample for a survey:

```sql
CREATE TABLE customers (
  id SERIAL PRIMARY KEY,
  name TEXT,
  email TEXT
);

-- Populate the table with sample data
INSERT INTO customers (name, email)
SELECT
  'Customer-' || generate_series,
  'customer' || generate_series || '@example.com'
FROM generate_series(1, 1000);

-- Select a random 1% sample
SELECT *
FROM customers
WHERE random() < 0.01;
```

This query selects approximately 1% of the customers randomly by filtering for rows where `random()` is less than 0.01.

```text
 id  |     name     |          email
-----+--------------+-------------------------
  18 | Customer-18  | customer18@example.com
 349 | Customer-349 | customer349@example.com
 405 | Customer-405 | customer405@example.com
 519 | Customer-519 | customer519@example.com
 712 | Customer-712 | customer712@example.com
 791 | Customer-791 | customer791@example.com
 855 | Customer-855 | customer855@example.com
 933 | Customer-933 | customer933@example.com
 970 | Customer-970 | customer970@example.com
(9 rows)
```

### Combining random() with other functions

You can use `random()` in combination with other functions to generate more complex random data. For example, let's create a table of random events with timestamps within the last 24 hours:

```sql
CREATE TABLE random_events (
  id SERIAL PRIMARY KEY,
  event_type TEXT,
  severity INTEGER,
  timestamp TIMESTAMP
);

INSERT INTO random_events (event_type, severity, timestamp)
SELECT
  (ARRAY['Error', 'Warning', 'Info'])[random(1, 3)],
  random(1, 5),
  NOW() - (random() * INTERVAL '24 hours')
FROM generate_series(1, 100);

SELECT * FROM random_events
ORDER BY timestamp DESC
LIMIT 4;
```

This creates 100 random events with different types, severities, and timestamps within the last 24 hours.

```text
 id | event_type | severity |         timestamp
----+------------+----------+----------------------------
 10 | Error	     |        1 | 2024-12-04 09:44:39.651498
 47	| Info	     |        1 | 2024-12-04 09:41:50.372958
 88 | Info	     |        3 | 2024-12-04 09:40:21.689072
 74 | Warning    |        2 | 2024-12-04 09:05:22.546381
(4 rows)
```

## Additional considerations

### Seed for reproducibility

The Postgres `random()` function uses a seed that is initialized at the start of each database session. If you need reproducible random numbers across sessions, you can set the seed manually using the `setseed()` function:

```sql
SELECT setseed(0.3);
SELECT random();
```

This will produce the same sequence of random numbers in any session where you set the same seed. The `setseed()` function takes a value between 0 and 1 as its argument.

### Performance implications

The `random()` function is generally fast, but excessive use in large datasets or complex queries can impact performance. For high-performance requirements, consider generating random values in application code or using materialized views with pre-generated random data.

### Alternative functions

- `gen_random_uuid()`: Generates a random UUID, useful when you need unique identifiers.

## Resources

- [PostgreSQL documentation: Mathematical Functions and Operators](https://www.postgresql.org/docs/current/functions-math.html)
- [PostgreSQL documentation: Random Functions](https://www.postgresql.org/docs/current/functions-math.html#FUNCTIONS-MATH-RANDOM-TABLE)

--- [Document source](https://neon.com/docs/functions/math-round.md) ---

> Summary: The PostgreSQL `round()` function rounds a numeric value to a specified number of decimal places or to the nearest integer using the half-round-up (round-half-away-from-zero) tie-breaking rule. Use it for financial calculations, percentage display, and any query where you need to reduce decimal precision without truncating. For bias-free rounding in accounting contexts, the page explains why `round()` differs from banker's rounding and covers alternatives `ceil()`, `floor()`, and `trunc()`.

# Postgres round() function

Round numbers to a specified precision

Last updated: 2026-06-05

The Postgres `round()` function rounds numeric values to a specified number of decimal places or the nearest integer.

It can help maintain consistency in numerical data, simplify complex decimal numbers, and adjust the precision of calculations to meet specific requirements. Use it in financial calculations, data analysis, and anywhere you need to present numerical data in a more readable format.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `round()` function has a simple form:

```sql
round(number [, decimal_places]) -> number
```

- `number`: The input value to be rounded. It can be of any numeric data type — integer, floating-point, or decimal.
- `decimal_places`: An optional integer that specifies the number of decimal places to round to. If omitted, the input number is rounded to the nearest integer.

## Example usage

Let's consider a table `product_sales` that tracks sales data for various products. We'll use the `round()` function to adjust the precision of our sales figures.

```sql
WITH product_sales(product_id, sales_amount) AS (
  VALUES
    (1, 1234.5678),
    (2, 2345.6789),
    (3, 3456.7890),
    (4, 4567.8901)
)
SELECT
  product_id,
  sales_amount,
  round(sales_amount) AS rounded_to_integer,
  round(sales_amount, 2) AS rounded_to_cents
FROM product_sales;
```

This query demonstrates using the `round()` function to round sales amounts to the nearest integer and to two decimal places (cents).

```text
 product_id | sales_amount | rounded_to_integer | rounded_to_cents
------------+--------------+--------------------+------------------
          1 |    1234.5678 |               1235 |          1234.57
          2 |    2345.6789 |               2346 |          2345.68
          3 |    3456.7890 |               3457 |          3456.79
          4 |    4567.8901 |               4568 |          4567.89
(4 rows)
```

## Other examples

### Using round() to calculate accurate percentages

The `round()` function is often used when calculating and displaying percentages. For example, consider a table with sales data for different products. Let's calculate the percentage of total sales contributed by each product.

```sql
WITH product_sales(product_id, sales_amount) AS (
  VALUES
    (1, 1234.56),
    (2, 2345.67),
    (3, 3456.78),
    (4, 4567.89)
)
SELECT
  product_id,
  sales_amount,
  round(
    (sales_amount / SUM(sales_amount) OVER ()) * 100,
    2
  ) AS percentage_of_total
FROM product_sales
ORDER BY percentage_of_total DESC;
```

This query calculates each product's contribution to total sales and rounds the percentage to two decimal places. This avoids displaying overly precise percentages that can be misleading.

```text
 product_id | sales_amount | percentage_of_total
------------+--------------+---------------------
          4 |      4567.89 |               39.36
          3 |      3456.78 |               29.79
          2 |      2345.67 |               20.21
          1 |      1234.56 |               10.64
(4 rows)
```

### Combining round() with other functions

We can combine `round()` with other functions for more complex calculations. For example, let's calculate the average order value and round it to the nearest dollar and the nearest cents:

```sql
WITH orders(order_id, total_amount) AS (
  VALUES
    (1, 123.45),
    (2, 234.56),
    (3, 345.67),
    (4, 456.78),
    (5, 567.89)
)
SELECT
  round(AVG(total_amount)) AS avg_order_value_rounded,
  round(AVG(total_amount), 2) AS avg_order_value_cents
FROM orders;
```

```text
 avg_order_value_rounded | avg_order_value_cents
-------------------------+-----------------------
                     346 |                345.67
```

## Additional considerations

### Rounding behavior

Postgres `round()` function uses the half-round-up method for tie-breaking. This means that when the input is exactly halfway between two numbers, it rounds up to the higher number. For example:

```sql
SELECT round(2.65, 1), round(2.75, 1);
```

This query rounds both 2.65 and 2.75 to the next higher number with one decimal place:

```text
 round | round
-------+-------
   2.7 |   2.8
(1 row)
```

Financial calculations often require banker's rounding (also known as round-to-even) to minimize bias. If you need this behavior, you can implement it using a custom function or by combining `round()` with other functions.

### Performance implications

The `round()` function is generally fast, but frequent use in large datasets might impact performance. If you need to round values frequently in queries, consider storing pre-rounded values in a separate column and creating a function index on it.

### Alternative functions

- `ceil()` and `floor()`: These functions round up or down to the nearest integer, respectively.
- `trunc()`: This function truncates a number to a specified number of decimal places without rounding.

## Resources

- [PostgreSQL documentation: Mathematical Functions and Operators](https://www.postgresql.org/docs/current/functions-math.html)
- [PostgreSQL documentation: Numeric Types](https://www.postgresql.org/docs/current/datatype-numeric.html)

--- [Document source](https://neon.com/docs/functions/max.md) ---

> Summary: The Postgres `max()` aggregate function returns the largest value from a column or expression across a set of rows, working with numeric, date, and timestamp types while ignoring NULL values. Use `max()` when you need the highest price, latest timestamp, or biggest transaction in a table, including grouped results with GROUP BY or conditional results with a FILTER clause. The function also operates as a window function for running maximums, and performance improves when the target column is indexed.

# Postgres max() function

Find the maximum value in a set of values

Last updated: 2026-06-05

You can use the Postgres `max()` function to find the maximum value in a set of values.

Use it for data analysis, reporting, and finding extreme values within datasets. You might use `max()` to find the product with the highest price in the catalog, the most recent timestamp in a log table, or the largest transaction amount in a financial system.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `max()` function has this simple form:

```sql
max(expression) -> same as expression
```

- `expression`: Any valid expression that can be evaluated across a set of rows. This can be a column name or a function that returns a value.

## Example usage

Consider an `orders` table that tracks orders placed by customers of an online store. It has columns `order_id`, `customer_id`, `product_id`, and `order_date`. We will use this table for examples throughout this guide.

```sql
CREATE TABLE orders (
    order_id SERIAL PRIMARY KEY,
    customer_id INTEGER NOT NULL,
    product_id INTEGER,
    order_amount DECIMAL(10, 2) NOT NULL,
    order_date TIMESTAMP NOT NULL
);

INSERT INTO orders (customer_id, product_id, order_amount, order_date)
VALUES
    (1, 101, 150.00, '2023-01-15 10:30:00'),
    (2, 102, 75.50, '2023-01-16 11:45:00'),
    (1, 103, 200.00, '2023-02-01 09:15:00'),
    (3, 104, 50.25, '2023-02-10 14:20:00'),
    (2, 105, 125.75, '2023-03-05 16:30:00'),
    (4, NULL, 90.00, '2023-03-10 13:00:00'),
    (1, 106, 180.50, '2023-04-02 11:10:00'),
    (3, 107, 60.25, '2023-04-15 10:45:00'),
    (5, 108, 110.00, '2023-05-01 15:20:00'),
    (2, 109, 95.75, '2023-05-20 12:30:00');
```

We can use `max()` to find the largest order amount:

```sql
SELECT max(order_amount) AS largest_order
FROM orders;
```

This query returns the following output:

```text
 largest_order
---------------
        200.00
(1 row)
```

To find the most recent order date, we compute the maximum value of `order_date`:

```sql
SELECT max(order_date) AS latest_order_date
FROM orders;
```

This query returns the following output:

```text
  latest_order_date
---------------------
 2023-05-20 12:30:00
(1 row)
```

## Advanced examples

### Using max() with GROUP BY

You can use `max()` with `GROUP BY` to find the maximum values in each group:

```sql
SELECT customer_id, max(order_amount) AS largest_order
FROM orders
GROUP BY customer_id
ORDER BY largest_order DESC
LIMIT 5;
```

This query finds the largest order amount for each customer and returns the top 5 customers, sorted in order of the largest order amount.

```text
 customer_id | largest_order
-------------+---------------
           1 |        200.00
           2 |        125.75
           5 |        110.00
           4 |         90.00
           3 |         60.25
(5 rows)
```

### Using max() with a FILTER clause

The `FILTER` clause allows you to selectively include rows in the `max()` calculation:

```sql
SELECT
    max(order_amount) AS max_overall,
    max(order_amount) FILTER (WHERE EXTRACT(MONTH FROM order_date) = 4) AS max_in_april
FROM orders;
```

This query calculates both the overall maximum order amount and the maximum order amount for the year 2023.

```text
 max_overall | max_in_april
-------------+--------------
      200.00 |       180.50
(1 row)
```

### Finding the row with the maximum value for a column

To retrieve the entire row containing the maximum value, you can use a subquery:

```sql
SELECT *
FROM orders
WHERE order_amount = (SELECT max(order_amount) FROM orders);
```

This query returns the full details of the order with the maximum `order_amount`.

```text
 order_id | customer_id | product_id | order_amount |     order_date
----------+-------------+------------+--------------+---------------------
        3 |           1 |        103 |       200.00 | 2023-02-01 09:15:00
(1 row)
```

### Using max() with window functions

`max()` can be used as a window function to calculate the running maximum over a set of rows:

```sql
SELECT
    order_id,
    order_date,
    max(order_amount) OVER (
        ORDER BY order_date
        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
    ) AS running_max_amount
FROM orders
ORDER BY order_date;
```

This query calculates the running maximum order amount over time, showing how the largest order amount changes as new orders come in.

```text
 order_id |     order_date      | running_max_amount
----------+---------------------+--------------------
        1 | 2023-01-15 10:30:00 |             150.00
        2 | 2023-01-16 11:45:00 |             150.00
        3 | 2023-02-01 09:15:00 |             200.00
        4 | 2023-02-10 14:20:00 |             200.00
        5 | 2023-03-05 16:30:00 |             200.00
        6 | 2023-03-10 13:00:00 |             200.00
        7 | 2023-04-02 11:10:00 |             200.00
        8 | 2023-04-15 10:45:00 |             200.00
        9 | 2023-05-01 15:20:00 |             200.00
       10 | 2023-05-20 12:30:00 |             200.00
(10 rows)
```

## Additional considerations

### NULL values

`max()` ignores NULL values in its calculations. If all values in the set are NULL, `max()` returns NULL.

### Performance implications

When used with an index on the column being evaluated, `max()` is typically very efficient. The database can often use an index scan to quickly find the maximum value without needing to examine every row in the table. For large datasets, ensure that the column used in the `max()` function is properly indexed to maintain good performance.

### Alternative functions

- `min()`: Returns the minimum value in a set of values.
- `greatest()`: Returns the largest value from a list of values/expressions within a single row.

## Resources

- [PostgreSQL documentation: Aggregate Functions](https://www.postgresql.org/docs/current/functions-aggregate.html)

--- [Document source](https://neon.com/docs/functions/now.md) ---

> Summary: The Postgres `now()` function returns the current date and time as a `timestamp with time zone`, fixed at the start of the current transaction, making it an alias for `current_timestamp` and `transaction_timestamp()`. Use `now()` to auto-populate `created_at` or `last_updated` columns via DEFAULT constraints or triggers when a stable, transaction-scoped timestamp is needed. Unlike the bare `now` keyword (evaluated once at table creation) or `clock_timestamp()` (updates within a statement), `now()` re-evaluates on every row insert.

# Postgres now() function

Get the current date and time

Last updated: 2026-06-05

The Postgres `now()` function returns the current date and time with timezone. It's an alias for the `current_timestamp()` function.

This function is commonly used for timestamping database entries, calculating time differences, or implementing time-based logic in applications. For instance, you might use it to record when a user creates an account, when an order is placed, or to calculate intervals - like how long ago an event occurred.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `now()` function has a single form:

```sql
now() -> timestamp with timezone
```

This form returns the current timestamp with the timezone at the start of the current transaction.

## Example usage

Let's consider a `user_accounts` table that tracks user registration information. We can use `now()` to record the exact time a user creates their account.

```sql
CREATE TABLE user_accounts (
  user_id SERIAL PRIMARY KEY,
  username VARCHAR(50) UNIQUE NOT NULL,
  email VARCHAR(100) UNIQUE NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT now()
);

INSERT INTO user_accounts (username, email)
VALUES ('john_doe', 'john@example.com');
```

This query creates a table to store user account information, with the `created_at` column automatically set to the current timestamp when a new record is inserted.

Let's insert another record and retrieve all user accounts:

```sql
INSERT INTO user_accounts (username, email)
VALUES ('jane_smith', 'jane@example.com');

SELECT * FROM user_accounts;
```

This query returns the following output:

```text
 user_id |  username  |      email       |          created_at
---------+------------+------------------+-------------------------------
       1 | john_doe   | john@example.com | 2024-06-25 08:40:25.603165+00
       2 | jane_smith | jane@example.com | 2024-06-25 08:40:38.220631+00
(2 rows)
```

## Advanced examples

### Use `now()` to calculate time differences

We can use `now()` in combination with stored timestamps to calculate time differences. For example, let's create a table to track project deadlines and calculate how much time is left:

```sql
CREATE TABLE projects (
  project_id SERIAL PRIMARY KEY,
  project_name VARCHAR(100) NOT NULL,
  start_date TIMESTAMP WITH TIME ZONE DEFAULT now(),
  deadline TIMESTAMP WITH TIME ZONE NOT NULL
);

INSERT INTO projects (project_name, deadline)
VALUES
  ('Website Redesign', now() + INTERVAL '30 days'),
  ('Mobile App Development', now() + INTERVAL '60 days'),
  ('Database Migration', now() + INTERVAL '15 days');

SELECT
  project_name,
  deadline - now() AS time_remaining
FROM projects
ORDER BY time_remaining;
```

This query calculates and displays the remaining time for each project, ordered from the most to the least urgent.

```text
      project_name      |     time_remaining
------------------------+------------------------
 Database Migration     | 14 days 23:59:59.93332
 Website Redesign       | 29 days 23:59:59.93332
 Mobile App Development | 59 days 23:59:59.93332
(3 rows)
```

### Use `now()` with triggers

We can use `now()` in combination with an update trigger to automatically maintain modification timestamps for records.

Here's an example using a table for tracking customer orders. It has columns for both the creation and last update timestamps, with a trigger that updates the `last_updated` column whenever an order is modified:

```sql
CREATE TABLE customer_orders (
  order_id SERIAL PRIMARY KEY,
  customer_id INTEGER NOT NULL,
  order_status VARCHAR(20) NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT now(),
  last_updated TIMESTAMP WITH TIME ZONE DEFAULT now()
);

CREATE OR REPLACE FUNCTION update_last_updated_column()
RETURNS TRIGGER AS $$
BEGIN
    NEW.last_updated = now();
    RETURN NEW;
END;
$$ language 'plpgsql';

CREATE TRIGGER update_customer_order_timestamp
BEFORE UPDATE ON customer_orders
FOR EACH ROW
EXECUTE FUNCTION update_last_updated_column();

INSERT INTO customer_orders (customer_id, order_status)
VALUES (1001, 'Pending'), (1002, 'Processing');
```

Now, let's update an order and observe the changes:

```sql
-- Simulate some delay before update
SELECT pg_sleep(2);
UPDATE customer_orders SET order_status = 'Shipped' WHERE order_id = 1;

SELECT * FROM customer_orders;
```

This query returns the following output, showing the updated status and the new `last_updated` timestamp, for the modified order.

```text
 order_id | customer_id | order_status |          created_at          |         last_updated
----------+-------------+--------------+------------------------------+-------------------------------
        2 |        1002 | Processing   | 2024-06-25 09:26:43.57742+00 | 2024-06-25 09:26:43.57742+00
        1 |        1001 | Shipped      | 2024-06-25 09:26:43.57742+00 | 2024-06-25 09:26:50.962194+00
(2 rows)
```

### Use `now()` in a function for date/time calculations

We can wrap `now()` in a user-defined function to perform more complex date/time calculations. For example, here's a function that calculates the current age of a user.

```sql
CREATE OR REPLACE FUNCTION calculate_age(birth_date DATE)
RETURNS INTEGER AS $$
BEGIN
    RETURN DATE_PART('year', AGE(now(), birth_date));
END;
$$ LANGUAGE plpgsql;

SELECT
  calculate_age('1990-05-15') AS age_1,
  calculate_age('2000-12-31') AS age_2,
  calculate_age('1985-03-20') AS age_3;
```

This query calculates the age of three users based on their date of birth:

```text
 age_1 | age_2 | age_3
-------+-------+-------
    34 |    23 |    39
(1 row)
```

## Additional considerations

### Time zone awareness

Like `current_timestamp`, `now()` returns a value in the timezone of the current session. This defaults to the server's timezone unless explicitly set in the session. It's important to keep this in mind when working with timestamps across different timezones.

### Difference between `now()` and the keyword `now`

The `now()` function is a built-in function that returns the current timestamp with the timezone. In contrast, the keyword `now` (without parentheses) is a reserved word that is converted to the current timestamp value when first parsed.

It is recommended to use `now()` for clarity and consistency. For example, if the default value for a column is set to `now`, it will be evaluated once when the table is created and reused for all successive records. Whereas, `now()` will be evaluated each time a new row is inserted, which is the typically desired behavior.

### Alternative functions

- `current_timestamp()` - Functionally identical to `now()`.
- `transaction_timestamp()` - Returns the current timestamp at the start of the current transaction, also equivalent to `now()`.
- `statement_timestamp()` - Returns the current timestamp at the start of the current statement.
- `clock_timestamp()` - Returns the actual current timestamp with timezone, which can change even during a single SQL statement.

## Resources

- [PostgreSQL documentation: Date/Time Functions and Operators](https://www.postgresql.org/docs/current/functions-datetime.html)
- [PostgreSQL documentation: Date/Time Types](https://www.postgresql.org/docs/current/datatype-datetime.html)

--- [Document source](https://neon.com/docs/functions/regexp_match.md) ---

> Summary: The Postgres `regexp_match()` function returns a `text[]` array of substrings from the first POSIX regular expression match in an input string, capturing each named or unnamed group as a separate array element. Use it when `LIKE` and `SIMILAR TO` are too limited and you need to extract structured fields from semi-structured text such as log entries, URLs, or user agent strings. The function returns NULL on no match, accepts an optional flags argument (e.g., `i` for case-insensitive), and differs from `regexp_matches()` which returns all matches, and `regexp_replace()` which substitutes matches.

# Postgres regexp_match() function

Extract substrings matching a regular expression pattern

Last updated: 2026-06-05

The Postgres `regexp_match()` function is used to extract substrings that match a regular expression pattern from a given string. It returns an array of matching substrings, including capture groups if specified in the pattern.

Use it for complex string parsing tasks, such as extracting structured information from semi-structured text data. For example, it can be used to parse log files, extract specific components from URLs, or analyze text data for specific patterns.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `regexp_match()` function has the following form:

```sql
regexp_match(string text, pattern text [, flags text]) -> text[]
```

- `string`: The input string to search for matches.
- `pattern`: A POSIX regular expression pattern to match against the string.
- `flags` (optional): A string of one or more single-letter flags that modify how the regular expression is interpreted.

The function returns an array of text values, where each element corresponds to a substring within the first match of the pattern in the input string. If there are no matches, the function returns NULL. If there are no capture groups in the pattern, the array contains a single element with the full match.

## Example usage

Consider a table `log_entries` with a `log_text` column containing log messages. We can use `regexp_match()` to extract specific information from these logs.

```sql
WITH log_entries AS (
  SELECT '[2024-03-04 10:15:30] INFO: User john_doe logged in from 192.168.1.100' AS log_text
  UNION ALL
  SELECT '[2024-03-04 10:20:45] ERROR: Failed login attempt for user jane_smith from 10.0.0.50' AS log_text
  UNION ALL
  SELECT '[2024-03-04 10:25:55] INFO: User admin logged out' AS log_text
)
SELECT
  regexp_match(log_text, '\[(.*?)\] (\w+): (.*)$') AS parsed_log
FROM log_entries;
```

This query extracts the timestamp, log level, and message from each log entry. The regular expression pattern `\[(.*?)\] (\w+): (.*)$` captures three groups:

1. The timestamp between square brackets
2. The log level (INFO, ERROR, etc.), which is alphabetical and terminated with a colon
3. The rest of the message

```text
                                       parsed_log
-----------------------------------------------------------------------------------------
 {"2024-03-04 10:15:30",INFO,"User john_doe logged in from 192.168.1.100"}
 {"2024-03-04 10:20:45",ERROR,"Failed login attempt for user jane_smith from 10.0.0.50"}
 {"2024-03-04 10:25:55",INFO,"User admin logged out"}
(3 rows)
```

## Advanced examples

### Use `regexp_match()` with regex flags

The `regexp_match()` function accepts optional flags to modify how the regular expression is interpreted. Here's an example using the 'i' flag for case-insensitive matching:

```sql
WITH user_agents AS (
  SELECT 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36' AS user_agent
  UNION ALL
  SELECT 'Mozilla/5.0 (iPhone; CPU iPhone OS 14_6 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.1 Mobile/15E148 Safari/604.1' AS user_agent
  UNION ALL
  SELECT 'CHROME/91.0.4472.124' AS user_agent
)
SELECT
  regexp_match(user_agent, '(chrome|safari|firefox|msie|opera)\/[\d\.]+', 'i') AS browser
FROM user_agents;
```

This query extracts the browser name and version from user agent strings, using case-insensitive matching.

```text
 browser
----------
 {Chrome}
 {Safari}
 {CHROME}
(3 rows)
```

### Use `regexp_match()` in a WHERE clause

You can use `regexp_match()` in a WHERE clause to filter rows based on a regex pattern:

```sql
WITH emails AS (
  SELECT 'john.doe@example.com' AS email
  UNION ALL
  SELECT 'jane.smith@company.co.uk' AS email
  UNION ALL
  SELECT 'support@mydomain.io' AS email
)
SELECT *
FROM emails
WHERE regexp_match(email, '^[^@]+@[^@]+\.(com|org|io)$') IS NOT NULL;
```

This query selects all rows from the `emails` table where the email address ends with `.com`, `.org`, or `.io`.

```text
        email
----------------------
 john.doe@example.com
 support@mydomain.io
(2 rows)
```

## Additional considerations

### Performance implications

Using `regexp_match()` can be computationally expensive, especially on large datasets or with complex patterns. For better performance:

1. Use simpler patterns when possible.
2. Consider using `LIKE` or `SIMILAR TO` for simple pattern matching.
3. If you frequently filter based on regex patterns, consider creating a functional index using the `regexp_match()` expression.

### NULL handling

`regexp_match()` returns NULL if there's no match or if the input string is NULL. This behavior can be useful in `WHERE` clauses but may require careful handling in `SELECT` lists.

### Alternative functions

- `regexp_matches()`: Returns a set of all matches, useful for extracting multiple occurrences of the pattern in the input string.
- `regexp_replace()`: Replaces substrings matching a regex pattern within a specified string.
- `regexp_split_to_array()`: Splits a string using a regex pattern as the delimiter and returns the result as an array.
- `substring()`: Extracts substrings based on a regex pattern similar to `regexp_match()`, but only returns the first captured group of the match.

## Resources

- [PostgreSQL documentation: Pattern Matching](https://www.postgresql.org/docs/current/functions-matching.html)
- [PostgreSQL documentation: Regular Expression Details](https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-POSIX-REGEXP)
- [Regular Expression Tester](https://regex101.com/): A useful tool for testing and debugging regular expressions

--- [Document source](https://neon.com/docs/functions/regexp_replace.md) ---

> Summary: The Postgres `regexp_replace()` function replaces substrings matching a regular expression pattern, with support for backreferences and flags such as `g` (global) and `i` (case-insensitive). Use it instead of `replace()` when you need pattern-based substitutions for tasks like stripping HTML tags, standardizing phone numbers, or anonymizing sensitive data. An extended form accepts `start` and `N` integer parameters to control the search position and which occurrence to replace.

# Postgres regexp_replace() function

Replace substrings matching a regular expression pattern

Last updated: 2026-06-05

The Postgres `regexp_replace()` function replaces substrings that match a regular expression pattern with the specified replacement string.

Use it for complex string manipulations and data cleaning/formatting tasks. Consider scenarios where you'd want to remove or replace specific patterns in text or transform data to meet certain requirements. For instance, you might use it to format phone numbers consistently, remove HTML tags from text, or anonymize sensitive information in logs.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `regexp_replace()` function has the following syntax:

```sql
regexp_replace(source text, pattern text, replacement text [, flags text]) -> text
```

- `source`: The input string to perform replacements on.
- `pattern`: The regular expression pattern to match.
- `replacement`: The string to replace matched substrings with.
- `flags` (optional): A string of one or more single-letter flags that modify how the regex is interpreted.

It returns the input string with occurrence(s) of the pattern replaced by the replacement string.

More recent versions of Postgres (starting with Postgres 16) also support additional parameters to further control the replacement operation:

```sql
regexp_replace(source text, pattern text, replacement text [, start int, [, N int]] [, flags text]) -> text
```

- start: The position in the source string to start searching for matches (default is 1).
- N: If specified, only the Nth occurrence of the pattern is replaced. If N is 0, or the `g` flag is used, all occurrences are replaced.

## Example usage

Consider a `customer_data` table with a `phone_number` column containing phone numbers in different formats. We can use `regexp_replace()` to standardize these numbers to a consistent format.

```sql
WITH customer_data AS (
  SELECT '(555) 123-4567' AS phone_number
  UNION ALL
  SELECT '555.987.6543' AS phone_number
  UNION ALL
  SELECT '555-321-7890' AS phone_number
)
SELECT
  phone_number AS original_number,
  regexp_replace(phone_number, '[^\d]', '', 'g') AS cleaned_number
FROM customer_data;
```

This query removes all non-digit characters from the phone numbers, standardizing them to a simple string of digits.

```text
 original_number | cleaned_number
-----------------+----------------
 (555) 123-4567  | 5551234567
 555.987.6543    | 5559876543
 555-321-7890    | 5553217890
(3 rows)
```

## Advanced examples

### Use `regexp_replace()` with backreferences

You can use backreferences in the replacement string to include parts of the matched pattern in the replacement.

```sql
WITH log_data AS (
  SELECT '2023-05-15 10:30:00 - User john.doe@example.com logged in' AS log_entry
  UNION ALL
  SELECT '2023-05-15 11:45:30 - User jane.smith@example.org logged out' AS log_entry
)
SELECT
  log_entry AS original_log,
  regexp_replace(log_entry, '(.*) - User (.+@.+) (.+)$', '\1 - User [REDACTED] \3') AS anonymized_log
FROM log_data;
```

This query anonymizes email addresses in log entries by replacing them with [REDACTED] while preserving the rest of the log structure.

```text
                         original_log                         |              anonymized_log
--------------------------------------------------------------+-------------------------------------------
 2023-05-15 10:30:00 - User john.doe@example.com logged in    | 2023-05-15 10:30:00 - User [REDACTED] in
 2023-05-15 11:45:30 - User jane.smith@example.org logged out | 2023-05-15 11:45:30 - User [REDACTED] out
(2 rows)
```

### Modify the behavior of `regexp_replace()` using flags

The `flags` parameter allows you to modify how the function operates. Common flags include:

- `g`: Global replacement (replace all occurrences)
- `i`: Case-insensitive matching
- `n`: Newline-sensitive matching

```sql
WITH product_descriptions AS (
  SELECT 'Red Apple: sweet and crisp' AS description
  UNION ALL
  SELECT 'Green Apple: tart and juicy apple' AS description
  UNION ALL
  SELECT 'Yellow Apple: mild and sweet' AS description
)
SELECT
  description AS original_description,
  regexp_replace(description, 'apple', 'pear', 'gi') AS modified_description
FROM product_descriptions;
```

This query replaces all occurrences of "apple" (case-insensitive) with "pear" in the product descriptions.

```text
       original_description        |      modified_description
-----------------------------------+---------------------------------
 Red Apple: sweet and crisp        | Red pear: sweet and crisp
 Green Apple: tart and juicy apple | Green pear: tart and juicy pear
 Yellow Apple: mild and sweet      | Yellow pear: mild and sweet
(3 rows)
```

### Use `regexp_replace()` for complex pattern matching and replacement

`regexp_replace()` can handle complex patterns for sophisticated text processing tasks. For example, the query below removes all HTML tags from the given markup, producing plain text.

```sql
WITH html_content AS (
  SELECT '<p>This is <b>bold</b> and <i>italic</i> text.</p>' AS content
  UNION ALL
  SELECT '<div>Another <span style="color: red;">example</span> here.</div>' AS content
)
SELECT
  content AS original_html,
  regexp_replace(content, '<[^>]+>', '', 'g') AS plain_text
FROM html_content;
```

This query produces the following output:

```text
                           original_html                           |          plain_text
-------------------------------------------------------------------+-------------------------------
 <p>This is <b>bold</b> and <i>italic</i> text.</p>                | This is bold and italic text.
 <div>Another <span style="color: red;">example</span> here.</div> | Another example here.
(2 rows)
```

## Additional considerations

### Performance implications

While `regexp_replace()` is powerful, complex regular expressions or operations on large text fields can be computationally expensive. For frequently used operations, consider preprocessing the data or using simpler string functions if possible.

### Alternative functions

- `replace()`: A simpler function for straightforward string replacements without regular expressions.
- `translate()`: Useful for character-by-character replacements.
- `regexp_matches()`: Returns an array of all substrings matching a regular expression pattern, which can be useful in conjunction with other functions for complex transformations.

## Resources

- [PostgreSQL documentation: String functions](https://www.postgresql.org/docs/current/functions-string.html)
- [PostgreSQL documentation: Pattern matching](https://www.postgresql.org/docs/current/functions-matching.html)
- [PostgreSQL documentation: Regular expressions](https://www.postgresql.org/docs/current/functions-matching.html#FUNCTIONS-POSIX-REGEXP)

--- [Document source](https://neon.com/docs/functions/substring.md) ---

> Summary: The PostgreSQL `substring()` function extracts part of a string by position and length or by a POSIX regex pattern with optional capture groups. Use it to pull fixed-length fields, zip codes, timestamps, or structured tokens from raw text without splitting on a delimiter. When filtering rows on a substring expression, add a functional index to avoid full column scans; alternatives include `left`, `right`, `split_part`, and `regexp_match`.

# Postgres substring() function

Extract a substring from a string

Last updated: 2026-06-05

The `substring()` function in Postgres is used to extract a portion of a string based on specified start and end positions, or a regular expression pattern.

It's useful for data cleaning and transformation where you might need to extract relevant parts of a string. For example, when working with semi-structured data like an address, where you want to extract the zip code. Or, to extract the timestamp of events when working with machine-generated data like logs.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `substring()` function has two forms:

```sql
substring(string text [from int] [for int]) -> text
```

- `string`: The input string to extract the substring from.
- `from` (optional): The starting position for the substring (1-based index). If omitted, it defaults to 1.
- `for` (optional): The length of the substring to extract. If omitted, the substring extends to the end of the string.

```sql
substring(string text from pattern text) -> text
```

- `string`: The input string to extract the substring from.
- `pattern`: A POSIX regular expression pattern. The substring matching this pattern is returned.

## Example usage

Consider a table `users` with a `user_id` column that contains IDs in the format "user_123". We can use `substring()` to extract just the numeric part of the ID.

```sql
WITH users AS (
  SELECT 'user_123' AS user_id
  UNION ALL
  SELECT 'user_482892' AS user_id
)
SELECT substring(user_id from 6) AS numeric_id
FROM users;
```

This query extracts the substring starting from the 6th character of `user_id` (1-based index) and returns it as `numeric_id`.

```text
 numeric_id
------------
 123
 482892
(2 rows)
```

You can also use a regular expression pattern to find and extract a substring.

```sql
WITH addresses AS (
  SELECT '123 Main St, Anytown, CA 12345, (555) 123-4567' AS address
  UNION ALL
  SELECT '456 Oak Ave, Somewhere, NY 54321, (555) 987-6543' AS address
)
SELECT substring(address from '\d{5}') AS zip_code
FROM addresses;
```

This query extracts the 5-digit zip code from the `address` column using the regular expression pattern `\d{5}`, which matches exactly 5 consecutive digits.

```text
 zip_code
----------
 12345
 54321
(2 rows)
```

## Advanced examples

### Extract a substring of a specific length

You can specify both the starting position and the length of the substring to extract.

```sql
WITH logs AS (
  SELECT '2023-05-15T10:30:00.000Z - User 123 logged in' AS log_entry
  UNION ALL
  SELECT '2023-05-15T11:45:30.000Z - User 456 logged out' AS log_entry
)
SELECT substring(log_entry from 1 for 23) AS timestamp
FROM logs;
```

This query extracts the timestamp portion from the `log_entry` column. It assumes that the timestamp always appears at the beginning of the log entry and has a fixed length of 23 characters

```text
        timestamp
-------------------------
 2023-05-15T10:30:00.000
 2023-05-15T11:45:30.000
(2 rows)
```

### Extract a substring matching a regex pattern with capture groups

The `substring()` function extracts the first part of the string that matches the regular expression pattern. However, if the pattern contains capture groups (specified using parentheses), it returns the substring matched by the first parenthesized subexpression.

```sql
WITH orders AS (
  SELECT 'Order #1234 - $150.00' AS order_info
  UNION ALL
  SELECT 'Order #5678 - $75.50' AS order_info
  UNION ALL
  SELECT 'Order #9012 - $200.00' AS order_info
)
SELECT
  substring(order_info from 'Order #(\d+)') AS order_number,
  substring(order_info from '\$(\d+\.\d+)') AS order_amount
FROM orders;
```

This query extracts the order number and order amount from the `order_info` column using regular expressions with capture groups.

- The pattern `Order #(\d+)` matches the string "Order #" followed by one or more digits. The parentheses around `\d+` create a capture group that extracts just the order number.
- The pattern `\$(\d+\.\d+)` matches a dollar sign followed by a decimal number. The parentheses around `\d+\.\d+` create a capture group that extracts just the order amount.

```text
 order_number | order_amount
--------------+--------------
 1234         | 150.00
 5678         | 75.50
 9012         | 200.00
(3 rows)
```

### Use `substring()` in a `WHERE` clause

You can use `substring()` in a `WHERE` clause to filter rows based on a substring condition.

```sql
WITH users AS (
  SELECT 'john.doe@example.com' AS email
  UNION ALL
  SELECT 'jane.smith@example.org' AS email
  UNION ALL
  SELECT 'admin@gmail.com' AS email
)
SELECT *
FROM users
WHERE substring(email from '.*@(.*)\.') = 'example';
```

This query selects all rows from the `users` table where the email address has the domain name `example`. The regular expression pattern `.*@(.*)\.` extracts the domain part of the email address.

```text
         email
------------------------
 john.doe@example.com
 jane.smith@example.org
(2 rows)
```

## Additional considerations

### Performance implications

When working with large datasets, using `substring()` in a `WHERE` clause may impact query performance since it requires scanning the entire string column to extract substrings and compare them.

If you frequently filter based on substrings, consider creating a _functional index_ on the relevant column using the substring expression, to improve query performance.

### Alternative functions

- `left` - Extracts the specified number of characters from the start of a string.
- `right` - Extracts the specified number of characters from the end of a string.
- `split_part` - Splits a string on the specified delimiter and returns the nth substring.
- `regexp_match` - Extracts the first substring matching a regular expression pattern. Unlike `substring()`, it returns an array of all the captured substrings when the regex pattern contains multiple parentheses.

## Resources

- [PostgreSQL documentation: String functions](https://www.postgresql.org/docs/current/functions-string.html)
- [PostgreSQL documentation: Pattern matching](https://www.postgresql.org/docs/current/functions-matching.html)

--- [Document source](https://neon.com/docs/functions/sum.md) ---

> Summary: The PostgreSQL `sum()` aggregate function totals numeric column values and promotes output types to prevent overflow (smallint and integer inputs return bigint; bigint and numeric inputs return numeric). Use it to compute revenue totals, quantity sums, or running totals with `GROUP BY`, `FILTER`, or `OVER` window clauses. NULL values are silently skipped, and `sum()` returns NULL rather than zero when no rows match the query.

# Postgres sum() function

Calculate the sum of a set of values

Last updated: 2026-06-05

The Postgres `sum()` function calculates the total of a set of numeric values.

It's used in data analysis and reporting to compute totals across rows in a table or grouped data. Use it in financial applications for revenue and expense totals, in inventory management for quantity sums, or in analytics for aggregating metrics.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `sum()` function has this simple form:

```sql
sum([DISTINCT] expression) -> numeric type
```

- `expression`: Any numeric expression or column name. The function returns a value of the same data type as the input.
- `DISTINCT`: Optional keyword that causes `sum()` to consider only unique values in the calculation.

The output of the `sum()` function has the same data type as the input if it's a floating-point (real / double-precision) type. To avoid overflow, the output for smallint/integer inputs is a bigint, and for bigint/numeric inputs, it is numeric type.

## Example usage

Consider a `sales` table that tracks product sales, with columns `product_id`, `quantity`, and `price`. We can use `sum()` to calculate the total revenue from each product.

```sql
WITH sales(product_id, quantity, price) AS (
  VALUES
    (1, 10, 100.0),
    (2, 5, 50.0),
    (1, 5, 100.0),
    (3, 3, 75.0),
    (2, 2, 50.0)
)
SELECT sum(quantity * price) AS total_revenue
FROM sales;
```

This query calculates the total revenue by multiplying the quantity and price for each sale.

```text
 total_revenue
---------------
        2075.0
(1 row)
```

## Advanced examples

### Sum with grouping

You can use `sum()` with `GROUP BY` to calculate subtotals for different categories:

```sql
WITH employee_sales AS (
  SELECT 'Alice' AS employee, 'Electronics' AS department, 5000 AS sales
  UNION ALL
  SELECT 'Bob' AS employee, 'Electronics' AS department, 6000 AS sales
  UNION ALL
  SELECT 'Charlie' AS employee, 'Clothing' AS department, 4500 AS sales
  UNION ALL
  SELECT 'David' AS employee, 'Clothing' AS department, 5500 AS sales
)
SELECT department, sum(sales) AS total_sales
FROM employee_sales
GROUP BY department;
```

This query calculates the total sales for each department.

```
 department  | total_sales
-------------+-------------
 Clothing    |       10000
 Electronics |       11000
(2 rows)
```

### Sum with FILTER clause

You can use the `FILTER` clause to conditionally include values in the sum:

```sql
WITH orders AS (
  SELECT 1 AS order_id, 'completed' AS status, 100 AS total
  UNION ALL
  SELECT 2 AS order_id, 'pending' AS status, 150 AS total
  UNION ALL
  SELECT 3 AS order_id, 'completed' AS status, 200 AS total
  UNION ALL
  SELECT 4 AS order_id, 'cancelled' AS status, 75 AS total
)
SELECT
  sum(total) AS all_orders_total,
  sum(total) FILTER (WHERE status = 'completed') AS completed_orders_total
FROM orders;
```

This query calculates the sum of all order totals and the sum of only completed order totals.

```text
 all_orders_total | completed_orders_total
------------------+------------------------
              525 |                    300
(1 row)
```

### Sum over a window

You can use `sum()` as a window function to calculate running totals:

```sql
WITH monthly_sales AS (
  SELECT
    '2023-01-01'::date AS month,
    10000 AS sales
  UNION ALL
  SELECT '2023-02-01'::date, 12000
  UNION ALL
  SELECT '2023-03-01'::date, 15000
  UNION ALL
  SELECT '2023-04-01'::date, 11000
)
SELECT
  month,
  sales,
  sum(sales) OVER (ORDER BY month) AS running_total
FROM monthly_sales;
```

This query calculates a running total of sales over time.

```text
   month    | sales | running_total
------------+-------+---------------
 2023-01-01 | 10000 |         10000
 2023-02-01 | 12000 |         22000
 2023-03-01 | 15000 |         37000
 2023-04-01 | 11000 |         48000
(4 rows)
```

## Additional considerations

### Null values

The `sum()` function ignores NULL values in its calculations. If all values are NULL, `sum()` returns NULL. Additionally, if there are no rows to sum over, `sum()` returns NULL instead of 0 which might be unexpected.

### Overflow handling

When summing very large numbers, be aware of potential overflow issues. Consider using larger data types (for example, `bigint` instead of `integer`) or the `numeric` type for precise calculations with large numbers.

### Alternative functions

- `avg()`: Calculates the average of a set of values.
- `count()`: Counts the number of rows or non-null values.
- `max()` and `min()`: Find the maximum and minimum in a set of values.

## Resources

- [PostgreSQL documentation: Aggregate Functions](https://www.postgresql.org/docs/current/functions-aggregate.html)
- [PostgreSQL documentation: Window Functions](https://www.postgresql.org/docs/current/tutorial-window.html)

--- [Document source](https://neon.com/docs/functions/trim.md) ---

> Summary: The Postgres `trim()` function removes leading, trailing, or both-end characters from a string, defaulting to spaces when no character set is specified. Use it to clean user input, strip sentinel characters like `#` or `*`, or normalize strings before comparison, filtering, or joining. Related functions include `ltrim()`, `rtrim()`, and `btrim()`; applying `trim()` in a `WHERE` clause on large datasets may require a functional index to avoid performance degradation.

# Postgres trim() function

Remove leading and trailing characters from a string

Last updated: 2026-06-05

The Postgres `trim()` function removes the specified characters from the beginning and/or end of a string.

This function is commonly used in data preprocessing tasks, such as cleaning user input before storing it in a database or standardizing data for comparison or analysis. For example, you might use it to remove extra spaces from product names or to standardize phone numbers by removing surrounding parentheses.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `trim()` function has two forms:

```sql
trim([leading | trailing | both] [characters] from string) -> text
```

- `leading | trailing | both` (optional): Specifies which part of the string to trim. If omitted, it defaults to `both`.
- `characters` (optional): The set of characters to remove. If omitted, it defaults to spaces.
- `string`: The input string to trim.

```sql
trim(string text [, characters text]) -> text
```

- `string`: The input string to trim.
- `characters` (optional): The characters to remove from both ends. If omitted, it defaults to spaces.

## Example usage

Consider a table `products` with a `product_name` column that contains product names with inconsistent spacing. We can use `trim()` to standardize these names.

```sql
WITH products(product_name) AS (
  VALUES
    ('  Laptop  '),
    ('Smartphone '),
    (' Tablet'),
    ('  Wireless Earbuds  ')
)
SELECT trim(product_name) AS cleaned_name
FROM products;
```

This query removes leading and trailing spaces from the `product_name` column.

```text
   cleaned_name
------------------
 Laptop
 Smartphone
 Tablet
 Wireless Earbuds
(4 rows)
```

You can also use `trim()` to remove specific characters from both ends of a string.

```sql
WITH order_ids(id) AS (
  VALUES
    ('###ORDER-123###'),
    ('###ORDER-456###'),
    ('###ORDER-789###')
)
SELECT trim(id, '#') AS cleaned_id
FROM order_ids;
```

This query removes the '#' characters from both ends of the `id` column.

```text
 cleaned_id
------------
 ORDER-123
 ORDER-456
 ORDER-789
(3 rows)
```

## Advanced examples

### Trim only leading or trailing characters

You can specify whether to trim characters from the beginning, end, or both sides of a string.

```sql
WITH user_inputs(input) AS (
  VALUES
    ('***Secret Password***'),
    ('***Admin Access***'),
    ('***Guest User***')
)
SELECT
  trim(leading '*' from input) AS leading_trimmed,
  trim(trailing '*' from input) AS trailing_trimmed,
  trim(both '*' from input) AS both_trimmed
FROM user_inputs;
```

The query above demonstrates trimming asterisks from the beginning, end, and both sides of the `input` column, as shown in the following table.

```text
  leading_trimmed   |  trailing_trimmed  |  both_trimmed
--------------------+--------------------+-----------------
 Secret Password*** | ***Secret Password | Secret Password
 Admin Access***    | ***Admin Access    | Admin Access
 Guest User***      | ***Guest User      | Guest User
(3 rows)
```

### Use trim() in a WHERE clause

You can use `trim()` in a `WHERE` clause to filter rows based on matching a trimmed value.

```sql
WITH product_codes(code) AS (
  VALUES
    ('  ABC-123  '),
    ('DEF-456'),
    (' ABC-789 '),
    ('  JKL-101  '),
    ('MNO-202 ')
)
SELECT code AS original_code, trim(code) AS trimmed_code
FROM product_codes
WHERE trim(code) LIKE 'ABC%';
```

The query above filters for rows where the trimmed `code` column starts with 'ABC', as shown in the following table:

```text
 original_code | trimmed_code
---------------+--------------
   ABC-123     | ABC-123
  ABC-789      | ABC-789
(2 rows)
```

### Combine trim() with other string functions

You can combine `trim()` with other string functions for more complex string manipulations.

```sql
WITH user_emails(email) AS (
  VALUES
    ('  john.doe@example.com  '),
    (' jane.smith@example.org '),
    ('  admin@gmail.com  ')
)
SELECT
  trim(email) AS trimmed_email,
  upper(split_part(trim(email), '@', 1)) AS username
FROM user_emails;
```

The query above trims spaces from the email addresses and then extracts and uppercases the username part (before the '@' symbol).

```text
     trimmed_email      |  username
------------------------+------------
 john.doe@example.com   | JOHN.DOE
 jane.smith@example.org | JANE.SMITH
 admin@gmail.com        | ADMIN
(3 rows)
```

## Additional considerations

### Performance implications

While `trim()` is generally efficient, using it extensively on large datasets, especially in `WHERE` clauses, may impact query performance. If you frequently filter or join based on trimmed values, consider creating a functional index on the trimmed column.

### Handling NULL values

The `trim()` function returns NULL if the input string is NULL. Be aware of this when working with potentially NULL columns to avoid unexpected results.

### Alternative functions

- `ltrim()` - Removes specified characters from the beginning (left side) of a string.
- `rtrim()` - Removes specified characters from the end (right side) of a string.
- `btrim()` - Removes specified characters from both the beginning and end of a string.
- `regexp_replace()` - Can be used for more complex trimming operations using regular expressions.

## Resources

- [PostgreSQL documentation: String functions and operators](https://www.postgresql.org/docs/current/functions-string.html)
- [PostgreSQL documentation: Pattern matching](https://www.postgresql.org/docs/current/functions-matching.html)

--- [Document source](https://neon.com/docs/functions/window-lag.md) ---

> Summary: The `lag()` window function in Postgres returns a value from a prior row in a sorted partition, enabling day-over-day differences, week-over-week trends, and days-since-last-event calculations without a self-join. Use `lag()` to compare each row to a prior row, as opposed to `lead()` (which looks ahead) or aggregate functions (which collapse rows). It accepts an optional offset and a default value for rows beyond the partition boundary.

# Postgres lag() window function

Use lag() to access values from previous rows in a result set

Last updated: 2026-06-05

The `lag()` function in Postgres is a window function that allows you to access values from previous rows in a result set without the need for a self-join. It's useful for comparing values between the current row and a previous row, for example, when calculating running differences, plotting trends, or doing time series analysis.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `lag()` function has the following forms:

```sql
lag(value any [, offset integer [, default any ]]) over (...)
```

- `value`: The value to return from the previous row. This can be a column, expression, or subquery.
- `offset` (optional): The number of rows back from the current row to retrieve the value from. If omitted, it defaults to 1. Must be a non-negative integer.
- `default` (optional): The value to return when the offset goes beyond the scope of the window. If omitted, it defaults to null.
- `over (...)`: The `OVER` clause defines the window frame for the function. It can be an empty `OVER ()`, or it can include a `PARTITION BY` and/or `ORDER BY` clause.

## Example usage

Consider a table `sales` that contains daily sales data for a company. We can use `lag()` to compare each day's sales to the previous day's sales.

```sql
WITH sales AS (
  SELECT date '2023-01-01' AS sale_date, 1000 AS amount
  UNION ALL
  SELECT date '2023-01-02' AS sale_date, 1500 AS amount
  UNION ALL
  SELECT date '2023-01-03' AS sale_date, 1200 AS amount
  UNION ALL
  SELECT date '2023-01-04' AS sale_date, 1800 AS amount
)
SELECT
  sale_date,
  amount,
  lag(amount) OVER (ORDER BY sale_date) AS prev_amount,
  amount - lag(amount) OVER (ORDER BY sale_date) AS diff
FROM sales;
```

This query calculates the previous day's sales amount (`prev_amount`) and the difference between the current day's sales and the previous day's sales (`diff`). The `OVER` clause specifies that the window frame should be ordered by `sale_date`.

```text
 sale_date  | amount | prev_amount |  diff
------------+--------+-------------+-------
 2023-01-01 |   1000 |             |
 2023-01-02 |   1500 |        1000 |   500
 2023-01-03 |   1200 |        1500 |  -300
 2023-01-04 |   1800 |        1200 |   600
(4 rows)
```

You can also use `lag()` to access values from rows further back by specifying an offset. For example, to compare each day's sales to the sales from the same day of the previous week:

```sql
WITH sales AS (
  SELECT
    sale_date,
    floor(random() * 1000 + 1)::int AS amount
  FROM generate_series(date '2023-01-01', date '2023-01-31', interval '1 day') AS sale_date
)
SELECT
  sale_date,
  amount,
  lag(amount, 7) OVER (ORDER BY sale_date) AS prev_week_amount,
  amount - lag(amount, 7) OVER (ORDER BY sale_date) AS diff
FROM sales
ORDER BY sale_date DESC
LIMIT 5;
```

This query generates random sales data for each day in January 2023 and compares each day's sales to the sales from the same day of the previous week. The `lag()` function with an offset of 7 retrieves the sales amount from 7 days ago.

```text
       sale_date        | amount | prev_week_amount | diff
------------------------+--------+------------------+------
 2023-01-31 00:00:00+00 |    245 |               64 |  181
 2023-01-30 00:00:00+00 |    736 |              789 |  -53
 2023-01-29 00:00:00+00 |    208 |              763 | -555
 2023-01-28 00:00:00+00 |    710 |              899 | -189
 2023-01-27 00:00:00+00 |      1 |              229 | -228
 (5 rows)
```

## Advanced examples

### Using `lag()` with a default value

When the offset in `lag()` goes beyond the start of the window frame, it returns null by default. You can specify a default value to use instead, so the resulting column does not contain nulls.

```sql
WITH inventory AS (
  SELECT date '2023-01-01' AS snapshot_date, 100 AS quantity
  UNION ALL
  SELECT date '2023-01-02' AS snapshot_date, 80 AS quantity
  UNION ALL
  SELECT date '2023-01-03' AS snapshot_date, 120 AS quantity
  UNION ALL
  SELECT date '2023-01-04' AS snapshot_date, 90 AS quantity
)
SELECT
  snapshot_date,
  quantity,
  lag(quantity, 1, quantity) OVER (ORDER BY snapshot_date) AS prev_quantity,
  quantity - lag(quantity, 1, quantity) OVER (ORDER BY snapshot_date) AS change
FROM inventory;
```

This query calculates the change in inventory quantity compared to the previous day. For the first row, where there is no previous quantity, it uses the current quantity as the default value, resulting in a change of 0.

```text
 snapshot_date | quantity | prev_quantity | change
---------------+----------+---------------+--------
 2023-01-01    |      100 |           100 |      0
 2023-01-02    |       80 |           100 |    -20
 2023-01-03    |      120 |            80 |     40
 2023-01-04    |       90 |           120 |    -30
(4 rows)
```

### Using `lag()` with partitioning

You can use `lag()` with partitioning to perform calculations within groups of rows.

```sql
WITH orders AS (
  SELECT 1 AS order_id, date '2023-01-01' AS order_date, 100 AS amount, 1 AS customer_id
  UNION ALL
  SELECT 2 AS order_id, date '2023-01-02' AS order_date, 150 AS amount, 1 AS customer_id
  UNION ALL
  SELECT 3 AS order_id, date '2023-01-03' AS order_date, 200 AS amount, 2 AS customer_id
  UNION ALL
  SELECT 4 AS order_id, date '2023-01-04' AS order_date, 120 AS amount, 1 AS customer_id
  UNION ALL
  SELECT 5 AS order_id, date '2023-01-05' AS order_date, 180 AS amount, 2 AS customer_id
)
SELECT
  order_id,
  order_date,
  amount,
  customer_id,
  lag(order_date) OVER (PARTITION BY customer_id ORDER BY order_date) AS prev_order_date,
  order_date - lag(order_date) OVER (PARTITION BY customer_id ORDER BY order_date) AS days_since_last_order
FROM orders;
```

This query calculates the number of days since each customer's previous order. The `OVER` clause partitions the data by `customer_id` and orders it by `order_date` within each partition.

```text
 order_id | order_date | amount | customer_id | prev_order_date | days_since_last_order
----------+------------+--------+-------------+-----------------+-----------------------
        1 | 2023-01-01 |    100 |           1 |                 |
        2 | 2023-01-02 |    150 |           1 | 2023-01-01      |                     1
        4 | 2023-01-04 |    120 |           1 | 2023-01-02      |                     2
        3 | 2023-01-03 |    200 |           2 |                 |
        5 | 2023-01-05 |    180 |           2 | 2023-01-03      |                     2
(5 rows)
```

## Additional considerations

### Correctness

The `lag()` function relates each row in the result set to a previous row in the same window frame. If the window frame is not explicitly defined, the default frame is the entire result set. Make sure to specify the correct `ORDER BY` and `PARTITION BY` clauses to ensure the desired behavior.

### Performance implications

Window functions like `lag()` perform calculations across a set of rows defined by the `OVER` clause. This can be computationally expensive for large datasets or complex window definitions.

To optimize performance, make sure to:

- Include an `ORDER BY` clause in the `OVER` clause to avoid sorting the entire dataset.
- Use partitioning (`PARTITION BY`) to divide the data into smaller chunks when possible.
- Create appropriate indexes on the columns used in the `OVER` clause.

### Alternative functions

- [lead](https://neon.com/docs/functions/window-lead) - Access values from subsequent rows in a result set. Similar to `lag()` but looks ahead in the partition instead of behind.
- `first_value()` - Get the first value within a window frame.
- `last_value()` - Get the last value within a window frame.

## Resources

- [PostgreSQL documentation: Window functions](https://www.postgresql.org/docs/current/tutorial-window.html)
- [PostgreSQL documentation: Lag function](https://www.postgresql.org/docs/current/functions-window.html#FUNCTIONS-WINDOW-TABLE)

--- [Document source](https://neon.com/docs/functions/window-lead.md) ---

> Summary: The `lead()` window function in Postgres reads a value from a future row in a sorted partition without a self-join. Use it to calculate time until the next event, find the next value in a sequence, or detect forward trends in time-series data. It is the forward-looking counterpart to `lag()`, and accepts an optional integer offset and a default value for when the offset extends past the end of the partition.

# Postgres lead() window function

Use lead() to access values from subsequent rows in a result set

Last updated: 2026-06-05

The `lead()` function in Postgres is a window function that allows you to access values from subsequent rows in a result set without the need for a self-join.

It's useful for comparing values between the current row and a later row, for example, when calculating the time until the next event, determining the next event in a sequence, or analyzing trends in time series data.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `lead()` function has the following forms:

```sql
lead(value any [, offset integer [, default any ]]) over (...)
```

- `value`: The value to return from the subsequent row. This can be a column, expression, or subquery.
- `offset` (optional): The number of rows ahead of the current row to retrieve the value from. If omitted, it defaults to 1. Must be a non-negative integer.
- `default` (optional): The value to return when the offset goes beyond the scope of the window. If omitted, it defaults to null.
- `over (...)`: The `OVER` clause defines the window frame for the function. It can be an empty `OVER ()`, or it can include a `PARTITION BY` and/or `ORDER BY` clause.

## Example usage

Consider a table `shipments` that contains information about product shipments. We can use `lead()` to determine the next scheduled shipment date for each product.

```sql
WITH shipments AS (
  SELECT 1 AS product_id, date '2023-01-01' AS ship_date
  UNION ALL
  SELECT 1 AS product_id, date '2023-01-15' AS ship_date
  UNION ALL
  SELECT 2 AS product_id, date '2023-01-05' AS ship_date
  UNION ALL
  SELECT 1 AS product_id, date '2023-02-01' AS ship_date
  UNION ALL
  SELECT 2 AS product_id, date '2023-01-20' AS ship_date
)
SELECT
  product_id,
  ship_date,
  lead(ship_date) OVER (PARTITION BY product_id ORDER BY ship_date) AS next_ship_date,
  lead(ship_date) OVER (PARTITION BY product_id ORDER BY ship_date) - ship_date AS days_until_next_shipment
FROM shipments;
```

This query calculates the next shipment date (`next_ship_date`) and the number of days until the next shipment (`days_until_next_shipment`) for each product. The `OVER` clause partitions the data by `product_id` and orders it by `ship_date` within each partition.

```text
 product_id | ship_date  | next_ship_date | days_until_next_shipment
------------+------------+----------------+--------------------------
          1 | 2023-01-01 | 2023-01-15     |                       14
          1 | 2023-01-15 | 2023-02-01     |                       17
          1 | 2023-02-01 |                |
          2 | 2023-01-05 | 2023-01-20     |                       15
          2 | 2023-01-20 |                |
(5 rows)
```

You can also use `lead()` to access values from rows further ahead by specifying an offset. For example, to compute the net return on investment for a stock ticker over each 2-year period:

```sql
WITH stock_prices AS (
  SELECT 'AAPL' AS ticker, date '2018-01-01' AS price_date, 41.54 AS price
  UNION ALL
  SELECT 'AAPL' AS ticker, date '2019-01-01' AS price_date, 39.48 AS price
  UNION ALL
  SELECT 'AAPL' AS ticker, date '2020-01-01' AS price_date, 74.60 AS price
  UNION ALL
  SELECT 'AAPL' AS ticker, date '2021-01-01' AS price_date, 131.96 AS price
  UNION ALL
  SELECT 'AAPL' AS ticker, date '2022-01-01' AS price_date, 182.01 AS price
  UNION ALL
  SELECT 'AAPL' AS ticker, date '2023-01-01' AS price_date, 129.93 AS price
)
SELECT
  ticker,
  price_date,
  price,
  lead(price, 2) OVER (PARTITION BY ticker ORDER BY price_date) AS price_2_years_later,
  round(100.0 * (lead(price, 2) OVER (PARTITION BY ticker ORDER BY price_date) - price) / price, 2) AS two_year_return_pct
FROM stock_prices;
```

This query calculates the price of each stock ticker 2 years later (`price_2_years_later`) and the percentage return on investment (`two_year_return_pct`) for each ticker. The `OVER` clause partitions the data by `ticker` and orders it by `price_date` within each partition.

```text
 ticker | price_date | price  | price_2_years_later | two_year_return_pct
--------+------------+--------+---------------------+---------------------
 AAPL   | 2018-01-01 |  41.54 |               74.60 |               79.59
 AAPL   | 2019-01-01 |  39.48 |              131.96 |              234.25
 AAPL   | 2020-01-01 |  74.60 |              182.01 |              143.98
 AAPL   | 2021-01-01 | 131.96 |              129.93 |               -1.54
 AAPL   | 2022-01-01 | 182.01 |                     |
 AAPL   | 2023-01-01 | 129.93 |                     |
 (6 rows)
```

## Advanced examples

### Using `lead()` with a default value

When the offset in `lead()` goes beyond the end of the window frame, it returns null by default. You can specify a default value to use instead, so the resulting column does not contain nulls.

```sql
WITH tasks AS (
  SELECT 1 AS project_id, 1 AS task_id, date '2023-01-01' AS start_date, date '2023-01-05' AS end_date
  UNION ALL
  SELECT 1 AS project_id, 2 AS task_id, date '2023-01-07' AS start_date, date '2023-01-10' AS end_date
  UNION ALL
  SELECT 1 AS project_id, 3 AS task_id, date '2023-01-10' AS start_date, date '2023-01-15' AS end_date
  UNION ALL
  SELECT 2 AS project_id, 1 AS task_id, date '2023-01-01' AS start_date, date '2023-01-10' AS end_date
  UNION ALL
  SELECT 2 AS project_id, 2 AS task_id, date '2023-01-11' AS start_date, date '2023-01-20' AS end_date
)
SELECT
  project_id,
  task_id,
  start_date,
  end_date,
  lead(start_date, 1, end_date) OVER (PARTITION BY project_id ORDER BY start_date) AS next_start_date
FROM tasks;
```

This query determines the start date of the next task in each project. For the last task in each project, where there is no next start date, it uses the current task's end date as the default value.

```text
 project_id | task_id | start_date |  end_date  | next_start_date
------------+---------+------------+------------+-----------------
          1 |       1 | 2023-01-01 | 2023-01-05 | 2023-01-07
          1 |       2 | 2023-01-07 | 2023-01-10 | 2023-01-10
          1 |       3 | 2023-01-10 | 2023-01-15 | 2023-01-15
          2 |       1 | 2023-01-01 | 2023-01-10 | 2023-01-11
          2 |       2 | 2023-01-11 | 2023-01-20 | 2023-01-20
(5 rows)
```

### Using `lead()` with multiple partitions

You can use `lead()` with multiple partitions to perform calculations within different groups of rows simultaneously.

```sql
WITH readings AS (
  SELECT 1 AS device_id, date '2023-01-01' AS reading_date, 25.5 AS temperature
  UNION ALL
  SELECT 1 AS device_id, date '2023-01-02' AS reading_date, 26.0 AS temperature
  UNION ALL
  SELECT 2 AS device_id, date '2023-01-01' AS reading_date, 22.1 AS temperature
  UNION ALL
  SELECT 1 AS device_id, date '2023-01-03' AS reading_date, 25.8 AS temperature
  UNION ALL
  SELECT 2 AS device_id, date '2023-01-02' AS reading_date, 21.9 AS temperature
)
SELECT
  device_id,
  reading_date,
  temperature,
  lead(temperature) OVER (PARTITION BY device_id ORDER BY reading_date) AS next_temperature,
  lead(temperature) OVER (PARTITION BY device_id ORDER BY reading_date) - temperature AS temperature_change
FROM readings;
```

This query calculates the next temperature reading (`next_temperature`) and the change in temperature (`temperature_change`) for each device. The `OVER` clause partitions the data by `device_id` and orders it by `reading_date` within each partition, allowing the analysis to be performed separately for each device.

```text
 device_id | reading_date | temperature | next_temperature | temperature_change
-----------+--------------+-------------+------------------+--------------------
         1 | 2023-01-01   |        25.5 |             26.0 |                0.5
         1 | 2023-01-02   |        26.0 |             25.8 |               -0.2
         1 | 2023-01-03   |        25.8 |                  |
         2 | 2023-01-01   |        22.1 |             21.9 |               -0.2
         2 | 2023-01-02   |        21.9 |                  |
(5 rows)
```

## Additional considerations

### Correctness

The `lead()` function relates each row in the result set to a subsequent row in the same window frame. If the window frame is not explicitly defined, the default frame is the entire partition or result set. Make sure to specify the correct `ORDER BY` and `PARTITION BY` clauses to ensure the desired behavior.

### Performance implications

Window functions like `lead()` perform calculations across a set of rows defined by the `OVER` clause. This can be computationally expensive, especially for large datasets or complex window definitions.

To optimize performance, make sure to:

- Include an `ORDER BY` clause in the `OVER` clause to avoid sorting the entire dataset.
- Use partitioning (`PARTITION BY`) to divide the data into smaller chunks when possible.
- Create appropriate indexes on the columns used in the `OVER` clause.

### Alternative functions

- [lag](https://neon.com/docs/functions/window-lag) - Access values from previous rows in a result set. Similar to `lead()` but looks behind in the partition instead of ahead.
- `first_value()` - Get the first value within a window frame.
- `last_value()` - Get the last value within a window frame.

## Resources

- [PostgreSQL documentation: Window functions](https://www.postgresql.org/docs/current/tutorial-window.html)
- [PostgreSQL documentation: Lead function](https://www.postgresql.org/docs/current/functions-window.html#FUNCTIONS-WINDOW-TABLE)

--- [Document source](https://neon.com/docs/functions/window-rank.md) ---

> Summary: The `rank()` window function assigns integer ranks to rows within a partition, giving tied rows the same rank and skipping subsequent rank values after ties. Use `rank()` for top-N-per-group queries, leaderboards, or percentile calculations where gaps in the rank sequence after ties are acceptable. Unlike `dense_rank()` (consecutive ranks, no gaps) or `row_number()` (unique integers regardless of ties), `rank()` reflects tied positions by leaving gaps.

# Postgres rank() window function

Use rank() to assign ranks to rows within a result set

Last updated: 2026-06-05

The `rank()` window function computes a ranking for each row within a partition of the result set. The rank is determined by the order of rows specified in the `ORDER BY` clause of the `OVER` clause. Rows with equal values for the ranking criteria receive the same rank, with the next rank(s) skipped.

This function is useful in scenarios such as finding the top N rows per group, calculating percentiles, or generating leaderboards.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Function signature

The `rank()` function has the following form:

```sql
rank() OVER ([PARTITION BY partition_expression] ORDER BY order_expression)
```

The `OVER` clause defines the window frame for the function.

- The `ORDER BY` clause specifies the order in which ranks are assigned to rows.
- The `PARTITION BY` clause is optional - if specified, it divides the result set into partitions and ranks are assigned within each partition. Otherwise, ranks are computed for each row over the entire result set.

## Example usage

Consider an `employees` table with columns for employee ID, name, department, and salary. We can use `rank()` to rank employees within each department by their salary.

```sql
WITH sample_data AS (
    SELECT *
    FROM (
        VALUES
            ('Alice', 'Sales', 50000),
            ('Bob', 'Marketing', 55000),
            ('Charlie', 'Sales', 52000),
            ('David', 'IT', 60000),
            ('Eve', 'Marketing', 55000),
            ('Frank', 'IT', 62000)
    ) AS t(employee_name, department, salary)
)
SELECT
    employee_name,
    department,
    salary,
    RANK() OVER (PARTITION BY department ORDER BY salary DESC) AS dept_salary_rank
FROM sample_data
ORDER BY department, dept_salary_rank;
```

This query ranks employees within each department based on their salary in descending order. Employees with the same salary within a department receive the same rank.

```text
 employee_name | department | salary | dept_salary_rank
---------------+------------+--------+------------------
 Frank         | IT         |  62000 |                1
 David         | IT         |  60000 |                2
 Bob           | Marketing  |  55000 |                1
 Eve           | Marketing  |  55000 |                1
 Charlie       | Sales      |  52000 |                1
 Alice         | Sales      |  50000 |                2
(6 rows)
```

## Advanced examples

### Top N per group

You can use `rank()` in a subquery to find the top N rows per group.

```sql
WITH products AS (
    SELECT *
    FROM (
        VALUES
            (1, 'A', 100),
            (2, 'A', 80),
            (3, 'B', 200),
            (4, 'B', 180),
            (5, 'B', 150),
            (6, 'C', 120)
    ) AS t(product_id, category, price)
)
SELECT *
FROM (
    SELECT
        product_id,
        category,
        price,
        rank() OVER (PARTITION BY category ORDER BY price DESC) AS rank
    FROM products
) ranked
WHERE rank <= 2;
```

This query finds the top 2 most expensive products in each category. The subquery ranks products within each category by price, and the outer query filters for rows with a rank less than or equal to 2.

```text
 product_id | category | price | rank
------------+----------+-------+------
          1 | A        |   100 |    1
          2 | A        |    80 |    2
          3 | B        |   200 |    1
          4 | B        |   180 |    2
          6 | C        |   120 |    1
(5 rows)
```

### Percentile calculation

You can calculate percentiles using the `rank()` function with some arithmetic.

```sql
WITH scores AS (
	SELECT *
	FROM (
        VALUES
            ('Student 1', 85),
            ('Student 2', 92),
            ('Student 3', 78),
            ('Student 4', 90),
            ('Student 5', 88)
	) AS t(student, score)
)
SELECT
	student,
	score,
	rank() OVER (ORDER BY score) AS rank,
	round(100.0 * rank() OVER (ORDER BY score) / (SELECT count(*) FROM scores), 2) AS percentile
FROM scores;
```

This query calculates the percentile rank for each student based on their score. The percentile is calculated by dividing the rank of each row by the total number of rows and multiplying by 100.

```text
  student  | score | rank | percentile
-----------+-------+------+------------
 Student 3 |    78 |    1 |      20.00
 Student 1 |    85 |    2 |      40.00
 Student 5 |    88 |    3 |      60.00
 Student 4 |    90 |    4 |      80.00
 Student 2 |    92 |    5 |     100.00
(5 rows)
```

## Alternative functions

### dense_rank

The `dense_rank()` function is similar to `rank()`, but it does not skip ranks when there are ties. If multiple rows have the same rank, the next rank will be the next consecutive integer.

```sql
WITH scores AS (
    SELECT *
    FROM (
        VALUES
            ('Player 1', 100),
            ('Player 2', 95),
            ('Player 3', 95),
            ('Player 4', 90)
    ) AS t(player, score)
)
SELECT
    player,
    score,
    rank() OVER (ORDER BY score DESC) AS rank,
    dense_rank() OVER (ORDER BY score DESC) AS dense_rank
FROM scores;
```

This query demonstrates the difference between `rank()` and `dense_rank()`. While `rank()` skips rank 3 due to the tie at rank 2, `dense_rank()` assigns consecutive ranks.

```text
  player  | score | rank | dense_rank
----------+-------+------+------------
 Player 1 |   100 |    1 |          1
 Player 2 |    95 |    2 |          2
 Player 3 |    95 |    2 |          2
 Player 4 |    90 |    4 |          3
(4 rows)
```

### row_number

The `row_number()` function assigns a unique, sequential integer to each row within the partition of a result set. Unlike `rank()` and `dense_rank()`, it does not handle ties.

```sql
WITH sales AS (
    SELECT date '2023-01-01' AS sale_date, 1000 AS amount
    UNION ALL
    SELECT date '2023-01-01', 1500
    UNION ALL
    SELECT date '2023-01-02', 1200
    UNION ALL
    SELECT date '2023-01-02', 1200
)
SELECT
    sale_date,
    amount,
    row_number() OVER (PARTITION BY sale_date ORDER BY amount DESC) AS row_num
FROM sales;
```

This query assigns a unique row number to each sale within a date, ordered by the sale amount descending. Even though there are ties for the date `2023-01-02`, each row receives a distinct row number.

```text
 sale_date  | amount | row_num
------------+--------+---------
 2023-01-01 |   1500 |       1
 2023-01-01 |   1000 |       2
 2023-01-02 |   1200 |       1
 2023-01-02 |   1200 |       2
(4 rows)
```

## Additional considerations

### Handling ties

The `rank()` and `dense_rank()` functions handle ties differently. `rank()` assigns the same rank to tied rows and skips the next rank(s), while `dense_rank()` assigns the same rank to tied rows but does not skip ranks. Choose the appropriate function based on your requirements.

### Performance implications

Like other window functions, `rank()` performs calculations across a set of rows defined by the `OVER` clause. This can be computationally expensive, especially for large datasets or complex window definitions.

To optimize performance:

- Include an `ORDER BY` clause in the `OVER` clause to avoid sorting the entire dataset.
- Use partitioning (`PARTITION BY`) to divide the data into smaller chunks when possible.
- Create appropriate indexes on the columns used in the `OVER` clause.

## Resources

- [PostgreSQL documentation: Window functions](https://www.postgresql.org/docs/current/functions-window.html)
- [PostgreSQL documentation: Tutorial on window functions](https://www.postgresql.org/docs/current/tutorial-window.html)

--- [Document source](https://neon.com/docs/get-started/backend-overview.md) ---

> Summary: A tour of the Neon backend, using one example app, a notes app you can chat with, to show how the pieces fit. A single neon.ts declares Postgres, Object Storage, Functions, the AI Gateway, Auth, and the Data API; each is a toggle (Postgres is on by default) plus neon deploy, which injects standard environment variables. Branch your project and the whole backend follows it through service-specific lifecycle mechanics. Each section covers what a capability is, when to use it, and the Neon-specific part you write, and links to that capability's own quickstart for the full setup.

# How a Neon backend fits together

Postgres, Object Storage, Functions, the AI Gateway, Auth, and the Data API, declared in one neon.ts and branched together

Last updated: 2026-10-30

On Neon, a single [`neon.ts`](https://neon.com/docs/reference/neon-ts) file declares your whole backend: a **Postgres database**, S3-compatible **Object Storage**, long-running **Functions**, an **AI Gateway** for calling LLMs through one credential, managed **Auth**, and the **Data API**. Each capability is a toggle, or on by default for Postgres, plus [`neon deploy`](https://neon.com/docs/cli/deploy), which provisions it and injects standard environment variables into your app. Branch your project and the whole backend follows it through service-specific lifecycle mechanics.

**Note: This is an orientation page**

This page shows how the pieces fit, not how to build step by step, so the snippets are illustrative. To build now, copy the prompt below or jump to [Where to build it](https://neon.com/docs/get-started/backend-overview#where-to-build-it). For one capability's full setup, follow its Reference link.

Hand this to your AI assistant to set up Neon: skills, project, and all capabilities. Then tell it what to build. [View prompt](https://neon.com/prompts/neon-backend.md)

## What you'll build

The running example is a **notes app you can chat with**. Signed-in users write notes, attach files to them, and ask an AI questions about their own notes. That one app uses five of Neon's six backend capabilities:

```
Browser  ──request + auth token──▶  Function (chat)
                                      │  verifies the token .............. Auth
                                      ├─▶ reads the user's notes ......... Postgres
                                      ├─▶ pulls attached files ........... Object Storage
                                      └─▶ sends the context to an LLM .... AI Gateway

Function  ──streams the answer──▶  Browser
```

So when you see a `notes` table, an `attachments` bucket, or a `chat` function below, they're all parts of this same app. Postgres is the system of record for notes; Storage holds the files that are too big for a row; the Function is the long-running piece that handles a chat request; the AI Gateway is the single credential for the model call; and Auth decides whose notes a request may read.

The sixth capability is the [Data API](https://neon.com/docs/data-api/overview), which exposes Postgres through a PostgREST-compatible HTTPS endpoint. This example doesn't enable it because the `chat` Function queries Postgres directly.

**Info: Region and access requirements**

Object Storage, Functions, and the AI Gateway are currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`), on new or existing projects in those regions, so use a project in one of them to try them. Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). Postgres and Managed Better Auth work in any region. Object Storage and Functions are available on any plan, subject to usage limits; the AI Gateway works on any plan with prepaid credits.

## The shape of a Neon backend

The setup is a few commands; the [CLI quickstart](https://neon.com/docs/cli/quickstart) is the full how-to. Install the CLI, link a project, scaffold one `neon.ts`.

Install the [`neon` CLI](https://neon.com/docs/cli/install) (requires **Node.js 20.19 or higher**) and sign in with [`neon login`](https://neon.com/docs/cli/login):

```bash
npm i -g neon
neon login
```

Then create the project. Create it in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, or `aws-ap-southeast-1` so the backend services are available:

```bash
neon link --project-name notes-app --region-id aws-us-east-2
```

[`neon link`](https://neon.com/docs/cli/link) writes your project context to a `.neon` file and pulls the branch's `DATABASE_URL` into a local `.env`. Then scaffold a `neon.ts` to declare the rest of your backend:

```bash
neon config init
```

<details>

<summary>The generated </summary>

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

export default defineConfig({
  // Declare your Neon services here
  auth: false,
  // Branch policy: per-branch tuning
  branch: (branch) => {
    if (branch.isDefault) {
      // Default branch: no overrides, uses project defaults
      return {};
    }
    if (!branch.exists) {
      // New non-default branches: auto-expire
      // Run `neon checkout <name> --create` to create a new branch with these settings
      return { ttl: "7d" };
    }
    // Existing branch: no changes
    return {};
  },
});
```

</details>

This creates `neon.ts` and installs the `@neon/config` and `@neon/env` packages. Each section below adds one capability to it.

## How it works

For capabilities declared in `neon.ts`, the setup follows the same three steps: **enable the service, run [`neon deploy`](https://neon.com/docs/cli/deploy), then read the injected environment variables.**

- **`neon.ts` is your backend as code.** One file declares Auth and the backend services; Postgres is on by default.
- **`neon deploy` reconciles that file** against your branch, provisions each service, and writes its credentials to your env file.
- **Branching forks the whole backend together through service-specific mechanics.** Postgres and Object Storage create copy-on-write state. Each branch runs its own Functions at their own URLs and gets its own Auth environment, Data API endpoint, and AI Gateway endpoint. AI Gateway credentials work on the branch where they're issued and its descendants. See [Branch your whole backend](https://neon.com/docs/get-started/backend-overview#branch-your-whole-backend).

| Capability              | Enable in `neon.ts`  | Injected env vars                                                                 | You use it with                                   |
| ----------------------- | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------- |
| **Postgres**            | on by default        | `DATABASE_URL`                                                                    | `@neondatabase/serverless`, or `pg` in a Function |
| **Object Storage**      | `buckets: { ... }`   | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, `AWS_REGION` | `files-sdk` (or any S3 client)                    |
| **Functions**           | `functions: { ... }` | `DATABASE_URL` and more, inside the function                                      | Hono (any web framework)                          |
| **AI Gateway**          | `aiGateway: true`    | `NEON_AI_GATEWAY_BASE_URL`, `NEON_AI_GATEWAY_TOKEN`                               | `@neon/ai-sdk-provider`                           |
| **Managed Better Auth** | `auth: true`         | `NEON_AUTH_BASE_URL`, `NEON_AUTH_JWKS_URL`                                        | `@neon/auth`                                      |
| **Data API**            | `dataApi: true`      | `NEON_DATA_API_URL`                                                               | `@neon/neon-js`                                   |

**Note: Reading the snippets**

The `neon.ts` fragments below show only the key being added. `auth`, `dataApi`, and the backend features (`buckets`, `functions`, `aiGateway`) are all top-level keys of `defineConfig({ ... })` (see [neon.ts](https://neon.com/docs/reference/neon-ts#services)). The [complete file](https://neon.com/docs/get-started/backend-overview#where-to-build-it) shows the five services this example uses assembled. Credentials are written to `.env` if you have one, otherwise `.env.local`; this page writes `.env` for whichever is yours.

## Postgres: the notes

**What it is:** serverless Postgres, generally available. **When to use it:** your system of record, anything relational. In the notes app, it holds the notes themselves. **When not:** large binary files, keep the bytes in [Object Storage](https://neon.com/docs/get-started/backend-overview#object-storage-the-attachments) and store the key in a column.

There's nothing to enable, since `neon link` already wrote `DATABASE_URL`. Create a `notes` table, then query it with the [serverless driver](https://neon.com/docs/serverless/serverless-driver), which talks to your branch over HTTP and suits serverless and edge runtimes:

```typescript filename="lib/db.ts"
import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
const notes = await sql`select id, title, body from notes order by created_at desc limit 20`;
```

Use it directly or behind an ORM like Drizzle. Schema, migrations, and route handlers are standard application code.

**Reference:** [Serverless driver](https://neon.com/docs/serverless/serverless-driver) · [Connect from any framework](https://neon.com/docs/get-started/frameworks)

## Object Storage: the attachments

**What it is:** S3-compatible object storage that branches together with your database, so files and rows stay in sync on every branch. In the notes app, it stores the files a user attaches to a note. **When to use it:** attachments, uploads, user files, anything too large for a column. **When not:** small structured values that belong in a row, where `text`, `jsonb`, or `bytea` is simpler and transactional.

Declare an `attachments` bucket (private by default) and deploy. `neon deploy` provisions it and injects AWS-standard credentials, so any S3 client works unchanged:

```typescript filename="neon.ts"
// top level
buckets: { attachments: {} },
```

Store the object **key** on the note row in Postgres and generate a short-lived URL on read, so the note and its file never drift. With the [Files SDK](https://files-sdk.dev):

```typescript filename="lib/storage.ts"
import { Files } from "files-sdk";
import { neon } from "files-sdk/neon"; // reads the injected AWS_* vars

const files = new Files({ adapter: neon({ bucket: "attachments" }) });

await files.upload(key, bytes, { contentType });      // save an attachment
const url = await files.url(key, { expiresIn: 3600 }); // short-lived download URL
```

**Reference:** [Storage get-started](https://neon.com/docs/storage/get-started) (credentials, S3/Python/CLI clients, public buckets) · [Overview](https://neon.com/docs/storage/overview)

## Functions: the chat endpoint

**What it is:** long-running serverless compute that runs next to your database and gets a public URL. In the notes app, it's the `chat` endpoint the browser calls. **When to use it:** work that outlasts a short serverless or edge request, streaming responses, background jobs, or an AI agent that makes several model calls. **When not:** a quick query that fits in a Next.js route handler, which serverless and edge hosts serve fine.

Declare the `chat` function and deploy. `neon deploy` bundles it, deploys it, prints its URL, and injects `DATABASE_URL` at runtime (plus the AI Gateway vars once you enable it below):

```typescript filename="neon.ts"
// top level
functions: {
  chat: { name: "notes chat", source: "./functions/chat.ts" },
},
```

The function is a normal [Hono](https://hono.dev) app. Because it keeps running across requests, it can open a `pg` connection once at module scope and reuse it, rather than the per-request serverless driver from the [Postgres](https://neon.com/docs/get-started/backend-overview#postgres-the-notes) section. You extend this same file in the next two sections, adding the AI call and the auth check:

```typescript filename="functions/chat.ts"
import { Hono } from "hono";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL }); // reused across requests
const app = new Hono();

app.post("/chat", async (c) => {
  const notes = await pool.query("select title, body from notes order by created_at desc limit 20");
  // ...next: send these notes to an LLM through the AI Gateway
  return c.json({ count: notes.rowCount });
});

export default app;
```

Run it locally with [`neon dev`](https://neon.com/docs/cli/dev), which serves the function with the same injected Neon variables it gets in production.

Beyond the `chat` endpoint the browser calls, Neon can invoke a function for you: [Function Triggers](https://neon.com/docs/compute/functions/triggers/overview) run it on a schedule or when an object is uploaded, so background work runs as the same function code and branches with your project. For example, run the function whenever a file is attached:

```typescript filename="neon.ts"
// top level
triggers: {
  "process-attachment": {
    type: "storage_object_created",
    function: "chat",
    bucket: "attachments",
    functionPath: "/on-upload",
  },
},
```

The function answers a `POST` at `/on-upload` with the bucket and object key, so it processes each new attachment. A `type: "schedule"` trigger with a `cron` field runs it on a timer instead.

**Reference:** [Functions get-started](https://neon.com/docs/compute/functions/get-started) (local dev, deploy, invoke, connection-pool guidance) · [Overview](https://neon.com/docs/compute/functions/overview) · [Function Triggers](https://neon.com/docs/compute/functions/triggers/overview) (schedule or object-upload invocation)

## AI Gateway: the model call

**What it is:** one Neon credential to reach many LLM providers and models, with no separate provider keys to manage. In the notes app, the `chat` function uses it to answer questions grounded in the user's notes. **When to use it:** adding AI without wiring up per-provider keys and billing, or swapping models by changing one string. **When not:** a single provider you'll never switch away from, where calling its SDK directly is simpler.

Enable it and deploy; `neon deploy` and `neon dev` inject the gateway URL and token:

```typescript filename="neon.ts"
// top level
aiGateway: true,
```

The [`@neon/ai-sdk-provider`](https://www.npmjs.com/package/@neon/ai-sdk-provider) discovers the gateway from those variables, so `neon(model)` needs no base URL or key, and it routes each model family to the right upstream for you. Back in the `chat` function, stream an answer from the notes you just read:

```typescript filename="functions/chat.ts"
import { neon } from "@neon/ai-sdk-provider";
import { streamText } from "ai";

const result = streamText({
  model: neon("gpt-oss-120b"), // any enabled model, e.g. "glm-5-3-flash"; frontier models (OpenAI, Gemini) need access requested first
  system: "Answer using only the user's notes.",
  prompt: `${question}\n\nNotes:\n${notesText}`,
});
return result.toTextStreamResponse();
```

Output isn't only text. The same credential reaches other modalities through model-specific options; for example, OpenAI models can generate images via the `image_generation` tool on the Responses API. Set the tool's `model` option to `gpt-image-2`, because the default image model isn't available on AI Gateway. See the [model catalog](https://neon.com/docs/ai-gateway/models) for which models support what.

**Note: First call after a deploy**

Right after `neon deploy` on a new branch, the first gateway call can return a `403` (`credential not authorized for this branch`) while the credential propagates. It clears within a few seconds, so retry.

**Reference:** [AI Gateway get-started](https://neon.com/docs/ai-gateway/get-started) (streaming, troubleshooting) · [Model catalog](https://neon.com/docs/ai-gateway/models) (per-modality snippets) · [Overview](https://neon.com/docs/ai-gateway/overview)

## Managed Better Auth: per-user access

**What it is:** authentication with per-user data, plus a way to secure your functions by verifying tokens in your own code. In the notes app, it makes notes private, so each user chats only with their own. **When to use it:** making the app multi-user. **When not:** a single-user tool or internal script, where you can skip the toggle and the per-row `user_id`.

Enable it and deploy; `neon deploy` injects the auth base URL and JWKS URL:

```typescript filename="neon.ts"
auth: true,
```

Managed Better Auth needs a session cookie secret that you provide; it isn't injected. Generate one and add it as `NEON_AUTH_COOKIE_SECRET` in the same env file as your other credentials:

```bash
openssl rand -base64 32   # paste the output as NEON_AUTH_COOKIE_SECRET
```

On the server, gate data with `auth.getSession()` and store `session.user.id` on each note. Inside the `chat` function, verify the caller's JWT against the injected JWKS before reading any notes, and scope the query to that user:

```typescript filename="functions/chat.ts"
import { createRemoteJWKSet, jwtVerify } from "jose";

const jwks = createRemoteJWKSet(new URL(process.env.NEON_AUTH_JWKS_URL!));
const token = c.req.header("authorization")?.replace(/^Bearer /i, "") ?? "";
const { payload } = await jwtVerify(token, jwks); // throws if invalid
const userId = String(payload.sub);
// now: select ... from notes where user_id = $1
```

**Reference:** [Authentication flow](https://neon.com/docs/auth/authentication-flow) (JWT, JWKS, verifying the caller) · [Auth quickstart](https://neon.com/docs/auth/quick-start/nextjs-api-only) (SDK wiring, prebuilt UI) · [Overview](https://neon.com/docs/auth/overview)

## Branch your whole backend

A branch forks the whole backend through service-specific mechanics. Postgres and Object Storage branch their state copy-on-write. Each branch runs its own Functions at their own URLs and gets its own Managed Better Auth environment, Data API endpoint, and AI Gateway endpoint. AI Gateway credentials work on the branch where they're issued and its descendants.

To try a change to the notes app safely, switch to a new branch with [`neon checkout`](https://neon.com/docs/cli/checkout). Pass `--create` to create the branch if it doesn't exist yet:

```bash
neon checkout my-feature --create   # create my-feature if new, then switch to it
neon deploy                         # provisions that branch's services
```

`neon deploy` writes the new branch's credentials into `.env`, so the same code now runs against branch-specific infrastructure: a different database, an isolated `attachments` bucket, and its own `chat` URL. A note you write on the branch never appears on `main`.

The `branch` function in `neon.ts` sets per-branch policy, for example auto-expiring non-default branches:

```typescript filename="neon.ts"
branch: (branch) => {
  if (branch.isDefault) return {};            // production: no TTL
  if (!branch.exists) return { ttl: "7d" };   // new branches auto-expire
  return {};
},
```

**Reference:** [Branching](https://neon.com/docs/introduction/branching)

## Where to build it

Here is the complete `neon.ts` for the notes app, with the five capabilities used by this example in one file. The Data API remains disabled because the Function queries Postgres directly.

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

export default defineConfig({
  auth: true,
  aiGateway: true,
  buckets: { attachments: {} },
  functions: {
    chat: { name: "notes chat", source: "./functions/chat.ts" },
  },
  branch: (branch) => {
    if (branch.isDefault) return {};
    if (!branch.exists) return { ttl: "7d" };
    return {};
  },
});
```

These services are declared as top-level keys, alongside `auth`.

Two ways to get it running:

**Let your AI editor build it.** Copy the prompt at the top of this page and hand it to your assistant. It installs the core skill, links a Neon project, adds the Object Storage, Functions, and AI Gateway skills with `neon skills`, then builds against each capability's current API.

**Start from a template.** `neon bootstrap` scaffolds a ready-to-run starter, installs dependencies, and links a project:

```bash
neon bootstrap notes-app --template ai-sdk   # Postgres + Storage + Functions + AI Gateway
```

Run `neon bootstrap --list-templates` for the full list, or browse them in the [examples repo](https://github.com/neondatabase/examples).

## Verify

A fast sanity check after deploy; each capability's get-started has the real testing guidance. Run one check per capability:

| Capability     | Quick check                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Postgres       | `grep DATABASE_URL .env` returns a value and a `select` from `notes` returns rows                                                                    |
| Object Storage | `AWS_ENDPOINT_URL_S3` is in `.env` and a short-lived URL opens an attachment                                                                         |
| Functions      | `neon dev`'s local URL and the deployed `chat` URL both respond                                                                                      |
| AI Gateway     | a `chat` call returns a streamed answer; a `401` means a bad token, and a `403` right after deploy means the credential is still propagating (retry) |
| Auth           | a new sign-up appears in `neon_auth."user"` on your branch                                                                                           |
| Branching      | the new branch has its own `DATABASE_URL` and `chat` URL                                                                                             |

## Next steps

**Reference for each capability:** [Storage](https://neon.com/docs/storage/get-started) · [Functions](https://neon.com/docs/compute/functions/get-started) · [AI Gateway](https://neon.com/docs/ai-gateway/get-started) · [Auth](https://neon.com/docs/auth/quick-start/nextjs-api-only) · [Postgres](https://neon.com/docs/serverless/serverless-driver)

**Realtime:** [Realtime](https://neon.com/docs/realtime/overview). Live SQL and reactive DX on standard Postgres.

--- [Document source](https://neon.com/docs/get-started/built-to-scale.md) ---

> Summary: Neon fits every growth stage without requiring an architecture change: a free plan for side projects, autoscaling and copy-on-write branching for startup teams, and API-driven fleet management for scale-ups.

# Built to scale

Neon supports you from prototype to scale-up

Last updated: 2026-10-13

Neon fits into every stage of growth, from the first side project to operating large fleets of production backends, without forcing you to rethink your architecture along the way.

## Stage 1: Side projects

**A full backend on the Free plan**

When you're looking for a free plan to start building, what you want is simplicity and enough room to work. Neon's Free plan abstracts most backend configuration, delivers real-world performance, and gives you branching and autoscaling. And you get more than a database: alongside Lakebase Postgres, you can deploy Managed Better Auth, Object Storage for your files, and Functions, all on the same plan.

- A [Free plan with real resources](https://neon.com/docs/introduction/plans): up to 100 projects, each project with its own 100 CU-hours of database compute (autoscaling between 0.25 and 2 CU), 1 GB of Postgres storage, and 5 GB of egress, enough to build and test real applications
- Plus the rest of the backend: [Managed Better Auth](https://neon.com/docs/auth/overview) (up to 60,000 MAU), [Object Storage](https://neon.com/docs/storage/overview) (5 GB per project), and [Functions](https://neon.com/docs/compute/functions/overview) (1 million invocations per project per month)
- [Scale to zero](https://neon.com/docs/introduction/scale-to-zero) means idle projects don't eat into your compute allowance: only active time counts
- [Instant branching](https://neon.com/docs/introduction/branching) gives each experiment its own copy of the whole backend, data and buckets included, so you can try changes without risk
- It's real Postgres: it works with [any framework, ORM, or tool that speaks Postgres](https://neon.com/docs/get-started/frameworks), plus a [broad catalog of extensions](https://neon.com/docs/extensions/pg-extensions)

## Stage 2: Startups

**Build and iterate fast**

As a project becomes a product, small teams need to ship quickly and support real users. Neon allows these teams to build fast via coding agents without compromising on scalability or reliability, backed by Lakebase Postgres and the rest of the Neon backend:

> **Production checklist**
>
> Before launching your product, go through this checklist to make sure your database has the right configuration to support your end users.
>
> [View checklist](https://neon.com/docs/get-started/production-checklist)

- [Autoscaling](https://neon.com/docs/introduction/autoscaling) adapts automatically to unpredictable workloads: you don't have to plan capacity in advance
- [Branching](https://neon.com/branching) lets you spin up development, preview, and test environments instantly, matching the latest production state, without manual work
- [Realtime](https://neon.com/docs/realtime/overview) is built-in, so you can build fast, modern, collaborative apps
- [Out-of-the-box integrations](https://neon.com/docs/guides/integrations) with platforms like Vercel further simplify previews and deployments
- [API-first workflows](https://neon.com/docs/reference/api) make it easy to automate almost all database operations
- AI-coding support via [MCP](https://neon.com/docs/ai/neon-mcp-server) and [Agent Skills](https://neon.com/docs/ai/agent-skills) allows tools like Cursor and Claude to fully interact with Neon
- [Instant restores](https://neon.com/docs/guides/backup-restore) lower the stakes for mistakes and accidents
- [Built-in connection pooling](https://neon.com/docs/connect/connection-pooling) takes care of growing connections in your serverless apps
- You get access to [compliance and security features](https://neon.com/blog/why-we-no-longer-lock-premium-features) without enterprise-only contracts
- The rest of the backend grows on the same project: [Managed Better Auth](https://neon.com/docs/auth/overview), [Object Storage](https://neon.com/docs/storage/overview), [Functions](https://neon.com/docs/compute/functions/overview), and the [Data API](https://neon.com/docs/data-api/overview), added as you need them

## Stage 3: Scale-ups and large fleets

**Operations at scale**

At this stage, teams need performance, reliability, isolation, and automation without ballooning costs or operational complexity. The lakebase architecture is built to address their different requirements directly.

### Operational efficiency

- [On-demand storage](https://neon.com/storage#unique-benefits-derived-from-neons-implementation) grows as data demands it, without planning for capacity in advance and without the risk of full-disk errors
- [Built-in high availability](https://neon.com/docs/introduction/high-availability) is provided by default through storage redundancy, with data replicated across availability zones and cloud object storage
- [Backup and restore via snapshots](https://neon.com/docs/guides/backup-restore) allows you to recover multi-terabyte databases in seconds, without full data copies
- You can use [time travel and snapshot inspections](https://neon.com/blog/three-ways-to-use-your-snapshots) to review past database states for auditing, debugging, and incident analysis
- By [creating environments as copy-on-write branches](https://neon.com/blog/how-mindvalley-minimizes-time-to-launch-with-neon-branches), you avoid the management work and costs associated with running separate instances for development, staging, testing, or recovery
- [Programmatic lifecycle management](https://neon.com/blog/how-dispatch-speeds-up-development-with-neon-while-keeping-workloads-on-aurora) lets you create, reset, and delete large numbers of environments without eating up engineering time
- The rest of the backend scales the same way: Object Storage, Functions, and Managed Better Auth provision, branch, and scale with your project, so there's no separate system to operate at fleet size

### Multi-tenancy

- A [database-per-tenant setup](https://neon.com/use-cases/database-per-tenant) gives each customer a dedicated Neon project, providing strong isolation, eliminating noisy neighbors, and ensuring consistent performance
- [API-first tenant management](https://neon.com/blog/provision-postgres-neon-api) enables programmatic provisioning, configuration, scaling, recovery, and deletion of tenant databases, making it practical for small teams to manage thousands of tenants

### Fleet management for platforms and agents

- Instant, API-driven provisioning lets you deploy a full Neon backend, Lakebase Postgres plus the primitives you need, as part of your [platform](https://neon.com/docs/guides/embedded-postgres) or [agent](https://neon.com/docs/guides/ai-agent-integration)
- The fully embedded experience keeps Neon invisible to your end users, with no third-party logins or external configuration required as part of your product workflow
- [Scale to zero](https://neon.com/docs/introduction/scale-to-zero) keeps unit costs low when large numbers of generated apps are never used or only accessed sporadically
- A mature API exposes [fleet management and cost-control capabilities](https://neon.com/docs/guides/consumption-limits) including quotas, usage limits, and lifecycle operations
- You can build versioning, checkpoints, rollbacks, and time-travel workflows with minimal engineering effort via [snapshots](https://neon.com/blog/promoting-postgres-changes-safely-production)
- Backend primitives such as [Managed Better Auth](https://neon.com/docs/auth/overview), [Object Storage](https://neon.com/docs/storage/overview), [Functions](https://neon.com/docs/compute/functions/overview), the PostgREST-compatible [Data API](https://neon.com/docs/data-api/overview), and the [AI Gateway](https://neon.com/docs/ai-gateway/overview) let you hook up full-stack applications by default

### Realtime that doesn't explode at scale

Realtime systems famously demo well but explode at scale. Most sync engines compromise between query expressivity, latency and write throughput.

[Realtime is different](https://neon.com/docs/realtime/how-it-works). It's a live SQL system designed from the ground up for Lakebase scale. With 1:1 query expressivity with standard interactive queries, high write throughput and a design that scales with flat latency to millions of concurrent subscribers.

> **Agent Plan**
>
> If you're building a full-stack agent platform, apply to our Agent Plan for special pricing, resource limits, and assistance.
>
> [Check it out](https://neon.com/programs/agents)

--- [Document source](https://neon.com/docs/get-started/connect-neon.md) ---

> Summary: Connecting to Neon uses a standard PostgreSQL connection string retrieved from the Neon Console. Code examples cover JavaScript (Neon serverless driver, Next.js, Drizzle, Prisma), Python (psycopg2), Go, .NET, Ruby, Rust, and psql. Use a pooled connection string when your application opens many concurrent connections; use a direct connection for migrations or session-level features. Choose this page to get a working DATABASE_URL and a first query running.

# Connecting Neon to your stack

Learn how to integrate Neon into your application

Last updated: 2026-10-05

Connecting to Neon works like any Postgres database. You use a standard connection string with your language or framework of choice. This guide shows you the essentials to get connected quickly.

## Get your connection string

Click **Connect** in the Console nav to open the **Connect to your branch** modal. Select your branch, database, and role. Your connection string appears automatically.

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

The connection string includes everything you need to connect:

```text
postgresql://alex:AbC123dEf@ep-cool-darkness-a1b2c3d4.us-east-2.aws.neon.tech/dbname?sslmode=require
             ^    ^         ^                                                   ^
       role -|    |         |- hostname                                        |- database
                  |
                  |- password
```

**Note:** Neon supports both pooled and direct connections. Use a pooled connection string (with `-pooler` in the hostname) if your application creates many concurrent connections. See [Connection pooling](https://neon.com/docs/connect/connection-pooling) for details.

## Connect from your application

Use your connection string to connect from any application. Here are examples for various frameworks and languages:

**Neon serverless driver**

```javascript
// Works in Node.js, Next.js, serverless, and edge runtimes
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL);

const users = await sql`SELECT * FROM users`;
```

**Next.js**

```javascript
// Next.js example
import postgres from 'postgres';

let { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;

const conn = postgres({
  host: PGHOST,
  database: PGDATABASE,
  username: PGUSER,
  password: PGPASSWORD,
  port: 5432,
  ssl: 'require',
});

const users = await conn`SELECT * FROM users`;
```

**Drizzle**

```javascript
// Drizzle example with the Neon serverless driver
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';

const sql = neon(process.env.DATABASE_URL);

const db = drizzle(sql);

const result = await db.select().from(...);
```

**Prisma**

```javascript
// Prisma ORM 7 example with the Neon serverless driver adapter
import { PrismaNeon } from '@prisma/adapter-neon';
import { PrismaClient } from './generated/prisma'; // path set by `output` in your schema.prisma generator

const adapter = new PrismaNeon({ connectionString: process.env.DATABASE_URL });

const prisma = new PrismaClient({ adapter });
```

**Python**

```python
# Python example with psycopg2
import os
import psycopg2

# Load the environment variable
database_url = os.getenv('DATABASE_URL')

# Connect to the PostgreSQL database
conn = psycopg2.connect(database_url)

with conn.cursor() as cur:
    cur.execute("SELECT version()")
    print(cur.fetchone())

# Close the connection
conn.close()
```

**Go**

```go
// Go example
package main
import (
    "database/sql"
    "fmt"
    "log"
    "os"

    _ "github.com/lib/pq"
    "github.com/joho/godotenv"
)

func main() {
    err := godotenv.Load()
    if err != nil {
        log.Fatalf("Error loading .env file: %v", err)
    }

    connStr := os.Getenv("DATABASE_URL")
    if connStr == "" {
        panic("DATABASE_URL environment variable is not set")
    }

    db, err := sql.Open("postgres", connStr)
    if err != nil {
        panic(err)
    }
    defer db.Close()

    var version string
    if err := db.QueryRow("select version()").Scan(&version); err != nil {
        panic(err)
    }
    fmt.Printf("version=%s\n", version)
}
```

**.NET**

```csharp
# .NET example

## Connection string
"Host=ep-cool-darkness-123456.us-east-2.aws.neon.tech;Database=dbname;Username=alex;Password=AbC123dEf"

## with SSL
"Host=ep-cool-darkness-123456.us-east-2.aws.neon.tech;Database=dbname;Username=alex;Password=AbC123dEf;SSL Mode=Require;Trust Server Certificate=true"

## Entity Framework (appsettings.json)
{
  ...
  "ConnectionStrings": {
    "DefaultConnection": "Host=ep-cool-darkness-123456.us-east-2.aws.neon.tech;Database=dbname;Username=alex;Password=AbC123dEf;SSL Mode=Require;Trust Server Certificate=true"
  },
  ...
}
```

**Ruby**

```ruby
# Ruby example
require 'pg'
require 'dotenv'

# Load environment variables from .env file
Dotenv.load

# Connect to the PostgreSQL database using the environment variable
conn = PG.connect(ENV['DATABASE_URL'])

# Execute a query
conn.exec("SELECT version()") do |result|
  result.each do |row|
    puts "Result = #{row['version']}"
  end
end

# Close the connection
conn.close
```

**Rust**

```rust
// Rust example
use postgres::Client;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::error;
use std::env;
use dotenv::dotenv;

fn main() -> Result<(), Box<dyn error::Error>> {
    // Load environment variables from .env file
    dotenv().ok();

    // Get the connection string from the environment variable
    let conn_str = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());
    let mut client = Client::connect(&conn_str, connector)?;

    for row in client.query("select version()", &[])? {
        let ret: String = row.get(0);
        println!("Result = {}", ret);
    }
    Ok(())
}
```

**psql**

```bash
# psql example connection string
psql postgresql://username:password@hostname:5432/database?sslmode=require&channel_binding=require
```

Store your connection string in an environment variable (like `DATABASE_URL`) rather than hardcoding it in your application.

## Next steps

This covers the basics. For more connection options and detailed guidance:

- [Connect documentation](https://neon.com/docs/connect/connect-intro): Comprehensive guide to all connection methods, troubleshooting, and security
- [Framework guides](https://neon.com/docs/get-started/frameworks): Step-by-step guides for Next.js, Remix, Django, Rails, and more
- [Language guides](https://neon.com/docs/get-started/languages): Connection examples for JavaScript, Python, Go, Rust, and other languages
- [Serverless driver](https://neon.com/docs/serverless/serverless-driver): Connect from serverless and edge environments using HTTP or WebSockets
- [Set up Auth](https://neon.com/docs/auth/overview): Managed Better Auth that branches with your database

--- [Document source](https://neon.com/docs/get-started/dev-experience.md) ---

> Summary: Neon's developer experience rests on the lakebase architecture and four principles: invisible infra, no waiting, branching- and agents-first workflows, and a composable, open backend. Autoscaling, scale-to-zero, copy-on-write branching, instant restore, and sub-second provisioning apply across the whole backend, Lakebase Postgres plus Object Storage, Functions, Managed Better Auth, the Data API, and the AI Gateway, not just the database. It also covers config-as-code with neon.ts and API, CLI, and MCP automation for agents and platforms.

# Our DX Principles

Neon adapts to your workflow, not the other way around.

Last updated: 2026-10-08

The developer experience across Neon is rooted in the lakebase architecture and anchored around four core pillars:

1. **Invisible infra** - compute and storage adapt to your workload in real time, with no instances to size anywhere in the backend
2. **No waiting** - new environments, deployments, and restores are instant across the backend, not just the database
3. **Branching-first and agents-first workflows** - databases and backends behave like any other modern, automatable tool
4. **Composable and open** - a full backend of open primitives around Lakebase Postgres, not a locked-in all-in-one

## Invisible infra

These behaviors start with Lakebase Postgres, but they define the whole backend. The other primitives provision, scale, and branch the same way, so there's no fixed infrastructure to size or maintain anywhere in your stack.

### Autoscaling compute

Traditional OLTP databases force you to provision compute upfront (i.e., choose an instance size), plan for peak traffic, and manually adjust capacity over time. This adds overhead and leads to either overpaying for idle resources or underprovisioning and risk performance degradation.

**How it works**

Lakebase Postgres runs an autoscaling loop that continuously monitors three core database / compute metrics, then adjusts resources in near real time. The three core metrics are:

- CPU load and overall memory usage are checked every 5 seconds
- Compute cache working set size is evaluated every 20 seconds
- Memory usage inside Postgres itself is monitored every 100 milliseconds

Rather than relying on fixed intervals or manual triggers, the autoscaling algorithm continuously evaluates these three workload signals, adjusting compute up or down based on the live measurements - while always staying within the minimum and maximum limits you configure.

**What this means for DX**

You don't need to pick instance sizes when creating a Neon branch: only your max/min autoscaling limits. You also don't have to monitor load capacity to tune capacity or to schedule resizes. Autoscaling happens continuously and transparently as your application runs.

### Scale to zero

When a database is not actively handling queries, Lakebase Postgres [automatically scales compute all the way down to zero](https://neon.com/docs/introduction/scale-to-zero). Unused databases consume no compute resources, eliminating the cost of always-on instances that sit unused for large portions of the day. This happens by default after 5 minutes of inactivity, and when it's time to restart, cold starts take less than 1 second, with less than 500 milliseconds being typical.

For production workloads where cold starts are not acceptable, paid plan users can disable scale to zero to keep their compute always active. See [Scale to zero](https://neon.com/docs/introduction/scale-to-zero).

**What this means for DX**

Scale to zero is a foundational capability for the Neon experience, allowing us to offer:

- **A Free plan developers can actually use**. Neon can offer a generous Free plan without subsidizing large amounts of idle infrastructure, something made possible by the lakebase architecture and scale-to-zero capabilities. [We want every Postgres developer building on Neon](https://neon.com/blog/why-so-many-projects-in-the-neon-free-plan), and this starts with hosting their side projects and experiments.

- **Many short-lived, non-production environments**. Scale to zero makes it practical to run [large numbers of ephemeral databases](https://neon.com/use-cases/dev-test) for previews, CI runs, experiments, and testing. Teams can create and discard environments freely, without cost pressure forcing them to share databases or cut corners.

- **A foundation for platforms and AI agents operating at scale**. Full-stack apps can provision and manage thousands of isolated Neon projects programmatically, fully integrating the process within their own product experience, for example to power their own free plans. Without scale-to-zero, this would imply massive infrastructure costs upfront.

### On-demand storage

In traditional Postgres setups, storage is something you plan upfront: you estimate how much data you'll need, provision disk accordingly, and revisit that decision as your application grows. Getting this wrong leads to wasted capacity and full-disk errors. Lakebase Postgres removes this friction by making storage fully on demand.

Lakebase Postgres storage is [built on object storage](https://neon.com/docs/introduction/architecture-overview), decoupled from compute. It is reliable by design and it expands automatically as data is written, as scaling storage does not require resizing compute resources or causing downtime. You can start with a small database and grow it continuously, without ever revisiting storage sizing decisions.

**What this means for DX**

Neon developers don't estimate disk sizes or plan storage migrations. Databases grow naturally with the application, without operational intervention or downtime.

### The rest of the backend

The same principle holds beyond Postgres. [Functions](https://neon.com/docs/compute/functions/overview) run serverless, with no instances to size and nothing to keep warm. [Object Storage](https://neon.com/docs/storage/overview) has no capacity to provision. [Managed Better Auth](https://neon.com/docs/auth/overview) and the [Data API](https://neon.com/docs/data-api/overview) run as managed services on the same branch. There's no fixed infrastructure to plan for anywhere in your stack, only the workload you actually run.

## No waiting

### New deployments are fast

With Neon, deploying backends is a fast operation that takes less than a second. Creating a new project or branch does not involve provisioning a new virtual machine, eliminating minutes of provisioning time. And it's the whole backend, not just the database: Functions deploy in seconds, and a new branch inherits its parent's Object Storage buckets and configuration, so the full environment comes up together.

**What this means for DX**

This speed adapts the experience of deploying backends to the agent era. It also makes Neon a natural fit for platforms that themselves provision backends programmatically for their users, such as app generation platforms or developer platforms with their own free plans. Instance creation becomes fast enough to sit directly on the user path.

### A record of all past states, instantly accessible

Storage in Lakebase Postgres is also [history-preserving](https://neon.com/blog/get-page-at-lsn) by design. As data changes over time, past versions of your database state are retained efficiently as part of normal operation, making operations that are painfully slow in traditional backends (like restores) trivial on Neon.

**Instant restores**

In Lakebase Postgres, [Instant Restore](https://neon.com/docs/introduction/branch-restore#how-instant-restore-works) allows you to restore your database to a precise point in time in a few clicks or a single API call. Restore operations are near-instant because Lakebase Postgres doesn't copy data or rebuild the database, it simply re-anchors the database state to a known point in its history.

**Snapshots as checkpoints**

In addition to continuous history, Lakebase Postgres exposes [snapshots](https://neon.com/docs/guides/backup-restore), explicit checkpoints that capture your database state at a moment in time. Snapshots are useful when you want long-lived restore points independent of the [history window](https://neon.com/docs/introduction/history-window), a known rollback point before a risky change, or versioned checkpoints for environments or [agent workflows](https://neon.com/docs/ai/ai-database-versioning).

**What this means for DX**

When your database keeps a complete, accessible record of its past, developers can work with a fundamentally different mindset: mistakes are reversible. They iterate more confidently, knowing that mistakes can be undone quickly and precisely.

### Realtime live data

Lakebase Postgres builds live data into the database itself. With [Realtime](https://neon.com/docs/realtime/overview), you can subscribe to any SQL query and sync it into the client for end-to-end reactive DX.

## Workflows

### Branching-first

Modern software development is built around iteration, but most database setups are still built around a single mutable state. Neon takes a different approach: instead of treating a database as a static resource that must be copied over and over, Lakebase Postgres treats the database as a versioned system using short-lived [branches](https://neon.com/docs/introduction/branching).

**Always lightweight**

Whether your database is 1 GB or 1 TB, creating a branch takes seconds. Branches use a copy-on-write model, so they're instant to create regardless of database size. [Object Storage](https://neon.com/docs/storage/overview) buckets branch the same way: a new branch inherits its parent's buckets and the objects in them at the moment of forking, with nothing copied upfront.

**Designed to be discarded**

Branching is optimized for short-lived environments or for environments that get to be refreshed often. To support this, Lakebase Postgres provides [branch expiration](https://neon.com/docs/guides/branch-expiration): you can configure branches to automatically expire and be deleted after a set period of time. You can also [reset a branch](https://neon.com/docs/guides/reset-from-parent) to the latest state of its parent instantly, with one click or API call, whenever you need a new starting point.

You can build your branching workflows using the [Neon CLI](https://neon.com/docs/cli), [Neon API](https://neon.com/docs/reference/api), or [GitHub Actions](https://neon.com/docs/guides/branching-github-actions). You can also keep your development branches up-to-date by resetting your schema and data to the latest from `main` with a simple command.

**What this means for DX**

Teams deploy hundreds of branches as temporary, task-specific environments, substituting heavy and expensive dev instances. Some [common patterns](https://neon.com/branching) include:

- **Branch per developer**. Each engineer works against their own isolated backend environment (a branch), avoiding conflicts when making schema or data changes.
- **Branch per experiment or feature**. Short-lived branches are used to explore changes, run migrations, or validate ideas, then deleted once the work is done.
- **Branch per pull request**. A new branch is created automatically for every PR, powering preview deployments with production-like data.
- **Branch per CI run**. Test suites run against a fresh database branch, ensuring clean state and reproducible results for every pipeline run.

### Agents-first

On Neon, agents are first-class: the same lakebase architecture that makes Lakebase Postgres instant, branchable, and serverless also makes the full backend operable by software, not only by humans in a console. Agents, coding assistants, and [codegen platforms](https://neon.com/use-cases/ai-agents) can provision, branch, query, and tear down backends the way they already manage code and deploys.

That depends on the architecture and the API working together.

**Lakebase architecture**

The lakebase architecture removes the friction that usually blocks automation:

- Projects and branches come up in under a second
- Scale to zero keeps fleets of mostly idle databases economical
- Copy-on-write branching gives agents isolated environments, versioning, checkpoints, and rollbacks without copying data
- History makes mistakes reversible

Those properties let an agent spin up hundreds of short-lived backends without blowing up cost or waiting on infrastructure.

**Full API readiness**

Every core operation in Neon is available programmatically:

- The [Neon API](https://neon.com/docs/reference/api) is shaped by real-world agent and platform workloads: create and manage hundreds of thousands of projects, automate lifecycles with minimal human intervention, and enforce usage limits and cost controls (compute uptime, autoscaling bounds, data written, storage per branch, and more)
- The [Neon CLI](https://neon.com/docs/cli), GitHub Actions, Vercel preview branching, MCP, and Agent Skills all sit on that same surface, so humans and agents share one control plane

**How agents use Neon**

- **In the IDE.** [MCP](https://neon.com/docs/ai/neon-mcp-server) and [Agent Skills](https://neon.com/docs/ai/agent-skills) let tools like Cursor and Claude understand and operate a Neon project in a structured, safe way.
- **As the backend for agent platforms.** [Full-stack codegen and agent platforms](https://neon.com/platforms) embed Lakebase Postgres (and the rest of the Neon primitives) so each generated app gets its own backend, provisioned and cleaned up automatically.
- **In your own pipelines.** Scripts and agents call the same API humans use in CI: create a branch, run migrations, take a snapshot, delete when done.

**What this means for DX**

Backend workflows stop being the exception you still have to manage manually. Developers can delegate them to coding agents, and agent platforms can treat Neon as infrastructure they drive end to end - with the lakebase architecture keeping that automation fast and affordable.

### Config as code

Your backend's configuration can live in code, not just in the console. A [`neon.ts`](https://neon.com/docs/reference/neon-ts) policy declares a branch's shape in one typed file: compute and lifecycle settings, Managed Better Auth and the Data API, Object Storage buckets, and Functions. [`neon config plan`](https://neon.com/docs/cli/config) previews the diff against a branch's live state and [`neon deploy`](https://neon.com/docs/cli/deploy) reconciles it, following the same inspect-plan-apply model as Terraform.

**What this means for DX**

Backend configuration is reviewed in pull requests, reproduced exactly across branches, and applied by the same CI that builds your app. A preview branch can be brought up to a known-good backend in one command, and agents can manage that configuration as code alongside the application.

## Composable and open

Neon is a complete set of cloud backend primitives built around Lakebase Postgres: Managed Better Auth, Object Storage, Functions, Data API, and AI Gateway. It gives you a full backend for apps and agents as open, composable pieces on open standards, rather than an all-in-one where every layer is proprietary and inseparable.

At the center is [Lakebase Postgres](https://neon.com/docs/get-started/why-neon). Around it, optional primitives cover the rest of a modern backend:

- [Managed Better Auth](https://neon.com/docs/auth/overview) for authentication and identity in Postgres
- [Object Storage](https://neon.com/docs/storage/overview) for S3-compatible files and blobs
- [Functions](https://neon.com/docs/compute/functions/overview) for long-running compute next to your data
- [Data API](https://neon.com/docs/data-api/overview) for HTTP access to your database
- [AI Gateway](https://neon.com/docs/ai-gateway/overview) for model access with one credential

You can adopt only what you need, swap pieces for your own providers, and keep the rest of your stack (frameworks, hosts, ORMs, AI tools) unchanged. Nothing requires a Neon-only workflow.

What ties the stack together is the [lakebase architecture](https://neon.com/docs/introduction/architecture-overview). Every service is designed to carry the same properties developers get from Lakebase Postgres: instant provisioning, branching, scale to zero, and serverless operation. The backend stays agent-ready and environment-friendly end to end.

**What this means for DX**

You get a backend that is complete when you want it to be, and modular when you don't. Start with Lakebase Postgres alone, add primitives as you need them, and keep architectures flexible instead of committing to a locked-in stack.

## Build without friction

Neon is designed to remove friction from backend workflows without constraining how you build. Our users tell us the best thing about Neon is that building feels intuitive, and that they forget the backend is even there. That's exactly the goal. When the backend stops getting in the way, teams can move faster, experiment safely, and focus on shipping.

--- [Document source](https://neon.com/docs/get-started/frameworks.md) ---

> Summary: Framework integration index for Neon serverless Postgres, linking per-framework connection guides for Node.js, Next.js, Django, Laravel, Ruby on Rails, SvelteKit, Remix, and many others. Several frameworks (Next.js, React, TanStack Router) also support Managed Better Auth, managed authentication that branches with your database. Use this page to find the right framework-specific guide rather than a generic Postgres connection walkthrough.

# Neon framework guides

Find detailed instructions for connecting to Neon from various frameworks

Last updated: 2026-07-15

Several frameworks support [Managed Better Auth](https://neon.com/docs/auth/overview), managed authentication stored in your database that **branches with your data**. Quick starts are available for [Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only), [React](https://neon.com/docs/auth/quick-start/react), and [TanStack Router](https://neon.com/docs/auth/quick-start/tanstack-router).

- [Node.js](https://neon.com/docs/guides/node): Connect a Node.js application to Neon
- [Next.js](https://neon.com/docs/guides/nextjs): Connect a Next.js application to Neon. Managed Better Auth supported.
- [NestJS](https://neon.com/docs/guides/nestjs): Connect a NestJS application to Neon
- [Astro](https://neon.com/docs/guides/astro): Connect an Astro site or app to Neon
- [Django](https://neon.com/docs/guides/django): Connect a Django application to Neon
- [Encore](https://neon.com/docs/guides/encore): Connect an Encore application to Neon
- [Entity Framework](https://neon.com/docs/guides/dotnet-entity-framework): Connect a Dotnet Entity Framework application to Neon
- [Express](https://neon.com/docs/guides/express): Connect an Express application to Neon
- [Hono](https://neon.com/docs/guides/hono): Connect a Hono application to Neon
- [Laravel](https://neon.com/docs/guides/laravel): Connect a Laravel application to Neon
- [Medusa.js](https://neon.com/docs/guides/medusajs): Use Medusa.js with Neon
- [Micronaut Kotlin](https://neon.com/docs/guides/micronaut-kotlin): Connect a Micronaut Kotlin application to Neon
- [Nuxt](https://neon.com/docs/guides/nuxt): Connect a Nuxt application to Neon
- [OAuth](https://neon.com/docs/guides/oauth-integration): Integrate with Neon using OAuth
- [Phoenix](https://neon.com/docs/guides/phoenix): Connect a Phoenix site or app to Neon
- [Quarkus](https://neon.com/docs/guides/quarkus-jdbc): Connect Quarkus (JDBC) to Neon
- [Quarkus](https://neon.com/docs/guides/quarkus-reactive): Connect Quarkus (Reactive) to Neon
- [React](https://neon.com/docs/guides/react): Connect a React application to Neon
- [RedwoodSDK](https://neon.com/docs/guides/redwoodsdk): Connect a RedwoodSDK application to Neon
- [Reflex](https://neon.com/docs/guides/reflex): Build Python Apps with Reflex and Neon
- [Remix](https://neon.com/docs/guides/remix): Connect a Remix application to Neon
- [Ruby on Rails](https://neon.com/docs/guides/ruby-on-rails): Connect a Ruby on Rails application to Neon
- [Symfony](https://neon.com/docs/guides/symfony): Connect from Symfony with Doctrine to Neon
- [SolidStart](https://neon.com/docs/guides/solid-start): Connect a SolidStart site or app to Neon
- [SQLAlchemy](https://neon.com/docs/guides/sqlalchemy): Connect a SQLAlchemy application to Neon
- [Sveltekit](https://neon.com/docs/guides/sveltekit): Connect a Sveltekit application to Neon
- [TanStack Start](https://neon.com/docs/guides/tanstack-start): Connect a TanStack Start application to Neon. Managed Better Auth supported.
- [Vue](https://neon.com/docs/guides/vue): Connect a Vue.js application to Neon

--- [Document source](https://neon.com/docs/get-started/full-backend-quickstart.md) ---

> Summary: End-to-end Next.js App Router tutorial that wires Lakebase Postgres on Neon, Drizzle ORM, Object Storage, and a Neon Function into a working backend, all declared in one neon.ts and provisioned with neon deploy. The function runs a streaming, tool-calling AI assistant on compute next to your database. Choose this page when building a Next.js project that needs a type-safe Postgres data layer plus serverless storage and long-running AI, without stitching together separate providers.

# Build a full backend with Next.js and Neon

Postgres, Object Storage, and a Neon Function for AI, declared in one neon.ts

Last updated: 2026-10-09

## Before you start

You'll need [Node.js 20.19+](https://nodejs.org/) and the [Neon CLI](https://neon.com/docs/cli/install) installed:

```bash
npm i -g neon
```

**Important: Create your project in a supported region**

Object Storage, Functions, and the AI Gateway are currently available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`), on new or existing projects in those regions, so use a project in one of them to follow this guide. Support is expanding toward [all regions](https://neon.com/docs/introduction/regions). Postgres works in any region. Object Storage and Functions work on any plan, subject to usage limits; the AI Gateway works on any plan with prepaid credits.

## Create a Neon project

If you don't have a Neon account, sign up at [console.neon.tech](https://console.neon.tech/signup).

Create your project in **AWS US East (Ohio)**, **US East (N. Virginia)**, **Europe (Frankfurt)**, or **Asia Pacific (Singapore)**. Any path below works; the rest of this guide uses the Neon CLI, which you'll also use in step 3 to link the project and pull its credentials automatically.

**Neon CLI**

Sign in and create the project:

```bash filename="Terminal"
neon login
neon projects create --name my-backend --region-id aws-us-east-2
```

**API**

Create an [API key](https://console.neon.tech/app/settings/api-keys), export it, then create the project:

```bash filename="Terminal"
export NEON_API_KEY=neon_...

curl -X POST https://console.neon.tech/api/v2/projects \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project": {"name": "my-backend", "region_id": "aws-us-east-2"}}'
```

**Console**

In the Neon Console, click **New Project**, name it `my-backend`, and select the **AWS US East (Ohio)** region.

## Scaffold a Next.js app

Create a new Next.js project with TypeScript, Tailwind CSS, and the App Router. The `--yes` flag accepts the remaining defaults without prompting.

```bash filename="Terminal"
npx create-next-app@latest my-backend --typescript --tailwind --app --eslint --yes
cd my-backend
```

## Declare your backend in neon.ts

A single [`neon.ts`](https://neon.com/docs/reference/neon-ts) file declares your backend as code. You enable a capability there, run [`neon deploy`](https://neon.com/docs/cli/deploy), and Neon provisions it and writes its credentials into `.env.local`. You'll grow this file as you add capabilities.

Work through the commands on the right:

1. `neon link` connects the directory to your project (writing a `.neon` file); `neon checkout` then pins the branch and pulls its env vars, including `DATABASE_URL`, into `.env.local`. If you haven't signed in to the CLI yet, run `neon login` first. Run interactively, `neon link` prompts you to create `neon.ts`; the `--no-config` flag skips that prompt so the explicit `neon config init` in step 2 stays in control.
2. `neon config init` scaffolds `neon.ts` and installs `@neon/config` and `@neon/env`. It includes a branch policy; keep it and add the service keys shown in later steps alongside it (those snippets omit the policy for brevity).

Postgres is already available on the branch, so `DATABASE_URL` is in `.env.local` and you can build the data layer before adding the other services.

```bash filename="Terminal"
neon link --no-config  # select the my-backend project; skip link's neon.ts prompt
neon checkout main     # pin the branch, pull env vars into .env.local
neon config init       # scaffold neon.ts, install @neon/config and @neon/env
```

## Install dependencies

Install `drizzle-orm` for typed queries and `@neondatabase/serverless` for the HTTP driver (works in Node, edge, and serverless runtimes). Add `drizzle-kit` as a dev dependency for the schema migration.

```bash filename="Terminal"
npm install drizzle-orm @neondatabase/serverless
npm install -D drizzle-kit
```

## Define your schema

Create a TypeScript schema for a `posts` table. This example uses Drizzle for schema management, but you can use any ORM or migration tool. Drizzle uses this schema for both the migration and your type-safe queries. Each post has an `author` so you can tell them apart; this app is single-user, so the author defaults to `anonymous`.

```typescript filename="lib/db/schema.ts"
import { bigint, boolean, pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const posts = pgTable('posts', {
  id: bigint('id', { mode: 'number' })
    .primaryKey()
    .generatedByDefaultAsIdentity(),
  author: text('author').notNull().default('anonymous'),
  content: text('content').notNull(),
  isPublished: boolean('is_published').notNull().default(false),
  createdAt: timestamp('created_at', { withTimezone: true })
    .notNull()
    .defaultNow(),
});
```

```typescript filename="drizzle.config.ts"
import { loadEnvConfig } from '@next/env';
import { defineConfig } from 'drizzle-kit';

loadEnvConfig(process.cwd());

export default defineConfig({
  schema: './lib/db/schema.ts',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});
```

`drizzle-kit` is a standalone CLI and doesn't read `.env.local` automatically. `loadEnvConfig` matches Next.js's env loading behavior so the migration step picks up the same `DATABASE_URL` as the app.

## Push the schema and seed sample data

This example uses Drizzle's CLI to apply the schema, but you can use your ORM or migration tool's equivalent command. `drizzle-kit push` creates the table directly from your schema. In production, you'd typically use `drizzle-kit generate` and `drizzle-kit migrate` for tracked migrations, but push is faster for a tutorial.

Then seed three sample posts in the [Neon Console SQL Editor](https://console.neon.tech): two published and one draft, so the `where(eq(posts.isPublished, true))` filter on the posts page has something visible to do.

```bash filename="Terminal"
npx drizzle-kit push
```

Open your project in the Neon Console, go to **Postgres database** > **SQL Editor**, and run:

```sql
INSERT INTO posts (author, content, is_published) VALUES
  ('Dana Smith', 'Postgres branching lets you copy your whole database in seconds.', true),
  ('Alex Lopez', 'Serverless compute scales to zero when idle, so you only pay for what you use.', true),
  ('anonymous', 'This draft is hidden. Flip is_published to true in the SQL editor to see it appear.', false);
```

## List posts in a Server Component

Create the Drizzle client and a `/posts` page. The page is a Server Component, so the Drizzle query runs on the server at request time. `dynamic = 'force-dynamic'` keeps the data fresh on every request.

```typescript filename="lib/db/client.ts"
import { drizzle } from 'drizzle-orm/neon-http';
import { neon } from '@neondatabase/serverless';
import * as schema from './schema';

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql, { schema });
```

```tsx filename="app/posts/page.tsx"
import { db } from '@/lib/db/client';
import { posts } from '@/lib/db/schema';
import { desc, eq } from 'drizzle-orm';

export const dynamic = 'force-dynamic';

export default async function PostsPage() {
  const allPosts = await db
    .select()
    .from(posts)
    .where(eq(posts.isPublished, true))
    .orderBy(desc(posts.createdAt))
    .limit(10);

  return (
    <main className="p-8">
      <h1 className="mb-4 text-2xl font-bold">Published posts</h1>
      <ul className="space-y-2">
        {allPosts.map((post) => (
          <li key={post.id} className="rounded border p-3">
            <p>{post.content}</p>
            <p className="mt-1 text-xs text-gray-500">by {post.author}</p>
          </li>
        ))}
      </ul>
    </main>
  );
}
```

## Add Object Storage and upload images

Add an `images` bucket to your `neon.ts` and run `neon deploy`. Neon provisions the bucket and injects the S3-compatible credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, `AWS_REGION`) into `.env.local`.

Then add a client upload page that submits the file to a Server Action. The [Files SDK](https://files-sdk.dev) `neon` adapter reads the injected `AWS_*` variables and configures the endpoint for you, so there's no client setup.

The action returns the object's public URL. In a real app you'd store that URL on a row, for example an `image_url` column on `posts`, so a record can reference its file. This step keeps the upload standalone to focus on the storage flow.

**Note:** `neon deploy` merges credentials into `.env.local` without discarding your own entries.

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

export default defineConfig({
  // branch policy omitted for brevity; keep the one from `neon config init`
  buckets: {
    images: { access: 'public_read' },
  },
});
```

```bash filename="Terminal"
neon deploy
npm install files-sdk @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner @aws-sdk/s3-presigned-post
```

```typescript filename="app/upload/actions.ts"
'use server';

import { Files } from 'files-sdk';
import { neon } from 'files-sdk/neon';

const files = new Files({ adapter: neon({ bucket: 'images' }) });

export async function uploadImage(
  _prev: { error?: string; publicUrl?: string } | null,
  formData: FormData,
) {
  const file = formData.get('file') as File | null;
  if (!file) return { error: 'No file selected' };

  const bytes = new Uint8Array(await file.arrayBuffer());
  const key = `${Date.now()}-${file.name}`;

  await files.upload(key, bytes, { contentType: file.type });

  // The images bucket is public_read, so the object is served directly.
  const publicUrl = `${process.env.AWS_ENDPOINT_URL_S3}/images/${key}`;
  return { publicUrl };
}
```

```tsx filename="app/upload/page.tsx"
'use client';

import { useActionState } from 'react';
import { uploadImage } from './actions';

export default function UploadPage() {
  const [state, formAction, isPending] = useActionState(uploadImage, null);

  return (
    <main className="p-8">
      <h1 className="mb-4 text-2xl font-bold">Upload an image</h1>
      <form action={formAction} className="mb-4">
        <input name="file" type="file" accept="image/*" required />
        <button
          type="submit"
          disabled={isPending}
          className="mt-3 rounded-md bg-indigo-500 px-3 py-1.5 text-sm font-semibold text-white disabled:opacity-50"
        >
          {isPending ? 'Uploading...' : 'Upload'}
        </button>
      </form>
      {state?.error && <p className="text-sm text-red-500">{state.error}</p>}
      {state?.publicUrl && (
        <p className="text-sm text-gray-500 break-all">Uploaded: {state.publicUrl}</p>
      )}
    </main>
  );
}
```

## Write the Neon Function

Now add the piece that makes this a full backend: a [Neon Function](https://neon.com/docs/compute/functions/overview) that runs AI on long-lived compute next to your database. It's a normal [Hono](https://hono.dev) app with two routes:

- `POST /generate` writes a post from a topic with the [AI Gateway](https://neon.com/docs/ai-gateway/overview).
- `POST /assistant` streams a tool-calling assistant that answers questions about your posts. The tool loop queries Postgres and runs in-process, so it isn't cut off by a serverless request limit.

Install the function's dependencies, then create `functions/posts.ts`.

**Note: Connect with a pooled `pg` client**

A function keeps running across requests, so open a `pg` `Pool` once at module scope and reuse it. Don't use `@neondatabase/serverless` inside a function; it's built for short-lived, per-request invocations. See [Connecting to Postgres](https://neon.com/docs/compute/functions/get-started#connect-to-postgres).

```bash filename="Terminal"
npm install hono pg ai@^7 @neon/ai-sdk-provider @neon/functions zod
npm install -D @types/pg
```

```typescript filename="functions/posts.ts"
import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { attachDatabasePool } from '@neon/functions';
import { Pool } from 'pg';
import { neon } from '@neon/ai-sdk-provider';
import { streamText, generateText, convertToModelMessages, tool, stepCountIs } from 'ai';
import { z } from 'zod';

// Reused across requests. Use a pooled pg client, not the serverless driver.
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
// Keep an idle disconnect from crashing the isolate.
attachDatabasePool(pool);

const app = new Hono();

// The assistant is called from the browser, so allow cross-origin requests.
app.use('/*', cors());

// One-shot generation: create a post from a topic and save it.
app.post('/generate', async (c) => {
  const { topic, author = 'anonymous' } = await c.req.json();

  const { text } = await generateText({
    // Open-weight models are enabled by default. Frontier models (for example OpenAI GPT) need access requested in the Console first.
    model: neon('gpt-oss-20b'),
    prompt: `Write a 2 sentence post about the following topic. Just send the post content without any additional text: ${topic}`,
  });

  const { rows } = await pool.query(
    'insert into posts (author, content, is_published) values ($1, $2, true) returning *',
    [author, text],
  );

  return c.json(rows[0]);
});

// Streaming assistant: answers questions about the posts, using a tool that
// queries Postgres. The tool loop runs in-process on Neon compute.
app.post('/assistant', async (c) => {
  const { messages } = await c.req.json();

  const result = streamText({
    model: neon('meta-llama-3-3-70b-instruct'),
    system:
      "You are a helpful assistant that answers questions about the user's blog posts. Use the queryPosts tool to look them up.",
    messages: await convertToModelMessages(messages),
    tools: {
      queryPosts: tool({
        description: 'Fetch the most recent published posts from the database.',
        inputSchema: z.object({
          limit: z.number().default(10).describe('How many posts to fetch.'),
        }),
        execute: async ({ limit }) => {
          // Cast created_at to text: a raw Date in the tool result fails the AI SDK
          // message schema when the result is fed back to the model on the next step.
          const { rows } = await pool.query(
            'select author, content, created_at::text from posts where is_published = true order by created_at desc limit $1',
            [limit],
          );
          return rows;
        },
      }),
    },
    stopWhen: stepCountIs(5),
    // Disable telemetry: the function runtime's tracing conflicts with the
    // AI SDK's streaming spans.
    experimental_telemetry: { isEnabled: false },
  });

  return result.toUIMessageStreamResponse();
});

export default app;
```

## Deploy the function

Declare the function and the AI Gateway in `neon.ts`, then `neon deploy`. Neon builds the function, gives it a public URL, and injects the AI Gateway credentials (`NEON_AI_GATEWAY_TOKEN`, `NEON_AI_GATEWAY_BASE_URL`) so the `@neon/ai-sdk-provider` inside the function needs no configuration.

Copy the `URL` from the `neon functions get posts` output into `.env.local` as `NEXT_PUBLIC_POSTS_FN_URL` (the `NEXT_PUBLIC_` prefix exposes it to the browser, which calls the assistant directly). `NEXT_PUBLIC_` variables are read at build time, so restart the dev server if it's already running.

A Neon Function has its own URL, so the browser calls it directly. That keeps a long stream off your host's serverless timeout.

**Note: First call after a deploy**

The first AI Gateway call on a new branch can return a `403` while the credential propagates. It clears within a few seconds, so retry.

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

export default defineConfig({
  // branch policy omitted for brevity; keep the one from `neon config init`
  aiGateway: true,
  buckets: {
    images: { access: 'public_read' },
  },
  functions: {
    posts: { name: 'posts assistant', source: './functions/posts.ts' },
  },
});
```

```bash filename="Terminal"
neon deploy
neon functions get posts   # prints the function URL
```

```
Function
Slug        posts
Name        posts assistant
URL         https://<branch_id>-posts.compute.<cell>.us-east-2.aws.neon.tech/
```

```bash filename=".env.local"
NEXT_PUBLIC_POSTS_FN_URL=https://<branch_id>-posts.compute.<cell>.us-east-2.aws.neon.tech/
```

## Call the function from your app

Wire two pages to the function:

- `/generate` calls `POST /generate` from a Server Action (server-to-server, so no CORS). Good for a short, one-shot generation.
- `/assistant` streams from `POST /assistant` directly in the browser with the AI SDK's `useChat` hook. Calling the function directly keeps the stream off any serverless host that would time it out.

```bash filename="Terminal"
npm install @ai-sdk/react
```

**Note: Authenticate the function in production**

The function has a public URL and no auth check, which is fine for this tutorial. Before shipping, gate it with an API key or a JWT. See [Neon Functions authentication](https://neon.com/docs/compute/functions/authentication).

```typescript filename="app/generate/actions.ts"
'use server';

export async function generatePost(
  _prev: { error?: string; content?: string } | null,
  formData: FormData,
) {
  const topic = formData.get('topic') as string;

  const res = await fetch(`${process.env.NEXT_PUBLIC_POSTS_FN_URL}generate`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ topic, author: 'anonymous' }),
  });

  if (!res.ok) return { error: 'Generation failed' };
  const post = await res.json();
  return { content: post.content as string };
}
```

```tsx filename="app/generate/page.tsx"
'use client';

import { useActionState } from 'react';
import { generatePost } from './actions';

export default function GeneratePage() {
  const [state, formAction, isPending] = useActionState(generatePost, null);

  return (
    <main className="p-8">
      <h1 className="mb-4 text-2xl font-bold">Generate a post</h1>
      <form action={formAction} className="mb-4 flex gap-2">
        <input name="topic" placeholder="Topic" required className="rounded border px-2 py-1" />
        <button
          type="submit"
          disabled={isPending}
          className="rounded-md bg-indigo-500 px-3 py-1.5 text-sm font-semibold text-white"
        >
          {isPending ? 'Generating...' : 'Generate'}
        </button>
      </form>
      {state?.error && <p className="text-sm text-red-500">{state.error}</p>}
      {state?.content && <p className="rounded border p-3">{state.content}</p>}
    </main>
  );
}
```

```tsx filename="app/assistant/page.tsx"
'use client';

import { useChat } from '@ai-sdk/react';
import { DefaultChatTransport } from 'ai';
import { useState } from 'react';

export default function AssistantPage() {
  const [input, setInput] = useState('');
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({
      api: `${process.env.NEXT_PUBLIC_POSTS_FN_URL}assistant`,
    }),
  });

  return (
    <main className="p-8">
      <h1 className="mb-4 text-2xl font-bold">Ask about your posts</h1>
      <div className="mb-4 space-y-2">
        {messages.map((m) => (
          <div key={m.id} className="rounded border p-3">
            <span className="font-medium">{m.role}: </span>
            {m.parts.map((p, i) => (p.type === 'text' ? <span key={i}>{p.text}</span> : null))}
          </div>
        ))}
      </div>
      <form
        onSubmit={(e) => {
          e.preventDefault();
          if (input.trim()) {
            sendMessage({ text: input });
            setInput('');
          }
        }}
        className="flex gap-2"
      >
        <input
          value={input}
          onChange={(e) => setInput(e.target.value)}
          placeholder="Ask about your posts"
          className="flex-1 rounded border px-2 py-1"
        />
        <button
          type="submit"
          disabled={status !== 'ready'}
          className="rounded-md bg-indigo-500 px-3 py-1.5 text-sm font-semibold text-white"
        >
          Send
        </button>
      </form>
    </main>
  );
}
```

## Run the app

Start the dev server, then open the URL it prints. Try each page:

- `/posts` lists the seeded posts.
- `/generate` generates a post and saves it.
- `/assistant` chats about your posts, streaming from the function.
- `/upload` uploads an image to your bucket.

To iterate on the function locally, run [`neon dev`](https://neon.com/docs/cli/dev), which serves it with the same injected Neon variables it gets in production.

```bash filename="Terminal"
npm run dev
```

## Add Function Triggers

Your app calls the function on request. A [Function Trigger](https://neon.com/docs/compute/functions/triggers/overview) lets Neon call it for you, so work runs on a schedule or on an event, even when the compute is scaled to zero. Add two, both pointing at the same `posts` function:

- A **schedule** trigger writes a post every day, like a cron job.
- A **`storage_object_created`** trigger runs when an image is uploaded to your `images` bucket.

The function has no root route, so each trigger targets its own path (`/daily`, `/on-upload`) that matches a new route. Neon sends a `POST` with a JSON envelope; each handler reads what it needs from `data` and checks the `X-Neon-Trigger-Invocation-Id` header to confirm the call came from Neon. See the [overview](https://neon.com/docs/compute/functions/triggers/overview) for the payload and branching behavior, and [Schedule a function](https://neon.com/docs/compute/functions/triggers/schedule) for cron syntax.

Add two routes to `functions/posts.ts`, before `export default app`:

```typescript filename="functions/posts.ts"
// Schedule trigger: generate and publish a post. Reuses the pool and model above.
app.post('/daily', async (c) => {
  if (!c.req.header('x-neon-trigger-invocation-id')) return c.json({ error: 'not a trigger call' }, 403);

  const { text } = await generateText({
    model: neon('kimi-k3'),
    prompt: 'Write a 2 sentence post sharing a Postgres tip. Send only the post content.',
  });
  await pool.query(
    'insert into posts (author, content, is_published) values ($1, $2, true)',
    ['scheduler', text],
  );
  return c.json({ ok: true });
});

// Object-storage trigger: runs when an image is uploaded.
app.post('/on-upload', async (c) => {
  if (!c.req.header('x-neon-trigger-invocation-id')) return c.json({ error: 'not a trigger call' }, 403);

  const { data } = await c.req.json();
  console.log(`image uploaded: ${data.bucket_name}/${data.object_key}`);
  return c.json({ ok: true });
});
```

Declare both triggers in `neon.ts`:

```typescript filename="neon.ts"
// add to your existing defineConfig({ ... })
triggers: {
  'daily-post': { type: 'schedule', function: 'posts', cron: '0 9 * * *', functionPath: '/daily' },
  'on-upload': { type: 'storage_object_created', function: 'posts', bucket: 'images', functionPath: '/on-upload' },
},
```

Deploy, then read the function logs:

```bash filename="Terminal"
neon deploy
neon logs query --source function
```

The upload trigger fires right away, so upload an image through `/upload` and watch the log line. The scheduled post runs at the next 09:00 UTC; set the cron to `* * * * *` to see it sooner. To stop the daily post, set `enabled: false` in `neon.ts` and redeploy, or manage it from the Console, CLI, or API.

## What you built

You now have a Next.js app where:

- Published posts are queried server-side via Drizzle with full TypeScript types
- Images upload to a Neon Storage bucket through a Server Action and the Files SDK
- A Neon Function generates posts and runs a streaming, tool-calling AI assistant on compute next to your database
- The whole backend is declared in one `neon.ts` and provisioned with `neon deploy`, which injects every credential into `.env.local`
- The Next.js app deploys to any App Router host that supports server actions, including Vercel, Netlify, and self-hosted Node, while the long-running AI lives on the Neon Function
- Scheduled and event-driven work run as the same function code through Function Triggers, with no scheduler or queue to operate

## Next steps

- **Make it multi-user with Managed Better Auth:** add [`auth: true`](https://neon.com/docs/reference/neon-ts) to `neon.ts` for [Managed Better Auth](https://neon.com/docs/auth/overview), gate the pages with a session, and verify the caller's JWT inside the function ([Neon Functions authentication](https://neon.com/docs/compute/functions/authentication)). See the [Auth quickstart](https://neon.com/docs/auth/quick-start/nextjs-api-only).
- **Go deeper on Functions:** hold open [WebSockets and SSE](https://neon.com/docs/compute/functions/websockets) or build a fuller [AI agent](https://neon.com/docs/compute/functions/agents) on the same function.
- **Branch your whole backend:** [`neon checkout`](https://neon.com/docs/cli/checkout) forks the database, buckets, and function together for preview environments. See [Branching](https://neon.com/docs/introduction/branching).
- **Generated migrations:** for tracked schema changes, switch from a direct push to generated migrations. If you're using Drizzle, that means moving from `drizzle-kit push` to [`drizzle-kit generate`](https://orm.drizzle.team/docs/migrations); other ORMs and migration tools offer an equivalent.
- **Run work on a schedule or an event:** the [Function Triggers overview](https://neon.com/docs/compute/functions/triggers/overview) covers cron syntax, object-key prefixes, and how triggers branch with your project.

--- [Document source](https://neon.com/docs/get-started/languages.md) ---

> Summary: Language connection guides for Neon provide step-by-step instructions for connecting to a Lakebase Postgres database from .NET (C#), Elixir, Go, Java, Kotlin, JavaScript, Python, and Rust. Use this page to find the correct driver, connection string format, and configuration for your language before connecting to Neon for the first time.

# Neon language guides

Find detailed instructions for connecting to Neon from various languages

Last updated: 2026-07-31

- [.NET](https://neon.com/docs/guides/dotnet-npgsql): Connect a .NET (C#) application to Neon
- [Elixir](https://neon.com/docs/guides/elixir): Connect an Elixir application to Neon
- [Go](https://neon.com/docs/guides/go): Connect a Go application to Neon
- [Java](https://neon.com/docs/guides/java): Connect a Java application to Neon
- [Kotlin](https://neon.com/docs/guides/kotlin): Connect a Kotlin application to Neon
- [JavaScript](https://neon.com/docs/guides/javascript): Connect a JavaScript application to Neon
- [Python](https://neon.com/docs/guides/python): Connect a Python application to Neon
- [Rust](https://neon.com/docs/guides/rust): Connect a Rust application to Neon

--- [Document source](https://neon.com/docs/get-started/orms.md) ---

> Summary: ORM integration guides for Lakebase Postgres, with per-ORM connection instructions for Django, Drizzle, Elixir Ecto, Kysely, Laravel, Prisma, Rails, SQLAlchemy, Tortoise ORM, and TypeORM. Use this page to find the right guide for your framework when connecting an ORM-backed application to your Lakebase Postgres database.

# Neon ORM guides

Find detailed instructions for connecting to Neon from various ORMs

Last updated: 2026-07-31

- [Django](https://neon.com/docs/guides/django): Connect a Django application to Neon
- [Drizzle](https://neon.com/docs/guides/drizzle): Learn how to use Drizzle ORM with your Lakebase Postgres database (Drizzle docs)
- [Elixir Ecto](https://neon.com/docs/guides/elixir-ecto): Connect from Elixir with Ecto to Neon
- [Kysely](https://neon.com/docs/guides/kysely): Learn how to connect from Kysely to your Lakebase Postgres database
- [Laravel](https://neon.com/docs/guides/laravel): Connect a Laravel application to Neon
- [Prisma](https://neon.com/docs/guides/prisma): Learn how to connect from Prisma ORM to your Lakebase Postgres database
- [Rails](https://neon.com/docs/guides/ruby-on-rails): Connect a Rails application to Neon
- [SQLAlchemy](https://neon.com/docs/guides/sqlalchemy): Connect a SQLAlchemy application to Neon
- [Tortoise ORM](https://neon.com/docs/guides/tortoise-orm): Connect a Tortoise ORM application to Neon
- [TypeORM](https://neon.com/docs/guides/typeorm): Connect a TypeORM application to Neon
- [Better Drizzle](https://neon.com/docs/guides/better-drizzle): Connect a Better Drizzle application to Neon

--- [Document source](https://neon.com/docs/get-started/production-checklist.md) ---

> Summary: A production readiness checklist for Lakebase Postgres on Neon covering plan selection, region placement, autoscaling limits, branch protection, and connection pooling. Use this page when moving a Neon project out of development. It covers scale-to-zero tradeoffs, instant restore history windows, snapshot schedules, IP Allow, pg_stat_statements for query monitoring, and metric exports to Datadog, Grafana, or any OTEL-compatible platform.

# Getting ready for production

Guidelines to optimize price, performance, and reliability

Last updated: 2026-11-05

## Production checklist

- [ ] [1. Use a paid plan for production workloads](https://neon.com/docs/get-started/production-checklist#use-a-paid-plan-for-production-workloads)
    Paid plans are usage-based, so your app won't stop or be limited as it grows. The Free plan includes compute hour limits, making it better suited for prototyping.
- [ ] [2. Choose a region close to your application](https://neon.com/docs/get-started/production-checklist#choose-a-region-close-to-your-application)
    Deploy your Neon project in the nearest available region to your application to minimize network latency.
- [ ] [3. Keep your production branch as the default](https://neon.com/docs/get-started/production-checklist#keep-your-production-branch-as-the-default)
    Your production branch should be a root branch set as the default to ensure compute availability, enable snapshots, and simplify billing.
- [ ] [4. Protect your production branch](https://neon.com/docs/get-started/production-checklist#protect-your-production-branch)
    Mark production branches as protected to prevent accidental resets or destructive operations.
- [ ] [5. Enable autoscaling and set appropriate limits](https://neon.com/docs/get-started/production-checklist#enable-autoscaling-and-set-appropriate-limits)
    Autoscaling lets your database handle traffic spikes automatically. Set limits that balance performance with cost.
- [ ] [6. Decide whether scale-to-zero is acceptable](https://neon.com/docs/get-started/production-checklist#decide-whether-scale-to-zero-is-acceptable)
    Scale-to-zero is great for development and bursty usage. For production, disable it if you need consistently low latency.
- [ ] [7. Test connection retries using the Neon API](https://neon.com/docs/get-started/production-checklist#test-connection-retries-using-the-neon-api)
    Brief disconnects can happen during scaling or maintenance. Verify your application reconnects automatically.
- [ ] [8. Size the history window for instant restore](https://neon.com/docs/get-started/production-checklist#size-the-history-window-for-instant-restore)
    On paid plans, Neon keeps 1 day of change history by default for **instant restore**. Increasing the history window gives more recovery depth, with storage tradeoffs.
- [ ] [9. Consider snapshot schedules](https://neon.com/docs/get-started/production-checklist#consider-snapshot-schedules)
    Snapshot schedules provide consistent backups for point-in-time restore, independently of your history window.
- [ ] [10. Test your restore workflow](https://neon.com/docs/get-started/production-checklist#test-your-restore-workflow)
    Plan whether you'll restore in place or from a snapshot, and how your application will switch if needed.
- [ ] [11. Clean up your branches regularly](https://neon.com/docs/get-started/production-checklist#clean-up-your-branches-regularly)
    Set branch expiration times and add cleanup logic to automated workflows to avoid unnecessary storage costs.
- [ ] [12. Use pooled connections where they make sense](https://neon.com/docs/get-started/production-checklist#use-pooled-connections-where-they-make-sense)
    Connection pooling improves concurrency for web and serverless apps, but may not be appropriate for migrations or long-running tasks.
- [ ] [13. Restrict access to production data](https://neon.com/docs/get-started/production-checklist#restrict-access-to-production-data)
    Limit database access to trusted sources using IP Allow to reduce the risk of unauthorized changes.
- [ ] [14. Install pg_stat_statements](https://neon.com/docs/get-started/production-checklist#install-pgstatstatements)
    Query execution times and frequency yourself with SQL or `neon inspect`. The Console's Query performance view works without it.
- [ ] [15. Integrate with your existing observability stack](https://neon.com/docs/get-started/production-checklist#integrate-with-your-existing-observability-stack)
    Export Neon metrics to Datadog, Grafana, or any OTEL-compatible platform to monitor usage and capacity alongside your existing systems.

## Use a paid plan for production workloads

Neon's paid plans are fully usage-based, which means your database is never subject to fixed limits that can stop your application as traffic grows. You pay for the compute and storage you use each month, without minimums.

The Free plan is designed to support experimentation and prototyping and includes compute hour limits. It should be avoided for production workloads where uninterrupted availability matters.

If you need technical support beyond billing, the Scale plan includes priority support with access to Neon's support team.

Keep reading: [Neon plans](https://neon.com/docs/introduction/plans)

## Choose a region close to your application

Network latency is one of the most common contributors to database response time: even a well-tuned database will feel slow if it's geographically far from your application servers. When creating a Neon project, choose the region that is closest to where your application runs.

Keep reading: [Neon regions](https://neon.com/docs/introduction/regions)

## Keep your production branch as the default root branch

Your production database should run on a [root branch](https://neon.com/docs/reference/glossary#root-branch) that is set as the project's [default branch](https://neon.com/docs/reference/glossary#default-branch). Neon projects are configured this way by default. Using a root branch enables [snapshots](https://neon.com/docs/guides/backup-restore), provides simpler billing (based on actual data size rather than accumulated changes), and prevents accidental deletion.

Keep reading: [Manage branches](https://neon.com/docs/manage/branches)

## Protect your production branch

Neon makes it easy to branch, reset, and restore databases. In production, that power should be paired with explicit safeguards. Branch protection helps ensure that powerful features like restore, reset, and snapshot operations are used deliberately when applied to production data. This is especially important in teams or automated environments.

![Protect branch button](https://neon.com/docs/guides/ip_allow_set_as_protected.png)

Keep reading: [Protected branches](https://neon.com/docs/guides/protected-branches)

## Enable autoscaling and set appropriate limits

Neon autoscaling automatically adjusts compute resources based on your workload, allowing your database to absorb traffic spikes without manual intervention. For production workloads:

- **Minimum compute size**: Set a minimum high enough so your working set (frequently accessed data) can be fully cached in memory. This is important because Neon's [compute cache](https://neon.com/docs/reference/glossary#compute-cache) is tied to your compute size. When the compute scales down and the cache shrinks, frequently accessed data may be evicted and need to be reloaded from storage, which impacts performance.

- **Maximum compute size**: Set a maximum that provides enough extra capacity for traffic spikes. The maximum also determines your available local disk space, which is used for things like temporary files, complex queries, [pg_repack](https://neon.com/docs/extensions/pg_repack), and replication.

A safe minimum combined with a sufficiently high maximum will give you the best performance while avoiding unnecessary baseline cost.

![Autoscaling control](https://neon.com/docs/get-started/autoscaling_control.png)

Keep reading:

- [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute)
- [Autoscaling configuration](https://neon.com/docs/introduction/autoscaling#configuring-autoscaling)
- [Monitor working set size](https://neon.com/docs/introduction/monitoring-page#working-set-size)
- [How the autoscaling algorithm works](https://neon.com/docs/guides/autoscaling-algorithm)

## Decide whether scale-to-zero is acceptable

Scale-to-zero allows Neon to suspend compute after a period of inactivity. This is a highly effective way to save costs in development environments and workloads with intermittent usage. For production workloads, the decision depends on your latency requirements.

If occasional cold starts are acceptable for your application (for example, for internal tools), leaving scale-to-zero enabled will be the most cost-effective choice.

Consider disabling scale-to-zero if:

- Your application requires consistently low latency
- Cold-start delays are unacceptable for user-facing requests
- You rely on long-lived sessions or in-memory state

Keep reading: [Scale to zero configuration](https://neon.com/docs/guides/scale-to-zero-guide)

## Test connection retries using the Neon API

In a serverless architecture, brief connection interruptions can occur during scaling events or maintenance. Most database drivers and connection pools already implement retry logic for transient failures, but rather than assuming this works, you should test it.

Our recommended approach:

- Use the Neon Console, CLI, or API to trigger a compute restart
- Observe how your application behaves during the restart
- Confirm that connections are re-established automatically without user-facing errors

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/{project_id}/endpoints/{endpoint_id}/restart \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

With the Neon CLI:

```bash
neon postgres computes restart <endpoint_id> --project-id <project_id>
```

Keep reading:

- [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute)
- [Build connection timeout handling into your application](https://neon.com/docs/connect/connection-latency#build-connection-timeout-handling-into-your-application)
- [Maintenance and updates overview](https://neon.com/docs/manage/maintenance-updates-overview)

## Size the history window for instant restore

**[Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore)** lets you roll a branch's database timeline back in time. How far back you can go depends on the **history window** you configure (under **Settings → Postgres**). On paid plans, the default history window is 1 day, which you can increase up to 7 days on Launch or 30 days on Scale.

A longer history window gives you more flexibility to recover from bugs discovered later or accidental data loss. However, longer windows retain more change history, which increases **History** usage on your bill. Choose a window that balances recovery needs with predictable storage costs.

Keep reading: [Storage and billing for instant restore](https://neon.com/docs/postgres/backup-restore/history-window#storage-and-billing)

## Consider snapshot schedules

Snapshot schedules provide regular, durable restore points taken daily, weekly, or monthly. While **[instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore)** lets you roll back to any moment still inside your **history window**, snapshots capture stable points in time that you can return to later, ensuring that recovery points exist even if they fall outside your chosen history window.

Snapshot schedules are only available on [root branches](https://neon.com/docs/manage/branches#root-branch).

![Snapshot schedule](https://neon.com/docs/guides/backup_restore_ui.png)

Keep reading: [Snapshot schedules](https://neon.com/docs/guides/backup-restore#create-backup-schedules)

## Test your restore workflow

Don't wait for an incident to learn how restore works. Plan and test your recovery process in advance.

**Database restore** (Postgres + Managed Better Auth) uses Neon's built-in capabilities:

- [Instant branch restores](https://neon.com/docs/guides/backup-restore#instantly-restore-a-branch), where the existing branch is restored to a previous state
- [Restore from a snapshot into the same branch](https://neon.com/docs/guides/backup-restore#one-step-restore)
- [Restore from a snapshot into a new branch](https://neon.com/docs/guides/backup-restore#multi-step-restore)

Plan and test which restore method you will use for production incidents, how your application will switch connections if a new branch is created, and how you will validate restored data before resuming traffic.

## Clean up your branches regularly

Neon's branching makes it easy to create preview, test, and temporary environments. Over time, unused branches can accumulate and contribute to unnecessary storage usage. To keep costs and complexity under control:

- Set expiration times for preview and test branches
- Add explicit delete steps to automated branching workflows
- Periodically review and remove branches that are no longer in use

Keep reading:

- [Branch expiration](https://neon.com/docs/guides/branch-expiration)
- [Automate branching with GitHub Actions](https://neon.com/docs/guides/branching-github-actions)
- [Plans and billing](https://neon.com/docs/introduction/plans)

## Use pooled connections where they make sense

Connection pooling increases the number of concurrent clients your database can serve (up to 10,000) by reusing a smaller number of backend connections. This reduces connection overhead and improves performance in web and serverless applications.

However, pooled connections are not appropriate for all workloads. Avoid them for:

- Long-running database migrations
- Workloads that rely on session-level state
- Administrative tasks that require persistent connections (for example, `pg_dump`)
- Logical replication (CDC tools like Fivetran, Airbyte)

Keep reading: [Connection pooling](https://neon.com/docs/connect/connection-pooling)

## Restrict access to production data

Neon's IP Allow feature ensures that only trusted IP addresses can connect to your database, preventing unauthorized access and enhancing security. Combine an allowlist with protected branches for enhanced security.

![IP Allow settings](https://neon.com/docs/get-started/ip_allow_settings.png)

Keep reading: [IP Allow](https://neon.com/docs/introduction/ip-allow)

## Install pg_stat_statements

The [pg_stat_statements extension](https://neon.com/docs/extensions/pg_stat_statements) tracks how often each query runs and how long it takes. The Console's [Query performance](https://neon.com/docs/introduction/monitor-query-performance) view shows this data without any setup. Install the extension in your database to query the statistics yourself with SQL or to use [`neon inspect`](https://neon.com/docs/cli/inspect):

```sql
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```

The statistics gathered by this extension require little overhead and let you quickly access metrics like:

- [Most frequently executed queries](https://neon.com/docs/postgresql/query-performance#most-frequently-executed-queries)
- [Longest running queries](https://neon.com/docs/postgresql/query-performance#long-running-queries)
- [Queries that return the most rows](https://neon.com/docs/postgresql/query-performance#queries-that-return-the-most-rows)

You can also use the **Monitoring Dashboard** in the Neon Console to view live graphs for system and database metrics like CPU, RAM, and connections.

![Monitoring page connections graph](https://neon.com/docs/introduction/monitor_connections.png)

Keep reading:

- [Query performance](https://neon.com/docs/postgresql/query-performance)
- [Monitoring](https://neon.com/docs/introduction/monitoring)

## Integrate with your existing observability stack

If you already operate an observability platform, you can export Neon metrics and logs to monitor database behavior alongside the rest of your system. This helps you:

- Track connection counts and usage patterns
- Monitor compute and storage growth over time
- Correlate database behavior with application-level events

You can export to any OTLP-compatible platform, Datadog, or Grafana Cloud.

Keep reading:

- [OpenTelemetry export guide](https://neon.com/docs/guides/opentelemetry)
- [Datadog export guide](https://neon.com/docs/guides/datadog)
- [Grafana Cloud export guide](https://neon.com/docs/guides/grafana-cloud)

--- [Document source](https://neon.com/docs/get-started/production-readiness.md) ---

> Summary: Neon's serverless Postgres platform scales across distinct growth stages, from a free plan with scale-to-zero compute, to a startup tier with autoscaling and copy-on-write branching, to fleet-scale with database-per-tenant isolation and API-driven provisioning. Read this page to match Neon features to your current growth stage before selecting a plan or designing a multi-tenant architecture.

# Built to scale

Neon supports you from prototype to scale-up

Last updated: 2026-10-01

Neon fits into every stage of growth, from the first side project to operating large fleets of production databases - without forcing you to rethink your database architecture along the way.

## Stage 1: Side projects

**Real hosted Postgres with zero costs**

When you're looking for a free plan to run Postgres, what you want is simplicity and enough room to build. Neon's Free plan abstracts most configuration work, delivers real-world performance, and gives you access to core Neon features like branching and autoscaling.

- You get a [Free Plan with real resources](https://neon.com/blog/why-so-many-projects-in-the-neon-free-plan), including up to 100 projects, computes with up to 2 CUs, and 1 GB of Postgres storage per project - enough to build and test real applications
- You get a Postgres connection string in a second so you can start building right away
- [Scale to zero](https://neon.com/docs/introduction/scale-to-zero) ensures idle databases don't eat up your compute limits: only active time counts
- Standard Postgres compatibility means you can plug Neon into [any framework, ORM, or tool that speaks Postgres](https://neon.com/docs/get-started/frameworks)
- A [broad catalog of Postgres extensions](https://neon.com/docs/extensions/pg-extensions) unlocks a Postgres-for-everything workflow

## Stage 2: Startups

**Build and iterate fast**

As a project becomes a product, small teams need to ship quickly and support real users. Neon gives these teams a frictionless building experience without compromising on performance and reliability.

> **Production checklist**
>
> Before launching your product, go through this checklist to make sure your DB has the right configuration to support your end users.
>
> [View checklist](https://neon.com/docs/get-started/production-checklist)

- [Autoscaling](https://neon.com/docs/introduction/autoscaling) adapts automatically to unpredictable workloads: you don't have to plan capacity in advance
- [Branching](https://neon.com/branching) lets you spin up development, preview, and test environments instantly, matching the latest production state, without manual work
- [Out-of-the-box integrations](https://neon.com/docs/guides/integrations) with platforms like Vercel further simplify previews and deployments
- [API-first workflows](https://neon.com/docs/reference/api) make it easy to automate almost all database operations
- AI-coding support via [MCP](https://neon.com/docs/ai/neon-mcp-server) and [Agent Skills](https://neon.com/docs/ai/agent-skills) allows tools like Cursor and Claude to fully interact with Neon
- [Instant restores](https://neon.com/docs/guides/backup-restore) lower the stakes for mistakes and accidents
- [Built-in connection pooling](https://neon.com/docs/connect/connection-pooling) takes care of growing connections in your serverless apps
- You get access to [compliance and security features](https://neon.com/blog/why-we-no-longer-lock-premium-features) without enterprise-only contracts

## Scale-ups and large fleets

**Frictionless operations at scale**

At this stage, teams need performance, reliability, isolation, and automation without ballooning costs or operational complexity. Neon's architecture is built to address their different requirements directly.

### Operational efficiency

- [On-demand storage](https://neon.com/storage#unique-benefits-derived-from-neons-implementation) grows as data demands it, without planning for capacity in advance and without the risk of full-disk errors
- [Built-in high availability](https://neon.com/docs/introduction/high-availability) is provided by default through storage redundancy, with data replicated across availability zones and cloud object storage
- [Backup and restore via snapshots](https://neon.com/docs/guides/backup-restore) allows you to recover multi-terabyte databases in seconds, without full data copies
- You can use [time travel and snapshot inspections](https://neon.com/blog/three-ways-to-use-your-snapshots) to review past database states for auditing, debugging, and incident analysis
- By [creating environments as copy-on-write branches](https://neon.com/blog/how-mindvalley-minimizes-time-to-launch-with-neon-branches), you avoid the management work and costs associated with running separate instances for development, staging, testing, or recovery
- [Programmatic lifecycle management](https://neon.com/blog/how-dispatch-speeds-up-development-with-neon-while-keeping-workloads-on-aurora) lets you create, reset, and delete large numbers of environments without eating up engineering time

### Multi-tenancy

- Neon's [database-per-tenant setup](https://neon.com/use-cases/database-per-tenant) gives each customer a dedicated Neon project, providing strong isolation, eliminating noisy neighbors, and ensuring consistent performance
- [API-first tenant management](https://neon.com/blog/provision-postgres-neon-api) enables programmatic provisioning, configuration, scaling, recovery, and deletion of tenant databases, making it practical for small teams to manage thousands of tenants

### Fleet management for platforms and agents

- Instant, API-driven database provisioning lets you deploy a full Neon backend as part of your [platform](https://neon.com/docs/guides/embedded-postgres) or [agent](https://neon.com/docs/guides/ai-agent-integration)
- The fully embedded database experience keeps Neon invisible to your end users, with no third-party logins or external configuration required as part of your product workflow
- [Scale to zero](https://neon.com/docs/introduction/scale-to-zero) keeps unit costs low when large numbers of generated apps are never used or only accessed sporadically
- A mature API exposes [fleet management and cost-control capabilities](https://neon.com/docs/guides/consumption-limits) including quotas, usage limits, and lifecycle operations
- You can build versioning, checkpoints, rollbacks, and time-travel workflows with minimal engineering effort via [snapshots](https://neon.com/blog/promoting-postgres-changes-safely-production)
- Built-in app platform services such as [Managed Better Auth](https://neon.com/docs/auth/overview) and our PostgREST-compatible [Data API](https://neon.com/docs/data-api/get-started) make it easy to hook full-stack applications out of the box

> **Agent Plan**
>
> If you're building a full-stack agent platform, apply to our Agent Plan for special pricing, resource limits, and assistance. 
>
> [Check it out](https://neon.com/programs/agents)

--- [Document source](https://neon.com/docs/get-started/query-with-neon-sql-editor.md) ---

> Summary: The Neon SQL Editor is a browser-based query interface built into the Neon Console that runs SQL against any database branch without installing a client. Use it to run EXPLAIN and EXPLAIN ANALYZE, query historical data with Time Travel, and generate SQL from natural language. Query history entries are capped at 9 KB. AI features are rate-limited, and results export as CSV, JSON, or XLSX.

# Query with Neon's SQL Editor

Query your database from the Neon Console using the Neon SQL Editor

Last updated: 2026-11-08

The Neon SQL Editor allows you to run queries on your Neon databases directly from the Neon Console. In addition, the editor keeps a query history, permits saving queries, and provides [**Explain**](https://www.postgresql.org/docs/current/sql-explain.html) and [**Analyze**](https://www.postgresql.org/docs/current/using-explain.html#USING-EXPLAIN-ANALYZE) features.

To use the SQL Editor:

1. Navigate to the [Neon Console](https://console.neon.tech/).
2. Select your project.
3. Select **Postgres database** > **SQL Editor**.
4. Select a branch and database.
5. Enter a query into the editor and click **Run** to view the results.

![Neon SQL Editor](https://neon.com/docs/get-started/sql_editor.png)

## Create a table with SQL

Neon runs standard Postgres, so you create tables from the SQL Editor with standard `CREATE TABLE` syntax. Enter the statement and click **Run**. The following query creates a table, adds data, and retrieves the data from the table, so you can try the editor end to end:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
INSERT INTO playing_with_neon(name, value)
SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
SELECT * FROM playing_with_neon;
```

Running multiple query statements at once returns a separate result set for each statement. The result sets are displayed in separate tabs, numbered in order of execution, as shown above.

For schema design and repeatable migrations in real projects, use an ORM or migration tool rather than ad hoc SQL. See the [ORM guides](https://neon.com/docs/get-started/orms).

To clear the editor, click **New Query**.

**Tip:** When querying objects such as tables and columns with upper case letters in their name, remember to enclose the identifier name in quotes. For example: `SELECT * FROM "Company"`. Postgres changes identifier names to lower case unless they are quoted. The same applies when creating objects in Postgres. For example, `CREATE TABLE DEPARTMENT(id INT)` creates a table named `department` in Postgres. For more information about how quoted and unquoted identifiers are treated by Postgres, see [Identifiers and Key Words](https://www.postgresql.org/docs/current/sql-syntax-lexical.html#SQL-SYNTAX-IDENTIFIERS), in the _PostgreSQL documentation_.

## Save your queries

The SQL Editor allows you to save your queries.

To save a query:

1. Enter the query into the editor.
2. Click **Save** to open the **SAVE QUERY** dialog.
3. Enter a name for the query and click **Save**.

The query is added to the **Saved** list in the left pane of the SQL Editor. You can rerun a query by selecting it from the **Saved** list.

You can rename or delete a saved query by selecting **Rename** or **Delete** from the more options menu associated with the saved query.

## View the query history

The SQL Editor maintains a query history for the project. To view your query history, select **History** in the left pane of the SQL Editor. You can click an item in the **History** list to view the query that was run.

**Note:** Queries saved to **History** are limited to 9 KB in length. While you can execute longer queries from the SQL Editor, any query exceeding 9 KB will be truncated when saved. A `-- QUERY TRUNCATED` comment is added at the beginning of these queries to indicate truncation. Additionally, if you input a query longer than 9 KB in the Neon SQL Editor, a warning similar to the following will appear: `This query will still run, but the last 1234 characters will be truncated from query history`.

## Explain and Analyze

The Neon SQL Editor provides **Explain** and **Explain (Analyze)** features.

- The **Explain** feature runs the specified query with the Postgres [EXPLAIN](https://www.postgresql.org/docs/current/sql-explain.html) command, which returns the execution plan for the query. The **Explain** feature only returns a plan with estimates. It does not execute the query.
- The **Explain (Analyze)** feature runs the specified query with [EXPLAIN ANALYZE](https://www.postgresql.org/docs/current/using-explain.html#USING-EXPLAIN-ANALYZE). The `ANALYZE` parameter causes the query to be executed and returns actual row counts and run times for plan nodes along with the `EXPLAIN` estimates.

Both features include Neon's `PREFETCH` and `FILECACHE` options, so **Explain (Analyze)** also shows compute cache hits and misses and prefetch statistics. See [View compute cache metrics with EXPLAIN ANALYZE](https://neon.com/docs/extensions/neon#view-lfc-metrics-with-explain-analyze).

**Warning:** Because **Explain (Analyze)** executes the statement, running it on a data-modifying statement (`INSERT`, `UPDATE`, `DELETE`, or `MERGE`) changes your data.

Understanding the information provided by the **Explain** and **Explain (Analyze)** features requires familiarity with the Postgres [EXPLAIN](https://www.postgresql.org/docs/current/sql-explain.html) command and its `ANALYZE` parameter. Refer to the [EXPLAIN](https://www.postgresql.org/docs/current/sql-explain.html) documentation and the [Using EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html) topic in the _PostgreSQL documentation_.

## Time Travel

You can toggle Time Travel in the SQL Editor to switch from querying your current data to querying against a selected point within your [history window](https://neon.com/docs/introduction/history-window).

![time travel in SQL Editor](https://neon.com/docs/get-started/time_travel_sql_editor.png)

For more details about using Time Travel queries, see:

- [Time Travel](https://neon.com/docs/guides/time-travel-assist)
- [Time Travel tutorial](https://neon.com/docs/guides/time-travel-tutorial)

## Export or copy query results

The Neon SQL Editor lets you export data to `CSV`, `JSON`, and `XLSX` formats, or copy query results directly to your clipboard as JSON. Access the download and copy buttons from the bottom right corner of the **SQL Editor** page. These buttons only appear when there is a result set to display.

To copy query results as JSON without downloading a file, click the copy icon button. The JSON will be instantly available in your clipboard, ready to paste into other applications or documentation.

## Expand results section of the SQL Editor window

You can expand the results section of the SQL Editor window by selecting the expand window button from the bottom right corner of the **SQL Editor** page. There must be query results to display, otherwise the expanded results section will appear blank.

## Meta-commands

The Neon SQL Editor supports using Postgres meta-commands, which act like shortcuts for interacting with your database. If you are already familiar with using meta-commands from the `psql` command-line interface, you can use many of those same commands in the SQL Editor.

### Benefits of Meta-Commands

Meta-commands can significantly speed up your workflow by providing quick access to database schemas and other critical information without needing to write full SQL queries. They are especially useful for database management tasks, making it easier to handle administrative duties directly from the Neon Console.

### Available meta-commands

Here are some of the meta-commands that you can use within the Neon SQL Editor:

- `\dt`: List all tables in the current database.
- `\d [table_name]`: Describe a table's structure.
- `\l`: List all databases.
- `\?` - A cheat sheet of available meta-commands
- `\h [NAME]` - Get help for any Postgres command. For example, try `\h SELECT`.

Note that not all meta-commands are supported in the SQL Editor. To get a list of supported commands, use `\?`.

<details>

<summary>Example of supported commands</summary>

```bash
Informational
  (options: S = show system objects, + = additional detail)
  \d[S+]                 list tables, views, and sequences
  \d[S+]  NAME           describe table, view, sequence, or index
  \da[S]  [PATTERN]      list aggregates
  \dA[+]  [PATTERN]      list access methods
  \dAc[+] [AMPTRN [TYPEPTRN]]  list operator classes
  \dAf[+] [AMPTRN [TYPEPTRN]]  list operator families
  \dAo[+] [AMPTRN [OPFPTRN]]   list operators of operator families
  \dAp[+] [AMPTRN [OPFPTRN]]   list support functions of operator families
  \db[+]  [PATTERN]      list tablespaces
  \dc[S+] [PATTERN]      list conversions
  \dconfig[+] [PATTERN]  list configuration parameters
  \dC[+]  [PATTERN]      list casts
  \dd[S]  [PATTERN]      show object descriptions not displayed elsewhere
  \dD[S+] [PATTERN]      list domains
  \ddp    [PATTERN]      list default privileges
  \dE[S+] [PATTERN]      list foreign tables
  \des[+] [PATTERN]      list foreign servers
  \det[+] [PATTERN]      list foreign tables
  \deu[+] [PATTERN]      list user mappings
  \dew[+] [PATTERN]      list foreign-data wrappers
  \df[anptw][S+] [FUNCPTRN [TYPEPTRN ...]]
                         list [only agg/normal/procedure/trigger/window] functions
  \dF[+]  [PATTERN]      list text search configurations
  \dFd[+] [PATTERN]      list text search dictionaries
  \dFp[+] [PATTERN]      list text search parsers
  \dFt[+] [PATTERN]      list text search templates
  \dg[S+] [PATTERN]      list roles
  \di[S+] [PATTERN]      list indexes
  \dl[+]                 list large objects, same as \lo_list
  \dL[S+] [PATTERN]      list procedural languages
  \dm[S+] [PATTERN]      list materialized views
  \dn[S+] [PATTERN]      list schemas
  \do[S+] [OPPTRN [TYPEPTRN [TYPEPTRN]]]
                         list operators
  \dO[S+] [PATTERN]      list collations
  \dp[S]  [PATTERN]      list table, view, and sequence access privileges
  \dP[itn+] [PATTERN]    list [only index/table] partitioned relations [n=nested]
  \drds [ROLEPTRN [DBPTRN]] list per-database role settings
  \drg[S] [PATTERN]      list role grants
  \dRp[+] [PATTERN]      list replication publications
  \dRs[+] [PATTERN]      list replication subscriptions
  \ds[S+] [PATTERN]      list sequences
  \dt[S+] [PATTERN]      list tables
  \dT[S+] [PATTERN]      list data types
  \du[S+] [PATTERN]      list roles
  \dv[S+] [PATTERN]      list views
  \dx[+]  [PATTERN]      list extensions
  \dX     [PATTERN]      list extended statistics
  \dy[+]  [PATTERN]      list event triggers
  \l[+]   [PATTERN]      list databases
  \lo_list[+]            list large objects
  \sf[+]  FUNCNAME       show a function's definition
  \sv[+]  VIEWNAME       show a view's definition
  \z[S]   [PATTERN]      same as \dp
```

</details>

For more information about meta-commands, see [PostgreSQL Meta-Commands](https://www.postgresql.org/docs/current/app-psql.html#APP-PSQL-META-COMMANDS).

### How to Use Meta-Commands

To use a meta-command in the SQL Editor:

1. Enter the meta-command in the editor, just like you would a SQL query.
2. Press **Run**. The result of the meta-command will be displayed in the output pane, similar to how SQL query results are shown.

   For example, here's the schema for the `playing_with_neon` table we created above, using the meta-command `\d playing_with_neon`:

   ![metacommand example](https://neon.com/docs/get-started/sql_editor_metacommand.png)

## AI features

The Neon SQL Editor offers three AI-driven features:

- **SQL generation**: Easily convert natural language requests to SQL. Press the ✨ button or **Cmd/Ctrl+Shift+M**, type your request, and the AI assistant will generate the corresponding SQL for you. It's schema-aware, meaning you can reference any table names, functions, or other objects in your schema.
  ![SQL generation](https://neon.com/docs/get-started/sql_editor_ai.png)
- **Fix with AI**: If your query returns an error, simply click **Fix with AI** next to the error message. The AI assistant will analyze the error, suggest a fix, and update the SQL Editor so you can run the query again.
  ![Fix with AI](https://neon.com/docs/get-started/fix_with_ai.png)
- **AI-generated query names**: Descriptive names are automatically assigned to your queries in the Neon SQL Editor's **History**. This feature helps you quickly identify and reuse previously executed queries.
  ![AI-generated query names](https://neon.com/docs/get-started/query_names.png)

**Important:** To give the AI features context, we share your database schema with the AI agent. No actual data is shared. We currently use Amazon Bedrock as our LLM provider, ensuring all requests remain within AWS's secure infrastructure where other Neon resources are also managed.

_There is a maximum limit of 10 AI requests every 60 seconds._

## Next steps

- **Connect your app:** pick your [framework](https://neon.com/docs/get-started/frameworks), [language](https://neon.com/docs/get-started/languages), or [ORM](https://neon.com/docs/get-started/orms), or start from [Connect your app](https://neon.com/docs/connect/connect-hub).
- **Try a branch:** [branching](https://neon.com/docs/introduction/branching) gives you an instant copy of your data and schema to test changes against, without touching your main branch.
- **Let your agent do it:** [Agent setup](https://neon.com/docs/ai/agent-setup) gives your AI coding agent the Neon tools to create tables, run queries, and manage branches for you.
- **Build a full backend:** the [full backend quickstart](https://neon.com/docs/get-started/full-backend-quickstart) adds Object Storage and Functions to a Next.js app backed by Lakebase Postgres.

--- [Document source](https://neon.com/docs/get-started/signing-up.md) ---

> Summary: The Neon Console tour walks you through querying with the SQL Editor and AI assistant, editing rows in the Tables view, enabling Managed Better Auth, and creating an isolated development branch with the Neon CLI. Choose this page to understand the object hierarchy (project, branch, database, compute) and how branching isolates schema and data from production before you connect an application stack.

# Tour the Neon Console

Explore Neon's core Postgres database features: the SQL Editor, branching, the Tables view, and Managed Better Auth

Last updated: 2026-10-09

**What you will learn:**

- How to view and modify data in the console
- Create an isolated database copy per developer
- Reset your branch to production when ready to start new work

**Related topics**

- [About branching](https://neon.com/docs/introduction/branching)
- [Branching workflows](https://neon.com/docs/get-started/workflow-primer)
- [Connect Neon to your stack](https://neon.com/docs/get-started/connect-neon)
- [Managed Better Auth](https://neon.com/docs/auth/overview)

This tutorial walks you through your first steps using Neon as your Postgres database. It assumes you've already signed up and created a project. You'll explore the Neon object hierarchy and learn how database branching can simplify your development workflow.

**Note:** This tour focuses on Postgres. For a tour of Neon's other backend services, including Object Storage, Functions, and the AI Gateway, see [Tour the Neon backend](https://neon.com/docs/get-started/backend-overview).

## Everything starts with a project

In Neon, everything starts with the **project**. It's the top-level container that holds your branches, databases, and roles. Typically, you create a project for each repository in your application. This lets you manage your database branches just like you manage your code branches: a branch for production, staging, development, new features, previews, and so forth.

## About branching

Each [branch](https://neon.com/docs/introduction/branching) is a fully-isolated copy of its parent. We suggest creating a long-term branch for each developer on your team to maintain consistent connection strings. You can reset your development branch to production whenever needed.

Your project starts with a `production` branch:

- `production` is your project's root default branch (default: 0.25-2 CU, adjustable up to 56 CU)

The default branch is named `main` if the project was created with the CLI or API, or `production` if created in the Console. This tour uses `production`.

You can create additional branches for development, staging, and other environments. For development branches, consider using a smaller compute size (0.25-1 CU) to optimize costs, while keeping production appropriately sized for your workload. All computes scale to zero after 5 minutes of inactivity by default, which keeps costs low for development branches. On paid plans, you can disable this for production if you need always-active compute. See [Scale to zero](https://neon.com/docs/introduction/scale-to-zero).

## Add sample data

Let's get familiar with the **SQL Editor**, where you can run queries against your databases directly from the Neon Console, as well as access more advanced features like [Time Travel](https://neon.com/docs/guides/time-travel-assist) and [Explain and Analyze](https://neon.com/docs/get-started/query-with-neon-sql-editor#explain-and-analyze).

From the Neon Console, use the sidebar navigation to open **Postgres database** > **SQL Editor**. Notice that your default branch `production` is already selected, along with your project's default database, `neondb`.

![Neon SQL Editor](https://neon.com/docs/get-started/sql_editor.png)

The first time you open the SQL Editor for a new project, the editor includes placeholder SQL commands to create and populate a new sample table called `playing_with_neon`.

For this tutorial, go ahead and create this sample table: click **Run**.

Every query you run in the SQL Editor is automatically saved with an AI-generated description, making it easy to find and reference your work later. For example, the sample table creation above will be saved with a description like "create and populate sample table in Neon". You can view your query history anytime by clicking the **History** button in the SQL Editor.

Or if you want to add the table from the command line and you already have `psql` installed:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
```

Your default branch `production` now has a table with some data.

## Try the AI Assistant

Now that you have some sample data, let's explore how the AI Assistant can help you write SQL queries using natural language prompts.

From the SQL Editor, click the **Generate SQL** button (the sparkle icon) in the top-right corner of the editor. This button opens the prompt field shown below. Don't use the separate **Ask AI** button next to your account menu. Try a few prompts:

- _Add three more rows to the playing_with_neon table with tech company names_
- _Show me the highest value in the table_
- _Calculate the average value grouped by the first letter of the name_

![Neon SQL Editor AI Assistant](https://neon.com/docs/get-started/sql_assistant.png)

Each query you run is automatically saved with an AI-generated description, making it easy to find and reuse queries later. For example, when you ask the AI Assistant to add company data, you should see a response like:

```sql
-- Text to SQL original prompt:
-- Add three more rows to the playing_with_neon table with tech company names
INSERT INTO public.playing_with_neon (name, value) VALUES
('Google', 1000.5),
('Apple', 1200.75),
('Microsoft', 950.25);
```

With the description: "Add tech companies to playing_with_neon table"

Learn more about AI features in the [SQL Editor documentation](https://neon.com/docs/get-started/query-with-neon-sql-editor#ai-features).

## View and modify data in the console

Now that you have some data to play with, let's take a look at it on the **Tables** page in the Neon Console. The **Tables** page, powered by [Drizzle Studio](https://orm.drizzle.team/drizzle-studio/overview), provides a visual interface for exploring and modifying data and schemas directly from the console. The integration with Drizzle Studio provides the ability to add, update, and delete records, filter data, export data in `.json` and `.csv` formats, manage schemas (including creating and altering tables, views, and enums), create Postgres roles, and define RLS policies.

![Tables page Drizzle integration](https://neon.com/docs/get-started/tables_drizzle.png)

For a detailed guide on how to interact with your data using the **Tables** page, visit [Managing your data with interactive tables](https://neon.com/docs/guides/tables).

## Set up Managed Better Auth

Neon includes **managed authentication**, so your app's users live in your Postgres database and branch with the rest of your data.

From the Neon Console sidebar, open the **Better Auth** page and toggle Managed Better Auth on for your project. You'll get:

- A sign-up / sign-in flow ready to wire up to any framework
- Users and sessions stored in your own Postgres database — query the `neon_auth.user` table directly alongside your application data
- Branch-aware auth: every preview or development branch you create gets its own isolated copy of users and sessions
- OAuth providers, email and password, magic links, and more, all configurable from the console

For framework-specific setup, see the [Managed Better Auth quickstarts](https://neon.com/docs/auth/overview) (Next.js, React, TanStack Router) or open the **Better Auth** page in the console and follow the prompts.

## Working with your development branch

Let's create a `development` branch and learn how to use the Neon CLI to manage branches and make schema changes in your development environment.

1. **Create a development branch**

   From the Neon Console, navigate to the **Branches** page and click **New Branch**. Name it `development`, select `production` as the parent branch, and click **Create new branch**. This creates an isolated copy of your production data that you can safely modify.

2. **Install CLI with Brew or NPM**

   Depending on your system, you can install the Neon CLI using either Homebrew (for macOS) or NPM (for other platforms).

   - For macOS using Homebrew:

     ```bash
     brew install neonctl
     ```

   - Using NPM (applicable for all platforms that support Node.js):

     ```bash
     npm install -g neon
     ```

3. **Authenticate with Neon**

   The `neon login` command launches a browser window where you can authorize the Neon CLI to access your Neon account.

   ```bash
   neon login
   ```

4. **View your branches**

   First, list your projects to get your project ID:

   ```bash
   neon projects list
   ```

   You'll be prompted to select your organization. The output shows your project IDs:

   ```bash
   Projects
   ID                    Name       Region ID      Created At
   cool-forest-12345678  myproject  aws-us-east-2  2026-10-14T14:33:43Z
   ```

   Now list your branches using your project ID:

   ```bash
   neon branches list --project-id cool-forest-12345678
   Name                            ID                   Current State  Expires At  Created At
   development                     br-calm-sky-123456   ready          never       2026-12-23T21:05:05Z
   [default] [current] production  br-bold-wind-123456  ready          never       2026-12-23T21:04:57Z
   ```

   This command shows your existing branches, including the `production` branch and the `development` branch you just created.

   **Tip:** To avoid specifying `--project-id` with each command, use `neon set-context` to set your default project and organization. See [set-context](https://neon.com/docs/cli/set-context) for details.

## Make some sample schema changes

First, let's make sure our development branch is in sync with `production`. This ensures we're starting from the same baseline:

```bash
neon branches reset development --parent --project-id cool-forest-12345678
```

Now that our `development` branch matches `production`, we can make some changes. The `playing_with_neon` table from `production` is now available in your `development` branch, and we'll modify its schema and add new data to demonstrate how branches can diverge.

You can use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) for this, but let's demonstrate how to connect and modify your database from the terminal using `psql`. If you don't have `psql` installed already, follow these steps to get set up:

**Mac**

```bash
brew install libpq
echo 'export PATH="/opt/homebrew/opt/libpq/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**Linux**

```bash
sudo apt update
sudo apt install postgresql-client
```

**Windows**

Download and install PostgreSQL from:

[https://www.postgresql.org/download/windows/](https://www.postgresql.org/download/windows/)

Ensure psql is included in the installation.

With `psql` available, let's work from the terminal to connect to your `development` branch's database and make changes.

1. **Connect to your database**

   Get the connection string to your branch and connect to it directly via `psql`:

   ```bash
   neon connection-string development --database-name neondb --project-id cool-forest-12345678 --psql
   ```

   This command establishes the psql terminal connection to the `neondb` database on your development branch.

2. **Modify the schema**

   Add a new column `description` and index it:

   ```sql
   ALTER TABLE playing_with_neon
   ADD COLUMN description TEXT;

   CREATE INDEX idx_playing_with_neon_description ON playing_with_neon (description);
   ```

3. **Insert new data**

   Add new data that will be exclusive to the dev branch.

   ```sql
   INSERT INTO playing_with_neon (name, description)
   VALUES ('Your dev branch', 'Exploring schema changes in the dev branch');
   ```

4. **Verify the schema changes**

   Query the table to verify your schema changes:

   ```sql
   SELECT * FROM playing_with_neon;
   ```

   Your response should include the new description column and a new row where name = `Your dev branch` and description = `Exploring schema changes in the dev branch`:

   ```sql {1,13}
    id |        name        |    value    |                description
   ----+--------------------+-------------+--------------------------------------------
     1 | c4ca4238a0         |   0.5315024 |
     2 | c81e728d9d         |  0.17189825 |
     3 | eccbc87e4b         |  0.21428405 |
     4 | a87ff679a2         |   0.9721639 |
     5 | e4da3b7fbb         |   0.8649301 |
     6 | 1679091c5a         |  0.48413596 |
     7 | 8f14e45fce         |  0.82630277 |
     8 | c9f0f895fb         |  0.99945337 |
     9 | 45c48cce2e         | 0.054623786 |
    10 | d3d9446802         |  0.36634886 |
    11 | Your dev branch    |             | Exploring schema changes in the dev branch
   (11 rows)
   ```

## Check your changes with Schema Diff

After making the schema changes to your development branch, you can use the [Schema Diff](https://neon.com/docs/guides/schema-diff) feature to compare your branch against its parent branch. Schema Diff is a GitHub-style code-comparison tool used to visualize differences between different branch's databases.

For this tutorial, Schema Diff helps with validating isolation: it confirms that schema changes made in your isolated development branch remain separate from the production branch.

From the **Branches** page in the Neon Console:

1. Open the detailed view for your `development` branch, open the three-dot menu, and select **Compare to parent**.
2. Verify the right branches are selected and click **Compare**. You can see the schema changes we added to our development branch highlighted in green.

   ![Schema diff from branches page](https://neon.com/docs/get-started/getting_started_schema_diff.png)

### Schema Migrations

A more typical scenario for Schema Diff is when preparing for schema migrations. While Neon does not provide built-in schema migration tools, you can use ORMs like [Drizzle](https://drizzle.team/) or [Prisma](https://www.prisma.io/) to handle schema migrations efficiently. Read more about using Neon in your development workflow in [Connect Neon to your stack](https://neon.com/docs/get-started/connect-neon).

## Reset your development branch to production

After experimenting with changes in your development branch, let's now reset the branch to `production`, its parent branch.

[Branch reset](https://neon.com/docs/guides/reset-from-parent) functions much like a `git reset –hard parent` in traditional Git workflows.

Resetting your development branches to the `production` branch ensures that all changes are discarded, and your branch reflects the latest stable state of `production`. This is key to maintaining a clean slate for new development tasks and is one of the core advantages of Neon's branching capabilities.

You can reset to parent from the **Branches** page of the Neon Console, but here we'll use the Neon CLI.

Use the following command to reset your `development` branch to the state of the `production` branch:

Example:

```bash
neon branches reset development --parent --project-id cool-forest-12345678
```

If you go back to your **Schema Diff** and compare branches again, you'll see they are now identical:

![schema diff after reset](https://neon.com/docs/get-started/getting_started_schema_diff_reset.png)

### When to reset your branch

Depending on your development workflow, you can use branch reset:

- **After a feature is completed and merged**

  Once your changes are merged into `production`, reset the development branch to start on the next feature.

- **When you need to abandon changes**

  If a project direction changes or if experimental changes are no longer needed, resetting the branch quickly reverts to a known good state.

- **As part of your CI/CD automation**

  With the Neon CLI, you can include branch reset as an enforced part of your CI/CD automation, automatically resetting a branch when a feature is closed or started.

Make sure that your development team is always working from the latest schema and data by including branch reset in your workflow. To read more about using branching in your workflows, see [Branching workflows](https://neon.com/docs/get-started/workflow-primer).

**Tip: Additional branching features**

- **Working with sensitive data?** Neon supports [schema-only branching](https://neon.com/docs/guides/branching-schema-only) to create branches with just the database structure, without copying production data.
- **Need automatic cleanup?** Set branches to automatically [expire and be deleted](https://neon.com/docs/guides/branch-expiration) after a specified time period, perfect for temporary test branches or time-limited preview environments.

## What's next

Building an app with users? [Set up Managed Better Auth](https://neon.com/docs/auth/overview) for managed sign-up, sessions, and OAuth. Identity lives in Postgres and branches with your data, so you can test full login flows on preview branches without touching production.

--- [Document source](https://neon.com/docs/get-started/why-neon.md) ---

> Summary: Neon is a complete set of cloud backend primitives built around Lakebase Postgres, for developers, startups, and agent platforms, from Databricks. Lakebase Postgres runs on the lakebase architecture, making instant branching, autoscaling, scale-to-zero, realtime reactivity and point-in-time restore intrinsic rather than add-ons. Neon also includes Managed Better Auth, Object Storage, Functions, and AI Gateway.

# Why Neon?

The backend for apps and agents, by Databricks

Last updated: 2026-11-08

## Our mission

**Neon is a complete set of cloud backend primitives built around Lakebase Postgres, for developers, startups, and agent platforms, from Databricks. Neon includes Lakebase Postgres, Managed Better Auth, Realtime, Object Storage, Functions, the Data API, and AI Gateway. Every service is agent-ready: instant, branchable, and serverless, designed to help developers build scalable applications faster than ever.**

Neon started with a mission: to deliver Postgres as a cloud service that gets out of developers' way, from their first side project to millions of users in production. Postgres should be as universal and accessible as object storage, something every developer can rely on without thinking about infrastructure.

That idea became what is now Lakebase Postgres, built on the lakebase architecture: a distributed, cloud-native design that separates storage and compute, giving Postgres the scale, reliability, and efficiency modern applications require. This foundation unlocks the features that agents, and the developers behind them, expect today: autoscaling, scale-to-zero, instant branching, instant restores, and usage-based pricing, without changing the Postgres you already know.

Neon has since grown beyond the database into a complete backend, so a single account provisions everything an app or agent needs, not just a place to store data.

**Tip: Neon, now a part of Databricks**

In May 2025, Neon joined Databricks to shape the future of Postgres and AI-native development. Our mission stayed the same. Lakebase Postgres is also available on Databricks, as [Lakebase](https://www.databricks.com/product/lakebase). Learn more in [Neon and Lakebase](https://neon.com/docs/introduction/neon-and-lakebase).

## What makes Neon different

### Real Postgres, serverless by architecture

At the center of Neon is Lakebase Postgres. It isn't "Postgres-like": it is Postgres, with full compatibility across ORMs, extensions, and frameworks. What sets it apart is the [lakebase architecture](https://neon.com/docs/introduction/architecture-overview), which separates storage from compute so serverless behavior is foundational, not layered on. Instead of sizing instances or tuning by hand, you get a database that behaves the way developers expect modern infrastructure to:

- **Scale-to-zero.** Inactive databases shut down automatically to save costs. Ideal for side projects, development environments, and agent-generated apps.
- **Autoscaling.** For production, Lakebase Postgres resizes compute up and down automatically based on traffic, so performance stays steady without capacity planning.
- **Branching.** Clone your entire database (data and schema) instantly to create dev environments, run migrations safely, automate previews, and build versioning and checkpoints for agents.
- **Realtime.** Subscribe to live SQL queries and build fast, modern apps with end-to-end reactivity and type safety.
- **Instant restores.** Go back to any point in time in seconds, no matter how large your database, or instantly revert to a saved snapshot.
- **Usage-based pricing.** Pay only for what you use, without provisioning storage or compute in advance and without expensive add-ons.
- **A Free plan developers can actually use.** The lakebase architecture makes it efficient for Neon to run a large Free plan with many projects per account and enough resources to build real apps.

### A complete backend, not just a database

Most apps and agents need more than a database. Neon gives you the rest of a modern backend as first-class primitives, each built to branch, scale, and provision the same way Lakebase Postgres does:

- **[Managed Better Auth](https://neon.com/docs/auth/overview)** for authentication and identity, backed by Postgres
- **[Object Storage](https://neon.com/docs/storage/overview)** for S3-compatible files and blobs that branch alongside your data
- **[Functions](https://neon.com/docs/compute/functions/overview)** for long-running compute next to your database
- **[Data API](https://neon.com/docs/data-api/overview)** for instant HTTP access to your data
- **[AI Gateway](https://neon.com/docs/ai-gateway/overview)** for model access across providers with a single credential

You adopt only the primitives you need and keep the rest of your stack (frameworks, hosts, ORMs, AI tools) unchanged. This is what lets a platform or agent deploy a full backend, not just a database, in a single step.

### Agent-ready by default

Every core operation is available as an API, so the whole backend is operable by software, not only by a human in a console. Agents provision, branch, query, and tear down backends through the [Neon API](https://neon.com/docs/reference/api), [SDKs](https://neon.com/docs/reference/sdk), [CLI](https://neon.com/docs/cli), and [MCP server](https://neon.com/docs/ai/neon-mcp-server) the same way they manage code, and the serverless architecture keeps that automation fast and cheap even across thousands of short-lived environments. An agent can even [provision a database before the user has an account](https://neon.com/docs/reference/claimable-neon) and hand back a claim link so a human can take ownership later.

## Who uses Neon and why

### Developers and their agents: From side projects to live apps

Independent developers want to build without friction. They don't want to create accounts, configure VMs, or invest large sums just to test an idea. Increasingly, they want their agent to handle the infrastructure directly.

**Why they build on Neon**

- Neon is agent-first: agents are a first-class interface
- The Free plan is generous enough to build real apps, not just to test things out
- A Postgres connection string is available immediately, with no wait for provisioning
- Branching, previews, and instant restores let agents experiment quickly
- Neon integrates easily with Next.js, Remix, Vercel, Prisma, Drizzle, and the broader ecosystem
- Managed Better Auth, Object Storage, and Functions are one call away when the project needs more than a database, with no new provider to sign up for
- The experience feels lightweight and fast, not enterprise-heavy

### Startups: From dev to scale

Startups want to ship product fast and avoid cloud infrastructure complexity. They need their backend to be reliable, scalable, and invisible, something they never have to think about unless something goes wrong. They also need their coding agent to handle it reliably.

**Why they build on Neon**

- The lakebase architecture removes most database administration, and agents can handle the tasks that remain
- Autoscaling takes care of unpredictable traffic without overprovisioning or planning compute sizes
- Branching speeds up building: entire dev backend environments get deployed instantly with minimal costs
- Realtime reactivity is built directly into the database and platform, avoiding silos and separate realtime systems
- Neon's straightforward and feature-complete [API](https://neon.com/docs/reference/api)
- Usage-based pricing means no waste, no upfront commitments
- Managed Better Auth, Object Storage, the Data API, and Functions are built in, so the team ships features without stitching together separate services
- Neon delivers on reliability, performance, and compliance, backed by Databricks

### App generation platforms: From prompt to app

Full-stack codegen platforms spin up thousands of independent applications instantly, each with its own backend. They need a backend that can support a fleet of thousands of mostly inactive apps every day without breaking performance or blowing up costs.

**Why they build on Neon**

- Neon is already tested at scale, powering platforms like Replit
- They can deploy a backend instantly and transparently on behalf of the end-user, including Lakebase Postgres, Managed Better Auth, Object Storage, Functions, and AI Gateway
- Agents and APIs create and delete thousands of short-lived, low-usage databases
- Scale-to-zero makes this setup economically viable at scale
- Branching makes it simple to build versioning, rollbacks, and checkpoints
- Realtime makes it simple to build fast, modern apps with end-to-end reactivity

**Tip: Join the Agent Program**

Building a full-stack agent that deploys backends? Apply to our [Agent Program](https://neon.com/programs/agents#agent-plan-pricing) and get access to special pricing, resource limits, features, and support from the team.

## How it works: the lakebase architecture

The serverless behaviors (instant branching, autoscaling, scale-to-zero, and fast recovery) aren't features layered on Postgres. They fall out of one idea: Postgres on the object store. Durability and history live in cloud object storage instead of on a single machine's disk, so compute becomes stateless and ephemeral, storage scales on its own, and past states are retained natively rather than rebuilt from backups. For the full design, including the safekeeper, pageserver, and read and write paths, see the [architecture overview](https://neon.com/docs/introduction/architecture-overview).

**Note: Not the same as Neon Object Storage**

The object store described here is the internal storage layer that Lakebase Postgres is built on: where your database's data and history live. It is separate from [Object Storage](https://neon.com/docs/storage/overview), the S3-compatible primitive you use directly to store application files and blobs. Both draw on the same object-store foundation, which is why a bucket branches alongside your database, but you interact with them at different layers.

The rest of Neon's primitives are designed to carry these same properties. Object Storage buckets, Functions, Managed Better Auth, and the Data API all provision instantly, branch with your project, and scale on demand, so the whole backend behaves the way Lakebase Postgres does, not just the database at its center.

**Tip: Neon and Lakebase**

Lakebase Postgres is available via Neon and via Databricks. For what's the same in both places and when to choose each, see [Neon and Lakebase](https://neon.com/docs/introduction/neon-and-lakebase).

## Get started

- **Set up with your AI agent:** [Agent setup](https://neon.com/docs/ai/agent-setup) gives Claude Code, Cursor, Codex, and other agents the Neon tools and skills, so your agent can provision and manage the backend for you.
- **Build a full backend:** the [full backend quickstart](https://neon.com/docs/get-started/full-backend-quickstart) wires Lakebase Postgres, Object Storage, and Functions into a Next.js app, all declared in one `neon.ts`.
- **Connect an existing app:** pick your [framework](https://neon.com/docs/get-started/frameworks), [language](https://neon.com/docs/get-started/languages), or [ORM](https://neon.com/docs/get-started/orms), or start from [Connect your app](https://neon.com/docs/connect/connect-hub).
- **Compare plans:** [Plans](https://neon.com/docs/introduction/plans) covers what the Free plan includes and when a paid plan makes sense.

> **Choosing between Neon and Databricks?**
>
> Lakebase Postgres is available via Neon and via Databricks. If your team is deciding which access path fits your workload, talk to sales.
>
> [Contact sales](https://www.databricks.com/company/contact)

--- [Document source](https://neon.com/docs/get-started/workflow-primer.md) ---

> Summary: Neon database branching creates isolated Postgres branches in ~1 second, each with its own connection string and a full copy of the parent's schema and data. Use this page when setting up per-developer, per-PR preview, or CI/CD test database environments via the Neon CLI or GitHub Actions. Available GitHub Actions include create-branch, delete-branch, reset-branch, and schema-diff; schema-only branching and automatic branch expiration are also covered.

# Database branching workflow primer

An introduction to integrating Postgres branching into your development workflow

Last updated: 2026-09-01

With Neon, you can work with your data just like you work with your code. The key is Neon's database [branching](https://neon.com/docs/concepts/branch-your-backend) feature, which lets you instantly create branches of your data that you can include in your workflow, as many branches as you need.

Neon branches are:

- **Isolated**: changes made to a branch don't affect its parent.
- **Fast to create**: creating a branch takes ~1 second, regardless of the size of your database.
- **Ready to use**: branches will have the parent branch's schema and all its data (you can also include data up to a certain point in time). If you're working with sensitive data, Neon also supports a [schema-only branching](https://neon.com/docs/guides/branching-schema-only) option.

Every Neon branch has a unique Postgres connection string, so they're completely isolated from one another.

```bash
# Branch 1
postgresql://database_name_owner:AbC123dEf@ep-shiny-cell-a5y2zuu0.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require

# Branch 2
postgresql://database_name_owner:AbC123dEf@ep-hidden-hall-a5x58cuv.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

You can create all of your branches from the default branch, or set up a dedicated branch that you use as a base. The first approach is simpler, while the second provides greater data isolation.

![database workflow A B](https://neon.com/docs/get-started/database_workflow_AB.jpg)

## Create branch methods

You can use either the Neon CLI or GitHub actions to incorporate branching into your workflow.

### Neon CLI

Using the [Neon CLI](https://neon.com/docs/cli), you can create branches without leaving your editor or automate branch creation in your CI/CD pipeline.

And here are the key CLI actions you can use:

```bash
# Create branch
neon branches create [options]

# Get Connection string
neon connection-string [branch] [options]

# Delete branch
neon branches delete <id|name> [options]
```

For more information, see:

- [Branching with the Neon CLI](https://neon.com/docs/guides/branching-neon-cli): Learn about branching with the Neon CLI
- [Neon CLI Reference](https://neon.com/docs/cli): Reference for all commands in the Neon CLI

### GitHub Actions

If you're using GitHub Actions for your CI workflows, Neon provides GitHub Actions for [creating](https://neon.com/docs/guides/branching-github-actions#create-branch-action), [deleting](https://neon.com/docs/guides/branching-github-actions#delete-branch-action), and [resetting](https://neon.com/docs/guides/branching-github-actions#reset-from-parent-action) branches, and there's also a [schema diff action](https://neon.com/docs/guides/branching-github-actions#schema-diff-action).

**Create branch**

Here is an example of what a create branch action might look like:

```yaml
name: Create Neon Branch with GitHub Actions Demo
run-name: Create a Neon Branch 🚀
jobs:
  Create-Neon-Branch:
    uses: neondatabase/create-branch-action@v5
    with:
      project_id: rapid-haze-373089
      parent_id: br-long-forest-224191
      branch_name: from_action_reusable
      api_key: {{ secrets.NEON_API_KEY }}
    id: create-branch
  - run: echo project_id ${{ steps.create-branch.outputs.project_id}}
  - run: echo branch_id ${{ steps.create-branch.outputs.branch_id}}
```

**Delete branch**

Here is an example of what a delete branch action might look like:

```yaml
name: Delete Neon Branch with GitHub Actions
run-name: Delete a Neon Branch 🚀
on:
  push:
    branches:
      - 'production'
jobs:
  delete-neon-branch:
    uses: neondatabase/delete-branch-action@v3
    with:
      project_id: rapid-haze-373089
      branch: br-long-forest-224191
      api_key: { { secrets.NEON_API_KEY } }
```

You can find these GitHub Actions here:

- [Create branch Action](https://github.com/neondatabase/create-branch-action): Create Neon Branch GitHub Action
- [Delete Branch Action](https://github.com/neondatabase/delete-branch-action): Delete Neon Branch GitHub Action
- [Reset Branch Action](https://github.com/neondatabase/reset-branch-action): Reset Neon Branch GitHub Action
- [Schema Diff Action](https://github.com/neondatabase/schema-diff-action): Neon Schema Diff GitHub Action

For more detailed documentation, see [Automate branching with GitHub Actions](https://neon.com/docs/guides/branching-github-actions).

## A branch for every environment

Here's how you can integrate Neon branching into your workflow:

### Development

You can create a Neon branch for every developer on your team. This ensures that every developer has an isolated environment that includes schemas and data. These branches are meant to be long-lived, so each developer can tailor their branch based on their needs. With Neon's [branch reset capability](https://neon.com/docs/manage/branches#reset-a-branch-from-parent), developers can refresh their branch with the latest schemas and data anytime they need. You can invite teammates to your organization so they have access to all your projects. See [Invite members](https://neon.com/docs/manage/orgs-manage#invite-members).

**Tip:**

To easily identify branches dedicated to development, we recommend prefixing the branch name with `dev/<developer-name>` or `dev/<feature-name>` if multiple developers collaborate on the same development branch.

Examples:

```bash
dev/alice             dev/new-onboarding
```

### Preview environments

Whenever you create a pull request, you can create a Neon branch for your preview deployment. This allows you to test your code changes and SQL migrations against production-like data.

We recommend following this naming convention to identify preview branches easily:

```bash
preview/pr-<pull_request_number>-<git_branch_name>
```

Example:

```bash
preview/pr-123-feat/new-login-screen
```

**Tip: Using Managed Better Auth?**

[Managed Better Auth](https://neon.com/docs/auth/overview) is provisioned on preview branches when enabled on production. Each preview gets isolated users, sessions, and auth configuration that branches with the database. Vercel integrations set `NEON_AUTH_BASE_URL` and `VITE_NEON_AUTH_URL` automatically. See [Branching authentication](https://neon.com/docs/auth/branching-authentication) and [Neon-managed Vercel integration](https://neon.com/docs/guides/neon-managed-vercel-integration).

You can also automate branch creation for every preview. These example applications show how to create Neon branches with GitHub Actions for every preview environment.

- [Preview branches with Fly.io](https://github.com/neondatabase/preview-branches-with-fly): Sample project showing you how to create a branch for every Fly.io preview deployment
- [Preview branches with Vercel](https://github.com/neondatabase/preview-branches-with-vercel): Sample project showing you how to create a branch for every Vercel preview deployment

### Testing

When running automated tests that require a database, each test run can have its branch with its own compute resources. You can create a branch at the start of a test run and delete it at the end.

**Tip:**

We recommend following this naming convention to identify these branches easily:

```bash
test/<git_branch_name-test_run_name-commit_SHA-time_of_the_test_execution>
```

The time of the test execution can be an epoch UNIX timestamp (such as 1704305739). For example:

```bash
test/feat/new-login-loginPageFunctionality-1a2b3c4d-20240211T1530
```

You can create test branches from the same date and time or Log Sequence Number (LSN) for tests requiring static or deterministic data.

## Additional branching features

### Working with sensitive data

If you're working with sensitive data and need to avoid copying production data to development or test environments, Neon supports [schema-only branching](https://neon.com/docs/guides/branching-schema-only). This creates branches with only the database schema (tables, indexes, constraints) without any of the actual data, allowing you to populate branches with anonymized or synthetic data instead.

### Automatic branch cleanup

To prevent branch accumulation and manage resources effectively, you can set branches to automatically expire and be deleted after a specified time period. This is a good fit for temporary environments like CI/CD test branches or time-limited preview deployments. See [Branch expiration](https://neon.com/docs/guides/branch-expiration) for details on configuring automatic branch deletion.

--- [Document source](https://neon.com/docs/guides/ai-agent-integration.md) ---

> Summary: The Neon Agent Plan integration guide explains how to provision per-tenant Postgres databases, transfer projects between free and paid organizations, and implement snapshot-based database versioning using the Neon API. AI agent platform builders use this guide when embedding Neon as database infrastructure for their users, covering the full lifecycle from free-tier project creation through paid upgrades and PITR/snapshot undo workflows. Project transfers require a personal API key.

# AI Agent integration guide

Implement database provisioning and versioning for your AI agent platform

Last updated: 2026-11-04

This guide covers the technical implementation of the Neon agent plan for your platform. You'll learn how to provision databases, implement versioning, manage user upgrades, and monitor usage at scale.

> **Learn from other agent platform builders**
>
> See how [Anything manages per-agent isolation at scale](https://neon.com/blog/the-hidden-ops-layer-of-agent-platforms), [Riff built full-stack AI agents with Postgres and Auth](https://neon.com/blog/riff-neon-integration), and [Dyad implemented database versioning for AI-generated apps](https://neon.com/blog/building-versioning-for-ai-generated-apps) using Neon.

**Note:** **Prerequisites:** You must be enrolled in the [Neon Agent Plan](https://neon.com/docs/introduction/agent-plan). If you haven't applied yet, visit [Neon for AI Agent Platforms](https://neon.com/use-cases/ai-agents).

## What you'll learn

This integration guide walks through:

1. **Provisioning projects**: Creating databases for free and paid users with appropriate quotas
2. **Handling user upgrades**: Transferring projects between organizations when users change tiers
3. **Implementing database versioning**: Using PITR and snapshots for undo/redo functionality
4. **Creating development environments**: Setting up isolated branches for safe testing
5. **Monitoring and billing**: Tracking usage and configuring limits

## Before you begin

After enrolling in the [Neon Agent Plan](https://neon.com/docs/introduction/agent-plan), you should have:

- **Two Neon organization IDs**: One for Free (sponsored) projects, one for paid projects
- **Organization API keys**: For creating and managing projects in each organization
- **Personal API key**: For transferring projects between organizations
- **Admin access**: Full control over both organizations via the [Neon API](https://neon.com/docs/reference/api)

Keep your API keys secure. You'll use them for all API operations in this guide. If you do not have the API keys, see [Manage API keys](https://neon.com/docs/manage/api-keys) for how to retrieve them.

### Project-per-tenant architecture

This integration uses a **project-per-tenant model**, where each tenant (user, app, or agent) gets its own dedicated Neon [project](https://neon.com/docs/concepts/the-object-model) (containing branches, databases, roles, computes, and backend services like object storage and functions). This provides complete data and resource isolation, makes consumption limits and billing straightforward, and aligns with how the Neon API is designed. For more on this database-per-tenant approach, see [Data Isolation at Scale](https://neon.com/use-cases/database-per-tenant).

**Tip:** For details about **Agent plan** structure, pricing, and benefits, refer to the [Neon Agent Plan](https://neon.com/docs/introduction/agent-plan) docs.

**Tip: Code samples and agent skill**

The [neon-for-agent-platforms](https://github.com/neondatabase/neon-for-agent-platforms) repository provides runnable TypeScript samples for the patterns in this guide. Install the companion agent skill with the [Neon CLI](https://neon.com/docs/cli):

```bash
neon skills -s neon-postgres-agent-platforms -y
```

## Provisioning projects

When a user on your platform needs a database, create a project in the appropriate organization based on their tier:

- **Free users** → Create projects in your Free organization (sponsored by Neon; no cost to you)
- **Paid users** → Create projects in your paid organization (usage-based billing)

The two-organization structure enables you to:

1. **Offer a truly free tier**: Neon sponsors infrastructure costs for free-tier projects (unlimited projects; we incrementally raise your limit to accommodate growing usage)
2. **Scale sustainably**: Paid users consume from your credits ($0.106 per compute unit hour)
3. **Upgrade users**: Transfer projects from free to paid organizations when users upgrade
4. **Control resources**: Set different usage quotas/limits for projects to match your desired pricing model

### Project limits by organization

Each organization has different limits that apply to all projects created within it. Understanding these limits helps you design your platform's features and set appropriate user expectations. For how Agent compares to Scale, see [Agent vs Scale](https://neon.com/docs/introduction/agent-plan#agent-vs-scale).

| Limit                    | Free Organization | Paid Organization | Notes                                                                                             |
| ------------------------ | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| **Max branches**         | 10 per project    | Up to 1,000       | Includes all branches (production, development, snapshots)                                        |
| **Max manual snapshots** | 1 per project     | 100 per project   | Manual snapshots only. Automated snapshot schedules are available upon request on the Agent plan. |
| **Compute range**        | 0.25 - 2 CU       | 0.25 - 16 CU      | CU = Compute Units (\~4GB RAM per CU). Fixed sizes up to 16 CU (Scale allows up to 56 CU).        |
| **History window**       | 1 day             | Up to 7 days      | Point-in-time recovery window (Scale allows up to 30 days)                                        |
| **Min auto-suspend**     | 5 minutes         | 1 minute          | Minimum time before compute suspends                                                              |

**Key constraints to consider:**

- **Manual snapshot limits**: Free projects can only maintain 1 manual snapshot at a time, while paid projects can keep up to 100. Automated snapshot schedules are available upon request on the Agent plan.
- **Branch limits**: Free projects are limited to 10 branches total, so you'll need to implement cleanup for development branches and temporary snapshots. Paid projects support up to 1,000 branches.
- **Compute limits**: Free projects can autoscale up to 2 CU, while paid projects can scale up to 16 CU for more demanding workloads.

For detailed quota examples and consumption limits, see [Configure consumption limits](https://neon.com/docs/guides/consumption-limits).

### Creating projects for free-tier users

For free-tier users, create projects in your Free organization (sponsored by Neon) with resource quotas matching (or within) Neon's Free plan limits using the [Create project](https://neon.com/docs/reference/api/projects/create-project) API:

| Resource          | Free Tier Quota    | Description                              |
| ----------------- | ------------------ | ---------------------------------------- |
| **Compute**       | 0.25 / 2 CU        | Autoscales from 0.25 to 2 compute units  |
| **Active time**   | `360000` seconds   | 100 hours of compute activity per month  |
| **Storage**       | `1073741824` bytes | 1 GB total storage limit                 |
| **Data transfer** | `5368709120` bytes | 5 GB data transfer per project per month |

Example API request:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $FREE_ORG_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "name": "user-free-database",
    "pg_version": 16,
    "settings": {
      "quota": {
        "active_time_seconds": 360000,
        "logical_size_bytes": 1073741824,
        "data_transfer_bytes": 5368709120
      }
    },
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 2,
      "suspend_timeout_seconds": 300
    }
  }
}'
```

### Creating projects for paid users

For paid users, create projects in your paid organization with higher resource quotas and autoscaling enabled. You can create multiple tiers within your paid organization to match your pricing model.

#### Example: Pro tier

| Resource             | Pro Tier Quota      | Description                             |
| -------------------- | ------------------- | --------------------------------------- |
| **Compute**          | 0.25 / 2 CU         | Autoscales from 0.25 to 2 compute units |
| **Active time**      | `2700000` seconds   | 750 hours of compute activity per month |
| **Postgres storage** | `10737418240` bytes | 10 GB Postgres storage limit            |
| **Data transfer**    | `53687091200` bytes | 50 GB data transfer per month           |

Example API request:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $PAID_ORG_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "name": "user-paid-database",
    "pg_version": 16,
    "settings": {
      "quota": {
        "active_time_seconds": 2700000,
        "logical_size_bytes": 10737418240,
        "data_transfer_bytes": 53687091200
      }
    },
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 2,
      "suspend_timeout_seconds": 300
    }
  }
}'
```

**Tip:** **Creating multiple paid tiers:** You can define different quota levels within your paid organization to match your platform's pricing tiers (for example, Pro, Business, Enterprise). Simply adjust the quota values and compute limits for each tier.

For detailed information about configuring quotas and what happens when limits are reached, see [Configure consumption limits](https://neon.com/docs/guides/consumption-limits).

### Provisioning timing and user experience

Project provisioning is near-instant (typically under 1 second), but consider these timing factors:

1. **Project creation**: Returns immediately with project details
2. **Compute activation**: First connection after the compute has been idle can take a few hundred milliseconds longer while it wakes
3. **Subsequent connections**: Near-instant once compute is active

For the best user experience:

- Create projects asynchronously when users sign up or request a database
- Store the connection string immediately
- Show a "setting up your database" message during first connection
- After initial startup, subsequent connections are immediate

**Tip:** **Store project metadata:** Save the project ID, organization ID, connection strings, and tier information in your database to associate them with your users. You'll need these for all future operations and billing.

### Getting connection strings

After creating a project, retrieve the database connection string to give to your users using the [Retrieve connection URI](https://neon.com/docs/reference/api/projects/get-connection-uri) API:

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/connection_uri?database_name=neondb&role_name=neondb_owner' \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY"
```

The connection string format is:

```
postgres://[role]:[password]@[endpoint]/[database]?sslmode=require
```

### What's created automatically

Each new project includes:

- **One default branch**: Named `main` by default
- **One database**: Named `neondb` by default
- **One role**: Named `neondb_owner` with full privileges
- **One compute endpoint**: Configured with your specified settings

Using the [Create project](https://neon.com/docs/reference/api/projects/create-project) API, you can customize these defaults during project creation or create additional databases, roles, and branches as needed.

## Handling user upgrades

When a free user upgrades to a paid plan, transfer their project from the Free organization (sponsored) to the paid organization. This preserves all their data, branches, and configuration while moving them to your paid tier with higher quotas.

### Transferring projects between organizations

Project transfers between the two organizations in your agent plan require a **personal API key** rather than an organization API key. This is because:

- As an agent plan participant, you're an admin member of both your Free (sponsored) and paid organizations
- Personal API keys have access to all organizations you belong to
- Organization API keys only work within a single organization
- Transfers need to authenticate against both the source and destination organizations

Use your personal API key with the [Transfer project](https://neon.com/docs/reference/api/projects/create-project-transfer-request) API to transfer projects:

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project_id}/transfer \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $PERSONAL_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "target_org_id": "<paid-org-id>"
}'
```

### Updating quotas after transfer

After transferring a project to your paid organization, update the resource quotas to match the user's new tier using the [Update project](https://neon.com/docs/reference/api/projects/update-project) API:

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project_id} \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $PAID_ORG_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "settings": {
      "quota": {
        "active_time_seconds": 720000,
        "compute_time_seconds": 2880000
      }
    },
    "default_endpoint_settings": {
      "autoscaling_limit_max_cu": 4
    }
  }
}'
```

**Tip:** **Transfer limits:** You can transfer up to 400 projects per API request. To create a personal API key, see [Create a personal API key](https://neon.com/docs/manage/api-keys#create-a-personal-api-key).

For more details, see [Transfer projects between organizations](https://neon.com/docs/manage/orgs-project-transfer).

### Handling downgrades

When a paid user downgrades to your free tier, transfer their project from the paid organization to the Free organization (sponsored) using the same personal API key:

```bash
# Transfer to Free organization (sponsored)
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project_id}/transfer \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $PERSONAL_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "target_org_id": "<free-org-id>"
}'
```

Then update quotas to match free tier limits:

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project_id} \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $FREE_ORG_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "settings": {
      "quota": {
        "active_time_seconds": 360000,
        "logical_size_bytes": 1073741824,
        "data_transfer_bytes": 5368709120
      }
    },
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 2
    }
  }
}'
```

**Important:** **Check usage before downgrading:** If a user's current usage exceeds free tier limits, notify them and give them options to either reduce their database size or stay on a paid plan.

## Implementing database versioning

AI agents and codegen platforms need robust database versioning to manage schema evolution and enable undo/redo functionality. Neon provides two complementary approaches:

### Point-in-time recovery (PITR)

Use PITR for recent history. The [history window](https://neon.com/docs/introduction/history-window) differs between your two organizations:

- **Free organization (sponsored by Neon)**: 1 day of point-in-time history (included at no charge)
- **Paid organization**: Up to 7 days of point-in-time history (billed at $0.20/GB-month for change history)
- **Instant restore**: Restore a database to any point in time that still falls within the **history window** (typically seconds using Neon's instant restore).

The Free organization provides 1 day of history for **instant restore**, while the Paid organization provides up to 7 days. Factor these limits into your platform's feature offerings and set appropriate user expectations for each tier.

Example creating a branch from 2 hours ago using the [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch) API:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "branch": {
    "name": "restored-state",
    "parent_id": "{parent_branch_id}",
    "parent_timestamp": "2024-11-05T14:00:00Z"
  }
}'
```

### Snapshots for longer retention

Use snapshots (branches) for versions you want to keep beyond the [history window](https://neon.com/docs/introduction/history-window):

- **Persistent versions**: Keep snapshots as long as needed
- **Named versions**: Give meaningful names to important database states
- **Storage cost**: Snapshots count toward storage usage
- **Manual snapshot limits**: Free projects: 1 manual snapshot max; Paid projects: 100 manual snapshots max (on paid plans, scheduled backup snapshots do not count)

**Important:** **Manual snapshot limits:** Free organization projects can only maintain **1 manual snapshot at a time**. If you need to create a new snapshot, you must delete the existing one first. Paid organization projects can maintain up to **100 manual snapshots** simultaneously. On paid plans, snapshots created by backup schedules do not count toward this limit. Design your versioning UI accordingly.

**Pricing:** Snapshot storage is billed at $0.09/GB-month.

Example creating a snapshot:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "branch": {
    "name": "v1.0-stable",
    "parent_id": "{parent_branch_id}"
  }
}'
```

**Tip:** Learn how our Developer Advocate approaches snapshot-based workflows in [Promoting Postgres changes safely to production](https://neon.com/blog/promoting-postgres-changes-safely-production).

### When to use each approach

| Use Case                        | Recommended Method   | Why                                                          |
| ------------------------------- | -------------------- | ------------------------------------------------------------ |
| **Undo recent changes**         | PITR (point-in-time) | Instant restore, automatic history (1 day to 7 days)         |
| **Save before major migration** | Snapshot (branch)    | Persist beyond PITR window, named versions, explicit control |
| **Daily automated backups**     | PITR (built-in)      | Already available, no action needed                          |
| **Release versions**            | Snapshot (branch)    | Keep indefinitely, tag with version numbers                  |
| **Experiment/test safely**      | Development branch   | Isolated, can be deleted after testing                       |

### Recommended approach

Combine both methods for the best user experience:

1. **Use PITR for recent history**: Fast, automatic undo/redo (1 day for Free tier, up to 7 days for Paid tier)
2. **Create snapshots for milestones**: Preserve important versions (releases, working states) as branches
3. **Manage manual snapshot limits**: Free tier users can only keep 1 manual snapshot; implement a "replace snapshot" workflow. Paid tier users get 100 manual snapshots (on paid plans, scheduled backup snapshots do not count toward this limit).
4. **Set user expectations**: Explain that recent history restores instantly, older versions may take longer
5. **Automate cleanup**: Delete old snapshots that are no longer needed to control storage costs and stay within limits

For more details on using snapshots, see [Database versioning for AI agents](https://neon.com/docs/ai/ai-database-versioning).

## Creating development environments

Agent platforms can give each user completely isolated development environments alongside their production database.

### The development workflow

For each user project, you can create:

1. **Production branch**: The main branch with live data
2. **Development branches**: Isolated copies for testing, development, and experimentation

Development branches are:

- **Instant to create**: Copy-on-write means instant branch creation
- **Fully isolated**: Separate compute, no impact on production
- **Cost-efficient**: Only pay for storage differences and actual compute usage
- **Easy to reset**: Restore development branch to match production anytime

**Note:** **Branch limits:** Remember that Free organization projects have a **10 branch maximum** (including main branch, development branches, and snapshots), while Paid organization projects support **up to 1,000 branches** (see [Agent plan pricing](https://neon.com/docs/introduction/agent-plan#pricing)). Implement branch cleanup for temporary development branches to stay within limits.

Example creating a development branch using the [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch) API:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "branch": {
    "name": "development",
    "parent_id": "{main_branch_id}"
  },
  "endpoints": [{
    "type": "read_write",
    "autoscaling_limit_min_cu": 0.25,
    "autoscaling_limit_max_cu": 2,
    "suspend_timeout_seconds": 300
  }]
}'
```

### Compute suspension settings

Control when development branch computes scale to zero:

- **Set to `0`**: Uses the default suspension timeout (300 seconds)
- **Positive integer** (for example, `600`): Custom timeout in seconds before scaling to zero
- **Set to `-1`**: Disables suspension entirely (compute always on, higher costs)

For development branches, a 5-minute timeout (300 seconds) balances cost efficiency with user experience.

This workflow prevents common issues like development data contaminating production databases, while giving users a safe space to experiment without risk.

## Monitoring and billing

### Track usage per project

You can use the Neon API to retrieve consumption metrics for your organizations and projects using the [Get consumption metrics for each project](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project) endpoint, which provides detailed metrics per project at hourly, daily, or monthly granularity.

Available metrics:

- `active_time_seconds`: Compute active time
- `compute_time_seconds`: CPU seconds consumed
- `written_data_bytes`: Data written to all branches
- `synthetic_storage_size_bytes`: Total storage used

**Tip:** On usage-based plans (Launch, Scale, Agent, Enterprise), you can also use the v2 endpoints, which return invoice-aligned metrics. The [project metrics endpoint](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project-v2) (`GET /consumption_history/v2/projects`) returns billing-aligned totals per project. The [branch metrics endpoint](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-branch-v2) (`GET /consumption_history/v2/branches`) breaks those metrics down by branch — useful for attributing usage to individual CI or development branches. See [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics).

For complete details on parameters, pagination, response formats, and metric definitions, see [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics).

### Configure consumption limits

Set consumption limits per project to control costs. You can configure these limits during [project creation](https://neon.com/docs/guides/ai-agent-integration#provisioning-projects) (as shown in the examples above) or update them later using the [Update project](https://neon.com/docs/reference/api/projects/update-project) API:

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project_id} \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "settings": {
      "quota": {
        "active_time_seconds": 108000,
        "compute_time_seconds": 108000,
        "written_data_bytes": 10000000000,
        "logical_size_bytes": 5000000000
      }
    }
  }
}'
```

See [Configure consumption limits](https://neon.com/docs/guides/consumption-limits) for details.

## Best practices

- **Project naming**: Use consistent naming to track ownership and tier (for example, `myapp-username-free-tier-timestamp`, `myapp-username-paid-tier-timestamp`).
- **Monitor quotas**: Alert users at 80% and 95% of consumption limits. See [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics).
- **Retry logic**: Implement exponential backoff for API calls to handle rate limits and transient failures.
- **Project deletion**: Delete immediately when users request it; warn before removing inactive projects; offer final snapshots.
- **Connection pooling**: Provide [pooled database connection strings](https://neon.com/docs/connect/connection-pooling) by default for bursty workloads.
- **Reserved names**: Avoid [reserved role names](https://neon.com/docs/manage/roles#reserved-role-names) and [database names](https://neon.com/docs/manage/databases#reserved-database-names).

## API and SDKs

All platform integrations use the Neon API. You can call it directly or use language-specific SDKs:

- **[Neon API](https://neon.com/docs/reference/api)**: All operations (projects, branches, databases, monitoring) are API-driven; language-agnostic REST interface. Agent plan participants receive higher rate limits optimized for high-volume operations.
- **SDKs**: [Neon Management SDK](https://neon.com/docs/reference/typescript-sdk), [Python SDK](https://neon.com/docs/reference/python-sdk). See [Neon SDKs](https://neon.com/docs/reference/sdk) for all options.

## Cost management

- **Free organization**: No charges to you for free-tier projects (Neon-sponsored). Project limits are unlimited; we incrementally raise your limit to accommodate growing usage.
- **Paid organization**: Usage-based billing at $0.106 per compute unit hour, covered by your initial credits. See [Agent plan pricing](https://neon.com/docs/introduction/agent-plan#pricing).
- **Monitor usage**: Track `active_time_seconds`, `compute_time_seconds`, `written_data_bytes`, `synthetic_storage_size_bytes` using [project metrics API](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project). Poll every 15 minutes; doesn't wake computes. See [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics).
- **Set quotas**: Configure usage limits during [project creation](https://neon.com/docs/guides/ai-agent-integration#provisioning-projects) or update later. See [Configure consumption limits](https://neon.com/docs/guides/consumption-limits).
- **Optimize costs**: Set shorter `suspend_timeout_seconds` (5 min) for free tier computes; cap `autoscaling_limit_max_cu` per tier to limit compute size scaling; cleanup old branches/snapshots to save on storage; alert your users at 80%/95% usage thresholds; right-size compute size ranges when creating projects for your users.

## Troubleshooting common issues

- **Project transfer fails with 403 error**: Using an organization API key instead of a personal API key. Project transfers between your Free (sponsored) and paid organizations require a personal API key because it has access to both organizations. Organization API keys only work within a single organization. Generate a personal API key in the Neon console under **Account settings** > **Developer settings**. See [Create a personal API key](https://neon.com/docs/manage/api-keys#create-a-personal-api-key).

- **Users hit quota limits unexpectedly**: Autoscaling can consume compute time faster than anticipated. Set `autoscaling_limit_max_cu` appropriately for each tier, monitor consumption metrics and alert users at 80% threshold, and consider lowering `suspend_timeout_seconds` for free tier to reduce active time.

- **First database connection is slow**: Compute needs to start from idle state (cold start). This is expected behavior for serverless compute: the first connection after the compute has been idle can take a few hundred milliseconds longer while it wakes. Set user expectations accordingly. For critical production endpoints, use `suspend_timeout_seconds: -1` to keep compute always on. Subsequent connections are near-instant.

- **Storage grows larger than expected**: Multiple branches or snapshots accumulate over time. Implement branch cleanup for old development branches, delete snapshots that are no longer needed, and monitor storage metrics to alert users approaching limits.

## Support

As an Neon Agent Plan participant, you have access to:

- **Dedicated Slack channel**: Direct access to the Neon team for technical questions
- **Your Neon representative**: Contact them for rate limit adjustments, limit increases, or custom needs
- **Priority support**: Faster response times for platform-critical issues

For immediate help, reach out through your dedicated Slack channel.

--- [Document source](https://neon.com/docs/guides/askyourdatabase.md) ---

> Summary: AskYourDatabase is a natural language SQL client that connects to Lakebase Postgres so users can query, visualize, and manage data by typing plain English instead of writing SQL. Use this guide to set up the connection via a Neon connection string and start chatting with your database in the AskYourDatabase desktop app. The guide also covers embedding a customer-facing chatbot powered by Lakebase Postgres directly into a website.

# Chat with Lakebase Postgres with AskYourDatabase

Chat with your Lakebase Postgres database without writing SQL

Last updated: 2026-07-31

AskYourDatabase is the ChatGPT for SQL databases, enabling you to interact with your SQL databases using natural language. You can use it for data management, business intelligence, schema design & migration, data visualization, and more. To learn more, see [AskYourDatabase](https://www.askyourdatabase.com/).

This guide shows how to connect from AskYourDatabase to Lakebase Postgres.

## Prerequisites

- AskYourDatabase Desktop app. See [Download AskYourDatabase](https://www.askyourdatabase.com/download).
- A Neon project. See [Create a Neon project](https://neon.com/docs/manage/projects#create-a-project).

## Connect to Neon from AskYourDatabase

1. Get the Neon URL by navigating to the Neon Console and copying the connection string. The URL will look something like this:

   ```text
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

2. Go to AskYourDatabase and click **Connect to your database**:
   ![Connect to new db](https://neon.com/docs/guides/askyourdatabase_connect_neon_1.png)

3. Select PostgreSQL as your database type, and paste your connection string:

   ![Paste connection string](https://neon.com/docs/guides/askyourdatabase_connect_neon_2.png)

4. A new chat session opens if the connection is successful:

   ![New chat session](https://neon.com/docs/guides/askyourdatabase_connect_neon_3.png)

## Chat with your data

Within the chat session, you can start asking your database questions.

For example, suppose you have a `user` table with a column named `dbType` that indicates the type of database.

If you want to know what the four most popular databases are and visualize the distribution in a pie chart, you can quickly and easily do so with a natural language question, as shown below:

![Chat with Neon](https://neon.com/docs/guides/askyourdatabase_ask_neon.png)

## What's more

AskYourDatabase also supports a customer-facing chatbot that can connect to a Lakebase Postgres database. You can embed the chatbot in your existing website, enabling your customers to explore analytics data by asking questions in natural language. To learn more, see [Create and Integrate Chatbot](https://www.askyourdatabase.com/docs/chatbot), in the AskYourDatabase documentation.

--- [Document source](https://neon.com/docs/guides/astro.md) ---

> Summary: Connecting Astro to Lakebase Postgres requires the Astro Node adapter for on-demand (SSR) rendering so pages query the database at request time rather than only at build time. The guide covers driver options including node-postgres, postgres.js, and the Neon serverless driver, and shows query patterns for both .astro page components and server endpoint API routes.

# Connect Astro to Postgres on Neon

Learn how to make server-side queries to Postgres from .astro files or API routes.

Last updated: 2026-09-16

Pre-built prompt for connecting Astro to Neon using the Neon serverless driver [View prompt](https://neon.com/prompts/astro-serverless-prompt.md)

Astro is a web framework for content sites, web applications, and server APIs. This guide describes how to create a database on Neon and query it from an Astro site or application at request time.

To create a Neon project and access it from an Astro site or application:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create an Astro project and add dependencies

1. Create an Astro project if you do not have one, for example with `npm create astro@latest`. For instructions, see [Getting Started](https://docs.astro.build/en/getting-started/) in the Astro documentation.

2. Add project dependencies using one of the following commands:

   **node-postgres**

   ```shell
   npm install pg
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless
   ```

## Enable on-demand rendering

Astro needs an adapter and server output to query your database at request time. Add the Node adapter:

```shell
npx astro add node
```

Then set `output: 'server'` in `astro.config.mjs` so every page and endpoint uses [on-demand rendering](https://docs.astro.build/en/guides/on-demand-rendering/) (also known as server-side rendering or SSR):

```javascript filename="astro.config.mjs"
// @ts-check
import { defineConfig, envField } from 'astro/config';

import node from '@astrojs/node';

// https://astro.build/config
export default defineConfig({
  output: 'server',
  adapter: node({
    mode: 'standalone',
  }),
  env: {
    schema: {
      DATABASE_URL: envField.string({ context: 'server', access: 'secret' }),
    },
  },
});
```

The `env.schema` entry declares `DATABASE_URL` as a server-only secret. Astro reads secrets from the environment at runtime instead of copying them into the build output, so your password doesn't end up in `dist/`. For more, see [Type-safe environment variables](https://docs.astro.build/en/guides/environment-variables/#type-safe-environment-variables) in the Astro documentation.

**Note:** The adapter alone isn't enough. Astro's default output is `static`, so without `output: 'server'`, `npm run build` prerenders your pages and API routes at build time and production serves the build-time results. To render only some routes on demand, keep the default and add `export const prerender = false;` to those pages and endpoints. Development mode (`npm run dev`) renders every request, so you won't see the difference until you build.

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection string to it. You can find the connection string for your database by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

If you use node-postgres, `pg` 8.23 and later print a `SECURITY WARNING` for `sslmode=require`. Change it to `sslmode=verify-full` to keep the same behavior without the warning.

## Create a database utility

Create a reusable database client that you can import throughout your application. This approach centralizes your database configuration and follows best practices for code organization.

Create a new file at `src/lib/neon.ts` (or `src/lib/neon.js`) with the following code:

**node-postgres**

```typescript
import { Pool } from 'pg';
import { DATABASE_URL } from 'astro:env/server';

export const pool = new Pool({
  connectionString: DATABASE_URL,
  ssl: true,
});
```

**postgres.js**

```typescript
import postgres from 'postgres';
import { DATABASE_URL } from 'astro:env/server';

export const sql = postgres(DATABASE_URL, { ssl: 'require' });
```

**Neon serverless driver**

```typescript
import { neon } from '@neondatabase/serverless';
import { DATABASE_URL } from 'astro:env/server';

export const sql = neon(DATABASE_URL);
```

## Configure the Postgres client

There are multiple ways to make server side requests with Astro. See below for two of those options: **Page Components (.astro files)** and **Server Endpoints (API Routes)**.

### Page Components (.astro files)

In your `.astro` page components (for example, `src/pages/index.astro`), you can query the database in the frontmatter section (between the `---` fences). Import the database client from your utility file:

**node-postgres**

```astro
---
import { pool } from '../lib/neon';

const client = await pool.connect();

let data = null;

try {
  const response = await client.query('SELECT version()');
  data = response.rows[0].version;
} finally {
  client.release();
}
---

{data}
```

**postgres.js**

```astro
---
import { sql } from '../lib/neon';

const response = await sql`SELECT version()`;
const data = response[0].version;
---

{data}
```

**Neon serverless driver**

```astro
---
import { sql } from '../lib/neon';

const response = await sql`SELECT version()`;
const data = response[0].version;
---

{data}
```

**Note:** You can also initialize the database connection directly in each `.astro` file, but using a shared utility file is recommended for maintainability and code organization.

#### Run the app

When you run `npm run dev` you can expect to see something like the following when you visit `localhost:4321`:

```shell
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

### Server Endpoints (API Routes)

In your server endpoints (API routes), import the database client from your utility file. Create `src/pages/api/index.ts`:

**node-postgres**

```typescript filename="src/pages/api/index.ts"
import { pool } from '../../lib/neon';

export async function GET() {
  const client = await pool.connect();
  let data = {};
  try {
    const { rows } = await client.query('SELECT version()');
    data = rows[0];
  } finally {
    client.release();
  }
  return new Response(JSON.stringify(data), { headers: { 'Content-Type': 'application/json' } });
}
```

**postgres.js**

```typescript filename="src/pages/api/index.ts"
import { sql } from '../../lib/neon';

export async function GET() {
  const response = await sql`SELECT version()`;
  return new Response(JSON.stringify(response[0]), {
    headers: { 'Content-Type': 'application/json' },
  });
}
```

**Neon serverless driver**

```typescript filename="src/pages/api/index.ts"
import { sql } from '../../lib/neon';

export async function GET() {
  const response = await sql`SELECT version()`;
  return new Response(JSON.stringify(response[0]), {
    headers: { 'Content-Type': 'application/json' },
  });
}
```

#### Run the app

When you run `npm run dev` you can expect to see something like the following when you visit the `localhost:4321/api` route:

```json
{"version":"PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit"}
```

To run the production build, run `npm run build`, then start the server with `DATABASE_URL` set in its environment. For example, load it from your `.env` file with Node's `--env-file` option (Node 20.6 or later):

```shell
node --env-file=.env ./dist/server/entry.mjs
```

The server listens on port 4321 by default; set the `PORT` environment variable to change it. With `output: 'server'`, each request queries your database. If `DATABASE_URL` isn't set, Astro fails the request with an `EnvInvalidVariables` error.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/auth-auth0.md) ---

> Summary: Auth0 integration guide for Next.js apps using Lakebase Postgres, walking through the full setup of the @auth0/nextjs-auth0 SDK, Drizzle ORM schema and migrations, and storing per-user rows in a Postgres table keyed by Auth0 user IDs. Choose this guide when you need social login, multi-factor authentication, or Auth0-managed users in a Lakebase database. The tutorial covers Auth0 application configuration, callback URLs, session handling with the Auth0 client and Next.js proxy, and Next.js server actions for inserting and deleting user data.

# Authenticate Lakebase Postgres application users with Auth0

Learn how to add authentication to a Lakebase Postgres database application using Auth0

Last updated: 2026-09-16

**Tip: Building on Neon?**

Neon provides [Managed Better Auth](https://neon.com/docs/auth/overview), a managed authentication service built on Better Auth that stores users, sessions, and auth configuration directly in your Neon database. Auth state **branches with your data**, so preview and CI environments get isolated users and sessions.

User authentication is an essential part of most web applications. Modern apps often require features like social login, multi-factor authentication, and secure user data management that complies with privacy regulations.

[Auth0](https://auth0.com/) is an authentication and authorization platform that provides these features out of the box. It offers SDKs for popular web frameworks, making it straightforward to integrate with your application backed by a Lakebase Postgres database.

In this guide, we'll walk through setting up a simple Next.js application using Lakebase Postgres as the database, and add user authentication using [Auth0](https://auth0.com/). We will cover how to:

- Set up a Next.js project with Auth0 for authentication
- Create a database on Neon and connect it to your application
- Define a database schema using Drizzle ORM and generate migrations
- Store and retrieve user data associated with Auth0 user IDs

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- An [Auth0](https://auth0.com/) account for user authentication. Auth0 provides a free plan to get started.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.

## Initialize your Next.js project

We will create a simple web app that lets you add a favorite quote to the home page, and edit it afterward. Run the following command in your terminal to create a new `Next.js` project:

```bash
npx create-next-app guide-neon-next-auth0 --typescript --eslint --tailwind --use-npm --no-src-dir --app --import-alias "@/*"
```

Now, navigate to the project directory and install the required dependencies:

```bash
npm install @neondatabase/serverless drizzle-orm
npm install -D drizzle-kit dotenv
npm install @auth0/nextjs-auth0
```

We use the `@neondatabase/serverless` package as the Postgres client, and `drizzle-orm`, a lightweight typescript ORM, to interact with the database. `@auth0/nextjs-auth0` is the Auth0 SDK for Next.js applications. We also use `dotenv` to manage environment variables and the `drizzle-kit` CLI tool for generating database migrations.

Also, add a `.env.local` file to the root of your project, which we'll use to store Neon/Auth0 connection parameters:

```bash
touch .env.local
```

This guide uses version 4 of `@auth0/nextjs-auth0` and Next.js 16.

Now, we can start building the application.

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select an existing project or click the **New Project** button to create a new one.
3. Choose the desired region and Postgres version for your project, then click **Create Project**.

### Retrieve your Neon database connection string

You can find your connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Add this connection string to the `.env.local` file in your Next.js project.

```bash
# .env.local

DATABASE_URL=NEON_DB_CONNECTION_STRING
```

## Configuring Auth0 for authentication

### Create an Auth0 application

1. Log in to your Auth0 account and navigate to the [Dashboard](https://manage.auth0.com/dashboard/). From the left sidebar, select `Applications > Create Application` to create a new app.
2. In the dialog that appears, provide a name for your application, select `Regular Web Applications` as the application type, and click `Create`.

### Configure Auth0 application settings

1. In the `Settings` tab of your Auth0 application, scroll down to the `Application URIs` section.
2. Set the `Allowed Callback URLs` to `http://localhost:3000/auth/callback` for local development.
3. Set the `Allowed Logout URLs` to `http://localhost:3000`.
4. Click `Save Changes` at the bottom of the page.

### Retrieve your Auth0 domain and client ID

From the `Settings` tab of your Auth0 application, copy the `Domain` and `Client ID` values. Add these to the `.env.local` file in your Next.js project:

```bash
# .env.local

AUTH0_DOMAIN='YOUR_AUTH0_DOMAIN'
AUTH0_CLIENT_ID='YOUR_AUTH0_CLIENT_ID'
AUTH0_CLIENT_SECRET='YOUR_AUTH0_CLIENT_SECRET'
AUTH0_SECRET='random-32-byte-value'
APP_BASE_URL='http://localhost:3000'
```

Replace `YOUR_AUTH0_DOMAIN`, `YOUR_AUTH0_CLIENT_ID` and `YOUR_AUTH0_CLIENT_SECRET` with the actual values from your Auth0 application settings. Set `AUTH0_DOMAIN` to the domain only, without `https://` (for example, `dev-abc123.us.auth0.com`).

Run the following command in your terminal to generate a random 32-byte value for the `AUTH0_SECRET` variable:

```bash
node -e "console.log(crypto.randomBytes(32).toString('hex'))"
```

## Implementing the application

### Define your database connection and schema

Create a `db` folder inside the `app/` directory. This is where we'll define the database schema and connection code.

Now, add the file `app/db/index.ts` with the following content:

```typescript
/// app/db/index.ts

import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import { UserMessages } from './schema';

if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL must be a Neon postgres connection string');
}

const sql = neon(process.env.DATABASE_URL);

export const db = drizzle(sql, {
  schema: { UserMessages },
});
```

This exports a `db` instance that we can use to execute queries against the Neon database.

Next, create a `schema.ts` file inside the `app/db` directory to define the database schema:

```typescript
/// app/db/schema.ts

import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const UserMessages = pgTable('user_messages', {
  user_id: text('user_id').primaryKey().notNull(),
  createTs: timestamp('create_ts').defaultNow().notNull(),
  message: text('message').notNull(),
});
```

This schema defines a table `user_messages` to store a message for each user, with the `user_id` provided by Auth0 as the primary key.

### Generate and run migrations

We'll use the `drizzle-kit` CLI tool to generate migrations for the schema we defined. To configure how it connects to the database, add a `drizzle.config.ts` file at the project root.

```typescript
/// drizzle.config.ts

import type { Config } from 'drizzle-kit';
import * as dotenv from 'dotenv';

dotenv.config({ path: '.env.local' });

if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL not found in environment');

export default {
  schema: './app/db/schema.ts',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL,
  },
  strict: true,
} satisfies Config;
```

Now, generate the migration files by running the following command:

```bash
npx drizzle-kit generate
```

This will create a `drizzle` folder at the project root with the migration files. To apply the migration to the database, run:

```bash
npx drizzle-kit push
```

The `user_messages` table will now be visible in the console.

### Configure Auth0 authentication

First, create an Auth0 client that the rest of the application uses to read sessions. Add the file `lib/auth0.ts` at the project root:

```typescript
/// lib/auth0.ts

import { Auth0Client } from '@auth0/nextjs-auth0/server';

export const auth0 = new Auth0Client();
```

The client reads its configuration from the `AUTH0_*` and `APP_BASE_URL` environment variables you set earlier.

Next, add a `proxy.ts` file at the project root. The Auth0 SDK uses it to mount the authentication routes at `/auth/login`, `/auth/logout`, `/auth/callback`, and `/auth/profile`, and to keep sessions up to date:

```typescript
/// proxy.ts

import type { NextRequest } from 'next/server';
import { auth0 } from './lib/auth0';

export async function proxy(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)'],
};
```

**Note:** Next.js 16 renamed `middleware.ts` to `proxy.ts`. On Next.js 15 or earlier, name the file `middleware.ts` and export the function as `middleware` instead of `proxy`.

You don't need a route file for the authentication endpoints. The proxy handles them.

Now, show the logged-in user's name and a logout link on every page. Replace the contents of the `app/layout.tsx` file with the following:

```tsx
/// app/layout.tsx

import type { Metadata } from 'next';
import { Suspense } from 'react';
import { Inter } from 'next/font/google';
import './globals.css';
import { auth0 } from '@/lib/auth0';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Neon-Next-Auth0 guide',
  description: 'Generated by create next app',
};

async function UserInfoBar() {
  const session = await auth0.getSession();
  if (!session) {
    return null;
  }

  const { user } = session;
  return (
    <div className="bg-gray-100 px-4 py-2">
      <span className="text-gray-800">
        Welcome, {user.name}!{' '}
        <a href="/auth/logout" className="text-blue-600 hover:underline">
          Logout
        </a>
      </span>
    </div>
  );
}

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Suspense fallback={null}>
          <UserInfoBar />
          {children}
        </Suspense>
      </body>
    </html>
  );
}
```

New Next.js 16 projects enable `cacheComponents`, which requires anything that reads request data, such as the session cookie, to render inside `<Suspense>`. Without it, `npm run build` fails with a prerendering error.

### Add interactivity to the application

Our application has a single page that lets the logged-in user store their favorite quote and displays it. We implement `Next.js` server actions to handle the form submission and database interaction.

Create a new file at `app/actions.ts` with the following content:

```typescript
/// app/actions.ts

'use server';

import { auth0 } from '@/lib/auth0';
import { UserMessages } from './db/schema';
import { db } from './db';
import { redirect } from 'next/navigation';
import { eq } from 'drizzle-orm';

export async function createUserMessage(formData: FormData) {
  const session = await auth0.getSession();
  if (!session) throw new Error('User not authenticated');

  const message = formData.get('message') as string;

  await db.insert(UserMessages).values({
    user_id: session.user.sub,
    message,
  });

  redirect('/');
}

export async function deleteUserMessage() {
  const session = await auth0.getSession();
  if (!session) throw new Error('User not authenticated');

  await db.delete(UserMessages).where(eq(UserMessages.user_id, session.user.sub));
  redirect('/');
}
```

The `createUserMessage` function inserts a new message into the `user_messages` table, while `deleteUserMessage` removes the message associated with the current user.

Next, we implement a minimal UI to interact with these functions. Replace the contents of the `app/page.tsx` file with the following:

```tsx
/// app/page.tsx

import { createUserMessage, deleteUserMessage } from './actions';
import { db } from './db';
import { auth0 } from '@/lib/auth0';

async function getUserMessage() {
  const session = await auth0.getSession();
  if (!session) return null;

  return db.query.UserMessages.findFirst({
    where: (messages, { eq }) => eq(messages.user_id, session.user.sub),
  });
}

function LoginBox() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <a
        href="/auth/login"
        className="text-gray-800 rounded-md bg-[#00E699] px-3.5 py-2.5 text-sm font-semibold shadow-sm hover:bg-[#00e5BF] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[#00E699]"
      >
        Log in
      </a>
    </main>
  );
}

export default async function Home() {
  const session = await auth0.getSession();
  const existingMessage = await getUserMessage();

  if (!session) {
    return <LoginBox />;
  }

  const ui = existingMessage ? (
    <div className="w-2/3 text-center">
      <h1 className="text-3xl">{existingMessage.message}</h1>
      <form action={deleteUserMessage} className="mb-4 w-full rounded px-8 pb-8 pt-6">
        <div className="w-full text-center">
          <input
            type="submit"
            value={'Delete Quote'}
            className="text-gray-800 cursor-pointer rounded bg-[#00E699] px-4 py-2 font-semibold transition-colors hover:bg-[#00e5BF] focus:outline-none"
          />
        </div>
      </form>
    </div>
  ) : (
    <form action={createUserMessage} className="w-2/3 rounded px-8 shadow-md">
      <div className="mb-6">
        <input
          type="text"
          name="message"
          placeholder="Mistakes are the portals of discovery - James Joyce"
          className="text-gray-700 w-full appearance-none rounded border p-3 text-center leading-tight focus:outline-none"
        />
      </div>
      <div className="w-full text-center">
        <input
          type="submit"
          value={'Save Quote'}
          className="text-gray-800 cursor-pointer rounded bg-[#00E699] px-4 py-2 font-semibold transition-colors hover:bg-[#00e5BF] focus:outline-none"
        />
      </div>
    </form>
  );

  return (
    <main className="align-center -mt-16 flex min-h-screen flex-col items-center justify-center px-24">
      <h2 className="text-gray-400 pb-6 text-2xl">
        {existingMessage ? 'Your quote is wonderful...' : 'Save an inspiring quote for yourself...'}
      </h2>
      {ui}
    </main>
  );
}
```

This implements a form with a single text field that lets the user input a quote, and submit it, whereby it gets stored in the database, associated with their `Auth0` user ID. If a quote is already stored, it displays the quote and provides a button to delete it.

The `auth0.getSession()` method provides the current user's session information, which we use to interact with the database on their behalf. If the user is not authenticated, the page displays a login button instead.

## Running the application

To start the application, run the following command:

```bash
npm run dev
```

This will start the Next.js development server. Open your browser and navigate to `http://localhost:3000` to see the application in action. When running for the first time, you'll be prompted to log in with Auth0. By default, Auth0 provides email and Google account as login options.

Once authenticated, you'll be able to visit the home page, add a quote, and see it displayed.

## Conclusion

In this guide, we walked through setting up a simple Next.js application with user authentication using Auth0 and a Lakebase Postgres database. We defined a database schema using Drizzle ORM, generated migrations, and interacted with the database to store and retrieve user data.

Next, you can add more routes and features to the application. Call `auth0.getSession()` in any server component, server action, or route handler to check whether the user is logged in and render content conditionally.

To view and manage the users who authenticated with your application, you can navigate to the [Auth0 Dashboard](https://manage.auth0.com/) and click on **User Management > Users** in the sidebar. Here, you can see the list of users who have logged in and perform any necessary actions for those users.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Authentication flow with Auth0](https://github.com/neondatabase/guide-neon-next-auth0): Authenticate users of your Neon application with Auth0

## Resources

For more information on the tools used in this guide, refer to the following documentation:

- [Neon Serverless Driver](https://neon.com/docs/serverless/serverless-driver)
- [Next.js Documentation](https://nextjs.org/docs)
- [Drizzle ORM](https://orm.drizzle.team/)
- [Auth0 Next.js SDK](https://auth0.com/docs/quickstart/webapp/nextjs)

--- [Document source](https://neon.com/docs/guides/auth-authjs.md) ---

> Summary: Auth.js (NextAuth.js v5) with the Lakebase Postgres adapter stores users, sessions, and magic-link verification tokens directly in a Lakebase database, enabling passwordless email authentication in Next.js without a separate auth service. Use this guide when you want self-managed auth with full database control, as an alternative to the Managed Better Auth option. The setup uses @auth/neon-adapter, @neondatabase/serverless, and Resend as the email provider for magic link delivery.

# Authenticate Lakebase Postgres application users with Auth.js

Learn how to add passwordless authentication to your Lakebase Postgres database application using Auth.js and Resend

Last updated: 2026-10-28

**Important: Start here: pick your auth setup**

Want authentication tables in your Postgres database with no separate auth service to run? Use [Managed Better Auth](https://neon.com/docs/auth/overview). It stores users and sessions directly in your database under the `neon_auth` schema, and every database branch gets its own isolated auth environment for preview and CI.

Choose this guide instead when you want to own and control the auth tables yourself: self-managed Auth.js with the [Neon adapter](https://authjs.dev/getting-started/adapters/neon) (`@auth/neon-adapter`), which stores users and sessions in tables you define and manage.

[Auth.js](https://authjs.dev/) (formerly NextAuth.js) is a popular authentication solution that supports a wide range of authentication methods, including social logins (for example, Google, Facebook), traditional email/password, and passwordless options like magic links. For simple authentication flows, such as social logins, Auth.js can operate using only in-memory session storage (in a browser cookie). However, if you want to implement custom login flows, or persist the signed-in users' information in your database, you need to specify a database backend.

For example, passwordless authentication methods like magic links require secure storage of temporary tokens. Magic link login has become increasingly popular since it eliminates the need for users to remember complex passwords, reducing the risk of credential-based attacks.

In this guide, we'll walk through setting up a simple Next.js application, using Lakebase Postgres as the database backend for both Auth.js authentication and application data. We'll use [Resend](https://resend.com/) for sending magic link emails. We will cover how to:

- Set up a Next.js project with Auth.js for magic link authentication
- Create a database on Neon and configure it as the Auth.js database backend
- Configure Resend as an authentication provider
- Implement a basic authenticated feature (a simple todo list)

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). We'll use a database named `neondb` in the following examples.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.
- A [Resend](https://resend.com/) account for sending emails. Resend offers a free tier to get started.
- A domain

## Initialize your Next.js project

Run the following command in your terminal to create a new Next.js project:

```bash
npx create-next-app guide-neon-next-authjs --typescript --eslint --tailwind --use-npm --no-src-dir --app --import-alias "@/*"
```

Now, navigate to the project directory and install the required dependencies:

```bash
cd guide-neon-next-authjs
npm install next-auth@beta
npm install @auth/neon-adapter @neondatabase/serverless
```

For authentication, we'll use the `Auth.js` library (aliased as v5 of the `next-auth` package), which provides a simple way to add authentication to Next.js applications. It comes with built-in support for Resend as an authentication provider. We use the `@neondatabase/serverless` package as the Postgres client for the `Auth.js` database adapter.

Also, add a `.env` file to the root of your project, which we'll use to store the Neon connection string and the Resend API key:

```bash
touch .env
```

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon console and go to the [Projects](https://console.neon.tech/app/projects) section.
2. Click the **New Project** button to create a new project.
3. Choose your preferred region and Postgres version, then click **Create Project**.

### Retrieve your Neon database connection string

You can find your database connection string by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Add this connection string to your `.env` file:

```bash
# .env
DATABASE_URL="YOUR_NEON_CONNECTION_STRING"
```

## Configuring Auth.js and Resend

### Set up Resend

1. Sign up for a [Resend](https://resend.com/) account if you don't already have one.

2. In the Resend dashboard, create an API key.

3. Add the API key to your `.env` file:

   ```bash
   # .env
   AUTH_RESEND_KEY="YOUR_RESEND_API_KEY"
   ```

4. Optional: Resend requires verification of ownership for the domain you use to send emails from. If you own a domain, you can follow the instructions [here](https://resend.com/docs/dashboard/domains/introduction) to verify ownership.

   For this example, we'll use the test email address (`onboarding@resend.dev`) to send emails. However, this only works for the email address you use to sign up for a Resend account, so you won't be able to sign in from other email accounts.

### Configure Auth.js

Create a new file `auth.ts` in the root directory of the project and add the following content:

```typescript
/// auth.ts

import NextAuth from 'next-auth';
import Resend from 'next-auth/providers/resend';
import NeonAdapter from '@auth/neon-adapter';
import { Pool } from '@neondatabase/serverless';

// *DO NOT* create a `Pool` here, outside the request handler.

export const { handlers, auth, signIn, signOut } = NextAuth(() => {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  return {
    adapter: NeonAdapter(pool),
    providers: [Resend({ from: 'Test <onboarding@resend.dev>' })],
  };
});
```

This file sets up Auth.js with the Lakebase Postgres adapter (`@auth/neon-adapter`) and configures the Email provider for magic link authentication.

Additionally, `Auth.js` also requires setting up an `AUTH_SECRET` environment variable, which is used to encrypt cookies and magic tokens. You can use the `Auth.js` CLI to generate one:

```bash
npx auth secret
```

Add the generated secret to your `.env` file:

```bash
# .env
AUTH_SECRET="YOUR_AUTH_SECRET"
```

### Implement authentication routes

Create a new dynamic route at `app/api/auth/[...nextauth]/route.ts` with the following content:

```tsx
/// app/api/auth/[...nextauth]/route.ts

import { handlers } from '@/auth';

export const { GET, POST } = handlers;
```

This route file imports the authentication handlers from the `auth.ts` file that handle all auth-related requests — sign-in, sign-out, and redirect after authentication.

The `auth` object exported from `./auth.ts` is the universal method we can use to interact with the authentication state in the application. For example, we add a message above the main app layout that indicates the current user's name and a sign-out button at the bottom.

## Implementing the application

### Create the database schema

Create a new file `app/db/schema.sql` with the following content:

```sql
-- Auth.js required tables
CREATE TABLE IF NOT EXISTS users (
  id SERIAL,
  name VARCHAR(255),
  email VARCHAR(255),
  "emailVerified" TIMESTAMPTZ,
  image TEXT,
  PRIMARY KEY (id)
);

CREATE TABLE IF NOT EXISTS accounts (
  id SERIAL,
  "userId" INTEGER NOT NULL,
  type VARCHAR(255) NOT NULL,
  provider VARCHAR(255) NOT NULL,
  "providerAccountId" VARCHAR(255) NOT NULL,
  refresh_token TEXT,
  access_token TEXT,
  expires_at BIGINT,
  token_type TEXT,
  scope TEXT,
  id_token TEXT,
  session_state TEXT,
  PRIMARY KEY (id)
);

CREATE TABLE IF NOT EXISTS sessions (
  id SERIAL,
  "sessionToken" VARCHAR(255) NOT NULL,
  "userId" INTEGER NOT NULL,
  expires TIMESTAMPTZ NOT NULL,
  PRIMARY KEY (id)
);

CREATE TABLE IF NOT EXISTS verification_token (
  identifier TEXT,
  token TEXT,
  expires TIMESTAMPTZ NOT NULL,
  PRIMARY KEY (identifier, token)
);

-- Application-specific table
CREATE TABLE IF NOT EXISTS todos (
  id SERIAL PRIMARY KEY,
  user_id INTEGER NOT NULL,
  content TEXT NOT NULL,
  completed BOOLEAN NOT NULL DEFAULT FALSE,
  created_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (user_id) REFERENCES users(id)
);
```

This schema defines all the tables required for the `Auth.js` library to work, and also the `todos` table that we'll use to store the todo list for each user.

To apply this schema to your database, you can use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) in the web console or a database management tool like [psql](https://neon.com/docs/connect/query-with-psql-editor).

### Implement the Todo list feature

Create a new file `app/TodoList.tsx`:

```tsx
'use client';

import { useState } from 'react';

type Todo = {
  id: number;
  content: string;
  completed: boolean;
};

export default function TodoList({ initialTodos }: { initialTodos: Todo[] }) {
  const [todos, setTodos] = useState<Todo[]>(initialTodos);
  const [newTodo, setNewTodo] = useState('');

  const addTodo = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!newTodo.trim()) return;

    const response = await fetch('/api/todos', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ content: newTodo }),
    });

    if (response.ok) {
      const todo = await response.json();
      setTodos([...todos, todo]);
      setNewTodo('');
    }
  };

  const toggleTodo = async (id: number) => {
    const response = await fetch(`/api/todos/${id}`, { method: 'PATCH' });
    if (response.ok) {
      setTodos(
        todos.map((todo) => (todo.id === id ? { ...todo, completed: !todo.completed } : todo))
      );
    }
  };

  return (
    <div className="w-full max-w-md">
      <form onSubmit={addTodo} className="mb-4">
        <input
          type="text"
          value={newTodo}
          onChange={(e) => setNewTodo(e.target.value)}
          placeholder="Add a new todo"
          className="mb-2 w-full rounded border p-2"
        />
        <button type="submit" className="w-full rounded border p-2">
          Add
        </button>
      </form>
      <ul className="space-y-2">
        {todos.map((todo) => (
          <li
            key={todo.id}
            onClick={() => toggleTodo(todo.id)}
            className="flex cursor-pointer items-center space-x-2"
          >
            <input type="checkbox" checked={todo.completed} readOnly className="cursor-pointer" />
            <span className={todo.completed ? 'line-through' : ''}>{todo.content}</span>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

### Update the main page

Replace the contents of `app/page.tsx` with:

```tsx
import { auth } from '@/auth';
import TodoList from '@/app/TodoList';
import { Pool } from '@neondatabase/serverless';

async function getTodos(userId: string) {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const { rows } = await pool.query('SELECT * FROM todos WHERE user_id = $1', [userId]);
  await pool.end();
  return rows;
}

type Todo = {
  id: number;
  content: string;
  completed: boolean;
};

export default async function Home() {
  const session = await auth();

  return (
    <div className="flex min-h-screen flex-col items-center justify-center p-4">
      <div className="w-full max-w-md text-center">
        {!session ? (
          <>
            <h1 className="mb-4 text-2xl">Welcome to the Todo App</h1>
            <p className="mb-4">Please sign in to access your todos.</p>
            <a href="/api/auth/signin" className="inline-block rounded border p-2">
              Sign In
            </a>
          </>
        ) : (
          <>
            <h1 className="mb-4 text-2xl">Welcome, {session.user?.name || session.user?.email}</h1>
            <TodoList initialTodos={await getTodos(session.user?.id as string)} />
            <a href="/api/auth/signout" className="mt-4 inline-block rounded border p-2">
              Sign Out
            </a>
          </>
        )}
      </div>
    </div>
  );
}
```

### Create API routes for the todos feature

Create a new file `app/api/todos/route.ts`:

```typescript
import { NextResponse } from 'next/server';
import { auth } from '@/auth';
import { Pool } from '@neondatabase/serverless';

export async function POST(req: Request) {
  const session = await auth();
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { content } = await req.json();
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });

  try {
    const { rows } = await pool.query(
      'INSERT INTO todos (user_id, content) VALUES ($1, $2) RETURNING *',
      [session.user.id, content]
    );
    return NextResponse.json(rows[0]);
  } catch (error) {
    return NextResponse.json({ error: 'Failed to create todo' }, { status: 500 });
  } finally {
    await pool.end();
  }
}
```

This implements a simple API endpoint that allows users to create new todos.

Create another file `app/api/todos/[id]/route.ts`:

```typescript
import { NextResponse } from 'next/server';
import { auth } from '../../auth/[...nextauth]/route';
import { Pool } from '@neondatabase/serverless';

export async function PATCH(req: Request, { params }: { params: { id: string } }) {
  const session = await auth();
  if (!session) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const pool = new Pool({ connectionString: process.env.DATABASE_URL });

  try {
    const { rows } = await pool.query(
      'UPDATE todos SET completed = NOT completed WHERE id = $1 AND user_id = $2 RETURNING *',
      [params.id, session.user.id]
    );
    if (rows.length === 0) {
      return NextResponse.json({ error: 'Todo not found' }, { status: 404 });
    }
    return NextResponse.json(rows[0]);
  } catch (error) {
    return NextResponse.json({ error: 'Failed to update todo' }, { status: 500 });
  } finally {
    await pool.end();
  }
}
```

This implements a simple API endpoint that allows users to update the status of a todo.

## Running the application

To start the application, run:

```bash
npm run dev
```

This will start the Next.js development server. Open your browser and navigate to `http://localhost:3000` to see the application in action. When running for the first time, you'll see a `Sign In` link which will redirect you to the `Auth.js` widget, prompting you to input your email address. Enter your email to receive a magic link. Once authenticated, you'll be able to add and manage your todos.

Note that if you are using the test email address (`onboarding@resend.dev`) to send emails, you won't be able to sign in from other email accounts.

## Conclusion

In this guide, we demonstrated how to set up a Next.js application with Auth.js for magic link authentication, using Lakebase Postgres as the database backend for both authentication and application data. We implemented a simple todo list feature to showcase how authenticated users can interact with the application.

Next, we can add more routes and features to the application. The `auth` method can be used in the Next.js API routes or middleware to protect endpoints that require authentication.

To view and manage the users who authenticated with your application, you can query the `users` table of your database. Similarly, all the generated magic link tokens are logged in the `verification_token` table, making it easy to audit and revoke access to your application.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Authentication flow with Auth.js](https://github.com/neondatabase/examples/tree/main/auth/with-authjs-next): Authenticate users of your Neon application with Auth.js

## Resources

For more information about the tools and libraries used in this guide, refer to the following documentation:

- [Neon Documentation](https://neon.com/docs)
- [Auth.js Documentation](https://authjs.dev/)
- [Next.js Documentation](https://nextjs.org/docs)
- [Resend Documentation](https://resend.com/docs)

--- [Document source](https://neon.com/docs/guides/auth-clerk.md) ---

> Summary: Clerk authentication integration with Lakebase Postgres in a Next.js app uses Clerk user IDs as primary keys in a Drizzle ORM schema to associate database rows with authenticated users, supporting social login, email, and multi-factor auth without building auth infrastructure. Choose this guide when Clerk is your identity provider and you need clerkMiddleware to protect routes and server actions for per-user Postgres data. The walkthrough covers Drizzle-kit migration commands, ClerkProvider setup, and Next.js server actions backed by the Neon serverless driver.

# Authenticate Lakebase Postgres application users with Clerk

Learn how to add authentication to a Lakebase Postgres database application using Clerk

Last updated: 2026-09-23

**Tip: Building on Neon?**

Neon provides [Managed Better Auth](https://neon.com/docs/auth/overview), a managed authentication service built on Better Auth that stores users, sessions, and auth configuration directly in your Neon database. Auth state **branches with your data**, so preview and CI environments get isolated users and sessions.

User authentication is a critical requirement for web applications. Modern applications require advanced features like social login and multi-factor authentication besides the regular login flow. Additionally, managing personally identifiable information (PII) requires a secure solution compliant with data protection regulations.

**Note:** Looking to manage **authorization** along with authentication? The [Neon Data API](https://neon.com/docs/data-api/custom-authentication-providers) validates Clerk JWTs and enforces Row-Level Security (RLS) policies directly in Postgres, so you can manage access at the database level.

[Clerk](https://clerk.com/) is a user authentication and identity management platform that provides these features out of the box. It comes with adapters for popular web frameworks, making it easy to integrate with an application backed by a Lakebase Postgres database.

In this guide, we'll walk through setting up a simple Next.js application using Lakebase Postgres as the database, and add user authentication using [Clerk](https://clerk.com/). We will go over how to:

- Set up a Next.js project with Clerk for authentication
- Create a database on Neon and connect it to your application
- Define a database schema using Drizzle ORM and generate migrations
- Store and retrieve user data associated with Clerk user IDs

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- A [Clerk](https://clerk.com/) account for user authentication. Clerk provides a free plan that you can use to get started.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.

## Initialize your Next.js project

We will create a simple web app that lets you add a favorite quote to the home page, and edit it afterward. Run the following command in your terminal to create a new `Next.js` project:

```bash
npx create-next-app guide-neon-next-clerk --typescript --eslint --tailwind --use-npm --no-src-dir --app --import-alias "@/*"
```

Now, navigate to the project directory and install the required dependencies:

```bash
npm install @neondatabase/serverless drizzle-orm
npm install -D drizzle-kit dotenv
npm install @clerk/nextjs
```

We use the `@neondatabase/serverless` package as the Postgres client, and `drizzle-orm`, a lightweight typescript ORM, to interact with the database. `@clerk/nextjs` is the Clerk SDK for Next.js applications. We also use `dotenv` to manage environment variables and the `drizzle-kit` CLI tool for generating database migrations.

Also, add a `.env` file to the root of your project, which we'll use to store Neon/Clerk connection parameters:

```bash
touch .env
```

Make sure to add an entry for `.env` to your `.gitignore` file, so that it's not committed to your repository.

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select an existing project or click the **New Project** button to create a new one.
3. Choose the desired region and Postgres version for your project, then click **Create Project**.

### Retrieve your Neon database connection string

You can find your database connection string by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Add this connection string to the `.env` file in your Next.js project.

```bash
# .env
DATABASE_URL=NEON_DB_CONNECTION_STRING
```

## Configuring Clerk for authentication

### Create a Clerk application

1. Log in to the [Clerk Dashboard](https://dashboard.clerk.com/). Select `Create Application` to create a new app.
2. In the dialog that appears, provide a name for your application and a few sign-in options. For this tutorial, we'll use `Email`, `Google` and `GitHub` as allowed sign-in methods.

### Retrieve your API keys

From the `Configure` tab, click on **API Keys** to find your API keys, needed to authenticate your application with Clerk. Select the `Next.js` option to get them as environment variables for your Next.js project. It should look similar to this:

```bash
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=**************
CLERK_SECRET_KEY=**************
```

Add these variables to the `.env` file in your Next.js project.

## Implementing the application

### Define your database connection and schema

Create a `db` folder inside the `app/` directory. This is where we'll define the database schema and connection code.

Now, add the file `app/db/index.ts` with the following content:

```typescript
/// app/db/index.ts

import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import { UserMessages } from './schema';

if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL must be a Neon postgres connection string');
}

const sql = neon(process.env.DATABASE_URL);
export const db = drizzle(sql, {
  schema: { UserMessages },
});
```

This exports a `db` instance that we can use to execute queries against the database.

Next, create a `schema.ts` file inside the `app/db` directory to define the database schema:

```typescript
/// app/db/schema.ts

import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const UserMessages = pgTable('user_messages', {
  user_id: text('user_id').primaryKey().notNull(),
  createTs: timestamp('create_ts').defaultNow().notNull(),
  message: text('message').notNull(),
});
```

This schema defines a table `user_messages` to store a message for each user, with the `user_id` provided by Clerk as the primary key.

### Generate and run migrations

We'll use the `drizzle-kit` CLI tool to generate migrations for the schema we defined. To configure how it connects to the database, add a `drizzle.config.ts` file at the project root.

```typescript
// drizzle.config.ts
import { defineConfig } from 'drizzle-kit';
if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL not found in environment');
export default defineConfig({
  dialect: 'postgresql',
  schema: './app/db/schema.ts',
  dbCredentials: { url: process.env.DATABASE_URL! },
  out: './drizzle',
});
```

Now, generate the migration files by running the following command:

```bash
npx drizzle-kit generate
```

This will create a `drizzle` folder at the project root with the migration files. To apply the migration to the database, run:

```bash
npx drizzle-kit push:pg
```

The `user_messages` table will now be visible in the console.

### Add the Clerk proxy

The Clerk SDK handles user authentication and session management for us. Create a new file `proxy.ts` in the root directory. Calling `auth.protect()` requires users to sign in before they can reach any app route, and redirects signed-out visitors to the Clerk sign-in page:

```typescript
/// proxy.ts

import { clerkMiddleware } from '@clerk/nextjs/server';

export default clerkMiddleware(async (auth) => {
  await auth.protect();
});

export const config = {
  matcher: [
    // Skip Next.js internals and all static files, unless found in search params
    '/((?!_next|[^?]*\\.(?:html?|css|js(?!on)|jpe?g|webp|png|gif|svg|ttf|woff2?|ico|csv|docx?|xlsx?|zip|webmanifest)).*)',
    // Always run for API routes
    '/(api|trpc)(.*)',
  ],
};
```

**Note:** Next.js 16 renamed `middleware.ts` to `proxy.ts`. On Next.js 15 or earlier, name the file `middleware.ts`. The code stays the same.

Next, we wrap the full application with the `ClerkProvider` component, so all pages have access to the current session and user context. Replace the contents of the `app/layout.tsx` file with the following:

```tsx
import type { Metadata } from 'next';
import { Suspense } from 'react';
import { Inter } from 'next/font/google';
import './globals.css';
import { ClerkProvider, UserButton } from '@clerk/nextjs';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Neon-Next-Clerk guide',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Suspense fallback={null}>
          <ClerkProvider>
            <div className="bg-white p-4">
              <UserButton showName={true}></UserButton>
            </div>
            {children}
          </ClerkProvider>
        </Suspense>
      </body>
    </html>
  );
}
```

This also adds a `UserButton` component to the layout, which displays the user's name and avatar when logged in.

New Next.js 16 projects enable `cacheComponents`, which requires anything that reads request data, such as the session cookie, to render inside `<Suspense>`. Without it, `npm run build` fails with a prerendering error.

### Add interactivity to the application

Our application has a single page that lets the logged-in user store their favorite quote and displays it. We implement `Next.js` server action to handle the form submission and database interaction.

Create a new file at `app/actions.ts` with the following content:

```typescript
'use server';

import { currentUser } from '@clerk/nextjs/server';
import { UserMessages } from './db/schema';
import { db } from './db';
import { redirect } from 'next/navigation';
import { eq } from 'drizzle-orm';

export async function createUserMessage(formData: FormData) {
  const user = await currentUser();
  if (!user) throw new Error('User not found');

  const message = formData.get('message') as string;
  await db.insert(UserMessages).values({
    user_id: user.id,
    message,
  });
  redirect('/');
}

export async function deleteUserMessage() {
  const user = await currentUser();
  if (!user) throw new Error('User not found');

  await db.delete(UserMessages).where(eq(UserMessages.user_id, user.id));
  redirect('/');
}
```

The `createUserMessage` function inserts a new message into the `user_messages` table, while `deleteUserMessage` removes the message associated with the current user.

Next, we implement a minimal UI to interact with these functions. Replace the contents of the `app/page.tsx` file with the following:

```tsx
import { createUserMessage, deleteUserMessage } from './actions';
import { db } from './db';
import { currentUser } from '@clerk/nextjs/server';

async function getUserMessage() {
  const user = await currentUser();
  if (!user) throw new Error('User not found');
  return db.query.UserMessages.findFirst({
    where: (messages, { eq }) => eq(messages.user_id, user.id),
  });
}

export default async function Home() {
  const existingMessage = await getUserMessage();
  const ui = existingMessage ? (
    <div className="w-2/3 text-center">
      <h1 className="text-3xl">{existingMessage.message}</h1>
      <form action={deleteUserMessage} className="mb-4 w-full rounded px-8 pb-8 pt-6">
        <div className="w-full text-center">
          <input
            type="submit"
            value={'Delete Quote'}
            className="text-gray-800 cursor-pointer rounded bg-[#00E699] px-4 py-2 font-semibold transition-colors hover:bg-[#00e5BF] focus:outline-none"
          />
        </div>
      </form>
    </div>
  ) : (
    <form action={createUserMessage} className="w-2/3 rounded px-8 shadow-md">
      <div className="mb-6">
        <input
          type="text"
          name="message"
          placeholder="Mistakes are the portals of discovery - James Joyce"
          className="text-gray-700 w-full appearance-none rounded border p-3 text-center leading-tight focus:outline-none"
        />
      </div>
      <div className="w-full text-center">
        <input
          type="submit"
          value={'Save Quote'}
          className="text-gray-800 cursor-pointer rounded bg-[#00E699] px-4 py-2 font-semibold transition-colors hover:bg-[#00e5BF] focus:outline-none"
        />
      </div>
    </form>
  );
  return (
    <main className="align-center -mt-16 flex min-h-screen flex-col items-center justify-center px-24">
      <h2 className="text-gray-400 pb-6 text-2xl">
        {existingMessage ? 'Your quote is wonderful...' : 'Save an inspiring quote for yourself...'}
      </h2>
      {ui}
    </main>
  );
}
```

This implements a form with a single text field that lets the user input a quote, and submit it, whereby it gets stored in the database, associated with their `Clerk` user ID. If a quote is already stored, it displays it and provides a button to delete it.

The `currentUser` hook from `@clerk/nextjs/server` provides the current user's information, which we use to interact with the database on their behalf.

## Running the application

To start the application, run the following command:

```bash
npm run dev
```

This will start the Next.js development server. Open your browser and navigate to `http://localhost:3000` to see the application in action. When running for the first time, you'll be prompted to sign in with Clerk. Once authenticated, you'll be able to visit the home page, add a quote, and see it displayed.

## Conclusion

In this guide, we walked through setting up a simple Next.js application with user authentication using Clerk and a Lakebase Postgres database. We defined a database schema using Drizzle ORM, generated migrations, and interacted with the database to store and retrieve user data.

Next, we can add more routes and features to the application. The Clerk proxy ensures that only authenticated users can access any app routes, and the `ClerkProvider` component provides the user context to each of them.

To view and manage the users who authenticated with your application, you can navigate to the [Clerk Dashboard](https://dashboard.clerk.dev/).

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Authentication flow with Clerk](https://github.com/neondatabase/guide-neon-next-clerk): Authenticate users of your Neon application with Clerk

## Resources

For more information on the tools used in this guide, refer to the following documentation:

- [Neon Serverless Driver](https://neon.com/docs/serverless/serverless-driver)
- [Drizzle ORM](https://orm.drizzle.team/)
- [Clerk Authentication](https://clerk.com/)
- [Next.js Documentation](https://nextjs.org/docs)

--- [Document source](https://neon.com/docs/guides/auth-okta.md) ---

> Summary: Okta Workforce Identity Cloud SSO integration for a Next.js app backed by Lakebase Postgres, wiring Auth.js (next-auth v5) with the built-in Okta OIDC provider and Drizzle ORM migrations to store per-user data keyed by the Okta sub claim. Choose this guide for organization-internal SSO login rather than Auth0 or Managed Better Auth. The tutorial covers creating an Okta OIDC web application, setting issuer URI and client credentials, defining a user_messages schema, and running drizzle-kit push:pg migrations against a Lakebase database.

# Authenticate Lakebase Postgres application users with Okta

Learn how to add authentication to a Lakebase Postgres database application with Okta

Last updated: 2026-09-16

**Tip: Building on Neon?**

Neon provides [Managed Better Auth](https://neon.com/docs/auth/overview), a managed authentication service built on Better Auth that stores users, sessions, and auth configuration directly in your Neon database. Auth state **branches with your data**, so preview and CI environments get isolated users and sessions.

User authentication is critical for web applications, especially for apps internal to an organization. [Okta Workforce Identity Cloud](https://www.okta.com/workforce-identity/) is an identity and access management platform for organizations, that provides authentication, authorization, and user management capabilities.

In this guide, we'll walk through building a simple Next.js application using [Neon's](https://neon.tech) Lakebase Postgres database, and add user authentication to it using [Okta](https://www.okta.com/). We will cover how to:

- Set up a Next.js project with Okta for authentication
- Create a database on Neon and connect it to your application
- Define a database schema using Drizzle ORM and generate migrations
- Store and retrieve user data associated with Okta user IDs

**Note:** Okta provides a different solution called [Customer Identity Cloud](https://www.okta.com/customer-identity/), powered by `Auth0`, to authenticate external customers for Saas applications. This guide focuses on the [Workforce Identity Cloud](https://www.okta.com/workforce-identity/) for internal applications. For an example guide using `Auth0`, refer to our [Auth0](https://neon.com/docs/guides/auth-auth0) guide.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- An [Okta](https://developer.okta.com/) administrator account for user authentication. Okta provides a free trial that you can use to set one up for your organization.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.

## Initialize your Next.js project

We will create a simple web app that lets you add a favorite quote to the home page, and edit it afterwards. Run the following command in your terminal to create a new `Next.js` project:

```bash
npx create-next-app guide-neon-next-okta --typescript --eslint --tailwind --use-npm --no-src-dir --app --import-alias "@/*"
```

Now, navigate to the project directory and install the required dependencies:

```bash
npm install @neondatabase/serverless drizzle-orm
npm install -D drizzle-kit dotenv
npm install next-auth@beta
```

We use the `@neondatabase/serverless` package as the Postgres client, and `drizzle-orm`, a lightweight typescript ORM, to interact with the database. We also use `dotenv` to manage environment variables and the `drizzle-kit` CLI tool for generating database migrations. For authentication, we'll use the `auth.js` library (aliased as v5 of the `next-auth` package), which provides a simple way to add authentication to Next.js applications. It comes with built-in support for Okta.

Also, add a `.env.local` file to the root of your project, which we'll use to store Neon/Okta connection parameters:

```bash
touch .env.local
```

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select an existing project or click the **New Project** button to create a new one.
3. Choose the desired region and Postgres version for your project, then click **Create Project**.

### Retrieve your Neon database connection string

You can find your database connection string by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Add this connection string to the `.env.local` file in your Next.js project.

```bash
# .env.local

DATABASE_URL=NEON_DB_CONNECTION_STRING
```

## Configuring Okta for authentication

### Create an Okta application

1. Log in to your Okta developer account and navigate to the **Applications** section. Click the **Create App Integration** button.
2. Select **OIDC - OpenID Connect** as the sign-in method.
3. Select **Web Application** as the application type and click **Next**.
4. Provide a name for your application, for example, "Neon Next Guide".
5. Set **Sign-in redirect URIs** to `http://localhost:3000/api/auth/callback/okta` and **Sign-out redirect URIs** to `http://localhost:3000`.
6. Click **Save** to create the application.

### Retrieve your Okta configuration

From the application's **General** tab, find the **Client ID** and **Client SECRET**. Also note your Okta **Issuer URI**, which is the first part of your Okta account's URL, for example, `https://dev-12345.okta.com`. If it isn't clear, visit the **Security > API** section from the sidebar in the console to find the **Issuer URI** and remove `/oauth2/default` from the end.

Add these as environment variables to the `.env.local` file in your Next.js project:

```bash
# .env.local

AUTH_OKTA_ISSUER=YOUR_OKTA_ISSUER
AUTH_OKTA_ID=YOUR_CLIENT_ID
AUTH_OKTA_SECRET=YOUR_CLIENT_SECRET
AUTH_SECRET=YOUR_SECRET
```

The last variable, `AUTH_SECRET`, is a random string used by `Auth.js` to encrypt tokens. Run the following command to generate one and add it to your `.env.local` file:

```bash
npx auth secret
```

**Note:** If you set up an Okta organization account specifically for this guide, you might need to assign yourself to the created Okta application to test the authentication flow. Visit **Applications > Applications** from the sidebar and select the application you created. In the **Assignments** tab, click **Assign** and select your own user account.

## Implementing the application

### Define database connection and schema

Create a `db` folder inside the `app/` directory. This is where we'll define the database schema and connection code.

Now, add the file `app/db/index.ts` with the following content:

```typescript
/// app/db/index.ts

import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import { UserMessages } from './schema';

if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL must be a Neon postgres connection string');
}

const sql = neon(process.env.DATABASE_URL);

export const db = drizzle(sql, {
  schema: { UserMessages },
});
```

This exports a `db` instance that we can use to execute queries against the database.

Next, create a `schema.ts` file inside the `app/db` directory to define the database schema:

```typescript
/// app/db/schema.ts

import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';

export const UserMessages = pgTable('user_messages', {
  user_id: text('user_id').primaryKey().notNull(),
  createTs: timestamp('create_ts').defaultNow().notNull(),
  message: text('message').notNull(),
});
```

This schema defines a table `user_messages` to store a message for each user, with the `user_id` provided by Okta as the primary key.

### Generate and run migrations

We'll use the `drizzle-kit` CLI tool to generate migrations for the schema we defined. To configure how it connects to the database, add a `drizzle.config.ts` file at the project root.

```typescript
/// drizzle.config.ts

import type { Config } from 'drizzle-kit';
import * as dotenv from 'dotenv';

dotenv.config({ path: '.env.local' });

if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL not found in environment');

export default {
  schema: './app/db/schema.ts',
  out: './drizzle',
  driver: 'pg',
  dbCredentials: {
    connectionString: process.env.DATABASE_URL,
  },
  strict: true,
} satisfies Config;
```

Now, generate the migration files by running the following command:

```bash
npx drizzle-kit generate:pg
```

This will create a `drizzle` folder at the project root with the migration files. To apply the migration to the database, run:

```bash
npx drizzle-kit push:pg
```

The `user_messages` table will now be visible in the console.

### Configure Okta authentication

Create a new file `auth.ts` in the root directory of the project and add the following content:

```typescript
import NextAuth from 'next-auth';
import Okta from 'next-auth/providers/okta';

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [Okta],
  callbacks: {
    async session({ session, token }) {
      session.user.id = token.sub as string;
      return session;
    },
  },
});
```

This file initializes `Auth.js` with Okta as the authentication provider. It also defines a callback to set the `sub` claim from the Okta token as the session user ID.

### Implement authentication routes

Create a new dynamic route at `app/api/auth/[...nextauth]/route.ts` with the following content:

```tsx
/// app/api/auth/[...nextauth]/route.ts

import { handlers } from '@/auth';

export const { GET, POST } = handlers;
```

This route file imports the authentication handlers from the `auth.ts` file that handle all auth-related requests — sign-in, sign-out, and redirect after authentication.

The `auth` object exported from `./auth.ts` is the universal method we can use to interact with the authentication state in the application. For example, we add a **User information** bar to the app layout that indicates the current user's name and provides a sign-out button.

Replace the contents of the `app/layout.tsx` file with the following:

```tsx
import type { Metadata } from 'next';
import { Inter } from 'next/font/google';
import './globals.css';
import { auth } from '@/auth';

const inter = Inter({ subsets: ['latin'] });

export const metadata: Metadata = {
  title: 'Create Next App',
  description: 'Generated by create next app',
};

async function UserInfoBar() {
  const session = await auth();
  if (!session) {
    return null;
  }

  return (
    <div className="bg-gray-100 px-4 py-2">
      <span className="text-gray-800">
        Welcome, {session.user?.name}!{' '}
        <a href="/api/auth/signout" className="text-blue-600 hover:underline">
          Sign out
        </a>
      </span>
    </div>
  );
}

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <UserInfoBar />
        {children}
      </body>
    </html>
  );
}
```

### Add interactivity to the application

Our application has a single page that lets the logged-in user store their favorite quote and display it. We implement `Next.js` server actions to handle the form submission and database interaction.

Create a new file at `app/actions.ts` with the following content:

```typescript
/// app/actions.ts

'use server';

import { auth } from '@/auth';
import { UserMessages } from './db/schema';
import { db } from './db';
import { redirect } from 'next/navigation';
import { eq } from 'drizzle-orm';

export async function createUserMessage(formData: FormData) {
  const session = await auth();
  if (!session) throw new Error('User not authenticated');

  const message = formData.get('message') as string;
  await db.insert(UserMessages).values({
    user_id: session.user?.id as string,
    message,
  });

  redirect('/');
}

export async function deleteUserMessage() {
  const session = await auth();
  if (!session) throw new Error('User not authenticated');

  await db.delete(UserMessages).where(eq(UserMessages.user_id, session.user?.id as string));
  redirect('/');
}
```

The `createUserMessage` function inserts a new message into the `user_messages` table, while `deleteUserMessage` removes the message associated with the current user.

Next, we implement a minimal UI to interact with these functions. Replace the contents of the `app/page.tsx` file with the following:

```tsx
/// app/page.tsx

import { createUserMessage, deleteUserMessage } from './actions';
import { db } from './db';
import { auth } from '@/auth';

async function getUserMessage() {
  const session = await auth();
  if (!session) return null;

  return db.query.UserMessages.findFirst({
    where: (messages, { eq }) => eq(messages.user_id, session.user?.id as string),
  });
}

function LoginBox() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-center p-24">
      <a
        href="/api/auth/signin"
        className="text-gray-800 rounded-md bg-[#00E699] px-3.5 py-2.5 text-sm font-semibold shadow-sm hover:bg-[#00e5BF] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[#00E699]"
      >
        Log in
      </a>
    </main>
  );
}

export default async function Home() {
  const session = await auth();
  const existingMessage = await getUserMessage();

  if (!session) {
    return <LoginBox />;
  }

  const ui = existingMessage ? (
    <div className="w-2/3 text-center">
      <h1 className="text-3xl">{existingMessage.message}</h1>
      <form action={deleteUserMessage} className="mb-4 w-full rounded px-8 pb-8 pt-6">
        <div className="w-full text-center">
          <input
            type="submit"
            value={'Delete Quote'}
            className="text-gray-800 cursor-pointer rounded bg-[#00E699] px-4 py-2 font-semibold transition-colors hover:bg-[#00e5BF] focus:outline-none"
          />
        </div>
      </form>
    </div>
  ) : (
    <form action={createUserMessage} className="w-2/3 rounded px-8 shadow-md">
      <div className="mb-6">
        <input
          type="text"
          name="message"
          placeholder="Mistakes are the portals of discovery - James Joyce"
          className="text-gray-700 w-full appearance-none rounded border p-3 text-center leading-tight focus:outline-none"
        />
      </div>
      <div className="w-full text-center">
        <input
          type="submit"
          value={'Save Quote'}
          className="text-gray-800 cursor-pointer rounded bg-[#00E699] px-4 py-2 font-semibold transition-colors hover:bg-[#00e5BF] focus:outline-none"
        />
      </div>
    </form>
  );

  return (
    <main className="align-center -mt-16 flex min-h-screen flex-col items-center justify-center px-24">
      <h2 className="text-gray-400 pb-6 text-2xl">
        {existingMessage ? 'Your quote is wonderful...' : 'Save an inspiring quote for yourself...'}
      </h2>
      {ui}
    </main>
  );
}
```

This code implements a form with a single text field that lets the user input a quote, and submit it, whereby the quote is stored in the database and associated with the user's `Okta` user ID. If a quote is already stored, it displays the quote and provides a button to delete it.

The `user.id` property set on the session object provides the current user's ID, which we use to interact with the database on their behalf. If the user is not authenticated, the page displays a login button instead.

## Running the application

To start the application, run the following command:

```bash
npm run dev
```

This will start the Next.js development server. Open your browser and navigate to `http://localhost:3000` to see the application in action. When running for the first time, you'll see a `Log In` button which will redirect you to the `Auth.js` widget, prompting you to sign in with Okta.

Once authenticated, you'll be able to visit the home page, add a quote, and see it displayed.

## Conclusion

In this guide, we walked through setting up a simple Next.js application with user authentication using Okta and a Lakebase Postgres database. We defined a database schema using Drizzle ORM, generated migrations, and interacted with the database to store and retrieve user data.

Next, we can add more routes and features to the application. The `auth` method can be used in the Next.js API routes or middleware to protect endpoints that require authentication.

To view and manage the users who authenticated with your application, you can navigate to your Okta admin console and view the **Directory > People** section in the sidebar.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Authentication flow with Okta](https://github.com/neondatabase/guide-neon-next-okta): Authenticate Neon application users with Okta

## Resources

For more information on the tools used in this guide, refer to the following documentation:

- [Neon Serverless Driver](https://neon.com/docs/serverless/serverless-driver)
- [Drizzle ORM](https://orm.drizzle.team/)
- [Next.js Documentation](https://nextjs.org/docs)
- [Auth.js Documentation](https://authjs.dev/getting-started/installation)

--- [Document source](https://neon.com/docs/guides/autoscaling-algorithm.md) ---

> Summary: Neon's autoscaling algorithm scales compute by evaluating CPU load average, RAM usage, and compute cache working set size against fixed thresholds, then applying the formula goalCU = max(cpuGoalCU, memGoalCU, lfcGoalCU). The autoscaler-agent polls CPU, memory, and cache activity on a regular schedule, while the vm-monitor checks Postgres memory every 100 milliseconds. Use this page to understand the internal decision logic, not the configuration steps covered in the enablement guide.

# Understanding Neon's autoscaling algorithm

How Neon's algorithm scales resources to match your workload

Last updated: 2026-08-07

**What you will learn:**

- Key metrics that drive autoscaling decisions
- How often the algorithm checks these metrics

**Related topics**

- [Introduction to autoscaling](https://neon.com/docs/introduction/autoscaling)
- [Enabling autoscaling](https://neon.com/docs/guides/autoscaling-guide)

The key concept behind autoscaling is that compute resizing happens _automatically_; once you set up your minimum and maximum [compute sizes](https://neon.com/docs/manage/endpoints#how-to-size-your-compute), there's no action required on your part other than [monitoring](https://neon.com/docs/introduction/monitoring-page) your usage metrics to see if adjustments are needed.

That said, it can be helpful to understand exactly when and under what circumstances the algorithm optimizes your database on two key fronts: **performance** and **efficiency**. In a nutshell, the algorithm automatically **scales up** your compute to ensure optimal performance and **scales down** to maximize efficiency.

![autoscaling algorithm](https://neon.com/docs/guides/autoscaling_algorithm.png)

## How the algorithm works

Neon's autoscaling algorithm uses two components, the [vm-monitor](https://neon.com/docs/reference/glossary#vm-monitor) and the [autoscaler-agent](https://neon.com/docs/reference/glossary#autoscaler-agent), to continuously monitor three key metrics: your average CPU load, your memory usage, and the activity of your [compute cache](https://neon.com/docs/reference/glossary#compute-cache). These metrics determine how your compute resources (the virtual machine that powers your database) should be scaled to maintain performance and efficiency.

### The Formula

In essence, the algorithm is built on **goals**. We set a goal (an ideal compute size) for each of the three key metrics:

- **`cpuGoalCU`** — Keep the 1-minute average CPU load at or below 90% of the available CPU capacity.
- **`memGoalCU`** — Keep memory usage at or below 75% of the total allocated RAM.
- **`lfcGoalCU`** — Fit your frequently accessed working set within the compute cache (up to 75% of the compute's RAM).

The formula can be expressed as:

```
goalCU := max(cpuGoalCU, memGoalCU, lfcGoalCU)
```

The algorithm selects the highest value from these goals as the overall `goalCU`, ensuring your database has enough resources to handle the most demanding metric, while staying within the minimum and maximum limits you've set.

### The Metrics

Let's go into a bit more detail about each metric.

#### CPU load average

The CPU load average is a measure of how much work your CPU is handling. Every 5 seconds, the autoscaler-agent checks the 1-minute load average from the virtual machine (VM) running your database. This load average reflects the average number of processes waiting to be executed by the CPU over the previous minute.

The goal is to keep the CPU load at or below 90% of the available CPU capacity. If the load exceeds this threshold, the algorithm increases the compute allocated to your database to handle the additional demand.

In simpler terms, if your database is working too hard, the algorithm adds more CPU power to keep things running smoothly.

#### Memory Usage

Memory usage refers to the amount of RAM your database and its related processes are using. Every 5 seconds, the autoscaler-agent checks for the latest memory metrics from inside the VM, and every 100ms the vm-monitor checks memory usage from Postgres.

The algorithm aims to keep overall memory usage at or below 75% of the total allocated memory. If your database starts using more memory than this threshold, the algorithm increases compute size to allocate more memory, making sure your database has enough RAM to perform well without over-provisioning.

#### Compute cache working set size

An important part of the scaling algorithm is estimating your current working set size (a subset of your most frequently accessed data) and scaling your compute to ensure it fits within the compute cache.

Every 20 seconds, the autoscaler-agent checks the working set size across a variety of time windows, ranging from 1 to 60 minutes. The goal is to fit your working set within the compute cache (up to 75% of the compute's RAM). If your working set exceeds this threshold, the algorithm increases compute size to expand the cache, keeping frequently accessed data in memory for faster access. To learn more about how we do this, see [Dynamically estimating and scaling Postgres' working set size](https://neon.com/blog/dynamically-estimating-and-scaling-postgres-working-set-size).

**Note:** If your dataset is small enough, you can improve performance by keeping the entire dataset in memory. Check your database size on the Monitoring [dashboard](https://neon.com/docs/introduction/monitoring-page#database-size) and adjust your minimum compute size accordingly. For example, a 6.4 GB database can comfortably fit within a compute size of 2 CU (8 GB of RAM), where up to 75% of the available RAM is used for data caching.

## How often the metrics are polled

To give you a sense of the algorithm's responsiveness, here's a summary of how often the metrics are polled:

- **Every 5 seconds** → the autoscaler-agent fetches load metrics from the VM, including CPU usage and overall memory usage.
- **Every 20 seconds** → the autoscaler-agent checks the compute cache metrics, including the working set size across various time windows: 1 minute, 2 minutes, up to 60 minutes.
- **Every 100 milliseconds** → the vm-monitor checks memory usage specifically within Postgres.

This frequent polling allows the algorithm to respond swiftly to changes in workload, ensuring that your compute resources are always appropriately scaled to meet current demands.

--- [Document source](https://neon.com/docs/guides/autoscaling-guide.md) ---

> Summary: Step-by-step guide to enabling autoscaling on a Neon compute by setting a minimum and maximum CU so Neon scales compute up and down automatically with no restarts. Use this page to configure or update autoscaling on an individual compute, set project-level defaults that propagate to new branches and read replicas, and interpret monitoring graphs to tune min/max thresholds. The neon_utils extension exposes a num_cpus() function for observing live CPU allocation.

# Enable Autoscaling in Neon

Last updated: 2026-10-09

**What you will learn:**

- Enable autoscaling for a compute
- Configure autoscaling defaults for your project

**Related topics**

- [About autoscaling](https://neon.com/docs/introduction/autoscaling)
- [How the algorithm works](https://neon.com/docs/guides/autoscaling-algorithm)

This guide demonstrates how to enable autoscaling in your Neon project and how to [visualize](https://neon.com/docs/guides/autoscaling-guide#monitor-autoscaling) your usage.

**Tip: Did you know?**

Neon's autoscaling feature instantly scales your compute and memory resources. **No manual intervention or restarts are required.**

## Enable autoscaling for a compute

You can edit an individual compute to alter the compute configuration, which includes autoscaling.

To edit a compute:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.

2. Under **Postgres database**, select **Computes**.

3. Identify the compute you want to configure and click **Edit**.
   ![Edit compute menu](https://neon.com/docs/guides/autoscaling_edit.png)

4. On the **Edit compute** drawer, select **Autoscale** and use the slider to specify a minimum and maximum compute size.

   Neon scales the compute size up and down within the specified range to meet workload demand. Autoscaling currently supports a range of 1/4 (.25) to 16 CU. Each CU allocates approximately 4 GB of RAM; for example, 1 CU has 4 GB of RAM, 2 CU has 8 GB of RAM, and so on. For an overview of available compute sizes, see [Compute size and autoscaling configuration](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration).

   **Note:** The maximum permitted autoscaling range is 8 CU. This means the difference between your maximum and minimum compute size cannot exceed 8 CU. For example, if you set the minimum to 1 CU, the maximum can be at most 9 CU.

   **Note:** You can configure the scale to zero setting for your compute at the same time. For more, see [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero).

5. Click **Save**.

## Configure autoscaling defaults for your project

You can configure autoscaling configuration defaults for your project so that **newly created computes** (including those created when you create a new branch or add read replica) are created with the same autoscaling configuration. This saves you from having to configure autoscaling settings with each new compute. See [Change your project's default compute settings](https://neon.com/docs/manage/projects#change-your-projects-default-compute-settings) for more detail.

**Note:** Changing your autoscaling default settings does not alter the autoscaling configuration for existing computes.

To configure autoscaling defaults:

1. In your project, select **Settings** from the sidebar.
2. Select **Postgres**.
3. Under **Compute defaults**, select **Modify defaults** to open the compute settings modal.
4. Use the slider to specify a minimum and maximum compute size and **Save** your changes.

The next time you create a compute, these settings will be applied to it.

### Autoscaling defaults for each Neon plan

The following table outlines the initial default autoscaling settings for newly created projects on each Neon plan.

| **Neon plan** | **Minimum compute size** | **Maximum compute size** |
| ------------- | ------------------------ | ------------------------ |
| Free          | 0.25                     | 2                        |
| Launch        | 0.25                     | 8                        |
| Scale         | 0.25                     | 8                        |

## Monitor autoscaling

From the Neon Console, you can view how your compute and RAM usage have scaled for the past 24 hours. Select **Monitoring** in the sidebar and view the **Metrics** tab.

Some key points about this Autoscaling graph:

- **Allocated** refers to the compute and memory size provisioned to handle current demand; autoscaling automatically adjusts this allocation, increasing or decreasing the allocated compute and memory size in a step-wise fashion as demand fluctuates, within your minimum and maximum limits.
- **CU Usage** is represented by the blue line
- **RAM usage** is represented by the green line.
- A re-activated compute scales up immediately to your minimum allocation, ensuring adequate performance for your anticipated demand.

Place your cursor anywhere in the graph to get more usage detail about that particular point in time.

See below for some rules of thumb on actions you might want to take based on trends you see in this view.

### Start with a good minimum

Ideally, for smaller datasets, you want to keep as much of your dataset in memory (RAM) as possible. This improves performance by minimizing I/O operations. We recommend setting a large enough minimum limit to fit your full dataset in memory. For larger datasets and more sizing advice, see [how to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

### Setting your maximum

If your autoscaling graphs show regular spikes that hit your maximum setting, consider increasing your maximum. However, because these spikes plateau at the maximum setting, it can be difficult to determine your actual demand.

Another approach is to set a higher threshold than you need and monitor usage spikes to get a sense of where your typical maximum demand reaches; you can then throttle the maximum setting down closer to anticipated/historical demand. Either way, with autoscaling you only use what's necessary; a higher setting does not translate to increased usage unless there's demand for it.

### The neon_utils extension

Another tool for understanding usage, the `neon_utils` extension provides a `num_cpus()` function that helps you monitor how the _Autoscaling_ feature allocates compute resources in response to workload. For more information, see [The neon_utils extension](https://neon.com/docs/extensions/neon-utils).

--- [Document source](https://neon.com/docs/guides/aws-lambda.md) ---

> Summary: Connecting a Neon serverless Postgres database to AWS Lambda lets you query Postgres from event-driven Node.js functions without managing persistent infrastructure. Use this guide when you need to wire a Lambda function to a Neon database using the pg library, the Serverless Framework CLI, and DATABASE_URL with SSL enabled via sslmode=require.

# Connect from AWS Lambda

Learn how to set up a Neon database and connect from an AWS Lambda function

Last updated: 2026-09-16

AWS Lambda is a serverless, event-driven compute service that allows you to run code without provisioning or managing servers. It is a convenient and cost-effective solution for running various types of workloads, including those that require a database.

This guide describes how to set up a Neon database and connect to it from an AWS Lambda function using Node.js as the runtime environment. It covers:

- Creating a Lambda function using the [Serverless Framework](https://www.serverless.com/), which is a serverless application lifecycle management framework.
- Connecting your Lambda function to a Neon database.
- Deploying the Lambda function to AWS.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://neon.com/docs/get-started/signing-up/) for instructions.
- An AWS account. You can create a free AWS account at [AWS Free plan](https://aws.amazon.com/free/). An [IAM User and Access Key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) are required to programmatically interact with your AWS account. You must provide these credentials when deploying the Serverless Framework project.
- A Service Framework account. You can sign up at [Serverless Framework](https://www.serverless.com/).

## Create a Neon project

If you do not have one already, create a Neon project:

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a table in Neon

To create a table, navigate to **Postgres database** > **SQL Editor** in the [Neon Console](https://console.neon.tech/):

In the SQL Editor, run the following queries to create a `users` table and insert some data:

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

INSERT INTO users (name, email)
VALUES
    ('Alice', 'alice@example.com'),
    ('Bob', 'bob@example.com'),
    ('Charlie', 'charlie@example.com'),
    ('Dave', 'dave@example.com'),
    ('Eve', 'eve@example.com');
```

## Create a Lambda function

Create the Lambda function using the [Serverless Framework](https://www.serverless.com/):

1. Install the Serverless Framework by running the following command:

   ```bash
   npm install -g serverless
   ```

2. Create a `my-lambda` project directory and navigate to it.

   ```bash
   mkdir neon-lambda
   cd neon-lambda
   ```

3. Run the **serverless** command to create a serverless project.

   ```bash
    serverless
   ```

   Follow the prompts, as demonstrated below. You will be required to provide your AWS account credentials. The process creates an `aws-node-project` directory.

   ```bash
   ? What do you want to make? AWS - Node.js - Starter
   ? What do you want to call this project? aws-node-project

   ✔ Project successfully created in aws-node-project folder

   ? Do you want to login/register to Serverless Dashboard? Yes
   Logging into the Serverless Dashboard via the browser
   If your browser does not open automatically, please open this URL:
   https://app.serverless.com?client=cli&transactionId=jP-Zz5A9xu67PPYqzIhOe

   ✔ You are now logged into the Serverless Dashboard

   ? What application do you want to add this to? [create a new app]
   ? What do you want to name this application? aws-node-project

   ✔ Your project is ready to be deployed to Serverless Dashboard (org: "myorg", app: "aws-node-project")

   ? No AWS credentials found, what credentials do you want to use? AWS Access Role
   (most secure)

   If your browser does not open automatically, please open this URL: https://app.serverless.com/myorg/settings/providers?source=cli&providerId=new&provider=aws

   To learn more about providers, visit: http://slss.io/add-providers-dashboard
   ?
   [If you encountered an issue when setting up a provider, you may press Enter to
   skip this step]

   ✔ AWS Access Role provider was successfully created

   ? Do you want to deploy now? Yes

   Deploying aws-node-project to stage dev (us-east-1, "default" provider)

   ✔ Service deployed to stack aws-node-project-dev (71s)

   dashboard: https://app.serverless.com/myorg/apps/my-aws-node-project/aws-node-project/dev/us-east-1

   functions:
     hello: aws-node-project-dev-hello (225 kB)

   What next?
   Run these commands in the project directory:

   serverless deploy    Deploy changes
   serverless info      View deployed endpoints and resources
   serverless invoke    Invoke deployed functions
   serverless --help    Discover more commands
   ```

4. Navigate to the `aws-node-project` directory created by the previous step and install the `node-postgres` package, which you will use to connect to the database.

   ```bash
   npm install pg
   ```

   After installing the `node-postgres` package, the following dependency should be defined in your `package.json` file:

   ```json
   {
     "dependencies": {
       "pg": "^8.13.1"
     }
   }
   ```

5. In the `aws-node-project` directory, add a `users.js` file, and add the following code to it:

   ```javascript
   'use strict';
   const { Client } = require('pg');

   let client;

   module.exports.getAllUsers = async () => {
     if (!client) {
       console.log('Initializing new database client');
       client = new Client({ connectionString: process.env.DATABASE_URL });
       try {
         await client.connect();
       } catch (error) {
         console.error('Error connecting to the database:', error);
         return {
           statusCode: 500,
           body: JSON.stringify({
             error: 'Failed to connect to the database',
           }),
         };
       }
     }

     try {
       const { rows } = await client.query('SELECT * FROM users');
       return {
         statusCode: 200,
         body: JSON.stringify({
           data: rows,
         }),
       };
     } catch (error) {
       console.error('Error executing query:', error);
       return {
         statusCode: 500,
         body: JSON.stringify({
           error: 'Failed to fetch users',
         }),
       };
     }
   };
   ```

   The code in the `users.js` file exports the `getAllUsers` function, which retrieves all rows from the `users` table and returns them as a `JSON` object in the `HTTP` response body.

   This function uses the `pg` library to connect to the Neon database. It creates a new `Client` instance and passes the database connection string, which is defined in the `DATABASE_URL` environment variable. It then calls `connect()` to establish a connection to the database. Finally, it uses the `query()` method to execute a `SELECT` statement that retrieves all rows from the `users` table.

   The query method returns a `Promise` that resolves to an object containing the rows retrieved by the `SELECT` statement, which the function parses to retrieve the `rows` property. Finally, the function returns an `HTTP` response with a status code of 200 and a body that contains a `JSON` object with a single `data` property, which is set to the value of the rows variable.

6. Add the `DATABASE_URL` environment variable and the function definition to the `serverless.yml` file, which is located in your `aws-node-project` directory.

   **Note:** Environment variables can also be added to a `.env` file and loaded automatically with the help of the [dotenv](https://www.npmjs.com/package/dotenv) package. For more information, see [Resolution of environment variables](https://www.serverless.com/framework/docs/environment-variables).

   You can find your database connection details by clicking the **Connect** button in the Console nav. Add the `DATABASE_URL` under `environment`, and add `sslmode=require&channel_binding=require` to the end of the connection string to enable SSL. The `sslmode=require` option tells Postgres to use SSL encryption and verify the server's certificate.

   ```yaml
   provider:
     name: aws
     runtime: nodejs14.x
     environment:
       DATABASE_URL: postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require

   functions:
     getAllUsers:
       handler: users.getAllUsers
       events:
         - httpApi:
             path: /users
             method: get
   ```

7. Deploy the serverless function using the following command:

   ```bash
   serverless deploy
   ```

   The `serverless deploy` command generates an API endpoint using [API Gateway](https://www.serverless.com/framework/docs/providers/aws/events/http-api). The output of the command appears similar to the following:

   ```bash
   Deploying aws-node-project to stage dev (us-east-1, "default" provider)

   ✔ Service deployed to stack aws-node-project-dev (60s)

   dashboard: https://app.serverless.com/myorg/apps/aws-node-project/aws-node-project/dev/us-east-1

   endpoint: GET - https://ge3onb0klj.execute-api.us-east-1.amazonaws.com/users

   functions:

     getAllUsers: aws-node-project-dev-getAllUsers (225 kB)
   ```

8. Test the generated endpoint by running a cURL command. For example:

   ```bash
   curl https://eg3onb0jkl.execute-api.us-east-1.amazonaws.com/users | jq
   ```

   The response returns the following data:

   ```bash
   {
     "data": [
       {
         "id": 1,
         "name": "Alice",
         "email": "alice@example.com",
         "created_at": "2023-01-10T17:46:29.353Z"
       },
       {
         "id": 2,
         "name": "Bob",
         "email": "bob@example.com",
         "created_at": "2023-01-10T17:46:29.353Z"
       },
       {
         "id": 3,
         "name": "Charlie",
         "email": "charlie@example.com",
         "created_at": "2023-01-10T17:46:29.353Z"
       },
       {
         "id": 4,
         "name": "Dave",
         "email": "dave@example.com",
         "created_at": "2023-01-10T17:46:29.353Z"
       },
       {
         "id": 5,
         "name": "Eve",
         "email": "eve@example.com",
         "created_at": "2023-01-10T17:46:29.353Z"
       }
     ]
   }
   ```

## Enabling CORS

If you make API calls to the Lambda function from your app, you will likely need to configure Cross-Origin Resource Sharing (CORS). Visit the AWS documentation for information about [how to enable CORS in API Gateway](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-cors.html).

You can run the following command to enable CORS to your local development environment:

```bash
aws apigatewayv2 update-api --api-id <api-id> --cors-configuration AllowOrigins="http://localhost:3000"
```

You can find your `api-id` on the API Gateway dashboard:

![Screenshot 2023-01-09 at 16 20 34](https://user-images.githubusercontent.com/13738772/211343246-27259351-d45b-4832-86d3-214431e196aa.png)

## Conclusion

In this guide, you have learned how to set up a Postgres database using Neon and connect to it from an AWS Lambda function using Node.js as the runtime environment. You have also learned how to use Serverless Framework to create and deploy the Lambda function, and how to use the `pg` library to perform basic database read operations.

--- [Document source](https://neon.com/docs/guides/aws-s3.md) ---

> Summary: AWS S3 and Lakebase Postgres integration pattern that stores binary files (images, videos, uploads) in an S3 bucket while persisting file metadata (object key, URL, user ID, timestamp) in a Lakebase Postgres table. Use this guide when you need a scalable file-upload architecture with presigned upload URLs, IAM credentials, CORS configuration, and a queryable metadata index in Postgres. Includes working backend examples in JavaScript (Hono, AWS SDK v3) and Python (Flask, boto3) with an s3_files schema and presign/save-metadata endpoints.

# File storage with AWS S3

Store files via AWS S3 and track metadata in Neon

Last updated: 2026-09-16

[Amazon Simple Storage Service (AWS S3)](https://aws.amazon.com/s3/) is an object storage service widely used for storing and retrieving large amounts of data, such as images, videos, backups, and application assets.

**Neon now offers native storage:**

Neon Object Storage is S3-compatible object storage built into the Neon backend. Object storage branches with your database: each branch gets its own isolated namespace, so you can test file uploads in preview branches without touching production. No separate cloud account needed. Use any S3-compatible SDK with your existing Neon credential.

For more information, see [Neon Object Storage](https://neon.com/docs/storage/overview).

This guide demonstrates how to integrate AWS S3 with Lakebase Postgres by storing file metadata (like the object key and URL) in your database, while using S3 for file storage.

## Setup steps

## Create a Neon project

1. Navigate to the [Neon Console](https://console.neon.tech) to create a new Neon project.
2. Copy the connection string by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Create an AWS account and S3 bucket

1. Sign up for or log in to your [AWS Account](https://aws.amazon.com/).

2. Navigate to the **S3** service in the AWS Management Console.

3. Click **Create bucket**. Provide a unique bucket name (for example, `my-neon-app-s3-uploads`), select an AWS Region (for example, `us-east-1`), and configure initial settings.
   ![Create S3 Bucket](https://neon.com/docs/guides/aws-s3-create-bucket.png)

4. **Public Access (for this example):** For simplicity in accessing uploaded files via URL in this guide, we'll configure the bucket to allow public read access _for objects uploaded with specific permissions_. Under **Block Public Access settings for this bucket**, _uncheck_ "Block all public access". Acknowledge the warning.
   ![Public Access Settings](https://neon.com/docs/guides/aws-s3-public-access.png)

   **Note: Public buckets**

   Making buckets or objects publicly readable carries security risks. For production applications, it's strongly recommended to:

   1. Keep buckets **private** (Block all public access enabled).
   2. Use **presigned URLs** not only for uploads but also for _downloads_ (temporary read access).
      This guide uses public access for simplicity, but you should implement secure access controls in production.

5. After the bucket is created, navigate to the **Permissions** tab. Under **Bucket Policy**, you can set up a policy to allow public read access to objects. For example:

   ```json
   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "PublicReadGetObject",
         "Effect": "Allow",
         "Principal": "*",
         "Action": "s3:GetObject",
         "Resource": "arn:aws:s3:::my-neon-app-s3-uploads/*"
       }
     ]
   }
   ```

   Replace `my-neon-app-s3-uploads` with your actual bucket name.

6. **Create IAM user for programmatic access:**
   - Navigate to the **IAM** service in the AWS Console.
   - Go to **Users** and click **Add users**.
   - Enter a username (for example, `neon-app-s3-user`). Select **Access key - Programmatic access** as the credential type. Click **Next: Permissions**.
   - Choose **Attach policies directly**. Search for and select `AmazonS3FullAccess`.
     ![Attach S3 Policy](https://neon.com/docs/guides/aws-s3-attach-policy.png)
   - Click **Next**, then **Create user**.
   - Click on **Create access key**.
     ![Create Access Key](https://neon.com/docs/guides/aws-s3-create-access-key.png)
   - Click **Other** > **Create access key**. Copy the **Access key ID** and **Secret access key**. These will be used in your application to authenticate with AWS S3.

## Configure CORS for client-side uploads

If your application involves uploading files **directly from a web browser** using the generated presigned URLs, you must configure Cross-Origin Resource Sharing (CORS) on your S3 bucket. CORS rules tell S3 which web domains are allowed to make requests (like `PUT` requests for uploads) to your bucket. Without proper CORS rules, browser security restrictions will block these direct uploads.

In your S3 bucket settings, navigate to the **Permissions** tab and find the **CORS configuration** section. Add the following CORS rules:

```json
[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT"],
    "AllowedOrigins": ["*"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 9000
  }
]
```

> This configuration allows any origin (`*`) to perform `GET` and `PUT` requests. In a production environment, you should restrict `AllowedOrigins` to your application's domain(s) for security.

## Create a table in Neon for file metadata

We need a table in the database to store metadata about the objects uploaded to S3.

1. Connect to your database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a client like [psql](https://neon.com/docs/connect/query-with-psql-editor). Create a table including the object key, URL, user ID, and timestamp:

   ```sql
   CREATE TABLE IF NOT EXISTS s3_files (
       id SERIAL PRIMARY KEY,
       object_key TEXT NOT NULL UNIQUE, -- Key (path/filename) in S3
       file_url TEXT NOT NULL,          -- Publicly accessible URL (if object is public)
       user_id TEXT NOT NULL,           -- User associated with the file
       upload_timestamp TIMESTAMPTZ DEFAULT NOW()
   );
   ```

2. Run the SQL statement. Add other relevant columns as needed (for example, `content_type`, `size`).

**Note: Securing metadata with RLS**

If you use [Row Level Security (RLS)](https://neon.com/blog/introducing-neon-authorize), remember to apply appropriate access policies to the `s3_files` table. This controls who can view or modify the object references stored in the database based on your RLS rules.

Note that these policies apply _only_ to the metadata in the database. Access control for the objects within the S3 bucket itself is managed via S3 bucket policies, IAM permissions, and object ACLs.

## Upload files to S3 and store metadata in Neon

The recommended pattern for client-side uploads to S3 involves **presigned upload URLs**. Your backend generates a temporary URL that the client uses to upload the file directly to S3. Afterwards, your backend saves the file's metadata to Neon.

This requires two backend endpoints:

1. `/presign-upload`: Generates the temporary presigned URL.
2. `/save-metadata`: Records the metadata in Neon after the client confirms successful upload.

**JavaScript**

We'll use [Hono](https://hono.dev/) for the server, [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3) and [`@aws-sdk/s3-request-presigner`](https://www.npmjs.com/package/@aws-sdk/s3-request-presigner) for S3 interaction, and [`@neondatabase/serverless`](https://www.npmjs.com/package/@neondatabase/serverless) for Neon.

First, install the necessary dependencies:

```bash
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @neondatabase/serverless @hono/node-server hono dotenv
```

Create a `.env` file:

```env
# AWS S3 Credentials & Config
AWS_ACCESS_KEY_ID=your_iam_user_access_key_id
AWS_SECRET_ACCESS_KEY=your_iam_user_secret_access_key
AWS_REGION=your_s3_bucket_region # for example, us-east-1
S3_BUCKET_NAME=your_s3_bucket_name # for example, my-neon-app-s3-uploads

# Database Connection String
DATABASE_URL=your_database_connection_string
```

The following code snippet demonstrates this workflow:

```javascript
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { neon } from '@neondatabase/serverless';
import 'dotenv/config';
import { randomUUID } from 'crypto';

const S3_BUCKET = process.env.S3_BUCKET_NAME;
const AWS_REGION = process.env.AWS_REGION;
const s3 = new S3Client({
  region: AWS_REGION,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  },
});
const sql = neon(process.env.DATABASE_URL);
const app = new Hono();

// Replace this with your actual user authentication logic, by validating JWTs/Headers, etc.
const authMiddleware = async (c, next) => {
  c.set('userId', 'user_123');
  await next();
};

// 1. Generate Presigned URL for Upload
app.post('/presign-upload', authMiddleware, async (c) => {
  try {
    const { fileName, contentType } = await c.req.json();
    if (!fileName || !contentType) throw new Error('fileName and contentType required');

    const objectKey = `${randomUUID()}-${fileName}`;
    const publicFileUrl = `https://${S3_BUCKET}.s3.${AWS_REGION}.amazonaws.com/${objectKey}`;

    const command = new PutObjectCommand({
      Bucket: S3_BUCKET,
      Key: objectKey,
      ContentType: contentType,
    });
    const presignedUrl = await getSignedUrl(s3, command, { expiresIn: 300 });

    return c.json({ success: true, presignedUrl, objectKey, publicFileUrl });
  } catch (error) {
    console.error('Presign Error:', error.message);
    return c.json({ success: false, error: 'Failed to prepare upload' }, 500);
  }
});

// 2. Save Metadata after Client Upload Confirmation
app.post('/save-metadata', authMiddleware, async (c) => {
  try {
    const { objectKey, publicFileUrl } = await c.req.json();
    const userId = c.get('userId');
    if (!objectKey) throw new Error('objectKey required');

    await sql`
      INSERT INTO s3_files (object_key, file_url, user_id)
      VALUES (${objectKey}, ${publicFileUrl}, ${userId})
    `;
    console.log(`Metadata saved for S3 object: ${objectKey}`);
    return c.json({ success: true });
  } catch (error) {
    console.error('Metadata Save Error:', error.message);
    return c.json({ success: false, error: 'Failed to save metadata' }, 500);
  }
});

const port = 3000;
serve({ fetch: app.fetch, port }, (info) => {
  console.log(`Server running at http://localhost:${info.port}`);
});
```

**Explanation**

1. **Setup:** Initializes the Neon database client (`sql`), Hono (`app`), and the AWS S3 client (`s3`) configured with region and credentials.
2. **Authentication:** A placeholder `authMiddleware` is included. **Crucially**, this needs to be replaced with real authentication logic. It currently just sets a static `userId` for demonstration.
3. **Upload endpoints:**
   - **`/presign-upload`:** Generates a temporary secure URL (`presignedUrl`) using `@aws-sdk/s3-request-presigner` that allows uploading a file directly to S3. It returns the URL, the generated `objectKey`, and the standard S3 public URL.
   - **`/save-metadata`:** Called by the client _after_ successful upload. Saves the `objectKey`, `file_url`, and `userId` into the `s3_files` table in Neon using `@neondatabase/serverless`.

**Python**

We'll use [Flask](https://flask.palletsprojects.com/en/stable/), [`boto3`](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) (AWS SDK for Python), and [`psycopg2`](https://pypi.org/project/psycopg2/).

First, install the necessary dependencies:

```bash
pip install Flask boto3 psycopg2-binary python-dotenv
```

Create a `.env` file:

```env
# AWS S3 Credentials & Config
AWS_ACCESS_KEY_ID=your_iam_user_access_key_id
AWS_SECRET_ACCESS_KEY=your_iam_user_secret_access_key
AWS_REGION=your_s3_bucket_region # for example, us-east-1
S3_BUCKET_NAME=your_s3_bucket_name # for example, my-neon-app-s3-uploads

# Database Connection String
DATABASE_URL=your_database_connection_string
```

The following code snippet demonstrates this workflow:

```python
import os
import uuid

import boto3
import psycopg2
from botocore.exceptions import ClientError
from dotenv import load_dotenv
from flask import Flask, jsonify, request

load_dotenv()

S3_BUCKET_NAME = os.getenv("S3_BUCKET_NAME")
AWS_REGION = os.getenv("AWS_REGION")
s3_client = boto3.client(
    service_name="s3",
    region_name=AWS_REGION,
    aws_access_key_id=os.getenv("AWS_ACCESS_KEY_ID"),
    aws_secret_access_key=os.getenv("AWS_SECRET_ACCESS_KEY"),
)

app = Flask(__name__)

# Use a global PostgreSQL connection instead of creating a new one for each request in production
def get_db_connection():
    return psycopg2.connect(os.getenv("DATABASE_URL"))

# Replace this with your actual user authentication logic
def get_authenticated_user_id(request):
    # Example: Validate Authorization header, session cookie, etc.
    return "user_123"  # Static ID for demonstration

# 1. Generate Presigned URL for Upload
@app.route("/presign-upload", methods=["POST"])
def presign_upload_route():
    try:
        user_id = get_authenticated_user_id(request)
        data = request.get_json()
        file_name = data.get("fileName")
        content_type = data.get("contentType")
        if not file_name or not content_type:
            raise ValueError("fileName and contentType required")

        object_key = f"{uuid.uuid4()}-{file_name}"
        public_file_url = (
            f"https://{S3_BUCKET_NAME}.s3.{AWS_REGION}.amazonaws.com/{object_key}"
        )

        presigned_url = s3_client.generate_presigned_url(
            "put_object",
            Params={
                "Bucket": S3_BUCKET_NAME,
                "Key": object_key,
                "ContentType": content_type,
            },
            ExpiresIn=300,
        )
        return jsonify(
            {
                "success": True,
                "presignedUrl": presigned_url,
                "objectKey": object_key,
                "publicFileUrl": public_file_url,
            }
        ), 200

    except (ClientError, ValueError) as e:
        print(f"Presign Error: {e}")
        return jsonify(
            {"success": False, "error": f"Failed to prepare upload: {e}"}
        ), 500
    except Exception as e:
        print(f"Unexpected Presign Error: {e}")
        return jsonify({"success": False, "error": "Server error"}), 500


# 2. Save Metadata after Client Upload Confirmation
@app.route("/save-metadata", methods=["POST"])
def save_metadata_route():
    conn = None
    cursor = None
    try:
        user_id = get_authenticated_user_id(request)
        data = request.get_json()
        object_key = data.get("objectKey")
        public_file_url = data.get("publicFileUrl")
        if not object_key:
            raise ValueError("objectKey required")

        conn = get_db_connection()
        cursor = conn.cursor()
        cursor.execute(
            """ INSERT INTO s3_files (object_key, file_url, user_id) VALUES (%s, %s, %s) """,
            (object_key, public_file_url, user_id),
        )
        conn.commit()
        print(f"Metadata saved for S3 object: {object_key}")
        return jsonify({"success": True}), 201
    except (psycopg2.Error, ValueError) as e:
        print(f"Metadata Save Error: {e}")
        return jsonify(
            {"success": False, "error": "Failed to save metadata"}
        ), 500
    except Exception as e:
        print(f"Unexpected Metadata Save Error: {e}")
        return jsonify({"success": False, "error": "Server error"}), 500
    finally:
        if cursor: cursor.close()
        if conn: conn.close()


if __name__ == "__main__":
    port = int(os.environ.get("PORT", 3000))
    app.run(host="0.0.0.0", port=port, debug=True)
```

**Explanation**

1. **Setup:** Initializes Flask, the PostgreSQL client (`psycopg2`), and the AWS S3 client (`boto3`) using environment variables for credentials and configuration.
2. **Authentication:** A placeholder `get_authenticated_user_id` function is included. **Replace this with real authentication logic.**
3. **Upload endpoints:**
   - **`/presign-upload`:** Generates a temporary secure URL (`presignedUrl`) using `boto3` that allows uploading a file directly to S3. It returns the URL, `objectKey`, and the standard public S3 URL.
   - **`/save-metadata`:** Called by the client _after_ successful upload. Saves the `objectKey`, `file_url`, and `userId` into the `s3_files` table in Neon using `psycopg2`.
4. In production, you should use a global PostgreSQL connection instead of creating a new one for each request. This is important for performance and resource management.

## Testing the upload workflow

Testing the presigned URL flow involves multiple steps:

1. **Get presigned URL:** Send a `POST` request to your `/presign-upload` endpoint with a JSON body containing `fileName` and `contentType`.
   **Using cURL:**

   ```bash
   curl -X POST http://localhost:3000/presign-upload \
        -H "Content-Type: application/json" \
        -d '{"fileName": "test-s3.txt", "contentType": "text/plain"}'
   ```

   You should receive a JSON response with a `presignedUrl`, `objectKey`, and `publicFileUrl`:

   ```json
   {
     "success": true,
     "presignedUrl": "https://<BUCKET_NAME>.s3.us-east-1.amazonaws.com/.....&x-id=PutObject",
     "objectKey": "<OBJECT_KEY>",
     "publicFileUrl": "https://<BUCKET_NAME>.s3.us-east-1.amazonaws.com/<OBJECT_KEY>"
   }
   ```

   Note the `presignedUrl`, `objectKey`, and `publicFileUrl` from the response. You will use these in the next steps.

2. **Upload file to S3:** Use the received `presignedUrl` to upload the actual file using an HTTP `PUT` request.
   **Using cURL:**

   ```bash
   curl -X PUT "<PRESIGNED_URL>" \
        --upload-file /path/to/your/test-s3.txt \
        -H "Content-Type: text/plain"
   ```

   A successful upload typically returns HTTP `200 OK` with no body.

3. **Save metadata:** Send a `POST` request to your `/save-metadata` endpoint with the `objectKey` and `publicFileUrl` obtained in step 1.
   **Using cURL:**
   ```bash
   curl -X POST http://localhost:3000/save-metadata \
        -H "Content-Type: application/json" \
        -d '{"objectKey": "<OBJECT_KEY>", "publicFileUrl": "<PUBLIC_URL>"}'
   ```
   You should receive a JSON response indicating success:
   ```json
   { "success": true }
   ```

**Expected outcome:**

- The file appears in your S3 bucket (check the AWS Console).
- A new row appears in your `s3_files` table in Neon containing the `object_key` and `file_url`.

You can now integrate API calls to these endpoints from various parts of your application (for example, web clients using JavaScript's `fetch` API, mobile apps, backend services) to handle file uploads.

## Accessing file metadata and files

Storing metadata in the database allows your application to easily retrieve references to the files hosted on S3.

Query the `s3_files` table from your application's backend when needed.

**Example SQL query:**

Retrieve files for user 'user_123':

```sql
SELECT
    id,
    object_key,     -- Key (path/filename) in S3
    file_url,       -- Publicly accessible S3 URL
    user_id,        -- User associated with the file
    upload_timestamp
FROM
    s3_files
WHERE
    user_id = 'user_123'; -- Use actual authenticated user ID
```

**Using the data:**

- The query returns metadata stored in the database.
- The `file_url` column contains the direct link to access the file via S3.
- Use this `file_url` in your application (for example, `<img>` tags, download links)

  **Note: Private buckets**

  For private S3 buckets, store only the `object_key` and generate presigned _read_ URLs on demand using a similar backend process.

This pattern effectively separates file storage and delivery concerns (handled by S3) from structured metadata management (handled by Postgres), leveraging the strengths of both services.

## Resources

- [AWS S3 documentation](https://docs.aws.amazon.com/s3/index.html)
- [AWS: Sharing objects with presigned URLs](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html)

--- [Document source](https://neon.com/docs/guides/azure-blob-storage.md) ---

> Summary: Azure Blob Storage integration with Neon keeps binary file objects in Azure while storing metadata (blob name, URL, user ID, upload timestamp) in a Neon Postgres table, giving apps structured querying over unstructured files. Use this page when you need client-side uploads via short-lived SAS tokens and want Neon to index what was uploaded without making blobs publicly accessible. The guide covers private-container setup with CORS, backend endpoints (generate-upload-sas and save-metadata) in JavaScript (Hono) and Python (Flask), and generating read-only SAS tokens for secure file retrieval.

# File storage with Azure Blob Storage

Store files via Azure Blob Storage and track metadata in Neon

Last updated: 2026-10-28

[Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/) is Microsoft's object storage solution for the cloud. It's optimized for storing massive amounts of unstructured data, such as text or binary data, including images, documents, streaming media, and archive data.

**Neon now offers native storage:**

Neon Object Storage is S3-compatible object storage built into the Neon backend. Object storage branches with your database: each branch gets its own isolated namespace, so you can test file uploads in preview branches without touching production. No separate cloud account needed. Use any S3-compatible SDK with your existing Neon credential.

For more information, see [Neon Object Storage](https://neon.com/docs/storage/overview).

This guide demonstrates how to integrate Azure Blob Storage with Neon by storing file metadata (like the blob name and URL) in your Neon database, while using Azure Blob Storage for file storage.

## Prerequisites

## Create a Neon project

1. Navigate to the [Neon Console](https://console.neon.tech) to create a new Neon project.
2. Copy the connection string by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Create an Azure account, storage account, and container

1. Sign up for or log in to your [Azure Account](https://azure.microsoft.com/free/).

2. Navigate to [Storage accounts](https://portal.azure.com/#create/Microsoft.StorageAccount) in the Azure portal.

3. Click **+ Create**. Fill in the required details: select a Subscription, create or select a Resource group, provide a unique Storage account name (for example, `myneonappblobstorage`), choose a Region (for example, `East US`), and select performance/redundancy options (Standard/LRS is fine for this example). Click **Review + create**, then **Create**.
   ![Azure Storage Account Creation](https://neon.com/docs/guides/azure-blob-storage-creation.png)

4. Once the storage account is deployed, go to the resource.

5. In the storage account menu, under **Data storage**, click **Containers**.

6. Click **+ Container**. Provide a name for your container (for example, `uploads`), set the **Public access level** to **Private (no anonymous access)**. This is the recommended setting for security; we will use SAS tokens for controlled access. Click **Create**.
   ![Azure Storage Container Creation](https://neon.com/docs/guides/azure-blob-storage-container-creation.png)

   **Note: Public access vs. SAS tokens**

   While you _can_ set container access levels to allow public read access (`Blob` or `Container`), it's generally more secure to keep containers private and use **Shared Access Signatures (SAS)** tokens for both uploads and downloads. SAS tokens provide temporary, granular permissions. This guide focuses on using SAS tokens for uploads. For serving files, you can either generate read-only SAS tokens on demand or, if needed, set the container to public `Blob` access.

7. **Get connection string:**
   - In your storage account menu, under **Security + networking**, click **Access keys**.
   - Copy one of the **Connection strings**. This will be used by your backend application to authenticate with Azure Blob Storage. Store it securely.
     ![Azure Storage Account Access Keys](https://neon.com/docs/guides/azure-blob-storage-access-keys.png)

## Configure CORS for client-side uploads

If your application involves uploading files **directly from a web browser** using the generated SAS URLs, you must configure Cross-Origin Resource Sharing (CORS) on your Azure Storage account. CORS rules tell Azure Storage which web domains are allowed to make requests (like `PUT` requests for uploads) to your blob service endpoint. Without proper CORS rules, browser security restrictions will block these direct uploads.

Follow Azure's guide to [Configure CORS for Azure Storage](https://docs.microsoft.com/en-us/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services). You can configure CORS rules via the Azure portal (Storage account > Settings > Resource sharing (CORS) > Blob service tab).

Here's an example CORS configuration allowing `PUT` uploads and `GET` requests from your deployed frontend application and your local development environment:

- **Allowed origins:** `https://your-production-app.com`, `http://localhost:3000` (Replace with your actual domains/ports)
- **Allowed methods:** `PUT`, `GET`
- **Allowed headers:** `*` (Or be more specific, for example, `Content-Type`, `x-ms-blob-type`)
- **Exposed headers:** `*`
- **Max age (seconds):** `3600` (Example: 1 hour)

  ![Azure Storage CORS Configuration](https://neon.com/docs/guides/azure-blob-storage-cors.png)

## Create a table in Neon for file metadata

We need a table in Neon to store metadata about the blobs uploaded to Azure Storage.

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a client like [psql](https://neon.com/docs/connect/query-with-psql-editor). Create a table including the blob name, URL, user ID, and timestamp:

   ```sql
   CREATE TABLE IF NOT EXISTS azure_files (
       id SERIAL PRIMARY KEY,
       blob_name TEXT NOT NULL UNIQUE,  -- Name (path/filename) in Azure Blob Storage container
       file_url TEXT NOT NULL,          -- Publicly accessible URL (base URL, SAS might be needed for access)
       user_id TEXT NOT NULL,           -- User associated with the file
       upload_timestamp TIMESTAMPTZ DEFAULT NOW()
   );
   ```

2. Run the SQL statement. Add other relevant columns as needed (for example, `content_type`, `size`).

**Note: Securing metadata with RLS**

If you use [Neon's Row Level Security (RLS)](https://neon.com/blog/introducing-neon-authorize), remember to apply appropriate access policies to the `azure_files` table. This controls who can view or modify the object references stored in Neon based on your RLS rules.

Note that these policies apply _only_ to the metadata in Neon. Access control for the blobs within the Azure container itself is managed via Azure RBAC, SAS tokens, and container access level settings.

## Upload files to Azure Blob Storage and store metadata in Neon

The recommended pattern for client-side uploads to Azure Blob Storage involves **SAS (Shared Access Signature) URLs**. Your backend generates a temporary URL containing a SAS token that grants specific permissions (like writing a blob) for a limited time. The client uses this SAS URL to upload the file directly to Azure Blob Storage. Afterwards, your backend saves the file's metadata to Neon.

This requires two backend endpoints:

1. `/generate-upload-sas`: Generates the temporary SAS URL for the client.
2. `/save-metadata`: Records the metadata in Neon after the client confirms successful upload.

**JavaScript**

We'll use [Hono](https://hono.dev/) for the server, [`@azure/storage-blob`](https://www.npmjs.com/package/@azure/storage-blob) for Azure interaction, and [`@neondatabase/serverless`](https://www.npmjs.com/package/@neondatabase/serverless) for Neon.

First, install the necessary dependencies:

```bash
npm install @azure/storage-blob @neondatabase/serverless @hono/node-server hono dotenv
```

Create a `.env` file:

```env
# Azure Blob Storage Config
AZURE_STORAGE_CONNECTION_STRING="your_storage_account_connection_string"
AZURE_STORAGE_CONTAINER_NAME=your_container_name # for example, uploads

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```javascript
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import {
  BlobServiceClient,
  generateBlobSASQueryParameters,
  BlobSASPermissions,
  SASProtocol,
} from '@azure/storage-blob';
import { neon } from '@neondatabase/serverless';
import 'dotenv/config';
import { randomUUID } from 'crypto';

const AZURE_CONNECTION_STRING = process.env.AZURE_STORAGE_CONNECTION_STRING;
const AZURE_CONTAINER_NAME = process.env.AZURE_STORAGE_CONTAINER_NAME;
const blobServiceClient = BlobServiceClient.fromConnectionString(AZURE_CONNECTION_STRING);
const containerClient = blobServiceClient.getContainerClient(AZURE_CONTAINER_NAME);

const sql = neon(process.env.DATABASE_URL);
const app = new Hono();

// Replace this with your actual user authentication logic, by validating JWTs/Headers, etc.
const authMiddleware = async (c, next) => {
  c.set('userId', 'user_123');
  await next();
};

// 1. Generate SAS URL for upload
app.post('/generate-upload-sas', authMiddleware, async (c) => {
  try {
    const { fileName, contentType } = await c.req.json();
    if (!fileName || !contentType) throw new Error('fileName and contentType required');

    const blobName = `${randomUUID()}-${fileName}`;
    const blobClient = containerClient.getBlockBlobClient(blobName);
    const fileUrl = blobClient.url;

    const sasOptions = {
      containerName: AZURE_CONTAINER_NAME,
      blobName: blobName,
      startsOn: new Date(),
      expiresOn: new Date(new Date().valueOf() + 300 * 1000), // 5 minutes expiry
      permissions: BlobSASPermissions.parse('w'), // Write permission
      protocol: SASProtocol.Https,
      contentType: contentType,
    };

    const sasToken = generateBlobSASQueryParameters(
      sasOptions,
      blobServiceClient.credential
    ).toString();
    const sasUrl = `${fileUrl}?${sasToken}`;

    return c.json({ success: true, sasUrl, blobName, fileUrl });
  } catch (error) {
    console.error('SAS Generation Error:', error.message);
    return c.json({ success: false, error: 'Failed to prepare upload URL' }, 500);
  }
});

// 2. Save metadata after client upload confirmation
app.post('/save-metadata', authMiddleware, async (c) => {
  try {
    const { blobName, fileUrl } = await c.req.json();
    const userId = c.get('userId');
    if (!blobName || !fileUrl) throw new Error('blobName and fileUrl required');

    await sql`
      INSERT INTO azure_files (blob_name, file_url, user_id)
      VALUES (${blobName}, ${fileUrl}, ${userId})
    `;
    console.log(`Metadata saved for Azure blob: ${blobName}`);
    return c.json({ success: true });
  } catch (error) {
    console.error('Metadata Save Error:', error.message);
    return c.json({ success: false, error: 'Failed to save metadata' }, 500);
  }
});

const port = 3000;
serve({ fetch: app.fetch, port }, (info) => {
  console.log(`Server running at http://localhost:${info.port}`);
});
```

**Explanation**

1. **Setup:** Initializes Neon client (`sql`), Hono (`app`), and Azure `BlobServiceClient` using the connection string.
2. **Authentication:** Placeholder `authMiddleware` needs replacing with actual user validation.
3. **Upload endpoints:**
   - **`/generate-upload-sas`:** Creates a unique `blobName`, gets a `BlockBlobClient`, and generates a SAS token using `generateBlobSASQueryParameters` with write permissions (`w`) and a short expiry. It returns the full `sasUrl` (base URL + SAS token), the `blobName`, and the base `fileUrl`.
   - **`/save-metadata`:** Called by the client _after_ successful upload. Saves the `blobName`, base `fileUrl`, and `userId` into the `azure_files` table in Neon.

**Python**

We'll use [Flask](https://flask.palletsprojects.com/en/stable/), [`azure-storage-blob`](https://pypi.org/project/azure-storage-blob/) (Azure SDK for Python), and [`psycopg2`](https://pypi.org/project/psycopg2/).

First, install the necessary dependencies:

```bash
pip install Flask azure-storage-blob psycopg2-binary python-dotenv python-dateutil
```

Create a `.env` file:

```env
# Azure Blob Storage Config
AZURE_STORAGE_CONNECTION_STRING="your_storage_account_connection_string"
AZURE_STORAGE_CONTAINER_NAME=your_container_name # for example, uploads

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```python
import os
import uuid
from datetime import datetime, timedelta, timezone
import psycopg2
from azure.storage.blob import BlobSasPermissions, BlobServiceClient, generate_blob_sas
from dotenv import load_dotenv
from flask import Flask, jsonify, request

load_dotenv()

AZURE_CONNECTION_STRING = os.getenv("AZURE_STORAGE_CONNECTION_STRING")
AZURE_CONTAINER_NAME = os.getenv("AZURE_STORAGE_CONTAINER_NAME")
DATABASE_URL = os.getenv("DATABASE_URL")

blob_service_client = BlobServiceClient.from_connection_string(
    AZURE_CONNECTION_STRING
)
container_client = blob_service_client.get_container_client(AZURE_CONTAINER_NAME)

app = Flask(__name__)

# Use a global PostgreSQL connection instead of creating a new one for each request in production
def get_db_connection():
    return psycopg2.connect(os.getenv("DATABASE_URL"))

# Replace this with your actual user authentication logic
def get_authenticated_user_id(request):
    # Example: Validate Authorization header, session cookie, etc.
    return "user_123"  # Static ID for demonstration

# 1. Generate SAS URL for upload
@app.route("/generate-upload-sas", methods=["POST"])
def generate_upload_sas_route():
    try:
        user_id = get_authenticated_user_id(request)
        data = request.get_json()
        file_name = data.get("fileName")
        content_type = data.get("contentType")
        if not file_name or not content_type:
            raise ValueError("fileName and contentType are required in JSON body.")

        blob_name = f"{uuid.uuid4()}-{file_name}"
        blob_client = container_client.get_blob_client(blob_name)
        file_url = blob_client.url

        start_time = datetime.now(timezone.utc)
        expiry_time = start_time + timedelta(minutes=5)  # 5 minutes expiry

        sas_token = generate_blob_sas(
            account_name=blob_service_client.account_name,
            container_name=AZURE_CONTAINER_NAME,
            blob_name=blob_name,
            account_key=blob_service_client.credential.account_key,
            permission=BlobSasPermissions(write=True),  # Write permission for upload
            expiry=expiry_time,
            start=start_time,
            content_type=content_type
        )

        sas_url = f"{file_url}?{sas_token}"

        return jsonify(
            {
                "success": True,
                "sasUrl": sas_url,
                "blobName": blob_name,
                "fileUrl": file_url,
            }
        ), 200

    except ValueError as e:
        print(f"SAS Generation Input Error: {e}")
        return jsonify({"success": False, "error": str(e)}), 400
    except Exception as e:
        print(f"SAS Generation Error: {e}")
        return jsonify({"success": False, "error": "Failed to prepare upload URL"}), 500


# 2. Save metadata after client upload confirmation
@app.route("/save-metadata", methods=["POST"])
def save_metadata_route():
    conn = None
    cursor = None
    try:
        user_id = get_authenticated_user_id(request)
        data = request.get_json()
        blob_name = data.get("blobName")
        file_url = data.get("fileUrl")
        if not blob_name or not file_url:
            raise ValueError("blobName and fileUrl are required in JSON body.")

        conn = get_db_connection()
        cursor = conn.cursor()
        cursor.execute(
            """ INSERT INTO azure_files (blob_name, file_url, user_id) VALUES (%s, %s, %s) """,
            (blob_name, file_url, user_id),
        )
        conn.commit()
        print(f"Metadata saved for Azure blob: {blob_name}")
        return jsonify({"success": True}), 201

    except psycopg2.Error as db_err:
        print(f"Database Save Error: {db_err}")
        return jsonify(
            {
                "success": False,
                "error": "Failed to save metadata",
            }
        ), 500
    except Exception as e:
        print(f"Unexpected Metadata Save Error: {e}")
        return jsonify(
            {"success": False, "error": "Server error during metadata save."}
        ), 500
    finally:
        if cursor: cursor.close()
        if conn: conn.close()


if __name__ == "__main__":
    port = int(os.environ.get("PORT", 3000))
    app.run(host="0.0.0.0", port=port, debug=True)
```

**Explanation**

1. **Setup:** Initializes Flask, `BlobServiceClient`, and `psycopg2` using environment variables.
2. **Authentication:** A placeholder `get_authenticated_user_id` function is included. **Replace this with real authentication logic**.
3. **Upload endpoints:**
   - **`/generate-upload-sas`:** Creates a unique `blobName`, gets the base `fileUrl`, and generates a SAS token using `generate_blob_sas` with write permissions and a short expiry. Returns the full `sasUrl`, `blobName`, and base `fileUrl`.
   - **`/save-metadata`:** Called by the client _after_ successful upload. Saves the `blobName`, base `fileUrl`, and `userId` into the `azure_files` table using `psycopg2`.
4. In production, you should use a global PostgreSQL connection instead of creating a new one for each request. This is important for performance and resource management.

## Testing the upload workflow

Testing the SAS URL flow involves multiple steps:

1. **Get SAS URL:** Send a `POST` request to your `/generate-upload-sas` endpoint with a JSON body containing `fileName` and `contentType`.
   **Using cURL:**

   ```bash
   curl -X POST http://localhost:3000/generate-upload-sas \
        -H "Content-Type: application/json" \
        -d '{"fileName": "test-azure.txt", "contentType": "text/plain"}'
   ```

   You should receive a JSON response with a `sasUrl`, `blobName`, and `fileUrl`:

   ```json
   {
     "success": true,
     "sasUrl": "https://<ACCOUNT_NAME>.blob.core.windows.net/<CONTAINER>/<BLOB_NAME>?<SAS_TOKEN>",
     "blobName": "<BLOB_NAME>",
     "fileUrl": "https://<ACCOUNT_NAME>.blob.core.windows.net/<CONTAINER>/<BLOB_NAME>"
   }
   ```

   Note the `sasUrl`, `blobName`, and `fileUrl` from the response. You will use these in the next steps.

2. **Upload file to Azure:** Use the received `sasUrl` to upload the actual file using an HTTP `PUT` request. You also need to set the `Content-Type` header to match what was specified during SAS generation and `x-ms-blob-type: BlockBlob`.
   **Using cURL:**

   ```bash
   curl -X PUT "<SAS_URL>" \
        --upload-file /path/to/your/test-azure.txt \
        -H "Content-Type: text/plain" \
        -H "x-ms-blob-type: BlockBlob"
   ```

   A successful upload returns HTTP `201 Created`.

3. **Save metadata:** Send a `POST` request to your `/save-metadata` endpoint with the `blobName` and base `fileUrl` from step 1.
   **Using cURL:**

   ```bash
   curl -X POST http://localhost:3000/save-metadata \
        -H "Content-Type: application/json" \
        -d '{"blobName": "<BLOB_NAME_FROM_STEP_1>", "fileUrl": "<FILE_URL_FROM_STEP_1>"}'
   ```

   You should receive a JSON response indicating success:

   ```json
   { "success": true }
   ```

**Expected outcome:**

- The file appears in your Azure Blob Storage container (check the Azure Portal).
- A new row appears in your `azure_files` table in Neon.

You can now integrate API calls to these endpoints from various parts of your application (for example, web clients using JavaScript `fetch` API, mobile apps, backend services) to handle file uploads.

## Accessing file metadata and files

Storing metadata in Neon allows your application to easily retrieve references to the files hosted on Azure Blob Storage.

Query the `azure_files` table from your application's backend when needed.

**Example SQL query:**

Retrieve files for user 'user_123':

```sql
SELECT
    id,
    blob_name,       -- Name (path/filename) in Azure container
    file_url,        -- Base URL of the blob
    user_id,         -- User associated with the file
    upload_timestamp
FROM
    azure_files
WHERE
    user_id = 'user_123'; -- Use actual authenticated user ID
```

**Using the data:**

- The query returns metadata stored in Neon.
- The `file_url` column contains the base URL of the blob.
- **Accessing the file:**

  - If your container allows public `Blob` access, this `file_url` might be directly usable.
  - If your container is **private** (recommended), you need to generate a **read-only SAS token** for the specific `blob_name` on demand using your backend (similar to the upload SAS generation, but with `BlobSASPermissions.parse("r")` or `BlobSasPermissions(read=True)`) and append it to the `file_url`. This provides secure, temporary read access.
  - Use the resulting URL (base URL or URL with read SAS token) in your application (for example, `<img>` tags, download links).

  For example here's how to generate a read SAS URL:

  **JavaScript**

  ```javascript
  import {
    BlobServiceClient,
    generateBlobSASQueryParameters,
    BlobSASPermissions,
    SASProtocol,
  } from '@azure/storage-blob';
  const AZURE_CONTAINER_NAME = process.env.AZURE_STORAGE_CONTAINER_NAME;

  const blobServiceClient = BlobServiceClient.fromConnectionString(
    process.env.AZURE_STORAGE_CONNECTION_STRING
  );

  async function generateReadOnlySasUrl(blobName, expiryMinutes = 15) {
    const containerClient = blobServiceClient.getContainerClient(AZURE_CONTAINER_NAME);
    const blobClient = containerClient.getBlobClient(blobName);

    const sasOptions = {
      containerName: AZURE_CONTAINER_NAME,
      blobName: blobName,
      startsOn: new Date(),
      expiresOn: new Date(new Date().valueOf() + expiryMinutes * 60 * 1000),
      permissions: BlobSASPermissions.parse('r'), // Read ('r') permission
      protocol: SASProtocol.Https,
    };

    const sasToken = generateBlobSASQueryParameters(
      sasOptions,
      blobServiceClient.credential
    ).toString();

    const sasUrl = `${blobClient.url}?${sasToken}`;
    return sasUrl;
  }

  // Replace '<BLOB_NAME_FROM_DB>' with the actual blob name
  generateReadOnlySasUrl('<BLOB_NAME_FROM_DB>')
    .then((url) => {
      console.log('Read-only SAS URL:', url);
    })
    .catch((error) => {
      console.error('Error generating read SAS URL:', error);
    });
  ```

  **Python**

  ```python
  import os
  from datetime import datetime, timedelta, timezone
  from azure.storage.blob import BlobSasPermissions, BlobServiceClient, generate_blob_sas

  AZURE_CONTAINER_NAME = os.getenv("AZURE_STORAGE_CONTAINER_NAME")

  blob_service_client = BlobServiceClient.from_connection_string(
      os.getenv("AZURE_STORAGE_CONNECTION_STRING")
  )

  def generate_read_only_sas_url(blob_name, expiry_minutes=15):
      blob_client = blob_service_client.get_blob_client(
          container=AZURE_CONTAINER_NAME, blob=blob_name
      )

      start_time = datetime.now(timezone.utc)
      expiry_time = start_time + timedelta(minutes=expiry_minutes)
      sas_token = generate_blob_sas(
          account_name=blob_service_client.account_name,
          container_name=AZURE_CONTAINER_NAME,
          blob_name=blob_name,
          account_key=blob_service_client.credential.account_key,
          permission=BlobSasPermissions(read=True), # Read permission
          expiry=expiry_time,
          start=start_time,
      )

      sas_url = f"{blob_client.url}?{sas_token}"
      return sas_url

  if __name__ == "__main__":
      # Replace '<BLOB_NAME_FROM_DB>' with the actual blob name
      test_blob_name = "<BLOB_NAME_FROM_DB>"
      read_url = generate_read_only_sas_url(test_blob_name)
      print(f"Read-only SAS URL: {read_url}")
  ```

  **Note: Private containers & read access**

  For private containers, always generate short-lived read SAS tokens when a user needs to access a file. Store only the `blob_name` and base `file_url` (or just `blob_name`) in Neon, and construct the full SAS URL in your backend when serving the file reference to the client.

This pattern effectively separates file storage and delivery concerns (handled by Azure Blob Storage) from structured metadata management (handled by Neon), leveraging the strengths of both services.

## Resources

- [Azure Blob Storage documentation](https://learn.microsoft.com/en-us/azure/storage/blobs/)
- [Azure Storage Shared Access Signatures (SAS)](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview)
- [Neon Documentation](https://neon.com/docs)

--- [Document source](https://neon.com/docs/guides/backblaze-b2.md) ---

> Summary: Backblaze B2 and Neon integration guide that splits file storage from structured data: B2 holds the objects (images, videos, backups) via S3-compatible presigned upload URLs, while Neon stores file metadata (object key, public URL, user ID, timestamp) in a Postgres table. Use this page when you need affordable object storage paired with relational metadata queries and want to avoid storing files in Postgres itself. Covers CORS setup for browser-direct uploads, bucket and application-key creation, and backend implementations in JavaScript (Hono, @aws-sdk/client-s3) and Python (Flask, boto3).

# File storage with Backblaze B2

Store files via Backblaze B2 and track metadata in Neon

Last updated: 2026-10-28

[Backblaze B2 Cloud Storage](https://www.backblaze.com/cloud-storage) is an S3-compatible object storage service known for its affordability and ease of use. It's suitable for storing large amounts of unstructured data like backups, archives, images, videos, and application assets.

**Neon now offers native storage:**

Neon Object Storage is S3-compatible object storage built into the Neon backend. Object storage branches with your database: each branch gets its own isolated namespace, so you can test file uploads in preview branches without touching production. No separate cloud account needed. Use any S3-compatible SDK with your existing Neon credential.

For more information, see [Neon Object Storage](https://neon.com/docs/storage/overview).

This guide demonstrates how to integrate Backblaze B2 with Neon by storing file metadata (like the file id, name and URL) in your Neon database, while using B2 for file storage.

## Prerequisites

## Create a Neon project

1. Navigate to the [Neon Console](https://console.neon.tech) to create a new Neon project.
2. Copy the connection string by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Create a Backblaze account and B2 bucket

1. Sign up for or log in to your [Backblaze account](https://www.backblaze.com/sign-up/cloud-storage?referrer=getstarted).
2. Navigate to **B2 Cloud Storage** > **Buckets** in the left sidebar.
3. Click **Create a Bucket**. Provide a globally unique bucket name (for example, `my-neon-app-b2-files`), choose whether files should be **Private** or **Public**. For this guide, we'll use **Public** for simplicity, but **Private** is recommended for production applications where you want to control access to files.
   ![Create B2 Bucket](https://neon.com/docs/guides/backblaze-b2-create-bucket.png)
4. **Create application key:**
   - Navigate to **B2 Cloud Storage** > **Application Keys** in the left sidebar.
   - Click **+ Add a New Application Key**.
   - Give the key a name (for example, `neon-app-b2-key`).
   - **Crucially**, restrict the key's access: Select **Allow access to Bucket(s)** and choose the bucket you just created (for example, `my-neon-app-b2-files`).
   - Select **Read and Write** for the **Type of Access**.
   - Leave other fields blank unless needed (for example, File name prefix).
   - Click **Create New Key**.
   - Copy the **Key ID** and **Application Key**. These will be used in your application to authenticate with B2.
     ![Create B2 Application Key](https://neon.com/docs/guides/backblaze-b2-create-app-key.png)
5. **Find S3 endpoint:**
   - Navigate back to **B2 Cloud Storage** > **Buckets**.
   - Find your bucket and note the **Endpoint** URL listed (for example, `s3.us-west-000.backblazeb2.com`). You'll need this S3-compatible endpoint for the SDK configuration.
     ![B2 Bucket Endpoint](https://neon.com/docs/guides/backblaze-b2-bucket-endpoint.png)

## Configure CORS for client-side uploads

If your application involves uploading files **directly from a web browser** using the generated presigned URLs, you must configure Cross-Origin Resource Sharing (CORS) rules for your B2 bucket. CORS rules tell B2 which web domains are allowed to make requests (like `PUT` requests for uploads) to your bucket. Without proper CORS rules, browser security restrictions will block these direct uploads.

Follow Backblaze's guide to [Cross-Origin Resource Sharing Rules](https://www.backblaze.com/docs/cloud-storage-cross-origin-resource-sharing-rules). You configure CORS rules in the B2 Bucket Settings page in the Backblaze web UI.

Here's an example CORS configuration allowing `http://localhost:3000` to view and upload files:
![Example CORS configuration](https://neon.com/docs/guides/backblaze-b2-cors-example.png)

> In a production environment, replace `http://localhost:3000` with your actual domain

## Create a table in Neon for file metadata

We need a table in Neon to store metadata about the objects uploaded to B2.

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a client like [psql](https://neon.com/docs/connect/query-with-psql-editor). Create a table including the B2 file name (object key), file URL, user ID, and timestamp:

   ```sql
   CREATE TABLE IF NOT EXISTS b2_files (
       id SERIAL PRIMARY KEY,
       object_key TEXT NOT NULL UNIQUE, -- Key (path/filename) in B2
       file_url TEXT,                   -- Base public URL
       user_id TEXT NOT NULL,           -- User associated with the file
       upload_timestamp TIMESTAMPTZ DEFAULT NOW()
   );
   ```

   > Storing the full public `file_url` is only useful if the bucket is public. For private buckets, you'll typically only store the `object_key` and generate presigned download URLs on demand.

2. Run the SQL statement. Add other relevant columns as needed (for example, `content_type`, `size` if needed).

**Note: Securing metadata with RLS**

If you use [Neon's Row Level Security (RLS)](https://neon.com/blog/introducing-neon-authorize), remember to apply appropriate access policies to the `b2_files` table. This controls who can view or modify the object references stored in Neon based on your RLS rules.

Note that these policies apply _only_ to the metadata in Neon. Access control for the objects within the B2 bucket itself is managed via B2 bucket settings (public/private), Application Key permissions, and presigned URL settings.

## Upload files to B2 and store metadata in Neon

Leveraging B2's S3 compatibility, the recommended pattern for client-side uploads involves **presigned upload URLs**. Your backend generates a temporary URL that the client uses to upload the file directly to B2. Afterwards, your backend saves the file's metadata to Neon.

This requires two backend endpoints:

1. `/presign-b2-upload`: Generates the temporary presigned URL.
2. `/save-b2-metadata`: Records the metadata in Neon after the client confirms successful upload.

**JavaScript**

We'll use [Hono](https://hono.dev/) for the server, [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3) and [`@aws-sdk/s3-request-presigner`](https://www.npmjs.com/package/@aws-sdk/s3-request-presigner) for B2 interaction (due to S3 compatibility), and [`@neondatabase/serverless`](https://www.npmjs.com/package/@neondatabase/serverless) for Neon.

First, install the necessary dependencies:

```bash
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @neondatabase/serverless @hono/node-server hono dotenv
```

Create a `.env` file:

```env
# Backblaze B2 Credentials & Config
B2_APPLICATION_KEY_ID=your_b2_key_id
B2_APPLICATION_KEY=your_b2_application_key
B2_BUCKET_NAME=your_b2_bucket_name
B2_ENDPOINT_URL=https://your_b2_s3_endpoint

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```javascript
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { neon } from '@neondatabase/serverless';
import 'dotenv/config';
import { randomUUID } from 'crypto';

const B2_BUCKET = process.env.B2_BUCKET_NAME;
const B2_ENDPOINT = process.env.B2_ENDPOINT_URL;
const endpointUrl = new URL(B2_ENDPOINT);
const region = endpointUrl.hostname.split('.')[1];

const s3 = new S3Client({
  endpoint: B2_ENDPOINT,
  region: region,
  credentials: {
    accessKeyId: process.env.B2_APPLICATION_KEY_ID,
    secretAccessKey: process.env.B2_APPLICATION_KEY,
  },
});
const sql = neon(process.env.DATABASE_URL);
const app = new Hono();

// Replace this with your actual user authentication logic, by validating JWTs/Headers, etc.
const authMiddleware = async (c, next) => {
  c.set('userId', 'user_123');
  await next();
};

// 1. Generate presigned URL for upload
app.post('/presign-b2-upload', authMiddleware, async (c) => {
  try {
    const { fileName, contentType } = await c.req.json();
    if (!fileName || !contentType) throw new Error('fileName and contentType required');

    const objectKey = `${randomUUID()}-${fileName}`;
    const publicFileUrl = `${B2_ENDPOINT}/${B2_BUCKET}/${objectKey}`;

    const command = new PutObjectCommand({
      Bucket: B2_BUCKET,
      Key: objectKey,
      ContentType: contentType,
    });
    const presignedUrl = await getSignedUrl(s3, command, { expiresIn: 300 }); // 5 min expiry

    return c.json({ success: true, presignedUrl, objectKey, publicFileUrl });
  } catch (error) {
    console.error('Presign Error:', error.message);
    return c.json({ success: false, error: 'Failed to prepare upload' }, 500);
  }
});

// 2. Save metadata after client upload confirmation
app.post('/save-b2-metadata', authMiddleware, async (c) => {
  try {
    const { objectKey, publicFileUrl } = await c.req.json();
    const userId = c.get('userId');
    if (!objectKey) throw new Error('objectKey required');

    await sql`
      INSERT INTO b2_files (object_key, file_url, user_id)
      VALUES (${objectKey}, ${publicFileUrl}, ${userId})
    `;
    console.log(`Metadata saved for B2 object: ${objectKey}`);
    return c.json({ success: true });
  } catch (error) {
    console.error('Metadata Save Error:', error.message);
    return c.json({ success: false, error: 'Failed to save metadata' }, 500);
  }
});

const port = 3000;
serve({ fetch: app.fetch, port }, (info) => {
  console.log(`Server running at http://localhost:${info.port}`);
});
```

**Explanation**

1. **Setup:** Initializes Neon (`sql`), Hono (`app`), and the AWS S3 client (`s3`) configured with the B2 endpoint, region (extracted from endpoint), and B2 Application Key credentials.
2. **Authentication:** A placeholder `authMiddleware` is included. **Replace this with real authentication logic.** It currently just sets a static `userId` for demonstration.
3. **Upload endpoints:**
   - **`/presign-b2-upload`:** Generates a temporary secure URL (`presignedUrl`) using `@aws-sdk/s3-request-presigner` that allows uploading a file directly to B2. It returns the URL, the generated `objectKey`, and the standard S3 public URL.
   - **`/save-b2-metadata`:** Called by the client after successful upload. Saves the `objectKey`, `file_url`, and `userId` into the `b2_files` table in Neon using `@neondatabase/serverless`.

**Python**

We'll use [Flask](https://flask.palletsprojects.com/en/stable/), [`boto3`](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) (AWS SDK for Python, leveraging S3 compatibility), and [`psycopg2`](https://pypi.org/project/psycopg2/).

First, install the necessary dependencies:

```bash
pip install Flask boto3 psycopg2-binary python-dotenv
```

Create a `.env` file:

```env
# Backblaze B2 Credentials & Config
B2_APPLICATION_KEY_ID=your_b2_key_id
B2_APPLICATION_KEY=your_b2_application_key
B2_BUCKET_NAME=your_b2_bucket_name
B2_ENDPOINT_URL=https://your_b2_s3_endpoint

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```python
import os
import uuid
import boto3
import psycopg2
from dotenv import load_dotenv
from urllib.parse import urlparse
from flask import Flask, jsonify, request
from botocore.exceptions import ClientError

load_dotenv()

B2_BUCKET_NAME = os.getenv("B2_BUCKET_NAME")
B2_ENDPOINT_URL = os.getenv("B2_ENDPOINT_URL")
parsed_endpoint = urlparse(B2_ENDPOINT_URL)
region_name = parsed_endpoint.hostname.split(".")[1]
s3_client = boto3.client(
    service_name="s3",
    endpoint_url=B2_ENDPOINT_URL,
    aws_access_key_id=os.getenv("B2_APPLICATION_KEY_ID"),
    aws_secret_access_key=os.getenv("B2_APPLICATION_KEY"),
    region_name=region_name
)

app = Flask(__name__)

# Use a global PostgreSQL connection instead of creating a new one for each request in production
def get_db_connection():
    return psycopg2.connect(os.getenv("DATABASE_URL"))

# Replace this with your actual user authentication logic
def get_authenticated_user_id(request):
    # Example: Validate Authorization header, session cookie, etc.
    return "user_123"  # Static ID for demonstration

# 1. Generate presigned URL for upload
@app.route("/presign-b2-upload", methods=["POST"])
def presign_b2_upload_route():
    try:
        user_id = get_authenticated_user_id(request)
        data = request.get_json()
        file_name = data.get("fileName")
        content_type = data.get("contentType")
        if not file_name or not content_type:
            raise ValueError("fileName and contentType required in JSON body")

        object_key = f"{uuid.uuid4()}-{file_name}"
        public_file_url = f"{B2_ENDPOINT_URL}/{B2_BUCKET_NAME}/{object_key}"

        presigned_url = s3_client.generate_presigned_url(
            "put_object",
            Params={
                "Bucket": B2_BUCKET_NAME,
                "Key": object_key,
                "ContentType": content_type
            },
            ExpiresIn=300,  # 5 minutes expiry
        )
        return jsonify(
            {
                "success": True,
                "presignedUrl": presigned_url,
                "objectKey": object_key,
                "publicFileUrl": public_file_url,
            }
        ), 200

    except (ClientError, ValueError) as e:
        print(f"Presign Error: {e}")
        return jsonify(
            {"success": False, "error": f"Failed to prepare upload: {e}"}
        ), 500
    except Exception as e:
        print(f"Unexpected Presign Error: {e}")
        return jsonify({"success": False, "error": "Server error"}), 500


# 2. Save metadata after client upload confirmation
@app.route("/save-b2-metadata", methods=["POST"])
def save_b2_metadata_route():
    conn = None
    cursor = None
    try:
        user_id = get_authenticated_user_id(request)
        data = request.get_json()
        object_key = data.get("objectKey")
        public_file_url = data.get("publicFileUrl")
        if not object_key or not public_file_url:
            raise ValueError("objectKey and publicFileUrl required in JSON body")

        conn = get_db_connection()
        cursor = conn.cursor()
        cursor.execute(
            """ INSERT INTO b2_files (object_key, file_url, user_id) VALUES (%s, %s, %s) """,
            (object_key, public_file_url, user_id),
        )
        conn.commit()
        print(f"Metadata saved for B2 object: {object_key}")
        return jsonify({"success": True}), 201
    except (psycopg2.Error, ValueError) as e:
        print(f"Metadata Save Error: {e}")
        return jsonify(
            {"success": False, "error": "Failed to save metadata"}
        ), 500
    except Exception as e:
        print(f"Unexpected Metadata Save Error: {e}")
        return jsonify({"success": False, "error": "Server error"}), 500
    finally:
        if cursor: cursor.close()
        if conn: conn.close()


if __name__ == "__main__":
    port = int(os.environ.get("PORT", 3000))
    app.run(host="0.0.0.0", port=port, debug=True)
```

**Explanation**

1. **Setup:** Initializes Flask, `boto3` S3 client configured for B2 (endpoint, region, credentials), and `psycopg2`.
2. **Authentication:** Placeholder `get_authenticated_user_id` needs replacing.
3. **Upload endpoints:**
   - **`/presign-b2-upload`:** Generates `object_key` and optional `public_file_url`. Uses `boto3`'s `generate_presigned_url` for `'put_object'` to get a temporary upload URL.
   - **`/save-b2-metadata`:** Called after client upload. Saves `object_key`, `public_file_url` (can be `None`), and `userId` to the `b2_files` table. Includes basic error handling for duplicates.
4. In production, use a global PostgreSQL connection pool.

## Testing the upload workflow

Testing the presigned URL flow involves multiple steps:

1. **Get presigned URL:** Send a `POST` request to your `/presign-b2-upload` endpoint with a JSON body containing `fileName` and `contentType`.
   **Using cURL:**

   ```bash
   curl -X POST http://localhost:3000/presign-b2-upload \
        -H "Content-Type: application/json" \
        -d '{"fileName": "test-b2.png", "contentType": "image/png"}'
   ```

   You should receive a JSON response with a `presignedUrl`, `objectKey`, and `publicFileUrl`:

   ```json
   {
     "success": true,
     "presignedUrl": "https://s3.<REGION>.backblazeb2.com/<BUCKET>/<OBJECT_KEY>?...",
     "objectKey": "<OBJECT_KEY>",
     "publicFileUrl": "https://s3.<REGION>.backblazeb2.com/<BUCKET>/<OBJECT_KEY>"
   }
   ```

   Note the `presignedUrl`, `objectKey`, and `publicFileUrl` from the response. You will use these in the next steps

2. **Upload file to B2:** Use the received `presignedUrl` to upload the actual file using an HTTP `PUT` request. The `Content-Type` header must match the one used to generate the URL.
   **Using cURL:**

   ```bash
   curl -X PUT "<PRESIGNED_URL>" \
        --upload-file /path/to/your/test-b2.png \
        -H "Content-Type: image/png"
   ```

   Replace `<PRESIGNED_URL>` with the actual URL from step 1. A successful upload typically returns HTTP `200 OK`.

3. **Save metadata:** Send a `POST` request to your `/save-b2-metadata` endpoint with the `objectKey` and optionally `publicFileUrl` from step 1.
   **Using cURL:**

   ```bash
   curl -X POST http://localhost:3000/save-b2-metadata \
        -H "Content-Type: application/json" \
        -d '{"objectKey": "<OBJECT_KEY>", "publicFileUrl": "<PUBLIC_URL>"}'
   ```

   You should receive a JSON response indicating success:

   ```json
   { "success": true }
   ```

**Expected outcome:**

- The file appears in your B2 bucket (check the Backblaze B2 web UI).
- A new row appears in your `b2_files` table in Neon.

## Accessing file metadata and files

Storing metadata in Neon allows your application to easily retrieve references to the files hosted on B2.

Query the `b2_files` table from your application's backend when needed.

**Example SQL query:**

Retrieve files for user 'user_123':

```sql
SELECT
    id,
    object_key,     -- Key (path/filename) in B2
    file_url,       -- Base public URL (only useful if bucket is Public)
    user_id,        -- User associated with the file
    upload_timestamp
FROM
    b2_files
WHERE
    user_id = 'user_123'; -- Use actual authenticated user ID
```

**Using the data:**

- The query returns metadata stored in Neon.
- **Accessing the file:**
  - If your bucket is **Public**, you can use the `file_url` directly in your application (for example, `<img>` tags, download links).
  - If your bucket is **Private**, the stored `file_url` is likely irrelevant. You **must** generate a **presigned download URL** (a GET URL) on demand using your backend. This involves a similar process to generating the upload URL but using `GetObjectCommand` (JS) or `generate_presigned_url('get_object', ...)` (Python) with read permissions. This provides secure, temporary read access.

This pattern effectively separates file storage and delivery concerns (handled by Backblaze B2) from structured metadata management (handled by Neon), leveraging the strengths of both services.

## Resources

- [Backblaze B2 Cloud Storage documentation](https://www.backblaze.com/docs/cloud-storage-developer-quick-start-guide)
- [Backblaze B2 S3 Compatible API](https://www.backblaze.com/docs/cloud-storage-s3-compatible-api)
- [Backblaze B2 Application Keys](https://www.backblaze.com/docs/cloud-storage-application-keys)
- [Neon documentation](https://neon.com/docs)

--- [Document source](https://neon.com/docs/guides/backup-restore.md) ---

> Summary: Neon's Backup & Restore feature combines instant point-in-time restore (PITR) and snapshots to recover a branch from accidental changes, schema issues, or data loss. Use it when you need to roll back a root branch to a specific timestamp or LSN, create manual snapshots before risky changes, or schedule automated daily, weekly, or monthly backups. Snapshot storage is billed at $0.09/GB-month. Scheduled snapshots do not count toward the manual snapshot limit.

# Backup & restore

Restore your branch from a point in time or snapshot

Last updated: 2026-09-11

**Note: Snapshots**

The **Snapshots** feature is available to all users. Manual snapshot limits: 1 on the Free plan and 100 on paid plans. On paid plans, snapshots created by backup schedules do not count toward this limit. Automated backup schedules are available on paid plans; on the Agent plan, they are available upon request. If you need higher limits, please reach out to [Neon support](https://neon.com/docs/introduction/support).

**Pricing:** Snapshot storage is billed at $0.09/GB-month.

Billing behavior: manual snapshots are charged as full snapshots. Scheduled snapshots are charged as full snapshots for the first scheduled snapshot, then as incremental (delta) storage for subsequent scheduled snapshots.

Use the **Backup & restore** page in the Neon Console to instantly restore a branch to a previous state or create and restore snapshots of your data. This feature combines **instant point-in-time restore** and **snapshots** to help you recover from accidental changes, data loss, or schema issues.

The **Enhanced view** toggle in the Neon Console lets you access the Backup & Restore page with snapshot capabilities. When enabled, you can create and manage snapshots alongside instant point-in-time restore. Toggle it off to return to the original Restore page if needed.

You can also manage snapshots from the terminal with the Neon CLI. For every subcommand, flag, and default, see the [snapshots](https://neon.com/docs/cli/snapshots) CLI reference.

![Backup and restore UI](https://neon.com/docs/guides/backup_restore_ui.png)

---

## What you can do

- ✅ Instantly restore a branch
- ✅ Preview data before restoring
- ✅ Create snapshots manually
- ✅ Schedule automated snapshots
- ✅ Restore from a snapshot

---

## Instantly restore a branch

Instantly restore your branch to a specific time in its history.

> Instant restore is only supported for root branches. Typically, this is your project's `production` branch. [Learn more](https://neon.com/docs/manage/branches#root-branch).

**Console**

You can restore from any time that falls within your project's [history window](https://neon.com/docs/postgres/backup-restore/history-window).

1. **Select a time**

   Click the date & time selector, choose a date & time, and click **Restore**.

   ![Backup and restore select a restore time](https://neon.com/docs/guides/backup_restore_select_time.png)

   You'll see a confirmation modal that outlines what will happen:

   - Your branch will be restored to its state at the selected date & time
   - Your current branch will be saved as a backup, in case you want to revert

   ![Backup and restore preview data](https://neon.com/docs/guides/backup_restore_preview_modal.png)

   At this point, you can either click **Restore** to proceed or select **Preview data** to inspect the data first.

2. **Preview the data**

   To preview the data to make sure you've selected the right restore point, you can:

   - **Browse data** in the **Tables** view to explore a read-only view of the data at the selected point in time
   - **Query data** directly from the restore page to run read-only SQL against the selected restore point
   - **Compare schemas** with the schema diff tool to see how your current schema differs from the one at the selected restore point

   ![Backup and restore preview data options](https://neon.com/docs/guides/backup_restore_preview_options.png)

3. **Restore**

   Click **Restore** to complete the restore operation, or **Cancel** to back out. You can also restore directly from any of the **Preview data** pages.

   When you restore, a backup branch is automatically created (named `<branch_name>_old_<timestamp>`) in case you need to revert back. You can find this branch on the **Branches** page.

   ![Backup branch on the Branches page](https://neon.com/docs/guides/backup_restore_backup_branch.png)

   For information about removing backup branches, see [Deleting backup branches](https://neon.com/docs/postgres/backup-restore/branch-restore#deleting-backup-branches).

**CLI**

To restore a branch to an earlier point in time, use the syntax `^self` in the `<source id|name>` field of the `branches restore` command. For example:

```bash
neon branches restore development ^self@2025-01-01T00:00:00Z --preserve-under-name development_old
```

This command resets the target branch `development` to its state at the start of 2025. The command also preserves the original state of the branch in a backup file called `development_old` using the `preserve-under-name` parameter (mandatory when resetting to self).

For full CLI documentation for `branches restore`, see [branches restore](https://neon.com/docs/cli/branches#restore).

**API**

To restore a branch using the API, use the endpoint:

```bash
POST /projects/{project_id}/branches/{branch_id_to_restore}/restore
```

This endpoint lets you restore a branch using the following request parameters:

| Parameter                 | Type     | Required | Description                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **source\_branch\_id**    | `string` | Yes      | The ID of the branch you want to restore from.<br/><br/>To restore to the latest data (head), omit `source_timestamp` and `source_lsn`.<br/><br/>To restore a branch to its own history (`source_branch_id` equals branch's own Id), you must include:<br/>- A time period: `source_timestamp` or `source_lsn`<br/>- A backup branch: `preserve_under_name`                           |
| **source\_lsn**           | `string` | No       | A Log Sequence Number (LSN) on the source branch. The branch will be restored with data up to this LSN.                                                                                                                                                                                                                                                                               |
| **source\_timestamp**     | `string` | No       | A timestamp indicating the point in time on the source branch to restore from. Use RFC 3339 format for the date-time string.                                                                                                                                                                                                                                                          |
| **preserve\_under\_name** | `string` | No       | If specified, a backup is created: the latest version of the branch's state is preserved under a new branch using the specified name.<br/><br/>**Note:** This field is required if:<br/>- The branch has children. All child branches will be moved to the newly created branch.<br/>- You are restoring a branch to its own history (`source_branch_id` equals the branch's own ID). |

#### Restoring a branch to its own history

In the following example, we are restoring branch `br-twilight-river-31791249` to an earlier point in time, `2024-02-27T00:00:00Z`, with a new backup branch named `backup-before-restore`. Note that the branch id in the `url` matches the value for `source_branch_id`.

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/floral-disk-86322740/branches/br-twilight-river-31791249/restore \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "source_branch_id": "br-twilight-river-31791249",
  "source_timestamp": "2024-02-27T00:00:00Z",
  "preserve_under_name": "backup-before-restore"
}
' | jq
```

## Create snapshots manually

Snapshots capture the state of your branch at a point in time. You can create snapshots manually (on root branches only). You can restore to these snapshots from any branch in your project.

**Console**

To create a snapshot manually, click **Create snapshot**. This captures the current state of your data and saves it as a **Manual snapshot**. It's a good idea to create a snapshot before making significant changes to your schema or data.

![Backup branch on the Branches page](https://neon.com/docs/guides/backup_restore_create_snapshot.png)

**CLI**

Use the [snapshots create](https://neon.com/docs/cli/snapshots#create) command to snapshot a branch. By default, it captures the head of the branch:

```bash
neon snapshots create --branch main --name pre-migration
```

To capture an earlier point within the branch's [history window](https://neon.com/docs/postgres/backup-restore/history-window), pass `--timestamp` or `--lsn`. The two options are mutually exclusive.

```bash
neon snapshots create --branch main --timestamp 2025-07-29T21:00:00Z
```

Use `--expires-at` to have the snapshot deleted automatically. It must be a future time. Omit it to keep the snapshot until you delete it.

```bash
neon snapshots create --branch main --name pre-upgrade --expires-at 2027-08-05T22:00:00Z
```

Both options use RFC 3339 format. Snapshot names must be unique within a project.

#### Update a snapshot's expiration

Use [snapshots update](https://neon.com/docs/cli/snapshots#update) to change a snapshot's expiration after it's created, or `--clear-expiration` to remove the expiration so it never expires:

```bash
neon snapshots update snap-1234 --expires-at 2027-12-31T00:00:00Z
```

```bash
neon snapshots update snap-1234 --clear-expiration
```

#### List and inspect snapshots

```bash
neon snapshots list
```

```bash
neon snapshots get snap-1234
```

For all subcommands and flags, see the [snapshots](https://neon.com/docs/cli/snapshots) CLI reference.

**API**

You can create a snapshot from a branch using the [Create snapshot](https://neon.com/docs/reference/api/snapshots/create-snapshot) endpoint. A snapshot can be created from a specific timestamp (RFC 3339 format) or LSN (for example 16/B3733C50) within the branch's [history window](https://neon.com/docs/postgres/backup-restore/history-window). The `timestamp` and `lsn` parameters are mutually exclusive; you can use one or the other, not both.

This endpoint takes its parameters in the query string. It has no request body, and a body you send is ignored without an error.

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/project_id/branches/branch_id/snapshot?name=my_snapshot&timestamp=2025-07-29T21:00:00Z&expires_at=2027-08-05T22:00:00Z" \
  -H 'authorization: Bearer $NEON_API_KEY' |jq
```

The parameters used in the example above:

- `timestamp`: A point in time to create the snapshot from (RFC 3339 format).
- `name`: A user-defined name for the snapshot.
- `expires_at`: The timestamp when the snapshot will be automatically deleted (RFC 3339 format). Omit it to keep the snapshot until you delete it. Manual snapshots have no maximum expiration.

#### Update a snapshot's expiration

You can change a snapshot's expiration after it is created using the [Update snapshot](https://neon.com/docs/reference/api/snapshots/update-snapshot) endpoint. Set `expires_at` to a future timestamp to extend or change the retention deadline, or send `null` to clear it so the snapshot never expires. Omit the field to leave the expiration unchanged.

```bash
curl -X PATCH "https://console.neon.tech/api/v2/projects/project_id/snapshots/snapshot_id" \
  -H "Content-Type: application/json" \
  -H 'authorization: Bearer $NEON_API_KEY' \
  -d '{
    "snapshot": {
      "expires_at": "2026-12-31T00:00:00Z"
    }
  }' |jq
```

### Snapshot size fields in API responses

Responses from the [Create snapshot](https://neon.com/docs/reference/api/snapshots/create-snapshot), [List project snapshots](https://neon.com/docs/reference/api/snapshots/list-snapshots), and [Update snapshot](https://neon.com/docs/reference/api/snapshots/update-snapshot) endpoints include a `snapshot` object that may contain optional **`full_size`** and **`diff_size`** (both **`int64`**, size in bytes).

#### Manual and scheduled snapshots

- **Manual** snapshots report **`full_size`**: the full logical size at the time of the snapshot.
- **Scheduled** snapshots: the **first** scheduled snapshot reports **`full_size`** (full logical size). **Subsequent** scheduled snapshots report **`diff_size`**, which is incremental storage since the **previous scheduled** snapshot, when the snapshot is billed on **incremental (diff)** usage.

#### The `full_size` field

Full logical size of the snapshot in bytes at the time it was taken. When the field is **absent**, the logical size has not been calculated yet and the snapshot is **not** being charged. When **present**, a value of **`0`** means the snapshot is **not** being charged.

#### The `diff_size` field

Incremental storage size in bytes since the **previous scheduled snapshot**, when the snapshot is billed on **incremental (diff)** usage. When **absent**, either the incremental size has not been calculated yet and the snapshot is **not** being charged, or the snapshot is charged at **full logical size** (in that case **`full_size`** is set).

Depending on billing mode and whether sizes have finished calculating, either field may be omitted. For parameter-level definitions, see each endpoint in the [Neon API Reference](https://neon.com/docs/reference/api).

**Related API references:**

- [Create snapshot](https://neon.com/docs/reference/api/snapshots/create-snapshot)
- [List project snapshots](https://neon.com/docs/reference/api/snapshots/list-snapshots)
- [Update snapshot](https://neon.com/docs/reference/api/snapshots/update-snapshot)
- [Delete snapshot](https://neon.com/docs/reference/api/snapshots/delete-snapshot)

## Create backup schedules

Schedule automated snapshots to run at regular intervals (daily, weekly, or monthly) to ensure consistent backups without manual intervention. Backup schedules are configured per branch and only apply to root branches.

**Console**

To create a backup schedule:

1. **Open the schedule editor**

   From the **Backup & restore** page, click **Edit schedule** to open the backup schedule configuration dialog.

   ![Edit schedule button on Backup & restore page](https://neon.com/docs/guides/edit_snapshot_schedule.png)

2. **Select a schedule frequency**

   Choose from the following options:

   - **No schedule**: Disables automated snapshots (default)
   - **Daily**: Creates a snapshot every day at a specified time
   - **Weekly**: Creates a snapshot on a specific day of the week
   - **Monthly**: Creates a snapshot on a specific day of the month

   ![Schedule frequency options dropdown](https://neon.com/docs/guides/snapshot_schedule_menu.png)

3. **Configure schedule details**

   Depending on your selected frequency, configure how often you want to create snapshots and how long to keep them.

Once configured, snapshots created by the backup schedule will appear on the **Backup & restore** page with a label indicating they were created automatically.

**CLI**

Use [snapshots schedule set](https://neon.com/docs/cli/snapshots#schedule-set) to set a branch's schedule. Pick a `--frequency`, then set the companion flags it requires:

| `--frequency` | Also required     | `--day` range       |
| ------------- | ----------------- | ------------------- |
| `daily`       | `--hour` (0-23)   | not used            |
| `weekly`      | `--day`, `--hour` | 1-7 (Monday-Sunday) |
| `monthly`     | `--day`, `--hour` | 1-31                |

Set a daily snapshot at 23:00 UTC, kept for 7 days:

```bash
neon snapshots schedule set --branch main --frequency daily --hour 23 --retention 604800
```

Set a weekly snapshot on Mondays at 04:00:

```bash
neon snapshots schedule set --branch main --frequency weekly --day 1 --hour 4
```

For a multi-entry schedule, pass JSON with `--schedule`, which overrides the single-entry flags:

```bash
neon snapshots schedule set --branch main --schedule '[{"frequency":"daily","hour":3},{"frequency":"weekly","day":1,"hour":4}]'
```

`--retention` is in seconds, from 3600 (1 hour) to 3024000 (35 days). See [Snapshot retention](https://neon.com/docs/guides/backup-restore#snapshot-retention) for what happens when you omit it.

To view the current schedule, use [snapshots schedule get](https://neon.com/docs/cli/snapshots#schedule-get):

```bash
neon snapshots schedule get --branch main
```

**API**

You can view and set backup schedules for branches using the Neon API. For complete API documentation, refer to the [Neon API Reference](https://neon.com/docs/reference/api).

**View backup schedule**

Retrieves the current backup schedule configuration for a branch using the [View backup schedule](https://neon.com/docs/reference/api/snapshots/get-snapshot-schedule) endpoint.

```bash
GET /projects/{project_id}/branches/{branch_id}/backup_schedule
```

```bash
curl 'https://console.neon.tech/api/v2/projects/<project_id>/branches/<branch_id>/backup_schedule' \
  -H 'Authorization: Bearer $NEON_API_KEY' | jq
```

**Example response:**

```json
{
  "schedule": [
    {
      "frequency": "daily",
      "hour": 23,
      "retention_seconds": 1209600
    }
  ]
}
```

**Set backup schedule**

Set the backup schedule for a branch using the [Update backup schedule](https://neon.com/docs/reference/api/snapshots/set-snapshot-schedule) endpoint.

```bash
PUT /projects/{project_id}/branches/{branch_id}/backup_schedule
```

The request body must include a `schedule` array. Each item in the array can specify:

- `frequency` (required): `daily`, `weekly`, or `monthly`
- `hour`: Hour of the day (0–23) to take the snapshot. Required for every frequency.
- `day`: Day of the week (1–7, Monday to Sunday) for `weekly`, or day of the month (1–31) for `monthly`. Required for those two frequencies, and setting it also requires `hour`.
- `retention_seconds` (optional): How long to keep each snapshot before it is automatically deleted, from 3600 (1 hour) to 3024000 (35 days). See [Snapshot retention](https://neon.com/docs/guides/backup-restore#snapshot-retention) for what happens when you omit it.

Although the schema marks `hour` and `day` optional, the server rejects a schedule that leaves out the values its frequency needs, with an error such as `daily schedules must specify the hour of the day`.

**Example: set a daily schedule**

```bash
curl -X PUT "https://console.neon.tech/api/v2/projects/<project_id>/branches/<branch_id>/backup_schedule" \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "schedule": [
      {
        "frequency": "daily",
        "hour": 23,
        "retention_seconds": 604800
      }
    ]
  }'
```

This example creates a daily snapshot at 23:00 (11:00 PM) UTC and keeps it for 7 days (604800 seconds).

### Snapshot retention

Manual and scheduled snapshots expire on different rules:

- **Scheduled snapshots** are kept for 35 days unless you set a shorter retention, and 35 days is also the maximum. The Console shows this per frequency as 35 days, 5 weeks, or 1 month.
- **Manual snapshots** never expire unless you give them an expiration, which has no maximum. Backup schedule retention settings do not apply to them.

While a branch has an active snapshot schedule, its most recent scheduled snapshot is preserved rather than deleted, even if it reaches its retention deadline, so a scheduled branch always keeps at least its latest scheduled snapshot. Older scheduled snapshots and manual snapshots follow the rules above. Turning off the schedule returns the latest snapshot to the standard expiry path.

You can adjust retention at any time by editing the schedule. Shorter retention periods help manage storage. On paid plans, the per-plan snapshot limit applies only to manual snapshots; scheduled backup snapshots do not count. Deleted snapshots cannot be recovered.

## Update backup schedules

Change an existing backup schedule or turn it off.

**Console**

From the **Backup & restore** page, click **Edit schedule** to open the **Edit backup schedule** modal. Change the frequency or schedule details, then click **Update schedule** to save.

**To turn off a snapshot schedule:** Select **No schedule** from the dropdown in the **Edit backup schedule** modal, then click **Update schedule**. No snapshots will be created until you set a schedule again.

![Edit backup schedule modal](https://neon.com/docs/guides/edit_backup_schedule_modal.png)

**CLI**

To change a schedule, run [snapshots schedule set](https://neon.com/docs/cli/snapshots#schedule-set) again with the new values. The command replaces the existing schedule rather than adding to it.

```bash
neon snapshots schedule set --branch main --frequency weekly --day 1 --hour 4
```

**To turn off a backup schedule:** pass an empty JSON array with `--schedule`:

```bash
neon snapshots schedule set --branch main --schedule '[]'
```

**API**

To update a backup schedule via API, use the same PUT endpoint and request format as for creating a schedule. See [Create backup schedules](https://neon.com/docs/guides/backup-restore#create-backup-schedules) for the endpoint, request body parameters, and example.

**To turn off a backup schedule:** Send a PUT request with an empty `schedule` array in the request body:

```bash
curl -X PUT "https://console.neon.tech/api/v2/projects/<project_id>/branches/<branch_id>/backup_schedule" \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "schedule": []
  }'
```

## Restore from a snapshot

You can restore from any snapshot in your project using one of two methods:

- **One-step restore** – Instantly restore data from the snapshot into the existing branch. The branch name and connection string remain the same, but the branch ID changes.
- **Multi-step restore** – Create a new branch from the snapshot. Use this option if you want to inspect or test the data before switching to the new branch.

### One-step restore

Use this option if you want to restore the snapshot data immediately without inspecting the data first.

**Console**

1. Locate the snapshot you want to use and click **Restore → One-step restore**.

   ![One step restore option](https://neon.com/docs/guides/one_step_restore.png)

2. The **One-step restore** modal explains the operation:

   - The restore operation will occur instantly.
   - The current branch will be restored to the snapshot state.
   - A branch named `<branch_name> (old)` will be created as a backup. Other snapshots you may have taken previously remain attached to this branch.

   ![One step restore confirmation modal](https://neon.com/docs/guides/one_step_restore_modal.png)

   Click **Restore** to proceed with the operation.

3. Your branch is immediately restored to the snapshot state, and the `<branch_name> (old)` branch is created, which you'll find on the **Branches** page in the Neon Console, as shown here:
   ![Branches page that shows the backup branch](https://neon.com/docs/guides/one_step_restore_branches_page.png)

   After you verify that the restore operation was successful, you can delete the backup branch if you no longer need it.

**CLI**

Use [snapshots restore](https://neon.com/docs/cli/snapshots#restore) with `--finalize` to restore and swap the branch in one step. This restores the snapshot to a new branch, moves your computes onto it, and replaces the target branch, so your connection details stay the same.

```bash
neon snapshots restore snap-1234 --target-branch main --finalize
```

Options:

- `--target-branch`: The branch to restore onto. Defaults to the snapshot's source branch. Recommended whenever you finalize, and especially if you apply several snapshots in succession, so the restore doesn't target a branch renamed by an earlier restore.
- `--name`: Name for the newly restored branch. Auto-generated when omitted.

Find the snapshot ID with `neon snapshots list`. The replaced branch is kept as a backup, renamed to `<branch_name> (old)`. If the branch being replaced was **protected**, that protection is **moved** to the branch with the restored data, not left on both branches.

**API**

A one-step restore operation is performed using the [Restore snapshot](https://neon.com/docs/reference/api/snapshots/restore-snapshot) endpoint. This operation creates a new branch, restores the snapshot to the new branch, and moves computes from your current branch to the new branch.

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/project_id/snapshots/snapshot_id/restore" \
  -H "Content-Type: application/json" \
  -H 'authorization: Bearer $NEON_API_KEY' \
  -d '{
    "name": "restored_branch",
    "target_branch_id": "br-twilight-river-31791249",
    "finalize_restore": true
  }' |jq
```

Parameters:

- `name`: (Optional) Name of the new branch with the restored snapshot data. If not provided, a default branch name will be generated. Pass this in the request body; the `name` query parameter is deprecated.
- `finalize_restore`: Set to `true` to finalize the restore immediately, which is what makes this a one-step restore. Finalizing the restore moves computes from your current branch to the new branch with the restored snapshot data for a seamless restore operation; no need to change the connection details in your application. If the branch being replaced was **protected**, that protection is **moved** to the branch with the restored data (it is not left on both branches). Set it to `false` for a [multi-step restore](https://neon.com/docs/guides/backup-restore#multi-step-restore) instead.
- `target_branch_id`: (Optional but recommended) The ID of the branch you want to replace when finalizing the restore. If omitted, subsequent snapshot restores may target the branch renamed to `<branch_name> (old)` from a previous restore, not your intended production branch.

**Note:** If you plan to apply multiple snapshots in succession, always supply `target_branch_id` to ensure the restore is finalized against the correct branch (typically your current production branch). Without it, a second snapshot may be applied to the previously renamed "(old)" branch.

**Related API references:**

- [Restore snapshot](https://neon.com/docs/reference/api/snapshots/restore-snapshot)
- [List project snapshots](https://neon.com/docs/reference/api/snapshots/list-snapshots)

### Multi-step restore

Use this option if you need to inspect the restored data before you switch over to the new branch.

**Console**

1. Locate the snapshot you want to use and click **Restore → Multi-step restore**.
   ![Multi-step restore option](https://neon.com/docs/guides/multi_step_restore.png)

2. The **Multi-step restore** modal explains the operation:

   - The restore will occur instantly
   - Your current branch will remain unchanged
   - A new branch with the snapshot data will be created

   ![Multi-step restore confirmation modal](https://neon.com/docs/guides/multi_step_restore_modal.png)

3. Clicking **Restore** creates the new branch with the restored data and directs you to the **Branch overview** page where you can:

   - **Get connection details** for the new branch to preview the data restored from the snapshot
   - **Migrate connections and settings** to move your database URLs and compute settings from the old branch to the new branch so you don't have to update the connection configuration in your application

   ![Branch overview page](https://neon.com/docs/guides/branch_overview_page.png)

**CLI**

1. **Restore the snapshot to a new branch**

   Run [snapshots restore](https://neon.com/docs/cli/snapshots#restore) without `--finalize`, which leaves the restore un-finalized so you can inspect the new branch first:

   ```bash
   neon snapshots restore snap-1234 --target-branch main --name my_restored_branch
   ```

   Options:

   - `--name`: (Optional) Name for the newly restored branch. Auto-generated when omitted.
   - `--target-branch`: (Optional but recommended) The branch you intend to replace when you later finalize (typically your production branch). Providing this avoids finalizing against the `<branch_name> (old)` branch created by an earlier restore.

   Find the snapshot ID with `neon snapshots list`. The command prints the ID of the restored branch along with the exact `finalize` command to run.

2. **Inspect the new branch**

   Connect to the restored branch and query it to confirm the data is what you expect:

   ```bash
   neon connection-string my_restored_branch
   ```

3. **Finalize the restore**

   Pass the restored branch, not the target branch, to [snapshots finalize](https://neon.com/docs/cli/snapshots#finalize):

   ```bash
   neon snapshots finalize br-twilight-river-31791249
   ```

   This performs the same actions as the API's finalize step: it moves the original branch's computes to the restored branch, renames the restored branch to the original's name, and renames the original to `<branch_name> (old)`. Any backup schedule moves to the restored branch, and if the original was **protected**, that protection is **moved** rather than left on both branches. Use `--name` to choose the replaced branch's name instead of the generated one.

**API**

1. **Restore the snapshot to a new branch**

   The first step in a multi-step restore operation is to restore the snapshot to a new branch using the [Restore snapshot](https://neon.com/docs/reference/api/snapshots/restore-snapshot) endpoint:

   ```bash
   curl -X POST "https://console.neon.tech/api/v2/projects/project_id/snapshots/snapshot_id/restore" \
   -H "Content-Type: application/json" \
   -H 'authorization: Bearer $NEON_API_KEY' \
   -d '{
      "name": "my_restored_branch",
      "finalize_restore": false
   }' |jq
   ```

   Parameters:

   - `name`: (Optional) Name of the new branch with the restored snapshot data. If not provided, a default branch name will be generated.
   - `finalize_restore`: Set to `false` so that you can inspect the new branch before finalizing the restore operation.
   - `target_branch_id`: (Optional but recommended) Specify the branch ID you intend to replace when you later finalize the restore (typically your production branch). Providing this avoids subsequent operations defaulting to the `<branch_name> (old)` branch created by an earlier restore.

     **Note:**

     You can find the `snapshot_id` using the [List project snapshots](https://neon.com/docs/reference/api/snapshots/list-snapshots) endpoint.

     ```bash
     curl -X GET "https://console.neon.tech/api/v2/projects/project_id/snapshots" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $NEON_API_KEY" |jq
     ```

     **Note:** If you will finalize the restore later or plan multiple restores, include `target_branch_id` during the restore call to anchor the operation to the correct target branch.

2. **Inspect the new branch**

   After restoring the snapshot, you can connect to the new branch and run queries to inspect the data. You can get the branch connection string from the Neon Console or using the [Retrieve connection URI](https://neon.com/docs/reference/api/projects/get-connection-uri) endpoint.

   ```bash
   curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/project_id/connection_uri?branch_id=branch_id&database_name=db_name&role_name=role_name&pooled=true' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' |jq
   ```

3. **Finalize the restore**

   If you're satisfied with the data on the new branch, finalize the restore operation using the [Finalize restore](https://neon.com/docs/reference/api/branches/finalize-restore-branch) endpoint. This step performs the following actions:

   - Moves your original branch's computes to the new branch and restarts the computes.
   - Renames the new branch to original branch's name.
   - Renames the original branch to `<branch_name> (old)`. Other snapshots you may have taken remain attached to this branch.
   - Moves any backup schedule from the original branch to the branch that now has the restored data, so scheduled snapshots continue on the active branch after finalize.
   - If the original branch was **protected**, that protection is **moved** to the branch that ends up with your restored data (the renamed branch that keeps your connection string). The previous branch is no longer protected, so your [protected branch](https://neon.com/docs/guides/protected-branches) count stays correct.

   ```bash
   curl -X POST "https://console.neon.tech/api/v2/projects/project_id/branches/branch_id/finalize_restore" \
   -H "Content-Type: application/json" \
   -H 'authorization: Bearer $NEON_API_KEY' |jq
   ```

   Parameters:

   - `project_id`: The Neon project ID.
   - `branch_id`: The branch ID of the branch created by the snapshot restore operation.

## Limitations

- Instant restore (PITR) is currently not supported on branches created from a snapshot restore. If you restore a snapshot to create a new branch, you cannot perform point-in-time restore on that branch at this time. Attempting to do so will return an error: `restore from snapshot on target branch is still ongoing`.
- **Reset from parent is unavailable on child branches for up to 24 hours after restoring a parent from a snapshot.** When you restore a branch from a snapshot, any child branches of that restored branch cannot use the [Reset from parent](https://neon.com/docs/guides/reset-from-parent) feature for up to 24 hours.

--- [Document source](https://neon.com/docs/guides/benchmarking-latency.md) ---

> Summary: Benchmarking latency in Neon's serverless Postgres requires separating cold queries (compute wakes from suspension) from hot queries (active instance), because standard benchmarking tools conflate the two and produce misleading results. Free-tier databases auto-suspend after 5 minutes of inactivity; paid plan users can disable auto-suspend to eliminate cold starts. HTTP and WebSocket connections have distinct latency profiles, and Neon provides an open-source regional latency dashboard for comparing connection methods across AWS regions.

# Benchmarking latency in Neon's serverless Postgres

Techniques for obtaining meaningful latency data in serverless database environments

Last updated: 2026-11-04

Benchmarking database query latency is inherently complex, requiring careful consideration of numerous variables and testing methodologies. Neon's serverless Postgres environment adds additional layers to this complexity due to compute auto-suspension, connection protocol differences, and geographic distribution. This guide provides detailed methodologies for separating cold-start costs from operational latency, selecting optimal connection types, and designing tests that accurately reflect production conditions.

## Understanding cold vs. hot queries

When benchmarking Neon databases, you'll encounter two distinct types of queries:

- **Cold queries**: Occur when a previously suspended compute resource is activated to process a request. This activation typically adds a few hundred milliseconds of latency. Cold queries are common in development or test environments where databases aren't running continuously.

- **Hot queries**: Execute on an already-active database instance, delivering consistent low latency. These represent typical performance in production environments where databases run continuously or remain active most of the time.

Free-tier Neon databases automatically suspend after 5 minutes of inactivity. Paid plans allow you to disable the auto-suspend timeout to eliminate cold starts entirely. The Neon [Scale plan](https://neon.com/docs/introduction/plans) lets you disable or configure the setting, enabling you to customize your testing approach. See [Compute Lifecycle](https://neon.com/docs/introduction/compute-lifecycle) and [Auto-suspend Configuration](https://neon.com/docs/introduction/scale-to-zero) for more details.

## Benchmarking methodology

For accurate benchmarking, always measure cold and hot queries separately:

1. **Cold query testing**:
   - Ensure your database is in a suspended state
   - Make a request to trigger compute activation
   - Measure this connection time, which includes the startup overhead

2. **Hot query testing**:
   - After triggering compute activation with a cold query
   - Make subsequent requests within the active window
   - Measure these connection times, which reflect normal operation

This methodology isolates the cold start overhead from normal operating performance, giving you a clearer picture of both typical performance and worst-case latency.

## Testing environment considerations

Before running benchmarks, determine exactly what kind of latency you want to measure:

- **Server-to-database latency**: If you're testing how quickly your application server can communicate with Neon, run benchmarks from the same location as your server. This is typically the most relevant metric for API performance.

- **Client-to-database latency**: If you're testing direct client connections (rare in production), benchmark from client locations.

Once you've determined what you're measuring:

- **Test from your production region**: Geographic proximity is the primary factor in connection latency. Run benchmarks from the same region as your production environment to get accurate results. If your Neon database is in `us-east-1`, execute benchmarks from a server in that AWS region.

- **Avoid localhost testing**: Testing from your local workstation doesn't reflect real-world conditions. In production, databases are typically queried from deployed servers, not client machines.

Avoid testing across unrealistic distances that don't represent your production setup, as this introduces network overhead your users won't experience. For more on geographic factors affecting latency, see [Connection Latency and Timeouts](https://neon.com/docs/connect/connection-latency).

## Connection types and their impact

[Neon's serverless driver](https://neon.com/docs/serverless/serverless-driver) supports two connection protocols: HTTP and WebSocket, each with distinctly different performance profiles. While some modern edge platforms now support direct TCP connections, many serverless environments still have limitations around persistent connections or TCP support. Neon's HTTP and WebSocket methods work across all serverless platforms, with each protocol having different latency characteristics and feature trade-offs depending on your query patterns. Understanding these differences is crucial for accurate benchmarking. For a comprehensive comparison, see [Choosing Connection Types](https://neon.com/docs/connect/choose-connection).

### HTTP connections

- **Performance profile**: Optimized for queries with minimal connection overhead
- **Use cases**:
  - Serverless functions that need low-latency query execution
  - Applications running multiple queries in parallel (HTTP can outperform WebSockets for parallel execution)
  - Scenarios where queries don't depend on each other
- **Limitations**: Doesn't support sessions, interactive transactions, NOTIFY, or COPY protocol
- **When to benchmark**: Use for measuring performance of stateless query operations, both individual and parallel
- **Optimization**: Connection caching can further reduce latency

### WebSocket connections

- **Performance profile**: Higher initial connection overhead but significantly faster for subsequent queries
- **Use cases**: Optimal for applications that execute multiple queries over a maintained connection
- **Features**: Supports full Postgres functionality including sessions, transactions, and all Postgres protocols
- **When to benchmark**: Measure both connection establishment time and subsequent query execution separately
- **Initialization**: Requires multiple round-trips between client and server to establish

### Benchmarking different connection types

When comparing HTTP vs WebSocket connections, you'll typically observe different latency patterns:

- **HTTP connections**: Show consistent low latency for individual queries and excel at parallel query execution
- **WebSocket connections**: Show higher initial connection latency (about 3-5x slower than HTTP) but very low latency for subsequent sequential queries

Consider your query patterns when choosing a connection type:

- For parallel queries or independent operations, HTTP often performs better
- For sequential queries where each depends on the previous result, WebSockets can be more efficient after the initial connection
- The break-even point typically occurs around 2-3 sequential queries, though this varies by region and workload

The runtime environment (Edge vs traditional serverless) can also impact connection performance characteristics.

**Testing approach:**

- For WebSockets: Establish the connection first, then measure query execution time separately. This reflects real-world usage where connections are reused.

- For HTTP: Measure individual query execution time including any per-query connection overhead.

For implementation details on both connection methods, refer to the [Serverless Driver Documentation](https://neon.com/docs/serverless/serverless-driver).

## Real-world usage pattern simulation

Design your benchmarks to simulate how your application actually interacts with Neon:

- **Use persistent connections**: For web servers or long-running applications, initialize the database connection before measuring query timings. Run a series of queries on this persistent connection. If your production environment uses connection pooling (which reuses database connections across requests), ensure your benchmarks account for this - pooled connections significantly reduce connection overhead after initial pool creation. See [Connection Pooling](https://neon.com/docs/connect/connection-pooling) for implementation details.

- **Avoid one-query-per-process testing**: While useful for understanding cold starts, simplistic tests that connect, query, and disconnect don't reflect long-running application performance.

- **Match your application pattern**:
  - If your app keeps connections alive, focus on post-connection query latency
  - If your app is serverless and frequently creates new connections, measure both scenarios but analyze them separately

For examples of different connection patterns and their implementation, see [Connection Examples](https://neon.com/docs/connect/choose-connection).

## Neon latency benchmarks dashboard

Neon provides a [Latency Benchmarks Dashboard](https://neon.com/demos/regional-latency) that measures latency between serverless functions and Neon databases across different regions.

![Screenshot of Neon's latency benchmarks dashboard showing regional performance metrics](https://neon.com/docs/guides/latency_benchmark.png)

The benchmark specifically tracks:

- Roundtrip time for executing simple SELECT queries
- Network latency between function and database regions
- Database connection establishment time
- Performance differences between HTTP and WebSocket connections
- Cold vs hot query performance

This data helps you understand expected latencies based on your specific region and connection method. The dashboard is open source and [available on GitHub](https://github.com/neondatabase-labs/latency-benchmarks).

If you encounter unexpected results during your benchmarking, consult the [Connection Troubleshooting](https://neon.com/docs/connect/connect-intro#troubleshoot-connection-issues) documentation to identify potential issues.

## Conclusion

Benchmarking Neon requires understanding the unique characteristics of serverless Postgres. By separating cold and hot query measurements, testing from appropriate locations, and selecting the right connection methods, you'll obtain accurate performance metrics that reflect what your applications will experience in production.

For further information on connection latency, see the [Neon Documentation](https://neon.com/docs/connect/connection-latency).

--- [Document source](https://neon.com/docs/guides/better-drizzle.md) ---

> Summary: Better Drizzle connection guide for Lakebase Postgres walks through setting up better-drizzle 0.3 with Drizzle ORM 1.0 and the node-postgres driver. Learn how to configure a Better Drizzle client, define relations with defineRelations, seed data, run CRUD queries, use plugins, and manage transactions with savepoints.

# Connect from Better Drizzle to Neon

Learn how to connect to Neon from Better Drizzle

Last updated: 2026-10-08

**What you will learn:**

- How to set up better-drizzle with Lakebase Postgres
- How to define schemas, seed, and query your database
- How to use plugins, hooks, and transactions in better-drizzle

**Related resources**

- [better-drizzle documentation](https://better-drizzle.com/docs)
- [better-drizzle GitHub](https://github.com/almeidazs/better-drizzle)
- [Neon Drizzle setup guide](https://neon.com/docs/guides/drizzle)

[better-drizzle](https://better-drizzle.com) is a thin wrapper around [Drizzle ORM](https://orm.drizzle.team) that gives every table a consistent, type-safe API without replacing Drizzle itself. If you are already using Drizzle with Lakebase Postgres, better-drizzle removes the repetitive query glue you would otherwise rewrite in every service while staying close to the metal.

better-drizzle is **sponsored by Neon**, and is maintained by [Hiago Almeida](https://github.com/almeidazs).

## What better-drizzle adds

better-drizzle wraps your existing Drizzle client and generates one delegate per table. You get:

- **Consistent CRUD**: `findMany`, `findFirst`, `findUnique`, `create`, `update`, `delete`, `upsert`, and `upsertMany` on every table
- **Typed relation loading**: `include` and `select` with full type inference from your Drizzle schema
- **Nested relation filters**: `some`, `every`, `none`, and `is` for filtering by related rows
- **Pagination with metadata**: Offset (`paginate`) and cursor (`cursor`) pagination, both returning `{ data, pagination }`
- **Lifecycle hooks**: Cross-cutting concerns like audit trails, tracing, and metrics without sprinkling them through every call
- **First-class plugins**: Timestamps, soft delete, and custom behavior packaged as reusable plugins
- **Transactions with savepoints**: Nested transactions, rollback, `afterCommit` callbacks, and automatic retries

All of this compiles down to Drizzle queries. You still define your schema in Drizzle, choose your driver, and drop to raw SQL whenever you need to.

To connect a TypeScript/Node.js project to Lakebase Postgres using better-drizzle, follow these steps:

## Create a TypeScript/Node.js project

Create a new directory for your project and navigate into it:

```bash
mkdir better-drizzle-demo
cd better-drizzle-demo
```

Initialize a new Node.js project with a `package.json` file:

```bash
npm init -y
```

## Create a project on Neon

If you do not have one already, create a project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Get your connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select a branch, a user, and the database you want to connect to. A connection string is constructed for you.
![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)
The connection string includes the user name, password, hostname, and database name.

Create a `.env` file in your project's root directory. Add the pooled connection string (the hostname includes `-pooler`) as `DATABASE_URL` for your application, and the direct connection string (without `-pooler`) as `DATABASE_URL_UNPOOLED` for Drizzle Kit migrations. To get the direct string, turn off **Connection pooling** in the **Connect to your branch** modal, or remove `-pooler` from the hostname. Your `.env` file should look like this:

```text
DATABASE_URL="postgresql://[user]:[password]@[endpoint]-pooler.[region].aws.neon.tech/[dbname]?sslmode=verify-full&channel_binding=require"
DATABASE_URL_UNPOOLED="postgresql://[user]:[password]@[endpoint].[region].aws.neon.tech/[dbname]?sslmode=verify-full&channel_binding=require"
```

The Console's connection string uses `sslmode=require`. `pg` 8.23 and later print a `SECURITY WARNING` for `sslmode=require`, so change it to `sslmode=verify-full`, which keeps the same behavior without the warning.

**Note:** A pooled connection string routes through a PgBouncer connection pool, which suits your application at runtime. Running migrations through the pooler can lead to errors, so Drizzle Kit uses the direct connection. For more information, see [Connection pooling](https://neon.com/docs/connect/connection-pooling) and [Schema migration with Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations).

## Install dependencies

Install the dependencies:

```bash
npm install better-drizzle drizzle-orm@1.0.0-rc.4 pg dotenv
npm install -D drizzle-kit@1.0.0-rc.4 tsx @types/pg @types/node
```

**Note: Drizzle ORM version**

better-drizzle 0.3 supports only Drizzle ORM `1.0.0-rc.4` and its `defineRelations` API. Install `drizzle-orm` and `drizzle-kit` with that exact version: a plain `npm install drizzle-orm` resolves to 0.x, and later release candidates aren't supported yet. Projects on Drizzle ORM 0.x need better-drizzle 0.2.x. See [Upgrading](https://better-drizzle.com/docs/guides/upgrading) in the better-drizzle docs.

## Configure Drizzle Kit

Drizzle Kit uses a configuration file to manage schema and migrations. Create a `drizzle.config.ts` file in your project root. It uses the direct connection string, since migrations shouldn't run through the connection pooler:

```typescript filename="drizzle.config.ts"
import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';

if (!process.env.DATABASE_URL_UNPOOLED) {
  throw new Error('DATABASE_URL_UNPOOLED is not set in the .env file');
}

export default defineConfig({
  schema: './src/schema.ts',
  out: './drizzle',
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL_UNPOOLED,
  },
});
```

## Define your schema and relations

better-drizzle reads your Drizzle tables and relations to generate each table's typed API. The relations you define power `include`, `select`, and nested relation filters.

Create a `src/schema.ts` file with two tables: `users` and `posts`.

```typescript filename="src/schema.ts"
import { boolean, integer, pgTable, serial, text } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
  active: boolean('active').notNull().default(true),
});

export const posts = pgTable('posts', {
  id: serial('id').primaryKey(),
  authorId: integer('author_id')
    .notNull()
    .references(() => users.id),
  title: text('title').notNull(),
  published: boolean('published').notNull().default(false),
});
```

Declare the relations with Drizzle's `defineRelations` in a `src/relations.ts` file. Each user can have many posts, and each post belongs to one user.

```typescript filename="src/relations.ts"
import { defineRelations } from 'drizzle-orm';
import * as schema from './schema';

export const relations = defineRelations(schema, (r) => ({
  users: {
    posts: r.many.posts(),
  },
  posts: {
    author: r.one.users({
      from: r.posts.authorId,
      to: r.users.id,
    }),
  },
}));
```

## Initialize the Better Drizzle client

Create a Drizzle client with your relations and wrap it with `better()` to get the Better client. `better()` reads the tables and relations from the Drizzle instance. Create a `src/db.ts` file:

```typescript filename="src/db.ts"
import 'dotenv/config';
import { better } from 'better-drizzle';
import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';
import { relations } from './relations';

export const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
const db = drizzle({ client: pool, relations });

export const client = better(db);
```

## Generate migrations

Generate your migration files using Drizzle Kit:

```bash
npx drizzle-kit generate
```

## Apply migrations

Apply the generated SQL migrations to your Neon database:

```bash
npx drizzle-kit migrate
```

## Seed the database

Create a `src/seed.ts` file to populate the database with some users and posts:

```typescript filename="src/seed.ts"
import { client, pool } from './db';

async function seed() {
  await client.users.upsertMany({
    data: [
      { email: 'alice@example.com', name: 'Alice', active: true },
      { email: 'bob@example.com', name: 'Bob', active: false },
      { email: 'charlie@example.com', name: 'Charlie', active: true },
    ],
    target: ['email'],
    update: ['name'],
  });

  const alice = await client.users.findUnique({
    where: { email: 'alice@example.com' },
  });

  const bob = await client.users.findUnique({
    where: { email: 'bob@example.com' },
  });

  await client.posts.createMany({
    data: [
      { authorId: alice!.id, title: 'Hello World', published: true },
      { authorId: alice!.id, title: 'better-drizzle is great', published: true },
      { authorId: alice!.id, title: 'Branching with Neon', published: true },
      { authorId: bob!.id, title: 'Secret draft', published: false },
    ],
  });

  console.log('Seeded 3 users and 4 posts.');
}

seed()
  .catch((error) => {
    console.error(error);
    process.exitCode = 1;
  })
  .finally(() => pool.end());
```

Run the seed script once:

```bash
npx tsx src/seed.ts
```

The script upserts users but inserts posts with `createMany`, so running it again adds duplicate posts and changes the query output shown below.

## Query with better-drizzle

### Reads with typed relations

Each table gets a delegate (`client.users`, `client.posts`) with methods that are fully typed against your schema. To try the examples in this section, put them in an `async` function in a file such as `src/queries.ts` that imports `client` and `pool` from `./db`, call `pool.end()` when you're done, and run it with `npx tsx src/queries.ts`.

List active users with their three most recent published posts:

```typescript
const users = await client.users.findMany({
  where: { active: true },
  include: {
    posts: {
      where: { published: true },
      select: { id: true, title: true },
      orderBy: [{ id: 'desc' }],
      take: 3,
    },
  },
  orderBy: [{ id: 'desc' }],
  take: 20,
});
```

The query returns active users with their published posts nested under each user:

```json title="Output"
[
  {
    "id": 3,
    "email": "charlie@example.com",
    "name": "Charlie",
    "active": true,
    "posts": []
  },
  {
    "id": 1,
    "email": "alice@example.com",
    "name": "Alice",
    "active": true,
    "posts": [
      { "id": 3, "title": "Branching with Neon" },
      { "id": 2, "title": "better-drizzle is great" },
      { "id": 1, "title": "Hello World" }
    ]
  }
]
```

**Note: select vs include**

By default, queries return all table columns.

- Use **`include`** to return all columns _plus_ nested relations (e.g., `include: { posts: true }`).
- Use **`select`** to return _only_ the specified columns and drop everything else (e.g., `select: { id: true, title: true }`).

`select` and `include` are mutually exclusive at the same query level, but you can nest a `select` inside an `include` to narrow the fields of a related table (as shown in the active users query above).

Find a single user by a unique field:

```typescript
const alice = await client.users.findUnique({
  where: { email: 'alice@example.com' },
});
```

Filter posts by conditions on their related author with nested relation filters:

```typescript
const posts = await client.posts.findMany({
  where: {
    published: true,
    author: { is: { active: true } },
  },
  select: {
    id: true,
    title: true,
    author: { select: { id: true, name: true } },
  },
  orderBy: [{ id: 'desc' }],
  take: 20,
});
```

The `author: { is: { active: true } }` filter keeps only posts where the author is active, so Bob's draft is excluded.

### Writes with skipDuplicates and upsertMany

Create a new user, or skip the insert if the email already exists. `create` returns `null` when it skips:

```typescript
const maybeCreated = await client.users.create({
  data: {
    email: 'better@example.com',
    name: 'better',
    active: true,
  },
  skipDuplicates: ['email'],
});

if (!maybeCreated) {
  console.log('User already existed');
}
```

Bulk upsert multiple users in a single batch operation:

```typescript
await client.users.upsertMany({
  data: [
    { email: 'alice@example.com', name: 'Alice Updated', active: true },
    { email: 'bob@example.com', name: 'Bob Updated', active: true },
  ],
  target: ['email'],
  update: ['name', 'active'],
  select: { id: true, name: true },
});
```

### Pagination

Use `paginate` for offset pagination:

```typescript
const page = await client.users.paginate({
  where: { active: true },
  select: { id: true, name: true },
  orderBy: [{ id: 'desc' }],
  skip: 0,
  limit: 10,
});
```

The result includes the rows and the page metadata. With only the seed data loaded (before the write examples above), it looks like this:

```json filename="Output"
{
  "data": [
    { "id": 3, "name": "Charlie" },
    { "id": 1, "name": "Alice" }
  ],
  "pagination": {
    "type": "offset",
    "page": 1,
    "perPage": 10,
    "total": 2,
    "pageCount": 1,
    "hasNext": false,
    "hasPrevious": false
  }
}
```

Use `cursor` for feed-style pagination. Pass the previous page's `nextCursor` as `after` to fetch the next page:

```typescript
const first = await client.users.cursor({
  where: { active: true },
  select: { id: true, name: true },
  orderBy: [{ id: 'desc' }],
  limit: 1,
});

const second = await client.users.cursor({
  where: { active: true },
  select: { id: true, name: true },
  orderBy: [{ id: 'desc' }],
  limit: 1,
  after: first.pagination.nextCursor ?? undefined,
});
```

Cursor results return `hasNext`, `hasPrevious`, `nextCursor`, and `previousCursor` in `pagination`. With only the seed data loaded, `first.pagination` is `{ "type": "cursor", "hasNext": true, "hasPrevious": false, "nextCursor": { "id": 3 }, "previousCursor": null }`.

### Count and exists

```typescript
const activeCount = await client.users.count({
  where: { active: true },
});

const exists = await client.users.exists({
  where: { id: 1 },
});
```

## Use plugins for cross-cutting behavior

Plugins can manage timestamps, soft deletes, and custom behavior. The timestamps and soft delete plugins ship with `better-drizzle`, so there's nothing extra to install.

### Timestamps

Auto-manage `createdAt` and `updatedAt` columns on every write. In `src/db.ts`, import the plugin and pass it to `better()`:

```typescript filename="src/db.ts"
import { timestamps } from 'better-drizzle/timestamps';

export const client = better(db, {
  plugins: [
    timestamps({
      createdAt: 'createdAt',
      updatedAt: 'updatedAt',
    }),
  ],
});
```

**Important: Timestamps plugin**

Use the property names defined in your Drizzle schema, not the Postgres column names. For example, if your schema defines `createdAt: timestamp('created_at')`, reference `createdAt` in the plugin configuration, not `created_at`.

The plugin sets `createdAt` and `updatedAt` when a row is created and updates `updatedAt` on every update. Add `createdAt` and `updatedAt` timestamp columns to your schema, then run `npx drizzle-kit generate` and `npx drizzle-kit migrate` again:

```typescript filename="src/schema.ts"
import { boolean, integer, pgTable, serial, text, timestamp } from 'drizzle-orm/pg-core';

export const users = pgTable('users', {
  id: serial('id').primaryKey(),
  email: text('email').notNull().unique(),
  name: text('name').notNull(),
  active: boolean('active').notNull().default(true),
  createdAt: timestamp('created_at'),
  updatedAt: timestamp('updated_at'),
});

export const posts = pgTable('posts', {
  id: serial('id').primaryKey(),
  authorId: integer('author_id')
    .notNull()
    .references(() => users.id),
  title: text('title').notNull(),
  published: boolean('published').notNull().default(false),
  createdAt: timestamp('created_at'),
  updatedAt: timestamp('updated_at'),
});
```

### Soft delete

To use soft deletes, add a `deletedAt` column to your schema, then generate and apply a migration:

```typescript filename="src/schema.ts"
export const posts = pgTable('posts', {
  id: serial('id').primaryKey(),
  authorId: integer('author_id')
    .notNull()
    .references(() => users.id),
  title: text('title').notNull(),
  published: boolean('published').notNull().default(false),
  deletedAt: timestamp('deleted_at'),
});
```

In `src/db.ts`, import the soft delete plugin and pass it to `better()`:

```typescript filename="src/db.ts"
import { softDelete } from 'better-drizzle/soft-delete';

export const client = better(db, {
  plugins: [
    softDelete({
      column: 'deletedAt',
      defaults: { mode: 'soft', visibility: 'without' },
    }),
  ],
});

// Soft-deletes the row instead of removing it
await client.posts.delete({ where: { id: 1 } });

// Get only deleted posts
await client.posts.findMany({ deleted: 'only' });

// Restore a soft-deleted row
await client.posts.restore({ where: { id: 1 } });
```

## Add lifecycle hooks

Observe operations for auditing, metrics, or custom metadata. Pass `hooks` to `better()` in `src/db.ts`:

```typescript filename="src/db.ts"
export const client = better(db, {
  hooks: {
    beforeCreate(ctx) {
      console.log('beforeCreate', ctx.action, ctx.table);
    },
    afterCreate(ctx) {
      console.log('afterCreate', ctx.row);
    },
    beforeQuery(ctx) {
      console.log('beforeQuery', ctx.action, ctx.args.where);
    },
    afterQuery(ctx) {
      console.log('afterQuery', ctx.action, ctx.result);
    },
  },
});
```

The example above shows create and query hooks, but Better Drizzle also supports `beforeUpdate` / `afterUpdate`, `beforeDelete` / `afterDelete`, transaction hooks (`beforeTransaction`, `afterTransactionCommit`, `afterTransactionRollback`, `onTransactionError`), raw SQL hooks (`beforeRaw`, `afterRaw`, `onRawError`), and a catch-all `onError`. See the [hooks docs](https://better-drizzle.com/docs/advanced/hooks) for details.

Hook callbacks receive `ctx.meta`, ideal for logging request IDs, tenant IDs, or user context in a server environment.

## Transactions with savepoints

Transactions run on the client, with the callback receiving a Better client bound to the transaction context:

```typescript
const user = await client.transaction(async (tx) => {
  const created = await tx.users.create({
    data: { email: 'new@example.com', name: 'New User', active: true },
  });

  await tx.posts.create({
    data: { authorId: created.id, title: 'Hello World', published: true },
  });

  tx.afterCommit(() => {
    console.log('Committed user', created.email);
  });

  return created;
});
```

Nested transactions use **savepoints** that roll back independently of the outer transaction:

```typescript
await client.transaction(async (tx) => {
  await tx.users.create({
    data: { email: 'a@test.com', name: 'Alice', active: true },
  });

  try {
    await tx.transaction(async (nested) => {
      await nested.users.create({
        data: { email: 'b@test.com', name: 'Bob', active: true },
      });
      nested.rollback('duplicate email, rolling back nested savepoint');
    });
  } catch {
    // Only the nested savepoint was rolled back
  }

  await tx.users.create({
    data: { email: 'c@test.com', name: 'Charlie', active: true },
  });
});
```

### Automatic retries

Opt into transaction retries for transient failures like deadlocks:

```typescript
await client.transaction(
  async (tx) => {
    await tx.users.create({
      data: { email: 'retry@example.com', name: 'Retry', active: true },
    });
  },
  {
    retries: {
      attempts: 3,
      on: ['deadlock', 'serializationFailure'],
      delayMs: (attempt) => attempt * 25,
    },
  },
);
```

## Other features

To explore more advanced capabilities of better-drizzle, refer to the following topics in the official documentation:

- **Querying & Reads**: [Reads & Filters](https://better-drizzle.com/docs/querying/filters), [Selecting fields](https://better-drizzle.com/docs/querying/selecting-fields), [Relations](https://better-drizzle.com/docs/querying/relations), and [Pagination](https://better-drizzle.com/docs/querying/pagination)
- **Writing & CRUD**: [CRUD Operations](https://better-drizzle.com/docs/writing/crud) and [Throwing Results](https://better-drizzle.com/docs/writing/throwing-results)
- **Core Concepts**: [Transactions](https://better-drizzle.com/docs/advanced/transactions), [Hooks](https://better-drizzle.com/docs/advanced/hooks), and [Error Handling](https://better-drizzle.com/docs/advanced/error-handling)
- **Plugins**: [Plugins Overview](https://better-drizzle.com/docs/plugins/overview) and [Writing Custom Plugins](https://better-drizzle.com/docs/plugins/writing-plugins)
- **Advanced Patterns**: [Service-layer Patterns](https://better-drizzle.com/docs/guides/service-patterns) and [Dynamic Repositories](https://better-drizzle.com/docs/guides/dynamic-repositories)

## Resources

- [better-drizzle documentation](https://better-drizzle.com/docs)
- [better-drizzle GitHub repository](https://github.com/almeidazs/better-drizzle)
- [Neon Drizzle setup guide](https://neon.com/docs/guides/drizzle)
- [Schema migration with Neon and Drizzle](https://neon.com/docs/guides/drizzle-migrations)
- [Realtime live SQL queries with Drizzle](https://neon.com/docs/realtime/examples/drizzle)

--- [Document source](https://neon.com/docs/guides/branch-archiving.md) ---

> Summary: Neon automatically archives inactive branches older than 14 days, moving their data to cost-effective object storage to reduce costs. Archived branches unarchive automatically on first access, though paid plans enforce a limit on unarchived branches per project before forced early archiving applies. Use this page to understand archiving thresholds, blocking conditions, and how to monitor archive and unarchive operations via the Console, CLI, or API.

# Branch archiving

Learn how Neon automatically archives inactive branches to cost-effective storage

Last updated: 2026-10-09

**What you will learn:**

- How Neon archives inactive branches
- How branches are unarchived
- How to monitor branch archiving

**Related docs**

- [Archive storage](https://neon.com/docs/reference/glossary#archive-storage)
- [Branches list command (Neon CLI)](https://neon.com/docs/cli/branches#list)
- [Get branch details (Neon API)](https://neon.com/docs/reference/api/branches/get-project-branch)

To minimize storage costs, Neon automatically archives branches that are:

- Older than **14 days**.
- Have not been accessed for the past **24 hours**

Both conditions must be true for a branch to be archived.

However, a branch **cannot** be archived if it:

- Has an **unarchived child branch**.
- Has **computes running**.
- Is **in transition** (for example, currently being created or unarchived).
- Is a **protected branch** ([learn more](https://neon.com/docs/guides/protected-branches)).

**Note:** If your Neon project was inactive for more than a week before the introduction of branch archiving on November 11, 2024, the thresholds mentioned above do not come into effect until the next time you access branches in your project.

## Unarchiving a branch

**No action is required to unarchive a branch. It happens automatically.**

Connecting to an archived branch, querying it, or performing some other action that accesses it will trigger the unarchive process. Branches with large amounts of data may experience slightly slower connection and query times while a branch is being unarchived.

For projects on paid Neon plans, there is a limit of **100 unarchived branches per project**. If a project reaches this limit, Neon archives branches **without waiting** for the 14-day or 24-hour archiving criteria described above.

**Note:** When a branch is unarchived, its parent branches, all the way up to the root branch, are also unarchived.

The following actions will automatically unarchive a branch, transferring the branch's data back to regular database storage:

- [Connecting to or querying the branch from a client or application](https://neon.com/docs/connect/connect-from-any-app)
- [Querying the branch from the Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor)
- [Viewing the branch on the Tables page in the Neon Console](https://neon.com/docs/guides/tables)
- [Creating a child branch](https://neon.com/docs/manage/branches#create-a-branch)
- [Creating a role on a branch](https://neon.com/docs/manage/roles#create-a-role)
- [Creating a database on a branch](https://neon.com/docs/manage/databases#create-a-database)
- [Reset the branch from its parent](https://neon.com/docs/manage/branches#reset-a-branch-from-parent)
- [Performing a restore operation on a branch](https://neon.com/docs/guides/branch-restore)
- [Setting the branch as protected](https://neon.com/docs/guides/protected-branches)
- Running [Neon CLI](https://neon.com/docs/cli) commands or [Neon API](https://neon.com/docs/reference/api) calls that access the branch

## Identifying archived branches

Archived branches can be identified by an archive icon on the **Branches** page in the Neon Console:

![the archive icon shown on a branch in the branches list page](https://neon.com/docs/guides/archived_branch_icon.png)

If you select an archived branch on the **Branches** page to view its details, you can see when the branch was archived:

![the archive status shown on a branch in the branch detail page](https://neon.com/docs/guides/archived_branch_details.png)

Archive and unarchive operations can also be monitored in the Neon Console or using the Neon API. See [Monitoring branch archiving](https://neon.com/docs/guides/branch-archiving#monitoring-branch-archiving).

## About archive storage

For Neon projects created in AWS regions, inactive branches are archived in Amazon S3 storage. For Neon projects created in Azure regions, branches are archived in Azure Blob storage. For more information about how archive storage works in Neon, refer to [Archive storage](https://neon.com/docs/reference/glossary#archive-storage) in our architecture documentation.

## Is branch archiving configurable?

Branch archiving thresholds are not configurable. Archiving and unarchiving happen automatically according to the thresholds and conditions described above.

If you know when a branch should be deleted, set an expiration date rather than wait for automatic archiving. This guarantees automatic deletion at the specified time and works well for CI/CD pipelines and temporary environments. See [Branch expiration](https://neon.com/docs/guides/branch-expiration) for details.

## Disabling branch archiving

You cannot fully disable branch archiving, but you can prevent a branch from being archived by defining it as a **protected branch**. For instructions, see [Set a branch as protected](https://neon.com/docs/manage/branches#set-a-branch-as-protected). Protected branches are supported on Neon paid plans.

## Monitoring branch archiving

You can monitor branch archive and unarchive operations from the **System operations** tab on the **Monitoring** page in the Neon Console. Look for the following operations:

- `Timeline archive`: The time when the branch archive operation was initiated
- `Timeline unarchive`: The time when the branch unarchive operation was initiated

For related information, see [System operations](https://neon.com/docs/manage/operations).

You can also monitor branch archiving using the Neon CLI or Neon API.

**CLI**

The Neon CLI [branches list](https://neon.com/docs/cli/branches#list) command shows a branch's `Current State`. Branch states include:

- `init` - the branch is being created but is not available for querying.
- `ready` - the branch is fully operational and ready for querying. Expect normal query response times.
- `archived` - the branch is stored in cost-effective archive storage. Expect slow query response times.

  ```bash
  neon branches list --project-id green-hat-46829796
  Name            ID                       Current State  Expires At  Created At
  [default] main  br-muddy-firefly-123456  ready          never       2026-10-30T14:59:57Z
  ```

**API**

The Neon API's [Get branch details](https://neon.com/docs/reference/api/branches/get-project-branch) endpoint can retrieve a branch's state:

```bash
curl --request GET \
     --url https://console.neon.tech/api/v2/projects/{project-id}/branches/{branch_id} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

The response includes a `current_state`, a `state_changed_at` timestamp for when the current state began, and a `pending_state` if the branch is currently transitioning between states. State values include:

- `init` - the branch is being created but is not available for querying.
- `ready` - the branch is fully operational and ready for querying. Expect normal query response times.
- `archived` - the branch is stored in cost-effective archive storage. Expect slow query response times.

This example shows a branch that is currently `archived`. The `state_changed_at` shows a timestamp indicating when the state last changed.

```json {9,10}
{
  "branch": {
    "id": "br-broad-smoke-w2sqcu0i",
    "project_id": "proud-darkness-91591984",
    "parent_id": "br-falling-glade-w25m64ct",
    "parent_lsn": "0/1F78F48",
    "parent_timestamp": "2024-10-02T08:54:18Z",
    "name": "development",
    "current_state": "archived",
    "state_changed_at": "2024-11-06T14:20:58Z",
    "logical_size": 30810112,
    "creation_source": "console",
    "primary": false,
    "default": false,
    "protected": false,
    ...
```

--- [Document source](https://neon.com/docs/guides/branch-expiration.md) ---

> Summary: Branch expiration automatically deletes Neon branches at a scheduled time using a TTL model, with expiration set via the Console, CLI (--expires-at flag), or API (expires_at) using RFC 3339 timestamps up to 30 days in the future. Use this feature to prevent storage accumulation from CI/CD test branches, ephemeral AI workflows, or time-boxed feature branches that would otherwise require manual cleanup. Expiration cannot be set on protected, default, or parent branches, and deletion is permanent and also removes associated compute endpoints.

# Branch expiration

Learn how to use Neon's branch expiration feature to automatically delete temporary branches

Last updated: 2026-10-08

## Overview

Branch expiration allows you to set automatic deletion timestamps on branches. When a branch reaches its expiration time, it is automatically deleted.

**Tip: Quick guide**

**Console:** When creating a branch, **Automatically delete branch after** is checked by default with 1 day selected. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable. When updating an existing branch, you can select a custom date and time.

**CLI:** Use `--expires-at` with [RFC 3339 format](https://neon.com/docs/guides/branch-expiration#timestamp-format-requirements) (for example, `2025-07-15T18:02:16Z`). Note: Expiration must be explicitly set; there is no default.

**API:** Use `expires_at` with [RFC 3339 format](https://neon.com/docs/guides/branch-expiration#timestamp-format-requirements) (for example, `2025-07-15T18:02:16Z`). Note: Expiration must be explicitly set; there is no default.

**What you will learn:**

- When and why to use branch expiration
- How to set expiration timestamps via Console, CLI, and API
- How expiration timestamps and TTL intervals work
- Restrictions and best practices

**Related docs**

- [Branching with the Neon CLI](https://neon.com/docs/guides/branching-neon-cli)
- [Branching with the Neon API](https://neon.com/docs/manage/branches#branching-with-the-neon-api)
- [Manage branches](https://neon.com/docs/manage/branches)
- [Branching workflows](https://neon.com/docs/introduction/branching#branching-workflows)

## Why use branch expiration?

Branch expiration is ideal for temporary branches that have predictable lifespans:

- **CI/CD environments** - Test branches that should clean up after pipeline completion
- **Feature development** - Time-boxed feature branches with known deadlines
- **Automated testing** - Ephemeral test environments created by scripts
- **AI workflows** - Temporary environments managed without human intervention

Without automatic expiration, these branches accumulate over time, increasing storage costs and project clutter.

**Tip:** Example expiration durations: CI/CD pipelines (2-4 hours), demos (24-48 hours), feature development (1-7 days), long-term testing (30 days).

## How it works

Branch expiration uses a time-to-live (TTL) model. When you set an expiration on a branch, you're defining how long the branch should exist before automatic deletion.

When you set an expiration timestamp on a branch:

1. The system stores both:
   - **Expiration timestamp** (`expires_at`) - The scheduled date and time when the branch will be deleted
   - **TTL interval** (`ttl_interval_seconds`) - The duration between creation/update and expiration (for example, 24 hours = 86400 seconds), a read-only value

2. A background process monitors branches and deletes them after their expiration time is reached

3. If you reset a branch from its parent, the TTL countdown restarts using the original interval

**Important:** Branch deletion is permanent and cannot be recovered. All associated data and compute endpoints are also deleted. Verify expiration times carefully before setting them.

## Setting branch expiration

You can set, update, or remove expiration timestamps through three interfaces:

- **Console** - When creating a branch, **Automatically delete branch after** is checked by default with 1 day selected. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable. When updating an existing branch, you can select a custom date and time.
- **CLI** - Use the `--expires-at` flag when creating or updating a branch with [RFC 3339](https://neon.com/docs/guides/branch-expiration#timestamp-format-requirements) format. Note: Expiration must be explicitly set; there is no default.
- **API** - Use the `expires_at` parameter with [RFC 3339](https://neon.com/docs/guides/branch-expiration#timestamp-format-requirements) format. Note: Expiration must be explicitly set; there is no default.

See the [Examples](https://neon.com/docs/guides/branch-expiration#examples) section below for detailed usage of each method.

## Timestamp format requirements

The `expires_at` parameter must use [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) format with second-level precision:

**Format patterns:**

```
YYYY-MM-DDTHH:MM:SSZ         (UTC)
YYYY-MM-DDTHH:MM:SS+HH:MM    (Positive UTC offset)
YYYY-MM-DDTHH:MM:SS-HH:MM    (Negative UTC offset)
```

**Valid examples:**

- `2025-07-15T18:02:16Z` (UTC)
- `2025-07-15T18:02:16-05:00` (Eastern Standard Time)
- `2025-07-15T18:02:16+09:00` (Japan Standard Time)

**Requirements:**

- Time zone is required in API requests: use either `Z` for UTC or a numeric offset like `+05:00`. The Neon CLI accepts a timestamp without one and reads it as your local time, so include it to be explicit.
- Fractional seconds are optional but only second precision is stored
- Timestamp must be in the future
- Maximum expiration is 30 days from the current time

**Note:** Common errors include past timestamps, combining `Z` with an offset (`2025-07-15T18:02:16Z-05:00`), and, in API requests, a missing time zone (`2025-07-15T18:02:16`).

## Restrictions

To maintain system integrity, expiration timestamps cannot be added to:

- **Protected branches** - Cannot expire protected branches or protect branches with expiration
- **Default branches** - Cannot expire default branches or set expiring branches as default
- **Parent branches** - Cannot expire branches that have children or create children from expiring branches

Branch expiration is supported with the [Data API](https://neon.com/docs/data-api/get-started) and [Managed Better Auth](https://neon.com/docs/auth/overview). The Data API's configuration lives in the branch database, so it's removed when the branch expires.

**Note:** When a branch expires and is deleted, all associated compute endpoints are also deleted. Ensure any critical workloads are migrated before expiration.

## Examples

### Creating a branch with expiration

**Console**

1. Navigate to the **Branches** page in the Console
2. Click **New branch**
3. Enter branch name and select parent branch
4. By default, **Automatically delete branch after** is checked with 1 day selected. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable.

![Set branch expiration](https://neon.com/docs/changelog/branch_expiration_presets.png)

5. Click **Create**

**CLI**

```bash {6,15}
# Create branch expiring at specific date/time
neon branches create \
  --project-id <project-id> \
  --name feature-test \
  --parent development \
  --expires-at "2026-01-29T18:02:16Z"

# Create branch expiring in 2 hours (using dynamic date)
# Linux/GNU: $(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)
# macOS/BSD: $(date -u -v+2H +%Y-%m-%dT%H:%M:%SZ)
neon branches create \
  --project-id <project-id> \
  --name ci-test \
  --parent development \
  --expires-at "$(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)"
```

**API**

```bash {11,21,22}
# Create branch that expires in 24 hours
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
       "branch": {
         "name": "feature-test",
         "parent_id": "br-main-12345",
         "expires_at": "2026-01-29T18:02:16Z"
       }
     }'

# Example response
{
  "branch": {
    "id": "br-feature-67890",
    "name": "feature-test",
    "parent_id": "br-main-12345",
    "expires_at": "2026-01-29T18:02:16Z",
    "ttl_interval_seconds": 86400,
    "created_at": "2026-01-28T18:02:16Z"
  }
}
```

### Updating branch expiration

**Console**

1. Navigate to the **Branches** page in the Console
2. Choose the **Update expiration** option for your branch

![Update branch expiration](https://neon.com/docs/guides/branch-update-set-expiration.png)

3. To update: Select a new date and time
4. To remove: Uncheck **Automatically delete branch after**
5. Click **Save**

**CLI**

```bash {4,12}
# Update expiration to new timestamp
neon branches set-expiration \
  <branch-id> \
  --expires-at "2026-01-29T12:00:00Z" \
  --project-id <project-id>

# Extend expiration by 7 days from now
# Linux/GNU: $(date -u -d '+7 days' +%Y-%m-%dT%H:%M:%SZ)
# macOS/BSD: $(date -u -v+7d +%Y-%m-%dT%H:%M:%SZ)
neon branches set-expiration \
  <branch-id> \
  --expires-at "$(date -u -d '+7 days' +%Y-%m-%dT%H:%M:%SZ)" \
  --project-id <project-id>

# Remove expiration from a branch (omit --expires-at)
neon branches set-expiration \
  <branch-id> \
  --project-id <project-id>
```

**API**

```bash {9,21}
# Update branch expiration to specific date
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id} \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
       "branch": {
         "expires_at": "2026-01-29T12:00:00Z"
       }
     }'

# Remove expiration from a branch
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id} \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
       "branch": {
         "expires_at": null
       }
     }'
```

### Retrieving branch information

Check expiration status of your branches:

**Console**

1. Navigate to the **Branches** page in the Console
2. Click on the desired branch to open the **Branch Overview**
3. See information similar to the following if branch expiration is set:

![View branch expiration](https://neon.com/docs/guides/branch-view-expiration.png)

**CLI**

```bash
neon branches get <branch_id> --project-id <project_id>
```

**API**

```bash
curl --request GET \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id} \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY"
```

## API reference

### Create project branch

[`POST /projects/{project_id}/branches`](https://neon.com/docs/reference/api/branches/create-project-branch)

- **`expires_at`** (optional) - Timestamp for automatic deletion in [RFC 3339](https://neon.com/docs/guides/branch-expiration#timestamp-format-requirements) format

### Update project branch

[`PATCH /projects/{project_id}/branches/{branch_id}`](https://neon.com/docs/reference/api/branches/update-project-branch)

- **`expires_at`** (optional, nullable) - Update or remove expiration
  - Timestamp value: Sets/updates expiration
  - `null`: Removes expiration
  - Omitted: No change

### Response fields

Branches with expiration include two key fields:

- **`expires_at`** - The scheduled deletion timestamp ([RFC 3339](https://neon.com/docs/guides/branch-expiration#timestamp-format-requirements) format)
- **`ttl_interval_seconds`** - The original TTL duration in seconds (read-only)

#### How these fields work together

When you create a branch with a TTL of 24 hours, `ttl_interval_seconds` is set to 86400 (seconds). The `expires_at` value is calculated as creation time plus 24 hours.

If you reset the branch from its parent, the `expires_at` value is recalculated using the preserved `ttl_interval_seconds` value, starting from the reset time. The interval itself remains unchanged.

**Example response:**

```json {4,5}
{
  "branch": {
    "id": "br-feature-67890",
    "expires_at": "2026-01-29T18:02:16Z",
    "ttl_interval_seconds": 86400,
    "created_at": "2026-01-28T18:02:16Z"
  }
}
```

In this example, the branch will be deleted 24 hours after creation.

--- [Document source](https://neon.com/docs/guides/branching-circleci.md) ---

> Summary: The Neon CircleCI Orb provisions an isolated Lakebase Postgres branch on Neon per CircleCI pipeline run, giving each CI job a real managed Postgres environment instead of a generic Docker container. Use it to eliminate shared-database race conditions and "works in CI, breaks in prod" failures by forking from a pre-migrated parent branch, running tests against that branch, then auto-cleaning up. The orb provides the neon/run_tests job and neon/create_branch, neon/delete_branch, and neon/reset_branch commands. Branches default to a 3600-second TTL and scale to zero between runs. The orb is community-maintained, not officially supported by Neon.

# Automate branching with CircleCI

Learn how to use the Neon CircleCI Orb to provision ephemeral Postgres branches for every CI pipeline run

Last updated: 2026-08-11

The **Neon CircleCI Orb** provisions a real Lakebase Postgres branch per pipeline run (or per parallel node), instead of a generic Postgres-in-Docker service container. That means your CI database behaves like production - same managed Postgres, network, and extensions, so you get fewer "works in CI, breaks in prod" issues.

Each run gets an isolated, ephemeral branch; you can branch from a pre-migrated parent to skip running migrations from scratch, and the orb handles cleanup and TTL so tests stay deterministic and parallel jobs never share state. This guide covers the `neon/run_tests` job and the `neon/create_branch`, `neon/delete_branch`, and `neon/reset_branch` commands.

**Note:** This orb is not maintained or officially supported by Neon. Use at your own discretion. If you have questions or face any issues, please contact the maintainer by raising an issue in the GitHub repository linked below.

**Neon CircleCI Orb**

- [GitHub repository](https://github.com/dhanushreddy291/neon-circle-ci-orb)
- [CircleCI Orb Registry](https://circleci.com/developer/orbs/orb/dhanushreddy291/neon)

## Prerequisites

To use the Neon CircleCI Orb, you need:

- A [CircleCI account](https://circleci.com/) and a project repository.
- A [Neon account](https://console.neon.tech) and a created project.
- A Neon **API Key**. See [Create an API key](https://neon.com/docs/manage/api-keys#create-an-api-key).
- A Neon **Project ID**. You can find this in the **Settings** page of your Neon project.

## Getting started

To allow CircleCI to communicate with Neon, configure your Neon credentials as environment variables in your CircleCI project.

1. In CircleCI, navigate to **Project Settings** > **Environment Variables**.
2. Add the following variables:

- `NEON_API_KEY`: Your Neon API key.
- `NEON_PROJECT_ID`: The ID of your Neon project.
  ![CircleCI environment variable configuration](https://neon.com/docs/guides/circleci-env-vars.png)

## Configuring pipeline triggers

To configure when your CircleCI pipeline runs, set the pipeline trigger settings:

1. In CircleCI, navigate to **Project Settings** > **Pipelines**.
2. Under the **Triggers** section, select the trigger condition.
3. Set it to **"PR opened or pushed to, default branch and tag pushes"**.

![CircleCI pipeline trigger configuration](https://neon.com/docs/guides/circleci-pipeline-trigger-settings.png)

This configuration triggers the pipeline for:

- Pull requests (when opened or pushed to)
- Direct pushes to the default branch
- Tag pushes

Each pipeline run creates a fresh Neon branch, ensuring isolated database environments for tests. PR workflows get dedicated branches without affecting the main branch or other PRs.

## Available jobs and commands

The orb provides the following pre-configured jobs and commands to manage Neon branches in your CircleCI pipelines:

| Component            | Type    | Description                                                                                  |
| :------------------- | :------ | :------------------------------------------------------------------------------------------- |
| `neon/run_tests`     | Job     | Creates a branch, runs migrations/tests, and deletes the branch. Best for standard CI flows. |
| `neon/create_branch` | Command | Creates a branch and exports connection variables.                                           |
| `neon/delete_branch` | Command | Deletes a branch.                                                                            |
| `neon/reset_branch`  | Command | Resets a branch to the parent's latest state. Useful for persistent staging environments.    |

## The `neon/run_tests` job

The `neon/run_tests` job automates the entire lifecycle of a Neon branch for testing. It provisions a branch, runs your specified commands, and ensures cleanup happens even if tests fail.

This job is ideal for most CI use cases where you want a fresh database for every pipeline run without having to manage the branch lifecycle manually.

The job accepts the following parameters:

- `api_key`: (Optional) Environment variable name containing the Neon API key. Defaults to `NEON_API_KEY`. Ensure this variable is set in your CircleCI project settings.
- `project_id`: (Optional) Environment variable name containing the Neon project ID. Defaults to `NEON_PROJECT_ID`. Ensure this variable is set in your CircleCI project settings.
- `parent_branch`: (Optional) The branch to fork from. Defaults to your project's default branch (named `main` if the project was created with the CLI or API, or `production` if created in the Console).
- `migrate_command`: The command to prepare the database (e.g., run migrations). This command runs after the branch is ready but before tests start. You can chain multiple commands here if needed (for example, installing dependencies and running migrations).
- `test_command`: The command to execute your tests. This command runs after the `migrate_command` completes. It should be configured to run your test suite (e.g., unit tests, integration tests, or end-to-end tests with Playwright) against the database using the `DATABASE_URL` environment variable.
- `role`: (Optional) The role to use for the connection. Defaults to `neondb_owner`.
- `database`: (Optional) The database name. Defaults to `neondb`.
- `password`: (Optional) The password for the role. You need to set this if you chose not to store passwords for your provided role in the Neon Console. If your role has a stored password in Neon, the Orb retrieves it automatically via API.
- `schema_only`: (Optional) If `true`, creates a schema-only branch. Defaults to `false`.
- `get_auth_url`: (Optional) If `true`, exports `NEON_AUTH_URL` for branches with Managed Better Auth enabled. Defaults to `false`.
- `get_data_api_url`: (Optional) If `true`, tries to export `NEON_DATA_API_URL` for branches with Data API enabled. Defaults to `false`.

**Outputs:**

- `DATABASE_URL`: The full connection string for the provisioned branch.
- `DATABASE_URL_POOLED`: The pooled connection string.
- `PGHOST`, `PGHOST_POOLED`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`: Individual connection parameters.
- `NEON_BRANCH_ID`: The ID of the created branch.
- `NEON_AUTH_URL`: The Managed Better Auth URL (if `get_auth_url` is `true` and Managed Better Auth is enabled).
- `NEON_DATA_API_URL`: The Neon Data API URL (if `get_data_api_url` is `true` and Data API is enabled).

An example usage of the `neon/run_tests` job is provided in the [Example: CircleCI configuration](https://neon.com/docs/guides/branching-circleci#example-circleci-configuration) section below.

### How it works

When the `neon/run_tests` job runs, it performs the following steps automatically:

1. **Provision**: Creates a Neon branch from `parent_branch`. The orb auto‑names it as `circle-ci-${CIRCLE_PIPELINE_NUM}-${CIRCLE_NODE_INDEX}` (pipeline run ID + parallel executor index).
2. **Connect**: Exports the connection string as `DATABASE_URL` (and individual PG variables like `PGHOST`, `PGUSER`, `PGPASSWORD`, `PGHOST_POOLED`) to the job environment.
3. **Prepare**: Runs the `migrate_command` you provided.
4. **Test**: Runs the `test_command` you provided.
5. **Cleanup**: Deletes the branch after tests complete, regardless of success or failure.

### Using the connection string

The `neon/run_tests` job automatically sets the `DATABASE_URL` environment variable, which contains your database connection string.

This means that any tool, migration script, or test runner that relies on `DATABASE_URL` can use it directly without extra configuration. For example, a migration command such as `npx drizzle-kit migrate` or a test command like `npm test` can connect to the Neon branch using the provided connection string. Alternatively, you can use the individual connection parameters (`PGHOST`, `PGUSER`, `PGPASSWORD`, etc.) if your tools require them.

### Example: CircleCI configuration

To better understand how to use `neon/run_tests` job, consider the following example CircleCI (`.circleci/config.yml`) configuration:

```yaml
version: 2.1

orbs:
  neon: dhanushreddy291/neon@1.0
  node: circleci/node@7.2.1

workflows:
  test_workflow:
    jobs:
      - neon/run_tests:
          name: e2e_tests
          executor:
            name: node/default
            tag: "24.12"
          # Migrate command can be any setup command that prepares the database. It runs after the branch is ready but before tests start. You can chain multiple commands here if needed.
          migrate_command: npm ci && npm run db:migrate && npx playwright install --with-deps chromium
          # Run any test command that relies on DATABASE_URL for the connection string. (e.g., unit tests, integration tests, or end-to-end tests with Playwright)
          test_command: npm test
```

In this example:

- **`orbs`**: Imports the `neon` orb (to manage database branches) and the `circleci/node` orb (to set up the Node.js environment).
- **`executor`**: Specifies the execution environment. We use the `node/default` executor from the Node orb with tag `24.12`.
- **`migrate_command`**: A chained command that installs dependencies (`npm ci`), runs database migrations (`npm run db:migrate`), and sets up browser binaries for Playwright (`npx playwright install ...`). This runs _after_ the database branch is created but _before_ tests start.
- **`test_command`**: The actual test runner command. You can configure `npm test` in your `package.json` to run any test suite, unit tests, integration tests, or end-to-end tests with tools like Playwright against the isolated Neon branch.

Checkout the full example in the [GitHub repository](https://github.com/dhanushreddy291/hono-crud-api), which shows a basic Hono app with a Playwright test suite. It uses the `neon/run_tests` job in CircleCI to provision a Neon branch, run migrations, and execute tests ensuring each pipeline run gets a fresh, isolated database for reliable per PR testing.

## Custom workflows with Orb commands

For advanced use cases such as complex build matrices or multi-stage pipelines you can use the Orb's granular commands directly within your own jobs.

## Available commands

The Orb provides the following commands for building custom workflows.

### `neon/create_branch`

Creates a new database branch. This command waits for the branch to be active ("ready") and exports the connection details to the environment.

| Input              | Type           | Default             | Description                                                                                                                                    |
| :----------------- | :------------- | :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`          | env\_var\_name | `NEON_API_KEY`      | Environment variable name containing the Neon API key.                                                                                         |
| `project_id`       | env\_var\_name | `NEON_PROJECT_ID`   | Environment variable name containing the Neon project ID.                                                                                      |
| `parent_branch`    | string         | _project default_   | The parent branch name or ID to fork from.                                                                                                     |
| `branch_name`      | string         | _generated_         | Custom branch name. If empty, defaults to `circle-ci-${CIRCLE_PIPELINE_NUM}-${CIRCLE_NODE_INDEX}` (pipeline run ID + parallel executor index). |
| `role`             | string         | `neondb_owner`      | The role to use for the connection.                                                                                                            |
| `database`         | string         | `neondb`            | Database name in connection strings.                                                                                                           |
| `password`         | string         | _retrieved via API_ | Password for the role. Required if role passwords are not stored in Neon.                                                                      |
| `ttl_seconds`      | integer        | `3600`              | Branch lifespan in seconds. Set `0` to disable auto-expiry.                                                                                    |
| `schema_only`      | boolean        | `false`             | Creates a schema-only branch when enabled.                                                                                                     |
| `get_auth_url`     | boolean        | `false`             | Exports `NEON_AUTH_URL` when Managed Better Auth is enabled for the branch.                                                                    |
| `get_data_api_url` | boolean        | `false`             | Exports `NEON_DATA_API_URL` when Data API is enabled for the branch/database.                                                                  |

**Outputs:**

- `DATABASE_URL`: The full connection string.
- `DATABASE_URL_POOLED`: The pooled connection string.
- `PGHOST`: The host address.
- `PGHOST_POOLED`: The pooled host address.
- `PGUSER`, `PGPASSWORD`, `PGDATABASE`: Individual connection parameters.
- `NEON_BRANCH_ID`: The ID of the created branch.
- `NEON_AUTH_URL`: The Managed Better Auth URL (if `get_auth_url` is `true` and Managed Better Auth is enabled).
- `NEON_DATA_API_URL`: The Neon Data API URL (if `get_data_api_url` is `true` and Data API is enabled).

### `neon/delete_branch`

Deletes a Neon branch. This is typically used in the final step of a job to clean up resources.

| Input        | Type           | Default           | Description                                                                                  |
| :----------- | :------------- | :---------------- | :------------------------------------------------------------------------------------------- |
| `api_key`    | env\_var\_name | `NEON_API_KEY`    | Environment variable name containing the Neon API key.                                       |
| `project_id` | env\_var\_name | `NEON_PROJECT_ID` | Environment variable name containing the Neon project ID.                                    |
| `branch_id`  | string         | `$NEON_BRANCH_ID` | The branch ID to delete. If omitted, the command uses `NEON_BRANCH_ID` from `create_branch`. |

If the branch is already gone (for example, expired via TTL), delete returns a safe no-op instead of failing.

### `neon/reset_branch`

Resets a branch to the latest state of its parent. This is useful for long-lived branches (like `staging` or `dev`) that need to be refreshed with production data before running tests.

| Input           | Type           | Default           | Description                                               |
| :-------------- | :------------- | :---------------- | :-------------------------------------------------------- |
| `api_key`       | env\_var\_name | `NEON_API_KEY`    | Environment variable name containing the Neon API key.    |
| `project_id`    | env\_var\_name | `NEON_PROJECT_ID` | Environment variable name containing the Neon project ID. |
| `branch_id`     | string         | -                 | Required. Branch ID or branch name to reset.              |
| `parent_branch` | string         | _original parent_ | Optional parent branch name or ID to reset from.          |

**Outputs:**

Unlike `neon/create_branch`, this command does not export a `DATABASE_URL`. It also does not support options like `role`, `database`, `password`, `schema_only`, `get_auth_url`, or `get_data_api_url`. You must ensure your job has access to the connection details for the target branch (e.g., via CircleCI context or project environment variables).

### Example: Custom job configuration

Here is how to compose these commands manually:

```yaml
version: 2.1

orbs:
  neon: dhanushreddy291/neon@1.0

jobs:
  custom-test:
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - neon/create_branch:
          parent_branch: production
          # Optional: Define a custom TTL (e.g., 30 minutes)
          ttl_seconds: 1800

      - run:
          name: Run Migrations
          command: npm run db:migrate

      - run:
          name: Run Tests
          command: npm test

      - neon/delete_branch:
          when: always  # Ensure branch is deleted even if tests fail

workflows:
  main:
    jobs:
      - custom-test
```

### Example: Resetting a long-lived branch

Instead of creating a new branch every time, you can reset a persistent branch like a staging environment to the latest state of your parent branch.

```yaml
jobs:
  reset-staging:
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - neon/reset_branch:
          # The ID of your persistent staging branch, stored as an environment variable
          branch_id: $STAGING_BRANCH_ID
          # The parent branch to reset from
          parent_branch: production

      - run:
          name: Run Integration Tests
          # Ensure DATABASE_URL is set in your environment (e.g., via CircleCI Project Settings)
          command: npm run test:integration
```

## Best practices

### Branch lifecycle and costs

Neon branches are lightweight and "scale-to-zero" by default, meaning you are not charged for compute when tests are not running. However, branches do consume storage (the delta from the parent branch), so it's important to ensure they are cleaned up after use to avoid unnecessary costs.

To optimize costs don't set the TTL too high for ephemeral branches. For long-lived branches (like staging), consider using the `reset_branch` command instead of creating new branches to minimize storage usage.

### Concurrency

The Neon Orb is designed for concurrency. If you run parallel tests (e.g., CircleCI `parallelism: 4`), the Orb creates a unique branch for every parallel executor. This ensures that tests running at the same time never read or write to the same database, eliminating race conditions and "flaky" tests caused by shared state.

The default branch names are generated from `CIRCLE_PIPELINE_NUM` and include a suffix for parallel executors (for example, `1234-1`, `1234-2`). This allows you to identify which branch corresponds to which test executor in your CircleCI dashboard.

--- [Document source](https://neon.com/docs/guides/branching-github-actions.md) ---

> Summary: Neon's GitHub Actions automate database branching inside CI/CD pipelines, enabling ephemeral Postgres branches for pull request (PR) preview deployments and isolated test environments. The actions cover branch creation, deletion, reset, and schema diff. Configure NEON_API_KEY and NEON_PROJECT_ID via the Neon GitHub integration or manual repository secrets before wiring them into workflow YAML files. The schema diff action posts a branch comparison as a pull request comment.

# Automate branching with GitHub Actions

Create and delete branches with GitHub Actions

Last updated: 2026-06-05

Neon provides a set of GitHub Actions to automate the creation, deletion, and management of database branches in your Neon projects.
These actions allow you to automate database branching as part of your CI/CD workflows, enabling you to create ephemeral database branches for pull requests, run tests against isolated data, and clean up resources automatically.

This guide covers how to set up and use the Neon GitHub Actions for managing database branches, including creating, deleting, resetting branches, and comparing schemas.

## Getting started

To use Neon's GitHub Actions, you need to add your Neon API key and Project ID to your GitHub repository. This allows the actions to authenticate with your Neon project and perform operations on your database branches.

### Automatically set up with the Neon GitHub integration

The easiest way to get started is with the [Neon GitHub integration](https://neon.com/docs/guides/neon-github-integration). It connects your Neon project to a GitHub repository, automatically creating the necessary `NEON_API_KEY` secret and `NEON_PROJECT_ID` variable for you. If you use the integration, you can skip the manual setup steps below.

### Manually set up your repository

1. **Create a Neon API key.** For instructions, see [Create an API key](https://neon.com/docs/manage/api-keys#create-an-api-key).
2. **Add the key to GitHub.** In your GitHub repository, navigate to **Settings** > **Secrets and variables** > **Actions**.
3. Click **New repository secret**.
4. Name the secret `NEON_API_KEY` and paste your API key into the value field.
5. Click **Add secret**.
6. You will also need your Neon **Project ID**, which you can find in the **Settings** page of the Neon console.
7. Add the Project ID to your GitHub repository as a **variable**:
   - In your GitHub repository, navigate to **Settings** > **Secrets and variables** > **Actions**.
   - Select **Variables** and click **New repository variable**.
   - Name the variable `NEON_PROJECT_ID` and set its value to your Neon Project ID.
   - Click **Add variable**.

You can now use the Neon GitHub Actions in your workflows by referencing them in your `.github/workflows` YAML files.

## Available actions

Neon provides the following GitHub Actions for working with Neon branches. For detailed information on usage, inputs, and outputs, please refer to the official documentation for each action on the GitHub Marketplace.

- **[Create branch action](https://github.com/marketplace/actions/neon-create-branch-github-action)**: Creates a new database branch in your Neon project. This is ideal for setting up isolated environments for preview deployments or running tests against a feature branch.
- **[Delete branch action](https://github.com/marketplace/actions/neon-database-delete-branch)**: Deletes a specified database branch. Use this to automate the cleanup of ephemeral branches after a pull request is merged or closed.
- **[Reset branch action](https://github.com/marketplace/actions/neon-database-reset-branch-action)**: Resets a branch to the latest state of its parent. This is useful for refreshing a development or staging branch with the most up-to-date data.
- **[Schema diff action](https://github.com/marketplace/actions/neon-schema-diff-github-action)**: Compares the schemas of two branches and posts a diff summary as a comment on a pull request, allowing for easy review of schema changes.

For detailed information on how to use these actions, including required inputs, outputs, and examples, check the individual actions documentation on GitHub Marketplace:

- [Create branch action](https://github.com/marketplace/actions/neon-create-branch-github-action): Creates a new database branch. Ideal for setting up isolated environments for preview deployments or feature testing.
- [Delete branch action](https://github.com/marketplace/actions/neon-database-delete-branch): Deletes a specified database branch. Use this to clean up ephemeral branches after a pull request is merged or closed.
- [Reset branch action](https://github.com/marketplace/actions/neon-database-reset-branch-action): Resets a branch to the latest state of its parent. Useful for refreshing a development branch with production data.
- [Schema diff action](https://github.com/marketplace/actions/neon-schema-diff-github-action): Compares the schema of two branches and posts a diff summary as a comment on a pull request.

## Example applications

For complete, deployable examples, explore these starter repositories:

- [Preview branches with Cloudflare Pages](https://github.com/neondatabase/preview-branches-with-cloudflare): Demonstrates using GitHub Actions workflows to create a Neon branch for every Cloudflare Pages preview deployment
- [Preview branches with Vercel](https://github.com/neondatabase/preview-branches-with-vercel): Demonstrates using GitHub Actions workflows to create a Neon branch for every Vercel preview deployment
- [Preview branches with Fly.io](https://github.com/neondatabase/preview-branches-with-fly): Demonstrates using GitHub Actions workflows to create a Neon branch for every Fly.io preview deployment

--- [Document source](https://neon.com/docs/guides/branching-neon-api.md) ---

> Summary: Neon API branch management lets you create, list, delete, restore, schema-only clone, and auto-expire branches programmatically using REST endpoints authenticated with a Neon API key. Use this page when you need to script branch workflows or integrate branch lifecycle into CI/CD pipelines, as opposed to using the Neon Console or CLI. Branch expiration accepts an RFC 3339 timestamp up to 30 days in the future. Schema-only branch creation via init_source=schema-only is in beta.

# Branching with the Neon API

Learn how to create and delete branches with the Neon API

Last updated: 2026-10-14

The examples in this guide demonstrate creating, viewing, and deleting branches using the Neon API. For other branch-related API methods, refer to the [Neon API Reference](https://neon.com/docs/reference/api).

**Note:** The API examples that follow may only show some of the user-configurable request body attributes that are available to you. To view all attributes for a particular method, refer to the method's request body schema in the [Neon API Reference](https://neon.com/docs/reference/api).

The `jq` program specified in each example is an optional third-party tool that formats the `JSON` response, making it easier to read. For information about this utility, see [jq](https://stedolan.github.io/jq/).

## Prerequisites

A Neon API request requires an API key. For information about obtaining an API key, see [Create an API key](../manage/api-keys#create-an-api-key). In the examples below, `$NEON_API_KEY` is specified in place of an actual API key, which you must provide when making a Neon API request.

## Create a branch with the API

The following Neon API method creates a branch. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch).

```http
POST /projects/{project_id}/branches
```

The API method appears as follows when specified in a cURL command:

**Note:** This method does not require a request body. Without a request body, the method creates a branch from the project's default branch, and a compute is not created.

```bash
curl 'https://console.neon.tech/api/v2/projects/<project_id>/branches' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoints": [
    {
      "type": "read_write"
    }
  ],
  "branch": {
    "parent_id": "br-wispy-dew-591433"
  }
}' | jq
```

- The `project_id` for a Neon project is found on the **Settings** page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API. It is a generated value that looks something like this: `autumn-disk-484331`.
- The `endpoints` attribute creates a compute, which is required to connect to the branch. Neon supports `read_write` and `read_only` compute types. A branch can be created with or without a compute. You can specify `read_only` to create a [read replica](https://neon.com/docs/guides/read-replica-guide).
- The `branch` attribute specifies the parent branch.
- The `parent_id` can be obtained by listing the branches for your project. See [List branches](https://neon.com/docs/guides/branching-neon-api#list-branches-with-the-api). The `parent_id` is the `id` of the branch you are branching from. A branch `id` has a `br-` prefix. You can branch from your Neon project's default branch or a non-default branch.

The response includes information about the branch, the branch's compute, and the `create_branch` and `start_compute` operations that were initiated.

```json
{
  "branch": {
    "id": "br-dawn-scene-747675",
    "project_id": "autumn-disk-484331",
    "parent_id": "br-wispy-dew-591433",
    "parent_lsn": "0/1AA6408",
    "name": "br-dawn-scene-747675",
    "current_state": "init",
    "pending_state": "ready",
    "created_at": "2022-12-08T19:55:43Z",
    "updated_at": "2022-12-08T19:55:43Z"
  },

  "endpoints": [
    {
      "host": "ep-small-bush-675287.us-east-2.aws.neon.tech",
      "id": "ep-small-bush-675287",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 1,
      "region_id": "aws-us-east-2",
      "type": "read_write",
      "current_state": "init",
      "pending_state": "active",
      "settings": {
        "pg_settings": {}
      },
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "created_at": "2022-12-08T19:55:43Z",
      "updated_at": "2022-12-08T19:55:43Z",
      "proxy_host": "us-east-2.aws.neon.tech"
    }
  ],
  "operations": [
    {
      "id": "22acbb37-209b-4b90-a39c-8460090e1329",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "action": "create_branch",
      "status": "running",
      "failures_count": 0,
      "created_at": "2022-12-08T19:55:43Z",
      "updated_at": "2022-12-08T19:55:43Z"
    },
    {
      "id": "055b17e6-ffe3-47ab-b545-cfd7db6fd8b8",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "endpoint_id": "ep-small-bush-675287",
      "action": "start_compute",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2022-12-08T19:55:43Z",
      "updated_at": "2022-12-08T19:55:43Z"
    }
  ]
}
```

## List branches with the API

The following Neon API method lists branches for the specified project. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/list-project-branches).

```http
GET /projects/{project_id}/branches
```

The API method appears as follows when specified in a cURL command:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/branches' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

The `project_id` for a Neon project is found on the **Settings** page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API.

The response lists the project's default branch and any child branches. The name of the default branch in this example is `main`.

Response:

```json
{
  "branches": [
    {
      "id": "br-dawn-scene-747675",
      "project_id": "autumn-disk-484331",
      "parent_id": "br-wispy-dew-591433",
      "parent_lsn": "0/1AA6408",
      "name": "br-dawn-scene-747675",
      "current_state": "ready",
      "logical_size": 28,
      "created_at": "2022-12-08T19:55:43Z",
      "updated_at": "2022-12-08T19:55:43Z"
    },
    {
      "id": "br-wispy-dew-591433",
      "project_id": "autumn-disk-484331",
      "name": "main",
      "current_state": "ready",
      "logical_size": 28,
      "physical_size": 31,
      "created_at": "2022-12-07T00:45:05Z",
      "updated_at": "2022-12-07T00:45:05Z"
    }
  ]
}
```

## Delete a branch with the API

The following Neon API method deletes the specified branch. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/delete-project-branch).

```http
DELETE /projects/{project_id}/branches/{branch_id}
```

The API method appears as follows when specified in a cURL command:

```bash
curl -X 'DELETE' \
  'https://console.neon.tech/api/v2/projects/autumn-disk-484331/branches/br-dawn-scene-747675' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

- The `project_id` for a Neon project is found on the **Settings** page in the Neon Console, or you can find it by listing the projects for your Neon account using the Neon API.
- The `branch_id` can be found by listing the branches for your project. The `<branch_id>` is the `id` of a branch. A branch `id` has a `br-` prefix. See [List branches](https://neon.com/docs/guides/branching-neon-api#list-branches-with-the-api).

The response shows information about the branch being deleted and the `suspend_compute` and `delete_timeline` operations that were initiated.

```json
{
  "branch": {
    "id": "br-dawn-scene-747675",
    "project_id": "autumn-disk-484331",
    "parent_id": "br-shy-meadow-151383",
    "parent_lsn": "0/1953508",
    "name": "br-flat-darkness-194551",
    "current_state": "ready",
    "created_at": "2022-12-08T20:01:31Z",
    "updated_at": "2022-12-08T20:01:31Z"
  },
  "operations": [
    {
      "id": "c7ee9bea-c984-41ac-8672-9848714104bc",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "endpoint_id": "ep-small-bush-675287",
      "action": "suspend_compute",
      "status": "running",
      "failures_count": 0,
      "created_at": "2022-12-08T20:01:31Z",
      "updated_at": "2022-12-08T20:01:31Z"
    },
    {
      "id": "41646f65-c692-4621-9538-32265f74ffe5",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "action": "delete_timeline",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2022-12-06T01:12:10Z",
      "updated_at": "2022-12-06T01:12:10Z"
    }
  ]
}
```

You can verify that a branch is deleted by listing the branches for your project. See [List branches](https://neon.com/docs/guides/branching-neon-api#list-branches-with-the-api). The deleted branch should no longer be listed.

## Restoring a branch using the API

To revert changes or recover lost data, you can use the branch restore endpoint in the Neon API.

```bash
POST /projects/{project_id}/branches/{branch_id_to_restore}/restore
```

For details on how to use this endpoint to restore a branch to its own or another branch's history, restore a branch to the head of its parent, and other restore options, see [Instant restore using the API](https://neon.com/docs/introduction/branch-restore#how-to-use-instant-restore).

## Creating a schema-only branch using the API

**Note:** The API is in beta and subject to change.

To create a schema-only branch using the Neon API, use the [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch) endpoint with the `init_source` option set to `schema-only`, as shown below. Required values include:

- Your Neon `project_id`
- The `parent_id`, which is the branch ID of the branch containing the schema you want to copy

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/wispy-salad-58347608/branches \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "branch": {
    "parent_id": "br-super-mode-w371g4od",
    "name": "my_schema_only_branch",
    "init_source": "schema-only"
  }
}
'
```

## Creating a branch with expiration using the API

To create a branch with an automatic expiration timestamp using the Neon API, use the [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch) endpoint with the `expires_at` option. When a branch reaches its expiration time, it is automatically deleted. Required values include:

- Your Neon `project_id`
- The `parent_id`, which is the branch ID of the branch you want to branch from
- The `expires_at` timestamp in [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6) format including a time zone (Z or offset)
- The expiration must be in the future and no more than 30 days from now

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/wispy-salad-58347608/branches \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
       "branch": {
         "name": "feature-test-branch",
         "parent_id": "br-super-mode-w371g4od",
         "expires_at": "2024-12-15T18:02:16Z"
       },
       "endpoints": [
         {
           "type": "read_write"
         }
       ]
     }'
```

Example response (partial):

```json
{
  "branch": {
    "id": "br-feature-67890",
    "name": "feature-test-branch",
    "expires_at": "2024-12-15T18:02:16Z",
    "ttl_interval_seconds": 604800,
    "created_at": "2024-12-08T18:02:16Z"
  }
}
```

Key response fields for branch expiration:

- The `expires_at` field shows the scheduled deletion timestamp in RFC 3339 format
- The `ttl_interval_seconds` field is the original expiration interval, in seconds (read-only)

For more detailed information about branch expiration, including updating and removing expiration timestamps, see [Branch expiration](https://neon.com/docs/guides/branch-expiration).

--- [Document source](https://neon.com/docs/guides/branching-neon-cli.md) ---

> Summary: Neon CLI branch management guide with runnable examples for neon branches create, list, delete, reset, restore, and set-expiration. Covers table/json/yaml output formats and API key authentication via NEON_API_KEY. Use this page to automate branching in CI pipelines, create branches from a non-default parent with --parent, or set a branch TTL with --expires-at. Console and API equivalents for these operations are covered on separate pages.

# Branching with the Neon CLI

Learn how to create and delete branches with the Neon CLI

Last updated: 2026-10-09

The examples in this guide demonstrate creating, viewing, and deleting branches using the Neon CLI. For other branch-related CLI commands, refer to [Neon CLI commands — branches](https://neon.com/docs/cli/branches). This guide also describes how to use the `--api-key` option to authenticate CLI branching commands from the command line.

The examples show the default `table` output format. The Neon CLI also supports `json` and `yaml` output formats. For example, if you prefer output in `json`, add `--output json` to your Neon CLI command.

## Prerequisites

- The Neon CLI. See [Install the Neon CLI](https://neon.com/docs/cli/install) for instructions.
- To run CLI commands, you must either authenticate through your browser or supply an API key using the `--api-key` option. See [Connect with the Neon CLI](https://neon.com/docs/cli/install#connect).

## Create a branch with the CLI

The following Neon CLI command creates a branch. This command requires specifying which project to use. You can use the `--project-id` option or set a default project using `neon set-context`. To view the CLI documentation for this command, refer to the [Neon CLI reference](https://neon.com/docs/cli/branches#create).
The command response includes the branch ID, the compute endpoint ID, and the connection URI for connecting to the branch.

**Tip:** You can use the `--name` option with a `neon branches create` command to specify your own branch name instead of using the name generated by Neon. For example: `neon branches create --name mybranch`. Also, for any Neon CLI command, you can specify `--output json` to change the command output from the default table format to JSON format.

```bash
neon branches create

Branch
Name           br-lucky-mud-123456
ID             br-lucky-mud-123456
Current State  ready
Created At     2026-07-24T20:22:42Z

Compute
ID                    Created At
ep-mute-voice-123456  2026-07-24T20:22:42Z

Connection string
Connection URI
postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

**Tip:** The Neon CLI provides a `neon connection-string` command you can use to extract a connection uri programmatically. See [Neon CLI commands — connection-string](https://neon.com/docs/cli/connection-string).

Pass `--no-secrets` (Neon CLI 4.9.0+) to keep the connection string out of terminal scrollback and CI logs; older versions ignore it and still print it.

## Create a branch from a non-default parent

Using the option `--parent`, you can specify any non-default branch that you want to use as the parent for your new branch, depending on the needs of your development workflow.

In this example, we're creating a hotfix branch called `hotfix/critical-fix` using the `development` branch as the parent:

```bash
neon branches create --name hotfix/critical-fix --parent development --project-id crimson-voice-12345678
Branch
Name           hotfix/critical-fix
ID             br-misty-mud-123456
Current State  ready
Created At     2026-04-23T17:04:10Z

Compute
ID                      Created At
ep-orange-heart-123456  2026-04-23T17:04:10Z

Connection string
Connection URI
postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

## List branches with the CLI

The following Neon CLI command lists all branches in your Neon project, as well as any branches shared with you. This command requires specifying which project to use. You can use the `--project-id` option or set a default project using `neon set-context`. To view the CLI documentation for this method, refer to the [Neon CLI reference](https://neon.com/docs/cli/branches#list).

First, list your projects to get your project ID:

```bash
neon projects list
Projects
ID                      Name      Region ID      Created At
crimson-voice-12345678  frontend  aws-us-east-2  2026-04-15T11:17:30Z
calm-thunder-12121212   backend   aws-us-east-2  2026-04-10T15:21:01Z
nameless-hall-87654321  billing   aws-us-east-2  2026-04-10T14:35:17Z
Shared with you
ID                 Name  Region ID         Created At
noisy-fire-212121  API   aws-eu-central-1  2026-04-22T18:41:13Z
```

Now list your branches using your project ID:

```bash
neon branches list --project-id crimson-voice-12345678
Name                      ID                   Current State  Expires At  Created At
development               br-calm-sky-123456   ready          never       2026-04-23T21:05:05Z
[default] [current] main  br-bold-wind-123456  ready          never       2026-04-23T21:04:57Z
```

**Tip:** To avoid specifying `--project-id` with each command, use `neon set-context` to set your default project and organization. See [set-context](https://neon.com/docs/cli/set-context) for details.

## Delete a branch with the CLI

The following Neon CLI command deletes the specified branch. This command requires a `--project-id` option unless you've set a default project with `neon set-context`. To view the CLI documentation for this command, refer to the [Neon CLI reference](https://neon.com/docs/cli/branches#delete). You can delete a branch by its ID or name.

```bash
neon branches delete br-lucky-mud-123456 --project-id crimson-voice-12345678
Name           br-lucky-mud-123456
ID             br-lucky-mud-123456
Current State  ready
Created At     2026-07-24T20:22:42Z
```

## Branching automation with the Neon CLI

The Neon CLI enables easy automation of branching operations for integration into your workflows or toolchains. To authenticate to Neon when running a CLI command, you can use an API key. For information about obtaining an API key, see [Create an API key](https://neon.com/docs/manage/api-keys#create-an-api-key).

To use an API key, you can store it in an environment variable on your system. This prevents the key from being hardcoded into your automation scripts or exposed in another way. For example, you can add the following line to your shell's profile file (`.bashrc` or `.bash_profile` for bash shell):

```bash
export NEON_API_KEY=<neon_api_key>
```

After exporting your key, source the profile file (source `~/.bashrc` or source `~/.bash_profile`), or start a new terminal session.

You do not need to specify the variable name explicitly when using a Neon CLI command. A Neon CLI command looks for a `NEON_API_KEY` variable setting by default.

This API key configuration ensures that the API key is kept secure while still providing a way to authenticate your CLI commands. Remember, you should handle your API key with the same level of security as your other credentials.

## Branch expiration

For temporary environments, create branches with `--expires-at` to set a TTL for automatic deletion instead of manual cleanup:

```bash
# Create a branch that expires at a specific date and time
neon branches create --project-id <project-id> --name ci-test --parent <parent-branch> --expires-at "2025-07-15T18:02:16Z"

# Create a branch that expires in 2 hours (Linux/GNU)
neon branches create --project-id <project-id> --name ci-test --parent <parent-branch> --expires-at "$(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)"

# Create a branch that expires in 2 hours (macOS/BSD)
neon branches create --project-id <project-id> --name ci-test --parent <parent-branch> --expires-at "$(date -u -v+2H +%Y-%m-%dT%H:%M:%SZ)"
```

You can also update or remove expiration from existing branches:

```bash
# Update expiration to a new timestamp
neon branches set-expiration <branch-id> --expires-at "2025-07-20T12:00:00Z" --project-id <project-id>

# Remove expiration from a branch (omit --expires-at)
neon branches set-expiration <branch-id> --project-id <project-id>
```

For details and configuration instructions, refer to our [Branch expiration guide](https://neon.com/docs/guides/branch-expiration).

## Resetting a branch from its parent

Depending on your development workflow, you might need to periodically reset a branch to match the latest state of its parent. This is useful, for example, when resetting a development branch back to the production branch before starting work on a new feature.

Use the following command to reset a branch to the current state (HEAD) of its parent branch:

```bash
neon branches reset <id|name> --parent
```

Example:

This example resets a feature branch to match the latest state of its parent branch:

```bash
neon branches reset feature/user-auth --parent --project-id crimson-voice-12345678
Name           feature/user-auth
ID             br-twilight-smoke-123456
Current State  ready
Created At     2026-04-23T17:01:49Z
Last Reset At  2026-04-23T17:57:35Z
```

**Note:** **Branch expiration behavior:** When you reset a branch that has an expiration set, the expiration timer restarts from the reset time using the original duration. For example, if your branch was originally set to expire in 24 hours, resetting gives it another full 24 hours from the reset time. This process recalculates the new `expires_at` value using the preserved `ttl_interval_seconds`, but the TTL interval itself remains unchanged. For more details, see [branch expiration](https://neon.com/docs/guides/branch-expiration).

If the branch you want to reset has child branches, you need to include the `preserve-under-name` parameter. This will save the current state of your branch under a new name before performing the reset. The child branches will then show this newly named branch as their parent. This step ensures that your original branch can be reset cleanly, as all child branches will have been transferred to the new parent name.

For example, here we are resetting `feature/user-auth` to its parent while preserving its latest state under the branch name `feature/user-auth-backup`:

```bash
neon branches reset feature/user-auth --parent --preserve-under-name feature/user-auth-backup --project-id crimson-voice-12345678
Name           feature/user-auth
ID             br-twilight-smoke-123456
Current State  ready
Created At     2026-04-23T17:01:49Z
Last Reset At  2026-04-23T18:02:36Z
```

For more details, see [Reset from parent](https://neon.com/docs/guides/reset-from-parent).

## Restoring a branch to its own or another branch's history

Using the CLI, you can restore a branch to an earlier point in its history or another branch's history using the following command:

```bash
neon branches restore <target id|name> <source id|name @ timestamp|lsn>
```

This command restores the branch `production` to an earlier timestamp in its own history, saving to a backup branch called `production_restore_backup_2026-05-06`:

```bash
neon branches restore production ^self@2026-05-06T10:00:00.000Z --preserve-under-name production_restore_backup_2026-05-06 --project-id crimson-voice-12345678
```

Results of the operation:

```bash
Restoring production to production at timestamp 2026-05-06T10:00:00.000Z
Restored branch
ID             br-purple-dust-123456
Name           production
Last Reset At  2026-05-07T09:45:21Z

Backup branch
ID    br-flat-forest-123456
Name  production_restore_backup_2026-05-06
```

For full details about the different restore options available with this command, see [Restoring using the CLI](https://neon.com/docs/introduction/branch-restore#how-to-use-instant-restore).

--- [Document source](https://neon.com/docs/guides/branching-schema-only.md) ---

> Summary: Schema-only branches in Neon copy only the database structure from a source branch, leaving all row data behind, so teams can develop and test against production schemas without exposing confidential records. Use this feature when you need a compliant development or CI/CD environment with realistic table structure but no sensitive data, distinct from standard Neon branches that copy both schema and data via copy-on-write. Schema-only branches are independent root branches with plan-specific storage limits; reset-from-parent is not supported.

# Schema-only branches

Protect sensitive data with schema-only branches

Last updated: 2026-10-14

**Note: Beta**

This feature is in beta. Please give us [Feedback](https://console.neon.tech/app/projects?modal=feedback) from the Neon Console or by connecting with us on [Discord](https://neon.com/discord). For more ways to reach us, see [Send feedback](https://neon.com/docs/introduction/feedback).

Neon supports creating schema-only branches, letting you create branches that replicate only the database schema from a source branch, without copying any of the actual data. This feature is ideal for working with confidential information. Instead of duplicating this sensitive data, you can now create a branch with just the database structure and populate it with randomized or anonymized data instead. This provides your team with a secure and compliant environment for developing and testing using Neon branches.

## Creating schema-only branches

You can create schema-only branches in the Neon Console or using the Neon API, in much the same way you create any Neon branch. Support for the Neon CLI will come in a future release.

**Neon Console**

To create a schema-only branch from the Neon Console:

1. Select your project.
2. Select **Branches** in the sidebar.
3. Click **New branch** to open the branch creation dialog.
   ![Create branch dialog](https://neon.com/docs/guides/create_schema_only_branch.png)
4. Select a **Parent branch**. The schema from this branch will be copied to your new schema-only branch. By default, your project's default branch is selected, but you can choose any existing branch in your project.
5. Specify a branch name, or leave it blank to use the default generated name.
6. Select the **Schema only** option.
7. Configure auto-deletion: By default, **Automatically delete branch after** is checked with 1 day selected to help prevent unused branches from accumulating. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable expiration entirely. This is useful for CI/CD pipelines and short-lived development environments. Note: This default only applies when creating branches through the Console; API and CLI branches have no expiration by default. Refer to our [Branch expiration guide](https://neon.com/docs/guides/branch-expiration) for details.
8. Click **Create** to create your schema-only branch.

**CLI**

To create a schema-only branch using the Neon CLI:

```bash
neon branch create --schema-only
```

If you have more than one project, you'll need to specify the `--project-id` option. See [Neon CLI - branch create](https://neon.com/docs/cli/branches#create).

**API**

**Note:** The API is in beta and subject to change.

To create a schema-only branch using the Neon API, use the [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch) endpoint with the `init_source` option set to `schema-only`, as shown below. Required values include:

- Your Neon `project_id`
- The `parent_id`, which is the branch ID of the branch containing the schema you want to copy

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/wispy-salad-58347608/branches \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "branch": {
    "parent_id": "br-super-mode-w371g4od",
    "name": "my_schema_only_branch",
    "init_source": "schema-only"
  }
}
'
```

## Schema-only branching example

To try out schema-only branches:

1. Start by creating an `employees` table on your Neon project's `production` branch and adding some dummy data. You can do this from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any SQL client by copying and pasting the following statements:

   ```sql
   CREATE TABLE employees (
       employee_id SERIAL PRIMARY KEY,
       first_name VARCHAR(50),
       last_name VARCHAR(50),
       email VARCHAR(100),
       phone_number VARCHAR(15),
       job_title VARCHAR(50),
       salary NUMERIC(10, 2),
       hire_date DATE
   );

   INSERT INTO employees (first_name, last_name, email, phone_number, job_title, salary, hire_date) VALUES
   ('John', 'Doe', 'john.doe@example.com', '123-456-7890', 'Software Engineer', 95000.00, '2020-01-15'),
   ('Jane', 'Smith', 'jane.smith@example.com', '987-654-3210', 'Product Manager', 110000.00, '2019-03-22'),
   ('Alice', 'Johnson', 'alice.johnson@example.com', '555-123-4567', 'HR Specialist', 65000.00, '2021-06-10'),
   ('Bob', 'Brown', 'bob.brown@example.com', '555-987-6543', 'Data Analyst', 78000.00, '2018-09-05'),
   ('Charlie', 'Davis', 'charlie.davis@example.com', '444-555-6666', 'Marketing Manager', 95000.00, '2017-11-14'),
   ('Diana', 'Miller', 'diana.miller@example.com', '333-444-5555', 'Sales Representative', 72000.00, '2022-04-18'),
   ('Edward', 'Wilson', 'edward.wilson@example.com', '222-333-4444', 'DevOps Engineer', 98000.00, '2020-12-03'),
   ('Fiona', 'Clark', 'fiona.clark@example.com', '111-222-3333', 'UI/UX Designer', 85000.00, '2016-08-29'),
   ('George', 'Harris', 'george.harris@example.com', '999-888-7777', 'Financial Analyst', 90000.00, '2021-01-11'),
   ('Hannah', 'Martin', 'hannah.martin@example.com', '888-777-6666', 'Backend Developer', 92000.00, '2019-07-23');
   ```

2. Navigate to the **Tables** page in the Neon Console, and select your `production` branch from the bread-crumb menu at the top of the console. Your `employees` table will have both schema and data, as shown here:

   ![production branch with schema and data](https://neon.com/docs/guides/schema-data-branch.png)

3. Create a schema-only branch following the instructions above. See [Creating schema-only branches](https://neon.com/docs/guides/branching-schema-only#creating-schema-only-branches). In this example, we've named the branch `employees_schema_only`.

   ![schema-only branch creation](https://neon.com/docs/guides/create_schema_only_branch.png)

4. On the **Tables** page, select your newly created `employees_schema_only` branch from the bread-crumb menu at the top of the console. You can see that the schema-only branch contains the schema, but no data. The same will be true for any table in any database on the schema-only branch; only the schema will be present.

   ![schema-only branch with only the schema](https://neon.com/docs/guides/schema-only-branch.png)

## Connect to a schema-only branch

Connecting to a schema-only branch works the same way as connecting to any Neon branch. You'll connect via a compute associated with the branch. Follow these steps to connect using `psql` and a connection string obtained from the Neon Console.

1. In the Neon Console, select a project.
2. In the Neon Console, click **Connect**, and select your schema-only branch, the database, and the role you want to connect with.
   ![Connection details modal](https://neon.com/docs/guides/schema_only_branch_connect.png)
3. Copy the connection string. A connection string includes your role name, the compute hostname, and the database name.

   ```bash
   postgresql://[user]:[password]@[neon_hostname]/[dbname]
   ```

## What's different about schema-only branches?

Unlike other branches, schema-only branches do not have a parent branch, as you can see below. Both the `production` branch of the project and the schema-only branch have no parent, indicated by the dash in the **Parent** column (`-`) on the **Branches** page in your Neon project.

![schema-only branch](https://neon.com/docs/guides/schema_only_no_parent.png)

Schema-only branches are independent [root branches](https://neon.com/docs/reference/glossary#root-branch), just like the `production` branch in your Neon project. When you create a schema-only branch, you're creating a new **root branch**.

### Key points about schema-only branches

- **No parent branch**: Schema-only branches are root branches. They do not have a parent branch.
- **No shared history**: Data added to a schema-only branch is independent and adds to your storage. There is no shared history with a parent.
- **Reset from parent is not supported**: With no parent branch, [reset from parent](https://neon.com/docs/manage/branches#reset-a-branch-from-parent) operations are not supported.
- **Restore is supported, but...** performing a [restore](https://neon.com/docs/guides/branch-restore) operation on a schema-only branch copies both schema and data from the source branch.
- **Branch protection is supported**: Like any other branch, you can enable [branch protection](https://neon.com/docs/guides/protected-branches) for schema-only branches.

## Schema-only branch allowances

There are certain allowances associated with schema-only branches:

- A schema-only branch is a [root branch](https://neon.com/docs/reference/glossary#root-branch), and only a certain number of root branches are permitted per Neon project, depending on your Neon plan.
- The `main` root branch created with each Neon project counts toward the _root branch allowance per project_, as do certain [backup branches](https://neon.com/docs/reference/glossary#backup-branch) created by restore operations.
- On the Free plan, all branches in a project share a total storage limit of 1 GB. Schema-only branches count toward this limit like any other branch. On paid plans, ordinary branch storage is unlimited, but each schema-only branch has its own maximum storage allowance, as outlined in the following table. These allowances apply only to schema-only branches; they are not a general storage cap.

| Plan   | Root branch allowance per project | Maximum storage allowance per schema-only branch |
| :----- | :-------------------------------- | :----------------------------------------------- |
| Free   | 3                                 | 1 GB                                             |
| Launch | 5                                 | 3 GB                                             |
| Scale  | 25                                | 20 GB                                            |

Once you use up your root branch allowance, you will not be able to create additional schema-only branches. You will be required to remove existing root branches first.

--- [Document source](https://neon.com/docs/guides/branching-test-queries.md) ---

> Summary: Neon branching lets you create an instant copy-on-write clone of your production database to safely run destructive or schema-altering queries before they touch live data. Use this page when you need to test a DELETE, UPDATE, or DDL statement against real production data without risk of data loss. The guide covers creating a test branch via the Neon Console, CLI, or API; running queries in the SQL Editor; and deleting the branch when done.

# Branching — Testing queries

Create a Neon branch to test queries before running them in production

Last updated: 2026-10-09

Complex queries that modify data or alter schemas have the potential to be destructive. It is advisable to test these types of queries before running them in production. On other database systems, testing potentially destructive queries can be time and resource intensive. For example, testing may involve setting up a separate database instance and replicating data. With Neon, you can instantly create a database branch with a full copy-on-write clone of your production data in just a few clicks. When you finish testing, you can remove the branch just as easily.

**Tip: working with sensitive data?**

Neon also supports schema-only branching. [Learn more](https://neon.com/docs/guides/branching-schema-only).

This guide walks you through creating a branch of your production data, testing a potentially destructive query, and deleting the branch when you are finished.

1. [Create a test branch](https://neon.com/docs/guides/branching-test-queries#create-a-test-branch)
2. [Test your query](https://neon.com/docs/guides/branching-test-queries#test-your-query)
3. [Delete the test branch](https://neon.com/docs/guides/branching-test-queries#delete-the-test-branch)

For the purpose of this guide, let's assume you have a database in Neon with the following table and data:

```sql
CREATE TABLE Post (
    id INT PRIMARY KEY,
    title VARCHAR(255),
    content TEXT,
    author_name VARCHAR(100),
    date_published DATE
);
```

```sql
INSERT INTO Post (id, title, content, author_name, date_published)
VALUES
(1, 'My first post', 'This is the content of the first post.', 'Alice', '2023-01-01'),
(2, 'My second post', 'This is the content of the second post.', 'Alice', '2023-02-01'),
(3, 'Old post by Bob', 'This is an old post by Bob.', 'Bob', '2020-01-01'),
(4, 'Recent post by Bob', 'This is a recent post by Bob.', 'Bob', '2023-06-01'),
(5, 'Another old post', 'This is another old post.', 'Alice', '2019-06-01');
```

## Create a test branch

1. In the Neon Console, select your project.
2. Select **Branches** in the sidebar.
3. Click **New Branch** to open the branch creation dialog.
   ![Create branch dialog](https://neon.com/docs/manage/create_branch.png)
4. Enter a name for the branch. This guide uses the name `my_test_branch`.
5. Select a parent branch. Select the branch defined as your default branch, such as production or main.
6. By default, the branch is created with the latest available data from the parent branch.
7. Click **Create** to create your branch.

You are directed to the connection details for the branch, and then the **Branches** page where you are shown the details for your new branch.

You can also create a test branch using the [Neon CLI](https://neon.com/docs/cli/branches#create) or [Neon API](https://neon.com/docs/manage/branches#create-a-branch-with-the-api).

**CLI**

```bash
neon branches create --project-id <project-id> --name my_test_branch
```

**API**

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/<project-id>/branches \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "branch": {
    "name": "my_test_branch"
  }
}
' | jq
```

## Test your query

Navigate to **Postgres database** > **SQL Editor**, select the test branch, and run your query. For example, perhaps you are deleting blog posts from your database for a certain author published before a certain date, and you want to make sure the query only removes the intended records.

```sql
DELETE FROM Post
WHERE author_name = 'Alice' AND date_published < '2020-01-01';
```

Next, inspect the data to ensure the intended records were deleted, while others remained unaffected. This query allows you to quickly see if the number of records matches your expectations:

```sql
SELECT COUNT(*) FROM Post;
```

Before the `DELETE` query, there were 5 records. If the query ran correctly, this should now show 4.

## Delete the test branch

When you finish testing your query, you can delete the test branch:

1. In the Neon Console, select a project.
2. Select **Branches** in the sidebar.
3. Select the test branch from the table.
4. From the three-dot menu (⋮) on the branch overview page, select **Delete**.

You can also delete a branch using the [Neon CLI](https://neon.com/docs/cli/branches#delete) or [Neon API](https://neon.com/docs/manage/branches#delete-a-branch-with-the-api).

**CLI**

```bash
neon branches delete my_test_branch
```

**API**

```bash
curl --request DELETE \
     --url https://console.neon.tech/api/v2/projects/<project-id>/branches/<branch-id> \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" | jq
```

--- [Document source](https://neon.com/docs/guides/bun.md) ---

> Summary: Connecting a Bun application to a Lakebase Postgres database requires either Bun's built-in `sql` client (no extra dependencies) or the `@neondatabase/serverless` driver installed via `bun add`. Choose this page when setting up Bun, Hono, or Elysia with Lakebase Postgres, covering project creation, `POSTGRES_URL` credential storage in `.env.local`, and a working TypeScript query to verify the connection.

# Connect a Bun application to Neon

Set up a Neon project in seconds and connect from a Bun application

Last updated: 2026-09-16

This guide describes how to create a project on Neon and connect to it from a Bun application. Examples are provided for using [Bun's built-in SQL client](https://bun.sh/docs/api/sql) and the [@neondatabase/serverless](https://neon.com/docs/serverless/serverless-driver) driver. Use the client you prefer.

**Note:** The same configuration steps can be used for [Hono](https://hono.dev/docs/getting-started/bun), [Elysia](https://elysiajs.com), and other Bun-based web frameworks.

## Create a project on Neon

If you do not have one already, create a project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Bun project and add dependencies

Create a Bun project and change to the newly created directory:

```shell
mkdir bun-neon-example
cd bun-neon-example
bun init -y
```

Next, add project dependencies if you intend to use the Neon serverless driver. Otherwise, Bun's built-in `sql` client is readily available.

**Bun.sql**

```shell
# No dependencies needed for Bun's built-in SQL client
```

**Neon serverless driver**

```shell
bun add @neondatabase/serverless
```

## Store your Neon credentials

Add a `.env.local` file to your project directory and add your Neon connection details to it. Bun automatically loads variables from `.env`, `.env.local`, and other `.env.*` files. You can find the connection details for your database by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select Bun from the **Connection string** dropdown. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
POSTGRES_URL='postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require'
```

**Note:** `Bun.sql` reads the connection string from `POSTGRES_URL` by default (it also checks `DATABASE_URL`), so you don't need to pass it in code.

**Important:** To ensure the security of your data, never expose your Neon credentials directly in your code or commit them to version control.

## Configure the Postgres client

`bun init` creates an `index.ts` file in your project directory. Replace its contents with the following code to connect to your Neon database. Choose the configuration that matches your preferred client.

**Bun.sql**

```typescript
import { sql } from 'bun';

async function getPgVersion() {
  const result = await sql`SELECT version()`;
  console.log(result[0]);
}

getPgVersion();
```

**Neon serverless driver**

```typescript
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.POSTGRES_URL!);

async function getPgVersion() {
  const result = await sql`SELECT version()`;
  console.log(result[0]);
}

getPgVersion();
```

## Run index.ts

Run `bun run index.ts` to view the result.

```shell
$ bun run index.ts
{
  version: "PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit",
}
```

## References

- [Bun SQL client](https://bun.sh/docs/api/sql)
- [@neondatabase/serverless driver](https://neon.com/docs/serverless/serverless-driver)

--- [Document source](https://neon.com/docs/guides/cloudflare-hyperdrive.md) ---

> Summary: Cloudflare Hyperdrive proxies and accelerates Lakebase Postgres queries from Cloudflare Workers by routing requests through a globally distributed connection pool, reducing per-request connection latency for serverless workloads. Use this guide when you need to connect a Workers application (node-postgres or postgres.js) to Neon via Hyperdrive, including Wrangler binding setup and worker placement by region. Covers the sslmode=disable behavior in Hyperdrive local connection strings and how to test with wrangler dev --remote.

# Use Neon with Cloudflare Hyperdrive

Connect Cloudflare Hyperdrive to your Lakebase Postgres database for faster queries

Last updated: 2026-10-09

[Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/) is a serverless application that proxies queries to your database and accelerates them. It works by maintaining a globally distributed pool of database connections, and routing queries to the closest available connection.

This is specifically useful for serverless applications that cannot maintain a persistent database connection and need to establish a new connection for each request. Hyperdrive can significantly reduce the latency of these queries for your application users.

This guide demonstrates how to configure a Hyperdrive service to connect to your Lakebase Postgres database. It demonstrates how to implement a regular `Workers` application that connects to Neon directly and then replace that connection with a `Hyperdrive` connection to achieve performance improvements.

## Prerequisites

To follow along with this guide, you require:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.

- A Cloudflare account. If you do not have one, sign up for [Cloudflare Workers](https://workers.cloudflare.com/) to get started.

  **NOTE**: You need to be on Cloudflare Workers' paid subscription plan to use Hyperdrive.

- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and deploy our Workers application.

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.

2. Click the **New Project** button to create a new project.

3. In the Neon Console, navigate to **Postgres database** > **SQL Editor** from the sidebar, and run the following SQL command to create a new table in your database:

   ```sql
   CREATE TABLE books_to_read (
    id SERIAL PRIMARY KEY,
    title TEXT,
    author TEXT
   );
   ```

   Next, we insert some sample data into the `books_to_read` table, so we can query it later:

   ```sql
   INSERT INTO books_to_read (title, author)
   VALUES
       ('The Way of Kings', 'Brandon Sanderson'),
       ('The Name of the Wind', 'Patrick Rothfuss'),
       ('Coders at Work', 'Peter Seibel'),
       ('1984', 'George Orwell');
   ```

### Retrieve your Neon database connection string

In the Neon Console, click **Connect** in the nav to open the **Connect to your branch** modal and find your database connection string. It should look similar to this:

```bash
postgresql://neondb_owner:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

## Setting up your Cloudflare Workers application

### Create a new Worker project

Run the following command in a terminal window to set up a new Cloudflare Workers project:

```bash
npm create cloudflare@latest
```

This initiates an interactive CLI prompt to generate a new project. To follow along with this guide, you can use the following settings:

```bash
├ In which directory do you want to create your application?
│ dir ./neon-hyperdrive-guide
│
├ What type of application do you want to create?
│ type "Hello World" Worker
│
├ Do you want to use TypeScript?
│ Yes typescript
```

When asked if you want to deploy your application, select `no`. We'll develop and test the application locally before deploying it to the Cloudflare Workers platform.

The `create-cloudflare` CLI also installs the `Wrangler` tool to manage the full workflow of testing and managing your Worker applications. To emulate the Node environment in the Workers runtime, we need to add the following entry to the `wrangler.toml` file.

```toml
#:schema node_modules/wrangler/config-schema.json
name = "with-hyperdrive"
main = "src/index.ts"
compatibility_date = "2024-12-05"
compatibility_flags = ["nodejs_compat"]
```

### Implement the Worker script

Navigate to the project directory and run the following command:

**node-postgres**

```bash
npm install pg
npm install -D @types/pg
```

**postgres.js**

```bash
npm install postgres
```

Now, you can update the `src/index.js` file in the project directory with the following code:

**node-postgres**

```javascript
import pkg from 'pg';

const { Client } = pkg;

export default {
  async fetch(request, env, ctx) {
    const client = new Client({ connectionString: env.DATABASE_URL });
    await client.connect();
    const { rows } = await client.query('SELECT * FROM books_to_read');
    return new Response(JSON.stringify(rows));
  },
};
```

**postgres.js**

```javascript
import postgres from 'postgres';

export default {
  async fetch(request, env, ctx) {
    const sql = postgres(env.DATABASE_URL);
    const rows = await sql`SELECT * FROM books_to_read`;
    return new Response(JSON.stringify(rows));
  },
};
```

The `fetch` handler defined above gets called when the worker receives an HTTP request. It will query the Neon database to fetch the full list of books in our to-read list.

### Test the worker application locally

First, you need to configure the `DATABASE_URL` environment variable to point to the Neon database. You can do this by creating a `.dev.vars` file at the root of the project directory with the following content:

```text
DATABASE_URL=YOUR_NEON_CONNECTION_STRING
```

Now, to test the worker application locally, you can use the `wrangler` CLI which comes with the Cloudflare project setup.

```bash
npx wrangler dev
```

This command starts a local server and simulates the Cloudflare Workers environment. You can visit the printed URL in your browser to test the worker application. It should return a JSON response with the list of books from the `books_to_read` table.

## Setting up Cloudflare Hyperdrive

With our Workers application able to query the database, we will now set up Cloudflare Hyperdrive to connect to Neon and accelerate the database queries.

### Create a new Hyperdrive service

You can use the `Wrangler` CLI to create a new Hyperdrive service, using your Neon database connection string from earlier:

```bash
npx wrangler hyperdrive create neon-guide-drive --connection-string=$NEON_DATABASE_CONNECTION_STRING
```

This command creates a new Hyperdrive service named `neon-guide-drive` and outputs its configuration details. Copy the `id` field from the output, which we will use next.

### Bind the Worker project to Hyperdrive

Cloudflare workers uses `Bindings` to interact with other resources on the Cloudflare platform. We will update the `wrangler.toml` file in the project directory to bind our Worker project to the Hyperdrive service.

Add the following lines to the `wrangler.toml` file. This lets us access the Hyperdrive service from our Worker application using the `HYPERDRIVE` binding.

```toml
[[hyperdrive]]
binding = "HYPERDRIVE"
id = $id-from-previous-step
```

### Update the Worker script to use Hyperdrive

Now, you can update the `src/index.js` file in the project directory to query the database, through the Hyperdrive service.

**node-postgres**

```javascript
import pkg from 'pg';

const { Client } = pkg;

export default {
  async fetch(request, env, ctx) {
    const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
    await client.connect();
    const { rows } = await client.query('SELECT * FROM books_to_read');
    return new Response(JSON.stringify(rows));
  },
};
```

**postgres.js**

```javascript
import postgres from 'postgres';

export default {
  async fetch(request, env, ctx) {
    const sql = postgres(env.HYPERDRIVE.connectionString);
    const rows = await sql`SELECT * FROM books_to_read`;
    return new Response(JSON.stringify(rows));
  },
};
```

### Optimize Worker placement

By default, Workers run in the data center closest to where the request was received. If your Worker makes multiple round trips to your database, you can reduce latency by placing the Worker closer to your database instead.

You can specify the cloud region where your database is hosted by adding a placement in your `wrangler.toml`. For example, if your database is in AWS US East 1:

```toml
[placement]
region = "aws:us-east-1"
```

Or if your database is in Azure Germany West Central:

```toml
[placement]
region = "azure:germanywestcentral"
```

### Deploy the updated Worker

Now that we have updated the Worker script to use the Hyperdrive service, we can deploy the updated Worker to the Cloudflare Workers platform:

```bash
npx wrangler deploy
```

This command uploads the updated Worker script to the Cloudflare Workers platform and makes it available at a public URL. You can visit the URL in your browser to test that the application works.

## Removing the example application and Neon project

To delete your Worker project, you can use the Cloudflare dashboard or run `wrangler delete` from your project directory, specifying your project name. Refer to the [Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/commands/#delete-3) for more details.

To delete your Neon project, follow the steps outlined in the Neon documentation under [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

## Example application

- [Neon + Cloudflare Hyperdrive](https://github.com/neondatabase/examples/tree/main/with-hyperdrive): Demonstrates using Cloudflare's Hyperdrive to access your Neon database from Cloudflare Workers

## Why sslmode=disable appears in Hyperdrive URLs

If you're using [Postgres.js](https://github.com/porsager/postgres) (or another library that requires SSL) with Neon and Hyperdrive, you might see an error like:

```text
PostgresError: connection is insecure (try using sslmode=require)
```

This happens because the local connection string generated by Hyperdrive includes `sslmode=disable`. While this may look insecure, it's by design and your database connection is still secure:

- Hyperdrive terminates SSL inside Cloudflare's infrastructure.
- Your Worker connects to Hyperdrive over an internal `.hyperdrive.local` address; no SSL needed.
- Hyperdrive then connects to your database using the original connection string with `sslmode=require`, maintaining full SSL encryption upstream.

**Connection path:**

```text
Worker → Hyperdrive (.hyperdrive.local, no SSL)
Hyperdrive → Neon Database (SSL enabled)
```

This setup works in production. But for local development, libraries like Postgres.js may still reject the connection due to the local `sslmode=disable`.

✅ **To avoid this issue locally**, use `wrangler dev --remote`. This runs your Worker in Cloudflare's infrastructure, where the connection string works as expected.

## Resources

- [Cloudflare Workers](https://workers.cloudflare.com/)
- [Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/)
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
- [Neon](https://neon.tech)

--- [Document source](https://neon.com/docs/guides/cloudflare-pages.md) ---

> Summary: Lakebase Postgres integration with Cloudflare Pages uses the Neon serverless driver (@neondatabase/serverless) inside Cloudflare Functions to query a Postgres database from the edge. Use this guide when you need server-side database access in a Cloudflare Pages app and want to avoid traditional connection pooling that does not work in Workers. Covers React/Vite project setup, Cloudflare Functions in the functions/ directory, local testing with Wrangler, and adding DATABASE_URL as a Cloudflare environment variable for production deployment.

# Use Neon with Cloudflare Pages

Connect a Lakebase Postgres database to your Cloudflare Pages web application

Last updated: 2026-10-09

**Note:** Cloudflare recommends Workers for new projects. To build a new app, see [Use Neon with Cloudflare Workers](https://neon.com/docs/guides/cloudflare-workers). This guide still applies to existing Cloudflare Pages projects.

`Cloudflare Pages` is a modern web application hosting platform that allows you to build, deploy, and scale your web applications. While it is typically used to host static websites, you can also use it to host interactive web applications by leveraging `functions` to run server-side code. Internally, Cloudflare functions are powered by `Cloudflare Workers`, a serverless platform that allows you to run JavaScript code on Cloudflare's edge network.

This guide demonstrates how to connect to a Lakebase Postgres database from your Cloudflare Pages application. We'll create a simple web application using `React` that tracks our reading list using the database and provides a form to add new books to it.

We'll use the Neon serverless driver to connect to the database and make queries.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- A Cloudflare account. If you do not have one, sign up for [Cloudflare Pages](https://pages.cloudflare.com/) to get started.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and deploy our `Pages` application.

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.

2. Click the **New Project** button to create a new project.

3. In the Neon Console, navigate to **Postgres database** > **SQL Editor** from the sidebar, and run the following SQL command to create a new table in your database:

   ```sql
   CREATE TABLE books_to_read (
       id SERIAL PRIMARY KEY,
       title TEXT,
       author TEXT
   );
   ```

   Next, we insert some sample data into the `books_to_read` table, so we can query it later:

   ```sql
   INSERT INTO books_to_read (title, author)
   VALUES
       ('The Way of Kings', 'Brandon Sanderson'),
       ('The Name of the Wind', 'Patrick Rothfuss'),
       ('Coders at Work', 'Peter Seibel'),
       ('1984', 'George Orwell');
   ```

### Retrieve your Neon database connection string

In the Neon Console, click **Connect** in the nav to open the **Connect to your branch** modal to find your database connection string. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

## Setting up your Cloudflare Pages project

### Create a new project

We will create a simple React application using the Vite bundler framework. Run the following command in a terminal window to set up a new Vite project:

```bash
npm create vite@latest
```

This initiates an interactive CLI prompt to generate a new project. To follow along with this guide, you can use the following settings:

```bash
✔ Project name: … my-neon-page
✔ Select a framework: ' React
✔ Select a variant: ' JavaScript

Scaffolding project in /Users/ishananand/repos/javascript/my-neon-page...

Done. Now run:

  cd my-neon-page
  npm install
  npm run dev
```

We set up a template React configured to be built using Vite.

### Implement the application frontend

Navigate to the `my-neon-page` directory and open the `src/App.jsx` file. Replace the contents of this file with the following code:

```jsx
// src/App.jsx

import React, { useState, useEffect } from 'react';

function App() {
  const [books, setBooks] = useState([]);
  const [bookName, setBookName] = useState('');
  const [authorName, setAuthorName] = useState('');

  // Function to fetch books
  const fetchBooks = async () => {
    try {
      const response = await fetch('/books');
      const data = await response.json();
      setBooks(data);
    } catch (error) {
      console.error('Error fetching books:', error);
    }
  };

  useEffect(() => {
    fetchBooks();
  }, []);

  const handleSubmit = async (event) => {
    event.preventDefault();
    try {
      const response = await fetch('/books/add', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ title: bookName, author: authorName }),
      });
      const data = await response.json();

      if (data.success) {
        console.log('Success:', data);
        setBooks([...books, { title: bookName, author: authorName }]);
      } else {
        console.error('Error adding book:', data.error);
      }
    } catch (error) {
      console.error('Error:', error);
    }

    // Reset form fields
    setBookName('');
    setAuthorName('');
  };

  return (
    <div className="App">
      <h1>Book List</h1>
      <ul>
        {books.map((book, index) => (
          <li key={index}>
            {book.title} by {book.author}
          </li>
        ))}
      </ul>

      <h2>Add a Book</h2>
      <form onSubmit={handleSubmit}>
        <label>
          Book Name:
          <input type="text" value={bookName} onChange={(e) => setBookName(e.target.value)} />
        </label>
        <label>
          Author Name:
          <input type="text" value={authorName} onChange={(e) => setAuthorName(e.target.value)} />
        </label>
        <button type="submit">Add Book</button>
      </form>
    </div>
  );
}

export default App;
```

The `App` component fetches the list of books from the server and displays them. It also provides a form to add new books to the list. `Cloudflare` Pages allows us to define the API endpoints as serverless functions, which we'll implement next.

### Implement the serverless functions

We'll use the Neon serverless driver to connect to the database, so we first need to install it as a dependency:

```bash
npm install @neondatabase/serverless
```

Next, we'll create two serverless functions for the application. In a `Cloudflare Pages` project, these must be defined in the `functions` directory at the root of the project. For further details, refer to the [Cloudflare Pages - Functions documentation](https://developers.cloudflare.com/pages/functions/).

#### Function to fetch list of books from the database

Create a new file named `functions/books/index.js` in the project directory with the following content:

```js
import { Client } from '@neondatabase/serverless';

export async function onRequestGet(context) {
  const client = new Client(context.env.DATABASE_URL);
  await client.connect();

  // Logic to fetch books from your database
  const { rows } = await client.query('SELECT * FROM books_to_read;');
  return new Response(JSON.stringify(rows));
}
```

This function fetches the list of books from the `books_to_read` table in the database and returns it as a JSON response.

#### Function to add a new book to the database

Create another file named `functions/books/add.js` in the project directory with the following content:

```js
import { Client } from '@neondatabase/serverless';

export async function onRequestPost(context) {
  const client = new Client(context.env.DATABASE_URL);
  await client.connect();

  // Extract the book details from the request body
  const book = await context.request.json();

  // Logic to insert a new book into your database
  const resp = await client.query('INSERT INTO books_to_read (title, author) VALUES ($1, $2); ', [
    book.title,
    book.author,
  ]);

  // Check if insert query was successful
  if (resp.rowCount === 1) {
    return new Response(JSON.stringify({ success: true, error: null, data: book }), {
      headers: { 'Content-Type': 'application/json' },
    });
  } else {
    return new Response(
      JSON.stringify({
        success: false,
        error: 'Failed to insert book',
        data: book,
      }),
      {
        headers: { 'Content-Type': 'application/json' },
        status: 500,
      }
    );
  }
}
```

This function extracts the book details from the request body and inserts it into the `books_to_read` table in the database. It returns a JSON response indicating the success or failure of the operation.

### Test the application locally

Our application is now ready to be tested locally. However, we first need to configure the `DATABASE_URL` environment variable to point to our database.

We can do this by creating a `.dev.vars` file at the root of the project directory with the following content:

```text
DATABASE_URL=YOUR_NEON_CONNECTION_STRING
```

Now, to test the `Pages` application locally, we can use the `wrangler` CLI tool used to manage Cloudflare projects. We can use it using the `npx` command as:

```bash
npx wrangler pages dev -- npm run dev
```

This command starts a local server simulating the Cloudflare environment. The function endpoints are run by the Wrangler tool while requests to the root URL are proxied to the Vite development server.

```bash
❯ npx wrangler pages dev -- npm run dev
Running npm run dev...
.
.
.
.
-------------------
Using vars defined in .dev.vars
Your worker has access to the following bindings:
- Vars:
  - DATABASE_URL: "(hidden)"
⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8788
```

Visit the printed localhost URL in your browser to interact with the application. You should see the list of books fetched from the database and a form to add new books.

## Deploying your application with Cloudflare Pages

### Authenticate Wrangler with your Cloudflare account

Run the following command to link the Wrangler tool to your Cloudflare account:

```bash
npx wrangler login
```

This command will open a browser window and prompt you to log into your Cloudflare account. After logging in and approving the access request for `Wrangler`, you can close the browser window and return to your terminal.

### Publish your Pages application and verify the deployment

Now, you can deploy your application to `Cloudflare Pages` by running the following command:

```bash
npm run build
npx wrangler pages deploy dist --project-name <NAME_OF_YOUR_PROJECT>
```

Give a unique name to your `Cloudflare Pages` project above. The Wrangler CLI will output the URL of your application hosted on the Cloudflare platform. Visit this URL in your browser to interact with it.

```bash
✨ Compiled Worker successfully
🌍  Uploading... (4/4)

✨ Success! Uploaded 0 files (4 already uploaded) (0.72 sec)

✨ Uploading Functions bundle
✨ Deployment complete! Take a peek over at https://21ea2a57.my-neon-page.pages.dev
```

### Add your Neon connection string as an environment variable

The Cloudflare production deployment doesn't have access to the `DATABASE_URL` environment variable yet. Hence, we need to navigate to the Cloudflare dashboard and add it manually.

Navigate to the dashboard and select the `Settings` section in your project. Go to the **Environment Variables** tab and add a new environment variable named `DATABASE_URL` with the value of your Neon database connection string.

To make sure the environment variable is available to the serverless functions, go back to the terminal and redeploy the project using the `wrangler` CLI:

```bash
npx wrangler pages deploy dist --project-name <NAME_OF_YOUR_PROJECT>
```

Now, visit the URL of your `Cloudflare Pages` application to interact with it. You should see the list of books fetched from the database and a form to add new books.

## Removing the example application and Neon project

To delete your `Cloudflare Pages` application, you can use the Cloudflare dashboard. Refer to the [Pages documentation](https://developers.cloudflare.com/pages) for more details.

To delete your Neon project, follow the steps outlined in the Neon documentation under [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

## Resources

- [Cloudflare Pages](https://pages.cloudflare.com/)
- [Cloudflare Pages - Documentation](https://developers.cloudflare.com/pages/)
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
- [Neon](https://neon.tech)

--- [Document source](https://neon.com/docs/guides/cloudflare-r2.md) ---

> Summary: Cloudflare R2 file storage paired with Neon gives you S3-compatible object storage with zero egress fees while keeping structured file metadata (object key, public URL, user ID, upload timestamp) in a Lakebase Postgres table. Use this guide when you need a split-storage architecture where R2 holds blobs and Neon holds queryable metadata, using presigned upload URLs to let clients upload directly without routing files through your backend. Covers bucket setup, CORS configuration, metadata schema, and backend endpoints in JavaScript (Hono, @aws-sdk/client-s3) and Python (Flask, boto3, psycopg2).

# File storage with Cloudflare R2

Store files via Cloudflare R2 and track metadata in Lakebase

Last updated: 2026-09-16

[Cloudflare R2](https://www.cloudflare.com/en-in/developer-platform/products/r2/) is S3-compatible object storage offering zero egress fees, designed for storing and serving large amounts of unstructured data like images, videos, and documents globally.

**Neon now offers native storage:**

Neon Object Storage is S3-compatible object storage built into the Neon backend. Object storage branches with your database: each branch gets its own isolated namespace, so you can test file uploads in preview branches without touching production. No separate cloud account needed. Use any S3-compatible SDK with your existing Neon credential.

For more information, see [Neon Object Storage](https://neon.com/docs/storage/overview).

This guide demonstrates how to integrate Cloudflare R2 with Neon by storing file metadata in your database, while using R2 for file storage.

## Setup steps

## Create a Neon project

1. Navigate to the [Neon Console](https://console.neon.tech) to create a new Neon project.
2. Copy the connection string by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Create a Cloudflare account and R2 bucket

1. Sign up for or log in to your [Cloudflare account](https://dash.cloudflare.com/sign-up/r2).
2. Navigate to **R2** in the Cloudflare dashboard sidebar.
3. Click **Create bucket**, provide a unique bucket name (for example, `my-neon-app-files`), and click **Create bucket**.
   ![Create R2 Bucket](https://neon.com/docs/guides/cloudflare-r2-create-bucket.png)
4. Generate R2 API credentials (**Access Key ID** and **Secret Access Key**) by following [Create an R2 API Token](https://developers.cloudflare.com/r2/api/tokens/). Select **Object Read & Write** permissions. Copy these credentials securely.
5. Obtain your Cloudflare **Account ID** by following [Find your Account ID](https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/#find-your-account-id).
6. For this example, enable public access to your bucket URL by following [Allow public access to your bucket](https://developers.cloudflare.com/r2/buckets/public-buckets/#enable-managed-public-access). Note your bucket's public URL (for example, `https://pub-xxxxxxxx.r2.dev`).

   **Note: Public access**

   Public access makes all objects readable via URL; consider private buckets and signed URLs for sensitive data in production.

## Configure CORS for client-side uploads

If your application involves uploading files **directly from a web browser** using the generated presigned URLs, you must configure Cross-Origin Resource Sharing (CORS) on your R2 bucket. CORS rules tell R2 which web domains are allowed to make requests (like `PUT` requests for uploads) to your bucket. Without proper CORS rules, browser security restrictions will block these direct uploads.

Follow Cloudflare's guide to [Configure CORS](https://developers.cloudflare.com/r2/buckets/cors/) for your bucket. You can add rules via R2 Bucket settings in the Cloudflare dashboard.

Here's an example CORS configuration allowing `PUT` uploads and `GET` requests from your deployed frontend application and your local development environment:

```json
[
  {
    "AllowedOrigins": [
      "https://your-production-app.com", // Replace with your actual frontend domain
      "http://localhost:3000" // For local development
    ],
    "AllowedMethods": ["PUT", "GET"]
  }
]
```

## Create a table in Neon for file metadata

We need a table in the database to store metadata about the objects uploaded to R2.

1. Connect to your database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a client like [psql](https://neon.com/docs/connect/query-with-psql-editor). Here is an example SQL statement to create a simple table including the object key, URL, user ID, and timestamp:

   ```sql
   CREATE TABLE IF NOT EXISTS r2_files (
       id SERIAL PRIMARY KEY,
       object_key TEXT NOT NULL UNIQUE, -- Key (path/filename) in R2
       file_url TEXT NOT NULL,          -- Publicly accessible URL
       user_id TEXT NOT NULL,           -- User associated with the file
       upload_timestamp TIMESTAMPTZ DEFAULT NOW()
   );
   ```

2. Run the SQL statement. You can add other relevant columns (file size, content type, etc.) depending on your application needs.

**Note: Securing metadata with RLS**

If you use [Neon's Row Level Security (RLS)](https://neon.com/blog/introducing-neon-authorize), remember to apply appropriate access policies to the `r2_files` table. This controls who can view or modify the object references stored in Neon based on your RLS rules.

Note that these policies apply _only_ to the metadata in Neon. Access control for the objects within the R2 bucket itself is managed via R2 permissions, API tokens, and presigned URL settings if used.

## Upload files to R2 and store metadata in Neon

A common pattern with S3-compatible storage like R2 involves **presigned upload URLs**. Your backend generates a temporary, secure URL that the client uses to upload the file directly to R2. Afterwards, your backend saves the file's metadata to Neon.

This requires two backend endpoints:

1. `/presign-upload`: Generates the temporary presigned URL for the client to upload a file directly to R2.
2. `/save-metadata`: Records the metadata in Neon after the client confirms a successful upload to R2.

**JavaScript**

We'll use [Hono](https://hono.dev/) for the server, [`@aws-sdk/client-s3`](https://www.npmjs.com/package/@aws-sdk/client-s3) and [`@aws-sdk/s3-request-presigner`](https://www.npmjs.com/package/@aws-sdk/s3-request-presigner) for R2 interaction, and [`@neondatabase/serverless`](https://www.npmjs.com/package/@neondatabase/serverless) for Neon.

First, install the necessary dependencies:

```bash
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @neondatabase/serverless @hono/node-server hono dotenv
```

Create a `.env` file:

```env
# R2 Credentials & Config
R2_ACCOUNT_ID=your_cloudflare_account_id
R2_ACCESS_KEY_ID=your_r2_api_token_access_key_id
R2_SECRET_ACCESS_KEY=your_r2_api_token_secret_access_key
R2_BUCKET_NAME=your_r2_bucket_name # my-neon-app-files if following the example
R2_PUBLIC_BASE_URL=https://your-bucket-public-url.r2.dev # Your R2 bucket public URL

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```javascript
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { neon } from '@neondatabase/serverless';
import 'dotenv/config';
import { randomUUID } from 'crypto';

const R2_ENDPOINT = `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`;
const R2_BUCKET = process.env.R2_BUCKET_NAME;
const R2_PUBLIC_BASE_URL = process.env.R2_PUBLIC_BASE_URL; // Ensure no trailing '/'
const s3 = new S3Client({
  region: 'auto',
  endpoint: R2_ENDPOINT,
  credentials: {
    accessKeyId: process.env.R2_ACCESS_KEY_ID,
    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  },
});

const sql = neon(process.env.DATABASE_URL);
const app = new Hono();

// Replace this with your actual user authentication logic, by validating JWTs/Headers, etc.
const authMiddleware = async (c, next) => {
  c.set('userId', 'user_123'); // Example: Get user ID after validation
  await next();
};

// 1. Generate Presigned URL for Upload
app.post('/presign-upload', authMiddleware, async (c) => {
  try {
    const { fileName, contentType } = await c.req.json();
    if (!fileName || !contentType) throw new Error('fileName and contentType required');

    const objectKey = `${randomUUID()}-${fileName}`;
    const publicFileUrl = R2_PUBLIC_BASE_URL ? `${R2_PUBLIC_BASE_URL}/${objectKey}` : null;

    const command = new PutObjectCommand({
      Bucket: R2_BUCKET,
      Key: objectKey,
      ContentType: contentType,
    });
    const presignedUrl = await getSignedUrl(s3, command, { expiresIn: 300 });

    return c.json({ success: true, presignedUrl, objectKey, publicFileUrl });
  } catch (error) {
    console.error('Presign Error:', error.message);
    return c.json({ success: false, error: 'Failed to prepare upload' }, 500);
  }
});

// 2. Save Metadata after Client Upload Confirmation
app.post('/save-metadata', authMiddleware, async (c) => {
  try {
    const { objectKey, publicFileUrl } = await c.req.json();
    const userId = c.get('userId');
    if (!objectKey) throw new Error('objectKey required');

    const finalFileUrl =
      publicFileUrl ||
      (R2_PUBLIC_BASE_URL ? `${R2_PUBLIC_BASE_URL}/${objectKey}` : 'URL not available');

    await sql`
      INSERT INTO r2_files (object_key, file_url, user_id)
      VALUES (${objectKey}, ${finalFileUrl}, ${userId})
    `;
    console.log(`Metadata saved for R2 object: ${objectKey}`);
    return c.json({ success: true });
  } catch (error) {
    console.error('Metadata Save Error:', error.message);
    return c.json({ success: false, error: 'Failed to save metadata' }, 500);
  }
});

const port = 3000;
serve({ fetch: app.fetch, port }, (info) => {
  console.log(`Server running at http://localhost:${info.port}`);
});
```

**Explanation**

1. **Setup:** Initializes the Neon database client (`sql`), the Hono web framework (`app`), and the AWS S3 client (`s3`) configured for R2 using environment variables.
2. **Authentication:** A placeholder `authMiddleware` is included. **Crucially**, this needs to be replaced with real authentication logic. It currently just sets a static `userId` for demonstration.
3. **Upload endpoints**:
   - **`/presign-upload`:** Generates a temporary secure URL (`presignedUrl`) that allows uploading a file with a specific `objectKey` and `contentType` directly to R2 using `@aws-sdk/client-s3`. It returns the URL, key, and public URL.
   - **`/save-metadata`:** Called by the client _after_ it successfully uploads the file to R2. It saves the `objectKey`, the final `file_url`, and the `userId` into the `r2_files` table in Neon using `@neondatabase/serverless`.

**Python**

We'll use [Flask](https://flask.palletsprojects.com/en/stable/), [`boto3`](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) (AWS SDK for Python), and [`psycopg2`](https://pypi.org/project/psycopg2/).

First, install the necessary dependencies:

```bash
pip install Flask boto3 psycopg2-binary python-dotenv
```

Create a `.env` file:

```env
# R2 Credentials & Config
R2_ACCOUNT_ID=your_cloudflare_account_id
R2_ACCESS_KEY_ID=your_r2_api_token_access_key_id
R2_SECRET_ACCESS_KEY=your_r2_api_token_secret_access_key
R2_BUCKET_NAME=your_r2_bucket_name # my-neon-app-files if following the example
R2_PUBLIC_BASE_URL=https://your-bucket-public-url.r2.dev # Your R2 bucket public URL

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```python
import os
import uuid
import boto3
import psycopg2
from botocore.exceptions import ClientError
from dotenv import load_dotenv
from flask import Flask, jsonify, request

load_dotenv()

R2_ACCOUNT_ID = os.getenv("R2_ACCOUNT_ID")
R2_BUCKET_NAME = os.getenv("R2_BUCKET_NAME")
R2_PUBLIC_BASE_URL = os.getenv("R2_PUBLIC_BASE_URL")
DATABASE_URL = os.getenv("DATABASE_URL")
R2_ENDPOINT_URL = f"https://{R2_ACCOUNT_ID}.r2.cloudflarestorage.com"

s3_client = boto3.client(
    service_name='s3',
    endpoint_url=R2_ENDPOINT_URL,
    aws_access_key_id=os.getenv("R2_ACCESS_KEY_ID"),
    aws_secret_access_key=os.getenv("R2_SECRET_ACCESS_KEY"),
    region_name='auto'
)
app = Flask(__name__)

# Use a global PostgreSQL connection instead of creating a new one for each request in production
def get_db_connection():
    return psycopg2.connect(DATABASE_URL)

# Replace this with your actual user authentication logic
def get_authenticated_user_id(request):
    # Example: Validate Authorization header, session cookie, etc.
    return "user_123"  # Static ID for demonstration

# 1. Generate Presigned URL for Upload
@app.route("/presign-upload", methods=["POST"])
def presign_upload_route():
    try:
        user_id = get_authenticated_user_id(request)
        if not user_id:
            return jsonify({"success": False, "error": "Unauthorized"}), 401
        data = request.get_json()
        file_name = data.get('fileName')
        content_type = data.get('contentType')
        if not file_name or not content_type:
             raise ValueError("fileName and contentType required")

        object_key = f"{uuid.uuid4()}-{file_name}"
        public_file_url = f"{R2_PUBLIC_BASE_URL}/{object_key}" if R2_PUBLIC_BASE_URL else None

        presigned_url = s3_client.generate_presigned_url(
            'put_object',
            Params={'Bucket': R2_BUCKET_NAME, 'Key': object_key, 'ContentType': content_type},
            ExpiresIn=300
        )
        return jsonify({ "success": True, "presignedUrl": presigned_url, "objectKey": object_key, "publicFileUrl": public_file_url }), 200
    except (ClientError, ValueError) as e:
        print(f"Presign Error: {e}")
        return jsonify({"success": False, "error": f"Failed to prepare upload: {e}"}), 500
    except Exception as e:
        print(f"Unexpected Presign Error: {e}")
        return jsonify({"success": False, "error": "Server error"}), 500


# 2. Save Metadata after Client Upload Confirmation
@app.route("/save-metadata", methods=["POST"])
def save_metadata_route():
    conn = None
    cursor = None
    try:
        user_id = get_authenticated_user_id(request)
        data = request.get_json()
        object_key = data.get('objectKey')
        public_file_url = data.get('publicFileUrl')
        if not object_key: raise ValueError("objectKey required")

        final_file_url = public_file_url or (f"{R2_PUBLIC_BASE_URL}/{object_key}" if R2_PUBLIC_BASE_URL else 'URL not available')

        conn = get_db_connection()
        cursor = conn.cursor()
        cursor.execute(
            """ INSERT INTO r2_files (object_key, file_url, user_id) VALUES (%s, %s, %s) """,
            (object_key, final_file_url, user_id),
        )
        conn.commit()
        print(f"Metadata saved for R2 object: {object_key}")
        return jsonify({"success": True}), 201
    except (psycopg2.Error, ValueError) as e:
        print(f"Metadata Save Error: {e}")
        return jsonify({"success": False, "error": "Failed to save metadata"}), 500
    except Exception as e:
        print(f"Unexpected Metadata Save Error: {e}")
        return jsonify({"success": False, "error": "Server error"}), 500
    finally:
        if cursor: cursor.close()
        if conn: conn.close()

if __name__ == "__main__":
    app.run(port=3000, debug=True)
```

**Explanation**

1. **Setup:** Initializes the Flask web framework, the R2 client (`s3_client` using `boto3`), and the PostgreSQL client (`psycopg2`) using environment variables.
2. **Authentication:** A placeholder `get_authenticated_user_id` function is included. **Replace this with real authentication logic.**
3. **Upload endpoints**:
   - **`/presign-upload`:** Generates a temporary secure URL (`presignedUrl`) that allows uploading a file with a specific `objectKey` and `contentType` directly to R2 using `boto3`. It returns the URL, key, and public URL.
   - **`/save-metadata`:** Called by the client _after_ it successfully uploads the file to R2. It saves the `objectKey`, the final `file_url`, and the `userId` into the `r2_files` table in Neon using `psycopg2`.
4. In production, you should use a global PostgreSQL connection instead of creating a new one for each request. This is important for performance and resource management.

## Testing the upload workflow

Testing the presigned URL flow involves multiple steps:

1. **Get presigned URL:** Send a `POST` request to your `/presign-upload` endpoint with a JSON body containing `fileName` and `contentType`.

   ```bash
   curl -X POST http://localhost:3000/presign-upload \
        -H "Content-Type: application/json" \
        -d '{"fileName": "test-image.png", "contentType": "image/png"}'
   ```

   You should receive a JSON response with a `presignedUrl`, `objectKey`, and `publicFileUrl`:

   ```json
   {
     "success": true,
     "presignedUrl": "https://<ACCOUNT_ID>.r2.cloudflarestorage.com/<BUCKET_NAME>/<GENERATED_OBJECT_KEY>?X-Amz-Algorithm=...",
     "objectKey": "<GENERATED_OBJECT_KEY>",
     "publicFileUrl": "https://pub-<HASH>.r2.dev/<GENERATED_OBJECT_KEY>"
   }
   ```

   Note the `presignedUrl`, `objectKey`, and `publicFileUrl` from the response. You will use these in the next steps.

2. **Upload file to R2:** Use the received `presignedUrl` to upload the actual file using an HTTP `PUT` request.

   ```bash
   curl -X PUT "<PRESIGNED_URL>" \
        --upload-file /path/to/your/test-image.png \
        -H "Content-Type: image/png"
   ```

   A successful upload typically returns HTTP `200 OK` with no body.

3. **Save metadata:** Send a `POST` request to your `/save-metadata` endpoint with the `objectKey` and `publicFileUrl` obtained in step 1.

   ```bash
   curl -X POST http://localhost:3000/save-metadata \
        -H "Content-Type: application/json" \
        -d '{"objectKey": "<OBJECT_KEY>", "publicFileUrl": "<PUBLIC_URL>"}'
   ```

   You should receive a JSON response indicating success:

   ```json
   { "success": true }
   ```

**Expected outcome:**

- The file is uploaded to your R2 bucket. You can verify this in the Cloudflare dashboard or by accessing the `publicFileUrl` if your bucket is public.
- A new row appears in your `r2_files` table containing the `object_key` and `file_url`.

You can now integrate API calls to these endpoints from various parts of your application (for example, web clients using JavaScript's `fetch` API, mobile apps, backend services) to handle file uploads.

## Accessing file metadata and files

Storing metadata in the database allows your application to easily retrieve references to the files hosted on R2.

Query the `r2_files` table from your application's backend when needed.

**Example SQL query:**

Retrieve files for user 'user_123':

```sql
SELECT
    id,             -- Your database primary key
    object_key,     -- Key (path/filename) in the R2 bucket
    file_url,       -- Publicly accessible URL
    user_id,        -- User associated with the file
    upload_timestamp
FROM
    r2_files
WHERE
    user_id = 'user_123'; -- Use actual authenticated user ID
```

**Using the data:**

- The query returns rows containing the file metadata stored in Neon.
- The `file_url` column contains the direct link to access the file.
- Use this `file_url` in your application (for example, `<img>` tags, API responses, download links) wherever you need to display or provide access to the file.

  **Note: Private buckets**

  For private R2 buckets, store only the `object_key` and generate presigned _read_ URLs on demand using a similar backend process.

This pattern separates file storage and delivery (handled by R2) from structured metadata management (handled by the database).

## Resources

- [Cloudflare R2 documentation](https://developers.cloudflare.com/r2/)
- [Cloudflare presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)

--- [Document source](https://neon.com/docs/guides/cloudflare-workers.md) ---

> Summary: Connecting Lakebase Postgres to Cloudflare Workers covers two approaches: Cloudflare Hyperdrive (recommended, included in all Workers plans), which pools connections across Cloudflare's network using native drivers like node-postgres, and the Neon serverless driver, which connects over HTTP or WebSockets without Hyperdrive. Use this guide when deploying a TypeScript Worker that queries Postgres and needs to choose between Hyperdrive's connection pooling and the serverless driver's lightweight setup.

# Use Neon with Cloudflare Workers

Connect a Lakebase Postgres database to your Cloudflare Workers application

Last updated: 2026-10-09

[Cloudflare Workers](https://workers.cloudflare.com/) is a serverless platform allowing you to deploy your applications globally across Cloudflare's network. It supports running JavaScript, TypeScript, and WebAssembly, making it a great choice for high-performance, low-latency web applications.

This guide demonstrates how to connect to a Lakebase Postgres database from your Cloudflare Workers application using two approaches:

- **[Hyperdrive](https://developers.cloudflare.com/hyperdrive/)** (recommended): Cloudflare's connection pooling service that provides the lowest possible latencies by performing database connection setup and connection pooling across Cloudflare's network. Hyperdrive is included in all Workers plans and supports native PostgreSQL drivers like [node-postgres](https://node-postgres.com/).
- **[Neon serverless driver](https://neon.com/docs/serverless/serverless-driver)**: A low-latency Postgres driver designed for serverless environments that connects over HTTP or WebSockets.

**Note:** Hyperdrive is the recommended approach as it provides optimized connection pooling and fast query routing by connecting directly to your database. When using Hyperdrive with Neon, use native PostgreSQL drivers like node-postgres or Postgres.js instead of the Neon serverless driver.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- A Cloudflare account. If you do not have one, sign up at [Cloudflare](https://dash.cloudflare.com/) to get started.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and deploy the Workers application.

## Setting up your Neon database

### Initialize a new project

Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.

1. Click the **New Project** button to create a new project.

2. In the Neon Console, navigate to **Postgres database** > **SQL Editor** from the sidebar, and run the following SQL command to create a new table in your database:

   ```sql
   CREATE TABLE books_to_read (
       id SERIAL PRIMARY KEY,
       title TEXT,
       author TEXT
   );
   ```

   Next, insert some sample data into the `books_to_read` table so that you can query it later:

   ```sql
   INSERT INTO books_to_read (title, author)
   VALUES
       ('The Way of Kings', 'Brandon Sanderson'),
       ('The Name of the Wind', 'Patrick Rothfuss'),
       ('Coders at Work', 'Peter Seibel'),
       ('1984', 'George Orwell');
   ```

## Setting up your Cloudflare Workers project

**Hyperdrive (recommended)**

### Create a Hyperdrive user in Neon

To use Hyperdrive with Neon, you'll need to create a dedicated database role for Hyperdrive to use:

1. In the Neon Console, navigate to your project.
2. Select your branch from the project/branch menu at the top of the sidebar.
3. Under **Postgres database**, select **Roles**.
4. Click **Add role** and enter `hyperdrive-user` as the name (or your preferred name).
5. **Copy the password** that is generated. You'll use this password in the connection string in the next step.

### Get your Neon connection string for Hyperdrive

1. In the Neon Console, click **Connect** at the top of the sidebar.
2. Select the **branch**, **database**, and **role** (for example, `hyperdrive-user`) that Hyperdrive will connect through.
3. **Important**: Toggle **Connection pooling** off. Hyperdrive manages connection pooling, so you need the direct connection string.
4. Copy the connection string, which should look like this:

   ```bash
   postgres://hyperdrive-user:PASSWORD@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname
   ```

### Create a new Worker project

Run the following command in a terminal window to set up a new Cloudflare Workers project:

```bash
npm create cloudflare@latest
```

This initiates an interactive CLI prompt to generate a new project. To follow along with this guide, you can use the following settings:

```bash
├ In which directory do you want to create your application?
│ type my-neon-worker
│
├ What would you like to start with?
│ select "Hello World example"
│
├ Which template would you like to use?
│ select "Worker only"
│
├ Which language do you want to use?
│ select "TypeScript"
│
├ Do you want to use git for version control?
│ select "Yes"
│
├ Do you want to deploy your application?
│ select "No"
```

For the purpose of demonstration, we will use the **Worker only** template and will deploy the application later.

Navigate to your project directory:

```bash
cd my-neon-worker
```

### Create a Hyperdrive configuration

If you are not already authenticated with your Cloudflare account, use the following command:

```bash
npx wrangler login
```

This command will open a browser window and prompt you to log into your Cloudflare account. After logging in, you can close the browser window and return to your terminal.

Now, create a Hyperdrive configuration with your Neon connection string:

```bash
npx wrangler hyperdrive create my-neon-hyperdrive --connection-string="postgres://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE"
```

Replace the placeholder values with your actual connection details from the previous step. You will then be prompted with "Would you like Wrangler to add it on your behalf?". Enter **Y**, and continue with the default name. This will add the required Hyperdrive configuration (bindings) to your project.

### Install the node-postgres driver

For Hyperdrive, we'll use the native PostgreSQL driver [node-postgres](https://node-postgres.com/):

```bash
npm install pg
npm install -D @types/pg
```

### Create types

To generate the types for your Hyperdrive binding, use the following command:

```bash
npm run cf-typegen
```

### Configure wrangler.jsonc

Update your `wrangler.jsonc` to add the **compatibility_flags** binding. We will also update the Hyperdrive binding and add the **localConnectionString**. This will allow our locally running application to connect to the Neon database via Hyperdrive. The complete `wrangler.jsonc` file should be as follows:

```json
{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "my-neon-worker",
  "main": "src/index.ts",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "compatibility_date": "2025-09-27",
  "hyperdrive": [
    {
      "binding": "HYPERDRIVE",
      "id": "<your-hyperdrive-id-here>",
      "localConnectionString": "postgres://USERNAME:PASSWORD@HOSTNAME:PORT/DATABASE"
    }
  ]
}
```

Replace the following placeholders:

- `localConnectionString` with your Neon connection string (the same one you used to create the Hyperdrive configuration). This is required for local development with `wrangler dev`.

### Implement the Worker script

Update the `src/index.ts` file in your project directory with the following code:

```ts
import { Client } from 'pg';

export default {
  async fetch(request, env, ctx) {
    const client = new Client({
      connectionString: env.HYPERDRIVE.connectionString
    });

    await client.connect();
    const result = await client.query('SELECT * FROM books_to_read;');

    // Clean up the client connection in the background
    ctx.waitUntil(client.end());

    return Response.json(result.rows);
  },
} satisfies ExportedHandler<Env>;
```

The `fetch` handler uses the Hyperdrive binding to connect to your Neon database through Cloudflare's optimized connection pooling service.

**Important:** When using Hyperdrive with Neon, always use native PostgreSQL drivers like node-postgres (pg) or Postgres.js instead of the Neon serverless driver. Hyperdrive already provides optimized connection pooling and query routing for Workers.

### Test the worker application locally

To test the worker application locally, run:

```bash
npm run dev
```

This command starts a local server and simulates the Cloudflare Workers environment.

```bash
❯ npm run dev

> my-neon-worker@0.0.0 dev
> wrangler dev


 ⛅️ wrangler 4.61.0
───────────────────
Your Worker has access to the following bindings:
Binding                                                Resource               Mode
env.HYPERDRIVE (YOUR_HYPERDRIVE_ID)      Hyperdrive Config      local

❓ Your types might be out of date. Re-run `wrangler types` to ensure your types are correct.
╭──────────────────────────────────────────────────────────────────────╮
│  [b] open a browser [d] open devtools [c] clear console [x] to exit  │
╰──────────────────────────────────────────────────────────────────────╯
⎔ Starting local server...
[wrangler:info] Ready on http://localhost:8787
```

Visit `http://localhost:8787` in your browser to test the worker application. It should return a JSON response with the list of books from the `books_to_read` table.

**Neon serverless driver**

### Retrieve your Neon database connection string

In the Neon Console, click **Connect** in the nav to open the **Connect to your branch** modal to find your database connection string. Enable the **Connection pooling** toggle to add the `-pooler` option to your connection string. A pooled connection is recommended for serverless environments. For more information, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

Your pooled connection string should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

### Create a new Worker project

Run the following command in a terminal window to set up a new Cloudflare Workers project:

```bash
npm create cloudflare@latest
```

This initiates an interactive CLI prompt to generate a new project. To follow along with this guide, you can use the following settings:

```bash
├ In which directory do you want to create your application?
│ type my-neon-worker
│
├ What would you like to start with?
│ select "Hello World example"
│
├ Which template would you like to use?
│ select "Worker only"
│
├ Which language do you want to use?
│ select "TypeScript"
│
├ Do you want to use git for version control?
│ select "Yes"
│
├ Do you want to deploy your application?
│ select "No"
```

We'll develop and test the application locally before deploying it to Cloudflare.

The `create-cloudflare` CLI installs the `Wrangler` CLI to manage the full workflow of testing and managing your Worker applications.

### Implement the Worker script

We'll use the [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver) to connect to the Neon database, so you need to install it as a dependency:

```bash
npm install @neondatabase/serverless
```

Now, you can update the `src/index.ts` file in the project directory with the following code:

```ts
import { Client } from '@neondatabase/serverless';

export default {
  async fetch(request, env, ctx) {
    const client = new Client(env.DATABASE_URL);
    await client.connect();
    const { rows } = await client.query('SELECT * FROM books_to_read;');
    return new Response(JSON.stringify(rows));
  },
} satisfies ExportedHandler<Env>;
```

The `fetch` handler defined above gets called when the worker receives an HTTP request. It will query the Neon database to fetch the full list of books in our to-read list.

### Test the worker application locally

You first need to configure the `DATABASE_URL` environment variable to point to our Neon database. You can do this by creating a `.dev.vars` file at the root of the project directory with the following content:

```text
DATABASE_URL=YOUR_NEON_CONNECTION_STRING
```

Now, to test the worker application locally, you can use the `wrangler` CLI which comes with the Cloudflare project setup.

```bash
npm run dev
```

This command starts a local server and simulates the Cloudflare Workers environment.

```bash
❯ npm run dev
 ⛅️ wrangler 3.28.1
-------------------
Using vars defined in .dev.vars
Your worker has access to the following bindings:
- Vars:
  - DATABASE_URL: "(hidden)"
⎔ Starting local server...
[wrangler:inf] Ready on http://localhost:8787
```

You can visit `http://localhost:8787` in your browser to test the worker application. It should return a JSON response with the list of books from the `books_to_read` table.

```
[{"id":1,"title":"The Way of Kings","author":"Brandon Sanderson"},{"id":2,"title":"The Name of the Wind","author":"Patrick Rothfuss"},{"id":3,"title":"Coders at Work","author":"Peter Seibel"},{"id":4,"title":"1984","author":"George Orwell"}]
```

## Deploying your application with Cloudflare Workers

### Authenticate Wrangler with your Cloudflare account

If you aren't authenticated, run the following command to link the Wrangler tool to your Cloudflare account:

```bash
npx wrangler login
```

This command will open a browser window and prompt you to log into your Cloudflare account. After logging in and approving, you can close the browser window and return to your terminal.

### Configure secrets

**Note:** If you're using **Hyperdrive**, your connection is already configured in the `wrangler.jsonc` file, so you can skip this step and proceed directly to publishing your Worker.

If you're using the **Neon serverless driver**, you need to add your connection string as a secret.

For the Neon serverless driver approach, use Wrangler to add your Neon database connection string as a secret to your Worker:

```bash
npx wrangler secret put DATABASE_URL
```

When prompted, paste your pooled Neon connection string.

### Publish your Worker application

Now, you can deploy your application to Cloudflare Workers by running the following command:

```bash
npm run deploy
```

The Wrangler CLI will output the URL of your Worker hosted on the Cloudflare platform. Visit this URL in your browser or use `curl` to verify the deployment works as expected.

```text
❯ npm run deploy
 ⛅️ wrangler 3.28.1
-------------------
Total Upload: 189.98 KiB / gzip: 49.94 KiB
Uploaded my-neon-worker (4.03 sec)
Published my-neon-worker (5.99 sec)
  https://my-neon-worker.anandishan2.workers.dev
Current Deployment ID: de8841dd-46e4-436d-b2c4-569e91f54c72
```

## Removing the example application and Neon project

To delete your Worker, you can use the Cloudflare dashboard or run `wrangler delete` from your project directory, specifying your project name. Refer to the [Wrangler documentation](https://developers.cloudflare.com/workers/wrangler/commands/#delete-3) for more details.

If you used Hyperdrive, you should also delete the Hyperdrive configuration:

```bash
npx wrangler hyperdrive delete my-neon-hyperdrive
```

To delete your Neon project, follow the steps outlined in the Neon documentation under [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

## Resources

- [Cloudflare Workers](https://workers.cloudflare.com/)
- [Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/)
- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)
- [node-postgres](https://node-postgres.com/)
- [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver)
- [Neon](https://neon.tech)

--- [Document source](https://neon.com/docs/guides/cloudinary.md) ---

> Summary: Cloudinary-Neon integration that securely uploads images and videos from the client using backend-generated signatures, then stores the resulting asset metadata (public_id, secure_url, resource_type) in a Lakebase Postgres table. Use this page when you need a media pipeline that offloads file storage and CDN delivery to Cloudinary while keeping structured metadata queryable in Postgres. Includes JavaScript (Hono) and Python (Flask) backend examples covering the /generate-signature and /save-metadata endpoints.

# Media storage with Cloudinary

Store files via Cloudinary and track metadata in Lakebase

Last updated: 2026-10-28

[Cloudinary](https://cloudinary.com/) is a cloud-based platform for image and video management, offering upload, storage, real-time manipulation, optimization, and delivery via CDN.

**Neon now offers native storage:**

Neon Object Storage is S3-compatible object storage built into the Neon backend. Object storage branches with your database: each branch gets its own isolated namespace, so you can test file uploads in preview branches without touching production. No separate cloud account needed. Use any S3-compatible SDK with your existing Neon credential.

For more information, see [Neon Object Storage](https://neon.com/docs/storage/overview).

This guide demonstrates how to integrate Cloudinary with Neon. You'll learn how to securely upload files directly from the client-side to Cloudinary using signatures generated by your backend, and then store the resulting asset metadata (like the Cloudinary Public ID and secure URL) in your database.

## Setup steps

## Create a Neon project

1. Navigate to the [Neon Console](https://console.neon.tech) to create a new Neon project.
2. Copy the connection string by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Create a Cloudinary account and get credentials

1. Sign up for a free or paid account at [Cloudinary.com](https://cloudinary.com/users/register/free).
2. Once logged in, navigate to your **Account settings**.
3. Find your **Product Environment Credentials** which include:

   - **Cloud Name**
   - **API Key**
   - **API Secret**

   Create a new **API Key** if you do not have one. This key is used to authenticate your application with Cloudinary.
   ![Cloudinary API Key](https://neon.com/docs/guides/cloudinary-api-key.png)

## Create a table in Neon for file metadata

We need a table to store metadata about the assets uploaded to Cloudinary.

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a client like [psql](https://neon.com/docs/connect/query-with-psql-editor). Create a table to store relevant details:

   ```sql
   CREATE TABLE IF NOT EXISTS cloudinary_files (
       id SERIAL PRIMARY KEY,
       public_id TEXT NOT NULL UNIQUE,  -- Cloudinary's unique identifier for the asset
       media_url TEXT NOT NULL,         -- Media URL for the asset on Cloudinary's CDN
       resource_type TEXT NOT NULL,     -- Type of asset (for example, 'image', 'video', 'raw')
       user_id TEXT NOT NULL,           -- User associated with the file
       upload_timestamp TIMESTAMPTZ DEFAULT NOW()
   );
   ```

2. Run the SQL statement. You can customize this table by adding other useful columns returned by Cloudinary (for example, `version`, `format`, `width`, `height`, `tags`).

**Note: Securing metadata with RLS**

If you use [Neon's Row Level Security (RLS)](https://neon.com/blog/introducing-neon-authorize), apply appropriate policies to the `cloudinary_files` table to control access to the metadata stored in Neon based on your rules.

Note that these policies apply _only_ to the metadata in Neon. Access control for the assets themselves is managed within Cloudinary (for example, via asset types, delivery types). By default, uploaded assets are typically accessible via their CDN URL.

## Upload files to Cloudinary and store metadata in Neon

The recommended secure approach for client-side uploads to Cloudinary involves **signed uploads**. Your backend generates a unique signature using your API Secret and specific upload parameters (like timestamp). The client uses this signature, along with your API Key and the parameters, to authenticate the direct upload request to Cloudinary. After a successful upload, the client sends the returned asset metadata back to your backend to save in Neon.

This requires two backend endpoints:

1. `/generate-signature`: Generates a signature, timestamp, and provides the API key for the client upload.
2. `/save-metadata`: Receives asset metadata from the client after a successful Cloudinary upload and saves it to the Neon database.

**JavaScript**

We'll use [Hono](https://hono.dev/) for the server, the official [`cloudinary`](https://www.npmjs.com/package/cloudinary) Node.js SDK for signature generation, and [`@neondatabase/serverless`](https://www.npmjs.com/package/@neondatabase/serverless) for Neon.

First, install the necessary dependencies:

```bash
npm install cloudinary @neondatabase/serverless @hono/node-server hono dotenv
```

Create a `.env` file with your credentials:

```env
# Cloudinary Credentials
CLOUDINARY_CLOUD_NAME=your_cloudinary_cloud_name
CLOUDINARY_API_KEY=your_cloudinary_api_key
CLOUDINARY_API_SECRET=your_cloudinary_api_secret

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```javascript
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { v2 as cloudinary } from 'cloudinary';
import { neon } from '@neondatabase/serverless';
import 'dotenv/config';

cloudinary.config({
  cloud_name: process.env.CLOUDINARY_CLOUD_NAME,
  api_key: process.env.CLOUDINARY_API_KEY,
  api_secret: process.env.CLOUDINARY_API_SECRET,
  secure: true,
});

const sql = neon(process.env.DATABASE_URL);
const app = new Hono();

// Replace this with your actual user authentication logic
const authMiddleware = async (c, next) => {
  // Example: Validate JWT, session, etc. and set user ID
  c.set('userId', 'user_123'); // Static ID for demonstration
  await next();
};

// 1. Generate signature for client-side upload
app.get('/generate-signature', authMiddleware, (c) => {
  try {
    const timestamp = Math.round(new Date().getTime() / 1000);
    const paramsToSign = { timestamp: timestamp };

    const signature = cloudinary.utils.api_sign_request(
      paramsToSign,
      process.env.CLOUDINARY_API_SECRET
    );

    return c.json({
      success: true,
      signature: signature,
      timestamp: timestamp,
      api_key: process.env.CLOUDINARY_API_KEY,
    });
  } catch (error) {
    console.error('Signature Generation Error:', error);
    return c.json({ success: false, error: 'Failed to generate signature' }, 500);
  }
});

// 2. Save metadata after client confirms successful upload to Cloudinary
app.post('/save-metadata', authMiddleware, async (c) => {
  try {
    const userId = c.get('userId');
    // Client sends metadata received from Cloudinary after upload
    const { public_id, secure_url, resource_type } = await c.req.json();

    if (!public_id || !secure_url || !resource_type) {
      throw new Error('public_id, secure_url, and resource_type are required');
    }

    // Insert metadata into Neon database
    await sql`
      INSERT INTO cloudinary_files (public_id, media_url, resource_type, user_id)
      VALUES (${public_id}, ${secure_url}, ${resource_type}, ${userId})
    `;

    console.log(`Metadata saved for Cloudinary asset: ${public_id}`);
    return c.json({ success: true });
  } catch (error) {
    console.error('Metadata Save Error:', error.message);
    return c.json({ success: false, error: 'Failed to save metadata' }, 500);
  }
});

const port = 3000;
serve({ fetch: app.fetch, port }, (info) => {
  console.log(`Server running at http://localhost:${info.port}`);
});
```

**Explanation**

1. **Setup:** Initializes the Neon client (`sql`), Hono (`app`), and configures the Cloudinary Node.js SDK using environment variables.
2. **Authentication:** Includes a placeholder `authMiddleware`. **Replace this with your actual user authentication logic.**
3. **API endpoints:**
   - **`/generate-signature` (GET):** Creates a current `timestamp`. Uses `cloudinary.utils.api_sign_request` with the parameters to sign (at minimum, the timestamp) and your `API Secret` to generate a `signature`. It returns the `signature`, `timestamp`, and your `API Key` to the client. These are needed for the client's direct upload request to Cloudinary.
   - **`/save-metadata` (POST):** Called by the client _after_ a successful direct upload to Cloudinary. The client sends the relevant asset metadata received from Cloudinary (`public_id`, `secure_url`, `resource_type`). The endpoint saves this information, along with the `userId`, into the `cloudinary_files` table in Neon.

**Python**

We'll use [Flask](https://flask.palletsprojects.com/en/stable/), the official [`cloudinary`](https://pypi.org/project/cloudinary/) Python SDK, and [`psycopg2`](https://pypi.org/project/psycopg2/).

First, install the necessary dependencies:

```bash
pip install Flask cloudinary psycopg2-binary python-dotenv
```

Create a `.env` file with your credentials:

```env
# Cloudinary Credentials
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```python
import os
import time

import cloudinary
import cloudinary.utils
import psycopg2
from dotenv import load_dotenv
from flask import Flask, jsonify, request

load_dotenv()

cloudinary.config(
    cloud_name=os.getenv("CLOUDINARY_CLOUD_NAME"),
    api_key=os.getenv("CLOUDINARY_API_KEY"),
    api_secret=os.getenv("CLOUDINARY_API_SECRET"),
    secure=True,
)

app = Flask(__name__)


# Use a global PostgreSQL connection pool in production instead of connecting per request
def get_db_connection():
    return psycopg2.connect(os.getenv("DATABASE_URL"))


# Replace this with your actual user authentication logic
def get_authenticated_user_id(request):
    # Example: Validate Authorization header, session cookie, etc.
    return "user_123"  # Static ID for demonstration


# 1. Generate signature for client-side upload
@app.route("/generate-signature", methods=["GET"])
def generate_signature_route():
    try:
        user_id = get_authenticated_user_id(request)
        if not user_id:
            return jsonify({"success": False, "error": "Unauthorized"}), 401

        timestamp = int(time.time())
        params_to_sign = {"timestamp": timestamp}

        signature = cloudinary.utils.api_sign_request(
            params_to_sign, os.getenv("CLOUDINARY_API_SECRET")
        )

        return (
            jsonify(
                {
                    "success": True,
                    "signature": signature,
                    "timestamp": timestamp,
                    "api_key": os.getenv("CLOUDINARY_API_KEY"),
                }
            ),
            200,
        )

    except Exception as e:
        print(f"Signature Generation Error: {e}")
        return jsonify({"success": False, "error": "Failed to generate signature"}), 500


# 2. Save metadata after client confirms successful upload to Cloudinary
@app.route("/save-metadata", methods=["POST"])
def save_metadata_route():
    conn = None
    cursor = None
    try:
        user_id = get_authenticated_user_id(request)
        if not user_id:
            return jsonify({"success": False, "error": "Unauthorized"}), 401

        # Client sends metadata received from Cloudinary after upload
        data = request.get_json()
        public_id = data.get("public_id")
        secure_url = data.get("secure_url")
        resource_type = data.get("resource_type")

        if not public_id or not secure_url or not resource_type:
            raise ValueError("public_id, secure_url, and resource_type are required")

        # Insert metadata into Neon database
        conn = get_db_connection()
        cursor = conn.cursor()
        cursor.execute(
            """
            INSERT INTO cloudinary_files (public_id, media_url, resource_type, user_id)
            VALUES (%s, %s, %s, %s)
            """,
            (public_id, secure_url, resource_type, user_id),
        )
        conn.commit()
        print(f"Metadata saved for Cloudinary asset: {public_id}")
        return jsonify({"success": True}), 201

    except (psycopg2.Error, ValueError) as e:
        print(f"Metadata Save Error: {e}")
        return (
            jsonify({"success": False, "error": "Failed to save metadata"}),
            500,
        )
    except Exception as e:
        print(f"Unexpected Metadata Save Error: {e}")
        return jsonify({"success": False, "error": "Server error"}), 500
    finally:
        if cursor:
            cursor.close()
        if conn:
            conn.close()


if __name__ == "__main__":
    app.run(port=3000, debug=True)
```

**Explanation**

1. **Setup:** Initializes Flask (`app`), the database connection function, and configures the Cloudinary Python SDK using environment variables.
2. **Authentication:** Includes a placeholder `get_authenticated_user_id` function. **Replace this with your actual user authentication logic.**
3. **API endpoints:**
   - **`/generate-signature` (GET):** Gets the current `timestamp`. Uses `cloudinary.utils.api_sign_request` with the parameters to sign and your `API Secret` to generate the `signature`. Returns the `signature`, `timestamp`, and `API Key` to the client.
   - **`/save-metadata` (POST):** Called by the client _after_ a successful direct upload to Cloudinary. It receives asset metadata from the client, validates required fields (`public_id`, `secure_url`, `resource_type`), and saves this along with the `userId` into the `cloudinary_files` table using `psycopg2`.
4. **Database Connection:** The example shows creating a new connection per request. In production, use a global connection pool for better performance.

## Testing the upload workflow

This workflow involves getting a signature from your backend, using it to upload directly to Cloudinary, and then notifying your backend.

1. **Get signature and parameters:** Send a `GET` request to your backend's `/generate-signature` endpoint.

   ```bash
   curl -X GET http://localhost:3000/generate-signature
   ```

   **Expected response:** A JSON object with the `signature`, `timestamp`, and `api_key`.

   ```json
   {
     "success": true,
     "signature": "a1b2c3d4e5f6...",
     "timestamp": 1713999600,
     "api_key": "YOUR_CLOUDINARY_API_KEY"
   }
   ```

2. **Upload file directly to Cloudinary:** Use the obtained `signature`, `timestamp`, `api_key`, and the file path to send a `POST` request with `multipart/form-data` directly to the Cloudinary Upload API. The URL includes your **Cloud Name**.

   ```bash
   curl -X POST https://api.cloudinary.com/v1_1/<YOUR_CLOUD_NAME>/image/upload \
        -F "file=@/path/to/your/test-image.jpg" \
        -F "api_key=<API_KEY_FROM_STEP_1>" \
        -F "timestamp=<TIMESTAMP_FROM_STEP_1>" \
        -F "signature=<SIGNATURE_FROM_STEP_1>"
   ```

   > If uploading a video, change the endpoint in the URL from `/image/upload` to `/video/upload`.

   **Expected response (from Cloudinary):** A successful upload returns a JSON object with metadata about the uploaded asset.

   ```json
   {
     "asset_id": "...",
     "public_id": "<PUBLIC_ID>",
     "version": 1713999601,
     "version_id": "...",
     "signature": "...",
     "width": 800,
     "height": 600,
     "format": "jpg",
     "resource_type": "image",
     "created_at": "2025-04-24T05:37:06Z",
     "tags": [],
     "bytes": 123456,
     "type": "upload",
     "etag": "...",
     "placeholder": false,
     "url": "http://res.cloudinary.com/<YOUR_CLOUD_NAME>/image/upload/v1713999601/sample_image_123.jpg",
     "secure_url": "https://res.cloudinary.com/<YOUR_CLOUD_NAME>/image/upload/v1713999601/sample_image_123.jpg",
     "folder": "",
     "original_filename": "test-image",
     "api_key": "YOUR_CLOUDINARY_API_KEY"
   }
   ```

   > Note the `public_id`, `secure_url`, and `resource_type` in the response. These are needed for the next step.

3. **Save metadata:** Send a `POST` request to your backend's `/save-metadata` endpoint with the key details received from Cloudinary in Step 2.

   ```bash
   curl -X POST http://localhost:3000/save-metadata \
        -H "Content-Type: application/json" \
        -d '{
             "public_id": "<PUBLIC_ID_FROM_STEP_2>",
             "secure_url": "<SECURE_URL_FROM_STEP_2>",
             "resource_type": "<RESOURCE_TYPE_FROM_STEP_2>"
           }'
   ```

   **Expected response (from your backend):**

   ```json
   { "success": true }
   ```

**Expected outcome:**

- The file is successfully uploaded to your Cloudinary account (visible in the Media Library).
- A new row corresponding to the uploaded asset exists in your `cloudinary_files` table in Neon.

## Accessing file metadata and files

With metadata stored in Neon, your application can retrieve references to the media hosted on Cloudinary.

Query the `cloudinary_files` table from your application's backend whenever you need to display or link to uploaded files.

**Example SQL query:**

Retrieve media files associated with a specific user:

```sql
SELECT
    id,
    public_id,      -- Cloudinary Public ID
    media_url,      -- HTTPS URL for the asset
    resource_type,
    user_id,
    upload_timestamp
FROM
    cloudinary_files
WHERE
    user_id = 'user_123' AND resource_type = 'image'; -- Use actual user ID & desired type
```

**Using the data:**

- The query returns metadata stored in Neon.
- The `media_url` is the direct CDN link to the asset.
- **Cloudinary transformations:** Cloudinary excels at on-the-fly transformations. You can manipulate the asset by modifying the `media_url`. Parameters are inserted between the `/upload/` part and the version/public_id part of the URL. For example, to get a 300px wide, cropped version: `https://res.cloudinary.com/<CLOUD_NAME>/image/upload/w_300,c_fill/v<VERSION>/<PUBLIC_ID>.<FORMAT>`. Explore the extensive [Cloudinary transformation documentation](https://cloudinary.com/documentation/image_transformations).

This pattern separates media storage, processing, and delivery (handled by Cloudinary) from structured metadata management (handled by Neon).

## Resources

- [Cloudinary documentation](https://cloudinary.com/documentation)
- [Cloudinary Upload API reference](https://cloudinary.com/documentation/image_upload_api_reference)
- [Neon Documentation](https://neon.com/docs)

--- [Document source](https://neon.com/docs/guides/consumption-limits.md) ---

> Summary: Storage is unlimited on paid plans: there's no hard per-branch size limit and storage grows with your usage. The customer-set quotas described here are separate, hard limits you choose. Per-project consumption quotas in Neon let you cap active_time_seconds, compute_time_seconds, written_data_bytes, data_transfer_bytes, and logical_size_bytes via the quota object in the Create or Update Project API endpoints. When any quota threshold is met, all active computes for that project are suspended and remain suspended until the next billing period starts, unlike scale-to-zero which restarts on the next connection. Use this page to configure, query, and reset quota limits for multi-tenant billing integrations where different plan tiers need different resource ceilings.

# Configure consumption limits

Learn how to set consumption limits per project with the Neon API

Last updated: 2026-09-02

When setting up your integration's billing solution with Neon, you may want to impose some hard limits on how much storage or compute resources a given project can consume. For example, you may want to cap how much usage your free plan users can consume versus pro or enterprise users. With the Neon API, you can use the `quota` key to set usage limits for a variety of consumption metrics. These limits act as thresholds after which all active computes for a project are [suspended](https://neon.com/docs/guides/consumption-limits#suspending-active-computes).

Consumption limits actively enforce usage caps: when a project hits a quota, Neon suspends its computes. They apply per project and per consumption metric (compute, storage, and data transfer). If you instead want email alerts when your organization's total monthly charges approach a dollar amount, without stopping usage, see [Spending notifications](https://neon.com/docs/introduction/spending-notifications).

## Metrics and quotas

By default, Neon tracks a variety of consumption metrics at the project level. If you want to set quotas (max limits) for these metrics, you need to explicitly [configure](https://neon.com/docs/guides/consumption-limits#configuring-quotas) them.

### Available metrics

Here are the relevant metrics that you can track in order to understand your users' current consumption levels.

#### Project-level metrics

- `active_time_seconds`
- `compute_time_seconds`
- `written_data_bytes`
- `data_transfer_bytes`

These consumption metrics represent total cumulative usage across all branches and computes in a given project, accrued so far in a given monthly billing period. Metrics are refreshed on the first day of the following month, when the new billing period starts.

**Note: Not for billing**

These fields are approximate and not intended for billing or metering. For billing, use the [consumption history API](https://neon.com/docs/guides/consumption-metrics) (`/consumption_history/v2/projects`).

#### Branch-level metric

There is an additional value that you also might want to track: `logical_size`, which gives you the current size of a particular branch.

Neon updates all metrics every 15 minutes but it could take up to 1 hour before they are reportable.

To find the current usage level for any of these metrics, see [querying metrics](https://neon.com/docs/guides/consumption-limits#querying-metrics-and-quotas).

### Corresponding quotas

You can set quotas for these consumption metrics per project using the `quota` settings object in the [Create project](https://neon.com/docs/reference/api/projects/create-project) or [Update project](https://neon.com/docs/reference/api/projects/update-project) API.

The `quota` object includes an array of parameters used to set threshold limits. Their names generally match their corresponding metric:

- `active_time_seconds`: Sets the maximum amount of time your project's computes are allowed to be active during the current billing period. It excludes time when computes are in an idle state due to [scale to zero](https://neon.com/docs/reference/glossary#scale-to-zero).

- `compute_time_seconds`: Sets the maximum amount of CPU seconds allowed in total across all of a project's computes. This includes any computes deleted during the current billing period. Note that the larger the compute size per endpoint, the faster the project consumes `compute_time_seconds`. For example, 1 second at .25 CU costs .25 compute seconds, while 1 second at 4 CU costs 4 compute seconds.

  | CU   | active\_time\_seconds | compute\_time\_seconds |
  | :--- | :-------------------- | :--------------------- |
  | 0.25 | 1                     | 0.25                   |
  | 4    | 1                     | 4                      |

- `written_data_bytes`: Sets the maximum amount of data in total, measured in bytes, that can be written across all of a project's branches for the month.

- `data_transfer_bytes`: Sets the maximum amount of egress data, measured in bytes, that can be transferred out of Neon from across all of a project's branches using the proxy.

There is one additional `quota` parameter, `logical_size_bytes`, which applies to individual branches, not to the overall project. You can use `logical_size_bytes` to set the maximum size (measured in bytes) that any one individual branch is allowed to reach. Once this threshold is met, the compute for that particular branch (and _only_ that particular branch) is suspended. Note that this limit is _not_ refreshed once per month: it is a strict size limit that applies for the life of the branch.

These customer-set quotas behave differently from Neon's own platform storage. On paid plans there's no hard per-branch size limit; your storage grows with your usage. A `logical_size_bytes` quota you set yourself is a hard limit and suspends the branch's compute instead.

### Sample quotas

Let's say you want to set limits for an application with two tiers, Trial and Pro, you might set limits like the following:

| Parameter (project)    | Trial (.25 CU)                   | Pro (max 4 CU)                                 |
| ---------------------- | -------------------------------- | ---------------------------------------------- |
| active\_time\_seconds  | 633,600 (business month 22 days) | 2,592,000 (30 days)                            |
| compute\_time\_seconds | 158,400 (approx 44 hours)        | 10,368,000 (4 times the active hours for 4 CU) |
| written\_data\_bytes   | 1,000,000,000 (approx. 1 GB)     | 50,000,000,000 (approx. 50 GB)                 |
| data\_transfer\_bytes  | 500,000,000 (approx. 500 MB)     | 10,000,000,000 (approx. 10 GB)                 |

| Parameter (branch)   | Trial                         | Pro                            |
| -------------------- | ----------------------------- | ------------------------------ |
| logical\_size\_bytes | 100,000,000 (approx. 100 MiB) | 10,000,000,000 (approx. 10 GB) |

### Guidelines

Generally, the most effective quotas for controlling spend per project are those controlling maximum compute (`active_time_seconds` and `compute_time_seconds`) and maximum written storage (`written_data_bytes`). In practice, it is possible that `data_transfer_bytes` could introduce unintended logical constraints against your usage. For example, let's say you want to run a cleanup operation to reduce your storage. If part of this cleanup operation involves moving data across the network (for instance, to create an offsite backup before deletion), the `data_transfer_bytes` limit could prevent you from completing the operation. This is an undesirable situation where two measures meant to control cost interfere with one another.

### Neon default limits

In addition to the configurable limits that you can set, Neon also sets certain branch size limits by default. You might notice these limits in a [Get Project](https://neon.com/docs/guides/consumption-limits#retrieving-details-about-a-project) response:

- `branch_logical_size_limit` (MiB)
- `branch_logical_size_limit_bytes`(Bytes)

These limits are not directly configurable. You can query the limits by running the [Get project details](https://neon.com/docs/reference/api/projects/get-project) or [Get project list](https://neon.com/docs/reference/api/projects/list-projects) endpoints.

## Suspending active computes

_**What happens when a quota is met?**_

When any configured metric reaches its quota limit, all active computes for that project are automatically suspended. It is important to understand, this suspension is persistent. It works differently than the inactivity-based [scale to zero](https://neon.com/docs/guides/scale-to-zero-guide), where computes restart at the next interaction: this suspend will _not_ restart at the next API call or incoming connection. If you don't take explicit action otherwise, the suspension remains in place until the next billing period starts (`consumption_period_end`).

See [Querying metrics and quotas](https://neon.com/docs/guides/consumption-limits#querying-metrics-and-quotas) to find the reset date, billing period, and other values related to a project's consumption.

**Note:** Neon tracks these consumption metrics on a monthly cycle. To track usage on a different cycle or across billing periods, use the [consumption history API](https://neon.com/docs/guides/consumption-metrics) (`/consumption_history/v2/projects`), which returns hourly, daily, or monthly metrics.

## Configuring quotas

You can set quotas using the Neon API either in a `POST` when you create a project or a `PATCH` to update an existing project:

- [Set quotas when you create the project](https://neon.com/docs/guides/consumption-limits#set-quotas-when-you-create-the-project)
- [Update an existing project](https://neon.com/docs/guides/consumption-limits#update-an-existing-project)

### Set quotas when you create the project

For performance reasons, you might want to configure these quotas at the same time that you create a new project for your user using the [Create a project](https://neon.com/docs/reference/api/projects/create-project) API, reducing the number of API calls you need to make.

Here is a sample `POST` in `curl` that creates a new project called `UserNew` and sets the `active_time_seconds` quota to a total allowed time of 10 hours (36,000 seconds) for the month, and a total allowed `compute_time_seconds` set to 2.5 hours (9,000 seconds) for the month. This 4:1 ratio between active and compute time is suitable for a fixed compute size of 0.25 CU.

```bash {11,12}
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "project": {
    "settings": {
      "quota": {
        "active_time_seconds": 36000,
        "compute_time_seconds": 9000
      }
    },
    "pg_version": 15,
    "name": "UserProject"
  }
}
' | jq
```

### Update an existing project

If you need to change the quota limits for an existing project (for example, if a user switches their plan to a higher usage tier), you can reset those limits via `PATCH` request. See [Update a project](https://neon.com/docs/reference/api/projects/update-project) in the Neon API.

Here is a sample `PATCH` that updates both the `active_time_seconds` and `compute_time_seconds` quotas to 30 hours (108,000):

```bash {11,12}
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/[project_ID]\
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "project": {
    "settings": {
      "quota": {
        "active_time_seconds": 108000,
        "compute_time_seconds": 108000
      }
    }
  }
}
' | jq
```

## Querying metrics and quotas

You can use the Neon API to retrieve consumption metrics for your organization and projects using the [Granular metrics per project](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project) endpoint, which provides detailed metrics for each project at hourly, daily, or monthly granularity. See [Get granular project-level metrics](https://neon.com/docs/guides/consumption-metrics-legacy#project-level-endpoint) for details.

## Resetting a project after suspend

Projects remain suspended until the next billing period. It is good practice to notify your users when they are close to reaching a limit; if the user is then suspended and loses access to their database, it will not be unexpected. If you have configured no further actions, the user will have to wait until the next billing period starts to resume usage.

Alternatively, you can actively reset a suspended compute by changing the impacted quota to `0`: this effectively removes the limit entirely. You will need to reset this quota at some point if you want to maintain limits.

### Using quotas to actively suspend a user

If you want to suspend a user for any reason (for example, suspicious activity or payment issues), you can use these quotas to actively suspend a given user. For example, setting `active_time_seconds` to a very low threshold (for example, `1`) will force a suspension if the user has 1 second of active compute for that month. To remove this suspension, you can set the threshold temporarily to `0` (infinite) or some value larger than their currently consumed usage.

## Other consumption related settings

In addition to setting quota limits against the project as a whole, there are other sizing-related settings you might want to use to control the amount of resources any particular endpoint is able to consume:

- `autoscaling_limit_min_cu`: Sets the minimum compute size for the endpoint. The default minimum is .25 CU but can be increased if your user's project could benefit from a larger compute start size.
- `autoscaling_limit_max_cu`: Sets a hard limit on how much compute an endpoint can consume in response to increased demand. For more info on min and max cpu limits, see [Autoscaling](https://neon.com/docs/guides/autoscaling-guide).
- `suspend_timeout_seconds`: Sets how long an endpoint's allotted compute will remain active with no current demand. After the timeout period, the endpoint is suspended until demand picks up. For more info, see [Scale to Zero](https://neon.com/docs/guides/scale-to-zero-guide).

There are several ways you can set these endpoint settings using the Neon API: you can set project-level defaults that apply for any new computes created in the project, you can define the endpoint settings when creating a new branch, or you can adjust these settings when creating or updating an endpoint for an existing branch.

See these sample CURL requests for each method.

**Project**

In this sample, we are setting defaults for all new endpoints created in the project as a whole. The minimum compute size is at **1 CU**, the max size at **3 CU**, and a 10 minute (**600 seconds**) inactivity period before the endpoint is suspended.

These default values are set in the
`default_endpoint_settings` object.

```bash {9-12}
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "project": {
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 3,
      "suspend_timeout_seconds": 600
    },
    "pg_version": 15
  }
}
' | jq
```

**Branch**

In this POST request, we are creating a new endpoint at the same time that we create our new branch called `Development`. We've sized the endpoint at **1 CU** min, **3 CU** max, and with a timeout period of 10 minutes (**600 seconds**).

```bash {14-16}
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/noisy-pond-28482075/branches \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "branch": {
    "name": "Development"
  },
  "endpoints": [
    {
      "type": "read_write",
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 3,
      "suspend_timeout_seconds": 600
    }
  ]
}
' | jq
```

**Endpoint**

In this example, we are creating a new endpoint for an already existing branch with ID `br-wandering-field-12345678`, with a min compute of **2 CU**, a max of **6 CU**, and a suspend timeout of 5 minutes (**300** seconds).

```bash {10-13}
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/noisy-pond-28482075/endpoints \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "endpoint": {
    "type": "read_write",
    "autoscaling_limit_min_cu": 2,
    "autoscaling_limit_max_cu": 6,
    "suspend_timeout_seconds": 300,
    "branch_id": "br-wandering-field-12345678"
  }
}
' | jq
```

--- [Document source](https://neon.com/docs/guides/consumption-metrics-legacy.md) ---

> Summary: The legacy Neon consumption API provides the `/consumption_history/projects` endpoint that returns active_time_seconds, compute_time_seconds, written_data_bytes, and synthetic_storage_size_bytes for accounts on Scale plans and above (legacy Scale, Business, Enterprise, and usage-based Scale+), with history available from March 1, 2024. This endpoint is not available on Launch and does not return invoice-aligned metrics on usage-based plans. For metrics that match your invoice or for Launch plan access, use the Query consumption metrics page instead.

# Query consumption metrics (legacy)

Legacy project consumption API for Scale, Business, and Enterprise plans

Last updated: 2026-07-15

Using the Neon API, you can query project-level consumption metrics with the legacy endpoint. The Management API only allows this path for **Scale plans and above** (legacy **Scale, Business, and Enterprise**, and usage-based **Scale** and higher). It is **not** available on **Launch**; use [`GET /consumption_history/v2/projects`](https://neon.com/docs/guides/consumption-metrics) instead. On every eligible plan, this endpoint returns **legacy metrics** only (active time, compute time, written data, synthetic storage). On a usage-based plan, those metrics do not match your invoice; for invoice-aligned metrics use the [project metrics endpoint](https://neon.com/docs/guides/consumption-metrics) in Query consumption metrics.

| API                 | Endpoint                        | Description                               | Available on                                                          |
| ------------------- | ------------------------------- | ----------------------------------------- | --------------------------------------------------------------------- |
| **Project metrics** | `/consumption_history/projects` | Per-project metrics at chosen granularity | Scale, Business, Enterprise (legacy); usage-based Scale+ (not Launch) |

Issuing calls to these APIs does not wake a project's compute endpoints.

**Tip:** **Which API should I use?** For metrics that match your **invoice** on a usage-based plan (including **Launch**), use the project metrics API in [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics); it is the only endpoint that returns usage-based billing metrics. For a guide to converting those metrics into billing units and calculating costs, see [Usage and cost calculations](https://neon.com/docs/introduction/usage-calculations). Use the endpoints on this page when you need **legacy metrics** and your organization is on **Scale plans and above** (see table above). These paths always return legacy metrics only, even on usage-based Scale+.

## Request overview

The legacy endpoints return consumption data for legacy billing plans. Date format, range limits, and granularity are the same as the usage-based endpoint; for details see [Date format, range, and granularity](https://neon.com/docs/guides/consumption-metrics#date-format-range-and-granularity) in Query consumption metrics. Consumption history is available from March 1, 2024, at 00:00:00 UTC.

### Metrics

Both endpoints return metrics that align with legacy billing. Default metrics are returned unless you specify otherwise with the `metrics` parameter:

| Metric                         | Unit       | Description                                                                                                                                                |
| ------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `active_time_seconds`          | Seconds    | Time compute endpoints have been active                                                                                                                    |
| `compute_time_seconds`         | Seconds    | CPU seconds used by compute endpoints (see [Legacy metric definitions](https://neon.com/docs/guides/consumption-metrics-legacy#legacy-metric-definitions)) |
| `written_data_bytes`           | Bytes      | Total data written to all of a project's branches                                                                                                          |
| `synthetic_storage_size_bytes` | Bytes      | Storage used (logical data + WAL for all branches)                                                                                                         |
| `data_storage_bytes_hour`      | Bytes-Hour | Storage consumed hourly (optional)                                                                                                                         |
| `logical_size_bytes`           | Bytes      | Logical size consumed (optional)                                                                                                                           |
| `logical_size_bytes_hour`      | Bytes-Hour | Logical size consumed hourly (optional)                                                                                                                    |

### Project-level endpoint

**Endpoint:**

```bash
GET https://console.neon.tech/api/v2/consumption_history/projects
```

Retrieves consumption metrics per project at the chosen granularity. The same **Scale plans and above** access rule applies as for the account endpoint (not available on **Launch**—use [v2 project metrics](https://neon.com/docs/guides/consumption-metrics) instead). Results are ordered by time in ascending order (oldest to newest). History begins at the time of upgrade. Issuing a call to this API does not wake a project's compute endpoint.

#### Required parameters

- **`from`** (date-time, required): Start of the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. Consumption history is available from March 1, 2024, at 00:00:00 UTC. The range must respect the granularity limits (hourly: last 168 hours; daily: last 60 days; monthly: last year).
- **`to`** (date-time, required): End of the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. The range must respect the same granularity limits as `from`.
- **`granularity`** (string, required): Granularity of consumption metrics. `hourly` (last 168 hours), `daily` (last 60 days), or `monthly` (last year).

#### Optional parameters

- **`project_ids`** (array of strings, 0-100 items): Filter to specific project IDs. If omitted, the response contains all projects. Can be an array of parameter values or a comma-separated list in a single parameter value.
- **`org_id`** (string): Organization for which to return project consumption metrics. If not provided, returns metrics for the authenticated user's projects.
- **`metrics`** (array of strings): Metrics to include. If omitted, `active_time_seconds`, `compute_time_seconds`, `written_data_bytes`, and `synthetic_storage_size_bytes` are returned. Possible values: `active_time_seconds`, `compute_time_seconds`, `written_data_bytes`, `synthetic_storage_size_bytes`, `data_storage_bytes_hour`, `logical_size_bytes`, `logical_size_bytes_hour`. Can be an array or comma-separated list.
- **`limit`** (integer, 1-100): Number of projects in the response. Default: `10`.
- **`cursor`** (string): Cursor value from the previous response to get the next batch of projects.

The **`include_v1_metrics`** parameter is deprecated; use **`metrics`** instead. If `metrics` is specified, `include_v1_metrics` is ignored.

### Legacy metric definitions

**Default metrics** (returned when `metrics` is omitted):

- **active_time_seconds**: Seconds. The amount of time the compute endpoints have been active.
- **compute_time_seconds**: Seconds. The number of CPU seconds used by compute endpoints, including compute endpoints that have been deleted. For example: 1 CPU for 1 second = 1; 2 CPUs for 1 second = 2.
- **written_data_bytes**: Bytes. The amount of written data for all branches.
- **synthetic_storage_size_bytes**: Bytes. The space occupied in storage. Synthetic storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches.

**Additional metrics** (include via the `metrics` parameter):

- **data_storage_bytes_hour**: Bytes-Hour. The amount of storage consumed hourly.
- **logical_size_bytes**: Bytes. The amount of logical size consumed.
- **logical_size_bytes_hour**: Bytes-Hour. The amount of logical size consumed hourly.

## Example request and response

Replace `$NEON_API_KEY` with your API key and include `org_id` if needed.

### Project-level

```bash
curl --request GET \
  --url 'https://console.neon.tech/api/v2/consumption_history/projects?from=2024-06-30T00:00:00Z&to=2024-07-02T00:00:00Z&granularity=daily&org_id=org-ocean-art-12345678&limit=10' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer $NEON_API_KEY'
```

<details>

<summary>Response body (project)</summary>

```json
{
  "projects": [
    {
      "project_id": "random-project-123456",
      "periods": [
        {
          "period_id": "random-period-abcdef",
          "period_plan": "scale",
          "period_start": "2024-06-01T00:00:00Z",
          "period_end": "2024-07-01T00:00:00Z",
          "consumption": [
            {
              "timeframe_start": "2024-06-30T00:00:00Z",
              "timeframe_end": "2024-07-01T00:00:00Z",
              "active_time_seconds": 147472,
              "compute_time_seconds": 43222,
              "written_data_bytes": 112730864,
              "synthetic_storage_size_bytes": 37000959232
            },
            {
              "timeframe_start": "2024-07-01T00:00:00Z",
              "timeframe_end": "2024-07-02T00:00:00Z",
              "active_time_seconds": 1792,
              "compute_time_seconds": 533,
              "written_data_bytes": 0,
              "synthetic_storage_size_bytes": 0
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "random-project-123456"
  }
}
```

</details>

**Tip:** You can request specific metrics with the `metrics` parameter (for example, `metrics=active_time_seconds,compute_time_seconds`).

For full parameter and response details, see [Retrieve project consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project) in the Neon API Reference.

The following sections cover paging (project endpoint), polling behavior, and handling errors.

## Pagination

The **project-level** endpoint uses cursor-based pagination. The response includes a `pagination` object with a `cursor` value (the project ID of the last project in the list). To get the next page, send another request with that `cursor` in the query string and the same `from`, `to`, and `granularity` as your first request.

Example request for the next page (using the `cursor` from the previous response):

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/consumption_history/projects?cursor=divine-tree-77657175&limit=10&from=2024-06-30T00%3A00%3A00Z&to=2024-07-02T00%3A00%3A00Z&granularity=daily&org_id=org-ocean-art-12345678' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

In the URL above, the **`cursor`** parameter is `cursor=divine-tree-77657175`. Replace that value with the `cursor` from your previous response's `pagination` object.

## Consumption polling

Neon's consumption data is updated approximately every 15 minutes. A minimum interval of 15 minutes between API calls is recommended. For reporting or invoicing, you can pull usage data at that interval or choose your own; Neon does not dictate how often you poll or how you bill your users.

The legacy and usage-based consumption API endpoints share a single rate limiter of approximately 50 requests per minute per account. Neon uses a **token bucket** approach, which refills at a steady rate and allows short bursts within the bucket size, so the limit behaves like a sliding window rather than a fixed reset every minute. For more details, see [Token bucket](https://en.wikipedia.org/wiki/Token_bucket).

Calling the consumption APIs does not wake computes that have been suspended due to inactivity, so polling will not increase your consumption.

The endpoints on this page return **legacy metrics** only; when your organization is eligible (Scale+), you can call them on legacy or usage-based plans, but responses will not match your invoice on a usage-based plan. For metrics that match your invoice—or for **Launch** plans—see [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics).

## Error responses

Common error responses you may encounter:

- **403 Forbidden**: These endpoints are not available for your plan. The API response states that access is included with **Scale plans and above** (legacy **Scale, Business, and Enterprise**, and usage-based **Scale** and higher—not **Launch**).
- **404 Not Found**: Account is not a member of the organization specified by `org_id`.
- **406 Not Acceptable**: The specified date-time range is outside the boundaries of the specified granularity. Adjust your `from` and `to` values or select a different `granularity`.
- **429 Too Many Requests**: Too many requests. Wait before retrying.

## Usage-based pricing and legacy API limitations

The legacy endpoints on this page were designed for Neon's legacy billing plans and do not align with [usage-based plans](https://neon.com/docs/introduction/plans). If you're on a usage-based plan (Launch, Scale, Agent, or Enterprise), use [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics) for metrics that map to your invoice.

**Legacy API:** Uses `synthetic_storage_size_bytes` (logical data + WAL for all branches in one metric).

**Usage-based API:** Returns separate metrics that match your invoice: `root_branch_bytes_month`, `child_branch_bytes_month`, `instant_restore_bytes_month`, `snapshot_storage_bytes_month`, `public_network_transfer_bytes`, `private_network_transfer_bytes`, `extra_branches_month`, and `compute_unit_seconds`. The legacy APIs do not provide these. Use the [project metrics endpoint](https://neon.com/docs/guides/consumption-metrics#request-overview) in Query consumption metrics to retrieve them.

--- [Document source](https://neon.com/docs/guides/consumption-metrics.md) ---

> Summary: The Neon consumption metrics API (/consumption_history/v2) returns project usage metrics for compute, storage, data transfer, extra branches, and Functions, plus per-branch metrics. It is available on Launch, Scale, Agent, and Enterprise plans. Use the project endpoint for project totals and invoicing inputs; use the branch endpoint to attribute compute, storage, and Functions usage to individual branches, CI environments, or development workflows. Granularity options are hourly, daily, and monthly. Calls do not wake suspended compute endpoints.

# Querying consumption metrics

Learn how to query project consumption metrics for usage-based plans using the Neon API

Last updated: 2026-10-31

Using the Neon API, you can query consumption metrics to track your resource usage. This page covers the two v2 metrics endpoints for usage-based plans. To monitor usage in the Console instead, see [Monitor billing and usage](https://neon.com/docs/introduction/monitor-usage).

| API                               | Endpoint                           | Description                                                                                | Plan availability                |
| --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------- |
| **Project metrics (usage-based)** | `/consumption_history/v2/projects` | Returns project metrics for compute, storage, data transfer, extra branches, and Functions | Launch, Scale, Agent, Enterprise |
| **Branch metrics**                | `/consumption_history/v2/branches` | Returns 10 project metrics broken down by branch, across one or more projects              | Launch, Scale, Agent, Enterprise |

**Tip:**

**Which API should I use?**

- For usage totals per project, use the [project metrics API](https://neon.com/docs/guides/consumption-metrics#request-overview). It's the only endpoint that returns all 12 project metrics, including snapshot storage, extra branches, and Functions metrics.
- To attribute usage to individual branches within a project, for example, to see which CI or development branches are driving compute, storage, or Functions usage, use the [branch metrics API](https://neon.com/docs/guides/consumption-metrics#branch-metrics).
- For legacy metrics on older plans, see the [legacy APIs](https://neon.com/docs/guides/consumption-metrics-legacy).

**Note: API reference: legacy vs v2**

In the [API reference](https://neon.com/docs/reference/api), two similarly named pages cover different paths. **Retrieve project consumption metrics (legacy plans)** is **`GET /consumption_history/projects`** and lists older metrics such as `active_time_seconds` and `compute_time_seconds`. **Retrieve project consumption metrics** (no "legacy plans" in the title) is **`GET /consumption_history/v2/projects`** and documents usage-based metrics, including snapshot storage and Functions metrics, in the **`metrics`** parameter. That v2 page matches this guide; see **[Retrieve project consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project-v2)**.

## Request overview

Retrieves consumption metrics for Launch, Scale, Agent, and Enterprise plan projects. Returns project usage metrics. History begins at the time of upgrade. Results are ordered by time in ascending order (oldest to newest). Issuing a call to this API does not wake a project's compute endpoint.

**Endpoint:**

```bash
GET https://console.neon.tech/api/v2/consumption_history/v2/projects
```

### Metrics

The response includes these usage metrics:

| Metric                                    | Raw unit              | Converted unit      | Description                                                                                                                                                                                                                    |
| ----------------------------------------- | --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `compute_unit_seconds`                    | CU-seconds            | CU-hours            | CPU time weighted by compute size                                                                                                                                                                                              |
| `root_branch_bytes_month`                 | byte-months           | GB-months           | Storage consumed by root branches                                                                                                                                                                                              |
| `child_branch_bytes_month`                | byte-months           | GB-months           | Storage consumed by child branches (delta from parent)                                                                                                                                                                         |
| `instant_restore_bytes_month`             | byte-months           | GB-months           | Instant restore (PITR) history storage                                                                                                                                                                                         |
| `snapshot_storage_bytes_month`            | byte-months           | GB-months           | Storage for [branch snapshots](https://neon.com/docs/guides/backup-restore): manual snapshots are full; scheduled snapshots are full for the first snapshot, then incremental (delta) for subsequent snapshots in the schedule |
| `public_network_transfer_bytes`           | bytes                 | GB                  | Data transfer over the public internet                                                                                                                                                                                         |
| `private_network_transfer_bytes`          | bytes                 | GB                  | Data transfer over private networks (for example, AWS PrivateLink)                                                                                                                                                             |
| `extra_branches_month`                    | branch-hours          | branch-months       | All child branches per hour (subtract plan allowance before billing)                                                                                                                                                           |
| `functions_active_capacity_microseconds`  | capacity-microseconds | Capacity-Hours      | Time Functions spend actively using CPU                                                                                                                                                                                        |
| `functions_waiting_capacity_microseconds` | capacity-microseconds | Capacity-Hours      | Time Functions spend waiting on I/O                                                                                                                                                                                            |
| `functions_invocations`                   | invocations           | million invocations | Number of function calls                                                                                                                                                                                                       |
| `functions_egress_bytes`                  | bytes                 | GB                  | Data sent by Functions                                                                                                                                                                                                         |

Use `snapshot_storage_bytes_month` for invoice-aligned, time-windowed snapshot storage reporting.

The four Functions metrics are available from both v2 endpoints. For current Functions rates, see [Plans](https://neon.com/docs/introduction/plans#functions).

To convert these raw values into readable units and, where applicable, calculate costs, see [Usage and cost calculations](https://neon.com/docs/introduction/usage-calculations).

### Required parameters

- **`from`** (date-time, required): Start date-time for the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. The earliest allowed value is March 1, 2024, at 00:00:00 UTC. Metrics are returned from when the account upgraded to an eligible plan, which may be later. The range must respect the granularity limits (hourly: last 168 hours; daily: last 60 days; monthly: last year).
- **`to`** (date-time, required): End date-time for the consumption period in RFC 3339 format. The value is rounded according to the specified granularity. The range must respect the same granularity limits as `from`.
- **`granularity`** (string, required): Granularity of consumption metrics. Hourly, daily, and monthly metrics are available for the last 168 hours, 60 days, and 1 year, respectively.
- **`org_id`** (string, required): Organization for which the project consumption metrics should be returned.
- **`metrics`** (array of strings, required): List of metrics to include in the response. Possible values: `compute_unit_seconds`, `root_branch_bytes_month`, `child_branch_bytes_month`, `instant_restore_bytes_month`, `snapshot_storage_bytes_month`, `public_network_transfer_bytes`, `private_network_transfer_bytes`, `extra_branches_month`, `functions_active_capacity_microseconds`, `functions_waiting_capacity_microseconds`, `functions_invocations`, `functions_egress_bytes`. Can be an array of parameter values or a comma-separated list in a single parameter value.

### Date format, range, and granularity

The API requires timestamps in RFC 3339 format (for example, `2024-06-30T15:30:00Z`), including date, time, and timezone; the `Z` indicates UTC. You can use a [timestamp converter](https://it-tools.tech/date-converter) to generate RFC 3339 formatted timestamps. The earliest allowed `from` value is March 1, 2024, at 00:00:00 UTC. Project metrics begin when the account upgrades to an eligible plan, which may be later.

When setting `from` and `to`, keep these limits in mind based on your chosen granularity:

| Granularity | Maximum time range      | Rounding behavior                |
| ----------- | ----------------------- | -------------------------------- |
| `hourly`    | Last 168 hours (7 days) | Rounds to the nearest hour       |
| `daily`     | Last 60 days            | Rounds to the start of the day   |
| `monthly`   | Last year               | Rounds to the start of the month |

Date-time values are automatically rounded according to the specified granularity. For example, `2024-03-15T15:30:00Z` with daily granularity becomes `2024-03-15T00:00:00Z`.

### Optional parameters

- **`project_ids`** (array of strings, 0-100 items): Filter to specific project IDs. If omitted, the response contains all projects. Can be an array of parameter values or a comma-separated list in a single parameter value.
- **`limit`** (integer, 1-100): Number of projects in the response. Default: `10`.
- **`cursor`** (string): Cursor value from the previous response to get the next batch of projects.

## Example request and response

Replace `$ORG_ID` and `$NEON_API_KEY` with your organization ID and API key, then run the following to retrieve daily metrics for a date range.

```bash
curl --request GET \
  --url 'https://console.neon.tech/api/v2/consumption_history/v2/projects?from=2026-02-01T00:00:00Z&to=2026-02-06T00:00:00Z&granularity=daily&org_id=$ORG_ID&metrics=compute_unit_seconds,root_branch_bytes_month,child_branch_bytes_month,instant_restore_bytes_month,snapshot_storage_bytes_month,public_network_transfer_bytes,private_network_transfer_bytes,extra_branches_month,functions_active_capacity_microseconds,functions_waiting_capacity_microseconds,functions_invocations,functions_egress_bytes' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $NEON_API_KEY' | jq
```

**Note:** `snapshot_storage_bytes_month` reflects snapshot storage for billing over the selected time window. Manual snapshots are billed as full snapshots. Scheduled snapshots are billed as full snapshots for the first scheduled snapshot, then as incremental (delta) storage for subsequent scheduled snapshots.

<details>

<summary>Response body</summary>

```json
{
  "projects": [
    {
      "project_id": "delicate-dawn-54854667",
      "periods": [
        {
          "period_id": "90c7f107-3fe7-4652-b1da-c61f71043128",
          "period_plan": "launch",
          "period_start": "2026-02-02T18:04:52Z",
          "consumption": [
            {
              "timeframe_start": "2026-02-04T00:00:00Z",
              "timeframe_end": "2026-02-05T00:00:00Z",
              "metrics": [
                {
                  "metric_name": "compute_unit_seconds",
                  "value": 84
                },
                {
                  "metric_name": "root_branch_bytes_month",
                  "value": 758513664
                },
                {
                  "metric_name": "instant_restore_bytes_month",
                  "value": 98344
                },
                {
                  "metric_name": "snapshot_storage_bytes_month",
                  "value": 0
                },
                {
                  "metric_name": "public_network_transfer_bytes",
                  "value": 1414
                }
              ]
            },
            {
              "timeframe_start": "2026-02-05T00:00:00Z",
              "timeframe_end": "2026-02-06T00:00:00Z",
              "metrics": [
                {
                  "metric_name": "compute_unit_seconds",
                  "value": 236
                },
                {
                  "metric_name": "root_branch_bytes_month",
                  "value": 758611968
                },
                {
                  "metric_name": "instant_restore_bytes_month",
                  "value": 983488
                },
                {
                  "metric_name": "snapshot_storage_bytes_month",
                  "value": 0
                },
                {
                  "metric_name": "public_network_transfer_bytes",
                  "value": 2184
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "delicate-dawn-54854667"
  }
}
```

</details>

**Tip:** You can also query individual metrics by specifying only the ones you need in the `metrics` parameter. Metrics with a value of zero for a given timeframe may be omitted from the response.

For full API details including all parameters and response schema, see [Retrieve project consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project-v2). To build a request for a custom time range, use the prompt below with an AI assistant.

Copy this prompt to have an AI assistant help you build the curl command for your desired time period. [View prompt](https://neon.com/prompts/consumption-api-prompt.md)

The following sections cover paging through many projects, polling behavior, and handling errors.

## Pagination

The project consumption metrics endpoint uses cursor-based pagination. The response includes a `pagination` object with a `cursor` value (the project ID of the last project in the list). To get the next page, send another request with that `cursor` in the query string and the same `from`, `to`, `granularity`, `org_id`, and `metrics` as your first request.

Example request for the next page (using the `cursor` from the previous response):

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/consumption_history/v2/projects?cursor=divine-tree-77657175&limit=10&from=2024-06-30T00%3A00%3A00Z&to=2024-07-02T00%3A00%3A00Z&granularity=daily&org_id=$ORG_ID&metrics=compute_unit_seconds,root_branch_bytes_month,child_branch_bytes_month,instant_restore_bytes_month,snapshot_storage_bytes_month,public_network_transfer_bytes,private_network_transfer_bytes,extra_branches_month,functions_active_capacity_microseconds,functions_waiting_capacity_microseconds,functions_invocations,functions_egress_bytes' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

In the URL above, the **`cursor`** parameter is `cursor=divine-tree-77657175`. Replace that value with the `cursor` from your previous response's `pagination` object.

## Consumption polling

Neon's consumption data is updated approximately every 15 minutes. A minimum interval of 15 minutes between API calls is recommended. For reporting or invoicing, you can pull usage data at that interval or choose your own; Neon does not dictate how often you poll or how you bill your users.

The consumption API endpoints share a single rate limiter of approximately 50 requests per minute per account. Neon uses a **token bucket** approach, which refills at a steady rate and allows short bursts within the bucket size, so the limit behaves like a sliding window rather than a fixed reset every minute. For more details, see [Token bucket](https://en.wikipedia.org/wiki/Token_bucket).

Calling the consumption APIs does not wake computes that have been suspended due to inactivity, so polling will not increase your consumption.

The [project metrics endpoint](https://neon.com/docs/guides/consumption-metrics#request-overview) on this page returns project usage metrics. The legacy APIs return different metrics that don't map to usage-based line items; see [Query consumption metrics (legacy)](https://neon.com/docs/guides/consumption-metrics-legacy) for those endpoints.

## Error responses

Common error responses you may encounter:

- **403 Forbidden**: This endpoint is not available for your plan. It is only supported with Launch, Scale, Agent, and Enterprise plan accounts.
- **404 Not Found**: Account is not a member of the organization specified by `org_id`.
- **406 Not Acceptable**: The specified date-time range is outside the boundaries of the specified granularity. Adjust your `from` and `to` values or select a different `granularity`.
- **429 Too Many Requests**: Too many requests. Wait before retrying.

## Build a usage dashboard

For a full example that uses this API to build a usage dashboard with Next.js (including charts, project filtering, and reporting), see [Building a Usage Dashboard with Neon's Consumption API](https://neon.com/guides/usage-dashboard-consumption-api). The guide includes a [sample application on GitHub](https://github.com/dhanushreddy291/neon-usage-dashboard) that you can clone and run to visualize your usage-based metrics.

## Branch metrics

The branch metrics endpoint returns per-branch consumption data across one or more projects. Use it when you need to see which branches within a project are driving usage, for example, attributing compute costs across CI branches, development environments, or feature branches.

**Endpoint:**

```bash
GET https://console.neon.tech/api/v2/consumption_history/v2/branches
```

### Metrics

Ten of the 12 project metrics are available on this endpoint:

| Metric                                    | Description                             |
| ----------------------------------------- | --------------------------------------- |
| `compute_unit_seconds`                    | CPU time weighted by compute size       |
| `root_branch_bytes_month`                 | Storage consumed by root branches       |
| `child_branch_bytes_month`                | Storage consumed by child branches      |
| `instant_restore_bytes_month`             | Instant restore (PITR) history storage  |
| `public_network_transfer_bytes`           | Data transfer over the public internet  |
| `private_network_transfer_bytes`          | Data transfer over private networks     |
| `functions_active_capacity_microseconds`  | Time Functions spend actively using CPU |
| `functions_waiting_capacity_microseconds` | Time Functions spend waiting on I/O     |
| `functions_invocations`                   | Number of function calls                |
| `functions_egress_bytes`                  | Data sent by Functions                  |

`extra_branches_month` and `snapshot_storage_bytes_month` are not available on this endpoint. Use the [project metrics endpoint](https://neon.com/docs/guides/consumption-metrics#request-overview) for those.

### Required parameters

- **`project_ids`** (array of strings, 1-100, required): Projects to include. Unlike the project endpoint, `project_ids` is always required here.
- **`from`** (date-time, required): Start of the consumption period in RFC 3339 format.
- **`to`** (date-time, required): End of the consumption period in RFC 3339 format.
- **`granularity`** (string, required): `hourly`, `daily`, or `monthly`. Subject to the same window limits as the project endpoint.
- **`org_id`** (string, required): Organization ID.
- **`metrics`** (array of strings, required): One or more of the 10 supported metrics above.

### Optional parameters

- **`branch_ids`** (array of strings, up to 100): Filter to specific branches. If omitted, all branches in the specified projects are returned.
- **`limit`** (integer, 1-1000): Branches per page. Default: 100.
- **`cursor`** (string): Pagination cursor from the previous response.

### Example request and response

```bash
curl --request GET \
  --url 'https://console.neon.tech/api/v2/consumption_history/v2/branches?project_ids=$PROJECT_ID&org_id=$ORG_ID&from=2026-05-01T00:00:00Z&to=2026-05-29T00:00:00Z&granularity=daily&metrics=compute_unit_seconds,root_branch_bytes_month,child_branch_bytes_month' \
  --header 'Authorization: Bearer $NEON_API_KEY' \
  --header 'Accept: application/json' | jq
```

<details>

<summary>Response body</summary>

```json
{
  "branches": [
    {
      "branch_id": "br-young-sky-a1b2c3d4",
      "project_id": "calm-night-03860858",
      "periods": [
        {
          "period_id": "7f3a1c2d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
          "period_plan": "launch",
          "period_start": "2026-05-01T00:00:00Z",
          "consumption": [
            {
              "timeframe_start": "2026-05-01T00:00:00Z",
              "timeframe_end": "2026-05-02T00:00:00Z",
              "metrics": [
                { "metric_name": "compute_unit_seconds", "value": 1440 },
                { "metric_name": "root_branch_bytes_month", "value": 875309056 },
                { "metric_name": "child_branch_bytes_month", "value": 0 }
              ]
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "br-young-sky-a1b2c3d4"
  }
}
```

</details>

For full API details, see [Retrieve branch consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-branch-v2).

--- [Document source](https://neon.com/docs/guides/datadog.md) ---

> Summary: The Neon Datadog integration exports Postgres metrics and logs from all project computes to Datadog, available on Scale plan projects. Use this page to set up monitoring of CPU, memory, connection counts, replication lag, database size, deadlocks, and PgBouncer stats, or to forward Postgres logs for error and activity visibility. Postgres log export is in beta. Log transmission counts toward your plan's public network transfer allowance.

# Datadog integration

Send metrics and logs from Lakebase Postgres on Neon to Datadog

Last updated: 2026-10-14

**What you will learn:**

- How to set up the integration
- How to configure log forwarding
- The full list of externally-available metrics

**External docs**

- [Datadog API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys/)
- [Identify Datadog site](https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site/)

Available for Scale plan users, the Neon Datadog integration lets you monitor database performance, resource utilization, and system health directly from Datadog's observability platform.

## How it works

The integration exports Neon metrics and Postgres logs to Datadog. By configuring the integration with your Datadog API key, Neon automatically sends data from your project to your selected Datadog site.

**Note:** Data is sent for all computes in your Neon project. For example, if you have multiple branches, each with an attached compute, both metrics and logs will be collected and sent for each compute.

### Neon metrics

The integration exports [a set of metrics](https://neon.com/docs/guides/datadog#available-metrics) including:

- **Connection counts**: Tracks active and idle database connections.
- **Database size**: Monitors total size of all databases in bytes.
- **Replication delay**: Measures replication lag in bytes and seconds.
- **Compute metrics**: Includes CPU and memory usage statistics for your compute.
- **PgBouncer metrics**: Tracks connection pooling metrics including client and server connections.

### Postgres logs

**Note: Beta**

**Postgres logs export** is in beta. Share your feedback on [Discord](https://neon.com/discord) or via the [Neon Console](https://console.neon.tech/app/projects?modal=feedback).

The Neon Datadog integration can forward Postgres logs to your Datadog account. These logs provide visibility into database activity, errors, and performance. See [Export Postgres logs to Datadog](https://neon.com/docs/guides/datadog#export-postgres-logs-to-datadog) for details.

## Prerequisites

Before getting started, ensure the following:

- You have a Neon account and project. If not, see [Sign up for a Neon account](https://neon.com/docs/get-started/signing-up).
- You have a Datadog account and API key.
- You know the region you selected for your Datadog account. Here's how to check: [Find your Datadog region](https://docs.datadoghq.com/getting_started/site/#access-the-datadog-site)

## Steps to integrate Datadog with Neon

1. In the Neon Console, navigate to the **Integrations** page in your Neon project.
2. Locate the **Datadog** card and click **Add**.
3. Enter your **Datadog API key**. You can generate or retrieve [Datadog API Keys](https://app.datadoghq.com/organization-settings/api-keys) from your Datadog organization. For instructions, see [Datadog API and Application Keys](https://docs.datadoghq.com/account_management/api-app-keys/).
4. Select the Datadog **site** that you used when setting up your Datadog account. The supported sites are US1 (`datadoghq.com`), US3 (`us3.datadoghq.com`), US5 (`us5.datadoghq.com`), EU1 (`datadoghq.eu`), US1-FED (`ddog-gov.com`), and AP1 (`ap1.datadoghq.com`).
5. Select what you want to export. You can enable either or both:
   - **Metrics**: System metrics and database statistics (CPU, memory, connections, etc.)
   - **Postgres logs**: Error messages, warnings, connection events, and system notifications
6. Click **Save** to complete the integration.

**Note:** You can change these settings later by editing your integration configuration.

Optionally, you can import the Neon-provided JSON configuration file into Datadog, which creates a pre-built dashboard from **Neon metrics** and **Postgres logs**, similar to the charts on the **Monitoring** page. See [Import the Neon dashboard](https://neon.com/docs/guides/datadog#import-the-neon-dashboard).

Once the integration is set up, Neon will start sending Neon metrics to Datadog, and you can use these metrics to create custom dashboards and alerts in Datadog.

**Note:** Neon computes only send logs and metrics when they are active. If [scale to zero](https://neon.com/docs/introduction/scale-to-zero) is enabled and a compute is suspended due to inactivity, no logs or metrics will be sent during the suspension. This may result in gaps in your Neon logs and metrics in Datadog. If you notice missing data in Datadog, check if your compute is suspended. You can verify a compute's status as `Idle` or `Active` on the **Branches** page in the Neon Console, and review **Suspend compute** events on the **System operations** tab of the **Monitoring** page.

Additionally, if you are setting up Neon's Datadog integration for a project with an inactive compute, you'll need to activate the compute before it can send metrics and logs to Datadog. To activate it, run a query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any connected client on the branch associated with the compute.

## Example usage in Datadog

Once integrated, you can create custom dashboards in Datadog by querying the metrics sent from Neon. Use Datadog's **Metrics Explorer** to search for metrics like `neon_connection_counts`, `neon_db_total_size`, and `host_cpu_seconds_total`. You can also set alerts based on threshold values for critical metrics.

### Filter by tag

Neon doesn't set the Datadog [unified service tags](https://docs.datadoghq.com/getting_started/tagging/unified_service_tagging/) (`env`, `service`, and `version`) on exported metrics or logs. To filter and group Neon data, use these tags instead:

- `project_id`: the Neon project
- `endpoint_id`: the compute. Each compute belongs to one branch, so you can use this tag to separate environments that run on different branches, such as production and staging.
- `compute_role`: `read_write` for a primary compute, or `read_only` for a read replica
- `region_id`: the region the project runs in
- `job`: the metric source (`compute-host-metrics`, `sql-metrics`, or `compute-pgbouncer-metrics`). Metrics only.

## Import the Neon dashboard

As part of the integration, Neon provides a JSON configuration file that you can import into Datadog to start with a pre-built dashboard based on a subset of Neon metrics, plus a Postgres logs stream.

![neon dashboard in datadog](https://neon.com/docs/guides/neon-dashboard-datadog.png)

Here's how you can import the dashboard:

1. In the Neon Console, open your Datadog integration from the **Integrations** page.

2. Scroll to the bottom of the panel and copy the JSON from there.

   OR

   You can copy the [JSON below](https://neon.com/docs/guides/datadog#dashboard-json) instead.

3. Next, create a new dashboard in Datadog.

4. Open **Configure**, select **Import dashboard JSON**, then paste the Neon-provided configuration JSON.

If any of the computes in your project are active, you should start seeing data in the resulting charts right away. By default, the charts show metrics for all active endpoints in your project. You can filter results to one or more selected endpoints using the **endpoint_id** variable dropdown selector.

![select endpoint variable in dashboard](https://neon.com/docs/guides/datadog_select_endpoint.png)

### Dashboard JSON

<details>

<summary>Copy JSON configuration</summary>

```json
{
  "title": "Single Neon Compute metrics (with dropdown)",
  "description": "",
  "widgets": [
    {
      "id": 3831219857468963,
      "definition": {
        "title": "RAM",
        "title_size": "16",
        "title_align": "left",
        "show_legend": true,
        "legend_layout": "auto",
        "legend_columns": [
          "avg",
          "min",
          "max",
          "value",
          "sum"
        ],
        "time": {},
        "type": "timeseries",
        "requests": [
          {
            "formulas": [
              {
                "number_format": {
                  "unit": {
                    "type": "canonical_unit",
                    "unit_name": "byte"
                  }
                },
                "alias": "Cached",
                "formula": "query3"
              },
              {
                "alias": "Used",
                "number_format": {
                  "unit": {
                    "type": "canonical_unit",
                    "unit_name": "byte"
                  }
                },
                "formula": "query1 - query2"
              }
            ],
            "queries": [
              {
                "name": "query3",
                "data_source": "metrics",
                "query": "max:host_memory_cached_bytes{$endpoint_id}"
              },
              {
                "name": "query1",
                "data_source": "metrics",
                "query": "max:host_memory_total_bytes{$endpoint_id}"
              },
              {
                "name": "query2",
                "data_source": "metrics",
                "query": "max:host_memory_available_bytes{$endpoint_id}"
              }
            ],
            "response_format": "timeseries",
            "style": {
              "palette": "dog_classic",
              "order_by": "values",
              "line_type": "solid",
              "line_width": "normal"
            },
            "display_type": "line"
          }
        ]
      },
      "layout": {
        "x": 0,
        "y": 0,
        "width": 6,
        "height": 2
      }
    },
    {
      "id": 7296782684811837,
      "definition": {
        "title": "CPU",
        "title_size": "16",
        "title_align": "left",
        "show_legend": true,
        "legend_layout": "auto",
        "legend_columns": [
          "avg",
          "min",
          "max",
          "value",
          "sum"
        ],
        "time": {},
        "type": "timeseries",
        "requests": [
          {
            "formulas": [
              {
                "alias": "Used",
                "formula": "per_minute(query1)"
              }
            ],
            "queries": [
              {
                "name": "query1",
                "data_source": "metrics",
                "query": "max:host_cpu_seconds_total{!mode:idle,$endpoint_id}.as_rate()"
              }
            ],
            "response_format": "timeseries",
            "style": {
              "palette": "dog_classic",
              "order_by": "values",
              "line_type": "solid",
              "line_width": "normal"
            },
            "display_type": "line"
          }
        ]
      },
      "layout": {
        "x": 6,
        "y": 0,
        "width": 6,
        "height": 2
      }
    },
    {
      "id": 7513607855022102,
      "definition": {
        "title": "Connections",
        "title_size": "16",
        "title_align": "left",
        "show_legend": true,
        "legend_layout": "auto",
        "legend_columns": [
          "avg",
          "min",
          "max",
          "value",
          "sum"
        ],
        "type": "timeseries",
        "requests": [
          {
            "formulas": [
              {
                "alias": "Total",
                "formula": "query1"
              },
              {
                "alias": "Active",
                "formula": "query2"
              },
              {
                "alias": "Idle",
                "formula": "query3"
              }
            ],
            "queries": [
              {
                "name": "query1",
                "data_source": "metrics",
                "query": "sum:neon_connection_counts{!datname:postgres,$endpoint_id}"
              },
              {
                "name": "query2",
                "data_source": "metrics",
                "query": "sum:neon_connection_counts{!datname:postgres,state:active ,$endpoint_id}"
              },
              {
                "name": "query3",
                "data_source": "metrics",
                "query": "sum:neon_connection_counts{!datname:postgres,!state:active,$endpoint_id}"
              }
            ],
            "response_format": "timeseries",
            "style": {
              "palette": "dog_classic",
              "order_by": "values",
              "line_type": "solid",
              "line_width": "normal"
            },
            "display_type": "line"
          }
        ]
      },
      "layout": {
        "x": 0,
        "y": 2,
        "width": 6,
        "height": 3
      }
    },
    {
      "id": 5523349536895199,
      "definition": {
        "title": "Database size",
        "title_size": "16",
        "title_align": "left",
        "show_legend": true,
        "legend_layout": "auto",
        "legend_columns": [
          "avg",
          "min",
          "max",
          "value",
          "sum"
        ],
        "type": "timeseries",
        "requests": [
          {
            "formulas": [
              {
                "number_format": {
                  "unit": {
                    "type": "canonical_unit",
                    "unit_name": "byte"
                  }
                },
                "formula": "query2"
              },
              {
                "number_format": {
                  "unit": {
                    "type": "canonical_unit",
                    "unit_name": "byte"
                  }
                },
                "alias": "Size of all databases",
                "formula": "query3"
              },
              {
                "alias": "Max size",
                "number_format": {
                  "unit": {
                    "type": "canonical_unit",
                    "unit_name": "byte"
                  }
                },
                "formula": "query1 * 1024 * 1024"
              }
            ],
            "queries": [
              {
                "name": "query2",
                "data_source": "metrics",
                "query": "max:neon_pg_stats_userdb{kind:db_size,$endpoint_id} by {datname}"
              },
              {
                "name": "query3",
                "data_source": "metrics",
                "query": "max:neon_db_total_size{$endpoint_id}"
              },
              {
                "name": "query1",
                "data_source": "metrics",
                "query": "max:neon_max_cluster_size{$endpoint_id}"
              }
            ],
            "response_format": "timeseries",
            "style": {
              "palette": "dog_classic",
              "order_by": "values",
              "line_type": "solid",
              "line_width": "normal"
            },
            "display_type": "line"
          }
        ],
        "yaxis": {
          "include_zero": false,
          "scale": "log"
        }
      },
      "layout": {
        "x": 6,
        "y": 2,
        "width": 6,
        "height": 3
      }
    },
    {
      "id": 1608572645458648,
      "definition": {
        "title": "Deadlocks",
        "title_size": "16",
        "title_align": "left",
        "show_legend": true,
        "legend_layout": "auto",
        "legend_columns": [
          "avg",
          "min",
          "max",
          "value",
          "sum"
        ],
        "type": "timeseries",
        "requests": [
          {
            "formulas": [
              {
                "alias": "Deadlocks",
                "formula": "query1"
              }
            ],
            "queries": [
              {
                "name": "query1",
                "data_source": "metrics",
                "query": "max:neon_pg_stats_userdb{kind:deadlocks,$endpoint_id} by {datname}"
              }
            ],
            "response_format": "timeseries",
            "style": {
              "palette": "dog_classic",
              "order_by": "values",
              "line_type": "solid",
              "line_width": "normal"
            },
            "display_type": "line"
          }
        ]
      },
      "layout": {
        "x": 0,
        "y": 5,
        "width": 6,
        "height": 2
      }
    },
    {
      "id": 5728659221127513,
      "definition": {
        "title": "Changed rows",
        "title_size": "16",
        "title_align": "left",
        "show_legend": true,
        "legend_layout": "auto",
        "legend_columns": [
          "avg",
          "min",
          "max",
          "value",
          "sum"
        ],
        "type": "timeseries",
        "requests": [
          {
            "formulas": [
              {
                "alias": "Rows inserted",
                "formula": "diff(query1)"
              },
              {
                "alias": "Rows deleted",
                "formula": "diff(query2)"
              },
              {
                "alias": "Rows updated",
                "formula": "diff(query3)"
              }
            ],
            "queries": [
              {
                "name": "query1",
                "data_source": "metrics",
                "query": "max:neon_pg_stats_userdb{kind:inserted,$endpoint_id}"
              },
              {
                "name": "query2",
                "data_source": "metrics",
                "query": "max:neon_pg_stats_userdb{kind:deleted,$endpoint_id}"
              },
              {
                "name": "query3",
                "data_source": "metrics",
                "query": "max:neon_pg_stats_userdb{kind:updated,$endpoint_id}"
              }
            ],
            "response_format": "timeseries",
            "style": {
              "palette": "dog_classic",
              "order_by": "values",
              "line_type": "solid",
              "line_width": "normal"
            },
            "display_type": "line"
          }
        ]
      },
      "layout": {
        "x": 6,
        "y": 5,
        "width": 6,
        "height": 2
      }
    },
    {
      "id": 630770240665422,
      "definition": {
        "title": "Compute cache hit rate",
        "title_size": "16",
        "title_align": "left",
        "show_legend": true,
        "legend_layout": "auto",
        "legend_columns": [
          "avg",
          "min",
          "max",
          "value",
          "sum"
        ],
        "time": {},
        "type": "timeseries",
        "requests": [
          {
            "formulas": [
              {
                "alias": "Cache hit rate",
                "formula": "query1 / (query1 + query2)",
                "number_format": {
                  "unit": {
                    "type": "canonical_unit",
                    "unit_name": "fraction"
                  }
                }
              }
            ],
            "queries": [
              {
                "name": "query1",
                "data_source": "metrics",
                "query": "max:neon_lfc_hits{$endpoint_id}"
              },
              {
                "name": "query2",
                "data_source": "metrics",
                "query": "max:neon_lfc_misses{$endpoint_id}"
              }
            ],
            "response_format": "timeseries",
            "style": {
              "palette": "dog_classic",
              "order_by": "values",
              "line_type": "solid",
              "line_width": "normal"
            },
            "display_type": "line"
          }
        ]
      },
      "layout": {
        "x": 0,
        "y": 7,
        "width": 6,
        "height": 3
      }
    },
    {
      "id": 2040733022455075,
      "definition": {
        "title": "Working set size",
        "title_size": "16",
        "title_align": "left",
        "show_legend": true,
        "legend_layout": "auto",
        "legend_columns": [
          "avg",
          "min",
          "max",
          "value",
          "sum"
        ],
        "time": {},
        "type": "timeseries",
        "requests": [
          {
            "formulas": [
              {
                "alias": "Compute cache size",
                "number_format": {
                  "unit": {
                    "type": "canonical_unit",
                    "unit_name": "byte"
                  }
                },
                "formula": "query2"
              },
              {
                "number_format": {
                  "unit": {
                    "type": "canonical_unit",
                    "unit_name": "byte"
                  }
                },
                "formula": "8192 * query1"
              }
            ],
            "queries": [
              {
                "name": "query2",
                "data_source": "metrics",
                "query": "max:neon_lfc_cache_size_limit{$endpoint_id}"
              },
              {
                "name": "query1",
                "data_source": "metrics",
                "query": "max:neon_lfc_approximate_working_set_size_windows{$endpoint_id} by {duration}"
              }
            ],
            "response_format": "timeseries",
            "style": {
              "palette": "dog_classic",
              "order_by": "values",
              "line_type": "solid",
              "line_width": "normal"
            },
            "display_type": "line"
          }
        ]
      },
      "layout": {
        "x": 6,
        "y": 7,
        "width": 6,
        "height": 3
      }
    },
    {
      "id": 7813951705806928,
      "definition": {
        "title": "Postgres Logs",
        "title_size": "16",
        "title_align": "left",
        "time": {},
        "requests": [
          {
            "response_format": "event_list",
            "query": {
              "data_source": "logs_stream",
              "query_string": "@$endpoint_id @$project_id",
              "indexes": [],
              "storage": "hot"
            },
            "columns": [
              {
                "field": "status_line",
                "width": "auto"
              },
              {
                "field": "host",
                "width": "auto"
              },
              {
                "field": "timestamp",
                "width": "auto"
              },
              {
                "field": "content",
                "width": "auto"
              }
            ]
          }
        ],
        "type": "list_stream"
      },
      "layout": {
        "x": 0,
        "y": 10,
        "width": 12,
        "height": 4
      }
    }
  ],
  "template_variables": [
    {
      "name": "endpoint_id",
      "prefix": "endpoint_id",
      "available_values": [],
      "default": "*"
    },
    {
      "name": "project_id",
      "prefix": "project_id",
      "available_values": [],
      "default": "*"
    },
    {
      "name": "state",
      "prefix": "state",
      "available_values": [],
      "default": "*"
    }
  ],
  "layout_type": "ordered",
  "notify_list": [],
  "reflow_type": "fixed"
}
```

</details>

## Available metrics

Neon exports metrics including connection counts, database size, replication delay, compute metrics (CPU and memory usage), and PgBouncer connection pooling metrics (client and server connections). For a complete list of all available metrics with detailed descriptions, see the [Metrics and logs reference](https://neon.com/docs/reference/metrics-logs).

## Export Postgres logs to Datadog

You can export your Postgres logs from your Neon compute to your Datadog account. These logs provide visibility into database activity, errors, and performance. By default, logs include warnings and errors, connections and disconnections, checkpoints, and slow autovacuum runs. Query text isn't logged, and slow-query logging is off unless you turn it on. For the full list of logging settings and log fields, see [Postgres logs](https://neon.com/docs/reference/metrics-logs#postgres-logs) in the Metrics and logs reference.

### Performance impact

Enabling this feature may result in:

- An increase in compute resource usage for log processing
- Additional public network transfer for log transmission, which counts toward your plan's [network transfer allowance](https://neon.com/docs/introduction/network-transfer)
- Associated costs based on log volume in Datadog

## Feedback

If you have feature requests or feedback, let us know through the [Feedback form](https://console.neon.tech/app/projects?modal=feedback) in the Neon Console or on [Discord](https://neon.com/discord).

--- [Document source](https://neon.com/docs/guides/django-migrations.md) ---

> Summary: Django schema migrations with Lakebase Postgres use Django's built-in ORM and the makemigrations/migrate commands to create and evolve database tables in a serverless Postgres database. Use this guide when connecting a Python 3.8+ Django project to Neon for the first time or when you need to apply model changes as versioned migrations. Neon recommends a direct (non-pooled) connection string for running migrations to avoid PgBouncer-related errors; the guide also covers dj-database-url configuration and seeding initial data.

# Schema migration with Lakebase Postgres and Django

Set up a database on Neon and run migrations for your Django project

Last updated: 2026-10-28

[Django](https://www.djangoproject.com/) is a high-level Python framework to make database-driven web applications. It provides an ORM (Object-Relational Mapping) layer that abstracts database operations, making it easy to interact with databases using Python code. Django also includes a powerful migration system that allows you to define and manage database schema changes over time.

This guide demonstrates how to use Django with a Lakebase Postgres database. We'll create a simple Django application and walk through the process of setting up the database, defining models, and generating and running migrations to manage schema changes.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- [Python](https://www.python.org/) installed on your local machine. We recommend using a newer version of Python, 3.8 or higher.

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select a project or click the `New Project` button to create a new one.

### Retrieve your Neon database connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

**Note:** Neon supports both direct and pooled database connection strings, which you can find by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. A pooled connection string connects your application to the database via a PgBouncer connection pool, allowing for a higher number of concurrent connections. However, using a pooled connection string for migrations can be prone to errors. For this reason, we recommend using a direct (non-pooled) connection when performing migrations. For more information about direct and pooled connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Setting up the Django project

### Set up the Python environment

To manage our Django project dependencies, we create a new Python virtual environment. Run the following commands in your terminal to set it up.

```bash
python -m venv myenv
```

Activate the virtual environment by running the following command:

```bash
# On macOS and Linux
source myenv/bin/activate
# On Windows
myenv\Scripts\activate
```

With the virtual environment activated, we can create a new directory for our Django project and install the required packages:

```bash
mkdir guide-neon-django && cd guide-neon-django

pip install Django "psycopg2-binary"
pip install python-dotenv dj-database-url
pip freeze > requirements.txt
```

We installed Django and the `psycopg2-binary` package to connect to the Lakebase Postgres database. We also added the `python-dotenv` to read environment variables easily, and the `dj-database-url` package to parse the Neon connection string into Django settings. We also saved the installed packages to a `requirements.txt` file so the project can be easily recreated in another environment.

### Create a new Django project

Run the following command to create a new Django project in the current directory:

```bash
django-admin startproject guide_neon_django .
```

This command creates a new Django project named `guide_neon_django` in the current directory.

### Set up the Database configuration

Create a `.env` file in the project root directory and add the `DATABASE_URL` environment variable to it. Use the connection string that you obtained from the Neon Console earlier.

```bash
# .env
DATABASE_URL=NEON_POSTGRES_CONNECTION_STRING
```

For Django to read the environment variables from the `.env` file, open the `settings.py` file located in the `guide_neon_django` directory and add the following code, updating the `DATABASES` setting:

```python
# settings.py

import os
import dotenv
import dj_database_url

dotenv.load_dotenv("../.env")

DATABASES = {
    "default": dj_database_url.parse(
        url=os.getenv("DATABASE_URL", ""),
        conn_max_age=600, conn_health_checks=True
    )
}
```

### Create a new Django app

Inside your project directory, run the following command to create a new Django app:

```bash
python manage.py startapp catalog
```

This command creates a new app named `catalog` inside the Django project.

## Defining data models and running migrations

### Specify the data model

Now, open the `models.py` file in your `catalog` app directory and define the database models for your application:

```python
# catalog/models.py

from django.db import models

class Author(models.Model):
    name = models.CharField(max_length=100)
    bio = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name

class Book(models.Model):
    title = models.CharField(max_length=200)
    author = models.ForeignKey(Author, on_delete=models.CASCADE)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.title
```

This code defines two models: `Author` and `Book`. The `Author` model represents an author with fields for `name`, `bio`, and a `created_at` timestamp. The `Book` model represents a book with fields for `title`, `author` (as a foreign key to the `Author` model), and a `created_at` timestamp. Django automatically creates an `id` field for each model as the primary key.

### Generate migration files

We first add the new application `catalog` to the list of installed apps for the Django project. Open the `settings.py` file in the `guide_neon_django` directory and add the `catalog` app to the `INSTALLED_APPS` setting:

```python
# settings.py

INSTALLED_APPS = [
    "django.contrib.admin",
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "catalog"
]
```

To generate migration files based on the defined models, run the following command:

```bash
python manage.py makemigrations
```

This command detects the new `Author` and `Book` models that were added and generates migration files in the `catalog/migrations` directory.

### Apply the migration

Now, to apply the migration and create the corresponding tables in the database, run the following command:

```bash
python manage.py migrate
```

This command executes the migration files and creates the necessary tables in the database. Note that Django creates multiple other tables, such as `django_migrations` and `auth_user` for its internal usage.

### Seed the database

To populate the database with some initial data, we can create a custom management command for our app. Create a new file named `populate.py` in the `catalog/management/commands` directory.

```bash
mkdir -p catalog/management/commands
touch catalog/management/commands/populate.py
```

Now, add the following code to the `populate.py` file to create some authors and books:

```python
from django.core.management.base import BaseCommand
from catalog.models import Author, Book

class Command(BaseCommand):
    help = 'Seeds the database with sample authors and books'

    def handle(self, *args, **options):
        # Create authors
        authors = [
            Author(
                name="J.R.R. Tolkien",
                bio="The creator of Middle-earth and author of The Lord of the Rings."
            ),
            Author(
                name="George R.R. Martin",
                bio="The author of the epic fantasy series A Song of Ice and Fire."
            ),
            Author(
                name="J.K. Rowling",
                bio="The creator of the Harry Potter series."
            ),
        ]
        Author.objects.bulk_create(authors)

        # Create books
        books = [
            Book(title="The Fellowship of the Ring", author=authors[0]),
            Book(title="The Two Towers", author=authors[0]),
            Book(title="The Return of the King", author=authors[0]),
            Book(title="A Game of Thrones", author=authors[1]),
            Book(title="A Clash of Kings", author=authors[1]),
            Book(title="Harry Potter and the Philosopher's Stone", author=authors[2]),
            Book(title="Harry Potter and the Chamber of Secrets", author=authors[2]),
        ]
        Book.objects.bulk_create(books)

        self.stdout.write(self.style.SUCCESS('Successfully seeded the database.'))
```

Now, run the custom management command in your terminal and seed the database:

```bash
python manage.py populate
```

## Implement the application

### Create views to display data

We can now create views to display the authors and books in our application. Create a file `views.py` in the `catalog` app directory and add the following code:

```python
# catalog/views.py

from django.http import JsonResponse
from django.core import serializers
from .models import Author, Book

def list_authors(request):
    authors = Author.objects.all()
    data = [serializers.serialize('json', authors)]
    return JsonResponse(data, safe=False)

def list_books_by_author(request, author_id):
    books = Book.objects.filter(author_id=author_id)
    data = [serializers.serialize('json', books)]
    return JsonResponse(data, safe=False)
```

We defined two views: `list_authors` to list all authors and `list_books_by_author` to list books by a specific author. The views return JSON responses with the serialized data.

### Define URLs for the views

Next, create a file `urls.py` in the `catalog` app directory and add the following code:

```python
# catalog/urls.py

from django.urls import path
from . import views

urlpatterns = [
    path('authors/', views.list_authors, name='list_authors'),
    path('books/<int:author_id>/', views.list_books_by_author, name='list_books_by_author'),
]
```

The URLs are mapped to the views defined previously using the Django URL dispatcher.

### Include the app URLs in the project

Finally, include the `catalog` app URLs in the project's main `urls.py` file, by updating the urlpatterns list:

```python
# guide_neon_django/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('catalog/', include('catalog.urls')),
]
```

### Run the Django development server

To start the Django development server and test the application, run the following command:

```bash
python manage.py runserver
```

Navigate to the url `http://localhost:8000/catalog/authors/` in your browser to view the list of authors. You can also view the books by a specific author by visiting `http://localhost:8000/catalog/books/<author_id>/`.

## Applying schema changes

We will demonstrate how to handle schema changes by adding a new field `country` to the `Author` model, to store the author's country of origin.

### Update the data model

Open the `models.py` file in your `catalog` app directory and add a new field to the `Author` model:

```python
# catalog/models.py

class Author(models.Model):
    name = models.CharField(max_length=100)
    bio = models.TextField(blank=True)
    country = models.CharField(max_length=100, blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    def __str__(self):
        return self.name
```

### Generate and run the migration

To generate a new migration file for the schema change, run the following command:

```bash
python manage.py makemigrations
```

This command detects the updated `Author` models and generates a new migration file to add the new field to the corresponding table in the database. Now, to apply the migration, run the following command:

```bash
python manage.py migrate
```

### Test the schema change

Restart the Django development server.

```bash
python manage.py runserver
```

Navigate to the url `http://localhost:8000/catalog/authors` to view the list of authors. You should see the new `country` field included and set to empty for each author entry, reflecting the schema change.

## Conclusion

In this guide, we demonstrated how to set up a Django project with Lakebase Postgres, define database models, and generate migrations and run them. Django's ORM and migration system make it easy to interact with the database and manage schema evolution over time.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Migrations with Neon and Django](https://github.com/neondatabase/guide-neon-django): Run migrations in a Neon-Django project

## Resources

For more information on the tools and concepts used in this guide, refer to the following resources:

- [Django Documentation](https://docs.djangoproject.com/)
- [Neon](https://neon.com/docs)

--- [Document source](https://neon.com/docs/guides/django.md) ---

> Summary: Connecting Django to Lakebase Postgres on Neon requires configuring the `DATABASES` block in `settings.py` with the psycopg3 driver, `sslmode: require`, and `CONN_HEALTH_CHECKS: True` to prevent dropped connections when the compute scales to zero after 5 minutes of inactivity. Use this page when setting up a new Django connection or debugging the `Endpoint ID is not specified` SNI error, which occurs with psycopg2 and libpq versions older than v14. For schema migrations after connecting, see the separate Django Migrations guide.

# Connect a Django application to Neon

Set up a Neon project in seconds and connect from a Django application

Last updated: 2026-09-16

Pre-built prompt for connecting Django applications to Neon [View prompt](https://neon.com/prompts/django-prompt.md)

To connect to Neon from a Django application:

## Prerequisites

- A [Neon account and project](https://neon.com/docs/get-started/signing-up) with connection parameters ready
- Python 3.12+ installed (required by Django 6). Django 5.2 LTS supports Python 3.10+.
- An existing Django project (or create one with `django-admin startproject myproject`)

**Important:**

Always use a Python virtual environment. Do not install packages globally. If you do not have one set up, create and activate it before proceeding:

```bash
python3 -m venv venv
source venv/bin/activate   # macOS / Linux
# venv\Scripts\activate    # Windows
```

## Install the Postgres driver

Install `psycopg` (psycopg 3) and `python-dotenv` inside your virtual environment:

```bash
pip install "psycopg[binary]" python-dotenv
```

**Note:** The examples below use `psycopg` (v3). If your project uses the older `psycopg2` driver, see [Connection issues](https://neon.com/docs/guides/django#connection-issues) for SNI compatibility requirements.

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

To create a Neon project:

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Configure Django connection settings

Connecting to Neon requires configuring database connection settings in your Django project's `settings.py` file.

**Note:** To avoid the `endpoint ID is not specified` connection issue described [here](https://neon.com/docs/guides/django#connection-issues), be sure that you are using an up-to-date driver.

In your Django project, navigate to the `DATABASES` section of your `settings.py` file and modify the connection details as shown:

```python
# Add these at the top of your settings.py
from os import getenv
from dotenv import load_dotenv

load_dotenv()

# Replace the DATABASES section of your settings.py with this
DATABASES = {
  'default': {
    'ENGINE': 'django.db.backends.postgresql',
    'NAME': getenv('PGDATABASE'),
    'USER': getenv('PGUSER'),
    'PASSWORD': getenv('PGPASSWORD'),
    'HOST': getenv('PGHOST'),
    'PORT': getenv('PGPORT', 5432),
    'OPTIONS': {
      'sslmode': 'require',
    },
    'DISABLE_SERVER_SIDE_CURSORS': True,
    'CONN_HEALTH_CHECKS': True,
  }
}
```

**Note:** Neon places computes into an idle state and closes connections after 5 minutes of inactivity (see [Compute lifecycle](https://neon.com/docs/introduction/compute-lifecycle/)). To avoid connection errors, you can set the Django [CONN_MAX_AGE](https://docs.djangoproject.com/en/stable/ref/settings/#std-setting-CONN_MAX_AGE) setting to 0 to close database connections at the end of each request so that your application does not attempt to reuse connections that were closed by Neon. From Django 4.1, you can use a higher `CONN_MAX_AGE` setting in combination with the [CONN_HEALTH_CHECKS](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks) setting to enable connection reuse while preventing errors that might occur due to closed connections. For more information about these configuration options, see [Connection management](https://docs.djangoproject.com/en/stable/ref/databases/#connection-management), in the _Django documentation_.

You can find all of the connection details listed above by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

Add a `.env` file to your project's root directory with the individual connection parameters (not a single `DATABASE_URL`, since Django's `DATABASES` setting expects separate fields):

```shell
PGHOST="<endpoint_hostname>.neon.tech"
PGDATABASE="<dbname>"
PGUSER="<user>"
PGPASSWORD="<password>"
PGPORT=5432
```

> Replace `<endpoint_hostname>`, `<dbname>`, `<user>`, and `<password>` with your actual database credentials. If you have a connection string (`postgresql://[user]:[password]@[neon_hostname]/[dbname]`), copy its parts into the matching variables. The pooled hostname (with `-pooler`) works with these settings.

For additional information about Django project settings, see [Django Settings: Databases](https://docs.djangoproject.com/en/stable/ref/settings/#databases), in the Django documentation.

## Test the connection

Create a simple view to verify the database connection is working.

1. In your project's main app directory (next to `urls.py`), create `views.py`:

   ```python
   from django.http import JsonResponse
   from django.db import connection

   def db_version(request):
       with connection.cursor() as cursor:
           cursor.execute("SELECT version();")
           version = cursor.fetchone()[0]
       return JsonResponse({'version': version})
   ```

2. Add a URL route in your project's `urls.py`:

   ```python
   from django.contrib import admin
   from django.urls import path
   from . import views

   urlpatterns = [
       path('admin/', admin.site.urls),
       path('', views.db_version, name='db_version'),
   ]
   ```

3. Run migrations and start the server:

   ```bash
   python manage.py migrate
   python manage.py runserver
   ```

4. Visit `http://localhost:8000` to see the Postgres version from your Neon database.

## Connection issues

- Django uses `psycopg` (v3) when it's installed and falls back to `psycopg2`. If your project uses an older version of `psycopg2`, you may encounter an `Endpoint ID is not specified` error when connecting to Neon. This error occurs if the client library used by your driver does not support the Server Name Indication (SNI) mechanism in TLS, which Neon uses to route incoming connections. The `psycopg2` driver uses the `libpq` client library, which supports SNI as of v14. You can check your `psycopg2` and `libpq` versions by starting a Django shell in your Django project and running the following commands:

  ```bash
  # Start a Django shell
  python3 manage.py shell
  ```

  ```python
  # Check versions
  import psycopg2
  print("psycopg2 version:", psycopg2.__version__)
  print("libpq version:", psycopg2._psycopg.libpq_version())
  ```

  The version number for `libpq` is presented in a different format, for example, version 14.1 will be shown as 140001. If your `libpq` version is less than version 14, you can either upgrade your `psycopg2` driver to get a newer `libpq` version or use one of the workarounds in [Connection errors](https://neon.com/docs/connect/connection-errors#the-endpoint-id-is-not-specified). Upgrading your `psycopg2` driver may introduce compatibility issues with your Django or Python version, so you should test your application thoroughly.

- If you encounter an `SSL SYSCALL error: EOF detected` when connecting to the database, this typically occurs because the application is trying to reuse a connection after the Neon compute has been suspended due to inactivity. To resolve this issue, try one of the following options:

  - Set your Django [`CONN_MAX_AGE`](https://docs.djangoproject.com/en/stable/ref/settings/#conn-max-age) setting to a value less than or equal to the scale to zero setting configured for your compute. The default is 5 minutes (300 seconds).
  - Enable [`CONN_HEALTH_CHECKS`](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks) by setting it to `True`. This forces a health check to verify that the connection is alive before executing a query.

  For information configuring Neon's Scale to zero setting, see [Configuring Scale to zero for Neon computes](https://neon.com/docs/guides/scale-to-zero-guide).

## Schema migration with Django

For schema migration with Django, see:

- [Django Migrations](https://neon.com/docs/guides/django-migrations): Schema migration with Lakebase Postgres and Django

## Django application blog post and sample application

Learn how to use Django with Lakebase Postgres with this blog post and the accompanying sample application.

- [Blog Post: Using Django with Neon](https://neon.com/blog/python-django-and-neons-serverless-postgres): Learn how to build a Django application with Lakebase Postgres
- [Django sample application](https://github.com/evanshortiss/django-neon-quickstart): Django with Lakebase Postgres

## Community resources

- [Django Project: Build a Micro eCommerce with Python, Django, Neon Postgres, Stripe, & TailwindCSS](https://youtu.be/qx9nshX9CQQ?start=1569)

<details>

<summary>**Notes for AI-assisted setup**</summary>

- Do not install packages globally. Always use a virtual environment and run commands with `venv/bin/pip` and `venv/bin/python` (or the activated equivalent).
- Use `psycopg[binary]` (psycopg v3), not the older `psycopg2`. If the project already uses `psycopg2`, check the [Connection issues](https://neon.com/docs/guides/django#connection-issues) section for SNI compatibility.
- Include `CONN_HEALTH_CHECKS: True` in the `DATABASES` configuration. This prevents errors from idle connections when Neon scales to zero.
- Do not hardcode credentials in `settings.py`. Use environment variables via `python-dotenv` and `os.getenv()`. For more information, see [Security overview](https://neon.com/docs/security/security-overview).
- The `.env` file should use individual `PG*` variables (`PGHOST`, `PGDATABASE`, etc.), not a single `DATABASE_URL`, since Django's database configuration expects separate fields.

</details>

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database.
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential.

--- [Document source](https://neon.com/docs/guides/dotnet-entity-framework.md) ---

> Summary: Entity Framework Core connection to Lakebase Postgres uses Npgsql as the EF Core provider, demonstrated through a complete ASP.NET Core Web API project with DbContext setup, connection string configuration, and EF migrations. Use this guide when wiring a .NET application (ASP.NET Core MVC, Blazor, or console app) to a Neon serverless Postgres database for the first time. Covers installing `Npgsql.EntityFrameworkCore.PostgreSQL`, `Microsoft.EntityFrameworkCore.Design`, and `dotnet-ef`, then applying the initial schema with `dotnet ef database update`.

# Connect an Entity Framework application to Neon

Set up a Neon project in seconds and connect from an Entity Framework application

Last updated: 2026-07-31

Pre-built prompt for connecting .NET Entity Framework projects to Lakebase Postgres. [View prompt](https://neon.com/prompts/dotnet-ef-prompt.md)

This guide describes how to create a Neon project and connect to it from an Entity Framework Core application. The example demonstrates how to set up a basic ASP.NET Core Web API project with Entity Framework Core using Npgsql as the database provider.

**Note:** The same configuration steps can be used for any .NET application using Entity Framework Core, including ASP.NET Core MVC, Blazor, or console applications.

To connect to Neon from an Entity Framework application:

1. [Create a Neon project](https://neon.com/docs/guides/dotnet-entity-framework#create-a-neon-project)
2. [Create a .NET project and add dependencies](https://neon.com/docs/guides/dotnet-entity-framework#create-a-net-project-and-add-dependencies)
3. [Configure Entity Framework](https://neon.com/docs/guides/dotnet-entity-framework#configure-entity-framework)
4. [Run the application](https://neon.com/docs/guides/dotnet-entity-framework#run-the-application)

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a .NET project and add dependencies

1. Create a new ASP.NET Core Web API project and change to the newly created directory:

   ```bash
   dotnet new webapi --use-controllers -n NeonEfExample
   cd NeonEfExample
   ```

   The `--use-controllers` option creates a controller-based project. Without it, .NET 8 and later create a minimal API project with no `Controllers` folder.

2. Delete the sample files `WeatherForecast.cs` and `Controllers/WeatherForecastController.cs`, which this guide doesn't use:

   ```bash
   rm WeatherForecast.cs Controllers/WeatherForecastController.cs
   ```

3. Install the EF Core tools and packages. Use package versions with the same major version as your .NET SDK. Run `dotnet --version` to check it: for example, `10.0.403` is .NET 10, so use `10.*`.

   ```bash
   dotnet tool install --global dotnet-ef --version '10.*'
   dotnet add package Microsoft.EntityFrameworkCore.Design --version '10.*'
   dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL --version '10.*'
   ```

   For .NET 9, use `'9.*'`; for .NET 8, use `'8.*'`. Don't pass the full SDK version (such as `10.0.403`): package versions don't match it, and the install fails.

## Configure Entity Framework

1. Create a model class in `Models/Todo.cs`:

   ```csharp
   namespace NeonEfExample.Models
   {
       public class Todo
       {
           public int Id { get; set; }
           public string? Title { get; set; }
           public bool IsComplete { get; set; }
       }
   }
   ```

2. Create a database context in `Data/ApplicationDbContext.cs`:

   ```csharp
   using Microsoft.EntityFrameworkCore;
   using NeonEfExample.Models;

   namespace NeonEfExample.Data
   {
       public class ApplicationDbContext : DbContext
       {
           public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
               : base(options)
           {
           }

           public DbSet<Todo> Todos => Set<Todo>();
       }
   }
   ```

3. Add a `ConnectionStrings` section to `appsettings.json` with your Neon connection details. Get them from the **Connect** modal in the Neon Console:

   ```json
   {
     "ConnectionStrings": {
       "TodoDbConnection": "Host=[neon_hostname];Database=[dbname];Username=[user];Password=[password];SSL Mode=Require;Channel Binding=Require"
     }
   }
   ```

   Npgsql uses this key-value format rather than a `postgresql://` URL. To convert a URL such as `postgresql://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require`, use the hostname for `Host`, the path for `Database`, the user and password for `Username` and `Password`, and map `sslmode=require` to `SSL Mode=Require` and `channel_binding=require` to `Channel Binding=Require`.

   Keep the existing `Logging` and `AllowedHosts` settings in the file. Don't commit a real password: for local development, you can store the connection string with [user secrets](https://learn.microsoft.com/en-us/aspnet/core/security/app-secrets) instead.

4. Create a Todo controller in `Controllers/TodoController.cs`:

   ```csharp
   using Microsoft.AspNetCore.Mvc;
   using Microsoft.EntityFrameworkCore;
   using NeonEfExample.Data;
   using NeonEfExample.Models;

   namespace NeonEfExample.Controllers
   {
       [ApiController]
       [Route("api/[controller]")]
       public class TodoController : ControllerBase
       {
           private readonly ApplicationDbContext _context;

           public TodoController(ApplicationDbContext context)
           {
               _context = context;
           }

           [HttpGet]
           public async Task<ActionResult<IEnumerable<Todo>>> GetTodos()
           {
               return await _context.Todos.ToListAsync();
           }

           [HttpPost]
           public async Task<ActionResult<Todo>> PostTodo(Todo todo)
           {
               _context.Todos.Add(todo);
               await _context.SaveChangesAsync();
               return CreatedAtAction(nameof(GetTodos), new { id = todo.Id }, todo);
           }
       }
   }
   ```

5. Replace the contents of `Program.cs`:

   ```csharp
   using Microsoft.EntityFrameworkCore;
   using NeonEfExample.Data;

   var builder = WebApplication.CreateBuilder(args);

   builder.Services.AddControllers();
   builder.Services.AddOpenApi();

   builder.Services.AddDbContext<ApplicationDbContext>(options =>
       options.UseNpgsql(builder.Configuration.GetConnectionString("TodoDbConnection")));

   var app = builder.Build();

   if (app.Environment.IsDevelopment())
   {
       app.MapOpenApi();
   }

   app.UseHttpsRedirection();
   app.UseAuthorization();
   app.MapControllers();

   app.Run();
   ```

   The name passed to `GetConnectionString` must match the key in `appsettings.json` (`TodoDbConnection`). If it doesn't, `dotnet ef database update` fails with `The ConnectionString property has not been initialized`.

6. Create and apply the initial migration:

   ```bash
   dotnet ef migrations add InitialCreate
   dotnet ef database update
   ```

## Run the application

1. Start the application on port 5001 (use any free port if 5001 is taken, and change the URLs below to match):

   ```bash
   dotnet run --urls http://localhost:5001
   ```

2. In another terminal, create a todo and then list todos:

   ```bash
   curl -X POST http://localhost:5001/api/todo \
     -H "Content-Type: application/json" \
     -d '{"title": "Try Neon", "isComplete": false}'

   curl http://localhost:5001/api/todo
   ```

   The second command returns the todo stored in your Neon database:

   ```json filename="Output"
   [{"id":1,"title":"Try Neon","isComplete":false}]
   ```

   In development, the OpenAPI document for the API is available at `http://localhost:5001/openapi/v1.json`.

## Resources

- [.NET Documentation](https://learn.microsoft.com/en-us/dotnet/)
- [Entity Framework Core](https://learn.microsoft.com/en-us/ef/)

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/dotnet-npgsql.md) ---

> Summary: Npgsql is the .NET data provider for PostgreSQL that lets a C# application connect to a Lakebase Postgres database and run SQL queries directly, without an ORM. Use this guide for raw SQL access to Neon via NpgsqlConnection and NpgsqlCommand, covering CRUD operations, parameterized queries to prevent SQL injection, and credential storage in appsettings.json. For ORM-based alternatives, see the Entity Framework guide.

# Connect a .NET (C#) application to Lakebase Postgres

Learn how to run SQL queries in Neon from .NET using the Npgsql library

Last updated: 2026-10-09

Pre-built prompt for connecting .NET applications to Neon [View prompt](https://neon.com/prompts/dotnet-prompt.md)

This guide describes how to create a Neon project and connect to it from a .NET (C#) application using [Npgsql](https://www.npgsql.org/), a .NET data provider for PostgreSQL.

You'll build a console application that demonstrates how to connect to your Neon database and perform basic Create, Read, Update, and Delete (CRUD) operations.

**Note:** The same configuration steps can be used for any .NET application type, including ASP.NET Core Web API, MVC, Blazor, or Windows Forms applications.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://console.neon.tech/signup).
- The [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0) or later.
  > _Other versions of .NET may work, but this guide is primarily tested with .NET 10._

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Your project is created with a ready-to-use database named `neondb`. In the following steps, you will connect to this database from your .NET application.

## Create a .NET project

For your .NET project, you will create a project directory and add the required packages using the `dotnet` CLI.

1. Create a new console application and change into the newly created directory.

   ```bash
   dotnet new console -o NeonLibraryExample
   cd NeonLibraryExample
   ```

   > Open this directory in your preferred code editor (for example, VS Code, Visual Studio).

2. Add the required NuGet packages using `dotnet add package`.

   - `Npgsql`: The .NET data provider for PostgreSQL.
   - `Microsoft.Extensions.Configuration.Json`: To read configuration from `appsettings.json`.
   - `Microsoft.Extensions.Configuration.Binder`: To bind configuration values to objects.

   ```bash
   dotnet add package Npgsql
   dotnet add package Microsoft.Extensions.Configuration.Json
   dotnet add package Microsoft.Extensions.Configuration.Binder
   ```

## Store your Neon connection string

Create a file named `appsettings.json` in your project's root directory. This is the standard .NET approach for storing configuration data like connection strings.

1. In the [Neon Console](https://console.neon.tech), open your project.
2. Click **Connect** in the Console nav to open the **Connect to your branch** modal.
3. Select **.NET** as your connection method.
   ![Connection modal](https://neon.com/docs/connect/dotnet_connection_details.png)
4. Copy the **pooled** connection string, which includes your password.
5. Create an `appsettings.json` file in your project's root directory and add the connection string to it as shown below.

   ```json filename="appsettings.json"
   {
     "ConnectionStrings": {
       "DefaultConnection": "Host=your-neon-host;Database=your-database;Username=your-username;Password=your-password;SSL Mode=VerifyFull; Channel Binding=Require"
     }
   }
   ```

   > Replace `your-neon-host`, `your-database`, `your-username`, and `your-password` with the actual values from your Neon connection string.

   **Note:** To ensure the security of your data, never commit your credentials to version control. In a production application, consider using environment variables or a secure secrets management solution to store sensitive information like connection strings.

## Write the application code

You will now write the C# code to connect to Neon and perform database operations. All the code will be in a single file named `Program.cs` which is the entry point of your console application.

Replace the contents of your `Program.cs` file with the following code:

```csharp filename="Program.cs"
using Microsoft.Extensions.Configuration;
using Npgsql;
using System.Text;

// --- 1. Read configuration and build connection string ---
var config = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json")
    .Build();

var connectionString = config.GetConnectionString("DefaultConnection");

// --- 2. Establish connection and perform CRUD operations ---
await using var conn = new NpgsqlConnection(connectionString);
try
{
    await conn.OpenAsync();
    Console.WriteLine("Connection established");

    // --- CREATE a table and INSERT data ---
    await using (var cmd = new NpgsqlCommand())
    {
        cmd.Connection = conn;

        cmd.CommandText = "DROP TABLE IF EXISTS books;";
        await cmd.ExecuteNonQueryAsync();
        Console.WriteLine("Finished dropping table (if it existed).");

        cmd.CommandText = @"
            CREATE TABLE books (
                id SERIAL PRIMARY KEY,
                title VARCHAR(255) NOT NULL,
                author VARCHAR(255),
                publication_year INT,
                in_stock BOOLEAN DEFAULT TRUE
            );";
        await cmd.ExecuteNonQueryAsync();
        Console.WriteLine("Finished creating table.");

        cmd.CommandText = "INSERT INTO books (title, author, publication_year, in_stock) VALUES (@t1, @a1, @y1, @s1);";
        cmd.Parameters.AddWithValue("t1", "The Catcher in the Rye");
        cmd.Parameters.AddWithValue("a1", "J.D. Salinger");
        cmd.Parameters.AddWithValue("y1", 1951);
        cmd.Parameters.AddWithValue("s1", true);
        await cmd.ExecuteNonQueryAsync();
        Console.WriteLine("Inserted a single book.");
        cmd.Parameters.Clear();

        var booksToInsert = new[] {
            new { Title = "The Hobbit", Author = "J.R.R. Tolkien", Year = 1937, InStock = true },
            new { Title = "1984", Author = "George Orwell", Year = 1949, InStock = true },
            new { Title = "Dune", Author = "Frank Herbert", Year = 1965, InStock = false }
        };

        foreach (var book in booksToInsert)
        {
            cmd.CommandText = "INSERT INTO books (title, author, publication_year, in_stock) VALUES (@title, @author, @year, @in_stock);";
            cmd.Parameters.AddWithValue("title", book.Title);
            cmd.Parameters.AddWithValue("author", book.Author);
            cmd.Parameters.AddWithValue("year", book.Year);
            cmd.Parameters.AddWithValue("in_stock", book.InStock);
            await cmd.ExecuteNonQueryAsync();
            cmd.Parameters.Clear();
        }
        Console.WriteLine("Inserted 3 rows of data.");
    }

    // --- READ the initial data ---
    await ReadDataAsync(conn, "Book Library");

    // --- UPDATE data ---
    await using (var cmd = new NpgsqlCommand("UPDATE books SET in_stock = @in_stock WHERE title = @title;", conn))
    {
        cmd.Parameters.AddWithValue("in_stock", true);
        cmd.Parameters.AddWithValue("title", "Dune");
        await cmd.ExecuteNonQueryAsync();
        Console.WriteLine("Updated stock status for 'Dune'.");
    }

    // --- READ data after update ---
    await ReadDataAsync(conn, "Book Library After Update");

    // --- DELETE data ---
    await using (var cmd = new NpgsqlCommand("DELETE FROM books WHERE title = @title;", conn))
    {
        cmd.Parameters.AddWithValue("title", "1984");
        await cmd.ExecuteNonQueryAsync();
        Console.WriteLine("Deleted the book '1984' from the table.");
    }

    // --- READ data after delete ---
    await ReadDataAsync(conn, "Book Library After Delete");

}
catch (Exception e)
{
    Console.WriteLine("Connection failed.");
    Console.WriteLine(e.Message);
}

// Helper function to read data and print it to the console
async Task ReadDataAsync(NpgsqlConnection conn, string title)
{
    Console.WriteLine($"\n--- {title} ---");
    await using var cmd = new NpgsqlCommand("SELECT * FROM books ORDER BY publication_year;", conn);
    await using var reader = await cmd.ExecuteReaderAsync();

    var books = new StringBuilder();
    while (await reader.ReadAsync())
    {
        books.AppendLine(
            $"ID: {reader.GetInt32(0)}, " +
            $"Title: {reader.GetString(1)}, " +
            $"Author: {reader.GetString(2)}, " +
            $"Year: {reader.GetInt32(3)}, " +
            $"In Stock: {reader.GetBoolean(4)}"
        );
    }
    Console.WriteLine(books.ToString().TrimEnd());
    Console.WriteLine("--------------------\n");
}
```

## Examples

This section walks through the code in `Program.cs`, explaining how each part performs a specific CRUD operation.

### Create a table and insert data

This snippet connects to your database, creates a `books` table, and populates it with initial data.

```csharp
await using var conn = new NpgsqlConnection(connectionString);
await conn.OpenAsync();
Console.WriteLine("Connection established");

await using (var cmd = new NpgsqlCommand())
{
    cmd.Connection = conn;

    cmd.CommandText = "DROP TABLE IF EXISTS books;";
    await cmd.ExecuteNonQueryAsync();
    Console.WriteLine("Finished dropping table (if it existed).");

    cmd.CommandText = @"
        CREATE TABLE books (
            id SERIAL PRIMARY KEY,
            title VARCHAR(255) NOT NULL,
            author VARCHAR(255),
            publication_year INT,
            in_stock BOOLEAN DEFAULT TRUE
        );";
    await cmd.ExecuteNonQueryAsync();
    Console.WriteLine("Finished creating table.");

    cmd.CommandText = "INSERT INTO books (title, author, publication_year, in_stock) VALUES (@t1, @a1, @y1, @s1);";
    cmd.Parameters.AddWithValue("t1", "The Catcher in the Rye");
    cmd.Parameters.AddWithValue("a1", "J.D. Salinger");
    cmd.Parameters.AddWithValue("y1", 1951);
    cmd.Parameters.AddWithValue("s1", true);
    await cmd.ExecuteNonQueryAsync();
    Console.WriteLine("Inserted a single book.");
    cmd.Parameters.Clear();

    var booksToInsert = new[] {
        new { Title = "The Hobbit", Author = "J.R.R. Tolkien", Year = 1937, InStock = true },
        new { Title = "1984", Author = "George Orwell", Year = 1949, InStock = true },
        new { Title = "Dune", Author = "Frank Herbert", Year = 1965, InStock = false }
    };

    foreach (var book in booksToInsert)
    {
        cmd.CommandText = "INSERT INTO books (title, author, publication_year, in_stock) VALUES (@title, @author, @year, @in_stock);";
        cmd.Parameters.AddWithValue("title", book.Title);
        cmd.Parameters.AddWithValue("author", book.Author);
        cmd.Parameters.AddWithValue("year", book.Year);
        cmd.Parameters.AddWithValue("in_stock", book.InStock);
        await cmd.ExecuteNonQueryAsync();
        cmd.Parameters.Clear();
    }
    Console.WriteLine("Inserted 3 rows of data.");
}
```

In the code above, you:

- Open a connection to your Neon database asynchronously. The `await using` statement ensures the connection is properly closed and disposed of.
- Drop the `books` table if it exists to ensure a clean start.
- Create a new `books` table with columns for book details.
- Insert a single book record using a parameterized query to prevent SQL injection.
- Insert three more books by looping through a collection.

When this code runs successfully, it produces the following output:

```text filename="Output"
Connection established
Finished dropping table (if it existed).
Finished creating table.
Inserted a single book.
Inserted 3 rows of data.
```

### Read data

This snippet calls a helper function, `ReadDataAsync`, to retrieve and display all the books currently in the table.

```csharp
// The helper function definition
async Task ReadDataAsync(NpgsqlConnection conn, string title)
{
    Console.WriteLine($"\n--- {title} ---");
    await using var cmd = new NpgsqlCommand("SELECT * FROM books ORDER BY publication_year;", conn);
    await using var reader = await cmd.ExecuteReaderAsync();

    var books = new StringBuilder();
    while (await reader.ReadAsync())
    {
        books.AppendLine(
            $"ID: {reader.GetInt32(0)}, " +
            $"Title: {reader.GetString(1)}, " +
            $"Author: {reader.GetString(2)}, " +
            $"Year: {reader.GetInt32(3)}, " +
            $"In Stock: {reader.GetBoolean(4)}"
        );
    }
    Console.WriteLine(books.ToString().TrimEnd());
    Console.WriteLine("--------------------\n");
}

// How the function is called
await ReadDataAsync(conn, "Book Library");
```

In the code above, you:

- Execute a SQL `SELECT` statement to fetch all rows from the `books` table, ordered by publication year.
- Use an `NpgsqlDataReader` to iterate through the result set row by row.
- Read the column values for each row and format them into a string for display.

After the initial data insert, the output is:

```text filename="Output"

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: True
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: True
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: True
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: False
--------------------

```

### Update data

This snippet updates the stock status for the book 'Dune' from `false` to `true`.

```csharp
await using (var cmd = new NpgsqlCommand("UPDATE books SET in_stock = @in_stock WHERE title = @title;", conn))
{
    cmd.Parameters.AddWithValue("in_stock", true);
    cmd.Parameters.AddWithValue("title", "Dune");
    await cmd.ExecuteNonQueryAsync();
    Console.WriteLine("Updated stock status for 'Dune'.");
}

// Calling ReadDataAsync again to see the result
await ReadDataAsync(conn, "Book Library After Update");
```

In the code above, you:

- Execute a SQL `UPDATE` statement with parameters to identify the row to update (`WHERE title = @title`) and the new value (`SET in_stock = @in_stock`).
- Call `ReadDataAsync` again to show that the change was successful.

The output from this operation is:

```text filename="Output"
Updated stock status for 'Dune'.

--- Book Library After Update ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: True
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: True
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: True
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: True
--------------------

```

> You can see that the stock status for 'Dune' has been updated to `True`.

### Delete data

This final snippet removes the book '1984' from the `books` table.

```csharp
await using (var cmd = new NpgsqlCommand("DELETE FROM books WHERE title = @title;", conn))
{
    cmd.Parameters.AddWithValue("title", "1984");
    await cmd.ExecuteNonQueryAsync();
    Console.WriteLine("Deleted the book '1984' from the table.");
}

// Calling ReadDataAsync one last time
await ReadDataAsync(conn, "Book Library After Delete");
```

In the code above, you:

- Execute a SQL `DELETE` statement with a `WHERE` clause to target the specific book for removal.
- Call `ReadDataAsync` a final time to verify that the row was deleted.

The output from this operation is:

```text filename="Output"
Deleted the book '1984' from the table.

--- Book Library After Delete ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: True
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: True
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: True
--------------------

```

> You can see that the book '1984' has been successfully removed from the table.

## Run the application

To run the entire script, execute the following command from your project directory:

```bash
dotnet run
```

This command would compile and execute your application, connecting to the Neon database and performing all the CRUD operations defined in `Program.cs` as described above. You should see output in your console similar to the examples provided in the previous sections, indicating the success of each operation.

## Next steps: Using an ORM or framework

While this guide demonstrates how to connect to Neon using raw SQL queries, for more advanced and maintainable data interactions in your .NET applications, consider using an Object-Relational Mapping (ORM) framework. ORMs not only let you work with data as objects but also help manage schema changes through automated migrations keeping your database structure in sync with your application models.

Explore the following resources to learn how to integrate ORMs with Neon:

- [Connect an Entity Framework application to Neon](https://neon.com/docs/guides/dotnet-entity-framework)

## Next steps: Neon backend services

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Resources

- [Npgsql Documentation](https://www.npgsql.org/doc/index.html)
- [.NET Documentation](https://learn.microsoft.com/en-us/dotnet/)
- [Connect an Entity Framework application to Neon](https://neon.com/docs/guides/dotnet-entity-framework)

--- [Document source](https://neon.com/docs/guides/draxlr.md) ---

> Summary: Draxlr is a no-code analytics tool that connects to a Lakebase Postgres database and lets you build dashboards and reports using a visual query builder, raw SQL, or an AI chat interface that translates natural-language questions into Postgres queries. Use this guide when you need product analytics, real-time metric monitoring with email or Slack alerts, or embeddable customer-facing dashboards on top of Neon without writing application code. Connection uses a Neon connection string or manual host, port, database, username, and password values from the Neon Console.

# Build dashboards on Lakebase Postgres with Draxlr

Create live Neon dashboards and reports directly from your Postgres data

Last updated: 2026-08-04

[Draxlr](https://www.draxlr.com) is a no code analytics tool for Lakebase Postgres that lets you build dashboards, reports, and insights using SQL, visual queries, or AI. It is commonly used for product analytics, reporting, and embedded dashboards.

This guide shows how to connect Draxlr to a Lakebase Postgres database.

## Prerequisites

- A Draxlr account. See [Sign up for Draxlr](https://app.draxlr.com/register/).
- A Neon project with a Postgres database. See [Create a Neon project](https://neon.com/docs/manage/projects#create-a-project).

## Connect Neon to Draxlr

1. **Get your Neon connection string**
   In the Neon Console, open your project and copy the Postgres connection string. It will look similar to the following:

   ```text
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require
   ```

2. Open Draxlr and add a new data source
   - Log in to Draxlr.
   - Click on **Connect Database**.

3. Select **Neon** as the database type
   ![Connect to neon](https://neon.com/docs/guides/draxlr_connect_1.png)

4. Paste the Neon connection details

   - Click on **Import from URL** and paste the Neon connection string into the connection URL field, or
   - Enter the _Host, Port, Database name, Username, and Password_ manually using values from the Neon Console.

   ![Adding connection details](https://neon.com/docs/guides/draxlr_connect_2.png)

5. Save the connection
   - Click Next and if the connection is successful, choose your desired schemas. Your database is now connected to Draxlr.

## Neon analytics with visual queries and SQL

Once connected, Draxlr works as a Neon analytics tool that lets you analyze data in multiple ways.

- **Visual Query Builder for Neon Analytics**: Build queries using a point-and-click interface. Select tables, define joins, apply filters, and create aggregations without writing SQL.
  ![Draxlr Visual Query Builder](https://neon.com/docs/guides/draxlr_queries_1.png)
- **Raw SQL for Neon Reporting and Analysis**: Switch to raw query mode to write SQL directly. This is ideal for advanced queries, performance tuning, or when you want full control over your Postgres queries.
  ![Draxlr Raw SQL Mode](https://neon.com/docs/guides/draxlr_queries_2.png)

You can freely move between visual queries and SQL, making it easy to start visually and refine queries as needed.

## Ask questions with AI chat

Draxlr also includes an AI-powered chat interface that lets you ask questions about your Lakebase Postgres data in natural language.

For example, you can ask:

- "What were the top 5 customers by revenue last month?"
- "Show me daily signups for the past 30 days."
- "Compare average order value by region."
  ![Draxlr AI Chat](https://neon.com/docs/guides/draxlr_queries_3.png)

Draxlr translates these questions into database queries, runs them on your database, and returns results as tables or visualizations - no SQL required.

## What's next?

With Draxlr and Neon, you can go beyond one-off queries and build reliable Neon analytics workflows.

You can:

1. Monitor key metrics from your database in real time and receive automated alerts via email or Slack when values changes.
2. Create live Neon dashboards and embed them into customer facing applications for interactive analytics.

Together, Draxlr and Neon provide a simple way to analyze, monitor, and visualize your data.

--- [Document source](https://neon.com/docs/guides/drizzle-migrations.md) ---

> Summary: Drizzle ORM schema migrations with Lakebase Postgres walks through defining TypeScript schemas, generating SQL migration files with drizzle-kit, and applying them to a database via the Neon serverless driver. Use this guide when you need a complete migration workflow for a Node.js TypeScript project, including initial table creation, seeding, and iterative schema changes. The guide uses drizzle-orm, drizzle-kit, @neondatabase/serverless, and Hono.js, and requires a direct (non-pooled) connection string for migrations.

# Schema migration with Lakebase Postgres and Drizzle ORM

Set up a database on Neon and run migrations for your TypeScript project using Drizzle ORM

Last updated: 2026-09-16

[Drizzle](https://orm.drizzle.team/) is a TypeScript-first ORM that connects to all major databases and works across most Javascript runtimes. It provides a simple way to define database schemas and queries in an SQL-like dialect and tools to generate and run migrations.

This guide shows how to use `Drizzle` with the Lakebase Postgres database in a Typescript project. We'll create a simple Node.js application with `Hono.js` and demonstrate the full workflow of setting up and working with your database using `Drizzle`.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select a project or click the `New Project` button to create a new one.

### Retrieve your Neon database connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

**Note:** Neon supports both direct and pooled database connection strings, which you can find by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. A pooled connection string connects your application to the database via a PgBouncer connection pool, allowing for a higher number of concurrent connections. However, using a pooled connection string for migrations can lead to errors. For this reason, we recommend using a direct (non-pooled) connection when performing migrations. For more information about direct and pooled connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Setting up the TypeScript application

### Create a new Hono.js project

We'll create a simple catalog, with API endpoints that query the database for authors and a list of their books. Run the following command in your terminal to set up a new project using `Hono.js`:

```bash
npm create hono@latest neon-drizzle-guide
```

This initiates an interactive CLI prompt to set up a new project. To follow along with this guide, you can use the following settings:

```bash
Need to install the following packages:
create-hono@0.9.0
Ok to proceed? (y) y

create-hono version 0.9.0
✔ Using target directory … neon-drizzle-guide
✔ Which template do you want to use? ' nodejs
cloned honojs/starter#main to ./repos/javascript/neon-drizzle-guide
✔ Do you want to install project dependencies? … yes
✔ Which package manager do you want to use? ' npm
```

To use Drizzle and connect to the Neon database, we also add the `drizzle-orm` and `drizzle-kit` packages to our project, along with the `Neon serverless` driver library.

```bash
cd neon-drizzle-guide && touch .env
npm install drizzle-orm @neondatabase/serverless
npm install -D drizzle-kit dotenv
```

Add the `DATABASE_URL` environment variable to your `.env` file, which you'll use to connect to our Neon database. Use the connection string that you obtained from the Neon Console earlier:

```bash
# .env
DATABASE_URL=NEON_DATABASE_CONNECTION_STRING
```

Test that the starter `Hono.js` application works by running `npm run dev` in the terminal. You should see the `Hello, Hono!` message when you navigate to `http://localhost:3000` in your browser.

### Set up the database schema

Now, we will define the schema for the application using the `Drizzle` ORM. Create a new `schema.ts` file in your `src` directory and add the following code:

```typescript
// src/schema.ts

import { pgTable, integer, serial, text, timestamp } from 'drizzle-orm/pg-core';

export const authors = pgTable('authors', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  bio: text('bio'),
  createdAt: timestamp('created_at').notNull().defaultNow(),
});

export const books = pgTable('books', {
  id: serial('id').primaryKey(),
  title: text('title').notNull(),
  authorId: integer('author_id').references(() => authors.id),
  createdAt: timestamp('created_at').notNull().defaultNow(),
});
```

The code defines two tables: `authors`, which will contain the list of all the authors, and `books`, which will contain the list of books written by the authors. Each book is associated with an author using the `authorId` field.

To generate a migration to create these tables in the database, we'll use the `drizzle-kit` command. Add the following script to the `package.json` file at the root of your project:

```json
{
  "scripts": {
    "db:generate": "drizzle-kit generate --dialect=postgresql --schema=src/schema.ts --out=./drizzle"
  }
}
```

Then, run the following command in your terminal to generate the migration files:

```bash
npm run db:generate
```

This command generates a new folder named `drizzle` containing the migration files for the `authors` and `books` tables.

### Run the migration

The generated migration file is written in SQL and contains the necessary commands to create the tables in the database. To apply these migrations, we'll use the [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver) and helper functions provided by the `drizzle-orm` library.

Create a new `migrate.ts` in your `src` directory and add the following code:

```typescript
// src/migrate.ts

import { drizzle } from 'drizzle-orm/neon-http';
import { neon } from '@neondatabase/serverless';
import { migrate } from 'drizzle-orm/neon-http/migrator';
import { config } from 'dotenv';

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

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle(sql);

const main = async () => {
  try {
    await migrate(db, { migrationsFolder: 'drizzle' });
    console.log('Migration completed');
  } catch (error) {
    console.error('Error during migration:', error);
    process.exit(1);
  }
};

main();
```

The `drizzle-orm` package comes with an integration for `Neon`, which allows us to run the migrations using the `migrate` function. Add a new script to the `package.json` file that executes the migration.

```json
{
  "scripts": {
    "db:migrate": "tsx ./src/migrate.ts"
  }
}
```

You can now run the migration script using the following command:

```bash
npm run db:migrate
```

You should see the `Migration completed` message in the terminal, indicating that the migration was successful.

### Seed the database

To test the application works, we need to add some example data to our tables. Create a new file at `src/seed.ts` and add the following code to it:

```typescript
// src/seed.ts

import { drizzle } from 'drizzle-orm/neon-http';
import { neon } from '@neondatabase/serverless';
import { authors, books } from './schema';
import { config } from 'dotenv';

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

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle(sql);

async function seed() {
  await db.insert(authors).values([
    {
      name: 'J.R.R. Tolkien',
      bio: 'The creator of Middle-earth and author of The Lord of the Rings.',
    },
    {
      name: 'George R.R. Martin',
      bio: 'The author of the epic fantasy series A Song of Ice and Fire.',
    },
    {
      name: 'J.K. Rowling',
      bio: 'The creator of the Harry Potter series.',
    },
  ]);

  const authorRows = await db.select().from(authors);
  const authorIds = authorRows.map((row) => row.id);

  await db.insert(books).values([
    {
      title: 'The Fellowship of the Ring',
      authorId: authorIds[0],
    },
    {
      title: 'The Two Towers',
      authorId: authorIds[0],
    },
    {
      title: 'The Return of the King',
      authorId: authorIds[0],
    },
    {
      title: 'A Game of Thrones',
      authorId: authorIds[1],
    },
    {
      title: 'A Clash of Kings',
      authorId: authorIds[1],
    },
    {
      title: "Harry Potter and the Philosopher's Stone",
      authorId: authorIds[2],
    },
    {
      title: 'Harry Potter and the Chamber of Secrets',
      authorId: authorIds[2],
    },
  ]);
}

async function main() {
  try {
    await seed();
    console.log('Seeding completed');
  } catch (error) {
    console.error('Error during seeding:', error);
    process.exit(1);
  }
}

main();
```

This script inserts some seed data into the `authors` and `books` tables. Add a new script to the `package.json` file that runs the seeding program.

```json
{
  "scripts": {
    "db:seed": "tsx ./src/seed.ts"
  }
}
```

Run the seed script using the following command:

```bash
npm run db:seed
```

You should see the `Seeding completed` message in the terminal, indicating that the seed data was inserted into the database.

### Implement the API endpoints

Now that the database is set up and populated with data, we can implement the API to query the authors and their books. Replace the existing `src/index.ts` file with the following code:

```typescript
// src/index.ts

import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { env } from 'hono/adapter';
import { config } from 'dotenv';

import { eq } from 'drizzle-orm';
import { drizzle } from 'drizzle-orm/neon-http';
import { neon } from '@neondatabase/serverless';
import { authors, books } from './schema';

config({ path: '.env' });
const app = new Hono();

app.get('/', (c) => {
  return c.text('Hello, this is a catalog of books!');
});

app.get('/authors', async (c) => {
  const { DATABASE_URL } = env<{ DATABASE_URL: string }>(c);
  const sql = neon(DATABASE_URL);
  const db = drizzle(sql);

  const output = await db.select().from(authors);
  return c.json(output);
});

app.get('/books/:authorId', async (c) => {
  const { DATABASE_URL } = env<{ DATABASE_URL: string }>(c);
  const sql = neon(DATABASE_URL);
  const db = drizzle(sql);

  const authorId = c.req.param('authorId');
  const output = await db
    .select()
    .from(books)
    .where(eq(books.authorId, Number(authorId)));
  return c.json(output);
});

const port = 3000;
console.log(`Server is running on port ${port}`);

serve({
  fetch: app.fetch,
  port,
});
```

This code sets up a simple API with two endpoints: `/authors` and `/books/:authorId`. The `/authors` endpoint returns a list of all the authors, and the `/books/:authorId` endpoint returns a list of books written by the specific author with the given `authorId`.

Run the application using the following command:

```bash
npm run dev
```

This will start a `Hono.js` server at `http://localhost:3000`. Navigate to `http://localhost:3000/authors` and `http://localhost:3000/books/1` in your browser to check that the API works as expected.

## Migration after a schema change

To demonstrate how to execute a schema change, we'll add a new column to the `authors` table, listing the country of origin for each author.

### Generate the new migration

Modify the code in the `src/schema.ts` file to add the new column to the `authors` table:

```typescript
// src/schema.ts

import { pgTable, integer, serial, text, timestamp } from 'drizzle-orm/pg-core';

export const authors = pgTable('authors', {
  id: serial('id').primaryKey(),
  name: text('name').notNull(),
  bio: text('bio'),
  country: text('country'),
  createdAt: timestamp('created_at').notNull().defaultNow(),
});

export const books = pgTable('books', {
  id: serial('id').primaryKey(),
  title: text('title').notNull(),
  authorId: integer('author_id').references(() => authors.id),
  createdAt: timestamp('created_at').notNull().defaultNow(),
});
```

Now, we can run the following command to generate a new migration file:

```bash
npm run db:generate
```

This command generates a new migration file in the `drizzle` folder, with the SQL command to add the new column to the `authors` table.

### Run the migration

Run the migration script using the following command:

```bash
npm run db:migrate
```

You should see the `Migration completed` message in the terminal, indicating it was successful.

### Verify the schema change

To verify that the schema change was successful, run the application using the following command:

```bash
npm run dev
```

You can navigate to `http://localhost:3000/authors` in your browser to check that each author entry has a `country` field, currently set to `null`.

## Conclusion

In this guide, we set up a new TypeScript project using `Hono.js` and `Drizzle` ORM and connected it to a `Neon` Postgres database. We created a schema for the database, generated and ran migrations, and implemented API endpoints to query the database.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Migrations with Neon and Drizzle](https://github.com/neondatabase/guide-neon-drizzle): Run Neon database migrations using Drizzle

## Resources

For more information on the tools used in this guide, refer to the following resources:

- [Drizzle ORM](https://orm.drizzle.team/)
- [Hono.js](https://hono.dev/)

--- [Document source](https://neon.com/docs/guides/drizzle.md) ---

> Summary: Drizzle ORM connection guide for Lakebase Postgres on Neon walks through initializing a TypeScript/Node.js project with supported drivers: Neon serverless HTTP, Neon WebSocket, node-postgres, and postgres.js. Use this page when you need type-safe queries plus Drizzle Kit migrations against a Lakebase Postgres database on Neon and want to pick the right driver for serverless or long-running environments. The guide also shows how to point Drizzle at different Neon branches per environment by selecting a connection string based on NODE_ENV.

# Connect from Drizzle to Neon

Learn how to connect to Neon from Drizzle

Last updated: 2026-10-08

**Realtime with Drizzle:**

See how to subscribe to live SQL queries with [Neon Realtime + Drizzle](https://neon.com/docs/realtime/examples/drizzle)

Pre-built prompt for connecting Node/TypeScript applications to Neon using Drizzle ORM. [View prompt](https://neon.com/prompts/drizzle-prompt.md)

**What you will learn:**

- How to connect from Drizzle using different drivers
- How to configure Drizzle Kit for migrations

**Related resources**

- [Drizzle with Neon Postgres (Drizzle Docs)](https://orm.drizzle.team/docs/tutorials/drizzle-with-neon)
- [Schema migration with Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations)
- [Getting started with Neon (Next.js and Drizzle video)](https://neon.com/docs/guides/nextjs#video-walkthrough)

Drizzle is a TypeScript ORM with type-safe queries. This guide shows you how to connect your application to a database on Neon using Drizzle ORM.

To connect a TypeScript/Node.js project to Neon using Drizzle ORM, follow these steps:

## Create a TypeScript/Node.js project

Create a new directory for your project and navigate into it:

```bash
mkdir my-drizzle-neon-project
cd my-drizzle-neon-project
```

Initialize a new Node.js project with a `package.json` file:

```bash
npm init -y
```

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Get your connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select a branch, a user, and the database you want to connect to. A connection string is constructed for you.
![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)
The connection string includes the user name, password, hostname, and database name.

Create a `.env` file in your project's root directory and add the connection string to it. Your `.env` file should look like this:

```text
# Pooled connection for your application
DATABASE_URL="postgresql://[user]:[password]@[endpoint]-pooler.[region].aws.neon.tech/[dbname]?sslmode=require&channel_binding=require"

# Unpooled connection for Drizzle Kit
DATABASE_URL_UNPOOLED="postgresql://[user]:[password]@[endpoint].[region].aws.neon.tech/[dbname]?sslmode=require&channel_binding=require"
```

**Note:** Neon supports both direct and pooled connection strings, which you can find by clicking the **Connect** button in the Console nav. A pooled connection string (the hostname includes `-pooler`) routes through a PgBouncer connection pool, which suits your application at runtime. However, using a pooled connection string for migrations can lead to errors. Use a direct (non-pooled) connection when running Drizzle Kit migrations. If you only have the pooled string, remove `-pooler` from the hostname to get the direct one. For more information, see [Connection pooling](https://neon.com/docs/connect/connection-pooling) and [Schema migration with Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations).

## Install Drizzle and a driver

Install Drizzle ORM, Drizzle Kit for migrations, `tsx` to run TypeScript, and a database driver. If you're not sure which driver to use, choose `node-postgres` for a Node.js server or script, and the Neon serverless HTTP driver for serverless and edge functions. For more detail, see [Choosing your connection method](https://neon.com/docs/connect/choose-connection).

**Neon Serverless (HTTP)**

Use the Neon serverless HTTP driver for serverless environments (for example, Vercel, Netlify).

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

**Neon WebSocket**

Use the Neon WebSocket driver when you need sessions or interactive transactions in a serverless or edge environment.

```bash
npm install drizzle-orm @neondatabase/serverless ws dotenv
npm install -D drizzle-kit tsx @types/ws
```

**node-postgres**

Use the `node-postgres` (`pg`) driver for Node.js servers and scripts that keep a TCP connection pool.

```bash
npm install drizzle-orm pg dotenv
npm install -D drizzle-kit tsx @types/pg
```

`pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. To keep the current behavior and remove the warning, change `sslmode=require` to `sslmode=verify-full` in both connection strings.

**postgres.js**

Use the `postgres.js` driver, another TCP driver for Node.js servers and scripts.

```bash
npm install drizzle-orm postgres dotenv
npm install -D drizzle-kit tsx
```

## Configure Drizzle Kit

Drizzle Kit uses a configuration file to manage schema and migrations. Create a `drizzle.config.ts` file in your project root and add the following content. This configuration tells Drizzle where to find your schema and where to output migration files.

```typescript
import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';

if (!process.env.DATABASE_URL_UNPOOLED) {
  throw new Error('DATABASE_URL_UNPOOLED is not set in the .env file');
}

export default defineConfig({
  schema: './src/schema.ts', // Your schema file path
  out: './drizzle', // Your migrations folder
  dialect: 'postgresql',
  dbCredentials: {
    url: process.env.DATABASE_URL_UNPOOLED,
  },
});
```

**Tip: Loading a .env.local file**

`import 'dotenv/config'` loads variables from a `.env` file. If you keep your connection string in `.env.local` (a common convention in Next.js and other frameworks), point dotenv at it explicitly instead:

```typescript
import { config } from 'dotenv';
config({ path: '.env.local' });

import { defineConfig } from 'drizzle-kit';

if (!process.env.DATABASE_URL_UNPOOLED) {
  throw new Error('DATABASE_URL_UNPOOLED is not set in .env.local');
}

// ...rest of config unchanged
```

## Initialize the Drizzle client

Create a file: `src/db.ts`, to initialize and export your Drizzle client. The setup varies depending on the driver you installed.

**Neon Serverless (HTTP)**

```typescript
import 'dotenv/config';
import { drizzle } from 'drizzle-orm/neon-http';
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);
export const db = drizzle(sql);
```

**Neon WebSocket**

```typescript
import 'dotenv/config';
import { drizzle } from 'drizzle-orm/neon-serverless';
import { Pool, neonConfig } from '@neondatabase/serverless';
import ws from 'ws';

// For Node.js environments older than v22, you must provide a WebSocket constructor
neonConfig.webSocketConstructor = ws;

// To work in edge environments (Cloudflare Workers, Vercel Edge, etc.), enable querying over fetch
// neonConfig.poolQueryViaFetch = true

const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
export const db = drizzle(pool);
```

**node-postgres**

```typescript
import 'dotenv/config';
import { drizzle } from 'drizzle-orm/node-postgres';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL!,
});

export const db = drizzle(pool);
```

**postgres.js**

```typescript
import 'dotenv/config';
import { drizzle } from 'drizzle-orm/postgres-js';
import postgres from 'postgres';

const client = postgres(process.env.DATABASE_URL!);
export const db = drizzle(client);
```

## Create a schema

Drizzle uses a schema-first approach, allowing you to define your database schema using TypeScript. This schema will be used to generate migrations and ensure type safety throughout your application.

The following example defines a schema for a simple `demo_users` table. Create a `src/schema.ts` file and add the following content:

```typescript
import { pgTable, serial, text } from 'drizzle-orm/pg-core';

export const demoUsers = pgTable('demo_users', {
  id: serial('id').primaryKey(),
  name: text('name'),
});
```

## Generate migrations

After defining your schema, you can generate migration files with Drizzle Kit. This will create the necessary SQL files to set up your database schema in Neon.

```bash
npx drizzle-kit generate
```

You should see output similar to the following, indicating that migration files have been created:

```bash
$ npx drizzle-kit generate
No config path provided, using default 'drizzle.config.ts'
Reading config file '/home/user/drizzle/drizzle.config.ts'
1 tables
demo_users 2 columns 0 indexes 0 fks

[✓] Your SQL migration file ➜ drizzle/0000_clever_purple_man.sql 🚀
```

You can find the generated SQL migration files in the `drizzle` directory specified in your `drizzle.config.ts`.

## Apply migrations

Apply the generated migrations (SQL files) to your Neon database using Drizzle Kit. This command will use the `drizzle.config.ts` file for database connection details and apply the migrations to your Neon database.

```bash
npx drizzle-kit migrate
```

You should see output similar to the following, indicating that the migrations have been applied successfully:

```bash
$ npx drizzle-kit migrate
No config path provided, using default 'drizzle.config.ts'
Reading config file '/home/user/drizzle/drizzle.config.ts'
Using 'pg' driver for database querying
```

The driver line depends on the driver you installed. With `@neondatabase/serverless`, Drizzle Kit also warns that it can only connect to Neon through a websocket. The migration still applies, so you can ignore that warning.

You can verify that the `demo_users` table has been created in your Neon database by checking the **Tables** section in the Neon Console.

## Query the database

Create a file: `src/index.ts`, to interact with your database using the Drizzle client. Here's an example of inserting a new user and querying all users from the `demo_users` table:

**Neon Serverless (HTTP)**

```typescript
import { db } from './db';
import { demoUsers } from './schema';

async function main() {
  try {
    await db.insert(demoUsers).values({ name: 'John Doe' });
    const result = await db.select().from(demoUsers);
    console.log('Successfully queried the database:', result);
  } catch (error) {
    console.error('Error querying the database:', error);
  }
}

main();
```

**Neon WebSocket / node-postgres / postgres.js**

```typescript
import { db } from './db';
import { demoUsers } from './schema';

async function main() {
  try {
    await db.insert(demoUsers).values({ name: 'John Doe' });
    const result = await db.select().from(demoUsers);
    console.log('Successfully queried the database:', result);
  } catch (error) {
    console.error('Error querying the database:', error);
  } finally {
    // Close the database connection to ensure proper shutdown for Neon WebSocket, node-postgres, and postgres.js drivers
    await db.$client.end();
  }
}

main();
```

Run the script using `tsx`:

```bash
npx tsx src/index.ts
```

You should see output similar to the following, indicating that the user was inserted and queried successfully:

```bash
Successfully queried the database: [ { id: 1, name: 'John Doe' } ]
```

## Using Neon branches with Drizzle

You can point Drizzle at different Neon [branches](https://neon.com/docs/introduction/branching) per environment by selecting the connection string based on `NODE_ENV` (or any other environment variable):

```typescript
import { drizzle } from 'drizzle-orm/neon-http';
import { neon } from '@neondatabase/serverless';

const getBranchUrl = () => {
  const env = process.env.NODE_ENV;
  if (env === 'development') return process.env.DEV_DATABASE_URL;
  if (env === 'test') return process.env.TEST_DATABASE_URL;
  return process.env.DATABASE_URL;
};

const sql = neon(getBranchUrl()!);
export const db = drizzle({ client: sql });
```

Each branch has its own connection string, available in the Neon Console or via the CLI (`neon connection-string <branch-id-or-name> --project-id <project-id>`).

## Resources

- [Get Started with Drizzle and Neon](https://orm.drizzle.team/docs/get-started/neon-new)
- [Drizzle with Neon Postgres](https://orm.drizzle.team/docs/tutorials/drizzle-with-neon)
- [Schema migration with Lakebase Postgres and Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations)
- [Todo App with Neon Postgres and Drizzle ORM](https://orm.drizzle.team/docs/tutorials/drizzle-nextjs-neon)

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/examples/drizzle): Build realtime Drizzle apps on Neon using your existing schema and queries

--- [Document source](https://neon.com/docs/guides/elixir-ecto.md) ---

> Summary: Elixir Ecto connection guide walks through adding ecto_sql and Postgrex dependencies, configuring SSL with cacerts against a Neon Serverless Postgres database, and running migrations via mix ecto.migrate. Choose this page when setting up a new Elixir project that connects to Neon and needs to account for Postgrex idle_interval defaults that can prevent Neon's scale-to-zero autosuspend from triggering.

# Connect from Elixir with Ecto to Neon

Set up a Neon project in seconds and connect from Elixir with Ecto

Last updated: 2026-10-09

Pre-built prompt for connecting Elixir applications to Neon with Ecto [View prompt](https://neon.com/prompts/elixir-ecto-prompt.md)

This guide describes how to connect from an Elixir application with Ecto, which is a database wrapper and query generator for Elixir. Ecto provides an API and abstractions for interacting databases, enabling Elixir developers to query any database using similar constructs.

The instructions in this guide follow the steps outlined in the [Ecto Getting Started](https://ecto.hexdocs.pm/getting-started.html) guide, modified to demonstrate connecting to a Neon Serverless Postgres database. It is assumed that you have a working installation of [Elixir](https://elixir-lang.org/install.html).

To connect to Neon from Elixir with Ecto:

## Create a database in Neon and copy the connection string

The instructions in this configuration use a database named `friends`.

To create the database:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select **Postgres database** > **Databases**.
4. Select the branch where you want to create the database.
5. Click **Add database**.
6. Enter a database name (`friends`), and select a database owner.
7. Click **Create**.

You can also create the database with SQL. Connect to the `neondb` database on your branch, for example with `psql`, and run the following command:

```sql
CREATE DATABASE friends;
```

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select a branch, a role, and the database you want to connect to. A connection string is constructed for you. Your connection string should look something like this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-west-2.aws.neon.tech/friends?sslmode=require&channel_binding=require
```

You will need the connection string details later in the setup.

## Create an Elixir project

Create an Elixir application called `friends`.

```bash
mix new friends --sup
```

The `--sup` option ensures that the application has a supervision tree, which is required by Ecto.

## Add Ecto and Postgrex to the application

1. Add the Ecto and the Postgrex driver dependencies to the `mix.exs` file by updating the `deps` definition in the file to include those items. For example:

   ```elixir filename="mix.exs"
   defp deps do
     [
       {:ecto_sql, "~> 3.0"},
       {:postgrex, "~> 0.22"}
     ]
   end
   ```

   Ecto provides the common querying API. The Postgrex driver acts as a bridge between Ecto and Postgres. Ecto interfaces with its own `Ecto.Adapters.Postgres` module, which communicates to Postgres through the Postgrex driver.

2. Install the Ecto and the Postgrex driver dependencies by running the following command in your application directory:

   ```bash
   mix deps.get
   ```

## Configure Ecto

Run the following command in your application directory to generate the configuration required to connect from Ecto to your Neon database.

```bash
mix ecto.gen.repo -r Friends.Repo
```

Follow these steps to complete the configuration:

1. The first part of the configuration generated by the `mix ecto.gen.repo` command is found in the `config/config.exs` file. Update this configuration with your Neon database connection details. Use the connection details from the Neon connection string you copied in the first part of the guide. Your `hostname` will differ from the example below.

   ```elixir
   config :friends, Friends.Repo,
     database: "friends",
     username: "alex",
     password: "AbC123dEf",
     hostname: "ep-cool-darkness-123456.us-west-2.aws.neon.tech",
     ssl: [cacerts: :public_key.cacerts_get()]
   ```

   The `:ssl` option is required to connect to Neon. Postgrex, since v0.18, verifies the server SSL certificate and you need to select CA trust store using `:cacerts` or `:cacertfile` options. You can use the OS-provided CA store by setting `cacerts: :public_key.cacerts_get()`. While not recommended, you can disable certificate verification by setting `ssl: [verify: :verify_none]`.

   **Note:** Postgrex has an `:idle_interval` connection parameter that defines an interval for pinging connections after a period of inactivity. The default setting is `1000ms`. If you rely on Neon's [autosuspend](https://neon.com/docs/introduction/scale-to-zero) feature to scale your compute to zero when your database is not active, this setting will prevent that. For more, see [Postgrex: DBConnection ConnectionError ssl send: closed](https://neon.com/docs/connect/connection-errors#postgrex-dbconnection-connectionerror-ssl-send-closed).

2. The second part of the configuration generated by the `mix ecto.gen.repo` command is the `Ecto.Repo` module, found in `lib/friends/repo.ex`. You shouldn't have to make any changes here, but verify that the following configuration is present:

   ```elixir
   defmodule Friends.Repo do
     use Ecto.Repo,
       otp_app: :friends,
       adapter: Ecto.Adapters.Postgres
   end
   ```

   Ecto uses the module definition to query the database. The `otp_app` setting tells Ecto where to find the database configuration. In this case, the `:friends` application is specified, so Ecto will use the configuration defined in the that application's `config/config.exs` file. The `:adapter` option defines the Postgres adapter.

3. Next, the `Friends.Repo` must be defined as a supervisor within the application's supervision tree. In `lib/friends/application.ex`, make sure `Friends.Repo` is specified in the `start` function, as shown:

   ```elixir
   def start(_type, _args) do
     children = [
       Friends.Repo,
     ]
   ```

   This configuration starts the Ecto process, enabling it to receive and execute the application's queries.

4. The final part of the configuration is to add the following line under the configuration in the `config/config.exs` file that you updated in the first step:

   ```elixir
   config :friends, ecto_repos: [Friends.Repo]
   ```

   This line tells the application about the new repo, allowing you to run commands such as `mix ecto.migrate`, which you will use in a later step to create a table in your database.

## Create a migration and add a table

Your `friends` database is currently empty. It has no tables or data. In this step, you will add a table. To do so, you will create a "migration" by running the following command in your application directory:

```bash
mix ecto.gen.migration create_people
```

The command generates an empty migration file in `priv/repo/migrations`, which looks like this:

```elixir
defmodule Friends.Repo.Migrations.CreatePeople do
  use Ecto.Migration

  def change do

  end
end
```

Add code to the migration file to create a table called `people`. For example:

```elixir
defmodule Friends.Repo.Migrations.CreatePeople do
  use Ecto.Migration

  def change do
    create table(:people) do
      add :first_name, :string
      add :last_name, :string
      add :age, :integer
    end
  end
end
```

To run the migration and create the `people` table in your database, which also verifies your connection to Neon, run the following command from your application directory:

```bash
mix ecto.migrate
```

The output of this command should appear similar to the following:

```bash
14:30:04.924 [info]  == Running 20230524172817 Friends.Repo.Migrations.CreatePeople.change/0 forward
14:30:04.925 [info]  create table people
14:30:05.014 [info]  == Migrated 20230524172817 in 0.0s
```

You can use the **Tables** feature in the Neon Console to view the table that was created:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select **Postgres database** > **Tables** from the sidebar.
4. Select the Branch, Database (`friends`), and the schema (`public`). You should see the `people` table along with a `schema_migrations` table that was created by the migration.

## Application code

You can find the application code for the example above on GitHub.

- [Neon Ecto Getting Started App](https://github.com/neondatabase/neon-ecto-getting-started-app): Learn how to connect from Elixir with Ecto to Neon

## Next steps

The [Ecto Getting Started Guide](https://ecto.hexdocs.pm/getting-started.html) provides additional steps that you can follow to create a schema, insert data, and run queries. See [Creating the schema](https://ecto.hexdocs.pm/getting-started.html#creating-the-schema) in the _Ecto Getting Started Guide_ to pick up where the steps in this guide leave off.

## Next steps with Neon backend services

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Usage notes

- Suppose you have `PGHOST` environment variable on your system set to something other than your Neon hostname. In that case, this hostname will be used instead of the Neon `hostname` defined in your Ecto Repo configuration when running `mix ecto` commands. To avoid this issue, you can either set the `PGHOST` environment variable to your Neon hostname or specify `PGHOST=""` when running `mix ecto` commands; for example: `PGHOST="" mix ecto.migrate`.
- Neon's _Scale to Zero_ feature scales computes to zero after 300 seconds (5 minutes) of inactivity, which can result in a `connection not available` error when running `mix ecto` commands. Typically, a Neon compute takes a few hundred milliseconds to transition from `Idle` to `Active`. Wait a second or two and try running the command again. Alternatively, consider the strategies outlined in [Connection latency and timeouts](https://neon.com/docs/connect/connection-latency) to manage connection issues resulting from compute suspension.

--- [Document source](https://neon.com/docs/guides/elixir.md) ---

> Summary: Postgrex-based guide for connecting an Elixir app to a Lakebase serverless Postgres database using raw SQL over SSL, covering project setup with mix, credential configuration in config.exs, and CRUD operations. Use this page when you want direct Postgrex access without an ORM; for Ecto-based integration see the Elixir Ecto guide.

# Connect an Elixir application to Lakebase Postgres

Learn how to run SQL queries in Neon from Elixir using Postgrex

Last updated: 2026-10-09

Pre-built prompt for connecting Elixir applications to Neon [View prompt](https://neon.com/prompts/elixir-prompt.md)

This guide describes how to create a Neon project and connect to it from an Elixir application using [Postgrex](https://hex.pm/packages/postgrex), a Postgres driver for Elixir.

You'll learn how to connect to your database from an Elixir application, and perform basic Create, Read, Update, and Delete (CRUD) operations.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://console.neon.tech/signup).
- Elixir v1.15 or later. If you do not have Elixir installed, see the [official installation guide](https://elixir-lang.org/install.html).

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Your project is created with a ready-to-use database named `neondb`. In the following steps, you will connect to this database from your Elixir application.

## Create an Elixir project

For your Elixir project, create a project directory using `mix` and add the required library.

1. Create a new supervised Elixir project and change into the directory.

   ```bash
   mix new neon_elixir_quickstart --sup
   cd neon_elixir_quickstart
   ```

   > Open this directory in your preferred code editor (for example, VS Code).

2. Add `postgrex` as a dependency in your `mix.exs` file. Find the `deps` function and add `{:postgrex, "~> 0.22"}`:

   ```elixir filename="mix.exs"
   defp deps do
     [
       {:postgrex, "~> 0.22"}
     ]
   end
   ```

3. Install the dependency from your terminal:

   ```bash
   mix deps.get
   ```

## Configure your Neon connection details

You'll configure your application to connect to Neon using the `config/config.exs` file. This method securely separates your credentials from your source code.

1. In the [Neon Console](https://console.neon.tech), open your project.
2. Click **Connect** in the Console nav to open the **Connect to your branch** modal.
3. Select the **Parameters only** tab to view the connection string parameters.
   ![Connection modal](https://neon.com/docs/connect/connection_details_parameters_only.png)
4. Copy the connection string parameters (user, password, host, and database name).
5. Create the `config/config.exs` file and add a configuration block for your project, replacing the placeholder values with your actual database credentials.

   ```elixir filename="config/config.exs"
   import Config

   config :neon_elixir_quickstart,
     username: "[user]",
     password: "[password]",
     hostname: "[neon_hostname]",
     database: "[dbname]",
     ssl: [cacerts: :public_key.cacerts_get()]
   ```

   > - The `:ssl` option is required to connect securely to Neon. Using `:public_key.cacerts_get()` tells Postgrex to use the OS-provided CA trust store to verify the server's SSL certificate.
   > - The `:neon_elixir_quickstart` key matches your application's name, allowing you to fetch this configuration from your code.

## Examples

This section provides example Elixir scripts that demonstrate how to connect to your Neon database and perform basic operations such as [creating a table](https://neon.com/docs/guides/elixir#create-a-table-and-insert-data), [reading data](https://neon.com/docs/guides/elixir#read-data), [updating data](https://neon.com/docs/guides/elixir#update-data), and [deleting data](https://neon.com/docs/guides/elixir#deleting-data).

### Create a table and insert data

In your project's root directory, create a file named `create_table.exs`. This script connects to your Neon database, creates a `books` table, and inserts sample data.

```elixir filename="create_table.exs"
defmodule CreateTable do
  def run do
    # Fetch connection config
    config = Application.get_all_env(:neon_elixir_quickstart)

    # Start a connection to the database
    {:ok, pid} = Postgrex.start_link(config)
    IO.puts("Connection established")

    try do
      # Drop the table if it already exists
      Postgrex.query!(pid, "DROP TABLE IF EXISTS books;", [])
      IO.puts("Finished dropping table (if it existed).")

      # Create a new table
      Postgrex.query!(pid, """
      CREATE TABLE books (
          id SERIAL PRIMARY KEY,
          title VARCHAR(255) NOT NULL,
          author VARCHAR(255),
          publication_year INT,
          in_stock BOOLEAN DEFAULT TRUE
      );
      """, [])
      IO.puts("Finished creating table.")

      # Insert a single book record
      Postgrex.query!(
        pid,
        "INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4);",
        ["The Catcher in the Rye", "J.D. Salinger", 1951, true]
      )
      IO.puts("Inserted a single book.")

      # Data to be inserted
      books_to_insert = [
        {"The Hobbit", "J.R.R. Tolkien", 1937, true},
        {"1984", "George Orwell", 1949, true},
        {"Dune", "Frank Herbert", 1965, false}
      ]

      # Prepare a statement for efficient multiple inserts
      {:ok, statement} = Postgrex.prepare(
        pid,
        "insert_books",
        "INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4);"
      )

      # Insert multiple books
      Enum.each(books_to_insert, fn {title, author, year, stock} ->
        Postgrex.execute!(pid, statement, [title, author, year, stock])
      end)

      IO.puts("Inserted 3 rows of data.")
    rescue
      e -> IO.inspect(e, label: "An error occurred")
    end
  end
end

# Run the script
CreateTable.run()
```

The above code does the following:

- Loads the connection configuration from `config/config.exs`.
- Connects to the Neon database using `Postgrex.start_link`.
- Drops the `books` table if it already exists to ensure a clean slate.
- Creates a table named `books` with columns for `id`, `title`, `author`, `publication_year`, and `in_stock`.
- Inserts a single book record using `Postgrex.query!`.
- Uses a prepared statement with `Postgrex.prepare` and `Postgrex.execute!` for efficiently inserting multiple records.

Run the script using the following command:

```bash
mix run create_table.exs
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established
Finished dropping table (if it existed).
Finished creating table.
Inserted a single book.
Inserted 3 rows of data.
```

### Read data

In your project directory, create a file named `read_data.exs`. This script connects to your Neon database and retrieves all rows from the `books` table.

```elixir filename="read_data.exs"
defmodule ReadData do
  def run do
    config = Application.get_all_env(:neon_elixir_quickstart)
    {:ok, pid} = Postgrex.start_link(config)
    IO.puts("Connection established")

    try do
      # Fetch all rows from the books table
      result = Postgrex.query!(pid, "SELECT * FROM books ORDER BY publication_year;", [])

      IO.puts("\n--- Book Library ---")
      for row <- result.rows do
        [id, title, author, year, in_stock] = row
        IO.puts(
          "ID: #{id}, Title: #{title}, Author: #{author}, Year: #{year}, In Stock: #{in_stock}"
        )
      end
      IO.puts("--------------------\n")
    rescue
      e -> IO.inspect(e)
    end
  end
end

ReadData.run()
```

The above code does the following:

- Loads the connection configuration and connects to the database.
- Uses a SQL `SELECT` statement to fetch all rows from the `books` table, ordered by `publication_year`.
- Iterates through the `rows` field of the `Postgrex.Result` struct.
- Prints each book's details in a formatted output.

Run the script using the following command:

```bash
mix run read_data.exs
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: false
--------------------
```

### Update data

In your project directory, create a file named `update_data.exs`. This script connects to your Neon database and updates the stock status of the book 'Dune' to `true`.

```elixir filename="update_data.exs"
defmodule UpdateData do
  def run do
    config = Application.get_all_env(:neon_elixir_quickstart)
    {:ok, pid} = Postgrex.start_link(config)
    IO.puts("Connection established")

    try do
      # Update a data row in the table
      Postgrex.query!(pid, "UPDATE books SET in_stock = $1 WHERE title = $2;", [true, "Dune"])
      IO.puts("Updated stock status for 'Dune'.")
    rescue
      e -> IO.inspect(e)
    end
  end
end

UpdateData.run()
```

The above code does the following:

- Loads the connection configuration and connects to the database.
- Uses a SQL `UPDATE` statement with parameters to change the `in_stock` status of the book 'Dune' to `true`.

Run the script using the following command:

```bash
mix run update_data.exs
```

After running this script, you can run `read_data.exs` again to verify that the row was updated.

```bash
mix run read_data.exs
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the stock status for 'Dune' has been updated to `true`.

### Delete data

In your project directory, create a file named `delete_data.exs`. This script connects to your Neon database and deletes the book '1984' from the `books` table.

```elixir filename="delete_data.exs"
defmodule DeleteData do
  def run do
    config = Application.get_all_env(:neon_elixir_quickstart)
    {:ok, pid} = Postgrex.start_link(config)
    IO.puts("Connection established")

    try do
      # Delete a data row from the table
      Postgrex.query!(pid, "DELETE FROM books WHERE title = $1;", ["1984"])
      IO.puts("Deleted the book '1984' from the table.")
    rescue
      e -> IO.inspect(e)
    end
  end
end

DeleteData.run()
```

The above code does the following:

- Loads the connection configuration and connects to the database.
- Uses a SQL `DELETE` statement to remove the book '1984' from the `books` table.

Run the script using the following command:

```bash
mix run delete_data.exs
```

After running this script, you can run `read_data.exs` again to verify that the row was deleted.

```bash
mix run read_data.exs
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the book '1984' has been successfully deleted from the `books` table.

## Next steps with an ORM or framework

While this guide demonstrates how to connect to Neon using raw SQL queries, for more advanced and maintainable data interactions in your Elixir applications, consider using an Object-Relational Mapping (ORM) framework. ORMs not only let you work with data as objects but also help manage schema changes through automated migrations keeping your database structure in sync with your application models.

Explore the following resources to learn how to integrate ORMs with Neon:

- [Connect an Elixir Ecto application to Neon](https://neon.com/docs/guides/elixir-ecto)

## Next steps with Neon backend services

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Resources

- [Postgrex Documentation](https://hexdocs.pm/postgrex/Postgrex.html)

--- [Document source](https://neon.com/docs/guides/embedded-postgres.md) ---

> Summary: Embedded Postgres on Neon lets SaaS platforms and developer tools provision an isolated Postgres database per user in under 1 second via API, with autoscaling, scale-to-zero, and per-project quotas for compute time, storage, and data transfer. Use this page when building a database-per-tenant integration with no Neon sign-up required from end users. It covers the project-per-user model, API key setup, autoscaling parameters, consumption quota enforcement, and usage monitoring via the metrics endpoint.

# Embedded Postgres

Offer instant, managed Postgres databases to your users with Neon

Last updated: 2026-08-27

Neon makes it easy to embed Postgres into your platform with one-second provisioning, autoscaling, and scale-to-zero, so each user gets an isolated database without the overhead. Databases are provisioned via API and fully integrated into your product, with no Neon signup or setup required by your users.

> **Learn how platforms embed Neon**
>
> Learn how [Retool manages 300k+ Postgres databases](https://neon.com/blog/how-retool-uses-retool-and-the-neon-api-to-manage-300k-postgres-databases) and [Koyeb offers serverless Postgres](https://www.koyeb.com/blog/serverless-postgres-public-preview) using Neon.

## Why embed Neon?

Neon is uniquely built to scale Postgres fleets efficiently:

- **Instant provisioning**: Create a new Postgres database in under 1 second via API
- **Scale to zero**: Inactive databases scale to zero to save on compute cost
- **True isolation**: Each user gets their own dedicated Neon project with complete data separation
- **Autoscaling**: Databases scale compute resources automatically based on demand
- **Set quotas**: Set consumption limits per project to manage usage and costs
- **Track usage**: Track compute time, storage, and other metrics per project

## The project-per-user model

When integrating Neon into your platform, we strongly recommend a **project-per-user model** rather than branch-per-user or database-per-user models.

### What is a project?

In Neon, resources such as branches, databases, roles, computes, and backend services like object storage and functions are organized within a Neon [project](https://neon.com/docs/concepts/the-object-model). When a user signs up with Neon directly, they start by creating a project, which includes a default branch, database, role, and compute instance. We recommend the same approach for your integration.

### Why project-per-user?

- **Data isolation**: Each user's data is completely separate, ensuring the highest level of security and privacy. This also helps with compliance standards like GDPR.

- **Resource isolation**: One user's usage patterns or actions don't impact others. Each user has dedicated compute resources.

- **Easier limits and billing**: Neon's APIs for setting consumption limits and tracking usage work at the project level, making it straightforward to implement usage-based billing.

- **Regional compliance**: Each project can be deployed in a specific region, making it easy to host customer data closer to their location or meet data residency requirements.

- **Independent recovery**: Operations like instant [point-in-time restore](https://neon.com/docs/guides/branch-restore) work at the branch level. In a project-per-user model, you can restore individual customer databases without impacting others.

- **Simpler to manage**: Following Neon's established project-based structure is easier than working against it. The Neon API is designed around this model.

**Note:** The project-per-user model implements a database-per-tenant architecture. For a deeper dive into this approach and how Neon compares to traditional solutions like RDS, read [Data Isolation at Scale](https://neon.com/use-cases/database-per-tenant).

## Getting started

## Set up API access

To interact with the Neon platform, you'll need an API key:

1. Generate a Neon API key from your Neon account settings. See [Creating API keys](https://neon.com/docs/manage/api-keys#creating-api-keys).
2. Store the key securely in your environment variables.
3. Use the API key to authenticate requests to the Neon API.

For detailed API documentation, refer to the [Neon API Reference](https://neon.com/docs/reference/api), which includes links to [Neon API examples](https://neon.com/docs/reference/api/get-started).

Alternatively, use our official SDKs for easier integration:

- [TypeScript SDK](https://neon.com/docs/reference/typescript-sdk)
- [Python SDK](https://neon.com/docs/reference/python-sdk)

## Create projects for your users

Use the [Create project API](https://neon.com/docs/reference/api/projects/create-project) to provision a new Postgres database for each user:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "name": "user-database-123",
    "pg_version": 16,
    "region_id": "aws-us-east-1"
  }
}' | jq
```

The response includes connection details you can provide to your user. Projects are created in under 1 second.

**Tip: Custom names**

You can customize the default database and role names when creating a project. See the [Create project API docs](https://neon.com/docs/reference/api/projects/create-project) for details.

## Set compute and scaling behavior

Configure how computes scale and when they suspend due to inactivity:

- `autoscaling_limit_min_cu`: Minimum compute size (default: 0.25 CU)
- `autoscaling_limit_max_cu`: Maximum compute size for autoscaling
- `suspend_timeout_seconds`: Inactivity period before compute suspends

Example setting a compute to scale between 1 and 4 CU with a 10-minute suspend timeout:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 4,
      "suspend_timeout_seconds": 600
    },
    "pg_version": 16
  }
}'
```

For more on autoscaling, see [Autoscaling](https://neon.com/docs/introduction/autoscaling) and [Scale to zero](https://neon.com/docs/introduction/scale-to-zero).

## Configure consumption limits

Set limits on compute time, storage, and data transfer to control costs and implement your pricing tiers. You can configure these limits when creating a project or update them later.

Here's an example setting limits for a "starter" tier user:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '{
  "project": {
    "settings": {
      "quota": {
        "active_time_seconds": 36000,
        "compute_time_seconds": 9000,
        "written_data_bytes": 1000000000,
        "data_transfer_bytes": 500000000,
        "logical_size_bytes": 100000000
      }
    },
    "name": "starter-tier-user",
    "pg_version": 16
  }
}'
```

When a quota is reached, the project's computes are automatically suspended until the next billing period or until you adjust the limits.

For detailed information about configuring limits, see [Configure consumption limits](https://neon.com/docs/guides/consumption-limits).

Here's a fictional example of how you might structure your own pricing tiers using Neon's consumption quotas:

| Resource          | Free Tier       | Pro Tier        | Enterprise |
| ----------------- | --------------- | --------------- | ---------- |
| Compute (min/max) | 0.25 / 0.25 CU  | 0.25 / 2 CU     | 1 / 8 CU   |
| Active time       | 100 hours/month | 750 hours/month | Unlimited  |
| Storage           | 512 MB          | 10 GB           | 100 GB+    |
| Data transfer     | 5 GB            | 50 GB           | Custom     |

For real-world examples, see how [Koyeb defines their database instance types and pricing](https://www.koyeb.com/docs/databases#database-instance-types-and-pricing).

## Monitor usage

Query consumption metrics to track usage across your projects and implement billing:

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/consumption_history/v2/projects?org_id=$ORG_ID&from=2024-11-01T00:00:00Z&to=2024-11-30T23:59:59Z&granularity=daily&metrics=compute_unit_seconds,root_branch_bytes_month,child_branch_bytes_month,public_network_transfer_bytes' \
     --header 'accept: application/json' \
     --header "authorization: Bearer $NEON_API_KEY"
```

The v2 project metrics endpoint returns billing-aligned metrics including compute, storage, and data transfer. To break usage down by branch within a project, use the [branch metrics endpoint](https://neon.com/docs/guides/consumption-metrics#branch-metrics) (`GET /consumption_history/v2/branches`).

For details on querying metrics, see [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics).

## Key considerations

Before going to production, consider these important aspects:

### Connection limits

Be aware of the [connection limits](https://neon.com/docs/connect/connection-pooling#connection-limits-without-connection-pooling) associated with each compute size. Connection pooling allows for significantly more concurrent connections. If you expect a high number of connections, we recommend using a pooled connection string. To learn more, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

### Reserved names

Neon reserves certain names for roles and databases. See [Reserved role names](https://neon.com/docs/manage/roles#reserved-role-names) and [Reserved database names](https://neon.com/docs/manage/databases#reserved-database-names).

### Polling consumption data

- Consumption data updates approximately every 15 minutes
- Minimum recommended polling interval: 15 minutes
- Rate limit: ~30 requests per minute per account
- Polling does NOT wake suspended computes

See [Consumption polling](https://neon.com/docs/guides/consumption-metrics#consumption-polling) for more details.

### Staying informed

Monitor these resources for updates that could impact your integration:

- [Neon Roadmap](https://neon.com/docs/introduction/roadmap) for recent deliveries and upcoming features
- [Neon Changelog](https://neon.com/docs/changelog) for product updates
- [Neon Status Page](https://neonstatus.com/) for platform status
- [RSS Feeds](https://neon.com/docs/reference/feeds) for all of the above

## Advanced features

### Isolated development environments

Neon's [branching](https://neon.com/docs/introduction/branching) feature lets your users create isolated copies of their database for development and testing. Branches are copy-on-write clones that initially share data with their parent, though storage costs accumulate as changes are made to the branch.

Each user can:

- Create instant database branches for testing
- Reset branches to production state
- Delete branches when done

This is particularly valuable for platforms where users need to test schema changes or experiment with data safely. Branching is fully supported by the [Neon API](https://neon.com/docs/reference/api). For examples, see [Branching with the Neon API](https://neon.com/docs/manage/branches#branching-with-the-neon-api).

### Schema migrations

If you're managing the same schema across many user databases, consider using tools like:

- [Drizzle migrations](https://neon.com/docs/guides/drizzle-migrations)
- [Prisma migrations](https://neon.com/docs/guides/prisma-migrations)
- [Flyway](https://neon.com/docs/guides/flyway)
- [Liquibase](https://neon.com/docs/guides/liquibase)

## Integration support

We're here to help you build your integration:

- [Neon API Reference](https://neon.com/docs/reference/api): Explore all available API endpoints
- [Talk to Sales](https://neon.com/contact-sales): Discuss your integration with our team

**Info:** Integrators of Neon can contact their Neon representative directly for assistance with their integration.

--- [Document source](https://neon.com/docs/guides/encore.md) ---

> Summary: Encore.ts is a type-safe TypeScript backend framework that integrates with Neon to automatically provision and migrate a Lakebase Postgres database when you deploy a production environment from the Encore Cloud dashboard. Use this guide when you want Encore to create and manage your Neon database, including per-pull-request Neon branch preview environments for safe schema testing.

# Connect an Encore application to Neon

Set up a Neon project in seconds and connect from an Encore.ts application

Last updated: 2026-08-07

[Encore](https://encore.dev) is a backend development framework that uses static analysis and type-safe primitives to provide automatic infrastructure provisioning, distributed tracing, and API documentation. This guide shows you how to use Neon with Encore for production deployments.

## Prerequisites

- [Encore CLI](https://encore.dev/docs/install) installed
- A [Neon](https://console.neon.tech) account
- Docker Desktop running (for local development)

## Install Encore

Install the Encore CLI.

**macOS**

```bash
brew install encoredev/tap/encore
```

**Linux**

```bash
curl -L https://encore.dev/install.sh | bash
```

**Windows**

```bash
iwr https://encore.dev/install.ps1 | iex
```

## Create an Encore application

Create a new Encore application using the CLI. The `--lang ts` flag creates a TypeScript app. Without it, the CLI creates a Go app when it runs without an interactive terminal.

```bash
encore app create my-neon-app --lang ts
```

The CLI asks you to choose a template that fits your needs (for example, **URL Shortener** or **Empty app**).

Navigate to your app directory.

```bash
cd my-neon-app
```

## Define your database schema

If you started with an empty app, set up your database.

1. Create a service directory and service definition (`hello/encore.service.ts`).

   ```typescript
   import { Service } from 'encore.dev/service';

   export default new Service('hello');
   ```

2. Create a database configuration file (`hello/db.ts`).

   ```typescript
   import { SQLDatabase } from 'encore.dev/storage/sqldb';

   export const db = new SQLDatabase('hello', {
     migrations: './migrations',
   });
   ```

3. Create a migration file (`hello/migrations/1_create_table.up.sql`).

   ```sql
   CREATE TABLE messages (
     id BIGSERIAL PRIMARY KEY,
     text TEXT NOT NULL,
     created_at TIMESTAMP NOT NULL DEFAULT NOW()
   );
   ```

4. Create API endpoints (`hello/hello.ts`).

   ```typescript
   import { api } from 'encore.dev/api';
   import { db } from './db';

   interface Message {
     id: number;
     text: string;
     created_at: Date;
   }

   export const create = api(
     { expose: true, method: 'POST', path: '/messages' },
     async (req: { text: string }): Promise<Message> => {
       const row = await db.queryRow<Message>`
         INSERT INTO messages (text)
         VALUES (${req.text})
         RETURNING id, text, created_at
       `;
       if (!row) throw new Error('Failed to create message');
       return row;
     }
   );

   export const list = api(
     { expose: true, method: 'GET', path: '/messages' },
     async (): Promise<{ messages: Message[] }> => {
       const rows = await db.query<Message>`
         SELECT id, text, created_at FROM messages
         ORDER BY created_at DESC
       `;
       const messages: Message[] = [];
       for await (const row of rows) {
         messages.push(row);
       }
       return { messages };
     }
   );
   ```

## Run locally

Start your Encore application.

```bash
encore run
```

Encore automatically provisions a local PostgreSQL database for development. This database runs in Docker and isn't your Neon project. Neon comes in when you deploy to Encore Cloud later in this guide. Your API will be available at `http://localhost:4000` and the development dashboard at `http://localhost:9400`.

![Encore local development dashboard](https://neon.com/guides/images/neon-encore-dashboard.png)

Test your endpoints using the API Explorer in the dashboard, or by running this command.

```bash
curl -X POST http://localhost:4000/messages \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from Encore!"}'
```

## Deploy to staging

Push your code to deploy to Encore's staging environment.

```bash
git add -A
git commit -m "Initial commit"
git push encore
```

This creates a staging environment with an Encore-managed database.

## Configure Neon for production

To use your Neon account for production databases.

1. **Create a Neon API Key.**
   - Go to your [Neon Console](https://console.neon.tech/app/settings/api-keys).
   - Create a new API key and copy it. See [Manage API keys](https://neon.com/docs/manage/api-keys) for more information.

2. **Add the API key to Encore.**
   - Open your app in the [Encore Cloud Dashboard](https://app.encore.cloud).
   - Navigate to **Settings** → **Integrations** → **Neon**.
   - Paste your Neon API key and click **Save**.

3. **Create a production environment.**
   - In the Encore dashboard, click **Create Environment**.
   - Name it `production`.
   - For the database provider, select **Neon**.
   - Choose your preferred region.
   - Click **Create**.

## Deploy to production

Deploy your application to the production environment.

```bash
git push encore
```

Encore will do the following.

- Create a Neon database in your account
- Run your migrations automatically
- Deploy your application
- Configure all connections

You can verify the database was created by checking your [Neon Console](https://console.neon.tech); you'll see a new database created by Encore with your migrations applied.

> **Preview Environments with Neon Branching**
>
> When you connect your Encore app to GitHub and enable preview environments, Encore automatically creates a new Neon database branch for each pull request. This gives each PR its own isolated database with a copy of your production data, allowing you to test database migrations and schema changes safely before merging to production.

## Source code

You can find a complete Encore + Neon example application on GitHub:

- [Get started with Encore and Neon](https://github.com/neondatabase/examples/tree/main/with-encore): Encore.ts application with Lakebase Postgres

## Learn more

- [Encore Documentation](https://encore.dev/docs)
- [Encore SQL Databases](https://encore.dev/docs/ts/primitives/databases)
- [Encore Cloud + Neon Integration](https://encore.dev/docs/platform/infrastructure/neon)
- [Blog post: Building Production API Services with Encore and Neon](https://neon.com/blog/building-production-api-services-with-encore-typescript-and-neon-serverless-postgres)

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/entity-migrations.md) ---

> Summary: Entity Framework Core schema migrations on Lakebase Postgres walks through installing the Npgsql EF Core provider, defining C# models, and running dotnet-ef commands to create and evolve tables in a database. Use this guide when you need to connect an EF Core application to Neon and generate or apply migrations, including incremental schema changes such as adding a column. Migrations must use a direct (non-pooled) Neon connection string; PgBouncer pooled strings are not supported for dotnet-ef operations.

# Schema migration with Lakebase Postgres and Entity Framework

Set up a database on Neon and run migrations for your Entity Framework project

Last updated: 2026-10-28

[Entity Framework](https://learn.microsoft.com/en-us/ef/) is a popular Object-Relational Mapping (ORM) framework for .NET applications. It simplifies database access by allowing developers to work with domain-specific objects and properties without focusing on the underlying database tables and columns. Entity Framework also provides a powerful migration system that enables you to define and manage database schema changes over time.

This guide demonstrates how to use Entity Framework with the Lakebase Postgres database. We'll create a simple .NET application and walk through the process of setting up the database, defining models, and generating and running migrations to manage schema changes.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- A recent version of the [.NET SDK](https://dotnet.microsoft.com/en-us/download/dotnet) installed on your local machine. This guide uses .NET 8.0, which is the current Long-Term Support (LTS) version.

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select a project or click the **New Project** button to create a new one.

### Retrieve your Neon database connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. It should appear similar to the following:

```bash
postgresql://username:password@hostname/dbname?sslmode=require&channel_binding=require
```

The Postgres client library we use in this guide requires the connection string to be in the following format:

```bash
Host=hostname;Port=5432;Database=dbname;Username=username;Password=password;SSLMode=Require
```

Construct the connection string in this format using the correct values for your Neon connection URI. Keep it handy for later use.

**Note:** Neon supports both direct and pooled database connection strings, which you can find by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. A pooled connection string connects your application to the database via a PgBouncer connection pool, allowing for a higher number of concurrent connections. However, using a pooled connection string for migrations can be prone to errors. For this reason, we recommend using a direct (non-pooled) connection when performing migrations. For more information about direct and pooled connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Setting up the Entity Framework project

### Create a new .NET project

Open your terminal and run the following command to create a new .NET console application:

```bash
dotnet new console -o guide-neon-entityframework
cd guide-neon-entityframework
```

### Install dependencies

Run the following commands to install the necessary NuGet packages:

```bash
dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add Microsoft.AspNetCore.App
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add package dotenv.net
```

These packages include the Entity Framework Core libraries, the design-time components for migrations, and the Npgsql provider for PostgreSQL.

We will also need the `EF Core` tools to generate and run migrations. Install the `dotnet-ef` tool globally:

```bash
dotnet tool install --global dotnet-ef
```

### Set up the database configuration

Create a new file named `.env` in the project root directory and add the following configuration:

```bash
DATABASE_URL=NEON_POSTGRES_CONNECTION_STRING
```

Replace `NEON_POSTGRES_CONNECTION_STRING` with the **formatted** connection string you constructed earlier.

## Defining data models and running migrations

### Create the data models

Create a new file named `Models.cs` in the project directory and define the data models for your application:

```csharp
# Models.cs

using System;
using Microsoft.EntityFrameworkCore;

namespace NeonEFMigrations
{
    public class Author
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Bio { get; set; }
        public DateTime CreatedAt { get; set; }
    }

    public class Book
    {
        public int Id { get; set; }
        public string Title { get; set; }
        public int AuthorId { get; set; }
        public Author Author { get; set; }
        public DateTime CreatedAt { get; set; }
    }
}
```

This code defines two entities: `Author` and `Book`. The `Author` entity represents an author with properties for name, bio, and created timestamp. The `Book` entity represents a book with properties for title, author (as a foreign key to the `Author` entity), and created timestamp.

Also, create a new file named `ApplicationDbContext.cs` in the project directory and add the following code:

```csharp
# ApplicationDbContext.cs

using Microsoft.EntityFrameworkCore;
using GuideNeonEF.Models;
using dotenv.net;

namespace GuideNeonEF
{
    public class ApplicationDbContext : DbContext
    {
        protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
        {
            if (!optionsBuilder.IsConfigured)
            {
                DotEnv.Load();
                optionsBuilder.UseNpgsql(Environment.GetEnvironmentVariable("DATABASE_URL"));
            }
        }
        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
            modelBuilder.Entity<Author>()
                .Property(a => a.CreatedAt)
                .HasDefaultValueSql("Now()");

            modelBuilder.Entity<Book>()
                .Property(b => b.CreatedAt)
                .HasDefaultValueSql("Now()");

            modelBuilder.Seed();
        }
        public DbSet<Author> Authors { get; set; }
        public DbSet<Book> Books { get; set; }
    }
}
```

The `ApplicationDbContext` class derives from `DbContext` and represents the database context. It includes the method where we configure the database connection and seed the database at initialization. We also set default values for the `CreatedAt` properties of the `Author` and `Book` entities.

### Add seeding script

To seed the database with some initial data, create another script named `ModelBuilderExtensions.cs` in the project directory and add the following code:

```csharp
# ModelBuilderExtensions.cs

using Microsoft.EntityFrameworkCore;
using GuideNeonEF.Models;

namespace GuideNeonEF
{
    public static class ModelBuilderExtensions
    {
        public static void Seed(this ModelBuilder modelBuilder)
        {
            var authors = new[]
            {
                new Author { Id = 1, Name = "J.R.R. Tolkien", Bio = "The creator of Middle-earth and author of The Lord of the Rings.", Country = "United Kingdom"},
                new Author { Id = 2, Name = "George R.R. Martin", Bio = "The author of the epic fantasy series A Song of Ice and Fire.", Country = "United States"},
                new Author { Id = 3, Name = "J.K. Rowling", Bio = "The creator of the Harry Potter series.", Country = "United Kingdom"}
            };
            modelBuilder.Entity<Author>().HasData(authors);

            var books = new[]
            {
                new Book { Id = 1, Title = "The Fellowship of the Ring", AuthorId = 1 },
                new Book { Id = 2, Title = "The Two Towers", AuthorId = 1 },
                new Book { Id = 3, Title = "The Return of the King", AuthorId = 1 },
                new Book { Id = 4, Title = "A Game of Thrones", AuthorId = 2 },
                new Book { Id = 5, Title = "A Clash of Kings", AuthorId = 2 },
                new Book { Id = 6, Title = "Harry Potter and the Philosopher's Stone", AuthorId = 3 },
                new Book { Id = 7, Title = "Harry Potter and the Chamber of Secrets", AuthorId = 3 }
            };
            modelBuilder.Entity<Book>().HasData(books);
        }
    }
}
```

This code defines a static method `Seed` that populates the database with some initial authors and books. Entity framework will include this data when generating database migrations.

### Generate migration files

To generate migration files based on the defined models, run the following command:

```bash
dotnet ef migrations add InitialCreate
```

This command detects the new `Author` and `Book` entities and generates migration files in the `Migrations` directory to create the corresponding tables in the database.

### Apply the migration

To apply the migration and create the tables in the Lakebase Postgres database, run the following command:

```bash
dotnet ef database update
```

This command executes the migration file and creates the necessary tables in the database. It will also seed the database with the initial data defined in the `Seed` method.

## Creating the web application

### Implement the API endpoints

The project directory has a `Program.cs` file that contains the application entry point. Replace the contents of this file with the following code:

```csharp
# Program.cs

using Microsoft.EntityFrameworkCore;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using GuideNeonEF;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<ApplicationDbContext>();

var app = builder.Build();

app.UseRouting();
app.MapGet("/authors", async (ApplicationDbContext db) =>
    await db.Authors.ToListAsync());
app.MapGet("/books/{authorId}", async (int authorId, ApplicationDbContext db) =>
    await db.Books.Where(b => b.AuthorId == authorId).ToListAsync());

app.Run();
```

This code sets up a simple web application with two endpoints: `/authors` and `/books/[authorId]`. The `/authors` endpoint returns a list of all authors, while the `/books/[authorId]` endpoint returns a list of books written by the author with the specified ID.

### Test the application

To test the application, run the following command:

```bash
dotnet run
```

This will start a local web server at `http://localhost:5000`. Navigate to these endpoints in your browser to view the seeded data.

```bash
curl http://localhost:5000/authors
curl http://localhost:5000/books/1
```

## Applying schema changes

We'll see how to handle schema changes by adding a new property `Country` to the `Author` entity to store the author's country of origin.

### Update the data model

Open the `Models.cs` file and add a new property to the `Author` entity:

```csharp
# Models.cs

public class Author
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Bio { get; set; }
    public DateTime CreatedAt { get; set; }
    public string Country { get; set; }
}
```

Also, update the seed data entries for the `Author` model to include the `Country` property:

```csharp
# ModelBuilderExtensions.cs

namespace GuideNeonEF
{
    public static class ModelBuilderExtensions
    {
        public static void Seed(this ModelBuilder modelBuilder)
        {
            var authors = new[]
            {
                new Author { Id = 1, Name = "J.R.R. Tolkien", Bio = "The creator of Middle-earth and author of The Lord of the Rings.", Country = "United Kingdom" },
                new Author { Id = 2, Name = "George R.R. Martin", Bio = "The author of the epic fantasy series A Song of Ice and Fire.", Country = "United States" },
                new Author { Id = 3, Name = "J.K. Rowling", Bio = "The creator of the Harry Potter series.", Country = "United Kingdom" }
            };
            modelBuilder.Entity<Author>().HasData(authors);
            ...
        }
    }
}
```

### Generate and run the migration

To generate a new migration file for the above schema change, run the following command in the terminal:

```bash
dotnet ef migrations add AddCountryToAuthor
```

This command detects the updated `Author` entity and generates a new migration file to add the new column to the corresponding table in the database. It will also include upserting the seed data with the new property added.

Now, to apply the migration, run the following command:

```bash
dotnet ef database update
```

### Test the schema change

Run the application again:

```bash
dotnet run
```

Now, if you navigate to the `/authors` endpoint, you should see the new `Country` property included in the response.

```bash
curl http://localhost:5000/authors
```

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Migrations with Neon and Entity Framework](https://github.com/neondatabase/guide-neon-entityframework): Run Neon database migrations in an Entity Framework project

## Conclusion

In this guide, we demonstrated how to set up an Entity Framework project with Lakebase Postgres, define data models, generate migrations, and run them. Entity Framework's migration system make it easy to interact with the database and manage schema evolution over time.

## Resources

For more information on the tools and concepts used in this guide, refer to the following resources:

- [Entity Framework Core Documentation](https://learn.microsoft.com/en-us/ef/core/)
- [Neon](https://neon.com/docs)

--- [Document source](https://neon.com/docs/guides/exograph.md) ---

> Summary: Exograph is a Rust-based GraphQL backend framework that uses Postgres for data persistence, making it a natural fit for Neon. This guide walks through scaffolding an Exograph project with `exo new`, applying the schema to a Neon database using `exo schema create | psql`, and starting a local dev server with `exo dev` that exposes a GraphQL endpoint and playground.

# Use Exograph with Neon

Build GraphQL backends in minutes with Exograph and Neon

Last updated: 2026-06-05

_This guide was contributed by the Exograph team_

[Exograph](https://exograph.dev) is a new approach to building GraphQL backends. With it, you can effortlessly create flexible, secure, high-performing GraphQL backends in minutes. Powered by a Rust-based runtime, Exograph ensures fast startup times, efficient execution, and minimal memory consumption. Exograph comes equipped with a comprehensive set of tools designed to support every stage of the development lifecycle: from initial development to deployment to ongoing maintenance.

Exograph supports Postgres for data persistence, which makes it a great fit to use with Neon.

## Prerequisites

- Exograph CLI. See [Install Exograph](https://exograph.dev/docs/getting-started).
- A Neon project. See [Create a Neon project](https://neon.com/docs/manage/projects#create-a-project).

## Create a backend with Exograph

Let's create a starter project with Exograph. Run the following commands:

```bash
exo new todo
cd todo
```

You can check the code it created by examining the `src/index.exo` file (which has a definition for the `Todo` type). If you would like, you can try the [yolo](https://exograph.dev/docs/cli-reference/development/yolo) mode by trying the `exo yolo` command.

Next, let's set up the Neon database.

## Create the schema in Neon

1. Navigate to the Neon Console, select your project, and copy the connection string, which will look something like this: `postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require`.
2. Create schema in Neon using Exograph CLI:

```bash
exo schema create | psql <the connection string>
```

## Launch the backend

```bash
EXO_POSTGRES_URL=<the connection string> exo dev
```

It will print the necessary information for connecting to the backend.

```raw
Starting server in development mode...
Watching the src directory for changes...

Verifying new model...
Started server on 0.0.0.0:9876 in 717.19 ms
- Playground hosted at:
 http://0.0.0.0:9876/playground
- Endpoint hosted at:
 http://0.0.0.0:9876/graphql
```

That's it! You can now open [http://localhost:9876/playground](http://localhost:9876/playground) in your browser to see the GraphQL Playground.

You can create a todo by running the following mutation:

```graphql
mutation {
  createTodo(data: { title: "Set up Exograph with Neon", completed: true }) {
    id
  }
}
```

To get all todos, try the following query:

```graphql
query {
  todos {
    id
    title
    completed
  }
}
```

And you should see the todo you just added. Please follow Exograph's [guide to creating a simple application](https://exograph.dev/docs/getting-started#creating-a-simple-application) for more details.

## Learn more

In this guide, we have created a basic todo backend using Exograph and Neon. You can extend this further by establishing relationships between types, implementing access control rules, and integrating custom business logic. Check out Exograph's [application tutorial](https://exograph.dev/docs/application-tutorial) for more details.

To deploy Exograph in the cloud and connect it to Neon, follow the guide below (select the "External Database" tab for Neon-specific instructions in each case):

1. Deploying on [Fly.io](https://exograph.dev/docs/deployment/flyio) (these instructions can be adapted to other cloud providers)
2. Deploying on [AWS Lambda](https://exograph.dev/docs/deployment/aws-lambda)

--- [Document source](https://neon.com/docs/guides/export-neon-postgres-compatible.md) ---

> Summary: The pg_dump -Fc export from Neon produces a custom-format Postgres archive that any standard Postgres toolchain can restore with pg_restore. Use this page when migrating a Neon database to another Postgres provider or self-hosted cluster and needing a provider-agnostic dump file. The export requires an unpooled connection string; the destination must run the same or a newer Postgres major version, and role ownership mismatches can be resolved with the -O flag on pg_restore.

# Postgres-compatible export from Neon

Export your Neon database with pg_dump as a standard Postgres archive

Last updated: 2026-11-04

This topic describes how to export your **Neon** database to a **Postgres-compatible** archive using the Postgres **`pg_dump`** utility. You get a normal custom-format dump (for example `-Fc`) that any Postgres toolchain can consume.

Once you have the archive, importing it is standard Postgres tooling. The **[Restore on your destination](https://neon.com/docs/guides/export-neon-postgres-compatible#restore-on-your-destination-with-pg-restore)** section below shows a **`pg_restore`** command that pairs with the **`-Fc`** export. **You must still check your destination Postgres platform or provider.** Their docs are authoritative for SSL, networking, extensions, roles, empty-database requirements, and any managed import UI they offer.

## Export steps on Neon

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

1. In the Neon Console, open **Connect** and turn **Connection pooling** **off**. Copy the connection string.

2. Run **`pg_dump`** in **custom** format (`-Fc`) and write a dump file:

   ```bash
   pg_dump -Fc -v -d "<neon_database_connection_string>" -f <dump_file_name>
   ```

   With your Neon URL and a file name filled in, a command looks like this:

   ```bash
   pg_dump -Fc -v -d "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require" -f mydatabase.bak
   ```

   The `pg_dump` arguments above:

   - **`-Fc`**: Custom-format archive for **`pg_restore`**.
   - **`-v`**: Verbose output during the dump.
   - **`-d`**: Your Neon database [connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING).
   - **`-f`**: Output file path (for example `mydatabase.bak`).

3. Store the file where your restore environment can reach it securely.

Each **`pg_dump`** run covers **one** Neon database. If your project has multiple databases, run **`pg_dump`** again with the other connection strings (and separate dump files).

For installing `pg_dump` on your machine, see [Backups with pg_dump](https://neon.com/docs/manage/backup-pg-dump). For advanced options, ownership, and piping, see [Migrate data from Postgres with pg_dump and pg_restore](https://neon.com/docs/import/migrate-from-postgres).

## Restore on your destination with `pg_restore`

A **custom-format** dump (`-Fc`) from Neon is restored with **`pg_restore`**. Use the **same dump file** you wrote with **`pg_dump -f`** in [Export steps on Neon](https://neon.com/docs/guides/export-neon-postgres-compatible#export-steps-on-neon) (the examples below use **`mydatabase.bak`** to match the export example).

**Before you run this:** Confirm with **your destination's documentation** that **`pg_restore`** against a custom-format (**`-Fc`**) archive is supported.

- **Postgres version:** Plan for the destination server to run a Postgres **major version that matches your Neon database or is newer**. Restoring into an **older** major version than the cluster you dumped from often **fails**. If versions differ, follow your provider's compatibility guidance and test first.
- **Extensions and settings:** The destination must support the **extensions** and features your Neon database uses, or you adjust before cutover.
- **Roles:** Source and destination role names often differ. Plan for **`-O` / `--no-owner`** on **`pg_restore`** (see below) so restores do not depend on matching role OIDs.

Install **`pg_dump`** and **`pg_restore`** builds that your **Neon** Postgres version and your **destination** provider support (if the two differ, follow each side's client guidance; see [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html) in the Postgres manual).

1. Create or select a **target database** on your destination as their docs require (**empty** is typical so objects from the dump do not collide with existing schema or data).

2. Obtain a **connection string** for that database.

3. Run **`pg_restore`** against the destination, passing the dump file path last (same role as **`-f`** on **`pg_dump`**):

   ```bash
   pg_restore -v -d "<destination_database_connection_string>" <dump_file_name>
   ```

   With your destination URL and the same file name you used when exporting, a command looks like this:

   ```bash
   pg_restore -v -d "postgresql://user:password@db.example.com:5432/mydb?sslmode=require" mydatabase.bak
   ```

   The `pg_restore` arguments above:

   - **`-v`**: Verbose output while restoring.
   - **`-d`**: Target database [connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) (your provider's URL format and query parameters).
   - **`<dump_file_name>`**: The custom-format archive from **`pg_dump`** (for example **`mydatabase.bak`** from the **`pg_dump`** command in [Export steps on Neon](https://neon.com/docs/guides/export-neon-postgres-compatible#export-steps-on-neon)).

If restore fails on ownership or role statements, try adding **`-O`** and consult [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations). For more flags (parallel jobs, schema-only, exclusions), see [Advanced pg_dump and pg_restore options](https://neon.com/docs/import/migrate-from-postgres#advanced-pgdump-and-pgrestore-options).

## Related

- [Region migration](https://neon.com/docs/import/region-migration)
- [Backups with pg_dump](https://neon.com/docs/manage/backup-pg-dump)
- [Migrate data from Postgres with pg_dump and pg_restore](https://neon.com/docs/import/migrate-from-postgres)

--- [Document source](https://neon.com/docs/guides/express.md) ---

> Summary: Express and Lakebase Postgres connection guide covering Node.js driver options: `@neondatabase/serverless` for edge and serverless platforms such as Vercel and Cloudflare Workers, `pg` (node-postgres) for long-running servers, and `postgres.js` for both. Use this page when connecting an Express API to a Neon database and choosing the right driver for your deployment target, from traditional Node.js servers to serverless runtimes without TCP support. Also covers project creation, `DATABASE_URL` setup via `dotenv`, and connection pool initialization outside route handlers.

# Connect an Express application to Neon

Set up a Neon project in seconds and connect from an Express application

Last updated: 2026-10-08

Pre-built prompt for connecting ExpressJS applications to Lakebase Postgres [View prompt](https://neon.com/prompts/express-prompt.md)

This guide describes how to create a Neon project and connect to it from an Express application to query a Lakebase Postgres database.

## Choose a driver

- **`@neondatabase/serverless`** connects over HTTP or WebSockets instead of TCP. Use it for serverless and edge platforms without built-in connection pooling (Vercel, Netlify Functions, Cloudflare Workers without Hyperdrive).
- **`postgres` (postgres.js)** works in both serverless and traditional Node.js server environments.
- **`pg` (node-postgres)** is the most widely used driver for traditional, long-running Node.js servers. Also the standard choice for [Vercel Fluid compute](https://vercel.com/docs/functions/fluid-compute) and Cloudflare with [Hyperdrive](https://developers.cloudflare.com/hyperdrive/).

For a detailed comparison including all platforms, see [Choosing your connection method](https://neon.com/docs/connect/choose-connection).

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create an Express project and add dependencies

1. Create an Express project and change to the newly created directory.

   ```shell
   mkdir neon-express-example
   cd neon-express-example
   npm init -y
   npm install express
   ```

2. Add project dependencies using one of the following commands:

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless dotenv
   ```

   **node-postgres**

   ```shell
   npm install pg dotenv
   ```

   **postgres.js**

   ```shell
   npm install postgres dotenv
   ```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection details to it. Find your database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select Node.js from the **Connection string** dropdown. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

**Important:** Never hardcode credentials in source code files. Always use environment variables via `process.env`. For more information, see [Security overview](https://neon.com/docs/security/security-overview).

## Configure the Postgres client

Add an `index.js` file to your project directory and add the following code snippet to connect to your Neon database:

**Neon serverless driver**

```javascript
require('dotenv').config();

const express = require('express');
const { neon } = require('@neondatabase/serverless');

const app = express();
const PORT = process.env.PORT || 4242;

const sql = neon(process.env.DATABASE_URL);

app.get('/', async (req, res) => {
  try {
    const [result] = await sql`SELECT version()`;
    const version = result?.version || 'No version found';
    res.json({ version });
  } catch (error) {
    console.error('Database query failed:', error);
    res.status(500).json({ error: 'Failed to connect to the database.' });
  }
});

app.listen(PORT, () => {
  console.log(`Listening to http://localhost:${PORT}`);
});
```

**node-postgres**

```javascript
require('dotenv').config();

const express = require('express');
const { Pool } = require('pg');

const app = express();
const PORT = process.env.PORT || 4242;

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

app.get('/', async (req, res) => {
  let client;
  try {
    client = await pool.connect();
    const { rows } = await client.query('SELECT version()');
    const version = rows[0]?.version || 'No version found';
    res.json({ version });
  } catch (error) {
    console.error('Database query failed:', error);
    res.status(500).json({ error: 'Failed to connect to the database.' });
  } finally {
    client?.release();
  }
});

app.listen(PORT, () => {
  console.log(`Listening to http://localhost:${PORT}`);
});
```

**postgres.js**

```javascript
require('dotenv').config();

const express = require('express');
// postgres.js 4 and later is ESM-only; .default returns the postgres function
const postgres = require('postgres').default;

const app = express();
const PORT = process.env.PORT || 4242;

const sql = postgres(process.env.DATABASE_URL);

app.get('/', async (req, res) => {
  try {
    const [result] = await sql`SELECT version()`;
    const version = result?.version || 'No version found';
    res.json({ version });
  } catch (error) {
    console.error('Database query failed:', error);
    res.status(500).json({ error: 'Failed to connect to the database.' });
  }
});

app.listen(PORT, () => {
  console.log(`Listening to http://localhost:${PORT}`);
});
```

**Note:** If you use node-postgres, note that `pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. To keep the current behavior and remove the warning, change `sslmode=require` to `sslmode=verify-full` in your connection string. For SSL mode definitions, see [SSL support](https://www.postgresql.org/docs/current/libpq-ssl.html) in the Postgres documentation.

## Run index.js

Run `node index.js` and open [localhost:4242](http://localhost:4242). The response looks like this:

```json
{ "version": "PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit" }
```

## Connection issues

- If you see an `endpoint ID is not specified` error, the TLS client your Postgres driver depends on doesn't support Server Name Indication (SNI), which Neon uses to route connections. For `pg` (node-postgres), this means an outdated `libpq`-compatible TLS stack; upgrading `pg` usually resolves it.
- If you encounter an `SSL SYSCALL error: EOF detected` (or a similar connection-reset error), this typically happens when an application tries to reuse a connection after the Neon compute has been suspended due to inactivity. This mainly affects long-running servers that keep a connection pool open, like the `pg` example above. Closing and recreating idle connections, or reconnecting on error, resolves it.

<details>

<summary>**Notes for AI-assisted setup**</summary>

- Do not hardcode credentials or connection strings in any `.js` source file. Always use environment variables via `process.env` and `dotenv`.
- Wrap all database queries in a `try...catch` block. Return a `500` status with an error message on failure.
- When using `pg` (node-postgres), declare `let client` before the `try` block and call `client?.release()` in the `finally` block. This safely handles cases where `pool.connect()` itself fails.
- Initialize the connection pool or client outside the route handler, not inside it. Creating a new pool on every request wastes resources.
- Choose the right driver for your platform. `@neondatabase/serverless` is for serverless/edge platforms without TCP support. For long-running Express servers, use `pg` or `postgres`. See [Choosing your connection method](https://neon.com/docs/connect/choose-connection).

</details>

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/guides/queries): Build realtime apps with end-to-end reactivity

--- [Document source](https://neon.com/docs/guides/file-storage.md) ---

> Summary: File storage in Neon uses a split-storage pattern where files go to an external object storage or file management service and file URLs, keys, and metadata are stored in a Lakebase Postgres database. Supported providers include AWS S3, Cloudflare R2, Azure Blob, Backblaze B2, Cloudinary, ImageKit, and Uploadcare. Choose this approach when your app needs file uploads and you want a relational store for querying and filtering metadata without building a native file store.

# File storage

Store files in external object storage and file management services and track metadata in Lakebase

Last updated: 2026-09-16

Applications often need to handle file uploads and storage, from user avatars and documents to images and other media.

**Neon now offers native storage:**

Neon Object Storage is S3-compatible object storage built into the Neon backend. Object storage branches with your database: each branch gets its own isolated namespace, so you can test file uploads in preview branches without touching production. No separate cloud account needed. Use any S3-compatible SDK with your existing Neon credential.

For more information, see [Neon Object Storage](https://neon.com/docs/storage/overview).

If you prefer an external provider or need features like image optimization, transformations, or CDN delivery, you can combine Neon with a specialized storage service instead. The typical pattern looks like this:

1. Upload files from your application (client or backend) to an object storage provider or file management service.
2. Store references (such as the file URL, unique key, or identifier) and related metadata like user ID, upload timestamp, file type, size, and permissions in your database.

This pattern separates file storage from relational data management, with purpose-built services like S3 or R2 handling file storage and the database managing your data.

## Options for external storage

You can integrate Neon with a variety of storage solutions:

- S3-compatible object storage: Services like [AWS S3](https://aws.amazon.com/pm/serv-s3/), [Cloudflare R2](https://www.cloudflare.com/en-in/developer-platform/products/r2/), and [Backblaze B2](https://www.backblaze.com/cloud-storage) offer file storage via the widely-adopted S3 API.
- File and media management SaaS platforms: Services like [ImageKit](https://imagekit.io/), [Cloudinary](https://cloudinary.com/), [Uploadcare](https://uploadcare.com/) or [Filestack](https://www.filestack.com/) provide higher-level abstractions, often including additional features like image optimization, transformations, and SDKs, while managing the underlying storage infrastructure for you.

* [AWS S3](https://neon.com/docs/guides/aws-s3): Upload files to AWS S3 and store metadata in Neon
* [Azure Blob Storage](https://neon.com/docs/guides/azure-blob-storage): Upload files to Azure Blob Storage and store metadata in Neon
* [Backblaze B2](https://neon.com/docs/guides/backblaze-b2): Upload files to Backblaze B2 and store metadata in Neon
* [Cloudflare R2](https://neon.com/docs/guides/cloudflare-r2): Upload files to Cloudflare R2 and store metadata in Neon
* [Cloudinary](https://neon.com/docs/guides/cloudinary): Upload files to Cloudinary and store metadata in Neon
* [ImageKit](https://neon.com/docs/guides/imagekit): Upload files to ImageKit and store metadata in Neon
* [Uploadcare](https://neon.com/docs/guides/uploadcare): Upload files to Uploadcare and store metadata in Neon

--- [Document source](https://neon.com/docs/guides/flyway-multiple-environments.md) ---

> Summary: Flyway multi-environment schema management with Neon maps each environment (development, staging, production) to a separate Neon branch, giving each an isolated Postgres instance and its own JDBC connection string. A per-environment Flyway config file controls which database receives each `flyway migrate -configFiles=` run, keeping schemas consistent across the pipeline. Use this guide when automating releases across a chain of environments and want to integrate Neon branch creation with Flyway migration ordering.

# Manage multiple database environments

Learn how to manage schemas for multiple database environments with Flyway

Last updated: 2026-10-09

With Flyway, you can manage and track changes to your database schema, ensuring that the database evolves consistently across different environments.

When automating releases, there are often multiple environments or a chain of environments that you must deliver changes to in a particular order. Such environments might include _development_, _staging_, and _production_.

In this guide, we'll show you how to use Neon's branching feature to spin up a branch for each environment and how to configure Flyway to manage schema changes across those environments.

## Prerequisites

- A flyway installation. See [Get started with Flyway and Neon](https://neon.com/docs/guides/flyway) for installation instructions.
- A Neon account and project. See [Sign up](https://neon.com/docs/get-started/signing-up).
- A database. This guide uses the ready-to-use `neondb` database on the `production` branch of your Neon project. You can create your own database if you like. See [Create a database](https://neon.com/docs/manage/databases#create-a-database) for instructions.

## Add a table to your database

Set up a database to work with by adding a table to your `neondb` database on the `production` branch of your Neon project. If you completed [Get started with Flyway and Neon](https://neon.com/docs/guides/flyway), you might already have this `person` table created. We'll consider this your _production_ environment database.

If you still need to create the `person` table, open the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), and run the following statement:

```bash
create table person (
    ID int not null,
    NAME varchar(100) not null
);
```

## Create databases for development and staging

Using Neon's branching feature, create your _development_ and _staging_ databases. When you create a branch in Neon, you are creating a copy-on-write clone of the parent branch that incudes all databases and roles that exist on the parent, and each branch is an isolated Postgres instance with its own compute resources.

Perform these steps twice, once for your _development_ branch and once for your _staging_ branch.

**Console**

1. In the Neon Console, select your project.
2. Select **Branches** in the sidebar.
3. Click **New Branch** to open the branch creation dialog.
4. Enter a name for the branch. For example, name the branch for the environment (_development_ or _staging_).
5. Select a parent branch. This should be the branch where you created the `person` table.
6. Leave the other default settings and click **Create Branch**.

**CLI**

```bash showLineNumbers
neon branches create --name development
```

**API**

```bash showLineNumbers
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/{project_id}/branches \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API" \
     --header 'Content-Type: application/json' \
     --data '
{
  "branch": {
    "name": "development"
  },
  "endpoints": [
    {
      "type": "read_only"
    }
  ]
}
' | jq
```

When you are finished, you should have a _development_ branch and a _staging_ branch.

## Retrieve your Neon database connection strings

In the Neon Console, click **Connect** to retrieve the connection string for each branch (`production`, `development`, and `staging`) from the **Connect to your branch** modal. Use the **Branch** drop-down menu to select each branch before copying the connection string.

Your connection strings should look something like the ones shown below. Note that the hostname differs for each (the part starting with `ep-` and ending with `aws.neon.tech`). That's because each branch is hosted on its own compute.

- **main**

  ```bash
  jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?user=alex&password=AbC123dEf
  ```

- **development**

  ```bash
  jdbc:postgresql://ep-mute-night-47642501.us-east-2.aws.neon.tech/neondb?user=alex&password=AbC123dEf
  ```

- **staging**

  ```bash
  jdbc:postgresql://ep-shrill-shape-27763949.us-east-2.aws.neon.tech/neondb?user=alex&password=AbC123dEf
  ```

**Important:** Use direct (non-pooled) connection strings with Flyway. Neon's pooled connection uses PgBouncer in transaction mode, which doesn't support all session-level operations that schema migration tools rely on, so running migrations over a pooled connection can lead to errors. Make sure none of the hostnames include the `-pooler` suffix (turn the **Connection pooling** toggle off in the **Connect** modal). See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Configure flyway to connect each environment

To enable Flyway to connect to multiple environments, we'll create a configuration file for each environment and add the environment-specific connection details. When running Flyway, you'll specify the configuration file to be used.

**Note:** By default, Flyway loads its configuration from the default `conf/flyway.conf` file. This is true even if you specify another configuration file when running Flyway. You can take advantage of this behavior by defining non-environment specific configuration settings in the default `conf/flyway.conf` file, and placing your environment-specific settings in separate configuration files, as we'll do here.

1. Switch to your Flyway `/conf` directory and create the following configuration files, one for each environment, by copying the default configuration file. For example:

   ```bash
   cd ~/flyway-x.y.z/conf
   cp flyway.conf env_dev.conf
   cp flyway.conf env_staging.conf
   cp flyway.conf env_prod.conf
   ```

2. In each configuration file, update the following items with the correct connection details for that database environment. The `url` setting will differ for each environment (in `env_prod.conf`, the `url` will point to `production`). In this example, where you are the only user, the `user` and `password` settings should be the same for each of your three database environments.

   ```bash
   flyway.url=jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech:5432/neondb

   flyway.user=alex

   flyway.password=AbC123dEf

   flyway.locations=filesystem:/home/alex/flyway-x.y.z/sql

   flyway.baselineOnMigrate=true
   ```

   - The `flyway.locations` setting tells Flyway where to look for your migration files. We'll create them in the `/sql` directory in a later step.
   - The `flyway.baselineOnMigrate=true` setting tells Flyway to perform a baseline action when you run the `migrate` command on a non-empty schema with no Flyway schema history table. The schema will then be initialized with the `baselineVersion` before executing migrations. Only migrations above the `baselineVersion` will then be applied. This is useful for initial Flyway deployments on projects with an existing database. You can disable this setting by commenting it out again or setting it to false after applying your first migration on the database.

## Create a migration

Create a migration file called `V2__Add_people.sql`, add it to your Flyway `/sql` directory, and add the following statements to the file:

```bash
insert into person (ID, NAME) values (1, 'Alex');
insert into person (ID, NAME) values (2, 'Mr. Lopez');
insert into person (ID, NAME) values (3, 'Ms. Smith');
```

### Run the migration on each environment

Run the migration on each environment in order by specifying the environment's configuration file in the `flyway migrate` command. You'll start with your `development` environment, then `staging`, and then finally, `production`.

**Development**

```bash showLineNumbers
flyway migrate -configFiles="conf/env_dev.conf"
```

**Staging**

```bash showLineNumbers
flyway migrate -configFiles="conf/env_staging.conf"
```

**Production**

```bash showLineNumbers
flyway migrate -configFiles="conf/env_prod.conf"
```

A successful migration command returns output similar to the following:

```bash
Database: jdbc:postgresql://ep-nameless-unit-49929920.us-east-2.aws.neon.tech/neondb (PostgreSQL 15.4)
Schema history table "public"."flyway_schema_history" does not exist yet
Successfully validated 1 migration (execution time 00:00.199s)
Creating Schema History table "public"."flyway_schema_history" with baseline ...
Successfully baselined schema with version: 1
Current version of schema "public": 1
Migrating schema "public" to version "2 - Add people"
Successfully applied 1 migration to schema "public", now at version v2 (execution time 00:00.410s)
A Flyway report has been generated here: /home/alex/flyway-x.y.z/report.html
```

After you run the migration commands, your database should be consistent across all three environments. You can verify that the data was added to each database by viewing the branch and table on the **Tables** page in the Neon Console. Select **Postgres database** > **Tables** from the sidebar and select your database.

## Conclusion

You've seen how you can instantly create new database environment with Neon's branching feature and how to keep schemas consistent across different environments using Flyway. The steps in this guide were performed manually from the command line but could be easily integrated into your release management pipeline. Neon provides a [CLI](https://neon.com/docs/cli) and [API](https://neon.com/docs/reference/api) for automating various tasks in Neon, such as branch creation, which you can also integrate into your release automation.

## References

- [Flyway documentation](https://documentation.red-gate.com/fd/flyway-documentation-138346877.html)
- [Flyway command-line tool](https://documentation.red-gate.com/fd/command-line-184127404.html)
- [Flyway command-line quickstart](https://documentation.red-gate.com/fd/quickstart-command-line-184127576.html)
- [A simple way to manage multi-environment deployments](https://flywaydb.org/blog/a-simple-way-to-manage-multi-environment-deployments)

--- [Document source](https://neon.com/docs/guides/flyway.md) ---

> Summary: Flyway database migration tool connects to a Lakebase Postgres database via a JDBC connection string, letting developers apply versioned SQL scripts and track schema history in a flyway_schema_history table. Use this page to install the Flyway CLI, write a flyway.conf file with Neon credentials, and run your first migrations against a Neon project. For applying the same migration workflow across multiple Neon branches or environments, see the companion guide on multiple database environments.

# Get started with Flyway and Neon

Learn how to manage schema changes in Neon with Flyway

Last updated: 2026-09-16

Flyway is a database migration tool that provides version control for databases. It allows developers to manage and track changes to the database schema, ensuring that the database evolves consistently across different environments.

This guide steps you through installing the Flyway command-line tool, configuring Flyway to connect to a Neon database, and running database migrations. The guide follows the setup described in the [Flyway command-line quickstart](https://documentation.red-gate.com/fd/quickstart-command-line-184127576.html).

## Prerequisites

- A Neon account. See [Sign up](https://neon.com/docs/get-started/signing-up).
- A Neon project. See [Create your first project](https://neon.com/docs/get-started/signing-up).
- A database. This guide uses the ready-to-use `neondb` database. You can create your own database if you like. See [Create a database](https://neon.com/docs/manage/databases#create-a-database) for instructions.

## Download and extract Flyway

1. Download the latest version of the [Flyway command-line tool](https://documentation.red-gate.com/fd/command-line-277579359.html).

2. Extract the Flyway files. For example:

   ```bash
   cd ~/Downloads
   tar -xzvf flyway-commandline-x.y.z-linux-x64.tar.gz -C ~/
   ```

3. Open a command prompt to view the contents of your Flyway installation:

   ```bash
   cd ~/flyway-x.y.z
   ls
   assets  drivers  flyway.cmd  jre  licenses    rules
   conf    flyway   jars        lib  README.txt  sql
   ```

## Set your path variable

Add the Flyway directory to your `PATH` so that you can execute Flyway commands from any location.

**bash**

```bash
echo 'export PATH=$PATH:~/flyway-x.y.z' >> ~/.bashrc
source ~/.bashrc
```

**zsh**

```zsh
echo 'export PATH=$PATH:~/flyway-x.y.x' >> ~/.zshrc
source ~/.zshrc
```

## Retrieve your Neon database connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select the **Java** option from the **Connection string** drop-down menu.

Your Java connection string should look something like this:

```bash
jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?user=alex&password=AbC123dEf
```

**Important:** Use a direct (non-pooled) connection string with Flyway. Neon's pooled connection uses PgBouncer in transaction mode, which doesn't support all session-level operations that schema migration tools rely on, so running migrations over a pooled connection can lead to errors. Make sure the hostname does not include the `-pooler` suffix (turn the **Connection pooling** toggle off in the **Connect** modal). See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Configure flyway

To configure Flyway to connect to your Neon database, create a `flyway.conf` file in the /conf directory. Include the following items, modified to use the connection details you retrieved in the previous step.

```bash
flyway.url=jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech:5432/neondb

flyway.user=alex

flyway.password=AbC123dEf

flyway.locations=filesystem:/home/alex/flyway-x.y.z/sql
```

## Create the first migration

Create an `sql` directory to hold your first migration file. We'll name the file `V1__Create_person_table.sql` and include the following command, which creates a person table in your database.

```bash
create table person (
    ID int not null,
    NAME varchar(100) not null
);
```

## Migrate the database

Run the `flyway migrate` command to migrate your database:

```bash
flyway migrate
```

If the command was successful, you'll see output similar to the following:

```bash
Database: jdbc:sqlite:FlywayQuickStartCLI.db (SQLite 3.41)
Successfully validated 1 migration (execution time 00:00.008s)
Creating Schema History table: "PUBLIC"."flyway_schema_history"
Current version of schema "PUBLIC": << Empty Schema >>
Migrating schema "PUBLIC" to version 1 - Create person table
Successfully applied 1 migration to schema "PUBLIC" (execution time 00:00.033s)
```

To verify that the `person` table was created, you can view it on the **Tables** page in the Neon Console. Select **Postgres database** > **Tables** from the sidebar and select your database.

## Add a second migration

Run another migration to add data to the table. Add a second migration file to the `/sql` directory called `V2__Add_people.sql` and add the following statements:

```bash
insert into person (ID, NAME) values (1, 'Alex');
insert into person (ID, NAME) values (2, 'Mr. Lopez');
insert into person (ID, NAME) values (3, 'Ms. Smith');
```

Run the migration:

```bash
flyway migrate
```

If the command was successful, you'll see output similar to the following:

```bash
Database: jdbc:postgresql://ep-red-credit-85617375.us-east-2.aws.neon.tech/neondb (PostgreSQL 15.4)
Successfully validated 2 migrations (execution time 00:00.225s)
Current version of schema "public": 1
Migrating schema "public" to version "2 - Add people"
Successfully applied 1 migration to schema "public", now at version v2 (execution time 00:00.388s)
A Flyway report has been generated here: /home/alex/flyway-x.y.z/sql/report.html
```

You can verify that the data was added by viewing the table on the **Tables** page in the Neon Console. Select **Postgres database** > **Tables** from the sidebar and select your database.

## View your schema migration history

When you run the `flyway migrate` command, Flyway registers the schema changes in the `flyway_schema_history` table, which Flyway automatically creates in your database. You can view the table by running the [flyway info](https://documentation.red-gate.com/fd/info-277578881.html) command.

```bash
flyway info
Database: jdbc:postgresql://ep-red-credit-85617375.us-east-2.aws.neon.tech/neondb (PostgreSQL 15.4)
Schema version: 2
+-----------+---------+---------------------+------+---------------------+---------+----------+
| Category  | Version | Description         | Type | Installed On        | State   | Undoable |
+-----------+---------+---------------------+------+---------------------+---------+----------+
| Versioned | 1       | Create person table | SQL  | 2023-10-22 19:00:39 | Success | No       |
| Versioned | 2       | Add people          | SQL  | 2023-10-22 19:04:42 | Success | No       |
+-----------+---------+---------------------+------+---------------------+---------+----------+
A Flyway report has been generated here: /home/alex/flyway-x.y.z/sql/report.html
```

You can also view the table on the **Tables** page in the Neon Console. Select **Postgres database** > **Tables** from the sidebar and select your database.

## Next steps

Learn how you can use Flyway with multiple database environments. See [Use Flyway with multiple database environments](https://neon.com/docs/guides/flyway-multiple-environments).

## References

- [Flyway documentation](https://documentation.red-gate.com/fd/flyway-documentation-138346877.html)
- [Flyway command-line tool](https://documentation.red-gate.com/fd/command-line-184127404.html)
- [Flyway command-line quickstart](https://documentation.red-gate.com/fd/quickstart-command-line-184127576.html)

--- [Document source](https://neon.com/docs/guides/go.md) ---

> Summary: Connecting a Go application to Lakebase Postgres with pgx/v5 requires Go 1.25 or later and a DATABASE_URL connection string passed via environment variable. Use this page for raw SQL access with parameterized queries, not an ORM: it walks through CREATE, SELECT, UPDATE, DELETE, bulk inserts via CopyFrom, and multi-statement transactions with conn.Begin and defer tx.Rollback.

# Connect a Go application to Lakebase Postgres

Learn how to run SQL queries in Neon from Go using the pgx library

Last updated: 2026-10-09

Pre-built prompt for connecting Go applications to Neon [View prompt](https://neon.com/prompts/golang-prompt.md)

This guide describes how to create a Neon project and connect to it from a Go (Golang) application using [pgx](https://github.com/jackc/pgx), a Postgres driver for Go.

You'll learn how to connect to your database from a Go application, and perform basic Create, Read, Update, and Delete (CRUD) operations.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://console.neon.tech/signup).
- Go 1.25 or later. If you do not have Go installed, see the [official installation guide](https://go.dev/doc/install).

**Note:** `pgx/v5` v5.9.0 and later require Go 1.25. If you can't upgrade Go, pin a release that supports Go 1.21: `go get github.com/jackc/pgx/v5@v5.7.4`.

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Your project is created with a ready-to-use database named `neondb`. In the following steps, you will connect to this database from your Go application.

## Create a Go project

For your Go project, create a project directory, initialize a Go module, and add the required libraries.

1. Create a project directory and change into it.

   ```bash
   mkdir neon-go-quickstart
   cd neon-go-quickstart
   ```

   > Open the directory in your preferred code editor (for example, VS Code, GoLand).

2. Initialize a Go module. This command creates a `go.mod` file to track your project's dependencies.

   ```bash
   go mod init neon-go-quickstart
   ```

3. Add the required Go packages using `go get`.

   - `pgx/v5`: The database driver for connecting to Postgres.
   - `godotenv`: A helper library to manage environment variables from a `.env` file.

   ```bash
   go get github.com/jackc/pgx/v5 github.com/joho/godotenv
   ```

   This will download the packages and add them to your `go.mod` and `go.sum` files.

## Store your Neon connection string

Create a file named `.env` in your project's root directory. This file stores your database connection string. Don't commit it to source control.

1. In the [Neon Console](https://console.neon.tech), open your project.
2. Click **Connect** in the Console nav to open the **Connect to your branch** modal.
   ![Connection modal](https://neon.com/docs/connect/connect_to_branch_modal.png)
3. Copy the connection string, which includes your password.
4. Add the connection string to your `.env` file as shown below.
   ```text
   DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
   ```
   > Replace `[user]`, `[password]`, `[neon_hostname]`, and `[dbname]` with your actual database credentials.

## Examples

This section provides example Go scripts that demonstrate how to connect to your Neon database and perform basic operations such as [creating a table](https://neon.com/docs/guides/go#create-a-table-and-insert-data), [reading data](https://neon.com/docs/guides/go#read-data), [updating data](https://neon.com/docs/guides/go#update-data), and [deleting data](https://neon.com/docs/guides/go#delete-data).

Each script is a standalone program with its own `main` function, so run each one by file name with `go run <file>.go`. Because they share a directory, `go build .` and your editor report `main redeclared`. That's expected for this guide. In a real app, put each program in its own directory under `cmd/`.

### Create a table and insert data

In your project directory, create a file named `create_table.go`. This script connects to your Neon database, creates a table named `books`, and inserts some sample data into it.

```go filename="create_table.go"
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5"
	"github.com/joho/godotenv"
)

func main() {
	// Load environment variables from .env file
	err := godotenv.Load()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error loading .env file: %v\n", err)
		os.Exit(1)
	}

	// Get the connection string from the environment variable
	connString := os.Getenv("DATABASE_URL")
	if connString == "" {
		fmt.Fprintf(os.Stderr, "DATABASE_URL not set\n")
		os.Exit(1)
	}

	ctx := context.Background()

	// Connect to the database
	conn, err := pgx.Connect(ctx, connString)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
		os.Exit(1)
	}
	defer conn.Close(ctx)

	fmt.Println("Connection established")

	// Drop the table if it already exists
	_, err = conn.Exec(ctx, "DROP TABLE IF EXISTS books;")
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to drop table: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("Finished dropping table (if it existed).")

	// Create a new table
	_, err = conn.Exec(ctx, `
        CREATE TABLE books (
            id SERIAL PRIMARY KEY,
            title VARCHAR(255) NOT NULL,
            author VARCHAR(255),
            publication_year INT,
            in_stock BOOLEAN DEFAULT TRUE
        );
    `)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to create table: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("Finished creating table.")

	// Insert a single book record
	_, err = conn.Exec(ctx,
		"INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4);",
		"The Catcher in the Rye", "J.D. Salinger", 1951, true,
	)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to insert single row: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("Inserted a single book.")

	// Data to be inserted
	booksToInsert := [][]interface{}{
		{"The Hobbit", "J.R.R. Tolkien", 1937, true},
		{"1984", "George Orwell", 1949, true},
		{"Dune", "Frank Herbert", 1965, false},
	}

	// Use CopyFrom for efficient bulk insertion
	copyCount, err := conn.CopyFrom(
		ctx,
		pgx.Identifier{"books"},
		[]string{"title", "author", "publication_year", "in_stock"},
		pgx.CopyFromRows(booksToInsert),
	)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to copy rows: %v\n", err)
		os.Exit(1)
	}
	fmt.Printf("Inserted %d rows of data.\n", copyCount)
}
```

The above code does the following:

- Loads the connection string from the `.env` file using the `godotenv` library.
- Connects to the Neon database using `pgx.Connect`. The `defer conn.Close(ctx)` statement ensures the connection is closed when the `main` function exits.
- Uses `conn.Exec` to run SQL commands that don't return rows, such as `DROP TABLE` and `CREATE TABLE`.
- Inserts a single row using `conn.Exec` with parameterized query placeholders (`$1`, `$2`, etc.) to prevent SQL injection.
- Uses `conn.CopyFrom` for efficient bulk insertion of multiple records.

Run the script using the following command:

```bash
go run create_table.go
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established
Finished dropping table (if it existed).
Finished creating table.
Inserted a single book.
Inserted 3 rows of data.
```

### Read data

In your project directory, create a file named `read_data.go`. This script connects to your Neon database and retrieves all rows from the `books` table.

```go filename="read_data.go"
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error loading .env file: %v\n", err)
		os.Exit(1)
	}

	connString := os.Getenv("DATABASE_URL")
	if connString == "" {
		fmt.Fprintf(os.Stderr, "DATABASE_URL not set\n")
		os.Exit(1)
	}

	ctx := context.Background()
	conn, err := pgx.Connect(ctx, connString)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
		os.Exit(1)
	}
	defer conn.Close(ctx)
	fmt.Println("Connection established")

	// Fetch all rows from the books table
	rows, err := conn.Query(ctx, "SELECT * FROM books ORDER BY publication_year;")
	if err != nil {
		fmt.Fprintf(os.Stderr, "Query failed: %v\n", err)
		os.Exit(1)
	}
	defer rows.Close()

	fmt.Println("\n--- Book Library ---")
	for rows.Next() {
		var id, publicationYear int
		var title, author string
		var inStock bool

		err := rows.Scan(&id, &title, &author, &publicationYear, &inStock)
		if err != nil {
			fmt.Fprintf(os.Stderr, "Failed to scan row: %v\n", err)
			os.Exit(1)
		}
		fmt.Printf("ID: %d, Title: %s, Author: %s, Year: %d, In Stock: %t\n",
			id, title, author, publicationYear, inStock)
	}
	fmt.Println("--------------------")

	if err := rows.Err(); err != nil {
		fmt.Fprintf(os.Stderr, "Error during rows iteration: %v\n", err)
		os.Exit(1)
	}
}
```

The above code does the following:

- Connects to the database using the connection string from the `.env` file.
- Uses `conn.Query` to execute a `SELECT` statement, which returns a `pgx.Rows` object.
- Iterates through the rows using `rows.Next()`.
- Uses `rows.Scan()` to copy the column values from the current row into Go variables.
- Prints each book's details in a formatted output.
- Checks for any errors that occurred during row iteration with `rows.Err()`.

Run the script using the following command:

```bash
go run read_data.go
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: false
--------------------
```

### Update data

In your project directory, create a file named `update_data.go`. This script connects to your Neon database and updates the stock status of the book 'Dune' to `true`.

```go filename="update_data.go"
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error loading .env file: %v\n", err)
		os.Exit(1)
	}

	connString := os.Getenv("DATABASE_URL")
	if connString == "" {
		fmt.Fprintf(os.Stderr, "DATABASE_URL not set\n")
		os.Exit(1)
	}

	ctx := context.Background()
	conn, err := pgx.Connect(ctx, connString)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
		os.Exit(1)
	}
	defer conn.Close(ctx)
	fmt.Println("Connection established")

	// Update a data row in the table
	_, err = conn.Exec(ctx, "UPDATE books SET in_stock = $1 WHERE title = $2;", true, "Dune")
	if err != nil {
		fmt.Fprintf(os.Stderr, "Update failed: %v\n", err)
		os.Exit(1)
	}

	fmt.Println("Updated stock status for 'Dune'.")
}
```

The above code uses `conn.Exec` with a parameterized `UPDATE` statement to change the `in_stock` status of the book 'Dune'.

Run the script using the following command:

```bash
go run update_data.go
```

After running this script, you can run `read_data.go` again to verify that the row was updated.

```bash
go run read_data.go
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the stock status for 'Dune' has been updated to `true`.

### Delete data

In your project directory, create a file named `delete_data.go`. This script connects to your Neon database and deletes the book '1984' from the `books` table.

```go filename="delete_data.go"
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error loading .env file: %v\n", err)
		os.Exit(1)
	}

	connString := os.Getenv("DATABASE_URL")
	if connString == "" {
		fmt.Fprintf(os.Stderr, "DATABASE_URL not set\n")
		os.Exit(1)
	}

	ctx := context.Background()
	conn, err := pgx.Connect(ctx, connString)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
		os.Exit(1)
	}
	defer conn.Close(ctx)
	fmt.Println("Connection established")

	// Delete a data row from the table
	_, err = conn.Exec(ctx, "DELETE FROM books WHERE title = $1;", "1984")
	if err != nil {
		fmt.Fprintf(os.Stderr, "Delete failed: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("Deleted the book '1984' from the table.")
}
```

The above code uses `conn.Exec` with a parameterized `DELETE` statement to remove the book '1984' from the `books` table.

Run the script using the following command:

```bash
go run delete_data.go
```

After running this script, you can run `read_data.go` again to verify that the row was deleted.

```bash
go run read_data.go
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the book '1984' has been successfully deleted from the `books` table.

### Using transactions

The examples above execute each operation independently. For production code where multiple operations must succeed or fail together, wrap them in a transaction. The `defer tx.Rollback(ctx)` pattern ensures the transaction is rolled back if the function exits before committing.

```go filename="transaction_example.go"
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/jackc/pgx/v5"
	"github.com/joho/godotenv"
)

func main() {
	err := godotenv.Load()
	if err != nil {
		fmt.Fprintf(os.Stderr, "Error loading .env file: %v\n", err)
		os.Exit(1)
	}

	connString := os.Getenv("DATABASE_URL")
	if connString == "" {
		fmt.Fprintf(os.Stderr, "DATABASE_URL not set\n")
		os.Exit(1)
	}

	ctx := context.Background()
	conn, err := pgx.Connect(ctx, connString)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Unable to connect to database: %v\n", err)
		os.Exit(1)
	}
	defer conn.Close(ctx)

	// Begin a transaction
	tx, err := conn.Begin(ctx)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Failed to begin transaction: %v\n", err)
		os.Exit(1)
	}
	// Defer a rollback in case anything fails. If the transaction
	// is committed successfully, the rollback is a no-op.
	defer tx.Rollback(ctx)

	// All operations use the tx object, not conn
	_, err = tx.Exec(ctx, "INSERT INTO books (title, author, publication_year) VALUES ($1, $2, $3)", "Brave New World", "Aldous Huxley", 1932)
	if err != nil {
		fmt.Fprintf(os.Stderr, "Insert failed: %v\n", err)
		os.Exit(1)
	}

	_, err = tx.Exec(ctx, "UPDATE books SET in_stock = $1 WHERE title = $2", false, "Brave New World")
	if err != nil {
		fmt.Fprintf(os.Stderr, "Update failed: %v\n", err)
		os.Exit(1)
	}

	// Commit the transaction
	if err := tx.Commit(ctx); err != nil {
		fmt.Fprintf(os.Stderr, "Commit failed: %v\n", err)
		os.Exit(1)
	}

	fmt.Println("Transaction committed successfully.")
}
```

Run with:

```bash
go run transaction_example.go
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Transaction committed successfully.
```

Run `read_data.go` again to see the new row: `Brave New World` by Aldous Huxley, with `In Stock: false`.

## Connection issues

- If you see an `endpoint ID is not specified` error, the TLS client your Postgres driver depends on doesn't support Server Name Indication (SNI), which Neon uses to route connections. This is uncommon with `pgx/v5`, which uses Go's standard `crypto/tls` package and supports SNI by default, but can occur with an older driver or an outdated TLS implementation.
- If you encounter an `SSL SYSCALL error: EOF detected` (or a similar connection-reset error), this typically happens when an application tries to reuse a connection after the Neon compute has been suspended due to inactivity. The examples in this guide open a fresh connection with `pgx.Connect` each time they run, so this mainly affects long-running servers that keep a connection or pool open across requests. For production use, consider [pgxpool](https://pkg.go.dev/github.com/jackc/pgx/v5/pgxpool) with health checks, or reconnecting on error.

<details>

<summary>**Notes for AI-assisted setup**</summary>

- Do not use `lib/pq`. It is a deprecated Go Postgres driver. Use `pgx/v5` as shown in this guide.
- Always use parameterized queries (`$1`, `$2`, etc.) for INSERT, UPDATE, and DELETE operations. Never concatenate user input into SQL strings.
- Wrap related database operations in a transaction (`conn.Begin` / `tx.Commit` / `tx.Rollback`). Use `defer tx.Rollback(ctx)` immediately after `conn.Begin` as a safety net.
- Always use `context.Context` for database operations. This enables cancellation and timeout control.
- Do not hardcode credentials in `.go` files. Use environment variables via `godotenv` and `os.Getenv`. For more information, see [Security overview](https://neon.com/docs/security/security-overview).

</details>

## Use an ORM

This guide uses raw SQL. An Object-Relational Mapping (ORM) library lets you work with rows as Go structs and can run migrations that keep your schema in sync with your models.

To use an ORM with Neon, see:

- [Connect a Go application to Neon using GORM](https://neon.com/guides/golang-gorm-postgres)

## Neon backend services

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Resources

- [pgx Documentation](https://pkg.go.dev/github.com/jackc/pgx/v5)

--- [Document source](https://neon.com/docs/guides/grafana-cloud.md) ---

> Summary: Grafana Cloud integration for Lakebase Postgres on Neon sends metrics and logs via the OTLP endpoint, routing metrics to Mimir and Postgres logs to Loki. Use this page to connect Neon to Grafana Cloud for dashboards, alerts, and LogQL queries covering connection counts, CPU, memory, cache hit rate, replication delay, and PgBouncer pooling metrics. Requires the Neon Scale plan.

# Grafana Cloud integration

Send metrics and logs from Lakebase Postgres on Neon to Grafana Cloud

Last updated: 2026-08-07

**What you will learn:**

- How to set up the Grafana Cloud integration
- How to configure log forwarding
- The full list of externally-available metrics

**External docs**

- [Grafana Cloud OTLP Documentation](https://grafana.com/docs/grafana-cloud/send-data/otlp/)
- [Grafana Cloud Authentication and Permissions](https://grafana.com/docs/grafana-cloud/account-management/authentication-and-permissions/)

The Grafana Cloud integration lets you monitor Neon database performance, resource utilization, and system health directly from Grafana Cloud. The integration requires [OTEL support](https://neon.com/docs/guides/opentelemetry), which is available with Neon's Scale plan.

## How it works

The integration uses Grafana Cloud's native OTLP endpoint to securely transmit Neon metrics and Postgres logs. By configuring the integration with your Grafana Cloud OTLP endpoint and authentication token, Neon automatically sends data from your project to your Grafana Cloud stack, where it's automatically routed to the appropriate storage backends (Mimir for metrics, Loki for logs, and Tempo for traces).

**Note:** Data is sent for all computes in your Neon project. For example, if you have multiple branches, each with an attached compute, both metrics and logs will be collected and sent for each compute.

### Neon metrics

The integration exports [a comprehensive set of metrics](https://neon.com/docs/guides/grafana-cloud#available-metrics) including:

- **Connection counts** — Tracks active and idle database connections.
- **Database size** — Monitors total size of all databases in bytes.
- **Replication delay** — Measures replication lag in bytes and seconds.
- **Compute metrics** — Includes CPU and memory usage statistics for your compute.
- **PgBouncer metrics** — Tracks connection pooling metrics including client and server connections.

### Postgres logs

**Note: Beta**

**Postgres logs export** is in beta. Share your feedback on [Discord](https://neon.com/discord) or via the [Neon Console](https://console.neon.tech/app/projects?modal=feedback).

With the Grafana Cloud integration, you can forward Postgres logs to your Grafana Cloud stack. These logs provide visibility into database activity, errors, and performance. See [Export Postgres logs to Grafana Cloud](https://neon.com/docs/guides/grafana-cloud#export-postgres-logs-to-grafana-cloud) for details.

## Prerequisites

Before getting started, ensure the following:

- You have a Neon account and project. If not, see [Sign up for a Neon account](https://neon.com/docs/get-started/signing-up).
- You have a Grafana Cloud account access to the Grafana Cloud Portal.

## Set up the integration

### 1. Get your Grafana Cloud credentials

In your Grafana Cloud instance:

1. Navigate to **Connections** → **Add new connection**.
2. Search for and select **Neon**.
3. Follow the **Neon Integration** wizard to generate a token with the required permissions.
4. Copy these three values for the next step:
   - **OTLP Endpoint** (for example, `https://otlp-gateway-prod-us-central-0.grafana.net/otlp`)
   - **Instance ID** (will be used as the username)
   - **API Key** (the generated token, will be used as the password)

**Tip:** The wizard automatically generates a token with the correct permissions (metrics:write, logs:write, traces:write).

### 2. Configure the integration in Neon

In the Neon Console:

1. Go to your project's **Integrations** page and select **OpenTelemetry** → **Add**.
2. Configure the connection:
   - **Protocol**: HTTP (recommended).
   - **Endpoint**: Your Grafana Cloud OTLP endpoint.
   - **Authentication**: Basic.
     - **Username**: Your OpenTelemetry Instance ID.
     - **Password**: Your Grafana Cloud API Key.
   - **Service name**: A descriptive name (for example, "neon-postgres-production").
   - **Export options**: Select **Metrics** and/or **Postgres logs** as needed.

Click **Add** to enable the integration.

**Tip:** You can change these settings later by editing your integration configuration from the **Integrations** page.

Once the integration is set up, Neon will start sending metrics and logs to your Grafana Cloud stack, where they'll be automatically stored in Mimir (metrics) and Loki (logs).

**Note:** Neon computes only send logs and metrics when they are active. If the [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero) feature is enabled and a compute is suspended due to inactivity, no logs or metrics will be sent during the suspension. This may result in gaps in your data. If you notice missing data, check if your compute is suspended. You can verify a compute's status as `Idle` or `Active` on the **Branches** page in the Neon console, and review **Suspend compute** events on the **System operations** tab of the **Monitoring** page.

Additionally, if you are setting up the Grafana Cloud integration for a project with an inactive compute, you'll need to activate the compute before it can send data. To activate it, simply run a query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any connected client.

## Example usage

Once integrated, you can explore your Neon metrics and logs in Grafana Cloud using the Explore feature. Navigate to **Explore** in your Grafana Cloud instance and query metrics like `neon_connection_counts`, `neon_db_total_size`, and `host_cpu_seconds_total` using your Prometheus data source. You can also create custom dashboards and set alerts based on threshold values for critical metrics.

## Import the Neon dashboard

Import the provided dashboard JSON configuration to get started with pre-built visualizations:

1. In your Grafana Cloud stack, navigate to **Dashboards** → **New** → **Import**
2. Copy and paste the [dashboard JSON below](https://neon.com/docs/guides/grafana-cloud#dashboard-json)
3. Click **Load** and configure the dashboard settings
4. The dashboard will automatically detect your Neon metrics and display key performance indicators

If any of the computes in your project are active, you should start seeing data in the resulting dashboard right away. By default, the dashboard shows metrics for all active endpoints in your project. You can filter results to one or more selected endpoints using the endpoint_id variable dropdown selector.

### Dashboard JSON

<details>

<summary>Copy Neon PostgreSQL Monitoring Dashboard JSON</summary>

```json
{
  "id": null,
  "uid": "neon-complete-monitoring",
  "title": "Neon PostgreSQL",
  "description": "Comprehensive monitoring dashboard for Neon PostgreSQL with metrics and logs",
  "tags": ["neon", "postgresql", "database", "monitoring"],
  "timezone": "browser",
  "editable": true,
  "graphTooltip": 1,
  "refresh": "30s",
  "schemaVersion": 39,
  "version": 1,
  "time": {
    "from": "now-1h",
    "to": "now"
  },
  "timepicker": {
    "refresh_intervals": ["5s", "10s", "30s", "1m", "5m", "15m", "30m", "1h", "2h", "1d"],
    "time_options": ["5m", "15m", "1h", "6h", "12h", "24h", "2d", "7d", "30d"]
  },
  "panels": [
    {
      "id": 1,
      "title": "Database Overview",
      "type": "stat",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "sum(neon_connection_counts{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"})",
          "legendFormat": "Total Connections",
          "refId": "A"
        },
        {
          "expr": "neon_db_total_size{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} / 1024 / 1024 / 1024",
          "legendFormat": "Database Size (GB)",
          "refId": "B"
        },
        {
          "expr": "neon_lfc_hits{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} / (neon_lfc_hits{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} + neon_lfc_misses{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}) * 100",
          "legendFormat": "Cache Hit Rate %",
          "refId": "C"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "short",
          "min": 0
        },
        "overrides": [
          {
            "matcher": {"id": "byName", "options": "Cache Hit Rate %"},
            "properties": [{"id": "unit", "value": "percent"}, {"id": "max", "value": 100}]
          },
          {
            "matcher": {"id": "byName", "options": "Database Size (GB)"},
            "properties": [{"id": "unit", "value": "decbytes"}]
          }
        ]
      },
      "gridPos": {"h": 6, "w": 24, "x": 0, "y": 0}
    },
    {
      "id": 2,
      "title": "Connection Activity",
      "type": "timeseries",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "neon_connection_counts{state=\"active\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Active - {{datname}}",
          "refId": "A"
        },
        {
          "expr": "neon_connection_counts{state=\"idle\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Idle - {{datname}}",
          "refId": "B"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "short",
          "min": 0
        }
      },
      "gridPos": {"h": 8, "w": 12, "x": 0, "y": 6}
    },
    {
      "id": 3,
      "title": "Database Size Growth",
      "type": "timeseries",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "neon_pg_stats_userdb{kind=\"db_size\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "{{datname}} Size",
          "refId": "A"
        },
        {
          "expr": "neon_db_total_size{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Total Size",
          "refId": "B"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "bytes",
          "min": 0
        }
      },
      "gridPos": {"h": 8, "w": 12, "x": 12, "y": 6}
    },
    {
      "id": 4,
      "title": "CPU Usage",
      "type": "timeseries",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "100 - (avg(rate(host_cpu_seconds_total{mode=\"idle\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m])) * 100)",
          "legendFormat": "CPU Usage %",
          "refId": "A"
        },
        {
          "expr": "rate(host_cpu_seconds_total{mode=\"system\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m]) * 100",
          "legendFormat": "System CPU %",
          "refId": "B"
        },
        {
          "expr": "rate(host_cpu_seconds_total{mode=\"user\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m]) * 100",
          "legendFormat": "User CPU %",
          "refId": "C"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "percent",
          "max": 100,
          "min": 0
        }
      },
      "gridPos": {"h": 8, "w": 12, "x": 0, "y": 14}
    },
    {
      "id": 5,
      "title": "Memory Usage",
      "type": "timeseries",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "host_memory_total_bytes{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Total Memory",
          "refId": "A"
        },
        {
          "expr": "host_memory_available_bytes{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Available Memory",
          "refId": "B"
        },
        {
          "expr": "host_memory_cached_bytes{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Cached Memory",
          "refId": "C"
        },
        {
          "expr": "host_memory_total_bytes{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} - host_memory_available_bytes{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Used Memory",
          "refId": "D"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "bytes",
          "min": 0
        }
      },
      "gridPos": {"h": 8, "w": 12, "x": 12, "y": 14}
    },
    {
      "id": 6,
      "title": "Database Activity Rates",
      "type": "timeseries",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "rate(neon_pg_stats_userdb{kind=\"inserted\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m])",
          "legendFormat": "Inserts/sec - {{datname}}",
          "refId": "A"
        },
        {
          "expr": "rate(neon_pg_stats_userdb{kind=\"updated\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m])",
          "legendFormat": "Updates/sec - {{datname}}",
          "refId": "B"
        },
        {
          "expr": "rate(neon_pg_stats_userdb{kind=\"deleted\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m])",
          "legendFormat": "Deletes/sec - {{datname}}",
          "refId": "C"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "rps",
          "min": 0
        }
      },
      "gridPos": {"h": 8, "w": 12, "x": 0, "y": 22}
    },
    {
      "id": 7,
      "title": "Cache Performance",
      "type": "timeseries",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "neon_lfc_hits{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} / (neon_lfc_hits{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} + neon_lfc_misses{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}) * 100",
          "legendFormat": "Cache Hit Rate %",
          "refId": "A"
        },
        {
          "expr": "rate(neon_lfc_hits{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m])",
          "legendFormat": "Cache Hits/sec",
          "refId": "B"
        },
        {
          "expr": "rate(neon_lfc_misses{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m])",
          "legendFormat": "Cache Misses/sec",
          "refId": "C"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "short",
          "min": 0
        },
        "overrides": [
          {
            "matcher": {"id": "byName", "options": "Cache Hit Rate %"},
            "properties": [{"id": "unit", "value": "percent"}, {"id": "max", "value": 100}]
          }
        ]
      },
      "gridPos": {"h": 8, "w": 12, "x": 12, "y": 22}
    },
    {
      "id": 8,
      "title": "Replication Status",
      "type": "timeseries",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "neon_replication_delay_bytes{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Replication Delay (Bytes)",
          "refId": "A"
        },
        {
          "expr": "neon_replication_delay_seconds{endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "legendFormat": "Replication Delay (Seconds)",
          "refId": "B"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "short",
          "min": 0
        },
        "overrides": [
          {
            "matcher": {"id": "byName", "options": "Replication Delay (Bytes)"},
            "properties": [{"id": "unit", "value": "bytes"}]
          },
          {
            "matcher": {"id": "byName", "options": "Replication Delay (Seconds)"},
            "properties": [{"id": "unit", "value": "s"}]
          }
        ]
      },
      "gridPos": {"h": 8, "w": 12, "x": 0, "y": 30}
    },
    {
      "id": 9,
      "title": "Deadlocks & Errors",
      "type": "timeseries",
      "datasource": {
        "type": "prometheus",
        "uid": "${DS_PROMETHEUS}"
      },
      "targets": [
        {
          "expr": "increase(neon_pg_stats_userdb{kind=\"deadlocks\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}[5m])",
          "legendFormat": "Deadlocks - {{datname}}",
          "refId": "A"
        }
      ],
      "fieldConfig": {
        "defaults": {
          "unit": "short",
          "min": 0
        }
      },
      "gridPos": {"h": 8, "w": 12, "x": 12, "y": 30}
    },
    {
      "id": 10,
      "title": "PostgreSQL Error Logs",
      "type": "logs",
      "datasource": {
        "type": "loki",
        "uid": "${DS_LOKI}"
      },
      "targets": [
        {
          "expr": "{service_name=\"$service_name\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} |~ \"(?i)error|fatal|panic\"",
          "refId": "A"
        }
      ],
      "options": {
        "showTime": true,
        "showLabels": true,
        "showCommonLabels": false,
        "wrapLogMessage": true,
        "prettifyLogMessage": false,
        "enableLogDetails": true,
        "dedupStrategy": "none",
        "sortOrder": "Descending"
      },
      "gridPos": {"h": 10, "w": 24, "x": 0, "y": 38}
    },
    {
      "id": 11,
      "title": "Connection Events",
      "type": "logs",
      "datasource": {
        "type": "loki",
        "uid": "${DS_LOKI}"
      },
      "targets": [
        {
          "expr": "{service_name=\"$service_name\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} |~ \"(?i)connection|connect|disconnect\"",
          "refId": "A"
        }
      ],
      "options": {
        "showTime": true,
        "showLabels": false,
        "showCommonLabels": false,
        "wrapLogMessage": true,
        "enableLogDetails": true,
        "sortOrder": "Descending"
      },
      "gridPos": {"h": 8, "w": 12, "x": 0, "y": 48}
    },
    {
      "id": 12,
      "title": "Query Performance Logs",
      "type": "logs",
      "datasource": {
        "type": "loki",
        "uid": "${DS_LOKI}"
      },
      "targets": [
        {
          "expr": "{service_name=\"$service_name\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"} |~ \"(?i)slow|duration|statement|query\" | logfmt",
          "refId": "A"
        }
      ],
      "options": {
        "showTime": true,
        "showLabels": false,
        "showCommonLabels": false,
        "wrapLogMessage": true,
        "enableLogDetails": true,
        "sortOrder": "Descending"
      },
      "gridPos": {"h": 8, "w": 12, "x": 12, "y": 48}
    },
    {
      "id": 13,
      "title": "Recent Log Activity",
      "type": "logs",
      "datasource": {
        "type": "loki",
        "uid": "${DS_LOKI}"
      },
      "targets": [
        {
          "expr": "{service_name=\"$service_name\", endpoint_id=~\"$endpoint_id\", project_id=~\"$project_id\"}",
          "refId": "A"
        }
      ],
      "options": {
        "showTime": true,
        "showLabels": false,
        "showCommonLabels": false,
        "wrapLogMessage": true,
        "enableLogDetails": true,
        "sortOrder": "Descending"
      },
      "maxDataPoints": 1000,
      "gridPos": {"h": 10, "w": 24, "x": 0, "y": 56}
    }
  ],
  "templating": {
    "list": [
      {
        "name": "DS_PROMETHEUS",
        "label": "Prometheus Datasource",
        "type": "datasource",
        "query": "prometheus",
        "hide": 0,
        "refresh": 1,
        "current": {
          "selected": false,
          "text": "Prometheus",
          "value": "prometheus"
        }
      },
      {
        "name": "DS_LOKI",
        "label": "Loki Datasource", 
        "type": "datasource",
        "query": "loki",
        "hide": 0,
        "refresh": 1,
        "current": {
          "selected": false,
          "text": "Loki",
          "value": "loki"
        }
      },
      {
        "name": "endpoint_id",
        "label": "Endpoint ID",
        "type": "query",
        "query": {
          "query": "label_values(neon_connection_counts, endpoint_id)",
          "refId": "StandardVariableQuery"
        },
        "datasource": {
          "type": "prometheus",
          "uid": "${DS_PROMETHEUS}"
        },
        "refresh": 2,
        "multi": true,
        "includeAll": true,
        "allValue": ".*",
        "current": {
          "selected": false,
          "text": "All",
          "value": "$__all"
        }
      },
      {
        "name": "project_id",
        "label": "Project ID",
        "type": "query",
        "query": {
          "query": "label_values(neon_connection_counts, project_id)",
          "refId": "StandardVariableQuery"
        },
        "datasource": {
          "type": "prometheus",
          "uid": "${DS_PROMETHEUS}"
        },
        "refresh": 2,
        "multi": true,
        "includeAll": true,
        "allValue": ".*",
        "current": {
          "selected": false,
          "text": "All",
          "value": "$__all"
        }
      },
      {
        "name": "service_name",
        "label": "Service Name",
        "type": "query",
        "query": {
          "query": "label_values({__name__=~\".+\"}, service_name)",
          "refId": "StandardVariableQuery"
        },
        "datasource": {
          "type": "loki",
          "uid": "${DS_LOKI}"
        },
        "refresh": 2,
        "multi": false,
        "includeAll": false,
        "current": {
          "selected": false,
          "text": "",
          "value": ""
        }
      }
    ]
  },
  "annotations": {
    "list": [
      {
        "name": "High CPU",
        "datasource": {
          "type": "prometheus",
          "uid": "${DS_PROMETHEUS}"
        },
        "expr": "100 - (avg(rate(host_cpu_seconds_total{mode=\"idle\"}[5m])) * 100) > 80",
        "titleFormat": "High CPU Usage",
        "textFormat": "CPU usage is above 80%",
        "iconColor": "red"
      },
      {
        "name": "Low Cache Hit Rate",
        "datasource": {
          "type": "prometheus", 
          "uid": "${DS_PROMETHEUS}"
        },
        "expr": "neon_lfc_hits / (neon_lfc_hits + neon_lfc_misses) * 100 < 90",
        "titleFormat": "Low Cache Hit Rate",
        "textFormat": "Cache hit rate dropped below 90%",
        "iconColor": "yellow"
      }
    ]
  },
  "links": [
    {
      "title": "Neon Console",
      "url": "https://console.neon.tech",
      "type": "link",
      "icon": "external link"
    },
    {
      "title": "Metrics Reference",
      "url": "https://neon.com/docs/reference/metrics-logs",
      "type": "link",
      "icon": "doc"
    }
  ]
}
```

</details>

## Available metrics

Neon exports a comprehensive set of metrics including connection counts, database size, replication delay, compute metrics (CPU and memory usage), and PgBouncer connection pooling metrics (client and server connections). For a complete list of all available metrics with detailed descriptions, see the [Metrics and logs reference](https://neon.com/docs/reference/metrics-logs).

## Export Postgres logs

You can export your Postgres logs from your Neon compute to your Grafana Cloud stack. These logs provide visibility into database activity, errors, and performance. The logs are automatically sent to Grafana Cloud Loki and can be queried using LogQL. By default, logs include warnings and errors, connections and disconnections, checkpoints, and slow autovacuum runs. Query text isn't logged, and slow-query logging is off unless you turn it on. For the full list of logging settings and log fields, see [Postgres logs](https://neon.com/docs/reference/metrics-logs#postgres-logs) in the Metrics and logs reference.

### Performance impact

Enabling this feature may result in:

- An increase in compute resource usage for log processing
- Additional public network transfer for log transmission, which counts toward your plan's [network transfer allowance](https://neon.com/docs/introduction/network-transfer)
- Associated costs based on log volume in Grafana Cloud

### Querying logs in Grafana Cloud

Once logs are flowing, you can query them in Grafana's Explore view using LogQL:

```logql
# View all logs from your Neon service
{service_name="your-service-name"}

# Filter for errors only
{service_name="your-service-name"} |= "ERROR"

# View connection events
{service_name="your-service-name"} |= "connection"
```

## Set up alerts

Create alerts for key metrics to monitor your database health:

1. **High CPU Usage**: Alert when CPU usage exceeds 80%

   ```promql
   rate(host_cpu_seconds_total{mode!="idle"}[5m]) > 0.8
   ```

2. **Low Cache Hit Rate**: Alert when cache hit rate drops below 90%

   ```promql
   neon_lfc_hits / (neon_lfc_hits + neon_lfc_misses) < 0.9
   ```

3. **High Connection Count**: Alert when connections exceed your threshold
   ```promql
   sum(neon_connection_counts) > 100
   ```

## Feedback and future improvements

We're always looking to improve! If you have feature requests or feedback, please let us know via the [Feedback form](https://console.neon.tech/app/projects?modal=feedback) in the Neon Console or on our [Discord channel](https://discord.com/channels/1176467419317940276/1176788564890112042).

--- [Document source](https://neon.com/docs/guides/hasura.md) ---

> Summary: Hasura Cloud connects to Lakebase Postgres either by OAuth (creating a new Neon project automatically) or by pasting an existing connection string into the Hasura Console. Connection limits depend on compute size and pooling settings, so tuning both Neon and Hasura values is required when hitting limits. Hasura event triggers, cron triggers, and source health checks can prevent Neon's scale-to-zero suspension.

# Connect from Hasura Cloud to Neon

Learn how to connect a Hasura Cloud project to a new or existing Neon database

Last updated: 2026-09-16

Hasura Cloud is an open source GraphQL engine that provides a scalable, highly available, globally distributed, secure GraphQL API for your data sources.

This guide covers Hasura v2 on Hasura Cloud. Hasura DDN, Hasura's newer product, uses a different engine and setup, and moving to it is optional. For supported v2 versions and end-of-life dates, see the [Hasura v2 support policy](https://hasura.io/legal/support-policy-hasura-v2).

## Connecting to a new Neon database

Use the following instructions to connect to a new Neon database. This connection method authenticates you from Hasura Cloud.

1. Navigate to [Hasura Cloud](https://cloud.hasura.io/projects) and sign up or log in.
2. On the Hasura Cloud dashboard, click **Create a project** to create a new Hasura project.
   ![Hasura Create a Projects](https://neon.com/docs/guides/hasura/create-project.png)
3. After the project is initialized, click **Launch Console** to open the Hasura Console.
   ![Hasura Launch Console](https://neon.com/docs/guides/hasura/launch-console.png)
4. On the Hasura Console, Select **Data** from the top navigation bar.
5. Click **Postgres** > **Connect Neon Database**.
   ![Hasura Connect Neon Database](https://neon.com/docs/guides/hasura/connect-neon-database.png)
6. When prompted to login or sign up for Neon, we recommend selecting **Hasura** for seamless authentication.
7. You will be redirected to an Oauth page to authorize Hasura to access your Neon account. Click **Authorize** to allow Hasura to create a new Neon project and database.
   ![Hasura Authorize Neon](https://neon.com/docs/guides/hasura/authorize-hasura.png)

After authenticating, a new Lakebase Postgres database is created and connected to your Hasura project, and the Neon project connection string is associated with the `PG_DATABASE_URL` environment variable.

![Environment Variables](https://neon.com/docs/guides/hasura/environment-variables.png)

To start exploring Hasura's GraphQL API with data stored in the database, see [Load a template in Hasura](https://neon.com/docs/guides/hasura#load-a-template-in-hasura-optional).

## Connecting to an existing Neon database

Use the following instructions to connect to an existing Neon database from Hasura Cloud. The connection is configured manually using a connection string.

### Prerequisites

- An existing Neon account. If you do not have one, see [Sign up](https://neon.com/docs/get-started/signing-up).
- An existing Neon project. If you do not have a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).
- A connection string for a database in your Neon project:

  ```text
  postgresql://[user]:[password]@[neon_hostname]/[dbname]
  ```

  You can find your database connection string by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

### Add Neon as a data source

The following steps describe how to navigate to Hasura Cloud and connect to your Neon project.

1. Navigate to [Hasura Cloud](https://cloud.hasura.io/projects) and sign up or log in.

2. Click **Create Project** to create a Hasura Cloud project or click **Launch Console** to open an existing project.

3. In the Hasura Console, select **Data** from the top navigation bar.

4. Click **Postgres** > **Connect Existing Database**.
   ![Hasura Connect Existing Database](https://neon.com/docs/guides/hasura/connect-existing-database.png)

5. Paste your connection string into the **Database URL** field.

   **Tip:** To enhance security and manageability, consider using environment variables in Hasura instead of hardcoding the connection string. To do this, navigate to **Hasura Project settings** > **Env vars** > **New env var** and create a new variable (for example, `NEON_DATABASE_URL`) with your connection string as its value.

   ![Create Environment Variable](https://neon.com/docs/guides/hasura/create-env-var.png)

   Then, in the connection tab, select **Connect database via Environment variable** and enter the variable name you created. This approach keeps your connection string secure and simplifies future updates.

6. Enter a display name for your database in the **Database name** field, and click **Connect Database**.

Hasura Cloud connects to your Neon project and automatically discovers the default `public` schema.

To start exploring Hasura's GraphQL API with data stored in Neon, see [Load a template in Hasura](https://neon.com/docs/guides/hasura#load-a-template-in-hasura-optional).

## Load a template in Hasura (optional)

Optionally, after connecting from your Hasura project to Neon, you can explore Hasura's GraphQL API by loading a template from Hasura's template gallery. Follow these steps to load the `Welcome to Hasura` template, which creates `customer` and `order` tables and populates them with sample data.

1. In the Hasura Console, select **Data**.
2. Under **Data Manager**, select your database.
3. From the **Template Gallery**, select **Welcome to Hasura** to install the template.

To view the newly created tables from the Neon Console:

1. In the Hasura Console, select **Data** > **Manage your Neon databases** to open the Neon Console.
2. In the Neon Console, select your project.
3. Select the **Tables** tab. The newly created `customer` and `order` tables should appear under the **Tables** heading in the sidebar.

## Import existing data to Neon

If you are migrating from Hasura with Heroku Postgres to Neon, refer to the [Import data from Heroku](https://neon.com/docs/import/migrate-from-heroku) guide for data import instructions. For general data import instructions, see [Import data from Postgres](https://neon.com/docs/import/migrate-from-postgres).

## Maximum connections configuration

In Neon, the maximum number of concurrent connections is defined according to the size of your compute. For example, a 0.25 CU compute in Neon supports 112 connections. The connection limit is higher with larger compute sizes (see [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute)). You can also enable connection pooling in Neon to support up to 10,000 concurrent connections. However, it is important to note that Hasura has a `HASURA_GRAPHQL_PG_CONNECTIONS` setting that limits Postgres connections to `50` by default. If you start encountering errors related to "max connections", try increasing the value of this setting as a first step, staying within the connection limit for your Neon compute. For information about the Hasura connection limit setting, refer to the [Hasura Postgres configuration documentation](https://hasura.io/docs/latest/deployment/performance-tuning/#postgres-configuration).

## Scale to zero considerations

Neon suspends a compute after five minutes (300 seconds) of inactivity. This behavior can be adjusted on Neon's paid plans. For more information, refer to [Configuring Scale to zero for Neon computes](https://neon.com/docs/guides/scale-to-zero-guide).

If you rely on Neon's scale to zero feature to minimize database usage, note that certain Hasura configuration options can keep your Neon compute in an active state:

- [Event triggers](https://hasura.io/docs/latest/event-triggers/overview/) may periodically poll your Neon database for new events.
- [Cron triggers](https://hasura.io/docs/latest/scheduled-triggers/create-cron-trigger/) can invoke HTTP endpoints that execute custom business logic involving your Neon database.
- [Source Health Checks](https://hasura.io/docs/latest/deployment/health-checks/source-health-check/) can keep your Neon compute active if the metadata database resides in Neon.

## Use Neon branches with Hasura

To serve development, testing, and preview environments from one Neon project and one Hasura instance, see [Dynamic routing with Hasura and Neon](https://neon.com/guides/hasura-dynamic-routing-with-neon).

--- [Document source](https://neon.com/docs/guides/heroku.md) ---

> Summary: Deploy a Node.js Express app to Heroku with Lakebase Postgres as the database backend. Covers creating the Neon project, connecting via the `pg` driver and `DATABASE_URL`, and pushing to Heroku using the Heroku CLI and Git. Useful when migrating from Heroku Postgres or hosting a new Node app on Heroku with Neon.

# Deploy Your Node.js App with Lakebase Postgres on Heroku

A step-by-step guide to deploying a Node application with a Lakebase Postgres database on Heroku

Last updated: 2026-10-28

[Heroku](https://heroku.com) is a popular platform as a service (PaaS) that enables developers to build, run, and operate applications entirely in the cloud. It simplifies the deployment process, making it a favorite among developers for its ease of use and integration capabilities.

This guide walks you through deploying a simple Node.js application connected to a Lakebase Postgres database, on Heroku.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- A Heroku account. Sign up at [Heroku](https://signup.heroku.com/) to get started.
- Git installed on your local machine. Heroku uses Git for version control and deployment.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.

## Setting Up Your Neon Database

### Initialize a New Project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.

2. Click **New Project** to create a new project.

3. In the Neon Console, go to **Postgres database** > **SQL Editor** and run the following SQL command to create a new table:

   ```sql
   CREATE TABLE music_albums (
       album_id SERIAL PRIMARY KEY,
       title VARCHAR(255) NOT NULL,
       artist VARCHAR(255) NOT NULL
   );

   INSERT INTO music_albums (title, artist)
   VALUES
       ('Rumours', 'Fleetwood Mac'),
       ('Abbey Road', 'The Beatles'),
       ('Dark Side of the Moon', 'Pink Floyd'),
       ('Thriller', 'Michael Jackson');
   ```

### Retrieve your Neon database connection string

You can find your database connection string by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

## Implementing the Node.js Application

We'll create a simple Express application that connects to our Neon database and retrieves the list of music albums. Run the following commands in your terminal to set it up:

```bash
mkdir neon-heroku-example && cd neon-heroku-example
npm init -y && npm pkg set type="module" && npm pkg set scripts.start="node index.js"
npm install express pg
touch .env
```

We use the `npm pkg set type="module"` command to enable ES6 module support in our project. We'll also create a new `.env` file to store the `DATABASE_URL` environment variable, which we'll use to connect to our Neon database. Lastly, we install the `pg` library which is the Postgres driver we use to connect to our database.

In the `.env` file, store your Neon database connection string:

```bash
# .env
DATABASE_URL=NEON_DATABASE_CONNECTION_STRING
```

Now, create a new file named `index.js` and add the following code:

```javascript
import express from 'express';
import pkg from 'pg';

const app = express();
const port = process.env.PORT || 3000;

// Parse JSON bodies for this app
app.use(express.json());

// Create a new pool using your Neon database connection string
const { Pool } = pkg;
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

app.get('/', async (req, res) => {
  try {
    // Fetch the list of music albums from your database using the postgres connection
    const { rows } = await pool.query('SELECT * FROM music_albums;');
    res.json(rows);
  } catch (error) {
    console.error('Failed to fetch albums', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

// Start the server
app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});
```

This code sets up an Express server that listens for requests on port 3000. When a request is made to the `URL`, the server queries the `music_albums` table in your Neon database and returns the results as JSON.

We can test this application locally by running:

```bash
node --env-file=.env index.js
```

Now, navigate to `http://localhost:3000/` in your browser to check it returns the sample data from the `music_albums` table.

## Deploying to Heroku

### Create a New Heroku App

We will use the `Heroku CLI` to deploy our application to Heroku manually. You can install it on your machine by following the instructions [here](https://devcenter.heroku.com/articles/heroku-cli). Once installed, log in to your Heroku account using:

```bash
❯ heroku login
 '   Warning: Our terms of service have changed:
 '   https://dashboard.heroku.com/terms-of-service
heroku: Press any key to open up the browser to login or q to exit:
Opening browser to https://cli-auth.heroku.com/auth/cli/browser/...
```

You will be prompted to log in to your Heroku account in the browser. After logging in, you can close the browser and return to your terminal.

Before creating the Heroku application, we need to initialize a new Git repository in our project folder:

```bash
git init && echo "node_modules" > .gitignore && echo ".env" >> .gitignore
git branch -M main
git add . && git commit -m "Initial commit"
```

Next, we can create a new app on Heroku using the following command. This creates a new Heroku app with the name `neon-heroku-example`, and sets up a new Git remote for the app called `heroku`.

```bash
heroku create neon-heroku-example
```

You'll also need to set the `DATABASE_URL` on Heroku to your Neon database connection string:

```bash
heroku config:set DATABASE_URL='NEON_DATABASE_CONNECTION_STRING' -a neon-heroku-example
```

### Deploy Your Application

To deploy your application to Heroku, use the following command to push your code to the `heroku` remote. Heroku will automatically detect that your application is a Node.js application, install the necessary dependencies and deploy it.

```bash
> git push heroku main
.
.
.
remote: -----> Launching...
remote:        Released v4
remote:        https://neon-heroku-example-fda03f6acbbe.herokuapp.com/ deployed to Heroku
remote:
remote: Verifying deploy... done.
remote: 2024/02/21 07:26:49 Rollbar error: empty token
To https://git.heroku.com/neon-heroku-example.git
remote: Verifying deploy... done.
```

Once the deployment is complete, you should see a message with the URL of your deployed application. Navigate to this URL in your browser to see your application live on Heroku.

You've now successfully deployed a Node.js application on Heroku that connects to a Lakebase Postgres database. For further customization and scaling options, you can explore the Heroku and Neon documentation.

## Removing Your Application and Neon Project

To remove your application from Heroku, select the app from your [Heroku dashboard](https://dashboard.heroku.com/apps). Navigate to the `Settings` tab and scroll down to the end to find the "Delete App" option.

To delete your Neon project, follow the steps outlined in the Neon documentation under [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

## Resources

- [Heroku Documentation](https://devcenter.heroku.com/)
- [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)
- [Neon](https://neon.com/docs)
- [Import data from Heroku Postgres to Neon](https://neon.com/docs/import/migrate-from-heroku)

--- [Document source](https://neon.com/docs/guides/hono.md) ---

> Summary: Connect a Hono application to Lakebase Postgres using node-postgres, postgres.js, or the Neon serverless driver (@neondatabase/serverless). Covers DATABASE_URL setup and route-level query code for Hono on Node.js, Bun, Deno, and Edge runtimes. Each driver option includes a complete TypeScript route handler with Postgres query examples.

# Connect a Hono application to Neon

Set up a Neon project in seconds and connect from a Hono application

Last updated: 2026-10-08

Pre-built prompt for connecting Hono applications to Lakebase Postgres [View prompt](https://neon.com/prompts/hono-prompt.md)

[Hono](https://hono.dev/) is a lightweight, multi-runtime web framework for the Edge, Node.js, Deno, Bun, and other runtimes. This topic describes how to create a Neon project and access it from a Hono application.

To create a Neon project and access it from a Hono application:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Hono project and add dependencies

1. Create a Hono project if you do not have one. This guide uses the Node.js template:

   ```shell
   npm create hono@latest my-app -- --template nodejs --pm npm --install
   cd my-app
   ```

   For other runtimes, see [Quick Start](https://hono.dev/docs/getting-started/basic) in the Hono documentation.

2. Add project dependencies using one of the following commands:

**node-postgres**

```shell
npm install pg
npm install -D @types/pg
```

**postgres.js**

```shell
npm install postgres
```

**Neon serverless driver**

```shell
npm install @neondatabase/serverless
```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection string to it. You can find your connection details by clicking **Connect** in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

The Node.js template's `dev` script (`tsx watch src/index.ts`) doesn't load `.env`. Without it, `DATABASE_URL` is undefined and the drivers try to connect to `localhost`. Update the `dev` and `start` scripts in `package.json` to load the file with Node's `--env-file` option:

```json filename="package.json"
{
  "scripts": {
    "dev": "tsx watch --env-file=.env src/index.ts",
    "build": "tsc",
    "start": "node --env-file=.env dist/index.js"
  }
}
```

If you use node-postgres, `pg` 8.23 and later print a `SECURITY WARNING` for `sslmode=require`. Change it to `sslmode=verify-full` to keep the same behavior without the warning.

## Configure the Postgres client

In your Hono application (for example, in `src/index.ts` or a specific route file), create the database client once at module level and use it in your route handlers.

Here's how you can set up a simple route to query the database. Replace the contents of `src/index.ts`:

**node-postgres**

```typescript filename="src/index.ts"
import { Pool } from 'pg';
import { Hono } from 'hono';
import { serve } from '@hono/node-server';

const app = new Hono();
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: true,
});

app.get('/', async (c) => {
  try {
    const { rows } = await pool.query('SELECT version()');
    return c.json({ version: rows[0].version });
  } catch (error) {
    console.error('Database query failed:', error);
    return c.text('Failed to connect to database', 500);
  }
});

serve(app, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`);
});
```

**postgres.js**

```typescript filename="src/index.ts"
import { Hono } from 'hono';
import postgres from 'postgres';
import { serve } from '@hono/node-server';

const app = new Hono();
const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

app.get('/', async (c) => {
  try {
    const response = await sql`SELECT version()`;
    return c.json({ version: response[0].version });
  } catch (error) {
    console.error('Database query failed:', error);
    return c.text('Failed to connect to database', 500);
  }
});

serve(app, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`);
});
```

**Neon serverless driver**

```typescript filename="src/index.ts"
import { Hono } from 'hono';
import { serve } from '@hono/node-server';
import { neon } from '@neondatabase/serverless';

const app = new Hono();
const sql = neon(process.env.DATABASE_URL!);

app.get('/', async (c) => {
  try {
    const response = await sql`SELECT version()`;
    return c.json({ version: response[0]?.version });
  } catch (error) {
    console.error('Database query failed:', error);
    return c.text('Failed to connect to database', 500);
  }
});

serve(app, (info) => {
  console.log(`Server is running on http://localhost:${info.port}`);
});
```

## Run the app

Start your Hono development server. You can use the following command:

```bash
npm run dev
```

Navigate to your application's URL ([localhost:3000](http://localhost:3000)). You should see a JSON response with the Postgres version:

```json
{
  "version": "PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit"
}
```

To run a production build, run `npm run build` and then `npm start`.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/quickstart): Build realtime apps with end-to-end reactivity »

--- [Document source](https://neon.com/docs/guides/imagekit.md) ---

> Summary: Integrate ImageKit.io with Lakebase Postgres for client-side media uploads to ImageKit's CDN, with file metadata stored in a Neon database. Backend authentication generates signed parameters (token, expire, signature) so uploads never touch your server. Includes backend examples for Node.js (Hono) and Python (Flask), a curl test workflow, and SQL patterns for per-user metadata retrieval.

# Media storage with ImageKit.io

Store files via ImageKit.io and track metadata in Neon

Last updated: 2026-09-16

[ImageKit.io](https://imagekit.io/) is a cloud-based image and video optimization and delivery platform. It provides real-time manipulation, storage, and delivery via a global CDN, simplifying media management for web and mobile applications.

**Neon now offers native storage:**

Neon Object Storage is S3-compatible object storage built into the Neon backend. Object storage branches with your database: each branch gets its own isolated namespace, so you can test file uploads in preview branches without touching production. No separate cloud account needed. Use any S3-compatible SDK with your existing Neon credential.

For more information, see [Neon Object Storage](https://neon.com/docs/storage/overview).

This guide demonstrates how to integrate ImageKit.io with Neon. You'll learn how to upload files directly from the client-side to ImageKit.io using securely generated authentication parameters from your backend, and then store the resulting file metadata (like the ImageKit File ID and URL) in your Lakebase Postgres database.

## Setup steps

## Create a Neon project

1. Navigate to the [Neon Console](https://console.neon.tech) to create a new Neon project.
2. Copy the connection string by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Create an ImageKit.io account and get credentials

1. Sign up for a free or paid account at [ImageKit.io](https://imagekit.io/registration).
2. Once logged in, navigate to the **Developer options** section in the dashboard sidebar.
3. Under **API Keys**, note your **Public Key**, **Private Key**, and **URL Endpoint**. These are essential for interacting with the ImageKit API and SDKs.
   ![ImageKit API Keys](https://neon.com/docs/guides/imagekit-api-keys.png)

## Create a table in Neon for file metadata

We need a table in Lakebase Postgres to store metadata about the files uploaded to ImageKit.io. This allows your application to reference the media stored in ImageKit.

1. Connect to your database on Neon using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a client like [psql](https://neon.com/docs/connect/query-with-psql-editor). Create a table to store relevant details:

   ```sql
   CREATE TABLE IF NOT EXISTS imagekit_files (
       id SERIAL PRIMARY KEY,
       file_id TEXT NOT NULL UNIQUE,    -- ImageKit.io unique File ID
       file_url TEXT NOT NULL,          -- ImageKit CDN URL for the file
       user_id TEXT NOT NULL,           -- User associated with the file
       upload_timestamp TIMESTAMPTZ DEFAULT NOW()
   );
   ```

2. Run the SQL statement. You can customize this table by adding or removing columns (like `width`, `height`, `tags`, etc.) based on the information you need from ImageKit and your application's requirements.

**Note: Securing metadata with RLS**

If you use [Neon's Row Level Security (RLS)](https://neon.com/blog/introducing-neon-authorize), remember to apply appropriate access policies to the `imagekit_files` table. This controls who can view or modify the object references stored in Lakebase Postgres based on your RLS rules.

Note that these policies apply _only_ to the metadata in Neon. Access control for the actual files on ImageKit is managed via ImageKit features (like private files or signed URLs, if needed). The default setup makes files publicly accessible via their URL.

## Upload files to ImageKit.io and store metadata in Neon

The recommended approach for client-side uploads is to generate secure **authentication parameters** on your backend. The client (for example, a web browser) uses these parameters, along with your public API key, to upload the file directly to ImageKit's Upload API. After a successful upload, the client sends the returned metadata (like `fileId` and `url`) back to your backend to be saved in Lakebase Postgres.

This requires two backend endpoints:

1. `/generate-auth-params`: Generates temporary authentication parameters (`token`, `expire`, `signature`).
2. `/save-metadata`: Receives file metadata from the client after a successful upload to ImageKit and saves it to the Neon database.

**JavaScript**

We'll use [Hono](https://hono.dev/) for the server, [`imagekit
`](https://www.npmjs.com/package/imagekit) for ImageKit interaction, and [`@neondatabase/serverless`](https://www.npmjs.com/package/@neondatabase/serverless) for Neon.

First, install the necessary dependencies:

```bash
npm install imagekit @neondatabase/serverless @hono/node-server hono dotenv
```

Create a `.env` file with your credentials:

```env
# ImageKit.io Credentials
IMAGEKIT_PUBLIC_KEY=your_imagekit_public_key
IMAGEKIT_PRIVATE_KEY=your_imagekit_private_key
IMAGEKIT_URL_ENDPOINT=your_imagekit_url_endpoint

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```javascript
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import ImageKit from 'imagekit';
import { neon } from '@neondatabase/serverless';
import 'dotenv/config';

const imagekit = new ImageKit({
  publicKey: process.env.IMAGEKIT_PUBLIC_KEY,
  privateKey: process.env.IMAGEKIT_PRIVATE_KEY,
  urlEndpoint: process.env.IMAGEKIT_URL_ENDPOINT,
});

const sql = neon(process.env.DATABASE_URL);
const app = new Hono();

// Replace this with your actual user authentication logic
const authMiddleware = async (c, next) => {
  // Example: Validate JWT, session, etc. and set user ID
  c.set('userId', 'user_123'); // Static ID for demonstration
  await next();
};

// 1. Generate authentication parameters for client-side upload
app.get('/generate-auth-params', authMiddleware, (c) => {
  try {
    const authParams = imagekit.getAuthenticationParameters();
    // These params (token, expire, signature) are sent to the client
    // The client uses these + public key to upload directly to ImageKit
    return c.json({ success: true, ...authParams });
  } catch (error) {
    console.error('Auth Param Generation Error:', error);
    return c.json({ success: false, error: 'Failed to generate auth params' }, 500);
  }
});

// 2. Save metadata after client confirms successful upload to ImageKit
app.post('/save-metadata', authMiddleware, async (c) => {
  try {
    const userId = c.get('userId');
    // Client sends metadata received from ImageKit after upload
    const { fileId, url } = await c.req.json();

    if (!fileId || !url) {
      throw new Error('fileId and url are required from ImageKit response');
    }

    // Insert metadata into Neon database
    await sql`
      INSERT INTO imagekit_files (file_id, file_url, user_id)
      VALUES (${fileId}, ${url}, ${userId})
    `;

    console.log(`Metadata saved for ImageKit file: ${fileId}`);
    return c.json({ success: true });
  } catch (error) {
    console.error('Metadata Save Error:', error.message);
    return c.json({ success: false, error: 'Failed to save metadata' }, 500);
  }
});

const port = 3000;
serve({ fetch: app.fetch, port }, (info) => {
  console.log(`Server running at http://localhost:${info.port}`);
});
```

**Explanation**

1. **Setup:** Initializes the Lakebase Postgres database client (`sql`), the Hono web framework (`app`), and the ImageKit Node.js SDK (`imagekit`) using credentials from environment variables.
2. **Authentication:** Includes a placeholder `authMiddleware`. **Replace this with your actual user authentication logic** to ensure only authenticated users can generate upload parameters and save metadata.
3. **API endpoints:**
   - **`/generate-auth-params` (GET):** Uses the ImageKit SDK's `getAuthenticationParameters()` method to create a short-lived `token`, `expire` timestamp, and `signature`. These are returned to the client.
   - **`/save-metadata` (POST):** This endpoint is called by the client _after_ it has successfully uploaded a file directly to ImageKit's Upload API. The client sends the relevant metadata returned by ImageKit (like `fileId`, `url`, `thumbnailUrl`, etc.). The endpoint then inserts this metadata, along with the authenticated `userId`, into the `imagekit_files` table in Lakebase Postgres.

**Python**

We'll use [Flask](https://flask.palletsprojects.com/en/stable/), [`imagekitio`](https://pypi.org/project/imagekitio/) (ImageKit Python SDK), and [`psycopg2`](https://pypi.org/project/psycopg2/).

First, install the necessary dependencies:

```bash
pip install Flask imagekitio psycopg2-binary python-dotenv
```

Create a `.env` file with your credentials:

```env
# ImageKit.io Credentials
IMAGEKIT_PUBLIC_KEY=your_imagekit_public_key
IMAGEKIT_PRIVATE_KEY=your_imagekit_private_key
IMAGEKIT_URL_ENDPOINT=your_imagekit_url_endpoint # for example, https://ik.imagekit.io/your_instance_id

# Neon Connection String
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```python
import os

import psycopg2
from dotenv import load_dotenv
from flask import Flask, jsonify, request
from imagekitio.client import ImageKit

load_dotenv()

imagekit = ImageKit(
    public_key=os.getenv("IMAGEKIT_PUBLIC_KEY"),
    private_key=os.getenv("IMAGEKIT_PRIVATE_KEY"),
    url_endpoint=os.getenv("IMAGEKIT_URL_ENDPOINT"),
)

app = Flask(__name__)


# Use a global PostgreSQL connection pool in production instead of connecting per request
def get_db_connection():
    return psycopg2.connect(os.getenv("DATABASE_URL"))


# Replace this with your actual user authentication logic
def get_authenticated_user_id(request):
    # Example: Validate Authorization header, session cookie, etc.
    return "user_123"  # Static ID for demonstration


# 1. Generate authentication parameters for client-side upload
@app.route("/generate-auth-params", methods=["GET"])
def generate_auth_params_route():
    try:
        user_id = get_authenticated_user_id(request)
        if not user_id:
            return jsonify({"success": False, "error": "Unauthorized"}), 401

        # Generate token, expire timestamp, and signature
        auth_params = imagekit.get_authentication_parameters()
        return jsonify(
            {
                "success": True,
                "token": auth_params["token"],
                "expire": auth_params["expire"],
                "signature": auth_params["signature"]
            }
        ), 200

    except Exception as e:
        print(f"Auth Param Generation Error: {e}")
        return (
            jsonify({"success": False, "error": "Failed to generate auth params"}),
            500,
        )


# 2. Save metadata after client confirms successful upload to ImageKit
@app.route("/save-metadata", methods=["POST"])
def save_metadata_route():
    conn = None
    cursor = None
    try:
        user_id = get_authenticated_user_id(request)
        if not user_id:
            return jsonify({"success": False, "error": "Unauthorized"}), 401

        data = request.get_json()
        file_id = data.get("fileId")
        url = data.get("url")

        if not file_id or not url:
            raise ValueError("fileId and url are required from ImageKit response")

        # Insert metadata into Neon database
        conn = get_db_connection()
        cursor = conn.cursor()
        cursor.execute(
            """
            INSERT INTO imagekit_files (file_id, file_url, user_id)
            VALUES (%s, %s, %s)
            """,
            (file_id, url, user_id),
        )
        conn.commit()
        print(f"Metadata saved for ImageKit file: {file_id}")
        return jsonify({"success": True}), 201

    except (psycopg2.Error, ValueError) as e:
        print(f"Metadata Save Error: {e}")
        return (
            jsonify({"success": False, "error": "Failed to save metadata"}),
            500,
        )
    except Exception as e:
        print(f"Unexpected Metadata Save Error: {e}")
        return jsonify({"success": False, "error": "Server error"}), 500
    finally:
        if cursor:
            cursor.close()
        if conn:
            conn.close()


if __name__ == "__main__":
    app.run(port=3000, debug=True)
```

**Explanation**

1. **Setup:** Initializes the Flask web framework (`app`), the PostgreSQL client function (`get_db_connection`) for Lakebase Postgres, and the ImageKit Python SDK (`imagekit`) using environment variables.
2. **Authentication:** Includes a placeholder `get_authenticated_user_id` function. **Replace this with your actual user authentication logic.**
3. **API endpoints:**
   - **`/generate-auth-params` (GET):** Uses the ImageKit SDK's `get_authentication_parameters()` method to create `token`, `expire`, and `signature`. These are returned to the client, usually as JSON.
   - **`/save-metadata` (POST):** Called by the client _after_ it has successfully uploaded a file directly to ImageKit. The client provides the metadata returned by ImageKit. The backend validates the required fields and inserts the data along with the `userId` into the `imagekit_files` table in Lakebase Postgres using `psycopg2`.
4. **Database Connection:** The example shows creating a new connection per request. In production, use a global connection pool for better performance.

## Testing the upload workflow

This workflow involves getting authentication parameters from your backend, using those parameters to upload the file directly to ImageKit via `curl`, and then notifying your backend to save the metadata.

1. **Get authentication parameters:** Send a `GET` request to your backend's `/generate-auth-params` endpoint.

   ```bash
   curl -X GET http://localhost:3000/generate-auth-params
   ```

   **Expected response:** A JSON object containing the necessary parameters. For example:

   ```json
   {
     "success": true,
     "token": "20xxxx-xxxx-xxxx-a350-a463b3dd544e",
     "expire": 1745435716,
     "signature": "ffxxxxxx5f19b6a22e2bd6bd90ae8a7db21"
   }
   ```

2. **Upload file directly to ImageKit:** Use the parameters obtained in Step 1, your **ImageKit Public Key**, and the file path to send a `POST` request with `multipart/form-data` directly to the ImageKit Upload API.

   ```bash
   curl -X POST https://upload.imagekit.io/api/v1/files/upload \
        -F "file=@/path/to/your/test-image.png" \
        -F "publicKey=<YOUR_IMAGEKIT_PUBLIC_KEY>" \
        -F "token=<TOKEN_FROM_STEP_1>" \
        -F "expire=<EXPIRE_FROM_STEP_1>" \
        -F "signature=<SIGNATURE_FROM_STEP_1>" \
        -F "fileName=test-image.png" \
        -F "useUniqueFileName=true"
   ```

   **Expected response (from ImageKit):** A successful upload returns a JSON object with details about the uploaded file. Note the `fileId`, `url`, etc.

   ```json
   {
       "fileId": "<YOUR_FILE_ID>",
       "name": "<YOUR_FILE_NAME>",
       "size": "<YOUR_FILE_SIZE>",
       "versionInfo": {
           "id": "<YOUR_FILE_ID>",
           "name": "Version 1"
       },
       "filePath": "<YOUR_FILE_PATH>",
       "url": "https://ik.imagekit.io/<YOUR_INSTANCE_ID>/<YOUR_FILE_PATH>",
       "fileType": "image",
       "height": <YOUR_FILE_HEIGHT>,
       "width": <YOUR_FILE_WIDTH>,
       "thumbnailUrl": "https://ik.imagekit.io/<YOUR_INSTANCE_ID>/tr:n-ik_ml_thumbnail/<YOUR_FILE_PATH>",
       "AITags": null
   }
   ```

3. **Save metadata:** Send a `POST` request to your backend's `/save-metadata` endpoint, providing the key details (like `fileId`, `url`) received from ImageKit in Step 2.

   ```bash
   curl -X POST http://localhost:3000/save-metadata \
        -H "Content-Type: application/json" \
        -d '{
             "fileId": "<FILE_ID_FROM_STEP_2>",
             "url": "<URL_FROM_STEP_2>"
           }'
   ```

   **Expected response (from your backend):**

   ```json
   { "success": true }
   ```

**Expected outcome:**

- The file is successfully uploaded to your ImageKit Media Library.
- You can verify a new row corresponding to the uploaded file exists in your `imagekit_files` table in Lakebase Postgres.

## Accessing file metadata and files

With metadata stored in Lakebase Postgres, your application can easily retrieve references to the media hosted on ImageKit.io.

Query the `imagekit_files` table from your application's backend whenever you need to display or link to uploaded files.

**Example SQL query:**

Retrieve files associated with a specific user:

```sql
SELECT
    id,             -- Your database primary key
    file_id,        -- ImageKit File ID
    file_url,       -- Base ImageKit CDN URL for the file
    user_id,
    upload_timestamp
FROM
    imagekit_files
WHERE
    user_id = 'user_123'; -- Use the actual authenticated user ID
```

**Using the data:**

- The query returns rows containing the file metadata stored in Neon.
- The `file_url` is the direct link to the file on ImageKit's CDN. You can use this directly in `<img>` tags, video players, or links.
- **ImageKit transformations:** A key benefit of ImageKit is real-time manipulation. You can append transformation parameters directly to the `file_url` to resize, crop, format, or optimize the media on-the-fly. For example, `file_url + '?tr=w-300,h-200'` would resize an image to 300x200 pixels. Learn more on [ImageKit transformation docs](https://imagekit.io/docs/image-transformation) for possibilities.

This pattern separates media storage, optimization, and delivery (handled by ImageKit.io) from structured metadata management (handled by Lakebase Postgres).

## Resources

- [ImageKit.io documentation](https://imagekit.io/docs)
- [ImageKit.io Upload API](https://imagekit.io/docs/api-reference/upload-file/upload-file)

--- [Document source](https://neon.com/docs/guides/integrations.md) ---

> Summary: Index of Neon integration guides organized by category: authentication, deployment, schema migration, replication, monitoring, and serverless. Use this page to find setup instructions for connecting Neon to a specific platform or tool.

# Neon integration guides

Find detailed instructions for integration across various platforms and services.

Last updated: 2026-10-21

## Authentication

- [Auth0](https://neon.com/docs/guides/auth-auth0): Authenticate Lakebase Postgres application users with Auth0
- [Auth.js](https://neon.com/docs/guides/auth-authjs): Authenticate Lakebase Postgres application users with Auth.js
- [Clerk](https://neon.com/docs/guides/auth-clerk): Authenticate Lakebase Postgres application users with Clerk
- [Okta](https://neon.com/docs/guides/auth-okta): Authenticate Lakebase Postgres application users with Okta

## Deploy

- [Cloudflare Pages](https://neon.com/docs/guides/cloudflare-pages): Use Neon with Cloudflare Pages
- [Cloudflare Workers](https://neon.com/docs/guides/cloudflare-workers): Use Neon with Cloudflare Workers
- [Heroku](https://neon.com/docs/guides/heroku): Deploy Your App with Neon on Heroku
- [Koyeb](https://neon.com/docs/guides/koyeb): Use Neon with Koyeb
- [Netlify Functions](https://neon.com/docs/guides/netlify-functions): Connect a Lakebase Postgres database to your Netlify Functions application
- [Railway](https://neon.com/docs/guides/railway): Use Neon with Railway
- [Render](https://neon.com/docs/guides/render): Use Neon with Render
- [Vercel](https://neon.com/docs/guides/vercel-overview): Learn how to integrate Neon with Vercel

## Develop

- [Convex](https://neon.com/guides/convex-neon): Integrate Convex with Neon
- [GitHub integration](https://neon.com/docs/guides/neon-github-app): Use the Neon GitHub integration
- [Knex](https://neon.com/docs/guides/knex): Connect from Knex to Neon
- [Prisma](https://neon.com/docs/guides/prisma): Connect from Prisma to Neon
- [TypeORM](https://neon.com/docs/guides/typeorm): Connect from TypeORM to Neon

## File & media storage

- [File storage](https://neon.com/docs/guides/file-storage): Integrate file storage with Neon
- [AWS S3](https://neon.com/docs/guides/aws-s3): Integrate AWS S3 with Neon
- [Azure Blob Storage](https://neon.com/docs/guides/azure-blob-storage): Integrate Azure Blob Storage with Neon
- [Backblaze B2](https://neon.com/docs/guides/backblaze-b2): Integrate Backblaze B2 with Neon
- [Cloudflare R2](https://neon.com/docs/guides/cloudflare-r2): Integrate Cloudflare R2 with Neon
- [Cloudinary](https://neon.com/docs/guides/cloudinary): Integrate Cloudinary with Neon
- [ImageKit](https://neon.com/docs/guides/imagekit): Integrate ImageKit with Neon
- [Uploadcare](https://neon.com/docs/guides/uploadcare): Integrate Uploadcare with Neon

## Monitor

- [Datadog](https://neon.com/docs/guides/datadog): Send metrics and events from Neon to Datadog
- [Grafana Cloud](https://neon.com/docs/guides/grafana-cloud): Send metrics and logs from Neon to Grafana Cloud
- [OpenTelemetry](https://neon.com/docs/guides/opentelemetry): Send metrics and events from Neon to any OpenTelemetry compatible backend

## Query

- [Ask Your Database](https://neon.com/docs/guides/askyourdatabase): Chat with your Lakebase Postgres database with AskYourDatabase
- [Cloudflare Hyperdrive](https://neon.com/docs/guides/cloudflare-hyperdrive): Use Neon with Cloudflare Hyperdrive
- [Draxlr](https://neon.com/docs/guides/draxlr): Connect Draxlr to Neon
- [Exograph](https://neon.com/docs/guides/exograph): Use Exograph with Neon
- [Hasura](https://neon.com/docs/guides/hasura): Connect from Hasura Cloud to Neon
- [PostgREST](https://neon.com/docs/guides/postgrest): Create a REST API from your Neon database

## Replicate from Neon

- [Airbyte](https://neon.com/docs/guides/logical-replication-airbyte): Replicate data from Neon with Airbyte
- [ClickHouse](https://neon.com/docs/guides/logical-replication-clickhouse): Replicate data from Neon to ClickHouse using ClickPipes
- [Confluent (Kafka)](https://neon.com/docs/guides/logical-replication-kafka-confluent): Replicate data from Neon with Confluent (Kafka)
- [Databricks](https://neon.com/docs/guides/logical-replication-databricks): Replicate data from Neon to Databricks with Lakeflow Connect
- [Decodable](https://neon.com/docs/guides/logical-replication-decodable): Replicate data from Neon with Decodable
- [Estuary](https://neon.com/docs/guides/logical-replication-estuary-flow): Replicate data from Neon with Estuary
- [Fivetran](https://neon.com/docs/guides/logical-replication-fivetran): Replicate data from Neon with Fivetran
- [Inngest](https://neon.com/docs/guides/logical-replication-inngest): Replicate data from Neon to Inngest
- [Materialize](https://neon.com/docs/guides/logical-replication-materialize): Replicate data from Neon to Materialize
- [Neon to Lakebase](https://neon.com/docs/guides/logical-replication-neon-to-lakebase): Replicate data from Neon to Lakebase Postgres on Databricks
- [Neon to Neon](https://neon.com/docs/guides/logical-replication-neon-to-neon): Replicate data from Neon to Neon
- [Neon to PostgreSQL](https://neon.com/docs/guides/logical-replication-postgres): Replicate data from Neon to PostgreSQL
- [Snowflake](https://neon.com/docs/guides/logical-replication-airbyte-snowflake): Replicate data from Neon to Snowflake with Airbyte
- [Stacksync](https://neon.com/docs/guides/logical-replication-stacksync): Replicate data from Neon with Stacksync

## Replicate to Neon

- [AlloyDB](https://neon.com/docs/guides/logical-replication-alloydb): Replicate data from AlloyDB to Neon
- [AWS RDS](https://neon.com/docs/guides/logical-replication-rds-to-neon): Replicate data from AWS RDS PostgreSQL to Neon
- [Cloud SQL](https://neon.com/docs/guides/logical-replication-cloud-sql): Replicate data from Cloud SQL to Neon
- [Lakebase to Neon](https://neon.com/docs/guides/logical-replication-lakebase-to-neon): Replicate data from Lakebase Postgres on Databricks to Neon
- [Neon to Neon](https://neon.com/docs/guides/logical-replication-neon-to-neon): Replicate data from Neon to Neon
- [PostgreSQL to Neon](https://neon.com/docs/guides/logical-replication-postgres-to-neon): Replicate data from PostgreSQL to Neon
- [Replicate from Azure](https://neon.com/docs/import/migrate-from-azure-postgres): Replicate data from Azure to Neon
- [Replicate from Supabase](https://neon.com/docs/guides/logical-replication-supabase-to-neon): Replicate data from Supabase to Neon

## Schema Migration

- [Django](https://neon.com/docs/guides/django-migrations): Connect a Django application to Neon
- [Drizzle](https://neon.com/docs/guides/drizzle-migrations): Schema migration with Lakebase Postgres and Drizzle ORM
- [Entity Framework](https://neon.com/docs/guides/entity-migrations): Schema migration with Neon and Entity Framework
- [Flyway](https://neon.com/docs/guides/flyway): Use Flyway with Neon
- [Laravel](https://neon.com/docs/guides/laravel): Connect from Laravel to Neon
- [Liquibase](https://neon.com/docs/guides/liquibase): Use Liquibase with Neon
- [Prisma](https://neon.com/docs/guides/prisma-migrations): Schema migration with Lakebase Postgres and Prisma ORM
- [Rails](https://neon.com/docs/guides/rails-migrations): Connect a Rails application to Neon
- [Sequelize](https://neon.com/docs/guides/sequelize): Schema migration with Lakebase Postgres and Sequelize
- [SQLAlchemy](https://neon.com/docs/guides/sqlalchemy): Connect an SQLAlchemy application to Neon

## Serverless

- [AWS Lambda](https://neon.com/docs/guides/aws-lambda): Connect from AWS Lambda to Neon
- [Azure Functions](https://neon.com/guides/query-postgres-azure-functions): Connect from Azure Functions to Neon
- [Neon](https://neon.com/docs/serverless/serverless-driver): Connect with the Neon serverless driver

--- [Document source](https://neon.com/docs/guides/java.md) ---

> Summary: Connect a Java application to Lakebase Postgres using the Postgres JDBC driver (pgJDBC) with Apache Maven. Covers complete CRUD examples including PreparedStatement inserts, batch operations, and transaction control with setAutoCommit, commit, and rollback. Also covers dotenv-java for credential management. Focuses on raw JDBC without an ORM, unlike Spring Boot or Hibernate guides.

# Connect a Java application to Lakebase Postgres

Learn how to run SQL queries in Neon from Java using the Postgres JDBC driver

Last updated: 2026-10-09

Pre-built prompt for connecting Java applications to Neon [View prompt](https://neon.com/prompts/java-prompt.md)

This guide describes how to create a Neon project and connect to it from a Java application using **Java Database Connectivity (JDBC)**, Java's standard API for relational databases, and the Postgres JDBC driver ([pgJDBC](https://jdbc.postgresql.org)).

You will learn how to set up a project, connect to your database, and perform basic create, read, update, and delete (CRUD) operations.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://console.neon.tech/signup).
- [Java Development Kit (JDK) 17](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html) or later.
- [Apache Maven](https://maven.apache.org/install.html) to manage project dependencies.

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Your project is created with a ready-to-use database named `neondb`. In the following steps, you will connect to this database from your Java application.

## Create a Java project

Create a project using the Maven `archetype:generate` command. This sets up a standard Java project structure.

1. Run the following command in your terminal to generate a new Maven project. This command creates a simple Java project with the `maven-archetype-quickstart` archetype.

   ```bash
   mvn archetype:generate \
       -DarchetypeGroupId=org.apache.maven.archetypes \
       -DarchetypeArtifactId=maven-archetype-quickstart \
       -DarchetypeVersion=1.5 \
       -DgroupId=com.neon.quickstart \
       -DartifactId=neon-java-jdbc \
       -DinteractiveMode=false
   ```

2. Change into the newly created project directory.

   ```bash
   cd neon-java-jdbc
   ```

   > Open this directory in your preferred code editor (for example, VS Code, IntelliJ IDEA).

3. Add the `postgresql` driver and `dotenv-java` libraries to your `pom.xml` file. The generated `pom.xml` already has a `<dependencies>` section with JUnit dependencies. Add these two `<dependency>` elements inside that existing section. Don't add a second `<dependencies>` section: Maven fails with `Duplicated tag: 'dependencies'`.

   ```xml filename="pom.xml"
   <dependency>
     <groupId>org.postgresql</groupId>
     <artifactId>postgresql</artifactId>
     <version>42.7.14</version>
   </dependency>
   <dependency>
     <groupId>io.github.cdimascio</groupId>
     <artifactId>dotenv-java</artifactId>
     <version>3.2.0</version>
   </dependency>
   ```

   **Note: Note**

   The generated `pom.xml` also has a `<dependencies>` section inside `<dependencyManagement>`. Don't add the libraries there: `<dependencyManagement>` only declares versions and doesn't include the libraries in your build.

   Save the file.

4. Compile the project to download the dependencies.

   ```bash
   mvn clean compile
   ```

   This command compiles your Java code and downloads the required dependencies specified in `pom.xml`.

## Store your Neon connection string

Create a file named `.env` in your project's root directory. This file stores your database connection string. Don't commit it to source control.

1. In the [Neon Console](https://console.neon.tech), open your project.
2. Click **Connect** in the Console nav to open the **Connect to your branch** modal.
3. Select **Java** as your programming language.
   ![Connection modal](https://neon.com/docs/connect/java_connection_details.png)
4. Copy the connection string, which includes your password.
5. Create a file named `.env` in your project's root directory and add the connection string to it as shown below:

   ```text filename=".env"
   DATABASE_URL="jdbc:postgresql://[neon_hostname]/[dbname]?user=[user]&password=[password]&sslmode=require&channelBinding=require"
   ```

   > Replace `[user]`, `[password]`, `[neon_hostname]`, and `[dbname]` with your actual database credentials. If you start from a `postgresql://` connection string, move the user and password into the `user` and `password` parameters, add the `jdbc:` prefix, and write `channel_binding=require` as `channelBinding=require`.

## Examples

This section provides code examples for performing CRUD operations. The examples should be placed inside `src/main/java/com/neon/quickstart/`.

### Create a table and insert data

Create a file named `CreateTable.java`. This class connects to your database, creates a table, and inserts data.

```java filename="src/main/java/com/neon/quickstart/CreateTable.java"
package com.neon.quickstart;

import io.github.cdimascio.dotenv.Dotenv;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.Statement;

public class CreateTable {

    public static void main(String[] args) {
        Dotenv dotenv = Dotenv.load();
        String connString = dotenv.get("DATABASE_URL");

        try (Connection conn = DriverManager.getConnection(connString)) {
            System.out.println("Connection established");

            try (Statement stmt = conn.createStatement()) {
                // Drop the table if it already exists
                stmt.execute("DROP TABLE IF EXISTS books;");
                System.out.println("Finished dropping table (if it existed).");

                // Create a new table
                stmt.execute("""
                    CREATE TABLE books (
                        id SERIAL PRIMARY KEY,
                        title VARCHAR(255) NOT NULL,
                        author VARCHAR(255),
                        publication_year INT,
                        in_stock BOOLEAN DEFAULT TRUE
                    );
                """);
                System.out.println("Finished creating table.");

                // Insert a single book record
                String insertOneSql = "INSERT INTO books (title, author, publication_year, in_stock) VALUES (?, ?, ?, ?);";
                try (PreparedStatement pstmt = conn.prepareStatement(insertOneSql)) {
                    pstmt.setString(1, "The Catcher in the Rye");
                    pstmt.setString(2, "J.D. Salinger");
                    pstmt.setInt(3, 1951);
                    pstmt.setBoolean(4, true);
                    pstmt.executeUpdate();
                    System.out.println("Inserted a single book.");
                }

                // Insert multiple books
                String insertManySql = "INSERT INTO books (title, author, publication_year, in_stock) VALUES (?, ?, ?, ?);";
                try (PreparedStatement pstmt = conn.prepareStatement(insertManySql)) {
                    Object[][] booksToInsert = {
                        {"The Hobbit", "J.R.R. Tolkien", 1937, true},
                        {"1984", "George Orwell", 1949, true},
                        {"Dune", "Frank Herbert", 1965, false}
                    };

                    for (Object[] book : booksToInsert) {
                        pstmt.setString(1, (String) book[0]);
                        pstmt.setString(2, (String) book[1]);
                        pstmt.setInt(3, (Integer) book[2]);
                        pstmt.setBoolean(4, (Boolean) book[3]);
                        pstmt.addBatch();
                    }
                    pstmt.executeBatch();
                    System.out.println("Inserted 3 rows of data.");
                }
            }
        } catch (Exception e) {
            System.out.println("Connection failed.");
            e.printStackTrace();
        }
    }
}
```

The above code does the following:

- Connects to the Neon database using the connection string from the `.env` file.
- Drops the `books` table if it already exists.
- Creates a new `books` table with columns for `id`, `title`, `author`, `publication_year`, and `in_stock`.
- Inserts a single book record.
- Inserts multiple book records in a batch operation.

Run the code to create the table and insert the data using the following command:

```bash
mvn exec:java -Dexec.mainClass="com.neon.quickstart.CreateTable"
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established
Finished dropping table (if it existed).
Finished creating table.
Inserted a single book.
Inserted 3 rows of data.
```

### Read data

Create a file named `ReadData.java`. This class fetches all rows from the `books` table and prints them.

```java filename="src/main/java/com/neon/quickstart/ReadData.java"
package com.neon.quickstart;

import io.github.cdimascio.dotenv.Dotenv;
import java.sql.*;

public class ReadData {
    public static void main(String[] args) {
        Dotenv dotenv = Dotenv.load();
        String connString = dotenv.get("DATABASE_URL");

        try (Connection conn = DriverManager.getConnection(connString);
             Statement stmt = conn.createStatement()) {
            System.out.println("Connection established");
            String sql = "SELECT * FROM books ORDER BY publication_year;";
            try (ResultSet rs = stmt.executeQuery(sql)) {
                System.out.println("\n--- Book Library ---");
                while (rs.next()) {
                    System.out.printf("ID: %d, Title: %s, Author: %s, Year: %d, In Stock: %b%n",
                            rs.getInt("id"), rs.getString("title"), rs.getString("author"),
                            rs.getInt("publication_year"), rs.getBoolean("in_stock"));
                }
                System.out.println("--------------------\n");
            }
        } catch (Exception e) {
            System.out.println("Connection failed.");
            e.printStackTrace();
        }
    }
}
```

The above code does the following:

- Connects to the Neon database using the connection string from the `.env` file.
- Executes a SQL query to select all rows from the `books` table, ordered by `publication_year`.
- Iterates through the result set and prints each book's details.

Run the code to read the data using the following command:

```bash
mvn exec:java -Dexec.mainClass="com.neon.quickstart.ReadData"
```

When the read logic runs, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: false
--------------------
```

### Update data

Create a file named `UpdateData.java` to update the stock status of 'Dune' to `true`.

```java filename="src/main/java/com/neon/quickstart/UpdateData.java"
package com.neon.quickstart;

import io.github.cdimascio.dotenv.Dotenv;
import java.sql.*;

public class UpdateData {
    public static void main(String[] args) {
        Dotenv dotenv = Dotenv.load();
        String connString = dotenv.get("DATABASE_URL");
        String sql = "UPDATE books SET in_stock = ? WHERE title = ?;";

        try (Connection conn = DriverManager.getConnection(connString);
             PreparedStatement pstmt = conn.prepareStatement(sql)) {
            System.out.println("Connection established");
            pstmt.setBoolean(1, true);
            pstmt.setString(2, "Dune");
            int rowsAffected = pstmt.executeUpdate();
            if (rowsAffected > 0) {
                System.out.println("Updated stock status for 'Dune'.");
            }
        } catch (Exception e) {
            System.out.println("Connection failed.");
            e.printStackTrace();
        }
    }
}
```

The above code does the following:

- Connects to the Lakebase Postgres database.
- Prepares an SQL `UPDATE` statement to set the `in_stock` status of the book 'Dune' to `true`.
- Executes the update and prints a confirmation message if successful.

Run the code to update the data using the following command:

```bash
mvn exec:java -Dexec.mainClass="com.neon.quickstart.UpdateData"
```

After running the update, verify the change by running the `ReadData` class again.

```bash
mvn exec:java -Dexec.mainClass="com.neon.quickstart.ReadData"
```

The updated output will be:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the stock status for 'Dune' has been updated to `true`.

### Delete data

Create a file named `DeleteData.java` to delete the book '1984' from the table.

```java filename="src/main/java/com/neon/quickstart/DeleteData.java"
package com.neon.quickstart;

import io.github.cdimascio.dotenv.Dotenv;
import java.sql.*;

public class DeleteData {
    public static void main(String[] args) {
        Dotenv dotenv = Dotenv.load();
        String connString = dotenv.get("DATABASE_URL");
        String sql = "DELETE FROM books WHERE title = ?;";

        try (Connection conn = DriverManager.getConnection(connString);
             PreparedStatement pstmt = conn.prepareStatement(sql)) {
            System.out.println("Connection established");
            pstmt.setString(1, "1984");
            int rowsAffected = pstmt.executeUpdate();
            if (rowsAffected > 0) {
                System.out.println("Deleted the book '1984' from the table.");
            }
        } catch (Exception e) {
            System.out.println("Connection failed.");
            e.printStackTrace();
        }
    }
}
```

The above code does the following:

- Connects to the Lakebase Postgres database.
- Prepares an SQL `DELETE` statement to remove the book '1984'.
- Executes the delete and prints a confirmation message if successful.

Run the code to delete the data using the following command:

```bash
mvn exec:java -Dexec.mainClass="com.neon.quickstart.DeleteData"
```

After running the delete, verify the change by running the `ReadData` class again.

```bash
mvn exec:java -Dexec.mainClass="com.neon.quickstart.ReadData"
```

The final output will be:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the book '1984' has been successfully deleted from the `books` table.

### Using transactions

The examples above execute each operation independently. For production code where multiple operations must succeed or fail together, wrap them in a transaction. Use `setAutoCommit(false)` to start a transaction, `commit()` on success, and `rollback()` in the catch block on failure.

```java filename="src/main/java/com/neon/quickstart/TransactionExample.java"
package com.neon.quickstart;

import io.github.cdimascio.dotenv.Dotenv;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.SQLException;

public class TransactionExample {
    public static void main(String[] args) {
        Dotenv dotenv = Dotenv.load();
        String connString = dotenv.get("DATABASE_URL");

        Connection conn = null;
        try {
            conn = DriverManager.getConnection(connString);
            conn.setAutoCommit(false); // Begin transaction

            // Insert
            try (PreparedStatement pstmt = conn.prepareStatement(
                    "INSERT INTO books (title, author, publication_year) VALUES (?, ?, ?)")) {
                pstmt.setString(1, "Brave New World");
                pstmt.setString(2, "Aldous Huxley");
                pstmt.setInt(3, 1932);
                pstmt.executeUpdate();
                System.out.println("Inserted book.");
            }

            // Update
            try (PreparedStatement pstmt = conn.prepareStatement(
                    "UPDATE books SET in_stock = ? WHERE title = ?")) {
                pstmt.setBoolean(1, false);
                pstmt.setString(2, "Brave New World");
                pstmt.executeUpdate();
                System.out.println("Updated stock status.");
            }

            conn.commit(); // Commit transaction
            System.out.println("Transaction committed successfully.");

        } catch (SQLException e) {
            System.err.println("Transaction failed. Rolling back.");
            if (conn != null) {
                try {
                    conn.rollback();
                } catch (SQLException ex) {
                    ex.printStackTrace();
                }
            }
            e.printStackTrace();
        } finally {
            if (conn != null) {
                try {
                    conn.close();
                } catch (SQLException e) {
                    e.printStackTrace();
                }
            }
        }
    }
}
```

Run with:

```bash
mvn exec:java -Dexec.mainClass="com.neon.quickstart.TransactionExample"
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Inserted book.
Updated stock status.
Transaction committed successfully.
```

Run `ReadData` again to see the new row: `Brave New World` by Aldous Huxley, with `In Stock: false`.

<details>

<summary>**Notes for AI-assisted setup**</summary>

- Always use `PreparedStatement` (with `?` placeholders) for INSERT, UPDATE, and DELETE operations. Do not use `Statement` for queries with user-provided data, as this is vulnerable to SQL injection.
- Add dependencies to the `<dependencies>` section of `pom.xml`, not `<dependencyManagement>`. The `<dependencyManagement>` section declares versions but does not include libraries in the build.
- Wrap related database operations in a transaction (`setAutoCommit(false)` / `commit()` / `rollback()`). Always call `rollback()` in a catch block to ensure atomicity on failure.
- Close JDBC connections and statements using `try-with-resources` or explicit `finally` blocks to prevent connection leaks.
- Do not hardcode credentials in `.java` files. Use environment variables via `dotenv-java`. For more information, see [Security overview](https://neon.com/docs/security/security-overview).

</details>

## Use an ORM or framework

This guide uses raw SQL through JDBC. An Object-Relational Mapping (ORM) framework such as Hibernate lets you work with rows as Java objects, and migration tools keep your schema in sync with your models.

To use an ORM or framework with Neon, see:

- [Database Schema Changes with Hibernate, Spring Boot, and Neon](https://neon.com/guides/spring-boot-hibernate)

## Neon backend services

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Resources

- [pgJDBC documentation](https://jdbc.postgresql.org/documentation/use/)
- [Apache Maven Quickstart](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html)
- [Database Migrations in Spring Boot with Flyway and Neon](https://neon.com/guides/spring-boot-flyway)

--- [Document source](https://neon.com/docs/guides/javascript.md) ---

> Summary: Connect a Node.js application to Lakebase Postgres using node-postgres (pg), Postgres.js, or the Neon serverless driver (@neondatabase/serverless). Each driver section includes working CRUD examples covering table creation, insert, select, update, and delete. The Neon serverless driver connects over HTTP and suits serverless and edge runtimes. Bun users are directed to a separate guide.

# Connect a JavaScript/Node.js application to Lakebase Postgres

Learn how to run SQL queries in Neon from JavaScript using pg, postgres.js, or the Neon serverless driver

Last updated: 2026-10-14

Pre-built prompt for connecting JavaScript applications to Neon [View prompt](https://neon.com/prompts/javascript-prompt.md)

This guide describes how to create a Neon project and connect to it from a Node.js application using popular Postgres clients:

- **[node-postgres (pg)](https://www.npmjs.com/package/pg)**: The most widely used Postgres driver for Node.js.
- **[Postgres.js](https://www.npmjs.com/package/postgres)**: A Postgres driver with a tagged-template query API.
- **[@neondatabase/serverless](https://www.npmjs.com/package/@neondatabase/serverless)**: The Neon serverless driver, which connects over HTTP and is designed for serverless and edge environments.

You'll learn how to connect to your Lakebase Postgres database from a JavaScript application and perform basic Create, Read, Update, and Delete (CRUD) operations.

**Important: Connect from the server side only**

Your database connection string contains sensitive credentials and must **never** be exposed in client-side JavaScript code (for example, in a browser). All database operations should be handled in a secure, server-side environment like a Node.js backend or a serverless function.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://console.neon.tech/signup).
- [Node.js](https://nodejs.org/) v20 or later.

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Your project is created with a ready-to-use database named `neondb`. In the following steps, you will connect to this Lakebase Postgres database from your JavaScript application.

## Create a Node.js project

For your Node.js project, create a project directory, initialize it with `npm`, and install the required libraries.

1. Create a project directory and change into it.

   ```bash
   mkdir neon-nodejs-quickstart
   cd neon-nodejs-quickstart
   ```

   > Open the directory in your preferred code editor (for example, VS Code).

2. Initialize a new Node.js project. The `-y` flag accepts all the default settings.

   ```bash
   npm init -y
   ```

3. Install the required libraries using `npm`.

   **node-postgres (pg)**

   ```bash title="Install node-postgres (pg)"
   npm install pg dotenv
   ```

   **Neon serverless driver**

   ```bash title="Install Neon serverless driver"
   npm install @neondatabase/serverless dotenv
   ```

   **postgres.js**

   ```bash title="Install postgres.js"
   npm install postgres dotenv
   ```

4. Set your project to use ES modules:

   ```bash
   npm pkg set type=module
   ```

   This sets `"type": "module"` in `package.json` (replacing the `"type": "commonjs"` that recent versions of `npm init` add), so you can use ES module syntax (`import`) in your JavaScript files.

## Store your Neon connection string

Create a file named `.env` in your project's root directory. This file will securely store your database connection string, keeping your credentials separate from your source code.

1. In the [Neon Console](https://console.neon.tech), open your project.
2. Click **Connect** in the Console nav to open the **Connect to your branch** modal.
   ![Connection modal](https://neon.com/docs/connect/connect_to_branch_modal.png)
3. Select **Node.js** from the connection string dropdown and copy the full connection string.
4. Add the connection string to your `.env` file as shown below.
   ```text
   DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
   ```
   > Replace `[user]`, `[password]`, `[neon_hostname]`, and `[dbname]` with your actual database credentials.

**Note:** `pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. If you use node-postgres, change `sslmode=require` to `sslmode=verify-full` in your connection string to keep the current behavior and remove the warning.

## Examples

This section provides example JavaScript scripts that demonstrate how to connect to your Neon database and perform basic operations such as [creating a table](https://neon.com/docs/guides/javascript#create-a-table-and-insert-data), [reading data](https://neon.com/docs/guides/javascript#read-data), [updating data](https://neon.com/docs/guides/javascript#update-data), and [deleting data](https://neon.com/docs/guides/javascript#delete-data).

### Create a table and insert data

In your project directory, create a file named `create_table.js` and add the code for your preferred library. This script connects to your Neon database, creates a table named `books`, and inserts some sample data into it.

**node-postgres (pg)**

```javascript title="create_table.js"
import 'dotenv/config';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

async function setup() {
  const client = await pool.connect();
  try {
    console.log('Connection established');

    // Drop the table if it already exists
    await client.query('DROP TABLE IF EXISTS books;');
    console.log('Finished dropping table (if it existed).');

    // Create a new table
    await client.query(`
      CREATE TABLE books (
          id SERIAL PRIMARY KEY,
          title VARCHAR(255) NOT NULL,
          author VARCHAR(255),
          publication_year INT,
          in_stock BOOLEAN DEFAULT TRUE
      );
    `);
    console.log('Finished creating table.');

    // Insert a single book record
    await client.query(
      'INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4);',
      ['The Catcher in the Rye', 'J.D. Salinger', 1951, true]
    );
    console.log('Inserted a single book.');

    // Data to be inserted
    const booksToInsert = [
      { title: 'The Hobbit', author: 'J.R.R. Tolkien', year: 1937, in_stock: true },
      { title: '1984', author: 'George Orwell', year: 1949, in_stock: true },
      { title: 'Dune', author: 'Frank Herbert', year: 1965, in_stock: false },
    ];

    // Insert multiple books
    for (const book of booksToInsert) {
      await client.query(
        'INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4);',
        [book.title, book.author, book.year, book.in_stock]
      );
    }
    console.log('Inserted 3 rows of data.');
  } catch (err) {
    console.error('Connection failed.', err.stack);
  } finally {
    client.release();
    pool.end();
  }
}

setup();
```

**Neon serverless driver**

```javascript title="create_table.js"
import 'dotenv/config';
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL);

async function setup() {
  try {
    console.log('Connection established');

    // Drop the table if it already exists
    await sql`DROP TABLE IF EXISTS books;`;
    console.log('Finished dropping table (if it existed).');

    // Create a new table
    await sql`
      CREATE TABLE books (
        id SERIAL PRIMARY KEY,
        title VARCHAR(255) NOT NULL,
        author VARCHAR(255),
        publication_year INT,
        in_stock BOOLEAN DEFAULT TRUE
      );
    `;
    console.log('Finished creating table.');

    // Insert a single book record
    await sql`
      INSERT INTO books (title, author, publication_year, in_stock)
      VALUES ('The Catcher in the Rye', 'J.D. Salinger', 1951, true);
    `;
    console.log('Inserted a single book.');

    // Data to be inserted
    const booksToInsert = [
      { title: 'The Hobbit', author: 'J.R.R. Tolkien', publication_year: 1937, in_stock: true },
      { title: '1984', author: 'George Orwell', publication_year: 1949, in_stock: true },
      { title: 'Dune', author: 'Frank Herbert', publication_year: 1965, in_stock: false },
    ];

    // Insert multiple books
    await sql`
      INSERT INTO books (title, author, publication_year, in_stock)
      VALUES (${booksToInsert[0].title}, ${booksToInsert[0].author}, ${booksToInsert[0].publication_year}, ${booksToInsert[0].in_stock}),
             (${booksToInsert[1].title}, ${booksToInsert[1].author}, ${booksToInsert[1].publication_year}, ${booksToInsert[1].in_stock}),
             (${booksToInsert[2].title}, ${booksToInsert[2].author}, ${booksToInsert[2].publication_year}, ${booksToInsert[2].in_stock});
    `;
    console.log('Inserted 3 rows of data.');
  } catch (err) {
    console.error('Connection failed.', err);
  }
}

setup();
```

**postgres.js**

```javascript title="create_table.js"
import 'dotenv/config';
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL, {
  ssl: 'require',
});

async function setup() {
  try {
    console.log('Connection established');

    // Drop the table if it already exists
    await sql`DROP TABLE IF EXISTS books;`;
    console.log('Finished dropping table (if it existed).');

    // Create a new table
    await sql`
      CREATE TABLE books (
        id SERIAL PRIMARY KEY,
        title VARCHAR(255) NOT NULL,
        author VARCHAR(255),
        publication_year INT,
        in_stock BOOLEAN DEFAULT TRUE
      );
    `;
    console.log('Finished creating table.');

    // Insert a single book record
    await sql`
      INSERT INTO books (title, author, publication_year, in_stock)
      VALUES ('The Catcher in the Rye', 'J.D. Salinger', 1951, true);
    `;
    console.log('Inserted a single book.');

    // Data to be inserted
    const booksToInsert = [
      { title: 'The Hobbit', author: 'J.R.R. Tolkien', publication_year: 1937, in_stock: true },
      { title: '1984', author: 'George Orwell', publication_year: 1949, in_stock: true },
      { title: 'Dune', author: 'Frank Herbert', publication_year: 1965, in_stock: false },
    ];

    // Insert multiple books
    await sql`
      INSERT INTO books ${sql(booksToInsert, 'title', 'author', 'publication_year', 'in_stock')}
    `;
    console.log('Inserted 3 rows of data.');
  } catch (err) {
    console.error('Connection failed.', err);
  } finally {
    sql.end();
  }
}

setup();
```

The above code does the following:

- Loads the connection string from the `.env` file.
- Connects to the Lakebase Postgres database.
- Drops the `books` table if it already exists to ensure a clean slate.
- Creates a table named `books` with columns for `id`, `title`, `author`, `publication_year`, and `in_stock`.
- Inserts a single book record and then multiple book records.

Run the script:

```bash
node create_table.js
```

When the code runs successfully, it produces the following output. On the first run, postgres.js also prints a `NOTICE` that the `books` table doesn't exist yet, which you can ignore.

```text title="Output"
Connection established
Finished dropping table (if it existed).
Finished creating table.
Inserted a single book.
Inserted 3 rows of data.
```

### Read data

In your project directory, create a file named `read_data.js`. This script connects to your Lakebase Postgres database and retrieves all rows from the `books` table.

**node-postgres (pg)**

```javascript title="read_data.js"
import 'dotenv/config';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

async function readData() {
  const client = await pool.connect();
  try {
    console.log('Connection established');

    // Fetch all rows from the books table
    const { rows } = await client.query('SELECT * FROM books ORDER BY publication_year;');

    console.log('\n--- Book Library ---');
    rows.forEach((row) => {
      console.log(
        `ID: ${row.id}, Title: ${row.title}, Author: ${row.author}, Year: ${row.publication_year}, In Stock: ${row.in_stock}`
      );
    });
    console.log('--------------------\n');
  } catch (err) {
    console.error('Connection failed.', err.stack);
  } finally {
    client.release();
    pool.end();
  }
}

readData();
```

**Neon serverless driver**

```javascript title="read_data.js"
import 'dotenv/config';
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL);

async function readData() {
  try {
    console.log('Connection established');

    // Fetch all rows from the books table
    const books = await sql`SELECT * FROM books ORDER BY publication_year;`;

    console.log('\n--- Book Library ---');
    books.forEach((book) => {
      console.log(
        `ID: ${book.id}, Title: ${book.title}, Author: ${book.author}, Year: ${book.publication_year}, In Stock: ${book.in_stock}`
      );
    });
    console.log('--------------------\n');
  } catch (err) {
    console.error('Connection failed.', err);
  }
}

readData();
```

**postgres.js**

```javascript title="read_data.js"
import 'dotenv/config';
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL, {
  ssl: 'require',
});

async function readData() {
  try {
    console.log('Connection established');

    // Fetch all rows from the books table
    const books = await sql`SELECT * FROM books ORDER BY publication_year;`;

    console.log('\n--- Book Library ---');
    books.forEach((book) => {
      console.log(
        `ID: ${book.id}, Title: ${book.title}, Author: ${book.author}, Year: ${book.publication_year}, In Stock: ${book.in_stock}`
      );
    });
    console.log('--------------------\n');
  } catch (err) {
    console.error('Connection failed.', err);
  } finally {
    sql.end();
  }
}

readData();
```

Run the script:

```bash
node read_data.js
```

When the code runs successfully, it produces the following output:

```text title="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: false
--------------------
```

### Update data

In your project directory, create a file named `update_data.js`. This script connects to your Lakebase Postgres database and updates the stock status of the book 'Dune' to `true`.

**node-postgres (pg)**

```javascript title="update_data.js"
import 'dotenv/config';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

async function updateData() {
  const client = await pool.connect();
  try {
    console.log('Connection established');

    // Update a data row in the table
    await client.query('UPDATE books SET in_stock = $1 WHERE title = $2;', [true, 'Dune']);
    console.log("Updated stock status for 'Dune'.");
  } catch (err) {
    console.error('Connection failed.', err.stack);
  } finally {
    client.release();
    pool.end();
  }
}

updateData();
```

**Neon serverless driver**

```javascript title="update_data.js"
import 'dotenv/config';
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL);

async function updateData() {
  try {
    console.log('Connection established');

    // Update a data row in the table
    await sql`UPDATE books SET in_stock = ${true} WHERE title = ${'Dune'}`;
    console.log("Updated stock status for 'Dune'.");
  } catch (err) {
    console.error('Connection failed.', err);
  }
}

updateData();
```

**postgres.js**

```javascript title="update_data.js"
import 'dotenv/config';
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL, {
  ssl: 'require',
});

async function updateData() {
  try {
    console.log('Connection established');

    // Update a data row in the table
    await sql`UPDATE books SET in_stock = ${true} WHERE title = ${'Dune'}`;
    console.log("Updated stock status for 'Dune'.");
  } catch (err) {
    console.error('Connection failed.', err);
  } finally {
    sql.end();
  }
}

updateData();
```

Run the script:

```bash
node update_data.js
```

After running this script, you can run `read_data.js` again to verify the change.

```bash
node read_data.js
```

When the code runs successfully, it produces the following output:

```text title="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the stock status for 'Dune' has been updated to `true`.

### Delete data

In your project directory, create a file named `delete_data.js`. This script connects to your Lakebase Postgres database and deletes the book '1984' from the `books` table.

**node-postgres (pg)**

```javascript title="delete_data.js"
import 'dotenv/config';
import { Pool } from 'pg';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

async function deleteData() {
  const client = await pool.connect();
  try {
    console.log('Connection established');

    // Delete a data row from the table
    await client.query('DELETE FROM books WHERE title = $1;', ['1984']);
    console.log("Deleted the book '1984' from the table.");
  } catch (err) {
    console.error('Connection failed.', err.stack);
  } finally {
    client.release();
    pool.end();
  }
}

deleteData();
```

**Neon serverless driver**

```javascript title="delete_data.js"
import 'dotenv/config';
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL);

async function deleteData() {
  try {
    console.log('Connection established');

    // Delete a data row from the table
    await sql`DELETE FROM books WHERE title = ${'1984'}`;
    console.log("Deleted the book '1984' from the table.");
  } catch (err) {
    console.error('Connection failed.', err);
  }
}

deleteData();
```

**postgres.js**

```javascript title="delete_data.js"
import 'dotenv/config';
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL, {
  ssl: 'require',
});

async function deleteData() {
  try {
    console.log('Connection established');

    // Delete a data row from the table
    await sql`DELETE FROM books WHERE title = ${'1984'}`;
    console.log("Deleted the book '1984' from the table.");
  } catch (err) {
    console.error('Connection failed.', err);
  } finally {
    sql.end();
  }
}

deleteData();
```

Run the script:

```bash
node delete_data.js
```

After running this script, you can run `read_data.js` again to verify that the row has been deleted.

```bash
node read_data.js
```

When the code runs successfully, it produces the following output:

```text title="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the book '1984' has been successfully deleted from the `books` table.

## Use an ORM or framework

While this guide demonstrates raw SQL queries, for more advanced and maintainable data interactions, consider using an Object-Relational Mapper (ORM) or query builder. ORMs let you work with your data as objects and manage schema changes through migrations, keeping your database structure in sync with your application models.

Explore these guides to integrate popular data tools with Neon:

- [Connect with Prisma](https://neon.com/docs/guides/prisma)
- [Connect with Drizzle ORM](https://neon.com/docs/guides/drizzle)
- [Connect with TypeORM](https://neon.com/docs/guides/typeorm)
- [Connect with Sequelize](https://neon.com/docs/guides/sequelize)

## Next steps: Neon backend services

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Add Realtime](https://neon.com/docs/realtime/overview): Make any SQL query live, with end-to-end, type-safe reactivity for apps and agents

## Using Bun

If you are using Bun, you can also connect to Neon databases using the Neon serverless driver or other Postgres clients. See [Connect with Bun](https://neon.com/docs/guides/bun).

## Source code

You can find the source code for the applications described in this guide on GitHub.

- [Get started with the Neon Serverless Driver](https://github.com/neondatabase/examples/tree/main/with-neon-serverless): Get started with Node.js and the Neon Serverless Driver

## Resources

- [Neon serverless driver documentation](https://github.com/neondatabase/serverless)
- [node-postgres (pg) documentation](https://node-postgres.com/)
- [Postgres.js documentation](https://github.com/porsager/postgres)

--- [Document source](https://neon.com/docs/guides/knex.md) ---

> Summary: Connect Knex to Lakebase Postgres by passing the Neon connection string to the `connectionString` option with `sslmode=verify-full`. Serverless deployments should use Neon's pooled endpoint to prevent connection exhaustion. You can also improve performance by switching to `pg-native` via the `NODE_PG_FORCE_NATIVE` environment variable.

# Connect from Knex to Neon

Learn how to connect to Neon from Knex

Last updated: 2026-09-16

Knex is an open-source SQL query builder for Postgres. This guide covers the following topics:

- [Connect to Neon from Knex](https://neon.com/docs/guides/knex#connect-to-neon-from-knex)
- [Use connection pooling with Knex](https://neon.com/docs/guides/knex#use-connection-pooling-with-knex)
- [Performance tips](https://neon.com/docs/guides/knex#performance-tips)

## Connect to Neon from Knex

To establish a basic connection from Knex to Neon, perform the following steps:

1. Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select a branch, a user, and the database you want to connect to. A connection string is constructed for you.
   ![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)
   The connection string includes the user name, password, hostname, and database name.

2. Install Knex and the `pg` driver with `npm install knex pg`. Then update the Knex initialization in your application to the following:

   ```typescript {2-5}
   export const client = knex({
     client: 'pg',
     connection: {
       connectionString: process.env.DATABASE_URL,
     },
   });
   ```

3. Add a `DATABASE_URL` variable to your `.env` file and set it to the Neon connection string that you copied in the previous step. We also recommend adding `?sslmode=verify-full&channel_binding=require` to the end of the connection string to ensure a [secure connection](https://neon.com/docs/connect/connect-securely).

   Your app needs to load this variable. For example, run a script with `node --env-file=.env` (Node.js 20.6 and later), or use the [dotenv](https://www.npmjs.com/package/dotenv) package.

   Your setting will appear similar to the following:

   ```text
   DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=verify-full&channel_binding=require"
   ```

## Use connection pooling with Knex

Serverless functions can require a large number of database connections as demand increases. If you use serverless functions in your application, we recommend that you use a pooled Neon connection string, as shown:

```ini
# Pooled Neon connection string
DATABASE_URL="postgresql://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=verify-full&channel_binding=require"
```

A pooled Neon connection string adds `-pooler` to the endpoint ID, which tells Neon to use a pooled connection. You can add `-pooler` to your connection string manually or copy a pooled connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Enable the **Connection pooling** toggle to add the `-pooler` suffix.

**Important:** Use a pooled connection string for your application at runtime, but use a direct (non-pooled) connection string when running Knex migrations. Neon's pooled connection uses PgBouncer in transaction mode, which doesn't support all session-level operations that migration tools rely on, so running migrations over a pooled connection can lead to errors. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Performance tips

This section outlines a performance optimization you can try when using Knex with Neon.

### Enabling NODE_PG_FORCE_NATIVE

Knex uses a [node-postgres](https://node-postgres.com) Pool instance to connect to your Postgres database. Installing [pg-native](https://npmjs.com/package/pg-native) and setting the `NODE_PG_FORCE_NATIVE` environment variable to `true` [switches the `pg` driver to `pg-native`](https://github.com/brianc/node-postgres/blob/master/packages/pg/lib/index.js#L31-L34), which can produce noticeably faster response times according to some users.

Install `pg-native` next to `knex` and `pg`:

```bash
npm install pg-native
```

Then set the variable in your environment:

```ini
NODE_PG_FORCE_NATIVE=true
```

--- [Document source](https://neon.com/docs/guides/kotlin.md) ---

> Summary: Connect a Kotlin application to Neon Postgres using the PostgreSQL JDBC driver with Gradle. Covers complete CRUD examples including PreparedStatement inserts, batch operations, and transaction control with autoCommit, commit, and rollback. Also covers dotenv-kotlin for credential management. Focuses on raw JDBC without an ORM, unlike Micronaut or Hibernate guides.

# Connect a Kotlin application to Neon Postgres

Learn how to run SQL queries in Neon from Kotlin using the PostgreSQL JDBC driver

Last updated: 2026-10-31

Pre-built prompt for connecting Kotlin applications to Neon [View prompt](https://neon.com/prompts/kotlin-prompt.md)

This guide describes how to create a Neon project and connect to it from a Kotlin application using **Java Database Connectivity (JDBC)**, the standard API for interacting with relational databases on the JVM.

You will learn how to set up a project, connect to your database, and perform basic create, read, update, and delete (CRUD) operations.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://console.neon.tech/signup).
- [Java Development Kit (JDK)](https://www.oracle.com/java/technologies/downloads/) 21 or later. The project that `gradle init` creates sets a Java 21 toolchain.
- [Gradle](https://gradle.org/install/) to manage the project and dependencies.

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Your project is created with a ready-to-use database named `neondb`. In the following steps, you will connect to this database from your Kotlin application.

## Create a Kotlin project

Create a project using the Gradle `init` command. This sets up a standard Kotlin application structure.

1. Run the following command in your terminal to generate a new Kotlin application project.

   ```bash
   gradle init \
       --type kotlin-application \
       --dsl kotlin \
       --project-name neon-kotlin-jdbc \
       --package com.neon.quickstart
   ```

2. Change into the newly created project directory.

   ```bash
   cd neon-kotlin-jdbc
   ```

   > Open this directory in your preferred code editor (for example, VS Code, IntelliJ IDEA).

3. Add the `postgresql` driver and `dotenv-kotlin` libraries. The project uses a Gradle version catalog (`gradle/libs.versions.toml`), so declare the libraries there and reference them from `app/build.gradle.kts`.

   Add these lines to the existing `[versions]` and `[libraries]` tables in `gradle/libs.versions.toml`. Don't create a second `[versions]` or `[libraries]` table, or Gradle fails with a TOML syntax error:

   ```toml filename="gradle/libs.versions.toml"
   # Add to the [versions] table
   postgresql = "42.7.14"
   dotenv = "6.5.1"

   # Add to the [libraries] table
   postgresql = { module = "org.postgresql:postgresql", version.ref = "postgresql" }
   dotenv = { module = "io.github.cdimascio:dotenv-kotlin", version.ref = "dotenv" }
   ```

   Then add these two lines to the `dependencies` block in `app/build.gradle.kts`:

   ```kotlin filename="app/build.gradle.kts"
   implementation(libs.postgresql)
   implementation(libs.dotenv)
   ```

   Save both files.

4. Compile the project to download the dependencies.

   ```bash
   ./gradlew build
   ```

   On Windows, use `gradlew.bat build`.

   This command compiles your Kotlin code and downloads the required dependencies.

## Store your Neon connection string

Create a file named `.env` in the `app` directory. This file will securely store your database connection string. Place it next to the application module so `dotenv-kotlin` can load it when you run the app with Gradle.

1. In the [Neon Console](https://console.neon.tech), open your project.
2. Click **Connect** in the Console nav to open the **Connect to your branch** modal.
3. Select **Java** as your programming language. Kotlin uses the same JDBC connection string format.
   ![Connection modal](https://neon.com/docs/connect/java_connection_details.png)
4. Copy the connection string, which includes your password.
5. Create a file named `.env` in the `app` directory and add the connection string to it as shown below:

   ```text filename="app/.env"
   DATABASE_URL="jdbc:postgresql://[neon_hostname]/[dbname]?user=[user]&password=[password]&sslmode=require&channelBinding=require"
   ```

   > Replace `[user]`, `[password]`, `[neon_hostname]`, and `[dbname]` with your actual database credentials.

## Examples

This section provides code examples for performing CRUD operations. Place the example files inside `app/src/main/kotlin/com/neon/quickstart/`.

You can also clone the complete example project from GitHub: [neon-kotlin-jdbc](https://github.com/aaravmahajanofficial/neon-kotlin-jdbc).

Each example is a package-level function. Replace the contents of `App.kt` with the following code, then uncomment the example you want to run:

The template also generates a test in `app/src/test/` for the original `App` class. Delete the `app/src/test` directory so `./gradlew build` still passes after you replace `App.kt`.

```kotlin filename="app/src/main/kotlin/com/neon/quickstart/App.kt"
package com.neon.quickstart

fun main() {
    // Uncomment the example you want to run.

    createTable()
    // readData()
    // updateData()
    // deleteData()
    // transactionExample()
}
```

Then run the selected example with:

```bash
./gradlew run
```

On Windows, use `gradlew.bat run`.

### Create a table and insert data

Create a file named `CreateTable.kt`. This function connects to your database, creates a table, and inserts data.

```kotlin filename="app/src/main/kotlin/com/neon/quickstart/CreateTable.kt"
package com.neon.quickstart

import io.github.cdimascio.dotenv.dotenv
import java.sql.DriverManager

fun createTable() {
    val dotEnv = dotenv()
    val connString = dotEnv["DATABASE_URL"]

    try {
        DriverManager.getConnection(connString).use { conn ->
            println("Connection established")

            conn.createStatement().use { stmt ->
                // Drop the table if it already exists
                stmt.execute("DROP TABLE IF EXISTS books;")
                println("Finished dropping table (if it existed).")

                // Create a new table
                stmt.execute(
                    """
                    CREATE TABLE books (
                        id SERIAL PRIMARY KEY,
                        title VARCHAR(255) NOT NULL,
                        author VARCHAR(255),
                        publication_year INT,
                        in_stock BOOLEAN DEFAULT TRUE
                    );
                    """.trimIndent()
                )
                println("Finished creating table.")

                // Insert a single book record
                val insertOneSql = """
                    INSERT INTO books (title, author, publication_year, in_stock)
                    VALUES (?, ?, ?, ?);
                """.trimIndent()

                conn.prepareStatement(insertOneSql).use { pstmt ->
                    pstmt.setString(1, "The Catcher in the Rye")
                    pstmt.setString(2, "J.D. Salinger")
                    pstmt.setInt(3, 1951)
                    pstmt.setBoolean(4, true)
                    pstmt.executeUpdate()

                    println("Inserted a single book.")
                }

                // Insert multiple books
                val insertManySql = """
                    INSERT INTO books (title, author, publication_year, in_stock)
                    VALUES (?, ?, ?, ?);
                """.trimIndent()

                conn.prepareStatement(insertManySql).use { pstmt ->
                    val booksToInsert = listOf(
                        listOf("The Hobbit", "J.R.R. Tolkien", 1937, true),
                        listOf("1984", "George Orwell", 1949, true),
                        listOf("Dune", "Frank Herbert", 1965, false)
                    )

                    for (book in booksToInsert) {
                        pstmt.setString(1, book[0] as String)
                        pstmt.setString(2, book[1] as String)
                        pstmt.setInt(3, book[2] as Int)
                        pstmt.setBoolean(4, book[3] as Boolean)
                        pstmt.addBatch()
                    }

                    pstmt.executeBatch()
                    println("Inserted 3 rows of data.")
                }
            }
        }
    } catch (e: Exception) {
        println("Connection failed.")
        e.printStackTrace()
    }
}
```

The above code does the following:

- Connects to the Neon database using the connection string from the `.env` file.
- Drops the `books` table if it already exists.
- Creates a new `books` table with columns for `id`, `title`, `author`, `publication_year`, and `in_stock`.
- Inserts a single book record.
- Inserts multiple book records in a batch operation.

In `App.kt`, ensure only `createTable()` is uncommented, then run:

```bash
./gradlew run
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established
Finished dropping table (if it existed).
Finished creating table.
Inserted a single book.
Inserted 3 rows of data.
```

### Read data

Create a file named `ReadData.kt`. This function fetches all rows from the `books` table and prints them.

```kotlin filename="app/src/main/kotlin/com/neon/quickstart/ReadData.kt"
package com.neon.quickstart

import io.github.cdimascio.dotenv.dotenv
import java.sql.DriverManager

fun readData() {
    val dotenv = dotenv()
    val connString = dotenv["DATABASE_URL"]

    try {
        DriverManager.getConnection(connString).use { conn ->
            conn.createStatement().use { stmt ->
                println("Connection established")

                val sql = "SELECT * FROM books ORDER BY publication_year;"

                stmt.executeQuery(sql).use { rs ->
                    println("\n--- Book Library ---")

                    while (rs.next()) {
                        println(
                            "ID: ${rs.getInt("id")}, " +
                                    "Title: ${rs.getString("title")}, " +
                                    "Author: ${rs.getString("author")}, " +
                                    "Year: ${rs.getInt("publication_year")}, " +
                                    "In Stock: ${rs.getBoolean("in_stock")}"
                        )
                    }

                    println("--------------------\n")
                }
            }
        }
    } catch (e: Exception) {
        println("Connection failed.")
        e.printStackTrace()
    }
}
```

The above code does the following:

- Connects to the Neon database using the connection string from the `.env` file.
- Executes a SQL query to select all rows from the `books` table, ordered by `publication_year`.
- Iterates through the result set and prints each book's details.

In `App.kt`, uncomment `readData()` (and comment out the other calls), then run:

```bash
./gradlew run
```

When the read logic runs, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: false
--------------------
```

### Update data

Create a file named `UpdateData.kt` to update the stock status of 'Dune' to `true`.

```kotlin filename="app/src/main/kotlin/com/neon/quickstart/UpdateData.kt"
package com.neon.quickstart

import io.github.cdimascio.dotenv.dotenv
import java.sql.DriverManager

fun updateData() {
    val dotenv = dotenv()
    val connString = dotenv["DATABASE_URL"]
    val sql = "UPDATE books SET in_stock = ? WHERE title = ?;"

    try {
        DriverManager.getConnection(connString).use { conn ->
            conn.prepareStatement(sql).use { pstmt ->
                println("Connection established")

                pstmt.setBoolean(1, true)
                pstmt.setString(2, "Dune")

                val rowsAffected = pstmt.executeUpdate()

                if (rowsAffected > 0) {
                    println("Updated stock status for 'Dune'.")
                }
            }
        }
    } catch (e: Exception) {
        println("Connection failed.")
        e.printStackTrace()
    }
}
```

The above code does the following:

- Connects to the Neon database.
- Prepares an SQL `UPDATE` statement to set the `in_stock` status of the book 'Dune' to `true`.
- Executes the update and prints a confirmation message if successful.

In `App.kt`, uncomment `updateData()`, then run:

```bash
./gradlew run
```

After running the update, verify the change by switching `App.kt` to call `readData()` and running again.

```bash
./gradlew run
```

The updated output will be:

```text filename="Output"
--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the stock status for 'Dune' has been updated to `true`.

### Delete data

Create a file named `DeleteData.kt` to delete the book '1984' from the table.

```kotlin filename="app/src/main/kotlin/com/neon/quickstart/DeleteData.kt"
package com.neon.quickstart

import io.github.cdimascio.dotenv.dotenv
import java.sql.DriverManager

fun deleteData() {
    val dotenv = dotenv()
    val connString = dotenv["DATABASE_URL"]
    val sql = "DELETE FROM books WHERE title = ?;"

    try {
        DriverManager.getConnection(connString).use { conn ->
            conn.prepareStatement(sql).use { pstmt ->
                println("Connection established")

                pstmt.setString(1, "1984")

                val rowsAffected = pstmt.executeUpdate()

                if (rowsAffected > 0) {
                    println("Deleted the book '1984' from the table.")
                }
            }
        }
    } catch (e: Exception) {
        println("Connection failed.")
        e.printStackTrace()
    }
}
```

The above code does the following:

- Connects to the Neon database.
- Prepares an SQL `DELETE` statement to remove the book '1984'.
- Executes the delete and prints a confirmation message if successful.

In `App.kt`, uncomment `deleteData()`, then run:

```bash
./gradlew run
```

After running the delete, verify the change by switching `App.kt` to call `readData()` and running again.

```bash
./gradlew run
```

The final output will be:

```text filename="Output"
--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the book '1984' has been successfully deleted from the `books` table.

### Using transactions

The examples above execute each operation independently. For production code where multiple operations must succeed or fail together, wrap them in a transaction. Set `autoCommit = false` to start a transaction, call `commit()` on success, and `rollback()` in the catch block on failure.

```kotlin filename="app/src/main/kotlin/com/neon/quickstart/TransactionExample.kt"
package com.neon.quickstart

import io.github.cdimascio.dotenv.dotenv
import java.sql.DriverManager
import java.sql.SQLException

fun transactionExample() {
    val dotenv = dotenv()
    val connString = dotenv["DATABASE_URL"]

    DriverManager.getConnection(connString).use { conn ->
        try {
            conn.autoCommit = false // Begin Transaction

            // Insert
            conn.prepareStatement(
                "INSERT INTO books (title, author, publication_year) VALUES (?, ?, ?)"
            ).use { pstmt ->
                pstmt.setString(1, "Brave New World")
                pstmt.setString(2, "Aldous Huxley")
                pstmt.setInt(3, 1932)
                pstmt.executeUpdate()

                println("Inserted book.")
            }

            // Update
            conn.prepareStatement(
                "UPDATE books SET in_stock = ? WHERE title = ?"
            ).use { pstmt ->
                pstmt.setBoolean(1, false)
                pstmt.setString(2, "Brave New World")
                pstmt.executeUpdate()

                println("Updated stock status.")
            }

            conn.commit() // Commit transaction
            println("Transaction committed successfully.")

        } catch (e: SQLException) {
            println("Transaction failed. Rolling back.")

            conn.rollback()
            e.printStackTrace()
        }
    }
}
```

In `App.kt`, uncomment `transactionExample()`, then run:

```bash
./gradlew run
```

<details>

<summary>**Notes for AI-assisted setup**</summary>

- Always use `PreparedStatement` (with `?` placeholders) for INSERT, UPDATE, and DELETE operations. Do not use `Statement` for queries with user-provided data, as this is vulnerable to SQL injection.
- Add library versions to `gradle/libs.versions.toml` and reference them with `implementation(libs.*)` in `app/build.gradle.kts`.
- Wrap related database operations in a transaction (`autoCommit = false` / `commit()` / `rollback()`). Always call `rollback()` in a catch block to ensure atomicity on failure.
- Close JDBC connections and statements using Kotlin's `.use { }` (equivalent to Java try-with-resources) to prevent connection leaks.
- Do not hardcode credentials in `.kt` files. Use environment variables via `dotenv-kotlin`. For more information, see [Security overview](https://neon.com/docs/security/security-overview).

</details>

## Next steps with a framework

While this guide demonstrates how to connect to Neon using raw SQL queries, for more advanced and maintainable data interactions in your Kotlin applications, consider using a framework or ORM. Frameworks help you manage schema changes and keep your database structure in sync with your application models.

Explore the following resources to learn how to integrate frameworks with Neon:

- [Connect a Micronaut Kotlin application to Neon](https://neon.com/docs/guides/micronaut-kotlin)
- [Database Schema Changes with Hibernate, Spring Boot, and Neon](https://neon.com/guides/spring-boot-hibernate)

## Next steps with Neon backend services

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Resources

- [Example project on GitHub](https://github.com/aaravmahajanofficial/neon-kotlin-jdbc)
- [PostgreSQL JDBC Driver Documentation](https://jdbc.postgresql.org/documentation/use/)
- [Gradle User Manual](https://docs.gradle.org/current/userguide/userguide.html)
- [dotenv-kotlin](https://github.com/cdimascio/dotenv-kotlin)
- [Connect a Micronaut Kotlin application to Neon](https://neon.com/docs/guides/micronaut-kotlin)

--- [Document source](https://neon.com/docs/guides/koyeb.md) ---

> Summary: Connect a Lakebase Postgres database to a Koyeb-deployed Node.js application using Prisma as the ORM and a DATABASE_URL environment variable. Use this guide when you need a managed Postgres backend on Koyeb without running your own database server. Covers both the Koyeb control panel and CLI deployment paths, including Prisma schema sync and database seeding.

# Use Neon with Koyeb

Learn how to connect a Lakebase Postgres database to an application deployed with Koyeb

Last updated: 2026-08-04

[Koyeb](https://www.koyeb.com/) is a developer-friendly, serverless platform designed to easily deploy reliable and scalable applications globally. Koyeb offers native autoscaling, automatic HTTPS (SSL), auto-healing, and global load-balancing across their edge network with zero configuration.

This guide describes how connect a Lakebase Postgres database to an application deployed with Koyeb. To follow the instructions in this guide, you require:

- A [Koyeb account](https://app.koyeb.com/) to deploy the application. Alternatively, you can install the [Koyeb CLI](https://www.koyeb.com/docs/quickstart/koyeb-cli) if you prefer to deploy the application from your terminal.
- A Neon account to deploy the Postgres database. If you do not have one, see [Sign up](https://neon.com/docs/get-started/signing-up).

The example application connects to your database using [Prisma](https://www.prisma.io/) as an ORM. Prisma synchronizes the database schema with the Prisma schema included with the application and seeds the database.

## Create a Neon project

1. Navigate to the [Neon Console](https://console.neon.tech/).
2. Select **Create a project**.
3. Enter a name for the project (`neon-koyeb`, for example), and select a Postgres version and region.
4. Click **Create project**.

A dialog pops up with your Neon connection string, which appears similar to the following:

```bash
postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

Store this value in a safe place. It is required later. The connection string specifies `neondb` as the database. This is the database created with your Neon project if you did not specify a different database name. You will use this database with the example application.

## Deploy the application on Koyeb

You can deploy on Koyeb using the control panel or the Koyeb CLI.

### From the Koyeb control panel

To deploy the application from the Koyeb [control panel](https://app.koyeb.com/), follow these steps:

1. Navigate to the `Apps` tab and select **Create App**.
2. Select GitHub as the deployment method.
3. When asked to select the repository to deploy, enter `https://github.com/koyeb/example-express-prisma` in the **Public GitHub repository** field.
4. Keep `example-express-prisma` as the name and `main` as the branch.
5. In **Build and deployment settings**, enable the **Override** setting and add the following **Build command**: `npm run postgres:init`
6. Select the region closest to your Neon database.
7. Under **Advanced** > **Environment variables**, add a `DATABASE_URL` environment variable to enable the application to connect to your database on Neon. Set the value to the Neon connection string provided to you when you created the Neon project.
8. Enter a name for your app. For example, `express-neon`
9. Click **Deploy**.

Koyeb builds the application. After the build and deployment have finished, you can access your application running on Koyeb by clicking the URL ending with `.koyeb.app`.

The example application exposes a `/planets` endpoint that you can use to list planets from the database. After your deployment is live, you should see the following results when navigating to `https://<YOUR_APP_URL>.koyeb.app/planets`:

```json
[
  {
    "id": 1,
    "name": "Mercury"
  },
  {
    "id": 2,
    "name": "Venus"
  },
  {
    "id": 3,
    "name": "Mars"
  }
]
```

### From the Koyeb CLI

You can also deploy your application using the Koyeb CLI. To install it, follow the instructions in the [Koyeb CLI documentation](https://www.koyeb.com/docs/quickstart/koyeb-cli).

Using the CLI requires an API access token, which you can generate in the Koyeb [control panel](https://app.koyeb.com/), under **Organization Settings** > **API**. Once generated, run the command `koyeb login` and enter the token when prompted.

To deploy the example application, run the following command in your terminal. Make sure to replace the `DATABASE_URL` with your Neon connection string.

```bash
koyeb apps init express-neon \
--instance-type free \
--git github.com/koyeb/example-express-prisma \
--git-branch main \
--git-build-command "npm run postgres:init" \
--ports 8080:http \
--routes /:8080 \
--env PORT=8080 \
--env DATABASE_URL="{}"
```

#### Access Koyeb deployment logs

To track the app deployment and visualize build logs, execute the following command:

```bash
koyeb service logs express-neon/express-neon -t build
```

#### Access your app

After the build and deployment have finished, you can retrieve the public domain to access your application by running the following command:

```bash
$ koyeb app get express-neon
ID          NAME         STATUS         DOMAINS                                CREATED AT
b8611a1d    express-neon HEALTHY        ["express-neon-myorg.koyeb.app"]       16 Feb 23 18:13 UTC
```

The example application exposes a `/planets` endpoint that you can use to list planets from the database. After your deployment is live, you should see the following results when navigating to `https://<YOUR_APP_URL>.koyeb.app/planets`:

```json
[
  {
    "id": 1,
    "name": "Mercury"
  },
  {
    "id": 2,
    "name": "Venus"
  },
  {
    "id": 3,
    "name": "Mars"
  }
]
```

## Delete the example application and Neon project

To delete the example application on Koyeb to avoid incurring any charges, follow these steps:

1. From the Koyeb [control panel](https://app.koyeb.com/), select the **App** to delete.
2. On the **Settings** tab, select **Danger Zone** and click **Delete**.

To delete your Neon project, refer to [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

--- [Document source](https://neon.com/docs/guides/kysely.md) ---

> Summary: Connect Kysely to Lakebase Postgres using the Neon HTTP serverless driver for edge environments, the Neon WebSocket driver for serverless workloads that need transactions, or node-postgres for long-running servers. Choose this guide when you want full SQL control with TypeScript type-checking and need to pick the right Neon driver dialect for your deployment target. Covers interface-based schema definitions, client initialization per driver, optional migrations via FileMigrationProvider, and CRUD query examples.

# Connect from Kysely to Neon

Learn how to connect to Neon from Kysely

Last updated: 2026-10-08

Pre-built prompt for connecting Node/TypeScript applications to Neon using Kysely. [View prompt](https://neon.com/prompts/kysely-prompt.md)

**What you will learn:**

- How to connect from Kysely using different drivers
- How to define TypeScript schemas for Kysely
- How to run migrations and queries

**Related resources**

- [Kysely Documentation](https://kysely.dev/docs/intro)
- [kysely-neon GitHub](https://github.com/kysely-org/kysely-neon)

Kysely is a type-safe SQL query builder for TypeScript. Instead of mapping objects to tables like an ORM, it gives you an API for building SQL queries and uses TypeScript's type system for type checking and autocompletion. This guide walks you through connecting your application to a Lakebase Postgres database using Kysely.

To connect a TypeScript/Node.js project to Neon using Kysely, follow these steps:

## Create a TypeScript/Node.js project

Create a new directory for your project and navigate into it:

```bash
mkdir my-kysely-neon-project
cd my-kysely-neon-project
```

Initialize a new Node.js project:

```bash
npm init -y
```

Install TypeScript and initialize a configuration file (Kysely requires TypeScript 4.6+):

```bash
npm install -D typescript tsx @types/node
npx tsc --init
```

Configure your `tsconfig.json` for type safety and module resolution. Ensure you have at least the following settings:

```json {4-10}
{
  "compilerOptions": {
    // ... other settings ...
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "types": ["node"],
    "strict": true,
    "allowImportingTsExtensions": true,
    "noEmit": true
  }
}
```

Recent versions of `tsc --init` set `"types": []`, which hides the Node.js types installed by `@types/node`. Set `"types": ["node"]` so names like `process` type-check.

Configure your `package.json` to use ES modules. `npm init -y` writes `"type": "commonjs"`, so change it to:

```json {3}
{
  // ... other settings ...
  "type": "module"
}
```

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Get your connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select a branch, a user, and the database you want to connect to. A connection string is constructed for you.
![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

Create a `.env` file in your project's root directory and add the connection string to it. Your `.env` file should look like this:

```text
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

If you use `node-postgres`, `pg` 8.23 and later print a `SECURITY WARNING` for `sslmode=require`. Change it to `sslmode=verify-full` to keep the same behavior without the warning.

## Install Kysely and a driver

Install the Kysely core package and the necessary driver dependencies. Choose one of the following drivers based on your application's needs. For a Node.js script or long-running server, use `node-postgres`.

**Neon Serverless (HTTP)**

Use the Neon serverless HTTP driver for serverless/edge environments (for example, Vercel Edge, Cloudflare Workers). This requires the `kysely-neon` dialect.

**Note: Note**

The Neon serverless driver over HTTP is stateless and does not support persistent connections or interactive transactions. If your application requires transactions, we recommend using the Neon WebSocket driver or `node-postgres`.

```bash
npm install kysely kysely-neon @neondatabase/serverless dotenv
```

**Neon WebSocket**

Use the Neon WebSocket driver for serverless environments that require a persistent connection or transactions. This uses the core Postgres dialect with the Neon driver.

```bash
npm install kysely @neondatabase/serverless ws dotenv
npm install -D @types/ws
```

**node-postgres**

Use the classic `node-postgres` (`pg`) driver, a widely-used choice for long-running Node.js servers.

```bash
npm install kysely pg dotenv
npm install -D @types/pg
```

## Create a table (optional)

> You can skip this step if you already have tables in your database.

Unlike many ORMs, Kysely does not automatically sync your TypeScript types with the database schema. Tables must exist before you query them.

To create the table with Kysely's migration helpers (`up` and `down`) instead, skip this step and follow [Run a migration](https://neon.com/docs/guides/kysely#run-a-migration-optional) below. Don't do both: the migration fails if the `users` table already exists.

Navigate to the [SQL Editor in the Neon Console](https://neon.com/docs/get-started/query-with-neon-sql-editor) and run the following SQL command to create a `users` table:

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT NOW() NOT NULL
);
```

## Define the database schema

Kysely is TypeScript-first and requires you to define an interface that describes your database structure. This interface tells Kysely which tables and columns exist.

Create a file `src/types.ts`:

```typescript
import type { Generated, Selectable, Insertable, Updateable } from 'kysely';

export interface Database {
  users: UsersTable;
}

export interface UsersTable {
  // Columns that are generated by the database should be marked
  // using the `Generated` type.
  id: Generated<number>;
  name: string;
  email: string;
  created_at: Generated<Date>;
}

// You can use these types in your application code
export type User = Selectable<UsersTable>;
export type NewUser = Insertable<UsersTable>;
export type UserUpdate = Updateable<UsersTable>;
```

## Initialize the Kysely client

Create a file `src/db.ts` to initialize and export your Kysely instance. The configuration depends on the driver you selected.

**Neon Serverless (HTTP)**

When using the HTTP driver, use `NeonDialect` from `kysely-neon`.

```typescript
import 'dotenv/config';
import { Kysely } from 'kysely';
import { NeonDialect } from 'kysely-neon';
import { neon } from '@neondatabase/serverless';
import type { Database } from './types.ts';

export const db = new Kysely<Database>({
  dialect: new NeonDialect({
    neon: neon(process.env.DATABASE_URL!),
  }),
});
```

**Neon WebSocket**

When using WebSockets, use the built-in `PostgresDialect` but pass the Neon `Pool`.

```typescript
import 'dotenv/config';
import { Kysely, PostgresDialect, type PostgresPool } from 'kysely';
import { Pool, neonConfig } from '@neondatabase/serverless';
import ws from 'ws';
import type { Database } from './types.ts';

// Configure the WebSocket constructor
neonConfig.webSocketConstructor = ws;

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export const db = new Kysely<Database>({
  dialect: new PostgresDialect({
    // Neon's Pool type doesn't match Kysely's PostgresPool type exactly,
    // but the Pool works with PostgresDialect at runtime.
    pool: pool as unknown as PostgresPool,
  }),
});
```

**node-postgres**

When using `node-postgres`, use the built-in `PostgresDialect` with the standard `pg` Pool.

```typescript
import 'dotenv/config';
import { Kysely, PostgresDialect } from 'kysely';
import { Pool } from 'pg';
import type { Database } from './types.ts';

export const db = new Kysely<Database>({
  dialect: new PostgresDialect({
    pool: new Pool({
      connectionString: process.env.DATABASE_URL,
    }),
  }),
});
```

## Run a migration (optional)

> You can skip this step if you do not intend to use Kysely for migrations.

Kysely manages migrations using TypeScript files. Create a migration to create the `users` table using Kysely's schema builder.

1. Create a folder named `migrations` in your project's root directory:
   ```bash
   mkdir migrations
   ```

2. Create a file `migrations/001_create_users.ts`:

   ```typescript
   import { Kysely, sql } from 'kysely';

   export async function up(db: Kysely<any>): Promise<void> {
     await db.schema
       .createTable('users')
       .addColumn('id', 'serial', (col) => col.primaryKey())
       .addColumn('name', 'text', (col) => col.notNull())
       .addColumn('email', 'text', (col) => col.unique().notNull())
       .addColumn('created_at', 'timestamp', (col) => col.defaultTo(sql`now()`).notNull())
       .execute();
   }

   export async function down(db: Kysely<any>): Promise<void> {
     await db.schema.dropTable('users').execute();
   }
   ```

3. Create a script to run the migration, `src/migrate.ts`. In Kysely 0.29 and later, `Migrator` and `FileMigrationProvider` are imported from `kysely/migration`.

   ```typescript
   import * as path from 'path';
   import { promises as fs } from 'fs';
   import { fileURLToPath } from 'url';
   import { Migrator, FileMigrationProvider } from 'kysely/migration';
   import { db } from './db.ts';

   const __filename = fileURLToPath(import.meta.url);
   const __dirname = path.dirname(__filename);

   async function migrateToLatest() {
     const migrator = new Migrator({
       db,
       provider: new FileMigrationProvider({
         fs,
         path,
         migrationFolder: path.join(__dirname, '../migrations'),
       }),
     });

     const { error, results } = await migrator.migrateToLatest();

     results?.forEach((it) => {
       if (it.status === 'Success') {
         console.log(`migration "${it.migrationName}" was executed successfully`);
       } else if (it.status === 'Error') {
         console.error(`failed to execute migration "${it.migrationName}"`);
       }
     });

     if (error) {
       console.error('failed to migrate');
       console.error(error);
       process.exit(1);
     }

     await db.destroy();
   }

   migrateToLatest();
   ```

4. Run the migration:
   ```bash
   npx tsx src/migrate.ts
   ```

## Query the database

Create a file `src/index.ts` to interact with your database. The following example demonstrates how to perform standard CRUD operations (Create, Read, Update, Delete) using Kysely.

```typescript
import { db } from './db.ts';

async function main() {
  try {
    // 1. Insert (Create)
    const { id } = await db
      .insertInto('users')
      .values({
        name: 'Neon User',
        email: `user-${Date.now()}@example.com`,
      })
      .returning('id')
      .executeTakeFirstOrThrow();

    console.log(`User created with ID: ${id}`);

    // 2. Select (Read)
    const users = await db.selectFrom('users').selectAll().execute();

    console.log('All users:', users);

    // 3. Update
    const updateResult = await db
      .updateTable('users')
      .set({ name: 'Updated Neon User' })
      .where('id', '=', id)
      .executeTakeFirst();

    console.log(`User updated. Rows affected: ${updateResult.numUpdatedRows}`);

    // 4. Delete
    const deleteResult = await db.deleteFrom('users').where('id', '=', id).executeTakeFirst();

    console.log(`User deleted. Rows affected: ${deleteResult.numDeletedRows}`);
  } catch (error) {
    console.error('Error querying the database:', error);
  } finally {
    // Close the connection
    await db.destroy();
  }
}

main();
```

Run the script using `tsx`:

```bash
npx tsx src/index.ts
```

You should see output indicating that the user was created and then fetched from the database.

```bash
$ npx tsx src/index.ts
User created with ID: 1
All users: [
  {
    id: 1,
    name: 'Neon User',
    email: 'user-1794150348648@example.com',
    created_at: 2026-11-08T15:05:48.648Z
  }
]
User updated. Rows affected: 1
User deleted. Rows affected: 1
```

For more advanced use cases, such as complex filters, joins, transactions, and subqueries, see the [Kysely documentation](https://kysely.dev/docs/intro).

## Learn more

- [Kysely Documentation](https://kysely.dev/docs/intro)
- [kysely-neon GitHub Repository](https://github.com/kysely-org/kysely-neon)
- [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver)

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/examples/kysely): Build fully-reactive realtime Kysely apps on Neon using your existing schema and queries »

--- [Document source](https://neon.com/docs/guides/laravel-migrations.md) ---

> Summary: Run Laravel schema migrations on Lakebase Postgres using the Eloquent ORM and `php artisan migrate`. Covers first-time setup and adding columns via new migration files. Neon requires a direct (non-pooled) connection string for migrations; pooled PgBouncer connections can cause migration errors.

# Schema migration with Lakebase Postgres and Laravel

Set up a database on Neon and run migrations for your Laravel project

Last updated: 2026-10-28

[Laravel](https://laravel.com/) is a popular PHP web application framework that provides an expressive and elegant syntax for building web applications. It includes an ORM (Object-Relational Mapping) called Eloquent, which allows you to interact with databases using a fluent API. Laravel also provides a powerful migration system to manage database schema changes over time.

This guide demonstrates how to use Laravel with the Lakebase Postgres database. We'll create a simple Laravel application and walk through the process of setting up the database, defining models, and generating and running migrations to manage schema changes.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- [PHP](https://www.php.net/) installed on your local machine. This guide uses PHP 8.1, but you can use any recent version compatible with Laravel.
- [Composer](https://getcomposer.org/) installed on your local machine for managing PHP dependencies.

## Setting up your Neon database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select a project or click the **New Project** button to create a new one.

### Retrieve your Neon database connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

**Important: Always use a direction connection for migrations**

Neon supports both direct and pooled database connection strings, which you can find by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. A pooled connection string connects your application to the database via a PgBouncer connection pool, allowing for a higher number of concurrent connections. However, using a pooled connection string for migrations can be prone to errors. For this reason, we recommend using a direct (non-pooled) connection when performing migrations. For more information about direct and pooled connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

Keep your connection string handy for later use.

## Setting up the Laravel project

### Create a new Laravel project

Open your terminal and navigate to the directory where you want to create your Laravel project. Run the following command to create a new Laravel project:

```bash
composer create-project --prefer-dist laravel/laravel guide-neon-laravel
```

This command creates a new Laravel project named `guide-neon-laravel` in the current directory.

### Set up the Database configuration

Open the `.env` file in the project root directory and update the following database connection variables:

```bash
DB_CONNECTION=pgsql
DB_PORT=5432
DATABASE_URL=NEON_POSTGRES_CONNECTION_STRING
```

Replace `NEON_POSTGRES_CONNECTION_STRING` with the connection string you retrieved from the Neon Console earlier. The `DB_CONNECTION` should be set to `pgsql` to indicate that we are using a Postgres database.

## Defining data models and running migrations

### Specify the data model

Data models are defined using the `Eloquent` ORM in Laravel. Our application is a simple catalog of authors and books, where each author can have multiple books. We'll create two models, `Author` and `Book`, to represent the data.

Create a new file `Author.php` in the `app/Models` directory with the following code:

```php
<?php

namespace App\Models;
use Illuminate\Database\Eloquent\Model;

class Author extends Model
{
    protected $fillable = ['name', 'bio'];
    public function books()
    {
        return $this->hasMany(Book::class);
    }
}
```

Create another file `Book.php` in the `app/Models` directory with the following code:

```php
<?php

namespace App\Models;
use Illuminate\Database\Eloquent\Model;

class Book extends Model
{
    protected $fillable = ['title', 'author_id'];
    public function author()
    {
        return $this->belongsTo(Author::class);
    }
}
```

The `Author` model represents an author with fields for name and bio. The `Book` model represents a book with fields for title and author (as a foreign key to the `Author` model). Laravel automatically creates an `id` field for each model as the primary key and manages the `created_at` and `updated_at` timestamps.

### Generate migration files

To generate migration files for creating the `authors` and `books` tables, run the following commands in the terminal:

```bash
php artisan make:migration create_authors_table
php artisan make:migration create_books_table
```

These commands generate empty migration files in the `database/migrations` directory. Unlike frameworks such as Django, Laravel does not generate the schema automatically based on the model definitions. Instead, you define the schema in the migration files.

Open the `create_authors_table` migration file and update the `up` method to define the table schema:

```php
public function up()
{
    Schema::create('authors', function (Blueprint $table) {
        $table->id();
        $table->string('name');
        $table->text('bio')->nullable();
        $table->timestamps();
    });
}
```

Similarly, open the `create_books_table` migration file and update the `up` method:

```php
public function up()
{
    Schema::create('books', function (Blueprint $table) {
        $table->id();
        $table->string('title');
        $table->unsignedBigInteger('author_id');
        $table->timestamps();

        $table->foreign('author_id')->references('id')->on('authors')->onDelete('cascade');
    });
}
```

### Apply the migration

To apply the migration and create the corresponding tables in the Lakebase Postgres database, run the following command:

```bash
php artisan migrate
```

This command executes the migration files and creates the `authors` and `books` tables in the database.

### Seed the database

To populate the database with some initial data, we use Laravel's database seeding feature. Open the file `DatabaseSeeder.php` in the `database/seeders` directory and replace its contents with the following code:

```php
<?php

namespace Database\Seeders;

use App\Models\Author;
use App\Models\Book;
use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    public function run(): void
    {
        $authors = [
            [
                'name' => 'J.R.R. Tolkien',
                'bio' => 'The creator of Middle-earth and author of The Lord of the Rings.',
                'books' => [
                    ['title' => 'The Fellowship of the Ring'],
                    ['title' => 'The Two Towers'],
                    ['title' => 'The Return of the King'],
                ],
            ],
            [
                'name' => 'George R.R. Martin',
                'bio' => 'The author of the epic fantasy series A Song of Ice and Fire.',
                'books' => [
                    ['title' => 'A Game of Thrones'],
                    ['title' => 'A Clash of Kings'],
                    ['title' => 'A Storm of Swords'],
                ],
            ],
            [
                'name' => 'J.K. Rowling',
                'bio' => 'The creator of the Harry Potter series.',
                'books' => [
                    ['title' => 'Harry Potter and the Philosopher\'s Stone'],
                    ['title' => 'Harry Potter and the Chamber of Secrets'],
                ],
            ],
        ];

        foreach ($authors as $authorData) {
            $author = Author::create([
                'name' => $authorData['name'],
                'bio' => $authorData['bio'],
            ]);

            foreach ($authorData['books'] as $bookData) {
                $author->books()->create($bookData);
            }
        }
    }
}
```

This seeder creates three authors and associates them with their corresponding books. To run this script and populate the database, run the following command in the terminal:

```bash
php artisan db:seed
```

## Implement the application

### Create routes and controllers

We'll create two routes and corresponding controllers to display the authors and books in our application.

Open the `routes/web.php` file and add the following routes:

```php
...

use App\Http\Controllers\AuthorController;
use App\Http\Controllers\BookController;

...

Route::get('/authors', [AuthorController::class, 'index'])->name('authors.index');
Route::get('/books/{author}', [BookController::class, 'index'])->name('books.index');
```

We define two routes: `/authors` to list all authors and `/books/{author}` to list books by a specific author.

Now, create a new file `AuthorController.php` in the `app/Http/Controllers` directory with the following code:

```php
<?php

namespace App\Http\Controllers;

use App\Models\Author;

class AuthorController extends Controller
{
    public function index()
    {
        $authors = Author::all();
        return response()->json($authors);
    }
}
```

Similarly, create another file `BookController.php` in the `app/Http/Controllers` directory with the following code:

```php
<?php

namespace App\Http\Controllers;

use App\Models\Author;

class BookController extends Controller
{
    public function index(Author $author)
    {
        $books = $author->books;
        return response()->json($books);
    }
}
```

These controllers define the `index` action to retrieve all authors and books by a specific author, respectively. The data is returned as JSON responses.

### Run the Laravel development server

To start the Laravel development server and test the application, run the following command:

```bash
php artisan serve
```

Navigate to the url `http://localhost:8000/authors` in your browser to view the list of authors. You can also view the books by a specific author by visiting `http://localhost:8000/books/{author_id}`.

## Applying schema changes

We will demonstrate how to handle schema changes by adding a new field `country` to the `Author` model, which will store the author's country of origin.

### Update the data model

Open the `Author.php` file in the `app/Models` directory and add the `country` field to the `$fillable` property:

```php
protected $fillable = ['name', 'bio', 'country'];
```

### Generate and run the migration

To generate a new migration file for the schema change, run the following command:

```bash
php artisan make:migration add_country_to_authors_table
```

This command generates a new migration file in the `database/migrations` directory.

Open the generated migration file and update the `up` method to add the new `country` column:

```php
public function up()
{
    Schema::table('authors', function (Blueprint $table) {
        $table->string('country')->nullable()->after('bio');
    });
}
```

Now, to apply the migration, run the following command:

```bash
php artisan migrate
```

### Test the schema change

Restart the Laravel development server:

```bash
php artisan serve
```

Navigate to the url `http://localhost:8000/authors` to view the list of authors. Each author entry now includes the `country` field set to `null`, reflecting the schema change.

## Conclusion

In this guide, we demonstrated how to set up a Laravel project with `Neon` Postgres, define database models using Eloquent, generate migrations, and run them. Laravel's Eloquent ORM and migration system make it easy to interact with the database and manage schema evolution over time.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Migrations with Neon and Laravel](https://github.com/neondatabase/guide-neon-laravel): Run Neon database migrations in a Laravel project

## Resources

For more information on the tools and concepts used in this guide, refer to the following resources:

- [Laravel Documentation](https://laravel.com/docs)
- [Neon](https://neon.com/docs)

--- [Document source](https://neon.com/docs/guides/laravel.md) ---

> Summary: Connect a Laravel application to Lakebase Postgres by setting the DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, and DB_PASSWORD variables in your .env file. Also covers the "endpoint ID is not specified" SNI error that affects older PDO_PGSQL or libpq drivers, with workarounds for passing the endpoint ID as a URL option or in the password field.

# Connect from Laravel to Neon

Set up a Neon project in seconds and connect from a Laravel application

Last updated: 2026-09-16

Pre-built prompt for connecting Laravel to Lakebase Postgres [View prompt](https://neon.com/prompts/laravel-prompt.md)

[Laravel](https://laravel.com/) is a PHP web application framework. Connecting to Neon from Laravel is the same as connecting to any Postgres database from Laravel. Only the connection details differ.

To connect to Neon from Laravel:

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Configure the connection

Open the `.env` file in your Laravel app and replace the database settings. New Laravel projects use `DB_CONNECTION=sqlite` with the other `DB_*` lines commented out; replace them with the following:

```shell
DB_CONNECTION=pgsql
DB_HOST=[neon_hostname]
DB_PORT=5432
DB_DATABASE=[dbname]
DB_USERNAME=[user]
DB_PASSWORD=[password]
DB_SSLMODE=require
```

If you have a connection string (`postgresql://[user]:[password]@[neon_hostname]/[dbname]`), copy its parts into the matching variables. The pooled hostname (with `-pooler`) works with these settings.

You can find your database connection details by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Test the connection

Run Laravel's default migrations against your Neon database, then show the connection details:

```shell
php artisan migrate
php artisan db:show
```

`db:show` lists the Postgres version, your Neon host, and the tables the migrations created.

## Connection issues

With older Postgres clients/drivers, including older PDO_PGSQL drivers, you may receive the following error when attempting to connect to Neon:

```txt
ERROR: The endpoint ID is not specified. Either upgrade the Postgres client library (libpq) for SNI support or pass the endpoint ID (the first part of the domain name) as a parameter: '&options=endpoint%3D'. See [https://neon.com/sni](https://neon.com/sni) for more information.
```

If you run into this error, see the following for an explanation of the issue and workarounds: [The endpoint ID is not specified](https://neon.com/docs/connect/connection-errors#the-endpoint-id-is-not-specified).

- If using a connection string to connect to your database, try [Workaround A. Pass the endpoint ID as an option](https://neon.com/docs/connect/connection-errors#a-pass-the-endpoint-id-as-an-option). For example:

  ```text
  postgresql://[user]:[password]@[neon_hostname]/[dbname]?options=endpoint%3D[endpoint_id]
  ```

  Replace `[endpoint_id]` with your compute's endpoint ID, which you can find in your Neon connection string. It looks similar to this: `ep-cool-darkness-123456`.

- If using database connection parameters, as shown above, try [Workaround D. Specify the endpoint ID in the password field](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field). For example:

  ```text
  DB_PASSWORD=endpoint=<endpoint_id>$<password>
  ```

## Schema migration with Laravel

For schema migration with Laravel, see:

- [Laravel Migrations](https://neon.com/docs/guides/laravel-migrations): Schema migration with Lakebase Postgres and Laravel

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/liquibase-workflow.md) ---

> Summary: Iterate on XML changesets against an isolated Neon development branch, then promote reviewed changes to production using Liquibase update, status, diff, and updateSQL commands. Use this page when you need a repeatable branch-develop-promote schema migration pattern, not initial Liquibase setup. Neon's copy-on-write branching keeps development changes isolated until explicitly promoted.

# Liquibase developer workflow with Neon

Implement a developer workflow with Liquibase and Neon branching

Last updated: 2026-09-25

Liquibase is an open-source database-independent library for tracking, managing, and applying database schema changes. To learn more about Liquibase, refer to the [Liquibase documentation](https://docs.liquibase.com/home.html).

This guide shows how to set up a developer workflow using Liquibase with Neon's branching feature. The workflow involves making schema changes to a database on a development branch and applying those changes back to the source database on the production branch of your Neon project.

The instructions in this guide are based on the workflow described in the [Liquibase Developer Workflow](https://www.liquibase.org/get-started/developer-workflow) tutorial.

## Prerequisites

- A Neon account. See [Sign up](https://neon.com/docs/get-started/signing-up).
- A Neon project. See [Create your first project](https://neon.com/docs/get-started/signing-up).
- Liquibase requires Java. For Liquibase Java requirements, see [Requirements](https://docs.liquibase.com/start/install/liquibase-requirements.html). To check if you have Java installed, run `java --version`, or `java -version` on macOS.
- An installation of Liquibase. For instructions, refer to [Get started with Liquibase and Neon](https://neon.com/docs/guides/liquibase).

## Initialize a new Liquibase project

Run the [init project](https://docs.liquibase.com/commands/init/project.html) command to initialize a Liquibase project in the specified directory. The project directory is created if it does not exist. Initializing a Liquibase project in this way provides you with a pre-populated Liquibase properties file, which we'll modify in a later step.

```bash
liquibase init project --project-dir ~/blogdb
```

Enter `Y` to accept the defaults.

## Prepare a source database

For demonstration purposes, create a `blog` database in Neon with two tables, `posts` and `authors`.

1. Open the [Neon Console](https://console.neon.tech/app/projects).
2. Select your project.
3. Select **Postgres database** > **Databases** from the sidebar and create a database named `blog`. For instructions, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).
4. Using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), add the following tables:

   ```sql
   -- Creating the `authors` table
   CREATE TABLE authors (
       author_id SERIAL PRIMARY KEY,
       first_name VARCHAR(100),
       last_name VARCHAR(100),
       email VARCHAR(255) UNIQUE NOT NULL,
       bio TEXT
   );

   -- Creating the `posts` table
   CREATE TABLE posts (
       post_id SERIAL PRIMARY KEY,
       author_id INTEGER REFERENCES authors(author_id),
       title VARCHAR(255) NOT NULL,
       content TEXT,
       published_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
   ```

## Prepare a development database

Now, let's prepare a development database in Neon by creating a development branch, where you can safely make changes to your database schema without affecting the source database on your `production` branch. A branch is a copy-on-write clone of the data in your Neon project, so it will include a copy of the `blog` database with the `authors` and `posts` tables that you just created.

To create a branch:

1. In the Neon Console, select **Branches** in the sidebar. You will see your `production` branch, where you just created your `blog` database and tables.
2. Click **New Branch** to open the branch creation dialog.
3. Enter a name for the branch. Let's call it `feature/blog-schema`.
4. Leave `production` selected as the parent branch. This is where you created the `blog` database.
5. Leave the remaining default settings. Creating a branch from **Head** creates a branch with the latest data, and a compute is required to connect to the database on the branch.
6. Click **Create Branch** to create your branch.

## Retrieve your Neon database connection strings

From the [Neon Console](https://console.neon.tech/app/projects), retrieve connection strings for your target and source databases by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

**Note:** The target database is the database on your `feature/blog-schema` branch where you will do your development work. Your source database is where you will apply your schema changes later, once you are satisfied with the changes on your development branch.

1. Select the `feature/blog-schema` branch, the `blog` database, and copy the connection string.

   ```bash
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/blog?sslmode=require&channel_binding=require
   ```

2. Select the `production` branch, the `blog` database, and copy the connection string.

   ```bash
   postgresql://alex:AbC123dEf@ep-silent-hill-85675036.us-east-2.aws.neon.tech/blog?sslmode=require&channel_binding=require
   ```

Be careful not to mix up your connection strings. You'll see that the hostname (the part starting with `ep-` and ending in `neon.tech`) differs. This is because the `feature/blog-schema` branch is a separate instance of Postgres, hosted on its own compute.

**Important:** Use direct (non-pooled) connection strings with Liquibase. Neon's pooled connection uses PgBouncer in transaction mode, which doesn't support all session-level operations that schema migration tools rely on, so running migrations over a pooled connection can lead to errors. Make sure your connection strings do not include the `-pooler` suffix (turn the **Connection pooling** toggle off in the **Connect** modal). See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Update your liquibase.properties file

The `liquibase.properties` file defines the location of the Liquibase changelog file and your target and source databases.

1. From your Liquibase project directory, open the `liquibase.properties` file, which comes pre-populated with example settings.

2. Change the `changeLogFile` setting as shown:

   ```bash
   changeLogFile=dbchangelog.xml
   ```

   The [changelog file](https://docs.liquibase.com/parameters/changelog-file.html) is where you define database schema changes (changesets).

3. Change the target database `url`, `username`, and `password` settings to the correct values for the `blog` database on your `feature/blog-schema` branch. You can obtain the required details from the connection string you copied previously. You will need to swap out the hostname (`ep-cool-darkness-123456.us-east-2.aws.neon.tech`), username, and password for your own.

   ```bash
   liquibase.command.url=jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech:5432/blog

   liquibase.command.username: alex

   liquibase.command.password: AbC123dEf
   ```

4. Change the source database settings to the correct values for the `blog` database on your `production` branch. The username and password will be the same as your `feature/blog-schema` branch, but make sure to use the right hostname. Copy the snippet below and replace the hostname (`ep-silent-hill-85675036.us-east-2.aws.neon.tech`), username, and password for your own.

   ```bash
   liquibase.command.referenceUrl: jdbc:postgresql://ep-silent-hill-85675036.us-east-2.aws.neon.tech:5432/blog

   liquibase.command.referenceUsername: alex

   liquibase.command.referencePassword: AbC123dEf
   ```

## Take a snapshot of your target database

Capture the current state of your target database. The following command creates a Liquibase changelog file named `mydatabase_changelog.xml`.

```bash
liquibase --changeLogFile=mydatabase_changelog.xml generateChangeLog
```

If the command was successful, you'll see output similar to the following:

```bash
Starting Liquibase at 09:23:33 (version 4.24.0 #14062 built at 2023-09-28 12:18+0000)
Liquibase Version: 4.24.0
Liquibase Open Source 4.24.0 by Liquibase
BEST PRACTICE: The changelog generated by diffChangeLog/generateChangeLog should be inspected for correctness and completeness before being deployed. Some database objects and their dependencies cannot be represented automatically, and they may need to be manually updated before being deployed.
Generated changelog written to mydatabase_changelog.xml
Liquibase command 'generateChangelog' was executed successfully.
```

Check for the `mydatabase_changelog.xml` file in your Liquibase project directory. It should look something like this:

```xml
<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:pro="http://www.liquibase.org/xml/ns/pro" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
    <changeSet author="alex (generated)" id="1697977416317-1">
        <createTable tableName="authors">
            <column autoIncrement="true" name="author_id" type="INTEGER">
                <constraints nullable="false" primaryKey="true" primaryKeyName="authors_pkey"/>
            </column>
            <column name="first_name" type="VARCHAR(100)"/>
            <column name="last_name" type="VARCHAR(100)"/>
            <column name="email" type="VARCHAR(255)">
                <constraints nullable="false"/>
            </column>
            <column name="bio" type="TEXT"/>
        </createTable>
    </changeSet>
    <changeSet author="alex (generated)" id="1697977416317-2">
        <createTable tableName="posts">
            <column autoIncrement="true" name="post_id" type="INTEGER">
                <constraints nullable="false" primaryKey="true" primaryKeyName="posts_pkey"/>
            </column>
            <column name="author_id" type="INTEGER"/>
            <column name="title" type="VARCHAR(255)">
                <constraints nullable="false"/>
            </column>
            <column name="content" type="TEXT"/>
            <column defaultValueComputed="CURRENT_TIMESTAMP" name="published_date" type="TIMESTAMP WITHOUT TIME ZONE"/>
        </createTable>
    </changeSet>
    <changeSet author="alex (generated)" id="1697977416317-3">
        <addUniqueConstraint columnNames="email" constraintName="authors_email_key" tableName="authors"/>
    </changeSet>
    <changeSet author="alex (generated)" id="1697977416317-4">
        <addForeignKeyConstraint baseColumnNames="author_id" baseTableName="posts" constraintName="posts_author_id_fkey" deferrable="false" initiallyDeferred="false" onDelete="NO ACTION" onUpdate="NO ACTION" referencedColumnNames="author_id" referencedTableName="authors" validate="true"/>
    </changeSet>
</databaseChangeLog>
```

## Create a schema change

Now, you can start making database schema changes by creating [changesets](https://docs.liquibase.com/concepts/changelogs/changeset.html) and adding them to the changelog file you defined in your `liquibase.properties` file. A changeset is the basic unit of change in Liquibase.

1. Create the changelog file where you will add your schema changes:

   ```bash
   cd ~/blogdb
   touch dbchangelog.xml
   ```

2. Add the following changeset to the `dbchangelog.xml` file, which adds a `comments` table to your database:

   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
   <databaseChangeLog
   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:pro="http://www.liquibase.org/xml/ns/pro"
   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.4.xsd
       http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-4.5.xsd">
       <changeSet author="alex" id="myIDNumber1234">
           <createTable tableName="comments">
               <column autoIncrement="true" name="comment_id" type="INTEGER">
                   <constraints nullable="false" primaryKey="true" primaryKeyName="comments_pkey"/>
               </column>
               <column name="post_id" type="INTEGER">
                   <constraints nullable="false" foreignKeyName="fk_comments_post_id" referencedTableName="posts" referencedColumnNames="post_id"/>
               </column>
               <column name="author_id" type="INTEGER">
                   <constraints nullable="false" foreignKeyName="fk_comments_author_id" referencedTableName="authors" referencedColumnNames="author_id"/>
               </column>
               <column name="comment" type="TEXT"/>
               <column name="commented_date" type="TIMESTAMP" defaultValueComputed="CURRENT_TIMESTAMP"/>
           </createTable>
       </changeSet>
   </databaseChangeLog>
   ```

### Deploy the schema change

Run the [update](https://docs.liquibase.com/commands/update/update.html) command to deploy the schema change to your target database (your development database on the `feature/blog-schema` branch).

```bash
liquibase update
```

If the command was successful, you'll see output similar to the following:

```bash
Starting Liquibase at 10:11:35 (version 4.24.0 #14062 built at 2023-09-28 12:18+0000)
Liquibase Version: 4.24.0
Liquibase Open Source 4.24.0 by Liquibase
Running Changeset: dbchangelog.xml::myIDNumber1234::alex

UPDATE SUMMARY
Run:                          1
Previously run:               0
Filtered out:                 0
-------------------------------
Total change sets:            1

Liquibase: Update has been successful. Rows affected: 1
Liquibase command 'update' was executed successfully.
```

**Info:**

When you run a changeset for the first time, Liquibase automatically creates two tracking tables in your database:

- [databasechangelog](https://docs.liquibase.com/concepts/tracking-tables/databasechangelog-table.html): Tracks which changesets have been run.
- [databasechangeloglock](https://docs.liquibase.com/concepts/tracking-tables/databasechangeloglock-table.html): Ensures only one instance of Liquibase runs at a time.

You can verify these tables were created by viewing the `blog` database on your `feature/blog-schema` branch on the **Tables** page in the Neon Console. Select **Postgres database** > **Tables** from the sidebar.

At this point, you can continue to iterate, applying schema changes to your database, until you are satisfied with the modified schema.

### Review schema changes

It is a best practice to review schema changes before saving and applying them to your source database.

You can run the [status](https://docs.liquibase.com/commands/change-tracking/status.html) command to see if there are any changesets that haven't been applied to the source database. Notice that the command specifies the hostname of the source database:

```bash
liquibase --url=jdbc:postgresql://ep-silent-hill-85675036.us-east-2.aws.neon.tech:5432/blog status --verbose
```

<details>

<summary>Command output</summary>

If the command was successful, you'll see output similar to the following indicating that there is one changeset that has not been applied to the source database. This is your `comments` table changeset.

```bash
Starting Liquibase at 12:30:51 (version 4.24.0 #14062 built at 2023-09-28 12:18+0000)
Liquibase Version: 4.24.0
Liquibase Open Source 4.24.0 by Liquibase
1 changesets have not been applied to alex@jdbc:postgresql://ep-silent-hill-85675036.us-east-2.aws.neon.tech:5432/blog
     dbchangelog.xml::myIDNumber1234::alex
Liquibase command 'status' was executed successfully.
```

</details>

### Check your SQL

Before applying the update, you can run the [updateSQL](https://docs.liquibase.com/commands/update/update-sql.html) command to inspect the SQL Liquibase will apply when running the update command:

```bash
liquibase --url=jdbc:postgresql://ep-silent-hill-85675036.us-east-2.aws.neon.tech:5432/blog updateSQL
```

<details>

<summary>Command output</summary>

If the command was successful, you'll see output similar to the following, which confirms that the changeset will create a `comments` table.

```bash
Starting Liquibase at 12:32:55 (version 4.24.0 #14062 built at 2023-09-28 12:18+0000)
Liquibase Version: 4.24.0
Liquibase Open Source 4.24.0 by Liquibase
SET SEARCH_PATH TO public, "$user","public";

-- Lock Database

UPDATE public.databasechangeloglock SET LOCKED = TRUE, LOCKEDBY = 'dot-VBox (10.0.2.15)', LOCKGRANTED = NOW() WHERE ID = 1 AND LOCKED = FALSE;

SET SEARCH_PATH TO public, "$user","public";
SET SEARCH_PATH TO public, "$user","public";

-- *********************************************************************
-- Update Database Script
-- *********************************************************************
-- Change Log: dbchangelog.xml
-- Ran at: 2023-10-08, 12:32 p.m.
-- Against: alex@jdbc:postgresql://ep-silent-hill-85675036.us-east-2.aws.neon.tech:5432/blog
-- Liquibase version: 4.24.0
-- *********************************************************************

SET SEARCH_PATH TO public, "$user","public";

-- Changeset dbchangelog.xml::myIDNumber1234::alex
SET SEARCH_PATH TO public, "$user","public";

CREATE TABLE public.comments (comment_id INTEGER GENERATED BY DEFAULT AS IDENTITY NOT NULL, post_id INTEGER NOT NULL, author_id INTEGER NOT NULL, comment TEXT, commented_date TIMESTAMP WITHOUT TIME ZONE DEFAULT NOW(), CONSTRAINT comments_pkey PRIMARY KEY (comment_id), CONSTRAINT fk_comments_author_id FOREIGN KEY (author_id) REFERENCES public.authors(author_id), CONSTRAINT fk_comments_post_id FOREIGN KEY (post_id) REFERENCES public.posts(post_id));

INSERT INTO public.databasechangelog (ID, AUTHOR, FILENAME, DATEEXECUTED, ORDEREXECUTED, MD5SUM, DESCRIPTION, COMMENTS, EXECTYPE, CONTEXTS, LABELS, LIQUIBASE, DEPLOYMENT_ID) VALUES ('myIDNumber1234', 'AlexL', 'dbchangelog.xml', NOW(), 1, '9:788a502d77d56330d53b6b356ee205ce', 'createTable tableName=comments', '', 'EXECUTED', NULL, NULL, '4.24.0', NULL);

-- Release Database Lock
SET SEARCH_PATH TO public, "$user","public";
UPDATE public.databasechangeloglock SET LOCKED = FALSE, LOCKEDBY = NULL, LOCKGRANTED = NULL WHERE ID = 1;
SET SEARCH_PATH TO public, "$user","public";

Liquibase command 'updateSql' was executed successfully.
```

</details>

### Run a diff command

You can also run a `diff` command to compare your source and target databases.

```bash
liquibase --referenceUrl=jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech:5432/blog --referenceUsername alex --referencePassword IwMdnTs1R6kH diff
```

<details>

<summary>Command output</summary>

If the command was successful, you'll see output similar to the following:

```bash
Starting Liquibase at 12:34:20 (version 4.24.0 #14062 built at 2023-09-28 12:18+0000)
Liquibase Version: 4.24.0
Liquibase Open Source 4.24.0 by Liquibase

Diff Results:

Reference Database: alex @ jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech:5432/blog (Default Schema: public)
Comparison Database: alex @ jdbc:postgresql://ep-silent-hill-85675036.us-east-2.aws.neon.tech:5432/blog (Default Schema: public)
Compared Schemas: public
Product Name: EQUAL
Product Version: EQUAL
Missing Catalog(s): NONE
Unexpected Catalog(s): NONE
Changed Catalog(s): NONE
Missing Column(s): NONE
Unexpected Column(s):
     public.comments.author_id
     public.comments.comment
     public.comments.comment_id
     public.comments.commented_date
     public.comments.post_id
Changed Column(s): NONE
Missing Foreign Key(s): NONE
Unexpected Foreign Key(s):
     fk_comments_author_id(comments[author_id] -> authors[author_id])
     fk_comments_post_id(comments[post_id] -> posts[post_id])
Changed Foreign Key(s): NONE
Missing Index(s): NONE
Unexpected Index(s):
     comments_pkey UNIQUE  ON public.comments(comment_id)
Changed Index(s): NONE
Missing Primary Key(s): NONE
Unexpected Primary Key(s):
     comments_pkey on public.comments(comment_id)
Changed Primary Key(s): NONE
Missing Schema(s): NONE
Unexpected Schema(s): NONE
Changed Schema(s): NONE
Missing Sequence(s): NONE
Unexpected Sequence(s): NONE
Changed Sequence(s): NONE
Missing Table(s): NONE
Unexpected Table(s):
     comments
Changed Table(s): NONE
Missing Unique Constraint(s): NONE
Unexpected Unique Constraint(s): NONE
Changed Unique Constraint(s): NONE
Missing View(s): NONE
Unexpected View(s): NONE
Changed View(s): NONE
Liquibase command 'diff' was executed successfully.
```

</details>

### Save your changelog to source control

When you are satisfied with the changes that will be applied, save your changelog to source control, such as a GitHub repository where you or your team stores you changelog.

### Apply the changeset to your source database

Apply the new changesets to the source database on your default branch:

```bash
liquibase --url=jdbc:postgresql://ep-silent-hill-85675036.us-east-2.aws.neon.tech:5432/blog update
```

<details>

<summary>Command output</summary>

If the command was successful, you'll see output similar to the following:

```bash
Starting Liquibase at 12:36:56 (version 4.24.0 #14062 built at 2023-09-28 12:18+0000)
Liquibase Version: 4.24.0
Liquibase Open Source 4.24.0 by Liquibase
Running Changeset: dbchangelog.xml::myIDNumber1234::AlexL

UPDATE SUMMARY
Run:                          1
Previously run:               0
Filtered out:                 0
-------------------------------
Total change sets:            1

Liquibase: Update has been successful. Rows affected: 1
Liquibase command 'update' was executed successfully.
```

</details>

To ensure that all changes have been applied to the production database, you can rerun the `status`, `updatedSql`, and `diff` commands you ran above. After applying the change, there should be no differences. You can also check your databases in the **Tables** view in the Neon Console to verify that the source database now has a `comments` table.

**Note:** When you run a changeset for the first time on the source database, you will find that Liquibase automatically creates the [databasechangelog](https://docs.liquibase.com/concepts/tracking-tables/databasechangelog-table.html) and [databasechangeloglock](https://docs.liquibase.com/concepts/tracking-tables/databasechangeloglock-table.html) tracking tables that were created in your development database. These tracking tables are created on any database where you apply changesets.

## References

- [Get started with Liquibase](https://www.liquibase.org/get-started/quickstart)
- [Setting up your Liquibase Workspace](https://www.liquibase.org/get-started/setting-up-your-workspace)
- [Liquibase Developer Workflow](https://www.liquibase.org/get-started/developer-workflow)

--- [Document source](https://neon.com/docs/guides/liquibase.md) ---

> Summary: Connect Liquibase to a Lakebase Postgres database over JDBC to track, deploy, and roll back versioned schema changes defined in XML changelog files. Use this guide when you need to version-control DDL changes against Neon with a repeatable deploy-and-rollback workflow. Covers the liquibase.properties JDBC URL format for Neon and demonstrates the update and rollbackCount commands.

# Get started with Liquibase and Neon

Learn how to manage schema changes in Neon with Liquibase

Last updated: 2026-09-16

Liquibase is an open-source library for tracking, managing, and applying database schema changes. To learn more about Liquibase, refer to the [Liquibase documentation](https://docs.liquibase.com/home.html).

This guide steps you through installing the Liquibase CLI, configuring Liquibase to connect to a Lakebase Postgres database, deploying a database schema change, and rolling back the schema change. The guide follows the setup described in the [Liquibase Get Started](https://www.liquibase.org/get-started/quickstart).

## Prerequisites

- A Neon account. See [Sign up](https://neon.com/docs/get-started/signing-up).
- A Neon project. See [Create your first project](https://neon.com/docs/get-started/signing-up).
- Liquibase requires Java. For Liquibase Java requirements, see [Requirements](https://docs.liquibase.com/start/install/liquibase-requirements.html). To check if you have Java installed, run `java --version`, or `java -version` on macOS.

## Download and extract Liquibase

1. Download the Liquibase CLI from [https://www.liquibase.com/download](https://www.liquibase.com/download).

2. Extract the Liquibase files. For example:

   ```bash
   cd ~/Downloads
   mkdir ~/liquibase
   tar -xzvf liquibase-x.yy.z.tar.gz -C ~/liquibase/
   ```

3. Open a command prompt to view the contents of your Liquibase installation:

   ```bash
   cd ~/liquibase
   ls
   ABOUT.txt      GETTING_STARTED.txt  licenses     liquibase.bat
   changelog.txt  internal             LICENSE.txt  README.txt
   examples       lib                  liquibase    UNINSTALL.txt
   ```

## Set your path variable

Add the Liquibase directory to your `PATH` so that you can run Liquibase commands from any location.

**bashrc**

```bash
echo 'export PATH=$PATH:/path/to/liquibase' >> ~/.bashrc
source ~/.bashrc
```

**profile**

```bash
echo 'export PATH=$PATH:/path/to/liquibase' >> ~/.profile
source ~/.profile
```

**zsh**

```bash
echo 'export PATH=$PATH:/path/to/liquibase' >> ~/.zshrc
source ~/.zshrc
```

## Verify your installation

Verify that the Liquibase installation was successful by running the following command:

```bash
liquibase --version
...
Liquibase Version: x.yy.z
Liquibase Open Source x.yy.z by Liquibase
```

## Prepare a Neon database

For demonstration purposes, create a `blog` database in Neon with two tables, `posts` and `authors`.

1. Open the [Neon Console](https://console.neon.tech/app/projects).
2. Select your project.
3. Select **Postgres database** > **Databases** from the sidebar and create a database named `blog`. For instructions, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).
4. Using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), add the following tables:

   ```sql
   -- Creating the `authors` table
   CREATE TABLE authors (
       author_id SERIAL PRIMARY KEY,
       first_name VARCHAR(100),
       last_name VARCHAR(100),
       email VARCHAR(255) UNIQUE NOT NULL,
       bio TEXT
   );

   -- Creating the `posts` table
   CREATE TABLE posts (
       post_id SERIAL PRIMARY KEY,
       author_id INTEGER REFERENCES authors(author_id),
       title VARCHAR(255) NOT NULL,
       content TEXT,
       published_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
   ```

## Retrieve your Neon database connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Use the selection drop-down menu.

Your Java connection string should look something like the one shown below.

```bash
jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech/blog?user=alex&password=AbC123dEf
```

**Important:** Use a direct (non-pooled) connection string with Liquibase. Neon's pooled connection uses PgBouncer in transaction mode, which doesn't support all session-level operations that schema migration tools rely on, so running migrations over a pooled connection can lead to errors. Make sure the hostname does not include the `-pooler` suffix (turn the **Connection pooling** toggle off in the **Connect** modal). See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Connect from Liquibase to your Neon database

1. Create a directory for your Liquibase project. For example:

   ```bash
   mkdir blogdb
   ```

2. Change to your project directory and create a `liquibase.properties` file.

   ```bash
   cd blogdb
   touch liquibase.properties
   ```

3. Open the `liquibase.properties` file in an editor and add entries for a [liquibase changelog file](https://docs.liquibase.com/concepts/changelogs/home.html) and your database `url`. We'll call the changelog file `dbchangelog.xml`. You will use this file to define schema changes. For the `url`, specify the Neon connection string you retrieved previously.

   ```bash
   changeLogFile:dbchangelog.xml
   url: jdbc:postgresql://ep-cool-darkness-123456.us-east-2.aws.neon.tech/blog?user=alex&password=AbC123dEf&sslmode=require&channel_binding=require
   ```

## Take a snapshot of your database

In this step, you will run the [generateChangelog](https://docs.liquibase.com/commands/inspection/generate-changelog.html) command in your project directory to create a changelog file with the current state of your database. We'll call this file `mydatabase_changelog.xml`.

```bash
liquibase --changeLogFile=mydatabase_changelog.xml generateChangeLog
```

You'll get a changelog file for your database that looks something like this:

```xml
<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:pro="http://www.liquibase.org/xml/ns/pro" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-latest.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd">
    <changeSet author="alex (generated)" id="1697969580160-1">
        <createTable tableName="authors">
            <column autoIncrement="true" name="author_id" type="INTEGER">
                <constraints nullable="false" primaryKey="true" primaryKeyName="authors_pkey"/>
            </column>
            <column name="first_name" type="VARCHAR(100)"/>
            <column name="last_name" type="VARCHAR(100)"/>
            <column name="email" type="VARCHAR(255)">
                <constraints nullable="false"/>
            </column>
            <column name="bio" type="TEXT"/>
        </createTable>
    </changeSet>
    <changeSet author="alex (generated)" id="1697969580160-2">
        <createTable tableName="posts">
            <column autoIncrement="true" name="post_id" type="INTEGER">
                <constraints nullable="false" primaryKey="true" primaryKeyName="posts_pkey"/>
            </column>
            <column name="author_id" type="INTEGER"/>
            <column name="title" type="VARCHAR(255)">
                <constraints nullable="false"/>
            </column>
            <column name="content" type="TEXT"/>
            <column defaultValueComputed="CURRENT_TIMESTAMP" name="published_date" type="TIMESTAMP WITHOUT TIME ZONE"/>
        </createTable>
    </changeSet>
    <changeSet author="alex (generated)" id="1697969580160-3">
        <addUniqueConstraint columnNames="email" constraintName="authors_email_key" tableName="authors"/>
    </changeSet>
    <changeSet author="alex (generated)" id="1697969580160-4">
        <addForeignKeyConstraint baseColumnNames="author_id" baseTableName="posts" constraintName="posts_author_id_fkey" deferrable="false" initiallyDeferred="false" onDelete="NO ACTION" onUpdate="NO ACTION" referencedColumnNames="author_id" referencedTableName="authors" validate="true"/>
    </changeSet>
</databaseChangeLog>
```

## Create a schema change

Now, you can start making database schema changes by creating [changesets](https://docs.liquibase.com/concepts/changelogs/changeset.html) and adding them to the database changelog file you defined in your `liquibase.properties` file. A changeset is the basic unit of change in Liquibase.

1. Create the changelog file where you will add your schema changes:

   ```bash
   cd ~/blogdb
   touch dbchangelog.xml
   ```

2. Add the following changeset, which adds a `comments` table to your database. Replace `author="alex" id="myIDNumber1234"` with your author name and id, which you can retrieve from your changelog file, described in the previous step.

   ```xml
   <?xml version="1.0" encoding="UTF-8"?>
   <databaseChangeLog
   xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns:pro="http://www.liquibase.org/xml/ns/pro"
   xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.4.xsd
       http://www.liquibase.org/xml/ns/pro http://www.liquibase.org/xml/ns/pro/liquibase-pro-4.5.xsd">
       <changeSet author="alex" id="myIDNumber1234">
           <createTable tableName="comments">
               <column autoIncrement="true" name="comment_id" type="INTEGER">
                   <constraints nullable="false" primaryKey="true" primaryKeyName="comments_pkey"/>
               </column>
               <column name="post_id" type="INTEGER">
                   <constraints nullable="false" foreignKeyName="fk_comments_post_id" referencedTableName="posts" referencedColumnNames="post_id"/>
               </column>
               <column name="author_id" type="INTEGER">
                   <constraints nullable="false" foreignKeyName="fk_comments_author_id" referencedTableName="authors" referencedColumnNames="author_id"/>
               </column>
               <column name="comment" type="TEXT"/>
               <column name="commented_date" type="TIMESTAMP" defaultValueComputed="CURRENT_TIMESTAMP"/>
           </createTable>
       </changeSet>
   </databaseChangeLog>
   ```

## Deploy your change

Deploy your database schema change by running the [update](https://docs.liquibase.com/commands/update/update.html) command:

```bash
liquibase update
```

<details>

<summary>Command output</summary>

If the command was successful, you'll see output similar to the following:

```bash
Starting Liquibase at 07:33:53 (version 4.24.0 #14062 built at 2023-09-28 12:18+0000)
Liquibase Version: 4.24.0
Liquibase Open Source 4.24.0 by Liquibase
Running Changeset: dbchangelog.xml::myIDNumber1234::AlexL

UPDATE SUMMARY
Run:                          1
Previously run:               0
Filtered out:                 0
-------------------------------
Total change sets:            1

Liquibase: Update has been successful. Rows affected: 1
Liquibase command 'update' was executed successfully.
```

</details>

**Info:**

When you run a changeset for the first time, Liquibase automatically creates two tracking tables in your database:

- [databasechangelog](https://docs.liquibase.com/concepts/tracking-tables/databasechangelog-table.html): Tracks which changesets have been run.
- [databasechangeloglock](https://docs.liquibase.com/concepts/tracking-tables/databasechangeloglock-table.html): Ensures only one instance of Liquibase runs at a time.

You can verify these tables were created by viewing the `blog` database on the **Tables** page in the Neon Console. Select **Postgres database** > **Tables** from the sidebar.

## Rollback a change

Try rolling back your last change by running the Liquibase [rollbackCount](https://docs.liquibase.com/commands/rollback/rollback-count.html) command:

```bash
liquibase rollbackCount 1
```

<details>

<summary>Command output</summary>

If the command was successful, you'll see output similar to the following:

```bash
Starting Liquibase at 07:36:22 (version 4.24.0 #14062 built at 2023-09-28 12:18+0000)
Liquibase Version: 4.24.0
Liquibase Open Source 4.24.0 by Liquibase
Rolling Back Changeset: dbchangelog.xml::myIDNumber1234::AlexL
Liquibase command 'rollbackCount' was executed successfully.
```

</details>

You can verify that creation of the `comments` table was rolled back viewing the `blog` database on the **Tables** page in the Neon Console. Select **Postgres database** > **Tables** from the sidebar.

## Next steps

Learn how to use Liquibase with Neon's database branching feature to set up a developer workflow. See [Set up a developer workflow with Liquibase and Neon](https://neon.com/docs/guides/liquibase-workflow).

## References

- [Get started with Liquibase](https://www.liquibase.org/get-started/quickstart)
- [Setting up your Liquibase Workspace](https://www.liquibase.org/get-started/setting-up-your-workspace)
- [Liquibase Developer Workflow](https://www.liquibase.org/get-started/developer-workflow)

--- [Document source](https://neon.com/docs/guides/logical-replication-airbyte-snowflake.md) ---

> Summary: Set up a Lakebase Postgres-to-Snowflake CDC pipeline using Airbyte's Postgres connector with the pgoutput plugin. Covers logical replication setup, replication slot and publication creation, Airbyte source configuration, and Snowflake destination provisioning. Enabling logical replication permanently sets wal_level to logical for all databases in the Neon project.

# Replicate data to Snowflake with Airbyte

Learn how to replicate data from Neon to Snowflake with Airbyte

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations. In this guide, you will learn how to define your Lakebase Postgres database as a data source in Airbyte so that you can stream data to Snowflake.

[Airbyte](https://airbyte.com/) is an open-source data integration platform that moves data from a source to a destination system. Airbyte offers a large library of connectors for various data sources and destinations.

[Snowflake](https://www.snowflake.com/) is a cloud-based data warehousing and analytics platform designed to handle large volumes of data. Snowflake allows businesses to store, process, and analyze data from various sources.

## Prerequisites

- A source [Neon project](https://neon.com/docs/manage/projects#create-a-project) with a database containing the data you want to replicate. If you're just testing this out and need some data to play with, you run the following statements from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or an SQL client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) to create a table with sample data:

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- An [Airbyte account](https://airbyte.com/)

- A [Snowflake account](https://www.snowflake.com/)

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Prepare your source Neon database

This section describes how to prepare your source Neon database (the publisher) for replicating data.

### Enable logical replication in Neon

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, meaning active connections will be dropped and have to reconnect.

To enable logical replication in Neon:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or an SQL client such as [psql](https://neon.com/docs/connect/query-with-psql-editor):

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

### Create a Postgres role for replication

It's recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/reference/api/branches/create-project-branch-role)

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

### Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a replication slot

Airbyte requires a dedicated replication slot. Only one source should be configured to use this replication slot.

Airbyte uses the `pgoutput` plugin in Postgres for decoding WAL changes into a logical replication stream. To create a replication slot called `airbyte_slot` that uses the `pgoutput` plugin, run the following command on your database using your replication role:

```sql
SELECT pg_create_logical_replication_slot('airbyte_slot', 'pgoutput');
```

`airbyte_slot` is the name assigned to the replication slot. You will need to provide this name when you set up your Airbyte source.

### Create a publication

Perform the following steps for each table you want to replicate data from:

1. Add the replication identity (the method of distinguishing between rows) for each table you want to replicate:

   ```sql
   ALTER TABLE <table_name> REPLICA IDENTITY DEFAULT;
   ```

   In rare cases, if your tables use data types that support [TOAST](https://www.postgresql.org/docs/current/storage-toast.html) or have very large field values, consider using `REPLICA IDENTITY FULL` instead:

   ```sql
   ALTER TABLE <table_name> REPLICA IDENTITY FULL;
   ```

2. Create the Postgres publication. Include all tables you want to replicate as part of the publication:

   ```sql
   CREATE PUBLICATION airbyte_publication FOR TABLE <tbl1, tbl2, tbl3>;
   ```

   The publication name is customizable. Refer to the [Postgres docs](https://www.postgresql.org/docs/current/logical-replication-publication.html) if you need to add or remove tables from your publication.

**Note:** The Airbyte UI currently allows selecting any table for Change Data Capture (CDC). If a table is selected that is not part of the publication, it will not be replicated even though it is selected. If a table is part of the publication but does not have a replication identity, the replication identity will be created automatically on the first run if the Postgres role you use with Airbyte has the necessary permissions.

## Create a Postgres source in Airbyte

1. From your Airbyte Cloud account, select **Sources** from the left navigation bar, search for **Postgres**, and then create a new Postgres source.

2. Enter the connection details for your Neon database. You can find your database connection details by clicking the **Connect** button in the Console nav. Use a direct connection to your compute endpoint, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers, so make sure the connection string does not include `-pooler` in the hostname. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).
   For example, given a connection string like this:

   ```bash
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   Enter the details in the Airbyte **Create a source** dialog as shown below. Your values will differ.

   - **Host**: ep-cool-darkness-123456.us-east-2.aws.neon.tech
   - **Port**: 5432
   - **Database Name**: dbname
   - **Username**: replication_user
   - **Password**: AbC123dEf

   ![Airbyte Create a source](https://neon.com/docs/guides/airbyte_create_source.png)

3. Under **Optional fields**, list the schemas you want to sync. Schema names are case-sensitive, and multiple schemas may be specified. By default, `public` is the only selected schema.

4. Select an SSL mode. You will most frequently choose `require` or `verify-ca`. Both of these options always require encryption. The `verify-ca` mode requires a certificate. Refer to [Connect securely](https://neon.com/docs/connect/connect-securely) for information about the location of certificate files you can use with Neon.

5. Under **Advanced**:
   - Select **Read Changes using Write-Ahead Log (CDC)** from available replication methods.
   - In the **Replication Slot** field, enter the name of the replication slot you created previously: `airbyte_slot`.
   - In the **Publication** field, enter the name of the publication you created previously: `airbyte_publication`.
     ![Airbyte advanced fields](https://neon.com/docs/guides/airbyte_cdc_advanced_fields.png)

### Allow inbound traffic

If you are on Airbyte Cloud, and you are using Neon's **IP Allow** feature to limit IP addresses that can connect to Neon, you will need to allow inbound traffic from Airbyte's IP addresses. You can find a list of IPs that need to be allowlisted in the [Airbyte Security docs](https://docs.airbyte.com/operating-airbyte/security). For information about configuring allowed IPs in Neon, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

### Complete the source setup

To complete your source setup, click **Set up source** in the Airbyte UI. Airbyte will test the connection to your database. Once this succeeds, you've successfully configured an Airbyte Postgres source for your Neon database.

## Configure Snowflake as a destination

To complete your data integration setup, you can now add Snowflake as your destination.

### Prerequisites

- A Snowflake account with the `ACCOUNTADMIN` role. If you're using a company account, you may need to contact your Snowflake administrator to set one up for you.

### Set up Airbyte entities in Snowflake

To set up the Snowflake destination connector, you first need to create Airbyte entities in Snowflake (a warehouse, database, schema, user, and role) with the `OWNERSHIP` permission to write data to Snowflake.

You can use the following script in a new [Snowflake worksheet](https://docs.snowflake.com/en/user-guide/ui-worksheet) to create the entities. This script is provided as part of [Airbyte's Snowflake connector setup guide](https://docs.airbyte.com/integrations/destinations/snowflake#setup-guide).

**Note:** If you want, you can edit the script to change the password to a more secure password and to change the names of other resources. If you do rename entities, make sure to follow [Snowflake identifier requirements](https://docs.snowflake.com/en/sql-reference/identifiers-syntax).

```sql
-- set variables (these need to be uppercase)
set airbyte_role = 'AIRBYTE_ROLE';
set airbyte_username = 'AIRBYTE_USER';
set airbyte_warehouse = 'AIRBYTE_WAREHOUSE';
set airbyte_database = 'AIRBYTE_DATABASE';
set airbyte_schema = 'AIRBYTE_SCHEMA';

-- set user password
set airbyte_password = 'password';

begin;

-- create Airbyte role
use role securityadmin;
create role if not exists identifier($airbyte_role);
grant role identifier($airbyte_role) to role SYSADMIN;

-- create Airbyte user
create user if not exists identifier($airbyte_username)
password = $airbyte_password
default_role = $airbyte_role
default_warehouse = $airbyte_warehouse;

grant role identifier($airbyte_role) to user identifier($airbyte_username);

-- change role to sysadmin for warehouse / database steps
use role sysadmin;

-- create Airbyte warehouse
create warehouse if not exists identifier($airbyte_warehouse)
warehouse_size = xsmall
warehouse_type = standard
auto_suspend = 60
auto_resume = true
initially_suspended = true;

-- create Airbyte database
create database if not exists identifier($airbyte_database);

-- grant Airbyte warehouse access
grant USAGE
on warehouse identifier($airbyte_warehouse)
to role identifier($airbyte_role);

-- grant Airbyte database access
grant OWNERSHIP
on database identifier($airbyte_database)
to role identifier($airbyte_role);

commit;

begin;

USE DATABASE identifier($airbyte_database);

-- create schema for Airbyte data
CREATE SCHEMA IF NOT EXISTS identifier($airbyte_schema);

commit;

begin;

-- grant Airbyte schema access
grant OWNERSHIP
on schema identifier($airbyte_schema)
to role identifier($airbyte_role);

commit;
```

### Set up Snowflake as a destination

To set up a new destination:

1. Navigate to Airbyte.
2. Select **New destination**.
3. Select the Snowflake connector.
4. Create the destination by filling in the required fields. You can authenticate using username/password or key pair authentication. We'll authenticate via username/password.

| Field         | Description                                                                                                                              | Example                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| **Host**      | The host domain of the Snowflake instance (must include the account, region, cloud environment, and end with `snowflakecomputing.com`).  | `<accountname>.us-east-2.aws.snowflakecomputing.com` |
| **Role**      | The role you created for Airbyte to access Snowflake.                                                                                    | `AIRBYTE_ROLE`                                       |
| **Warehouse** | The warehouse you created for Airbyte to sync data into.                                                                                 | `AIRBYTE_WAREHOUSE`                                  |
| **Database**  | The database you created for Airbyte to sync data into.                                                                                  | `AIRBYTE_DATABASE`                                   |
| **Schema**    | The default schema used as the target schema for all statements issued from the connection that do not explicitly specify a schema name. | -                                                    |
| **Username**  | The username you created to allow Airbyte to access the database.                                                                        | `AIRBYTE_USER`                                       |
| **Password**  | The password associated with the username.                                                                                               | -                                                    |

When you're finished filling in the required fields, click **Set up destination**.

![Airbyte Snowflake destination](https://neon.com/docs/guides/airbyte_snowflake_destination.png)

## Set up a connection

In this step, you'll set up a connection between your Lakebase Postgres source and your Snowflake destination.

To set up a new destination:

1. Navigate to Airbyte.
2. Select **New connection**.
3. Select the existing Postgres source you created earlier.
4. Select the existing Snowflake destination you created earlier.
5. Select **Replicate source** as the sync mode.
6. Click **Next**.
7. On the **Configure connection** dialog, you can accept the defaults or modify the settings according to your requirements.
8. Click **Finish & sync** to complete the setup.

Your first sync may take a few moments.

## Verify the replication

After the sync operation is complete, you can verify the replication by navigating to Snowflake, opening your Snowflake project, navigating to a worksheet, and querying your database to view the replicated data. For example, if you've replicated the `playing_with_neon` example table, you can run a `SELECT * FROM PLAYING_WITH_NEON;` query to view the replicated data.

![Airbyte Snowflake verify replication](https://neon.com/docs/guides/airbyte_snowflake_verify.png)

## References

- [Setting up the Airbyte destination connector](https://docs.airbyte.com/integrations/destinations/snowflake)
- [Airbyte: Add a destination](https://docs.airbyte.com/using-airbyte/getting-started/add-a-destination)
- [Airbyte: Set up a connection](https://docs.airbyte.com/using-airbyte/getting-started/set-up-a-connection)
- [Airbyte: How to load data from Postgres to Snowflake destination](https://airbyte.com/how-to-sync/postgresql-to-snowflake-data-cloud)
- [What is an ELT data pipeline?](https://airbyte.com/blog/elt-pipeline)
- [Logical replication - PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication.html)
- [Publications - PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication-publication.html)

--- [Document source](https://neon.com/docs/guides/logical-replication-airbyte.md) ---

> Summary: Configure Lakebase Postgres as an Airbyte source for Change Data Capture using Postgres WAL and the pgoutput plugin over a direct, non-pooled connection. Covers wal_level promotion to logical, replication slot creation, publication setup, and Airbyte source configuration. Enabling logical replication permanently sets wal_level to logical for all databases in the project.

# Replicate data with Airbyte

Learn how to replicate data from Neon with Airbyte

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

[Airbyte](https://airbyte.com/) is an open-source data integration platform that moves data from a source to a destination system. Airbyte offers a large library of connectors for various data sources and destinations.

In this guide, you will learn how to define your Lakebase Postgres database as a data source in Airbyte so that you can stream data to one or more of Airbyte's supported destinations.

## Prerequisites

- An [Airbyte account](https://airbyte.com/)
- A [Neon account](https://console.neon.tech/)
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Prepare your source Neon database

This section describes how to prepare your source Neon database (the publisher) for replicating data to your destination Neon database (the subscriber).

### Enable logical replication in Neon

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, meaning active connections will be dropped and have to reconnect.

To enable logical replication in Neon:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor):

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

### Create a Postgres role for replication

It's recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/reference/api/branches/create-project-branch-role)

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

### Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a replication slot

Airbyte requires a dedicated replication slot. Only one source should be configured to use this replication slot.

Airbyte uses the `pgoutput` plugin in Postgres for decoding WAL changes into a logical replication stream. To create a replication slot called `airbyte_slot` that uses the `pgoutput` plugin, run the following command on your database using your replication role:

```sql
SELECT pg_create_logical_replication_slot('airbyte_slot', 'pgoutput');
```

`airbyte_slot` is the name assigned to the replication slot. You will need to provide this name when you set up your Airbyte source.

### Create a publication

Perform the following steps for each table you want to replicate data from:

1. Add the replication identity (the method of distinguishing between rows) for each table you want to replicate:

   ```sql
   ALTER TABLE <table_name> REPLICA IDENTITY DEFAULT;
   ```

   In rare cases, if your tables use data types that support [TOAST](https://www.postgresql.org/docs/current/storage-toast.html) or have very large field values, consider using `REPLICA IDENTITY FULL` instead:

   ```sql
   ALTER TABLE <table_name> REPLICA IDENTITY FULL;
   ```

2. Create the Postgres publication. Include all tables you want to replicate as part of the publication:

   ```sql
   CREATE PUBLICATION airbyte_publication FOR TABLE <tbl1, tbl2, tbl3>;
   ```

   The publication name is customizable. Refer to the [Postgres docs](https://www.postgresql.org/docs/current/logical-replication-publication.html) if you need to add or remove tables from your publication.

**Note:** The Airbyte UI currently allows selecting any table for Change Data Capture (CDC). If a table is selected that is not part of the publication, it will not be replicated even though it is selected. If a table is part of the publication but does not have a replication identity, the replication identity will be created automatically on the first run if the Postgres role you use with Airbyte has the necessary permissions.

## Create a Postgres source in Airbyte

1. From your Airbyte Cloud account, select **Sources** from the left navigation bar, search for **Postgres**, and then create a new Postgres source.

2. Enter the connection details for your Neon database. You can find your database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

   **Important:** Use a **direct connection** to your compute endpoint, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers. When copying your connection string from Neon, make sure it does not include `-pooler` in the hostname. For more information about connection pooling and when to use direct connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

   For example, given a connection string like this:

   ```bash
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   Enter the details in the Airbyte **Create a source** dialog as shown below. Your values will differ.

   - **Host**: ep-cool-darkness-123456.us-east-2.aws.neon.tech
   - **Port**: 5432
   - **Database Name**: dbname
   - **Username**: replication_user
   - **Password**: AbC123dEf

3. Under **Optional fields**, list the schemas you want to sync. Schema names are case-sensitive, and multiple schemas may be specified. By default, `public` is the only selected schema.

4. Select an SSL mode. You will most frequently choose `require` or `verify-ca`. Both of these options always require encryption. The `verify-ca` mode requires a certificate. Refer to [Connect securely](https://neon.com/docs/connect/connect-securely) for information about the location of certificate files you can use with Neon.

5. Under **Advanced**:
   - Select **Read Changes using Write-Ahead Log (CDC)** from available replication methods.
   - In the **Replication Slot** field, enter the name of the replication slot you created previously: `airbyte_slot`.
   - In the **Publication** field, enter the name of the publication you created previously: `airbyte_publication`.
     ![Airbyte advanced fields](https://neon.com/docs/guides/airbyte_cdc_advanced_fields.png)

## Allow inbound traffic

If you are on Airbyte Cloud, and you are using Neon's **IP Allow** feature to limit IP addresses that can connect to Neon, you will need to allow inbound traffic from Airbyte's IP addresses. You can find a list of IPs that need to be allowlisted in the [Airbyte Security docs](https://docs.airbyte.com/operating-airbyte/security). For information about configuring allowed IPs in Neon, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

## Complete the source setup

To complete your source setup, click **Set up source** in the Airbyte UI. Airbyte will test the connection to your database. Once this succeeds, you've successfully configured an Airbyte Postgres source for your Neon database.

## Configure a destination

To complete your data integration setup, you can now add one of Airbyte's many supported destinations, such as [Snowflake](https://neon.com/docs/guides/logical-replication-airbyte-snowflake), BigQuery, or Kafka, to name a few. After configuring a destination, you'll need to set up a connection between your Neon source database and your chosen destination. Refer to the Airbyte documentation for instructions:

- [Add a destination](https://docs.airbyte.com/using-airbyte/getting-started/add-a-destination)
- [Set up a connection](https://docs.airbyte.com/using-airbyte/getting-started/set-up-a-connection)

## References

- [What is an ELT data pipeline?](https://airbyte.com/blog/elt-pipeline)
- [Logical replication - PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication.html)
- [Publications - PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication-publication.html)

--- [Document source](https://neon.com/docs/guides/logical-replication-alloydb.md) ---

> Summary: Replicate data from Google AlloyDB to Neon using logical replication. Requires enabling the AlloyDB-specific flags alloydb.enable_pglogical and alloydb.logical_decoding, then creating a publication on AlloyDB and a matching subscription on Lakebase Postgres. Covers NAT Gateway IP allowlisting, replication role setup with alloydbsuperuser, and schema transfer via pg_dump and pg_restore before starting the subscription.

# Replicate data from AlloyDB

Learn how to replicate data from AlloyDB to Neon

Last updated: 2026-09-16

This guide describes how to replicate data from AlloyDB Postgres to Neon using native Postgres logical replication. The steps in this guide follow those described in [Set up native PostgreSQL logical replication](https://cloud.google.com/sql/docs/postgres/replication/configure-logical-replication#set-up-native-postgresql-logical-replication), in the _Google AlloyDB documentation_.

## Prerequisites

- An AlloyDB Postgres instance containing the data you want to replicate. If you're just testing this out and need some data to play with, you can use the following statements to create a table with sample data.

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- A Neon project with a Postgres database to receive the replicated data. For information about creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

## Prepare your AlloyDB source database

This section describes how to prepare your source AlloyDB Postgres instance (the publisher) for replicating data to Neon.

### Enable logical replication

Your first step is to enable logical replication at the source Postgres instance. In AlloyDB, you can enable logical replication by setting the `alloydb.enable_pglogical` and `alloydb.logical_decoding` flags to `on`. This sets the Postgres `wal_level` parameter to `logical`.

To enable these flags:

1. In the Google Cloud console, navigate to your [AlloyDB Clusters](https://console.cloud.google.com/alloydb/clusters) page.
2. From the **Actions** menu for your Primary instance, select **Edit**.
3. Scroll down to the **Advanced Configurations Options** > **Flags** section.
4. If the flags have not been set on the instance before, click **Add a Database Flag**, and set the value to `on` for the `alloydb.enable_pglogical` and `alloydb.logical_decoding`.
5. Click **Update instance** to save your changes and confirm your selections.

Afterward, you can verify that logical replication is enabled by running `SHOW wal_level;` from **AlloyDB Studio** or your terminal:

![show wal\_level](https://neon.com/docs/guides/alloydb_show_wal_level.png)

### Allow connections from Neon

You need to allow connections to your AlloyDB Postgres instance from Neon. To do this in your AlloyDB instance:

1. In the Google Cloud console, navigate to your [AlloyDB Clusters](https://console.cloud.google.com/alloydb/clusters) page and select your **Primary instance** to open the **Overview** page.

2. Scroll down to the **Instances in your cluster** section.

3. Click **Edit Primary**.

4. Select the **Enable public IP** checkbox to allow connections over the public internet.

5. Under **Authorized external networks**, enter the Neon IP addresses you want to allow. Add an entry for each of the NAT gateway IP addresses associated with your Neon project's region. Neon has 3 to 6 IP addresses per region, corresponding to each availability zone. See [NAT Gateway IP addresses](https://neon.com/docs/introduction/regions#nat-gateway-ip-addresses) for the IP addresses.

   **Note:** AlloyDB requires addresses to be specified in CIDR notation. You can do so by appending `/32` to the NAT Gateway IP address; for example: `18.217.181.229/32`

   In the example shown below, you can see that three addresses were added in CIDR format by appending `/32`.

   ![AlloyDB network configuration](https://neon.com/docs/guides/alloydb_network_config.png)

6. Under **Network Security**, select **Require SSL Encryption (default)** if it's not already selected.

7. Click **Update Instance** when you are finished.

### Note your public IP address

Record the public IP address of your AlloyDB Postgres instance. You'll need this value later when you set up a subscription from your Neon database. You can find the public IP address on your AlloyDB instance's **Overview** page, under **Instances in your cluster** > **Connectivity**.

**Note:** If you do not use a public IP address, you'll need to configure access via a private IP. See [Private IP overview](https://cloud.google.com/alloydb/docs/private-ip), in the AlloyDB documentation.

![AlloyDB public IP address](https://neon.com/docs/guides/alloydb_public_ip.png)

### Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data from your AlloyDB Postgres instance. The role must have the `REPLICATION` privilege. On your AlloyDB Postgres instance, login in as your `postgres` user or an administrative user you use to create roles and run the following command to create a replication role. You can replace the name `replication_user` with whatever name you want to use.

```sql
CREATE USER replication_user WITH REPLICATION IN ROLE alloydbsuperuser LOGIN PASSWORD 'replication_user_password';
```

### Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to a Postgres role named `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a publication on the source database

Publications are a fundamental part of logical replication in Postgres. They define what will be replicated.

To create a publication for a specific table:

```sql
CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

## Prepare your Neon destination database

This section describes how to prepare your destination Lakebase Postgres database (the subscriber) to receive replicated data from your AlloyDB Postgres instance.

### Prepare your database schema

When configuring logical replication in Postgres, the tables defined in your publication on the source database you are replicating from must also exist in the destination database, and they must have the same table names and columns. You can create the tables manually in your destination database or use utilities like `pg_dump` and `pg_restore` to dump the schema from your source database and load it to your destination database.

**Note:**

If you're just using the sample `playing_with_neon` table, you can create the same table on the destination database with the following statement:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

#### Dump the schema

To dump only the schema from a database, you can run a `pg_dump` command similar to the following to create an `.sql` dump file with the schema only:

```sql
pg_dump --schema-only \
	--no-privileges \
	"postgresql://role:password@hostname:5432/dbname" \
	> schema_dump.sql
```

- With the `--schema-only` option, only object definitions are dumped. Data is excluded.
- The `--no-privileges` option prevents dumping privileges. Neon may not support the privileges you've defined elsewhere, or if dumping a schema from Neon, there maybe Neon-specific privileges that cannot be restored to another database.

#### Review and modify the dumped schema

After dumping a schema to an `.sql` file, review it for statements that you don't want to replicate or that won't be supported on your destination database, and comment them out. For example, when dumping a schema from AlloyDB, you'll see the statements shown below, which you'll need to comment out because they won't be supported in Neon. Generally, you should remove any parameters configured on another Postgres provider and rely on Neon's default Postgres settings.

If you are replicating a large dataset, also consider removing any `CREATE INDEX` statements from the resulting dump file to avoid creating indexes when loading the schema on the destination database (the subscriber). Taking indexes out of the equation can substantially reduce the time required for initial data load performed when starting logical replication. Save the `CREATE INDEX` statements that you remove. You can add the indexes back after the initial data copy is completed.

**Note:** To comment out a single line, you can use `--` at the beginning of the line.

```sql
-- SET statement_timeout = 0;
-- SET lock_timeout = 0;
-- SET idle_in_transaction_session_timeout = 0;
-- SET client_encoding = 'UTF8';
-- SET standard_conforming_strings = on;
-- SELECT pg_catalog.set_config('search_path', '', false);
-- SET check_function_bodies = false;
-- SET xmloption = content;
-- SET client_min_messages = warning;
-- SET row_security = off;

-- ALTER SCHEMA public OWNER TO alloydbsuperuser;

-- CREATE EXTENSION IF NOT EXISTS google_columnar_engine WITH SCHEMA public;

-- CREATE EXTENSION IF NOT EXISTS google_db_advisor WITH SCHEMA public;
```

#### Load the schema

After making any necessary modifications to the dump file, load the dumped schema using `pg_restore`.

**Tip:** When you're restoring on Neon, you can input your Neon connection string in place of `postgresql://role:password@hostname:5432/dbname`. You can find your database connection string by clicking the **Connect** button in the Console nav.

```sql
psql \
	"postgresql://role:password@hostname:5432/dbname" \
	< schema_dump.sql
```

After you've loaded the schema, you can view the result with this `psql` command:

```sql
\dt
```

### Create a subscription

After creating a publication on the source database, you need to create a subscription on your Neon destination database.

1. Create the subscription using the using a `CREATE SUBSCRIPTION` statement:

   ```sql
   CREATE SUBSCRIPTION my_subscription
   CONNECTION 'host=<primary-ip> port=5432 dbname=postgres user=replication_user password=replication_user_password'
   PUBLICATION my_publication;
   ```

   - `subscription_name`: A name you chose for the subscription.
   - `connection_string`: The connection string for the source AlloyDB database where you defined the publication. For the `<primary_ip>`, use the IP address of your AlloyDB Postgres instance that you noted earlier, and specify the name and password of your replication role. If you're replicating from a database other than `postgres`, be sure to specify that database name.
   - `publication_name`: The name of the publication you created on the source Neon database.

2. Verify the subscription was created by running the following command:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription has been created successfully.

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from the publisher to the subscriber database.

1. Run some data modifying queries on the source database (inserts, updates, or deletes). If you're using the `playing_with_neon` database, you can use this statement to insert 10 rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on the source and destination databases to make sure the result matches.

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   30
   (1 row)
   ```

Alternatively, you can run the following query on the subscriber to make sure the `last_msg_receipt_time` is as expected. For example, if you just ran an insert option on the publisher, the `last_msg_receipt_time` should reflect the time of that operation.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

## Switch over your application

After the replication operation is complete, you can switch your application over to the destination database by swapping out your AlloyDB source database connection details for your Neon destination database connection details.

You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For details, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

--- [Document source](https://neon.com/docs/guides/logical-replication-clickhouse.md) ---

> Summary: Replicate data from Lakebase Postgres to ClickHouse Cloud using ClickPipes, a WAL-based ingestion service that reads CDC events via a Postgres publication and a dedicated replication role. Use this guide to sync Neon tables into ClickHouse for real-time analytics without custom ETL, with Console, API, or Terraform setup options. Enabling logical replication permanently sets wal_level=logical for the entire Neon project.

# Replicate data to ClickHouse

Learn how to replicate data from Neon to ClickHouse Cloud

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

[ClickHouse](https://clickhouse.com/) is an open-source column-oriented database management system designed for real-time analytical queries on large volumes of data. Using **[ClickPipes](https://clickhouse.com/cloud/clickpipes)**, ClickHouse Cloud's native continuous data ingestion service, you can easily set up Change Data Capture (CDC) from your Lakebase Postgres database to stream real-time changes directly into ClickHouse.

In this guide, you will learn how to prepare your Lakebase Postgres database and configure a Postgres CDC ClickPipe to replicate data to ClickHouse Cloud.

## Prerequisites

- A [ClickHouse Cloud account](https://clickhouse.cloud/)
- A [Neon account](https://console.neon.tech/)
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin
- [Neon API key](https://neon.com/docs/manage/api-keys#create-project-scoped-organization-api-keys) (for API or Terraform) with permissions to modify project settings.
- **ClickHouse Cloud credentials** - Key ID, Key Secret, and Organization ID obtained from the [ClickHouse Cloud console](https://clickhouse.com/docs/cloud/manage/openapi) and organization settings (for API or Terraform)

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Prepare your source Neon database

Before setting up the ClickPipe in ClickHouse Cloud, you need to prepare your source database for logical replication. This involves enabling logical replication, creating a publication, and ensuring your tables are properly configured for replication.

### Enable logical replication in Neon

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, meaning active connections will be temporarily dropped and have to reconnect.

To enable logical replication in Neon:

**Console**

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

   ![Neon dashboard settings with option to enable logical replication](https://neon.com/docs/guides/neon-console-settings-logical-replication.png)

**API**

Use the [Update project](https://neon.com/docs/reference/api/projects/update-project) endpoint to enable logical replication programmatically. Replace `$PROJECT_ID` with your project ID.

```bash
curl -X PATCH "https://console.neon.tech/api/v2/projects/$PROJECT_ID" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "project": {
    "settings": {
      "enable_logical_replication": true
    }
  }
}'
```

> Replace `$NEON_API_KEY` and `$PROJECT_ID` with your actual Neon API key and project ID.

You can verify that logical replication is enabled by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor):

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

### Create a Postgres role for replication

It's recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name (`replication_user`).
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

Capture the `password` value from the API response. For example, your response will look similar to the following:

<details>

<summary>Example API response for role creation</summary>

```json
{
    "role": {
        "branch_id": "br-spring-base-aqftsqpm",
        "name": "replication_user",
        "password": "your_password",
        "protected": false,
        "authentication_method": "password",
        "created_at": "2026-05-08T06:20:28Z",
        "updated_at": "2026-05-08T06:20:28Z"
    },
    "operations": [
        {
            "id": "0390cd9d-7e69-4bb5-b06c-2b88371d1d55",
            "project_id": "holy-heart-14531142",
            "branch_id": "br-spring-base-aqftsqpm",
            "endpoint_id": "ep-autumn-glitter-aqi3gmt4",
            "action": "apply_config",
            "status": "running",
            "failures_count": 0,
            "created_at": "2026-05-08T06:20:28Z",
            "updated_at": "2026-05-08T06:20:28Z",
            "total_duration_ms": 0
        }
    ]
}
```

</details>

The `password` field is present inside the `role` object in the API response. Make sure to securely store this password, as it will be required when configuring your ClickPipe connection to authenticate with your Neon database.

### Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant the required access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA "public" TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA "public" TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA "public" GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` and using `ALTER DEFAULT PRIVILEGES` ensures that your replication user can read all existing tables and any future tables added to the schema.

### Configure replica identity for tables

For a table to be replicated using ClickPipes, it must have either a `PRIMARY KEY` or a `REPLICA IDENTITY` defined.

If you have tables without a primary key, you must set the replica identity to `FULL` so that `UPDATE` and `DELETE` operations work correctly:

```sql
ALTER TABLE your_table_name REPLICA IDENTITY FULL;
```

**Note:** Using `REPLICA IDENTITY FULL` requires more data to be written to the WAL for each change, which can increase WAL storage usage and impact performance. Use primary keys on your tables wherever possible.

### Create a publication

Create a Postgres publication that includes the tables you want to replicate. It is recommended to create a publication that includes only the tables you want to replicate, rather than using `FOR ALL TABLES`, to minimize unnecessary data replication and reduce the amount of WAL data generated.

To create a publication named `clickpipes_pub` for specific tables, run the following command:

```sql
CREATE PUBLICATION clickpipes_pub FOR TABLE tb1, tb2;
```

> Replace `tb1` and `tb2` with the actual names of the tables you want to replicate. You can include as many tables as needed in the publication.

ClickPipes will use this publication to capture changes from your specified tables. Refer to the [Postgres docs](https://www.postgresql.org/docs/current/logical-replication-publication.html) if you need to add or remove tables from your publication.

### Allow inbound traffic (optional)

If you are using Neon's [**IP Allow**](https://neon.com/docs/introduction/ip-allow) feature to limit IP addresses that can connect to Neon, add ClickHouse's IPs to your allowlist in Neon.

For instructions, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow). You can find the list of IPs that need to be allowlisted in the [ClickHouse Cloud documentation](https://clickhouse.com/docs/integrations/clickpipes#list-of-static-ips).

## Create a ClickPipe in ClickHouse Cloud

Now that your Neon source database is prepared, you can create the CDC integration in ClickHouse.

**Console**

1. Log in to your [ClickHouse Cloud account](https://clickhouse.cloud/) and navigate to your service.

2. Select **Data Sources** on the left-side menu and click **Create ClickPipe**.
   ![ClickHouse Cloud create ClickPipe button](https://neon.com/docs/guides/clickhouse_create_clickpipe.png)

3. Select the **Neon** tile.
   ![ClickHouse Cloud Neon tile for ClickPipe source selection](https://neon.com/docs/guides/clickhouse_neon_clickpipe_tile.png)

4. Enter the connection details for your Neon database. You can find these details by clicking **Connect** in the Console nav. Toggle **Parameters only** to easily copy individual connection values.

   **Important:** Use a **direct connection** to your compute endpoint, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers. When copying your connection string from Neon, make sure it does not include `-pooler` in the hostname. For more information, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

   Enter the following connection details in ClickHouse Cloud:

   - **Name**: A name for your ClickPipe (e.g., `neon_to_clickhouse`)
   - **Host**: Your Neon database host (e.g., `ep-cool-darkness-123456.us-east-2.aws.neon.tech`)
   - **Port**: 5432
   - **User**: `replication_user` (the dedicated replication user you created earlier)
   - **Password**: The password for your replication user
   - **Database**: The name of the database you are replicating from

   Keep the default replication method, **Initial Load + CDC**, selected. This option first takes a snapshot of your existing data and then continuously replicates any ongoing changes.

   Click **Next** to continue.

5. **Configure your ClickPipe**: Select the Publication you created earlier (e.g., `clickpipes_pub`) from the dropdown menu. This tells ClickPipes which tables to replicate and ensures that only the necessary WAL data is captured.

6. **Advanced Settings** (Optional): You can configure the sync interval, batch sizes, or parallel threads for the initial snapshot. The defaults are generally recommended for standard workloads.

7. **Configure Tables**: Select the tables you want to replicate from the source Postgres database. You can also rename tables for the destination ClickHouse database if desired.

8. **Permissions**: Review the necessary permissions. Select the "Full access" role from the dropdown, then click **Create ClickPipe**.

ClickPipes will immediately begin provisioning. It will first take a snapshot of the source tables (Initial Load) and then transition to `Running` state, actively streaming Change-Data-Capture (CDC) events from Neon to ClickHouse using the write-ahead log (WAL).

![ClickHouse Cloud ClickPipe running status](https://neon.com/docs/guides/clickhouse_clickpipe_running.png)

**API**

You can provision and manage your ClickHouse Cloud service and ClickPipes programmatically using the ClickHouse Cloud API. Refer to the [ClickHouse Cloud API documentation](https://clickhouse.com/docs/cloud/manage/api/swagger) for more details.

First, submit a `POST` request to the `/services` endpoint to create a ClickHouse Cloud service:

```bash
curl -X POST "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services" \
  -u "$KEY_ID:$KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "neon-clickhouse-service",
  "provider": "aws",
  "region": "us-east-1",
  "ipAccessList": [
        {
            "source": "0.0.0.0/0",
            "description": "Allow all"
        }
    ]
}'
```

> Modify the `provider`, `region`, and `ipAccessList` values as needed for your use case. The above example allows all IPs to connect, which is never recommended for production environments. For secure access, specify only the IP addresses or ranges that require access.

The response will include a `service` object containing an `id`. Use this ID as your `$SERVICE_ID` for the next step.

<details>

<summary>Example API response for service creation</summary>

```json
{
    "result": {
        "service": {
            "id": "abcd1234-5678-90ab-cdef-1234567890ab",
            "name": "neon-clickhouse-service",
            "provider": "aws",
            "region": "us-east-1",
            "state": "provisioning",
            "endpoints": [
                {
                    "protocol": "nativesecure",
                    "host": "b22y67wt8m.us-east-1.aws.clickhouse.cloud",
                    "port": 9440
                },
                {
                    "protocol": "https",
                    "host": "b22y67wt8m.us-east-1.aws.clickhouse.cloud",
                    "port": 8443
                }
            ],
            "idleScaling": true,
            "idleTimeoutMinutes": 15,
            "minReplicaMemoryGb": 16,
            "maxReplicaMemoryGb": 120,
            "minTotalMemoryGb": 48,
            "maxTotalMemoryGb": 360,
            "numReplicas": 3,
            "ipAccessList": [
                {
                    "source": "0.0.0.0/0",
                    "description": "Allow all"
                }
            ],
            "createdAt": "2026-05-08T08:28:19Z",
            "clickhouseVersion": "25.12",
            "iamRole": "arn:aws:iam::551171829645:role/CH-S3-navyaws-at-27-ue1-42-Role",
            "privateEndpointIds": [],
            "availablePrivateEndpointIds": [],
            "dataWarehouseId": "ded125b0-6283-41b7-9802-ac022e5d6115",
            "isPrimary": true,
            "isReadonly": false,
            "profile": "v1-default",
            "releaseChannel": "default",
            "hasTransparentDataEncryption": false,
            "tags": [],
            "enableCoreDumps": true,
            "mcpEnabled": false
        },
        "password": "secure_password_123"
    },
    "requestId": "85ef7cfa-fbbb-4c61-b51d-428b3bc66ccb",
    "status": 200
}
```

</details>

Next, submit a `POST` request to the `/clickpipes` endpoint with your connection details to set up the ClickPipe:

```bash
curl -X POST "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID/clickpipes" \
  -u "$KEY_ID:$KEY_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "neon_to_clickhouse",
  "source": {
    "postgres": {
      "type": "neon",
      "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
      "port": 5432,
      "database": "neondb",
      "credentials": {
        "username": "replication_user",
        "password": "your_password"
      },
      "settings": {
          "syncIntervalSeconds": 60,
          "publicationName": "clickpipes_pub",
          "replicationMode": "cdc"
      },
      "tableMappings": [
        {
          "sourceSchemaName": "public",
          "sourceTable": "your_table",
          "targetTable": "your_table"
        }
      ]
    }
  },
  "destination": {
    "database": "default"
  }
}'
```

> Replace the connection details with your actual configuration. Make sure to use a **direct connection** to your Neon compute endpoint, not a pooled connection. When copying your connection string from Neon, ensure that the hostname does not include `-pooler`.

<details>

<summary>Example API response for ClickPipe creation</summary>

```json
{
    "result": {
        "id": "b7eefe5c-7e7c-4a0c-84bc-2a78f53a6253",
        "serviceId": "59851646-bdc4-477b-9c00-613b48487fbe",
        "name": "neon_to_clickhouse",
        "state": "Provisioning",
        "source": {
            "postgres": {
                "type": "neon",
                "host": "ep-autumn-glitter-aqi3gmt4.c-8.us-east-1.aws.neon.tech",
                "port": 5432,
                "database": "neondb",
                "authentication": "basic",
                "settings": {
                    "syncIntervalSeconds": 60,
                    "pullBatchSize": 100000,
                    "snapshotNumRowsPerPartition": 100000,
                    "initialLoadParallelism": 4,
                    "snapshotNumberOfParallelTables": 1,
                    "replicationSlotName": "",
                    "publicationName": "clickpipes_pub",
                    "replicationMode": "cdc",
                    "allowNullableColumns": false,
                    "enableFailoverSlots": false,
                    "deleteOnMerge": false
                },
                "tableMappings": [
                    {
                        "sourceSchemaName": "public",
                        "sourceTable": "playing_with_neon",
                        "targetTable": "playing_with_neon",
                        "excludedColumns": [],
                        "useCustomSortingKey": false,
                        "sortingKeys": [],
                        "tableEngine": "ReplacingMergeTree"
                    }
                ]
            }
        },
        "destination": {
            "database": "default",
            "table": "",
            "managedTable": false,
            "columns": []
        },
        "fieldMappings": [],
        "settings": {},
        "createdAt": "2026-05-08T08:41:14.83600211Z",
        "updatedAt": "2026-05-08T08:41:14.83600211Z"
    },
    "requestId": "7bbc392d-001e-47a3-ad38-008254bec55c",
    "status": 200
}
```

</details>

**Terraform**

You can provision and manage your ClickHouse Cloud service and ClickPipes as infrastructure-as-code using the [ClickHouse Terraform provider](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs).

Create a Terraform configuration file (e.g., `main.tf`) with the following content, replacing the placeholder values with your actual configuration:

```terraform
terraform {
  required_providers {
    clickhouse = {
      source  = "ClickHouse/clickhouse"
      version = ">= 3.14.0"
    }
  }
}

provider "clickhouse" {
  organization_id = "your_organization_id"
  token_key       = "your_key_id"
  token_secret    = "your_key_secret"
}

# 1. Create the ClickHouse Cloud service
resource "clickhouse_service" "my_service" {
  name           = "neon-clickhouse-service"
  cloud_provider = "aws"
  region         = "us-east-1"
  password       = "replace-with-a-secure-password-123"
  ip_access = [
    {
      source      = "0.0.0.0/0"
      description = "Allow all"
    }
  ]
}

# 2. Create the ClickPipe connecting Neon to the ClickHouse service
resource "clickhouse_clickpipe" "pg_pipe" {
  name       = "neon_to_clickhouse"
  service_id = clickhouse_service.my_service.id
  source = {
    postgres = {
      type     = "neon"
      host     = "ep-cool-darkness-123456.us-east-2.aws.neon.tech"
      port     = 5432
      database = "neondb"
      credentials = {
        username = "replication_user"
        password = "your_password"
      }
      settings = {
        publication_name = "clickpipes_pub"
        replication_mode = "cdc"
      }
      table_mappings = [
        {
          source_schema_name = "public"
          source_table       = "your_table"
          target_table       = "your_table"
        }
      ]
    }
  }
  destination = {
    database = "default"
  }
}
```

> **Note:** The `ip_access_list` block above allows all IPs (`0.0.0.0/0`) to connect to the ClickHouse service, which is never recommended for production environments. For secure access, restrict this to your specific IP addresses or ranges.

**Important:** If you are hardcoding or passing your Neon connection string, ensure you use a **direct connection** to your Neon compute endpoint, not a pooled connection. Make sure the hostname does not include `-pooler`.

Initialize Terraform to download the ClickHouse provider:

```bash
terraform init
```

Next, run `terraform plan` to verify the resources that will be created.

```bash
terraform plan --out=tfplan
```

You should see an output indicating that a ClickHouse service and a ClickPipe will be created. Verify that the configuration looks correct, and then apply the changes to provision the resources:

```bash
terraform apply "tfplan"
```

Terraform will create the ClickHouse Cloud service and set up the ClickPipe to replicate data from your database to ClickHouse. You can monitor the status of your ClickPipe in the ClickHouse Cloud console or by using the ClickHouse Cloud API.

## References

- [ClickHouse: Ingesting data from Postgres to ClickHouse (using CDC)](https://clickhouse.com/docs/integrations/clickpipes/postgres)
- [ClickHouse: Neon Postgres source setup guide](https://clickhouse.com/docs/integrations/clickpipes/postgres/source/neon-postgres)
- [ClickHouse: ClickPipes for Postgres FAQ](https://clickhouse.com/docs/integrations/clickpipes/postgres/faq)
- [ClickHouse Cloud API documentation](https://clickhouse.com/docs/cloud/manage/api/swagger)
- [ClickHouse Terraform provider documentation](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs)

```
```

--- [Document source](https://neon.com/docs/guides/logical-replication-cloud-sql.md) ---

> Summary: Replicate data from Google Cloud SQL Postgres to Neon using logical replication. Setup involves enabling the `cloudsql.logical_decoding` flag, allowlisting Neon's NAT gateway IPs, and creating a publication on the source with a matching `CREATE SUBSCRIPTION` on the Lakebase Postgres destination. Use this guide when migrating or continuously syncing from Cloud SQL to Neon rather than a one-time pg_dump import. Covers replication role creation, schema preparation, subscription verification, and application cutover.

# Replicate data from Cloud SQL Postgres

Learn how to replicate data from Google Cloud SQL Postgres to Neon

Last updated: 2026-09-16

This guide describes how to replicate data from Cloud SQL Postgres using native Postgres logical replication, as described in [Set up native PostgreSQL logical replication](https://cloud.google.com/sql/docs/postgres/replication/configure-logical-replication#set-up-native-postgresql-logical-replication), in the Google Cloud SQL documentation.

## Prerequisites

- A Cloud SQL Postgres instance containing the data you want to replicate. If you're just testing this out and need some data to play with, you can use the following statements to create a table with sample data. Your database and schema may differ.

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- A Neon project with a Postgres database to receive the replicated data. For information about creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

## Prepare your Cloud SQL source database

This section describes how to prepare your source Cloud SQL Postgres instance (the publisher) for replicating data to Neon.

### Enable logical replication

The first step is to enable logical replication at the source Postgres instance. In Cloud SQL, you can enable logical replication for your Postgres instance by setting the `cloudsql.logical_decoding` flag to `on`. This action will set the Postgres `wal_level` parameter to `logical`.

To enable this flag:

1. In the Google Cloud console, select the project that contains the Cloud SQL instance for which you want to set a database flag.
2. Open the instance and click **Edit**.
3. Scroll down to the **Flags** section.
4. If this flag has not been set on the instance before, click **Add item**, choose the flag from the drop-down menu, and set its value to `On`.
5. Click **Save** to save your changes.
6. Confirm your changes under **Flags** on the **Overview** page.

The change requires restarting the instance:

![Clod SQL instance restart](https://neon.com/docs/guides/cloud_sql_restart.png)

Afterward, you can verify that logical replication is enabled by running `SHOW wal_level;` from **Cloud SQL Studio** or your terminal.

![show wal\_level](https://neon.com/docs/guides/cloud_sql_show_wal_level.png)

### Allow connections from Neon

You need to allow connections to your Cloud SQL Postgres instance from Neon. To do this in Google Cloud:

1. In the Google Cloud console, go to the Cloud SQL Instances page.

2. Open the **Overview** page of your instance by clicking the instance name.

3. From the SQL navigation menu, select **Connections**.

4. Click the **Networking** tab.

5. Select the **Public IP** checkbox.

6. Click **Add network**.

7. Optionally, in the **Name** field, enter a name for this network.

8. In the **Network** field, enter the IP address from which you want to allow connections. You will need to perform this step for each of the NAT gateway IP addresses associated with your Neon project's region. Neon uses 3 to 6 IP addresses per region for this outbound communication, corresponding to each availability zone in the region. See [NAT Gateway IP addresses](https://neon.com/docs/introduction/regions#nat-gateway-ip-addresses) for Neon's NAT gateway IP addresses.

   **Note:** Cloud SQL requires addresses to be specified in CIDR notation. You can do so by appending `/32` to the NAT Gateway IP address; for example: `18.217.181.229/32`

   In the example shown below, you can see that three addresses were added, named `Neon1`, `Neon2`, and `Neon3`. You can name them whatever you like. The addresses were added in CIDR format by adding `/32`.

   ![Cloud SQL network configuration](https://neon.com/docs/guides/cloud_sql_network_config.png)

9. Click **Done** after adding a Network entry.

10. Click **Save** when you are finished adding Network entries for all of your Neon project's NAT Gateway IP addresses.

**Note:** You can specify a single Network entry using `0.0.0.0/0` to allow traffic from any IP address. However, this configuration is not considered secure and will trigger a warning.

### Note your public IP address

Record the public IP address of your Cloud SQL Postgres instance. You'll need this value later when you set up a subscription from your Neon database. You can find the public IP address on your Cloud SQL instance's **Overview** page.

**Note:** If you do not use a public IP address, you'll need to configure access via a private IP. Refer to the [Cloud SQL documentation](https://cloud.google.com/sql/docs/mysql/private-ip).

![Cloud SQL public IP address](https://neon.com/docs/guides/cloud_sql_public_ip.png)

### Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data from your Cloud SQL Postgres instance. The role must have the `REPLICATION` privilege. On your Cloud SQL Postgres instance, login in as your `postgres` user or an administrative user you use to create roles and run the following command to create a replication role. You can replace the name `replication_user` with whatever role name you want to use.

```sql
CREATE USER replication_user WITH REPLICATION IN ROLE cloudsqlsuperuser LOGIN PASSWORD 'replication_user_password';
```

### Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to a Postgres role named `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a publication on the source database

Publications are a fundamental part of logical replication in Postgres. They define what will be replicated.

To create a publication for a specific table:

```sql
CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

## Prepare your Neon destination database

This section describes how to prepare your source database (the subscriber) to receive replicated data from your Cloud SQL Postgres instance.

### Prepare your database schema

When configuring logical replication in Postgres, the tables in the source database you are replicating from must also exist in the destination database, and they must have the same table names and columns. You can create the tables manually in your destination database or use utilities like `pg_dump` and `pg_restore` to dump the schema from your source database and load it to your destination database. See [Import a database schema](https://neon.com/docs/import/migrate-schema-only) for instructions.

If you're using the sample `playing_with_neon` table, you can create the same table on the destination database with the following statement:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

### Create a subscription

After creating a publication on the source database, you need to create a subscription on your Neon destination database.

1. Create the subscription using the using a `CREATE SUBSCRIPTION` statement.

   ```sql
   CREATE SUBSCRIPTION my_subscription
   CONNECTION 'host=<primary-ip> port=5432 dbname=postgres user=replication_user password=replication_user_password'
   PUBLICATION my_publication;
   ```

   - `subscription_name`: A name you chose for the subscription.
   - `connection_string`: The connection string for the source Cloud SQL database where you defined the publication. For the `<primary_ip>`, use the IP address of your Cloud SQL Postgres instance that you noted earlier, and specify the name and password of your replication role. If you're replicating from a database other than `postgres`, be sure to specify that database name.
   - `publication_name`: The name of the publication you created on the source Neon database.

2. Verify the subscription was created by running the following command:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription has been created successfully.

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from the publisher to the subscriber database.

1. Run some data modifying queries on the source database (inserts, updates, or deletes). If you're using the `playing_with_neon` database, you can use this statement to insert some rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on the source and destination databases to make sure the result matches.

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   30
   (1 row)
   ```

Alternatively, you can run the following query on the subscriber to make sure the `last_msg_receipt_time` is as expected. For example, if you just ran an insert option on the publisher, the `last_msg_receipt_time` should reflect the time of that operation.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

## Switch over your application

After the replication operation is complete, you can switch your application over to the destination database by swapping out your Cloud SQL source database connection details for your Neon destination database connection details.

You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For details, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

--- [Document source](https://neon.com/docs/guides/logical-replication-concepts.md) ---

> Summary: PostgreSQL logical replication replicates row-level changes (INSERT, UPDATE, DELETE, TRUNCATE) from a publisher to subscribers using WAL decoding, replication slots, and decoder plugins such as pgoutput or wal2json. Read this page to understand the publisher-subscriber model, publications, subscriptions, and WAL components before setting up replication with Neon. Neon automatically removes inactive replication slots and supports wal2json alongside the standard pgoutput plugin.

# Postgres logical replication concepts

Learn about PostgreSQL logical replication concepts

Last updated: 2026-08-07

Logical Replication is a method of replicating data between databases or between your database and other data services or platforms. It differs from physical replication in that it replicates transactional changes rather than copying the entire database byte-for-byte. This approach allows for selective replication, where users can choose specific tables or rows for replication. It works by capturing DML operations in the source database and applying these changes to the target, which could be another Postgres database or data platform.

With logical replication, you can copy some or all of your data to a different location and continue sending updates from your source database in real-time, allowing you to maintain up-to-date copies of your data in different locations.

**Note:** For step-by-step setup instructions, refer to our [logical replication guides](https://neon.com/docs/guides/logical-replication-guide).

## Publisher subscriber model

The Postgres logical replication architecture is very simple. It uses a _publisher and subscriber_ model for data replication. The primary data source is the _publisher_, and the database or platform receiving the data is the _subscriber_. On the initial connection from a subscriber, all the data is copied from the publisher to the subscriber. After the initial copy operation, any changes made on the publisher are sent to the subscriber. You can read more about this model in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication.html).

![Logical replication publisher subscriber architecture](https://neon.com/docs/guides/logical_replication_model.jpg)

## Enabling logical replication

When replicating data from Neon, enable logical replication on your Neon project. When replicating data to Neon, enable it on the source database instead.

**Important:** Enabling logical replication changes the PostgreSQL `wal_level` setting from `replica` to `logical` for all databases in your Neon project. This allows Postgres to record the row-level WAL detail required for logical decoding. Once changed, it cannot be reverted. Enabling logical replication also restarts all computes, so active connections will be dropped and have to reconnect.

You can enable logical replication from the Neon Console or via the API. See [Enable logical replication](https://neon.com/docs/guides/logical-replication-neon#enable-logical-replication) for instructions.

You can verify that logical replication is enabled by running the following query:

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

## Publications

The Postgres documentation describes a [publication](https://www.postgresql.org/docs/current/logical-replication-publication.html) as a group of tables whose data changes are intended to be replicated through logical replication. It also describes a publication as a set of changes generated from a table or a group of tables. It's indeed both of these things.

A particular table can be included in multiple publications if necessary. Currently, publications can only include tables within a single schema. This is a Postgres limitation.

Publications can specify the types of changes they replicate, which can include `INSERT`, `UPDATE`, `DELETE`, and `TRUNCATE` operations. By default, publications replicate all of these operation types.

You can create a publication for one or more tables on the "publisher" database using [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html) syntax. For example, this command creates a publication named `users_publication` that tracks changes made to a `users` table.

```sql
CREATE PUBLICATION users_publication FOR TABLE users;
```

## Subscriptions

A subscription represents the downstream side of logical replication. Data is replicated _to_ a subscriber. A subscription- establishes a connection to the publisher and identifies the publication it intends to subscribe to.

A single subscriber can maintain multiple subscriptions, including multiple subscriptions to the same publisher.

You can create a subscription on a "subscriber" database or platform using [CREATE SUBSCRIPTION](https://www.postgresql.org/docs/current/sql-createsubscription.html) syntax. Building on the `users_publication` example above, here's how you would create a subscription:

```sql
CREATE SUBSCRIPTION users_subscription
CONNECTION 'postgresql://username:password@host:port/dbname'
PUBLICATION users_publication;
```

A subscription requires a unique name, a database connection string, the name and password of your replication role, and the name of the publication it subscribes to.

**Note:** When the connection string points at a Neon database, use a direct connection, not a pooled one. Logical replication requires a persistent connection and is not compatible with connection poolers, so the hostname must not include the `-pooler` suffix. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## How does it work under the hood?

While the publisher and subscriber model forms the surface of Postgres logical replication, the underlying mechanism is driven by a few key components, described below.

### Write-Ahead Log (WAL)

The WAL is central to Postgres's data durability and crash recovery mechanisms. In the context of logical replication, the WAL records all changes to your data. For logical replication, the WAL serves as the primary source of data that needs to be replicated. It's the transaction data captured in the WAL that's processed and then relayed from a publisher to a subscriber.

### Replication slots

Replication slots on the publisher database track replication progress, ensuring that no data in the WAL is purged before the subscriber has successfully replicated it. This mechanism helps maintain data consistency and prevent data loss in cases of network interruption or subscriber downtime.

Replication slots are typically created automatically with new subscriptions, but they can be created manually using the `pg_create_logical_replication_slot` function. Some "subscriber" data services and platforms require that you create a dedicated replication slot. This is accomplished using the following syntax:

```sql
SELECT pg_create_logical_replication_slot('my_replication_slot', 'pgoutput');
```

The first value, `my_replication_slot` is the name given to the replication slot. The second value is the decoder plugin the slot should use. Decoder plugins are discussed below.

The `max_replication_slots` configuration parameter defines the maximum number of replication slots that can be used to manage database replication connections. Each replication slot tracks changes in the publisher database to ensure that the connected subscriber stays up to date. You'll want a replication slot for each replication connection. For example, if you expect to have 10 separate subscribers replicating from your database, you would set `max_replication_slots` to 10 to accommodate each connection.

The `max_replication_slots` configuration parameter on Neon is set to `10` by default.

```ini
max_replication_slots = 10
```

**Important:** To prevent storage bloat, **Neon automatically removes _inactive_ replication slots after a period of time. Please see [Unused replication slots](https://neon.com/docs/guides/logical-replication-neon#unused-replication-slots) to learn more.

### Decoder plugins

The Postgres replication architecture uses decoder plugins to decode WAL entries into a logical replication stream, making the data understandable for the subscriber. The default decoder plugin for PostgreSQL logical replication is `pgoutput`, and it's included in Postgres by default. You don't need to install it.

Neon, supports an alternative decoder plugin called `wal2json`. This decoder plugin differs from `pgoutput` in that it converts WAL data into `JSON` format, which is useful for integrating Postgres with systems and applications that work with `JSON` data.

To use this decoder plugin, you'll need to create a dedicated replication slot for it, as shown here:

```sql
SELECT pg_create_logical_replication_slot('my_replication_slot', 'wal2json');
```

For more information about this alternative decoder plugin and how to use it, see [wal2json](https://github.com/eulerto/wal2json).

### WAL senders

WAL senders are processes on the publisher database that read the WAL and send the relevant data to the subscriber.

The `max_wal_senders` parameter defines the maximum number of concurrent WAL sender processes that are responsible for streaming WAL data to subscribers. In most cases, you should have one WAL sender process for each subscriber or replication slot to ensure efficient and consistent data replication.

The `max_wal_senders` configuration parameter on Neon is set to `10` by default, which matches the maximum number of replication slots defined by the `max_replication_slots` setting.

```ini
max_wal_senders = 10
```

### WAL receivers

On the subscriber side, WAL receivers receive the replication stream (the decoded WAL data), and apply these changes to the subscriber. The number of WAL receivers is determined by the number of connections made by subscribers.

## References

- [Logical replication - PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication.html)
- [Publications - PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication-publication.html)
- [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html)
- [CREATE SUBSCRIPTION](https://www.postgresql.org/docs/current/sql-createsubscription.html)
- [wal2json](https://github.com/eulerto/wal2json)

--- [Document source](https://neon.com/docs/guides/logical-replication-databricks.md) ---

> Summary: Replicate data from Lakebase Postgres to Databricks Lakehouse Delta tables using Lakeflow Connect's PostgreSQL connector and logical replication with the pgoutput plugin. Use this guide for continuous, low-latency ingestion from Neon into Unity Catalog, covering publication setup, replication slot creation, Unity Catalog connection, and pipeline configuration. The connector requires PostgreSQL 13 or later on the Neon primary; read replicas are not supported.

# Replicate data to Databricks with Lakeflow Connect

Learn how to replicate data from Neon to Databricks Lakehouse using the Lakeflow Connect PostgreSQL connector

Last updated: 2026-09-25

Neon's logical replication feature lets you stream changes from your Lakebase Postgres database into external systems. This guide shows how to use Databricks Lakeflow Connect's PostgreSQL connector to replicate data from Lakebase Postgres into Databricks Lakehouse using PostgreSQL logical replication.

The PostgreSQL connector for Lakeflow Connect is a managed ingestion connector that:

- Connects to PostgreSQL over TLS using a Unity Catalog connection
- Uses logical replication with the `pgoutput` plugin for change data capture (CDC)
- Requires PostgreSQL 13+ on the primary instance (not a read replica)
- Extracts snapshot and change data through an ingestion gateway and loads it into Delta tables via an ingestion pipeline

**Important: Public Preview**

The PostgreSQL connector for Lakeflow Connect is currently in Public Preview. You must work with your Databricks account team to have it enabled for your workspace.

## Prerequisites

You need:

- **A Neon project** with a Postgres database containing the data you want to replicate. For test data, you can run the following in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or an SQL client such as [psql](https://neon.com/docs/connect/query-with-psql-editor):

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon (
    id    SERIAL PRIMARY KEY,
    name  TEXT NOT NULL,
    value REAL
  );

  INSERT INTO playing_with_neon (name, value)
  SELECT LEFT(md5(i::TEXT), 10), random()
  FROM generate_series(1, 10) s(i);
  ```

- **A Databricks workspace** with Unity Catalog enabled, serverless compute available for Lakeflow Spark Declarative Pipelines, and the Lakeflow Connect PostgreSQL connector enabled (Public Preview)

- **Permissions in Databricks**: `CREATE CONNECTION` on the metastore (if you will create a new Unity Catalog connection); `USE CATALOG` on target and staging catalogs; `USE SCHEMA`, `CREATE TABLE`, and `CREATE VOLUME` on target schemas, or `CREATE SCHEMA` on the catalogs

- **Network connectivity**: Neon must accept inbound connections from your Databricks workspace (or via VPN/PrivateLink, depending on setup). If you use [IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow) in Neon, add the Databricks egress addresses to your allowlist. See [Subscriber access](https://neon.com/docs/guides/logical-replication-neon#subscriber-access)

- **PostgreSQL**: Lakebase Postgres running v13 or later with logical replication enabled on the primary. The connector does not support logical replication from a read replica

Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

## Step 1: Prepare your database

Configure Neon as a logical replication publisher that Lakeflow Connect can subscribe to.

### Enable logical replication in Neon

**Important:** Enabling logical replication sets `wal_level` from `replica` to `logical` for the entire project and restarts all computes in the project, briefly disconnecting clients. Once set to `logical`, it cannot be reverted.

1. In the Neon Console, open your project.
2. Go to **Settings** → **Postgres**, then **Logical replication**.
3. Click **Enable**.

Verify:

```sql
SHOW wal_level;
-- should return: logical
```

### Create a dedicated replication role

Databricks recommends a dedicated database user for ingestion. Create a role in Neon (roles created via the Neon Console, CLI, or API are granted the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege). You can name it `databricks_replication` or reuse an existing replication role.

**Console**

1. In the [Neon Console](https://console.neon.tech), select your project.
2. Select your branch from the project/branch menu at the top of the sidebar, then under **Postgres database** select **Roles**.
3. Click **Add Role**, enter the role name (e.g. `databricks_replication`), and click **Create**. Save the password.

**CLI**

```bash
neon roles create --name databricks_replication
```

**API**

Set `PROJECT_ID` and `BRANCH_ID` from your Neon project (for example from the project URL in the Console or via the Neon API).

```bash
export PROJECT_ID="your_project_id"
export BRANCH_ID="your_branch_id"

curl "https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID/roles" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"role": {"name": "databricks_replication"}}'
```

Then grant the role access to the database and tables. Run the following as a user with sufficient privileges (e.g. your primary role):

```sql
GRANT CONNECT ON DATABASE your_database TO databricks_replication;
GRANT USAGE ON SCHEMA public TO databricks_replication;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO databricks_replication;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO databricks_replication;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` and `ALTER DEFAULT PRIVILEGES` ensures future tables in the schema are included without re-granting.

### Configure replica identity for tables

Logical replication needs enough row identity to apply updates and deletes. For tables with a primary key and no large TOAST columns, use the default:

```sql
ALTER TABLE public.playing_with_neon REPLICA IDENTITY DEFAULT;
```

For tables without a primary key or with very large variable-length columns (e.g. large TEXT, BYTEA), use `FULL`:

```sql
ALTER TABLE public.some_large_table REPLICA IDENTITY FULL;
```

Repeat for each table you plan to replicate.

### Create a publication

Create a logical replication publication that includes all tables you want to ingest. One publication per database.

```sql
-- Option 1: Explicit list
CREATE PUBLICATION databricks_publication
  FOR TABLE public.playing_with_neon;

-- Option 2: All tables in the database
-- CREATE PUBLICATION databricks_publication FOR ALL TABLES;
```

You can later use `ALTER PUBLICATION` to add or remove tables. Only tables in this publication will be replicated.

### Create a logical replication slot

Lakeflow Connect uses logical replication slots with the `pgoutput` plugin. From your Neon database, connected as your replication role:

```sql
SELECT pg_create_logical_replication_slot('databricks_slot', 'pgoutput');
```

You will use the slot name `databricks_slot` and publication name `databricks_publication` when configuring the Lakeflow gateway.

**Tip: Replication slots and WAL**

Logical replication slots retain WAL until a subscriber consumes it. If the Lakeflow ingestion gateway is stopped for too long, WAL can accumulate. Keep the gateway running continuously and monitor replication lag. Neon also [removes inactive replication slots](https://neon.com/docs/guides/logical-replication-neon#unused-replication-slots) after approximately 40 hours if progress is not acknowledged.

At this point Neon is ready: `wal_level = logical`, a dedicated replication user with the required privileges, replica identities set on tables, `databricks_publication` defined, and `databricks_slot` created with `pgoutput`.

## Step 2: Create a Unity Catalog connection to Neon

Lakeflow Connect uses Unity Catalog connections to store JDBC connection details and credentials for PostgreSQL. Create the connection in the Databricks UI or via the CLI.

### Using the Databricks UI (recommended)

1. In your Databricks workspace, open **Catalog** (Catalog Explorer).
2. Click the plus icon (+) and select **Create a connection**.
3. Enter a **Connection name**.
   Choose **PostgreSQL** as the connection type.
4. For Auth type, select `Username and password`.
5. Enter your Neon connection details (from **Connect** in the Console nav). Use your direct Neon host, not the pooled host. Logical replication requires a persistent connection and is not compatible with connection poolers, so the host must not include the `-pooler` suffix. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).
   - **Host**: your Neon host (e.g. `ep-cool-darkness-123456.us-east-2.aws.neon.tech`)
   - **Port**: 5432
   - **Database**: your Neon database name
   - **User**: `databricks_replication` (or the replication role you created).
   - **Password**: the password for that role. You can obtain the password from the **Connect** modal (**Connect** in the Console nav).
6. Create the connection.
7. On the **Catalog basics** page, test your connection. You will need to provide the name of your PostgreSQL database.
8. Click next to grant catalog access. Specify the users, groups, and service principals that have privileges on this catalog. Additionally, set up workspace-catalog bindings to isolate user data access.

### Using the Databricks CLI (alternative)

```bash
export CONNECTION_NAME="neon_postgresql_connection"
export DB_HOST="ep-cool-darkness-123456.us-east-2.aws.neon.tech"
export DB_PORT="5432"
export DB_DATABASE="dbname"
export DB_USER="databricks_replication"
export DB_PASSWORD="your_secure_password"

databricks connections create --json "{
  \"name\": \"${CONNECTION_NAME}\",
  \"connection_type\": \"POSTGRESQL\",
  \"options\": {
    \"host\": \"${DB_HOST}\",
    \"port\": \"${DB_PORT}\",
    \"database\": \"${DB_DATABASE}\",
    \"user\": \"${DB_USER}\",
    \"password\": \"${DB_PASSWORD}\"
  }
}"
```

## Step 3: Create the Lakeflow Connect gateway and ingestion pipeline

The Lakeflow PostgreSQL connector uses two pipelines:

- **Gateway pipeline**: Connects to Neon via the Unity Catalog connection, continuously extracts snapshot and CDC data using logical replication, and writes raw data into a staging volume in Unity Catalog.
- **Ingestion pipeline**: Reads from the staging volume and applies changes into destination streaming tables in your target catalog and schema.

### Create the gateway and pipeline in the Databricks UI

1. In the Lakehouse sidebar, click **Data ingestion**.
2. On **Add data**, under Databricks connectors, select **PostgreSQL**.
3. **Connection**: Choose the PostgreSQL connection you created (e.g. `neon_postgresql_connection`), then click **Next**.
4. **Ingestion setup**:
   - Select **Change data capture**.
   - **Ingestion pipeline name**: e.g. `neon_to_lakehouse_ingestion`.
   - **Event log catalog and schema**: Choose where the pipeline event log will be stored.
   - (Optional) Turn **Auto full refresh for all tables** on if you want the pipeline to automatically fix certain schema or log issues via full refreshes.
   - **Gateway name**: e.g. `neon_postgresql_gateway`.
   - **Staging catalog and schema**: Choose where the staging volume for CDC data will live.
   - Click **Create pipeline and continue**.
5. **Source (select tables)**: Databricks introspects Neon via the connection. Select the tables to replicate (e.g. `public.playing_with_neon`). Optionally set a custom **Destination name** per table or configure **History tracking** (SCD type 2). Click **Next**.
6. **Destination**: Choose the Unity Catalog catalog and schema that will hold the replicated Delta tables. Click **Next**.
7. **Database setup (Neon replication config)**: If requested, for each source Neon database, set:
   - **Replication slot name**: `databricks_slot`
   - **Publication name**: `databricks_publication`
     These must match the slot and publication you created in Neon. This step may not be necessary if you have only one replication slot. Optionally, click `Validate` to ensure your database setup is correct. This may take a few minutes. Issues are reported if encountered.
8. **Schedules and notifications** (optional): Set how often the ingestion pipeline runs (e.g. every 5 or 15 minutes) and add email notifications for failures or successful runs.
9. Click **Save and run pipeline** to start the first full snapshot and CDC extraction.

The gateway runs continuously on classic compute to keep up with Neon's WAL stream. The ingestion pipeline runs on serverless compute on the schedule you define.

### Alternative: Declarative Automation Bundles or CLI

If you use code-defined infrastructure, the Databricks PostgreSQL ingestion documentation includes sample bundle YAML and CLI JSON for the gateway and pipeline. Use your `neon_postgresql_connection`, `slot_name`: `databricks_slot`, `publication_name`: `databricks_publication`, and the appropriate source catalog, schema, and table names.

## Step 4: Monitor and maintain the pipeline

- Use the pipeline details page in Databricks to monitor row counts and status (e.g. Upserted and Deleted counts per run).
- Keep the gateway running continuously to avoid WAL buildup on Neon.
- Periodically check replication slots on Neon and [drop unused slots](https://neon.com/docs/guides/logical-replication-manage#remove-a-replication-slot) if you delete pipelines; Databricks does not drop slots automatically.

Databricks recommends limiting each ingestion pipeline to roughly 250 tables or fewer for best performance.

## Step 5: Verify the replication in Databricks

After the initial run completes (full snapshot and any CDC):

1. In your Databricks workspace, open **SQL Editor**.
2. Query the replicated table. For example, if you wrote into catalog `workspace` and schema `public`:

```sql
SELECT * FROM workspace.public.playing_with_neon LIMIT 10;
```

Replace `workspace` with your Unity Catalog name, `public` with the destination schema you chose, and `playing_with_neon` with the destination table name (same as source or the custom name you set). You should see rows from your Neon table in the Delta table.

## Notes and limitations (Lakeflow Connect PostgreSQL)

- **Primary only**: The connector does not support logical replication from read replicas or standbys. Always point Lakeflow Connect at the Neon primary.
- **Authentication**: Username and password only; no IAM-based auth for the PostgreSQL connector.
- **Replication slots**: The gateway must run continuously to prevent WAL bloat. Replication slots are not removed when you delete a pipeline; drop them explicitly in Neon.
- **Replica identity**: Each replicated table must have `REPLICA IDENTITY` set to `DEFAULT` or `FULL` as appropriate.
- **Scale**: Keep each pipeline to about 250 tables or fewer for best performance; there is no hard row or column limit per table.
- **Neon compatibility**: The connector supports PostgreSQL 13+ on various managed and self-hosted sources. Neon is a managed Postgres service that exposes a standard primary with logical replication; validate in a non-production environment and coordinate with Databricks Support for mission-critical use.

For adding tables, monitoring lag, and cleaning up slots, see Databricks' [Maintain PostgreSQL ingestion pipelines](https://docs.databricks.com/aws/en/ingestion/lakeflow-connect/postgresql-maintenance) documentation and [Logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon).

## References

**Databricks**

- [Configure PostgreSQL for ingestion into Databricks](https://docs.databricks.com/en/ingestion/lakeflow-connect/postgresql/configure-postgresql.html) (Lakeflow Connect)
- [Ingest data from PostgreSQL](https://docs.databricks.com/en/ingestion/lakeflow-connect/postgresql/ingest-postgresql.html) (Lakeflow Connect PostgreSQL pipeline)
- [PostgreSQL connector FAQs](https://docs.databricks.com/en/ingestion/lakeflow-connect/postgresql/faq.html)
- [PostgreSQL connector limitations](https://docs.databricks.com/en/ingestion/lakeflow-connect/postgresql/limitations.html)

**Neon**

- [Logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon)
- [Logical replication commands](https://neon.com/docs/guides/logical-replication-manage)

**PostgreSQL**

- [Logical replication](https://www.postgresql.org/docs/current/logical-replication.html)
- [Publications](https://www.postgresql.org/docs/current/logical-replication-publication.html)

--- [Document source](https://neon.com/docs/guides/logical-replication-decodable.md) ---

> Summary: Logical replication from Lakebase Postgres to Decodable uses a Postgres CDC connector (Apache Flink and Debezium) to stream row-level changes into Decodable streams for routing to sinks such as Snowflake, Kafka, Amazon S3, or Elasticsearch. Use this guide when you need continuous, low-latency change capture from Neon with optional SQL or Flink transformations before data reaches its destination. Setup requires enabling wal_level=logical on the Neon project (irreversible) and setting replica identity to FULL on each source table. Connect Decodable using a direct non-pooled connection string.

# Replicate data with Decodable

Learn how to replicate data from Neon with Decodable

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

[Decodable](https://www.decodable.co/) is a fully managed platform for ETL, ELT, and stream processing,
powered by Apache Flink® and Debezium.

In this guide, you will learn how to configure a Postgres source connector in Decodable for ingesting changes from your Neon database so that you can replicate data from Lakebase Postgres to any of Decodable's [supported data sinks](https://docs.decodable.co/connections.html#sinks), optionally processing the data with SQL or custom Flink jobs.

## Prerequisites

- A [Decodable account](https://www.decodable.co/) ([start free](https://app.decodable.co/-/accounts/create), no credit card required)
- A [Neon account](https://console.neon.tech/)
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Enable logical replication in Neon

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, meaning active connections will be dropped and have to reconnect.

To enable logical replication in Neon:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor):

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

## Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/reference/api/branches/create-project-branch-role)

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

## Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

## Create a publication

For each table you would like to ingest into Decodable, set its [replica identity](https://www.postgresql.org/docs/current/logical-replication-publication.html) to `FULL`.
To do so, issue the following statement in the **Neon SQL Editor**:

```sql
ALTER TABLE <tbl1> REPLICA IDENTITY FULL;
```

Next, create a [publication](https://www.postgresql.org/docs/current/sql-createpublication.html) with the name `dbz_publication`. Include all the tables you would like to ingest into Decodable.

```sql
CREATE PUBLICATION dbz_publication FOR TABLE <tbl1, tbl2, tbl3>>;
```

Refer to the [Postgres docs](https://www.postgresql.org/docs/current/sql-alterpublication.html) if you need to add or remove tables from your publication.

Upon start-up, the Decodable connector for Postgres will automatically create the [replication slot](https://www.postgresql.org/docs/current/logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS) required for ingesting data change events from Postgres.
The slot's name will be prefixed with `decodable_`, followed by a unique identifier.

## Allow inbound traffic

If you are using Neon's **IP Allow** feature to limit the IP addresses that can connect to Neon, you will need to allow inbound traffic from Decodable's IP addresses.
Refer to the [Decodable documentation](https://docs.decodable.co/reference/regions-and-ip-addresses.html#ip-addresses) for the list of IPs that need to be allowlisted for the Decodable region of your account.
For information about configuring allowed IPs in Neon, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

## Create a Postgres source connector in Decodable

1. In the Decodable web UI, select **Connections** from the left navigation bar and click **New Connection**.

2. In the connector catalog, choose **Postgres CDC** and click **Connect**.

3. Enter the connection details for your Neon database. You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

   **Important:** Use a **direct connection** to your compute endpoint, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers. When copying your connection string from Neon, make sure it does not include `-pooler` in the hostname. For more information about connection pooling and when to use direct connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

   Your connection string will look like this:

   ```bash
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   Enter the details for **your connection string** into the source connector fields. Based on the sample connection string above, the values would be specified as shown below. Your values will differ.

   - **Connection Type**: Source (the default)
   - **Host**: ep-cool-darkness-123456.us-east-2.aws.neon.tech
   - **Port**: 5432
   - **Database**: dbname
   - **Username**: alex
   - **Password**: Click **Add a new secret...**, then specify a name for that secret and `AbC123dEf` as its value
   - **Decoding Plugin Name**: pgoutput (the default)

   ![Creating a source connector in Decodable](https://neon.com/docs/guides/decodable_create_source_connector.png)

4. Click **Next**. Decodable will now scan the source database for all the tables that can be replicated. Select one or more table(s) by checking the **Sync** box next to their name. Optionally, you can change the name of the destination stream for each table, which by default will be in the form of `<database name>__<schema name>__<table_name>`. You can also take a look a the schema of each stream by clicking **View Schema**.

   ![Selecting source tables in Decodable](https://neon.com/docs/guides/decodable_select_source_tables.png)

5. Click **Next** and specify a name for your connection, for instance: `neon-source`.

6. Click **Create and start**. The default start options in the following dialog don't require any changes, so click **Start** to launch the connector.

## Previewing the data

Once the connector is in **Running** state, navigate to the connected Decodable stream, via **Outbound to...** on the connector's overview tab.
By clicking **Run Preview**, you can examine the change events ingested by the connector.

![Preview of ingested data in Decodable](https://neon.com/docs/guides/decodable_preview_ingested_data.png)

## Next steps

At this point, you have a running connector, which continuously ingests changes from a Neon database into Decodable with low latency.
Next, you could set up one of the supported Decodable **sink connectors** which will propagate the data to a wide range of data stores and systems, such as Snowflake, Elasticsearch, Apache Kafka, Apache Iceberg, Amazon S3, any many more.

If needed, you also can add a **processing step**, either using SQL or by deploying your own Apache Flink job,
for instance, to filter and transform the data before propagating it to an external system.
Of course, you also can take your processed data back to another Neon database, using the Decodable sink connector for Postgres.

## References

- [Decodable: The Pragmatic Approach to Data Movement](https://www.decodable.co/blog/pragmatic-approach-to-data-movement)
- [Getting Started With Decodable](https://docs.decodable.co/welcome.html)
- [Connecting Decodable to Sources and Destinations](https://docs.decodable.co/connections.html)
- [About Decodable Pipelines](https://docs.decodable.co/pipelines.html)
- [Postgres Documentation: Logical Replication](https://www.postgresql.org/docs/current/logical-replication.html)

--- [Document source](https://neon.com/docs/guides/logical-replication-estuary-flow.md) ---

> Summary: Estuary's Neon PostgreSQL source connector streams CDC events from a Lakebase Postgres database to any Estuary materialization destination at sub-100ms latency. Use this guide when you need continuous, low-latency replication of inserts, updates, and deletes from Neon to an external system. Setup requires enabling logical replication (permanently sets wal_level to logical project-wide), a direct non-pooled connection string, and IP allowlisting for Estuary's egress addresses.

# Replicate data with Estuary

Learn how to replicate data from Neon with Estuary

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

[Estuary](https://estuary.dev/) (formerly Estuary Flow) is a real-time data streaming platform that allows you to connect, transform, and move data from various sources to destinations with sub-100ms latency.

In this guide, you will learn how to configure a Postgres source connector in Estuary for ingesting changes from your Neon database, enabling you to replicate data from Lakebase Postgres to any of Estuary's [supported destinations](https://docs.estuary.dev/reference/Connectors/materialization-connectors/#available-materialization-connectors), with optional transformations along the way.

## Prerequisites

- An [Estuary account](https://dashboard.estuary.dev/register) (start free, no credit card required)
- A [Neon account](https://console.neon.tech/)
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Enable Logical Replication in Neon

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, meaning active connections will be dropped and have to reconnect.

To enable logical replication in Neon:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor):

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

## Create a Postgres Role for Replication

It is recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon Console, CLI, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/reference/api/branches/create-project-branch-role)

```bash
neon roles create --name cdc_role
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name (for example, `cdc_role`).
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "cdc_role"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

## Grant Schema Access to Your Postgres Role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. Run these commands for each schema:

```sql
GRANT USAGE ON SCHEMA public TO cdc_role;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO cdc_role;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO cdc_role;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

## Create a Publication

Create a [publication](https://www.postgresql.org/docs/current/sql-createpublication.html) with the name `estuary_publication`. Include all the tables you would like to ingest into Estuary.

```sql
CREATE PUBLICATION estuary_publication FOR TABLE <tbl1, tbl2, tbl3>;
```

Refer to the [Postgres docs](https://www.postgresql.org/docs/current/sql-alterpublication.html) if you need to add or remove tables from your publication.

Upon startup, the Estuary connector for Postgres will automatically create the [replication slot](https://www.postgresql.org/docs/current/logicaldecoding-explanation.html#LOGICALDECODING-REPLICATION-SLOTS) required for ingesting data change events from Postgres. The slot's name will be prefixed with `estuary_`, followed by a unique identifier.

## Allow Inbound Traffic

If you are using Neon's **IP Allow** feature to limit the IP addresses that can connect to Neon, you will need to allow inbound traffic from Estuary's IP addresses.
Refer to the [Estuary documentation](https://docs.estuary.dev/reference/allow-ip-addresses/#ip-addresses-to-allowlist) for the list of IPs that need to be allowlisted for the Estuary region of your account.
For information about configuring allowed IPs in Neon, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

## Create a Postgres Source Connector in Estuary

1. In the Estuary web UI, select **Sources** from the left navigation bar and click **New Capture**.

2. In the connector catalog, choose **Neon PostgreSQL** and click **Connect**.

3. Enter the connection details for your Neon database. You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

   **Important:** Use a **direct connection** to your compute endpoint, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers. When copying your connection string from Neon, make sure it does not include `-pooler` in the hostname. For more information about connection pooling and when to use direct connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

   Your connection string will look like this:

   ```bash
   postgres://cdc_role:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   ![Creating a Neon capture connector in Estuary](https://neon.com/docs/guides/estuary_flow_create_neon_capture.png)

   Enter the details for **your connection string** into the source connector fields. Based on the sample connection string above, the values would be specified as shown below. Your values will differ.

   - **Name:**: Name of the Capture connector
   - **Server Address**: ep-cool-darkness-123456.us-east-2.aws.neon.tech:5432
   - **User**: cdc_role
   - **Password**: Click **Add a new secret...**, then specify a name for that secret and `AbC123dEf` as its value
   - **Database**: dbname

   ![Configuring Neon capture in Estuary](https://neon.com/docs/guides/estuary_flow_configure_neon_capture.png)

4. Click **Next**. Estuary will now scan the source database for all the tables that can be replicated. Select one or more tables by checking the checkbox next to their name.
   Optionally, you can change the name of the destination name for each table. You can also take a look at the schema of each stream by clicking on the **Collection** tab.

   ![Selecting collections for replication in Estuary](https://neon.com/docs/guides/estuary_flow_configure_collections.png)

5. Click **Save and Publish** to provision the connector and kick off the automated backfill process.

## Previewing the Data

Once the connector is up and running state, navigate to the Collections page in the Estuary dashboard and click on the collection being filled by your capture.

![Preview data in Estuary](https://neon.com/docs/guides/estuary_flow_preview_collections.png)

--- [Document source](https://neon.com/docs/guides/logical-replication-fivetran.md) ---

> Summary: Logical replication from Neon to Fivetran lets you stream Postgres WAL changes to any Fivetran-supported destination by configuring a pgoutput replication slot and publication on Lakebase Postgres, then connecting Fivetran via a direct (non-pooled) connection. Use this page when setting up Neon as a PostgreSQL source in Fivetran. Note that enabling logical replication is a one-way, irreversible change, and Fivetran IPs must be added to Neon's IP Allow list.

# Replicate data with Fivetran

Learn how to replicate data from Neon with Fivetran

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

[Fivetran](https://fivetran.com/) is an automated data movement platform that helps you centralize data from disparate sources, which you can then manage directly from your browser. Fivetran extracts your data and loads it into your data destination.

In this guide, you will learn how to define a Lakebase Postgres database as a data source in Fivetran so that you can replicate data to one or more of Fivetran's supported destinations.

## Prerequisites

- A [Fivetran account](https://fivetran.com/)
- A [Neon account](https://console.neon.tech/)
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Enable logical replication in Neon

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, meaning active connections will be temporarily dropped before automatically reconnecting.

To enable logical replication in Neon:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor):

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

## Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/reference/api/branches/create-project-branch-role)

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

## Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

## Create a publication

Create the Postgres publication. Include all tables you want to replicate as part of the publication:

```sql
CREATE PUBLICATION fivetran_pub FOR TABLE <tbl1, tbl2, tbl3>;
```

The publication name is customizable. Refer to the [Postgres docs](https://www.postgresql.org/docs/current/logical-replication-publication.html) if you need to add or remove tables from your publication.

## Create a replication slot

Fivetran requires a dedicated replication slot. Only one source should be configured to use this replication slot.

Fivetran uses the `pgoutput` plugin in Postgres for decoding WAL changes into a logical replication stream. To create a replication slot called `fivetran_slot` that uses the `pgoutput` plugin, run the following command on your database using your replication role:

```sql
SELECT pg_create_logical_replication_slot('fivetran_pgoutput_slot', 'pgoutput');
```

The name assigned to the replication slot is `fivetran_pgoutput_slot`. You will need to provide this name when you set up your Fivetran source.

## Create a Postgres source in Fivetran

1. Log in to your [Fivetran](https://fivetran.com/) account.

2. On the **Select your datasource** page, search for the **PostgreSQL** source and click **Set up**.

3. In your connector setup form, enter a value for **Destination Schema Prefix**. This prefix applies to each replicated schema and cannot be changed once your connector is created. In this example, we'll use `neon` as the prefix.

4. Enter the connection details for your Neon database. You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

   **Important:** Use a **direct connection** to your compute endpoint, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers. When copying your connection string from Neon, make sure it does not include `-pooler` in the hostname. For more information about connection pooling and when to use direct connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

   For example, let's say this is your connection string:

   ```bash
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   From this string, the values in the Fivetran **Create a source** dialog would show as below. Your actual values will differ, with the exception of the port number.

   - **Host**: ep-cool-darkness-123456.us-east-2.aws.neon.tech
   - **Port**: 5432
   - **Username**: alex
   - **Password**: AbC123dEf
   - **Database Name**: dbname

5. For **Connection Method**, select **Logical replication of the WAL using the pgoutput plugin** and enter values for the **Replication Slot** and **Publication Name**. You defined these values earlier (`fivetran_pgoutput_slot` and `fivetran_pub`, respectively).

   ![Fivetran connector setup](https://neon.com/docs/guides/fivetran_connector_setup.png)

6. If you are using Neon's **IP Allow** feature to limit IP addresses that can connect to Neon, add Fivetran's IPs to your allowlist in Neon.

   ![Fivetran IP addresses](https://neon.com/docs/guides/fivetran_ips.png)

   For instructions, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow). You'll need to do this before you can validate your connection in the next step. If you are not using Neon's **IP Allow** feature, you can skip this step.

7. Click **Save & Test**. Fivetran tests and validates the connection to your database. Upon successful completion of the setup tests, you can sync your data using Fivetran.

   During the test, Fivetran asks you to confirm the certificate chain by selecting the certificate to use as the trust anchor. Select the `CN=ISRG Root X1, 0=Internet Security Research Group, C=US` option. This certificate is valid until 2035-06-04.

   When the connection test is completed, you should see an **All connection tests passed!** message in Fivetran, as shown below:

   ![Fivetran all connections passed message](https://neon.com/docs/guides/fivetran_connection_test.png)

8. Click **Continue**.

9. On the **Select Data to Sync** page, review the connector schema and select any columns you want to block or hash.

   ![Fivetran select data to sync page](https://neon.com/docs/guides/fivetran_select_data.png)

10. Click **Save & Continue**.

11. On the **How would you like to handle changes?** page, specify how you would like to handle future schema changes. For this example, we'll select **We will allow all new schemas, tables and columns**. Choose the option that best fits your organization's requirements.

    ![Fivetran how to handle changes](https://neon.com/docs/guides/fivetran_changes.png)

12. Click **Continue**. Your data is now ready to sync.

    ![Fivetran data is ready to sync page](https://neon.com/docs/guides/fivetran_ready_to_sync.png)

13. Click **Start Initial Sync** to enable syncing.

## References

- [Fivetran Generic PostgreSQL Setup Guide](https://fivetran.com/docs/databases/postgresql/setup-guide)

--- [Document source](https://neon.com/docs/guides/logical-replication-guide.md) ---

> Summary: Neon logical replication streams data between Lakebase Postgres and external systems using Postgres's native publisher-subscriber model. Find guides for CDC to data warehouses, live migrations from AWS RDS, Google Cloud SQL, AlloyDB, or Supabase, and cross-region Neon-to-Neon replication. Logical replication must be explicitly enabled per project, cannot be reverted, and Neon can act as either publisher or subscriber.

# Get started with logical replication

Learn how to replicate data to and from your Lakebase Postgres database

Last updated: 2026-10-21

Neon's logical replication feature, available to all Neon users, allows you to replicate data to and from your Lakebase Postgres database:

- Stream data from your Neon database to external destinations, enabling Change Data Capture (CDC) and real-time analytics. External sources might include data warehouses, analytical database services, real-time stream processing systems, messaging and event-streaming platforms, and external Postgres databases, among others. See [Replicate data from Neon](https://neon.com/docs/guides/logical-replication-guide#replicate-data-from-neon).
- Perform live migrations to Neon from external sources such as AWS RDS and Google Cloud SQL — or any platform that runs Postgres. See [Replicate data to Neon](https://neon.com/docs/guides/logical-replication-guide#replicate-data-to-neon).
- Replicate data from one Neon project to another for Neon project, account, Postgres version, or region migration. See [Replicate data from one Neon project to another](https://neon.com/docs/guides/logical-replication-neon-to-neon).

![Neon logical replication subscribers image](https://neon.com/docs/guides/logical_replication_publishers_subscribers.jpg)

Logical replication in Neon works like it does on any standard Postgres installation. It uses a publisher-subscriber model to replicate data from the source database to the destination database. Neon can act as a publisher or subscriber.

Replication starts by copying a snapshot of the data from the publisher to the subscriber. Once this is done, subsequent changes are sent to the subscriber as they occur in real-time.

To learn more about Postgres logical replication, see the following topics.

## Learn about logical replication

- [Logical replication concepts](https://neon.com/docs/guides/logical-replication-concepts): Learn about Postgres logical replication concepts
- [Logical replication commands](https://neon.com/docs/guides/logical-replication-manage): Commands for managing your logical replication configuration
- [Logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon): Information about logical replication specific to Neon
- [Managing schema changes](https://neon.com/docs/guides/logical-replication-schema-changes): Learn about managing schema changes in a logical replication setup

To get started, jump into one of our step-by-step logical replication guides.

## Replicate data from Neon

**Note:** To replicate data from Neon, you must first enable logical replication on your project. This setting cannot be reverted once enabled. See [Enable logical replication](https://neon.com/docs/guides/logical-replication-neon#enable-logical-replication) for Console and API instructions.

- [Airbyte](https://neon.com/docs/guides/logical-replication-airbyte): Replicate data from Neon with Airbyte
- [ClickHouse](https://neon.com/docs/guides/logical-replication-clickhouse): Replicate data from Neon to ClickHouse using ClickPipes
- [Confluent (Kafka)](https://neon.com/docs/guides/logical-replication-kafka-confluent): Replicate data from Neon with Confluent (Kafka)
- [Databricks](https://neon.com/docs/guides/logical-replication-databricks): Replicate data from Neon to Databricks
- [Decodable](https://neon.com/docs/guides/logical-replication-decodable): Replicate data from Neon with Decodable
- [Estuary](https://neon.com/docs/guides/logical-replication-estuary-flow): Replicate data from Neon with Estuary
- [Fivetran](https://neon.com/docs/guides/logical-replication-fivetran): Replicate data from Neon with Fivetran
- [Materialize](https://neon.com/docs/guides/logical-replication-materialize): Replicate data from Neon to Materialize
- [Neon to Lakebase](https://neon.com/docs/guides/logical-replication-neon-to-lakebase): Replicate data from Neon to Lakebase Postgres on Databricks
- [Neon to Neon](https://neon.com/docs/guides/logical-replication-neon-to-neon): Replicate data from Neon to Neon
- [Neon to PostgreSQL](https://neon.com/docs/guides/logical-replication-postgres): Replicate data from Neon to PostgreSQL
- [Snowflake](https://neon.com/docs/guides/logical-replication-airbyte-snowflake): Replicate data from Neon to Snowflake with Airbyte
- [Inngest](https://neon.com/docs/guides/logical-replication-inngest): Replicate data from Neon to Inngest

## Replicate data to Neon

- [AlloyDB](https://neon.com/docs/guides/logical-replication-alloydb): Replicate data from AlloyDB to Neon
- [Azure PostgreSQL](https://neon.com/docs/import/migrate-from-azure-postgres): Replicate data from Azure PostgreSQL to Neon
- [Cloud SQL](https://neon.com/docs/guides/logical-replication-cloud-sql): Replicate data from Cloud SQL to Neon
- [Lakebase to Neon](https://neon.com/docs/guides/logical-replication-lakebase-to-neon): Replicate data from Lakebase Postgres on Databricks to Neon
- [Neon to Neon](https://neon.com/docs/guides/logical-replication-neon-to-neon): Replicate data from Neon to Neon
- [PostgreSQL to Neon](https://neon.com/docs/guides/logical-replication-postgres-to-neon): Replicate data from PostgreSQL to Neon
- [RDS](https://neon.com/docs/guides/logical-replication-rds-to-neon): Replicate data from AWS RDS PostgreSQL to Neon
- [Supabase](https://neon.com/docs/guides/logical-replication-supabase-to-neon): Replicate data from Supabase to Neon

--- [Document source](https://neon.com/docs/guides/logical-replication-inngest.md) ---

> Summary: Inngest's native Neon integration uses Postgres logical replication to convert row-level database changes into typed events (such as db/users.updated) that trigger durable, serverless TypeScript workflows. Choose this approach when you need to forward Lakebase Postgres changes to third-party destinations like Amplitude or S3 without writing a custom replication consumer. Setup requires enabling logical replication in the Neon console and supplying admin credentials to the Inngest integration wizard (credentials are not stored).

# Replicate data with Inngest

Learn how to replicate data from Neon with Inngest

Last updated: 2026-09-16

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

[Inngest](https://www.inngest.com?utm_source=neon\&utm_medium=logical-replication-guide) is a durable workflow platform that allows you to trigger workflow based on Neon database changes. With its native Neon integration, it is the easiest way to set up data replication with custom transformations or 3rd party API destinations (ex, Neon to Amplitude, Neon to S3).

In this guide, you will learn how to configure your Inngest account for ingesting changes from your Neon database, enabling you to replicate data from Lakebase Postgres to Inngest workflows.

## Prerequisites

- A [Inngest account](https://www.inngest.com?utm_source=neon\&utm_medium=logical-replication-guide)
- A [Neon account](https://console.neon.tech/)
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Enabling Logical Replication on your database

The Inngest Integration relies on Neon's Logical Replication feature to get notified upon database changes.

Navigate to your Neon Project using the Neon Console and open the **Settings** > **Postgres** page. From here, follow the instructions to enable Logical Replication:

![Neon dashboard settings with option to enable logical replication](https://neon.com/docs/guides/neon-console-settings-logical-replication.png)

## Configuring the Inngest integration

Your Neon database is now ready to work with Inngest.

To configure the Inngest Neon Integration, navigate to the Inngest Platform, open the [Integrations page](https://app.inngest.com/settings/integrations?utm_source=neon\&utm_medium=trigger-serverless-functions-guide), and follow the instructions of the [Neon Integration installation wizard](https://app.inngest.com/settings/integrations/neon/connect?utm_source=neon\&utm_medium=trigger-serverless-functions-guide):

![Neon integration card inside the Inngest integrations page](https://neon.com/docs/guides/inngest-integrations-page.png)

The Inngest Integration requires Postgres admin credentials to complete its setup. _These credentials are not stored and are only used during the installation process_.

![Neon authorization step inside the Inngest integrations page](https://neon.com/docs/guides/inngest-integration-neon-authorize-step.png)

You can find your admin Neon database connection credentials by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For details, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app). Use a direct connection, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers, so make sure the connection string does not include `-pooler` in the hostname. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Example: Replicating data to Amplitude

The below example demonstrates how to replicate new `users` table rows to Amplitude using Amplitude's API.

Once the Inngest integration is installed, a flow of `"db/*"` events will be created when updates are made to your database.

For example, if you create a new user in your database, a `"db/users.updated"` [event](https://www.inngest.com/docs/features/events-triggers?utm_source=neon\&utm_medium=logical-replication-guide) will be created:

```json
{
  "name": "db/users.updated",
  "data": {
    "new": {
      "id": {
        "data": 2,
        "encoding": "i"
      },
      "name": {
        "data": "Charly",
        "encoding": "t"
      },
      "email": {
        "data": "charly@inngest.com",
        "encoding": "t"
      }
    },
    "table": "users",
    "txn_commit_time": "2024-09-24T14:41:19.75149Z",
    "txn_id": 36530520
  },
  "ts": 1727146545006
}
```

Such events can be used to trigger Inngest functions to transform and replicate data to external destinations like Amplitude:

```typescript
// inngest/functions/users-replication.ts
import { inngest } from './client';

export const updateAmplitudeUserMapping = inngest.createFunction(
  { id: 'update-amplitude-user-mapping' },
  { event: 'db/users.updated' },
  async ({ event, step }) => {
    // Extract the user data from the event
    const { data } = event;
    const { id, email } = data.new;

    // Update the user mapping in Amplitude
    await step.run('update-amplitude-user-mapping', async () => {
      const response = await fetch(
        `https://api.amplitude.com/usermap?mapping=[{"user_id":"${id}", "global_user_id": "${email}"}]&api_key=${process.env.AMPLITUDE_API_KEY}`
      );

      if (!response.ok) {
        throw new Error(`Failed to send user data to Amplitude: ${response.statusText}`);
      }

      return response.json();
    });

    return { success: true };
  }
);
```

--- [Document source](https://neon.com/docs/guides/logical-replication-kafka-confluent.md) ---

> Summary: Confluent Cloud CDC pipeline from Lakebase Postgres streams WAL change events (inserts, updates, deletes) to a Kafka topic using the PostgreSQL CDC Source Connector (Debezium) with pgoutput or wal2json decoding. Use this guide when you need real-time Kafka replication from Neon to Confluent Cloud. You'll need to configure a logical replication slot, publication, and dedicated replication role before connecting. The connector takes an initial snapshot then streams all subsequent row-level changes; active subscriber connections prevent scale-to-zero and may increase billing.

# Replicate data with Kafka (Confluent) and Debezium

Learn how to replicate data from Neon with Kafka (Confluent) and Debezium

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

Confluent Cloud is a fully managed, cloud-native real-time data streaming service, built on Apache Kafka. It allows you to stream data from various sources, including Postgres, and build apps that consume messages from an Apache Kafka cluster.

In this guide, you will learn how to stream data from a Lakebase Postgres database to a Kafka cluster in Confluent Cloud. You will use the [PostgreSQL CDC Source Connector (Debezium) for Confluent Cloud](https://docs.confluent.io/cloud/current/connectors/cc-postgresql-cdc-source-debezium.html) to read Change Data Capture (CDC) events from the Write-Ahead Log (WAL) of your Neon database in real-time. The connector will write events to a Kafka stream and auto-generate a Kafka topic. The connector performs an initial snapshot of the table and then streams any future change events.

**Note:** Confluent Cloud Connectors can be set up using the [Confluent Cloud UI](https://confluent.cloud/home) or the [Confluent command-line interface (CLI)](https://docs.confluent.io/confluent-cli/current/overview.html). This guide uses the Confluent Cloud UI.

## Prerequisites

- A [Confluent Cloud](https://www.confluent.io/confluent-cloud) account
- A [Neon account](https://console.neon.tech/)
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Enable logical replication in Neon

**Important:** Enabling logical replication modifies the PostgreSQL `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, which means that active connections will be dropped and have to reconnect.

To enable logical replication in Neon:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor):

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

## Create a publication

In this example, we'll create a publication for a `users` table in the `public` schema of your Neon database.

1. Create the `users` table in your Neon database. You can do this via the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or by connecting to your Neon database from an SQL client such as [psql](https://neon.com/docs/connect/query-with-psql-editor).

   ```sql
   CREATE TABLE users (
     id SERIAL PRIMARY KEY,
     username VARCHAR(50) NOT NULL,
     email VARCHAR(100) NOT NULL
   );
   ```

2. Create a publication for the `users` table:

   ```sql
   CREATE PUBLICATION users_publication FOR TABLE users;
   ```

This command creates a publication, named `users_publication`, which will include all changes to the `users` table in your replication stream.

## Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/reference/api/branches/create-project-branch-role)

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

## Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

## Create a replication slot

The Debezium connector requires a dedicated replication slot. Only one source should be configured to use this replication slot.

To create a replication slot called `debezium`, run the following command on your database using your replication role:

```sql
SELECT pg_create_logical_replication_slot('debezium', 'pgoutput');
```

- `debezium` is the name assigned to the replication slot. You will need to provide the slot name when you set up your source connector in Confluent.
- `pgoutput` is the logical decoder plugin used in this example. Neon supports both `pgoutput` and `wal2json` decoder plugins.

## Set up a Kafka cluster in Confluent Cloud

1. Sign in to Confluent Cloud at [https://confluent.cloud](https://confluent.cloud).
2. Click **Add cluster**.
3. On the **Create cluster** page, for the **Basic cluster**, select **Begin configuration**.
4. On the **Region/zones** page, choose a cloud provider, a region, and select a single availability zone.
5. Select **Continue**.
6. Specify your payment details. You can select **Skip payment** for now if you're just trying out the setup.
7. Specify a cluster name, review the configuration and cost information, and select **Launch cluster**. In this example, we use `cluster_neon` as the cluster name.
   It may take a few minutes to provision your cluster. After the cluster has been provisioned, the **Cluster Overview** page displays.

## Set up a source connector

To set up a Postgres CDC source connector for Confluent Cloud:

1. On the **Cluster Overview** page, under **Set up connector**, select **Get started**.

2. On the **Connector Plugins** page, enter `Postgres` into the search field.

3. Select the **Postgres CDC Source** connector. This is the [PostgreSQL CDC Source Connector (Debezium) for Confluent Cloud](https://docs.confluent.io/cloud/current/connectors/cc-postgresql-cdc-source-debezium.html). This connector will take a snapshot of the existing data and then monitor and record all subsequent row-level changes to that data.

4. On the **Add Postgres CDC Source connector** page:

   - Select the type of access you want to grant the connector. For the purpose of this guide, we'll select **Global access**, but if you are configuring a production pipeline, Confluent recommends **Granular access**.
   - Click the **Generate API key & download** button to generate an API key and secret that your connector can use to communicate with your Kafka cluster. Your applications will need this API key and secret to make requests to your Kafka cluster. Store the API key and secret somewhere safe. This is the only time you'll see the secret.

   Click **Continue**.

5. On the **Add Postgres CDC Source connector** page:

   - Add the connection details for your Neon database. You can find your admin Neon database connection credentials by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

   **Important:** Use a **direct connection** to your compute endpoint, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers. When copying your connection string from Neon, make sure it does not include `-pooler` in the hostname. For more information about connection pooling and when to use direct connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

   Your connection string will look something like this:

   ```text
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   Enter the details for **your connection string** into the source connector fields. Based on the sample connection string above, the values would be specified as shown below. Your values will differ.

   - **Database name**: `dbname`

   - **Database server name**: `neon_server` (This is a user-specified value that will represent the logical name of your Postgres server. Confluent uses this name as a namespace in all Kafka topic and schema names. It is also used for Avro schema namespaces if the Avro data format is used. The Kafka topic will be created with the prefix `database.server.name`. Only alphanumeric characters, underscores, hyphens, and dots are allowed.)

   - **SSL mode**: `require`

   - **Database hostname** `ep-cool-darkness-123456.us-east-2.aws.neon.tech` (this example shows the portion of a Neon connection string forms the database hostname)

   - **Database port**: `5432` (Neon uses port `5432`)

   - **Database username**: `alex`

   - **Database Password** `AbC123dEf`

   - If you use Neon's **IP Allow** feature to limit IP addresses that can connect to Neon, you will need to add the Confluent cluster static IP addresses to your allowlist. For information about configuring allowed IPs in Neon, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow). If you do not use Neon's **IP Allow** feature, you can skip this step.

   Click **Continue**.

6. Under **Output Kafka record value format**, select an output format for Kafka record values. The default is `JSON`, so we'll use that format in this guide. Other supported values include `AVRO`, `JSON_SR`, and `PROTOBUF`, which are schema-based message formats. If you use any of these, you must also configure a [Confluent Cloud Schema Registry](https://docs.confluent.io/cloud/current/sr/index.html).

   Expand the **Show advanced configurations** drop-down and set the following values:

   - Under **Advanced configuration**
     - Ensure **Slot name** is set to `debezium`. This is the name of the replication slot you created earlier.
     - Set the **Publication name** to `users_publication`, which is the name of the publication you created earlier.
     - Set **Publication auto-create** mode to `disabled`. You've already created your publication.
   - Under **Database details**, set **Tables included** to `public.users`, which is the name of the Neon database table you are replicating from.

   Click **Continue**.

7. For **Connector sizing**, accept the default for the maximum number of [Tasks](https://docs.confluent.io/platform/current/connect/index.html#tasks). Tasks can be scaled up at a later time for additional throughput capacity.

   Click **Continue**.

8. Adjust your **Connector name** if desired, and review your **Connector configuration**, which is provided in `JSON` format, as shown below. We'll use the default connector name in this guide.

   ```json
   {
     "connector.class": "PostgresCdcSource",
     "name": "PostgresCdcSourceConnector_0",
     "kafka.auth.mode": "KAFKA_API_KEY",
     "kafka.api.key": "2WY3UABFDN7DDFIV",
     "kafka.api.secret": "****************************************************************",
     "schema.context.name": "default",
     "database.hostname": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
     "database.port": "5432",
     "database.user": "alex",
     "database.password": "************",
     "database.dbname": "dbname",
     "database.server.name": "neon_server",
     "database.sslmode": "require",
     "publication.name": "users_publication",
     "publication.autocreate.mode": "all_tables",
     "snapshot.mode": "initial",
     "tombstones.on.delete": "true",
     "plugin.name": "pgoutput",
     "slot.name": "debezium",
     "poll.interval.ms": "1000",
     "max.batch.size": "1000",
     "event.processing.failure.handling.mode": "fail",
     "heartbeat.interval.ms": "0",
     "provide.transaction.metadata": "false",
     "decimal.handling.mode": "precise",
     "binary.handling.mode": "bytes",
     "time.precision.mode": "adaptive",
     "cleanup.policy": "delete",
     "hstore.handling.mode": "json",
     "interval.handling.mode": "numeric",
     "schema.refresh.mode": "columns_diff",
     "output.data.format": "JSON",
     "after.state.only": "true",
     "output.key.format": "JSON",
     "json.output.decimal.format": "BASE64",
     "tasks.max": "1"
   }
   ```

   Click **Continue** to provision the connector, which may take a few moments to complete.

## Verify your Kafka stream

To verify that events are now being published to a Kafka stream in Confluent:

1. Insert a row into your `users` table from the Neon SQL Editor or a `psql` client connect to your Neon database. For example:

   ```sql
   -- Insert a new user
   INSERT INTO users (username, email) VALUES ('Zhang', 'zhang@example.com');
   ```

2. In Confluent Cloud, navigate to your cluster (`cluster_neon` in this guide) and select **Topics** > **neon_server.public.users** > **Messages**. Your newly inserted data should appear at the top of the list of messages.

## Next steps

With events now being published to a Kafka stream, you can now set up a connection between Confluent and a supported consumer. This is quite simple using a Confluent Connector. For example, you can stream data to [Databricks](https://docs.confluent.io/cloud/current/connectors/cc-databricks-delta-lake-sink/databricks-aws-setup.html#), [Snowflake](https://docs.confluent.io/cloud/current/connectors/cc-snowflake-sink.html), or one of the other supported consumers. Refer to the Confluent documentation for connector-specific instructions.

## References

- [Quick Start for Confluent Cloud](https://docs.confluent.io/cloud/current/get-started/index.html#cloud-quickstart)
- [Publications - PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication-publication.html)

--- [Document source](https://neon.com/docs/guides/logical-replication-lakebase-to-neon.md) ---

> Summary: Logical replication from Lakebase Postgres on Databricks to Neon streams row-level changes from a publication on a Lakebase database to a subscription on a Neon database. Use this guide for a low-downtime migration from Databricks to Neon, or to keep a Neon copy of Lakebase data in sync. Lakebase runs at wal_level = logical by default. Steps cover enabling password connections and creating a native Postgres password role with REPLICATION on Lakebase, creating a publication, allowing Neon NAT gateway IPs in the Databricks workspace IP access list, creating the target schema and subscription on Neon, verifying replication, resetting sequences, and cutting over.

# Replicate data from Lakebase Postgres on Databricks to Neon

Use logical replication to migrate or stream data from Lakebase Postgres on Databricks to a Neon database

Last updated: 2026-10-21

Neon's logical replication feature lets you replicate data from Lakebase Postgres on Databricks to a Neon database. Neon subscribes to a publication on your Lakebase database, copies the existing data, and then applies each insert, update, and delete as it happens. Use it to:

- **Migrate from Databricks to Neon with minimal downtime**: Keep the Neon database current while your application still runs on Lakebase, then cut over when you're ready.
- **Keep a Neon copy of Lakebase data**: Replicate selected tables to Neon for use with apps and agents built on Neon.

To replicate in the other direction, see [Replicate data from Neon to Lakebase Postgres on Databricks](https://neon.com/docs/guides/logical-replication-neon-to-lakebase).

## Prerequisites

- A Lakebase project on Databricks with a database containing the data you want to replicate, in a workspace on AWS or Azure. If you're just testing this out and need some data to play with, you can use the following statements to create a table with sample data:

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- A Lakebase Postgres role that is a member of the `databricks_superuser` role, to create the publication. See [Create Postgres roles](https://docs.databricks.com/aws/en/oltp/projects/postgres-roles).

- A destination Neon project. For information about creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

**Important: Compute usage on Lakebase**

While Neon is subscribed, the Lakebase compute that publishes changes stays active and doesn't scale to zero. See [Logical replication and scale to zero](https://docs.databricks.com/aws/en/oltp/projects/logical-replication-manage#scale-zero) in the Databricks documentation.

## Prepare your source Lakebase database

This section describes how to prepare your source Lakebase database (the publisher) for replicating data to your Neon database (the subscriber).

Lakebase runs at `wal_level = logical` by default, so you don't need to enable logical replication on the Lakebase project. You also don't need to enable it on the Neon project, because Neon is only the subscriber.

### Enable password connections

Neon connects to Lakebase with a Postgres username and password. Password connections are disabled by default for new Lakebase projects. Enable them for your project. See [Manage password connections](https://docs.databricks.com/aws/en/oltp/projects/manage-roles#block-connections).

### Create a Postgres role for replication

Create a dedicated role for Neon to connect as. Use a **native Postgres password role**, not an OAuth role. OAuth roles authenticate with short-lived Databricks tokens, which a subscription connection string can't use.

The role must have the `REPLICATION` attribute. Roles you create in the Lakebase App, CLI, or API have this attribute automatically. See [Create a native Postgres password role](https://docs.databricks.com/aws/en/oltp/projects/postgres-roles#create-native).

To set the password yourself, create the role with SQL instead. Include the `REPLICATION` attribute, because roles created with SQL don't receive it automatically:

```sql
CREATE ROLE replication_user WITH LOGIN REPLICATION PASSWORD 'AbC123dEf';
```

### Grant schema access to your Postgres role

If your replication role doesn't own the schemas and tables you're replicating from, grant access. For example, the following commands grant access to all tables in the `public` schema to the `replication_user` role:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a publication on the source database

Connect to the Lakebase database as a member of the `databricks_superuser` role, then create a publication. Publications define what gets replicated. Each table in the publication must have a primary key or a [replica identity](https://www.postgresql.org/docs/current/logical-replication-publication.html#LOGICAL-REPLICATION-PUBLICATION-REPLICA-IDENTITY) so that updates and deletes can be replicated.

To create a publication for a specific table:

```sql
CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

### Allow connections from Neon

Neon connects in to Lakebase over the public internet. Private Link isn't supported for logical replication on Lakebase.

If your Databricks workspace uses an IP access list, add the NAT gateway IP addresses for your Neon project's region to it. Neon uses 3 to 6 IP addresses per region for outbound communication, one for each availability zone, so be sure to add all of them. See [NAT Gateway IP addresses](https://neon.com/docs/introduction/regions#nat-gateway-ip-addresses) for the list, and [Manage the IP access list](https://docs.databricks.com/aws/en/security/network/front-end/ip-access-list) in the Databricks documentation for instructions.

## Prepare your Neon destination database

This section describes how to prepare your destination Neon database (the subscriber) to receive replicated data.

### Prepare your database schema

Logical replication copies data, not schema. The tables you replicate must exist in the Neon database with the same names and columns before you create the subscription. Create them empty. The initial copy fails on duplicate keys or constraint violations if a target table already contains rows.

You can create the tables manually or use `pg_dump` and `pg_restore` to dump the schema from Lakebase and load it into Neon. See [Import a database schema](https://neon.com/docs/import/migrate-schema-only) for instructions. Lakebase dumps can include ownership and privileges for Databricks-specific roles that don't exist on Neon, so restore with `--no-owner` and `--no-acl`. See [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations).

If you're using the sample `playing_with_neon` table, you can create the same table on the Neon database with the following statement:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

### Create a subscription

After creating a publication on the source database, create a subscription on the Neon database.

1. Use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), `psql`, or another SQL client to connect to your Neon database. Roles created using the Neon CLI, Console, or API, including the default role created with your project, can create subscriptions.

2. Create the subscription using a `CREATE SUBSCRIPTION` statement.

   ```sql
   CREATE SUBSCRIPTION my_subscription
   CONNECTION 'host=<lakebase-host> port=5432 dbname=databricks_postgres user=replication_user password=AbC123dEf sslmode=verify-full sslrootcert=system'
   PUBLICATION my_publication;
   ```

   - `subscription_name`: A name you chose for the subscription.
   - `connection_string`: The connection details for the source Lakebase database where you defined the publication. Replace `<lakebase-host>` with your Lakebase endpoint hostname, and `databricks_postgres` with your database name if it's different. You can find both in the **Connect** dialog for your Lakebase project. Use the direct hostname, not the `-pooler` connection pooler hostname, because logical replication requires a persistent connection. `sslmode=verify-full` with `sslrootcert=system` encrypts the connection and verifies Lakebase's publicly trusted certificate. `sslrootcert=system` requires Postgres 16 or later on your Neon database. If your Neon project runs Postgres 14 or 15, use `sslmode=require` instead.
   - `publication_name`: The name of the publication you created on the source Lakebase database.

   Creating the subscription creates a replication slot on your Lakebase database, copies the existing rows, and then streams ongoing changes.

3. Verify the subscription was created by running the following command:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription has been created successfully.

**Warning: Replication slots and inactive subscriptions**

If the Neon subscription stops consuming changes, for example because it's disabled or failing, the replication slot on Lakebase becomes inactive. Lakebase removes inactive replication slots after about 40 hours, and the subscription must then be re-created. See [Automatic removal of inactive slots](https://docs.databricks.com/aws/en/oltp/projects/logical-replication-manage#auto-slot-removal) in the Databricks documentation.

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from Lakebase to Neon.

1. Run some data modifying queries on the Lakebase database (inserts, updates, or deletes). If you're using the `playing_with_neon` table, you can use this statement to insert some rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on the Lakebase and Neon databases to make sure the result matches.

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   20
   (1 row)
   ```

Alternatively, you can run the following query on Neon to make sure the `last_msg_receipt_time` is as expected. For example, if you just ran an insert on Lakebase, the `last_msg_receipt_time` should reflect the time of that operation.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

## Switch over your application

When the Neon database has caught up, stop writes on Lakebase and confirm that Neon is fully current.

Logical replication doesn't copy sequence values. Before you resume writes on Neon, reset each sequence to match the replicated data. Otherwise, new inserts into `SERIAL` or identity columns can generate duplicate primary keys. For example:

```sql
SELECT setval(pg_get_serial_sequence('playing_with_neon', 'id'), (SELECT MAX(id) FROM playing_with_neon));
```

Then switch your application to the Neon connection details. You can find them by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. See [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

After your application is running against Neon, drop the subscription on Neon to stop replicating. Dropping the subscription also removes the replication slot on Lakebase.

```sql
DROP SUBSCRIPTION my_subscription;
```

## Related docs

**Neon**

- [Logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon)
- [Replicate data from Neon to Lakebase Postgres on Databricks](https://neon.com/docs/guides/logical-replication-neon-to-lakebase)

**Databricks**

- [Logical replication](https://docs.databricks.com/aws/en/oltp/projects/logical-replication)
- [Replicate data from Lakebase](https://docs.databricks.com/aws/en/oltp/projects/logical-replication-publication)
- [Manage and monitor logical replication](https://docs.databricks.com/aws/en/oltp/projects/logical-replication-manage)

--- [Document source](https://neon.com/docs/guides/logical-replication-manage.md) ---

> Summary: SQL command reference for managing PostgreSQL logical replication objects on Neon: publications, subscriptions, and replication slots. Covers CREATE, ALTER, and DROP syntax, pg_create_logical_replication_slot and pg_drop_replication_slot, and monitoring lag with pg_stat_replication and pg_replication_slots. Use this page after initial setup to reconfigure or remove replication objects. Also explains why DDL changes such as ALTER TABLE require manual intervention on the subscriber.

# Logical replication commands

Commands for managing your logical replication configuration

Last updated: 2026-09-16

This topic provides commands for managing publications, subscriptions, and replication slots.

For step-by-step setup instructions, refer to our [logical replication guides](https://neon.com/docs/guides/logical-replication-guide).

## Publications

This section outlines how to manage **publications** in your replication setup.

### Create a publication

This command creates a publication named `my_publication` that will track changes made to the `users` table:

```sql
CREATE PUBLICATION my_publication FOR TABLE users;
```

This command creates a publication that publishes all changes in two tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

This command creates a publication that only publishes `INSERT` and `UPDATE` operations. Delete operations will not be published.

```sql
CREATE PUBLICATION my_publication FOR TABLE users
    WITH (publish = 'insert,update');
```

### Add a table to a publication

This command adds a table to a publication:

```sql
ALTER PUBLICATION my_publication ADD TABLE sales;
```

### Remove a table from a publication

This command removes a table from a publication:

```sql
ALTER PUBLICATION my_publication DROP TABLE sales;
```

### Remove a publication

This command removes a publication:

```sql
DROP PUBLICATION IF EXISTS my_publication;
```

### Recreate a publication

This command recreates a publication within a single transaction:

```sql
BEGIN;
  -- drop the publication
  DROP PUBLICATION IF EXISTS my_publication;

  -- re-create the publication
  CREATE PUBLICATION my_publication;
COMMIT;
```

## Subscriptions

This section outlines how to manage **subscriptions** in your replication setup.

### Create a subscription

Building on the `my_publication` example in the preceding section, here's how you can create a subscription:

```sql
CREATE SUBSCRIPTION my_subscription
CONNECTION 'postgresql://username:password@host:port/dbname'
PUBLICATION my_publication;
```

A subscription requires a unique name, a database connection string, the name and password of your replication role, and the name of the publication that it subscribes to.

In the example above, `my_subscription` is the name of the subscription that connects to a publication named `my_publication`. In the example above, you would replace the connection details with your Neon database connection string. You can find your Neon connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal.

### Create a subscription with two publications

This command creates a subscription that receives data from two publications:

```sql
CREATE SUBSCRIPTION my_subscription
CONNECTION 'postgresql://username:password@host:port/dbname'
PUBLICATION my_publication, sales_publication;
```

A single subscriber can maintain multiple subscriptions, including multiple subscriptions to the same publisher.

### Create a subscription to be enabled later

This command creates a subscription with `enabled = false` so that you can enable the subscription at a later time:

```sql
CREATE SUBSCRIPTION my_subscription
CONNECTION 'postgresql://username:password@host:port/dbname'
PUBLICATION my_publication
WITH (enabled = false);
```

### Change the publication subscribed to

This command modifies an existing subscription to set it to a different publication:

```sql
ALTER SUBSCRIPTION my_subscription SET PUBLICATION new_new_publication;
```

### Change the subscription connection

This command updates the connection details for a subscription:

```sql
ALTER SUBSCRIPTION subscription_name CONNECTION 'new_connection_string';
```

### Disable a subscription

This command disables an existing subscription:

```sql
ALTER SUBSCRIPTION my_subscription DISABLE;
```

### Drop a subscription

This command drops an existing subscription:

```sql
DROP SUBSCRIPTION my_subscription;
```

## Replication slots

Replication slots are created on the publisher database to track replication progress, ensuring that no data in the WAL is purged before the subscriber has successfully replicated it. This mechanism serves to maintain data consistency and prevent data loss in cases of network interruption or subscriber downtime.

**Important:** To prevent storage bloat, **Neon automatically removes _inactive_ replication slots after a period of time. Please see [Unused replication slots](https://neon.com/docs/guides/logical-replication-neon#unused-replication-slots) to learn more.

### Create a replication slot

Replication slots are typically created automatically with new subscriptions, but they can be created manually using the `pg_create_logical_replication_slot` function. Some "subscriber" data services and platforms require that you create a dedicated replication slot. This is accomplished using the following syntax:

```sql
SELECT pg_create_logical_replication_slot('my_replication_slot', 'pgoutput');
```

The first value, `my_replication_slot` is the name given to the replication slot. The second value is the [decoder plugin](https://neon.com/docs/guides/logical-replication-manage#decoder-plugins) the slot should use.

The `max_replication_slots` configuration parameter defines the maximum number of replication slots that can be used to manage database replication connections. Each replication slot tracks changes in the publisher database to ensure that the connected subscriber stays up to date. You'll want a replication slot for each replication connection. For example, if you expect to have 10 separate subscribers replicating from your database, you would set `max_replication_slots` to 10 to accommodate each connection.

The `max_replication_slots` configuration parameter on Neon is set to `10` by default.

```ini
max_replication_slots = 10
```

### Remove a replication slot

To drop a logical replication slot that you created, you can use the `pg_drop_replication_slot()` function. For example, if you've already created a replication slot named `my_replication_slot` using `pg_create_logical_replication_slot()`, you can drop it by executing the following SQL command:

```sql
SELECT pg_drop_replication_slot('my_replication_slot');
```

This command removes the specified replication slot (`my_replication_slot` in this case) from your database. It's important to ensure that the replication slot is no longer in use or required before dropping it, as this action is irreversible and could affect replication processes relying on this slot.

## Data Definition Language (DDL) operations

Logical replication in Postgres primarily handles Data Manipulation Language (DML) operations like `INSERT`, `UPDATE`, and `DELETE`. However, it does not automatically replicate Data Definition Language (DDL) operations such as `CREATE TABLE`, `ALTER TABLE`, or `DROP TABLE`. This means that schema changes in the publisher database are not directly replicated to the subscriber database.

Manual intervention is required to replicate DDL changes. This can be done by applying the DDL changes separately in both the publisher and subscriber databases or by using third-party tools that can handle DDL replication.

## Monitoring replication

To ensure that your logical replication setup is running as expected, you should monitor replication processes regularly. The [pg_stat_replication](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW) view displays information about each active replication connection to the publisher.

```sql
SELECT * FROM pg_stat_replication;
```

The view provides details like the state of the replication, the last received WAL location, sent location, write location, and the delay between the publisher and subscriber.

Additionally, the [pg_replication_slots](https://www.postgresql.org/docs/current/view-pg-replication-slots.html) view shows information about the current replication slots on the publisher, including their size.

```sql
SELECT * FROM pg_replication_slots;
```

It's important to keep an eye on replication lag, which indicates how far behind the subscriber is from the publisher. A significant replication lag could mean that the subscriber isn't receiving updates in a timely manner, which could lead to data inconsistencies.

From the Neon CLI, [`neon inspect db replication-slots`](https://neon.com/docs/cli/inspect#db-replication-slots) shows slot status and lag, and [`neon inspect db subscriptions`](https://neon.com/docs/cli/inspect#db-subscriptions) shows per-table progress on a subscriber.

## References

- [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html)
- [ALTER PUBLICATION](https://www.postgresql.org/docs/current/sql-alterpublication.html)
- [DROP PUBLICATION](https://www.postgresql.org/docs/current/sql-droppublication.html)
- [CREATE SUBSCRIPTION](https://www.postgresql.org/docs/current/sql-createsubscription.html)
- [ALTER SUBSCRIPTION](https://www.postgresql.org/docs/current/sql-altersubscription.html)
- [DROP SUBSCRIPTION](https://www.postgresql.org/docs/current/sql-dropsubscription.html)
- [wal2json](https://github.com/eulerto/wal2json)
- [pg_stat_replication](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-REPLICATION-VIEW)
- [pg_replication_slots](https://www.postgresql.org/docs/current/view-pg-replication-slots.html)

--- [Document source](https://neon.com/docs/guides/logical-replication-materialize.md) ---

> Summary: Lakebase Postgres-to-Materialize logical replication streams Postgres WAL change events from a Lakebase Postgres publication into a Materialize PostgreSQL source, enabling real-time operational analytics without a separate ETL pipeline. Follow this guide to enable logical replication, set REPLICA IDENTITY FULL on replicated tables, and verify snapshot completion via mz_source_statistics. A direct (non-pooled) Neon connection is required; active replication prevents scale-to-zero and increases compute billing.

# Replicate data to Materialize

Learn how to replicate data from Neon to Materialize

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

[Materialize](https://materialize.com/) is a data warehouse for operational workloads, purpose-built for low-latency applications. You can use it to process data at speeds and scales not possible in traditional databases, but without the cost, complexity, or development time of most streaming engines.

In this guide, you will learn how to stream data from your Lakebase Postgres database to Materialize using the Materialize [PostgreSQL source](https://materialize.com/docs/sql/create-source/postgres/).

## Prerequisites

- A [Materialize account](https://materialize.com/register/).
- A [Neon account](https://console.neon.tech/).
- Optionally, you can install the [psql](https://www.postgresql.org/docs/current/logical-replication.html) command line utility for running commands in both Neon and Materialize. Alternatively, you can run commands from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) and Materialize **SQL Shell**, which require no installation or setup.
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Enable logical replication

**Important:** Enabling logical replication modifies the PostgreSQL `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, meaning that active connections will be dropped and have to reconnect.

To enable logical replication in Neon:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query:

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

## Create a publication

After logical replication is enabled in Neon, the next step is to create a publication for the tables that you want to replicate to Materialize.

1. From a `psql` client connected to your Neon database or from the **Neon SQL Editor**, set the [replica identity](https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY) to `FULL` for each table that you want to replicate to Materialize:

   ```sql
   ALTER TABLE <table1> REPLICA IDENTITY FULL;
   ```

   `REPLICA IDENTITY FULL` ensures that the replication stream includes the previous data of changed rows, in the case of `UPDATE` and `DELETE` operations. This setting allows Materialize to ingest Postgres data with minimal in-memory state.

2. Create a [publication](https://www.postgresql.org/docs/current/logical-replication-publication.html) with the tables you want to replicate:

   For specific tables:

   ```sql
   CREATE PUBLICATION mz_source FOR TABLE <tbl1, tbl2, tbl3>;
   ```

   The `mz_source` publication will contain the set of change events generated from the specified tables and will later be used to ingest the replication stream.

   Be sure to include only the tables you need. If the publication includes additional tables, Materialize wastes resources on ingesting and then immediately discarding the data from those tables.

## Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/reference/api/branches/create-project-branch-role)

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

## Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

## Allow inbound traffic

If you use Neon's **IP Allow** feature to limit IP addresses that can connect to Neon, you will need to allow inbound traffic from Materialize IP addresses. If you are currently not limiting IP address access in Neon, you can skip this step.

1. From a `psql` client connected to Materialize or from the Materialize **SQL Shell**, run this command to find the static egress IP addresses for the Materialize region you are running in:

   ```sql
   SELECT * FROM mz_egress_ips;
   ```

2. In your Neon project, add the IPs to your **IP Allow** list, which you can find in your project's settings. For instructions, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

## Create an ingestion cluster

In Materialize, a [cluster](https://materialize.com/docs/get-started/key-concepts/#clusters) is an isolated environment, similar to a virtual warehouse in Snowflake. When you create a cluster, you choose the size of its compute resource allocation based on the work you need the cluster to do, whether ingesting data from a source, computing always-up-to-date query results, serving results to clients, or a combination.

In this case, you'll create 1 new cluster containing 1 medium replica for ingesting source data from your Lakebase Postgres database.

From a `psql` client connected to Materialize or from the Materialize **SQL Shell**, run the `CREATE CLUSTER` command to create the new cluster:

```sql
CREATE CLUSTER ingest_postgres SIZE = 'medium';
```

Materialize recommends starting with a medium [size](https://materialize.com/docs/sql/create-cluster/#size) replica or larger. This helps Materialize quickly process the initial snapshot of the tables in your publication. Once the snapshot is finished, you can right-size the cluster.

## Start ingesting data

Now that you've configured your database network and created an ingestion cluster, you can connect Materialize to your Lakebase Postgres database and start ingesting data.

1. From a `psql` client connected to Materialize or from the Materialize **SQL Shell**, use the [CREATE SECRET](https://materialize.com/docs/sql/create-secret/) command to securely store the password for the Postgres role you created earlier:

   ```sql
   CREATE SECRET pgpass AS '<PASSWORD>';
   ```

   You can access the password for your Neon role from the **Connect to your branch** modal; click the **Connect** button in the Console nav to open the modal.

2. Use the [CREATE CONNECTION](https://materialize.com/docs/sql/create-connection/) command to create a connection object with access and authentication details for Materialize to use:

   ```sql
   CREATE CONNECTION pg_connection TO POSTGRES (
   HOST '<host>',
   PORT 5432,
   USER '<role_name>',
   PASSWORD SECRET pgpass,
   SSL MODE 'require',
   DATABASE '<database>'
   );
   ```

   You can find the connection details for your replication role in the **Connect to your branch** modal in the Console nav; click the **Connect** button.

   **Important:** Use a **direct connection** to your compute endpoint, not a pooled connection. Logical replication requires a persistent connection and is not compatible with connection poolers. When copying your connection string from Neon, make sure it does not include `-pooler` in the hostname. For more information about connection pooling and when to use direct connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

   A Neon connection string looks like this:

   ```text
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   - Replace `<host>` with your Neon hostname (for example, `ep-cool-darkness-123456.us-east-2.aws.neon.tech`)
   - Replace `<role_name>` with the name of your Postgres role (for example, `alex`)
   - Replace `<database>` with the name of the database containing the tables you want to replicate to Materialize (for example, `dbname`)

3. Use the [CREATE SOURCE](https://materialize.com/docs/sql/create-source/) command to connect Materialize to your database and start ingesting data from the publication you created earlier:

   ```sql
   CREATE SOURCE mz_source
   IN CLUSTER ingest_postgres
   FROM POSTGRES CONNECTION pg_connection (PUBLICATION 'mz_source')
   FOR TABLES <table1>, <table2>;
   ```

   **Tip: Tips**

   - To ingest data from specific schemas, you can use `FOR SCHEMAS (<schema1>,<schema2>)`.
   - After creating a source, you can incorporate upstream schema changes for specific replicated tables using the `ALTER SOURCE...{ADD | DROP} SUBSOURCE` syntax.

## Check the ingestion status

Before Materialize starts consuming a replication stream, it takes a snapshot of the tables in your publication. Until this snapshot is complete, Materialize won't have the same view of your data as your Postgres database.

In this step, you'll verify that the source is running and then check the status of the snapshotting process.

1. From a `psql` client connected to Materialize or from the Materialize **SQL Shell**, use the [mz_source_statuses](https://materialize.com/docs/sql/system-catalog/mz_internal/#mz_source_statuses) table to check the overall status of your source:

   ```sql
   WITH
   source_ids AS
   (SELECT id FROM mz_sources WHERE name = 'mz_source')
   SELECT *
   FROM
   mz_internal.mz_source_statuses
       JOIN
       (
           SELECT referenced_object_id
           FROM mz_internal.mz_object_dependencies
           WHERE
           object_id IN (SELECT id FROM source_ids)
           UNION SELECT id FROM source_ids
       )
       AS sources
       ON mz_source_statuses.id = sources.referenced_object_id;
   ```

   For each subsource, make sure the status is running. If you see stalled or failed, there's likely a configuration issue for you to fix. Check the error field for details and fix the issue before moving on. If the status of any subsource is starting for more than a few minutes, contact [Materialize support](https://materialize.com/docs/support/).

2. Once the source is running, use the [mz_source_statistics](https://materialize.com/docs/sql/system-catalog/mz_internal/#mz_source_statistics) table to check the status of the initial snapshot:

   ```sql
   WITH
   source_ids AS
   (SELECT id FROM mz_sources WHERE name = 'mz_source')
   SELECT sources.object_id, bool_and(snapshot_committed) AS snapshot_committed
   FROM
   mz_internal.mz_source_statistics
       JOIN
       (
           SELECT object_id, referenced_object_id
           FROM mz_internal.mz_object_dependencies
           WHERE
           object_id IN (SELECT id FROM source_ids)
           UNION SELECT id, id FROM source_ids
       )
       AS sources
       ON mz_source_statistics.id = sources.referenced_object_id
   GROUP BY sources.object_id;
   object_id | snapshot_committed
   ----------|------------------
   u144     | t
   (1 row)
   ```

   Once `snapshot_commited` is `t`, move on to the next step. Snapshotting can take between a few minutes to several hours, depending on the size of your dataset and the size of the cluster replica you chose for your `ingest_postgres` cluster.

## Right-size the cluster

After the snapshotting phase, Materialize starts ingesting change events from the Postgres replication stream. For this work, Materialize generally performs well with an `xsmall` replica, so you can resize the cluster accordingly.

1. From a `psql` client connected to Materialize or from the Materialize **SQL Shell**, use the [ALTER CLUSTER](https://materialize.com/docs/sql/alter-cluster/) command to downsize the cluster to `xsmall`:

   ```sql
   ALTER CLUSTER ingest_postgres SET (SIZE 'xsmall');
   ```

   Behind the scenes, this command adds a new `xsmall` replica and removes the `medium` replica.

2. Use the [SHOW CLUSTER REPLICAS](https://materialize.com/docs/sql/show-cluster-replicas/) command to check the status of the new replica:

   ```sql
   SHOW CLUSTER REPLICAS WHERE cluster = 'ingest_postgres';
       cluster     | replica |  size  | ready
   -----------------+---------+--------+-------
   ingest_postgres | r1      | xsmall | t
   (1 row)
   ```

3. Going forward, you can verify that your new replica size is sufficient as follows:

   a. From a `psql` client connected to Materialize or from the Materialize **SQL Shell**, get the replication slot name associated with your Postgres source from the [mz_internal.mz_postgres_sources](https://materialize.com/docs/sql/system-catalog/mz_internal/#mz_postgres_sources) table:

   ```sql
   SELECT
       d.name AS database_name,
       n.name AS schema_name,
       s.name AS source_name,
       pgs.replication_slot
   FROM
       mz_sources AS s
       JOIN mz_internal.mz_postgres_sources AS pgs ON s.id = pgs.id
       JOIN mz_schemas AS n ON n.id = s.schema_id
       JOIN mz_databases AS d ON d.id = n.database_id;
   ```

   b. From a `psql` client connected to your Neon database or from the **Neon SQL Editor**, check the replication slot lag, using the replication slot name from the previous step:

   ```sql
   SELECT
       pg_size_pretty(pg_current_wal_lsn() - confirmed_flush_lsn)
       AS replication_lag_bytes
   FROM pg_replication_slots
   WHERE slot_name = '<slot_name>';
   ```

   The result of this query is the amount of data your Postgres cluster must retain in its replication log because of this replication slot. Typically, this means Materialize has not yet communicated back to your Lakebase Postgres database that it has committed this data. A high value can indicate that the source has fallen behind and that you might need to scale up your ingestion cluster.

## Next steps

With Materialize ingesting your Postgres data into durable storage, you can start exploring the data, computing real-time results that stay up-to-date as new data arrives, and serving results efficiently.

- Explore your data with [SHOW SOURCES](https://materialize.com/docs/sql/show-sources) and [SELECT](https://materialize.com/docs/sql/select/).
- Compute real-time results in memory with [CREATE VIEW](https://materialize.com/docs/sql/create-view/) and [CREATE INDEX](https://materialize.com/docs/sql/create-index/) or in durable storage with [CREATE MATERIALIZED VIEW](https://materialize.com/docs/sql/create-materialized-view/).
- Serve results to a Postgres-compatible SQL client or driver with [SELECT](https://materialize.com/docs/sql/select/) or [SUBSCRIBE](https://materialize.com/docs/sql/subscribe/) or to an external message broker with [CREATE SINK](https://materialize.com/docs/sql/create-sink/).
- Check out the [tools and integrations](https://materialize.com/docs/integrations/) supported by Materialize.

--- [Document source](https://neon.com/docs/guides/logical-replication-neon-to-lakebase.md) ---

> Summary: Logical replication from Neon to Lakebase Postgres on Databricks streams row-level changes from a publication on a Neon database to a subscription on a Lakebase database. Use this guide for a low-downtime migration from Neon to Databricks, or to keep a Lakebase copy of Neon data in sync. Steps cover enabling logical replication on the Neon project, creating a replication role and publication, allowing Lakebase to reach Neon, creating the target schema and subscription on Lakebase, verifying replication, resetting sequences, and cutting over. Enabling logical replication on Neon is irreversible and restarts all computes in the project.

# Replicate data from Neon to Lakebase Postgres on Databricks

Use logical replication to migrate or stream data from a Neon database to Lakebase Postgres on Databricks

Last updated: 2026-10-21

Neon's logical replication feature lets you replicate data from a Neon database to Lakebase Postgres on Databricks. Lakebase subscribes to a publication on your Neon database, copies the existing data, and then applies each insert, update, and delete as it happens. Use it to:

- **Migrate from Neon to Databricks with minimal downtime**: Keep the Lakebase database current while your application still runs on Neon, then cut over when you're ready.
- **Keep a Lakebase copy of Neon data**: Replicate selected tables to Lakebase for use alongside other Databricks workloads.

If a short write outage is acceptable, a dump and restore is simpler. See [Migrate Neon to Lakebase](https://neon.com/docs/guides/migrate-neon-to-lakebase). To replicate in the other direction, see [Replicate data from Lakebase Postgres on Databricks to Neon](https://neon.com/docs/guides/logical-replication-lakebase-to-neon).

## Prerequisites

- A Neon project with a database containing the data you want to replicate. If you're just testing this out and need some data to play with, you can use the following statements to create a table with sample data:

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- A Lakebase project on Databricks for the destination database, in a workspace on AWS or Azure. See [Lakebase Postgres](https://docs.databricks.com/aws/en/oltp).

- A Lakebase Postgres role that can create subscriptions: a member of the `databricks_superuser` role, or a role granted the `pg_create_subscription` predefined role. See [Create Postgres roles](https://docs.databricks.com/aws/en/oltp/projects/postgres-roles).

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

**Important: Compute and billing**

Replication keeps your Neon compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while Lakebase is subscribed, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Prepare your source Neon database

This section describes how to prepare your source Neon database (the publisher) for replicating data to your Lakebase database (the subscriber).

### Enable logical replication in the source Neon project

In the Neon project containing your source database, enable logical replication. You don't need to change anything on Lakebase. As a subscriber, Lakebase doesn't require a `wal_level` change.

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication restarts all computes in your Neon project, meaning that active connections will be dropped and have to reconnect.

To enable logical replication:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query:

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

### Create a Postgres role for replication

Create a dedicated Postgres role for Lakebase to connect as. The role must have the `REPLICATION` privilege. Roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege. Roles created with SQL don't have this privilege, and it can't be granted. See [Replication roles](https://neon.com/docs/guides/logical-replication-neon#replication-roles).

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI roles command](https://neon.com/docs/cli/roles).

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

### Grant schema access to your Postgres role

If your replication role doesn't own the schemas and tables you're replicating from, grant access. For example, the following commands grant access to all tables in the `public` schema to the `replication_user` role:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a publication on the source database

Publications define what gets replicated. Each table in the publication must have a primary key or a [replica identity](https://www.postgresql.org/docs/current/logical-replication-publication.html#LOGICAL-REPLICATION-PUBLICATION-REPLICA-IDENTITY) so that updates and deletes can be replicated.

To create a publication for a specific table:

```sql
CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

### Allow Lakebase to connect to Neon

As the subscriber, Lakebase connects out to your Neon database over the public internet. Private Link isn't supported for logical replication on Lakebase.

- **On Neon**: No action is needed unless you use Neon's **IP Allow** feature. If you do, the Lakebase connection must come from an allowed address. See [Subscriber access](https://neon.com/docs/guides/logical-replication-neon#subscriber-access).
- **On Databricks**: If your Databricks account enforces a network policy for serverless workloads, add your Neon hostname (for example, `ep-cool-darkness-123456.us-east-2.aws.neon.tech`) to the allowed internet destinations. Otherwise, Databricks rejects the subscription when you create it. See [Manage network policies](https://docs.databricks.com/aws/en/security/network/serverless-network-security/manage-network-policies).

## Prepare your Lakebase destination database

This section describes how to prepare your destination Lakebase database (the subscriber) to receive replicated data.

### Prepare your database schema

Logical replication copies data, not schema. The tables you replicate must exist in the Lakebase database with the same names and columns before you create the subscription. Create them empty. The initial copy fails on duplicate keys or constraint violations if a target table already contains rows.

You can create the tables manually or dump the schema from Neon with `pg_dump --schema-only` and load it into Lakebase. Neon dumps include ownership and privileges for Neon-specific roles such as `neondb_owner` and `neon_superuser`, which don't exist on Lakebase, so restore with `--no-owner` and `--no-acl`. See [Restore into Lakebase](https://neon.com/docs/guides/migrate-neon-to-lakebase#restore-into-lakebase) for details.

If you're using the sample `playing_with_neon` table, you can create the same table on the Lakebase database with the following statement:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

### Create a subscription

After creating a publication on the source database, create a subscription on the Lakebase database.

1. Connect to your Lakebase database as a role that can create subscriptions (see [Prerequisites](https://neon.com/docs/guides/logical-replication-neon-to-lakebase#prerequisites)). You can use the SQL editor in the Lakebase App, `psql`, or another SQL client. See [Connect to your database](https://docs.databricks.com/aws/en/oltp/projects/connect).

2. Create the subscription using a `CREATE SUBSCRIPTION` statement.

   ```sql
   CREATE SUBSCRIPTION my_subscription
   CONNECTION 'host=ep-cool-darkness-123456.us-east-2.aws.neon.tech port=5432 dbname=neondb user=replication_user password=AbC123dEf sslmode=verify-full sslrootcert=system'
   PUBLICATION my_publication;
   ```

   - `subscription_name`: A name you chose for the subscription.
   - `connection_string`: The connection details for the source Neon database where you defined the publication. Use the direct hostname, not the pooled one. Logical replication requires a persistent connection and isn't compatible with connection poolers, so the hostname must not include the `-pooler` suffix. See [Connection pooling](https://neon.com/docs/connect/connection-pooling). `sslmode=verify-full` with `sslrootcert=system` encrypts the connection and verifies Neon's publicly trusted certificate.
   - `publication_name`: The name of the publication you created on the source Neon database.

   Creating the subscription creates a replication slot on your Neon database, copies the existing rows, and then streams ongoing changes.

3. Verify the subscription was created by running the following command:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription has been created successfully.

**Warning: Replication slots and inactive subscriptions**

If the Lakebase subscription stops consuming changes, for example because it's disabled or failing, the replication slot on Neon becomes inactive. Neon removes inactive replication slots after approximately 40 hours, and the subscription must then be re-created. See [Unused replication slots](https://neon.com/docs/guides/logical-replication-neon#unused-replication-slots).

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from Neon to Lakebase.

1. Run some data modifying queries on the Neon database (inserts, updates, or deletes). If you're using the `playing_with_neon` table, you can use this statement to insert some rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on the Neon and Lakebase databases to make sure the result matches.

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   20
   (1 row)
   ```

Alternatively, you can run the following query on Lakebase to make sure the `last_msg_receipt_time` is as expected. For example, if you just ran an insert on Neon, the `last_msg_receipt_time` should reflect the time of that operation.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

To confirm that the initial copy of every table has finished, see [Monitor replication](https://docs.databricks.com/aws/en/oltp/projects/logical-replication-manage#monitor) in the Databricks documentation.

## Switch over your application

When the Lakebase database has caught up, stop writes on Neon and confirm that Lakebase is fully current.

Logical replication doesn't copy sequence values. Before you resume writes on Lakebase, reset each sequence to match the replicated data. Otherwise, new inserts into `SERIAL` or identity columns can generate duplicate primary keys. For example:

```sql
SELECT setval(pg_get_serial_sequence('playing_with_neon', 'id'), (SELECT MAX(id) FROM playing_with_neon));
```

Then switch your application to the Lakebase connection details. See [Connect to your database](https://docs.databricks.com/aws/en/oltp/projects/connect).

After your application is running against Lakebase, drop the subscription on Lakebase to stop replicating. Dropping the subscription also removes the replication slot on Neon.

```sql
DROP SUBSCRIPTION my_subscription;
```

If you no longer need the Neon project, you can delete it. See [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

## Related docs

**Neon**

- [Logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon)
- [Migrate Neon to Lakebase](https://neon.com/docs/guides/migrate-neon-to-lakebase)
- [Replicate data from Lakebase Postgres on Databricks to Neon](https://neon.com/docs/guides/logical-replication-lakebase-to-neon)

**Databricks**

- [Logical replication](https://docs.databricks.com/aws/en/oltp/projects/logical-replication)
- [Replicate data into Lakebase](https://docs.databricks.com/aws/en/oltp/projects/logical-replication-subscription)
- [Manage and monitor logical replication](https://docs.databricks.com/aws/en/oltp/projects/logical-replication-manage)

--- [Document source](https://neon.com/docs/guides/logical-replication-neon-to-neon.md) ---

> Summary: Neon-to-Neon logical replication streams data from a publisher project to a subscriber project using Postgres publications and subscriptions, enabling cross-region replication, region migration, and Postgres version upgrades (for example, Postgres 16 to 17). Use this guide when you need to replicate between two separate Neon projects using Lakebase Postgres; replicating between databases on the same Neon project branch requires a different configuration. Enabling logical replication changes wal_level from replica to logical on all databases in the source project and the change cannot be reverted.

# Replicate data from one Neon project to another

Replicate data to a different Neon project for cross-region replication, version migration, or region migration

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from one Neon project to another. This enables different usage scenarios, including:

- **Cross-region replication**: Replicating data from a Neon project in one region to a Neon project in another region to support regional failover scenarios.
- **Postgres version migration**: Moving data from one Postgres version to another; for example, from a Neon project that runs Postgres 16 to one that runs Postgres 17.
- **Region migration**: Moving data from one region to another; for example, from a Neon project in one region to a Neon project in a different region.

These are some common Neon-to-Neon replication scenarios. There may be others. You can follow the steps in this guide for any scenario that requires replicating data between different Neon projects.

**Info: Replicating between databases on the same Neon project branch**

**The procedure in this guide does not work for replicating between databases on the same Neon project branch**. That setup requires a slightly different publication and subscription configuration. For details, see [Replicating between databases on the same Neon project branch](https://neon.com/docs/guides/logical-replication-neon#replicating-between-databases-on-the-same-neon-project-branch).

## Prerequisites

- A Neon project with a database containing the data you want to replicate. If you're just testing this out and need some data to play with, you can use the following statements to create a table with sample data:

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- A destination Neon project.

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

For information about creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

## Prepare your source Neon database

This section describes how to prepare your source Neon database (the publisher) for replicating data to your destination Neon database (the subscriber).

### Enable logical replication in the source Neon project

In the Neon project containing your source database, enable logical replication. You only need to perform this step on the source Neon project.

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication restarts all computes in your Neon project, meaning that active connections will be dropped and have to reconnect.

To enable logical replication:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query:

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

### Create a publication on the source database

Publications are a fundamental part of logical replication in Postgres. They define what will be replicated.

To create a publication for a specific table:

```sql
CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

## Prepare your Neon destination database

This section explains how to prepare your destination database (the subscriber) to receive replicated data. For cross-region replication, be sure to create the destination Neon project in a different region than your source database.

### Prepare your database schema

When configuring logical replication in Postgres, the tables in the source database you are replicating from must also exist in the destination database, and they must have the same table names and columns. You can create the tables manually in your destination database or use utilities like `pg_dump` and `pg_restore` to dump the schema from your source database and load it to your destination database. See [Import a database schema](https://neon.com/docs/import/migrate-schema-only) for instructions.

If you're using the sample `playing_with_neon` table, you can create the same table on the destination database with the following statement:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

### Create a subscription

After creating a publication on the source database, you need to create a subscription on the destination database.

1. Use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), `psql`, or another SQL client to connect to your destination database.

2. Create the subscription using the using a `CREATE SUBSCRIPTION` statement.

   ```sql
   CREATE SUBSCRIPTION my_subscription
   CONNECTION 'postgresql://neondb_owner:<password>@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require'
   PUBLICATION my_publication;
   ```

   - `subscription_name`: A name you chose for the subscription.
   - `connection_string`: The connection string for the source Neon database where you defined the publication. Use a direct connection string, not a pooled one. Logical replication requires a persistent connection and is not compatible with connection poolers, so the hostname must not include the `-pooler` suffix. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).
   - `publication_name`: The name of the publication you created on the source Neon database.

3. Verify the subscription was created by running the following command:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription has been created successfully.

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from the publisher to the subscriber database.

1. Run some data modifying queries on the source database (inserts, updates, or deletes). If you're using the `playing_with_neon` database, you can use this statement to insert some rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on the source and destination databases to make sure the result matches.

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   10
   (1 row)
   ```

Alternatively, you can run the following query on the subscriber to make sure the `last_msg_receipt_time` is as expected. For example, if you just ran an insert option on the publisher, the `last_msg_receipt_time` should reflect the time of that operation.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

## Switch over your application

After the replication operation is complete or in a failover situation, you can switch your application over to the destination database by swapping out your source database connection details for your destination database connection details.

You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. See [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

--- [Document source](https://neon.com/docs/guides/logical-replication-neon.md) ---

> Summary: Logical replication in Neon requires enabling it per project, which permanently changes `wal_level` to `logical` and restarts all computes. Use this page when configuring Neon as a publisher or subscriber. It covers Neon-specific constraints: inactive replication slots are removed after ~40 hours, subscribers prevent scale-to-zero, and `max_wal_senders` and `max_replication_slots` are both set to 10. Supported decoder plugins are `pgoutput` and `wal2json`.

# Logical replication in Neon

Information about logical replication specific to Neon

Last updated: 2026-10-09

This topic outlines information about logical replication specific to Neon, including important notices.

## Enable logical replication

When replicating data from Neon, enable logical replication on your Neon project. When replicating data to Neon, enable it on the source database instead.

**Important:** Enabling logical replication changes the PostgreSQL `wal_level` setting from `replica` to `logical` for all databases in your Neon project. This allows Postgres to record the row-level WAL detail required for logical decoding. Once changed, it cannot be reverted. Enabling logical replication also restarts all computes, so active connections will be dropped and have to reconnect.

**Console**

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

**CLI**

Use the [Neon CLI](https://neon.com/docs/cli) `projects update` command with `--enable-logical-replication`. Replace `$PROJECT_ID` with your project ID. The `--yes` flag skips the confirmation prompt.

```bash
neon projects update $PROJECT_ID --enable-logical-replication --yes
```

**API**

Use the [Update project](https://neon.com/docs/reference/api/projects/update-project) endpoint to enable logical replication programmatically. Replace `$PROJECT_ID` with your project ID.

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/$PROJECT_ID' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "project": {
    "settings": {
      "enable_logical_replication": true
    }
  }
}'
```

You can verify that logical replication is enabled by running the following query:

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

## Important notices

To avoid potential issues, please review the following notices carefully before using logical replication in Neon.

### Neon as a publisher

These notices apply when replicating data **from** Neon (Neon as the publisher):

- **Scale to zero and compute usage**: While a logical replication subscriber is connected, your Neon compute stays active and will not scale to zero. Neon does not "disable" scale to zero; the database is simply always active because replication keeps it in use, so the compute never becomes idle. This results in ongoing compute usage and can significantly affect your bill. For details, see [Logical replication and scale to zero](https://neon.com/docs/guides/logical-replication-neon#logical-replication-and-scale-to-zero). If you are optimizing costs, see also [Cost optimization](https://neon.com/docs/introduction/cost-optimization).
- **Removal of inactive replication slots**: To prevent storage bloat, **Neon automatically removes _inactive_ replication slots after approximately 40 hours. Please see [Unused replication slots](https://neon.com/docs/guides/logical-replication-neon#unused-replication-slots) for more information.
- **Branch restore removes replication slots**: [Restoring a branch](https://neon.com/docs/guides/branch-restore) will delete all replication slots on that branch. Replication slots are not automatically re-created during the restore process.

### Neon as a subscriber

- Before dropping a database in response to a user issued `DROP DATABASE` command or operation, Neon will drop any logical replication subscriptions defined in the database.
- To prevent issues due to unintended duplication of logical replication subscriptions, subscriptions defined on a parent branch are not duplicated on child branches; they are dropped from child branches before the compute associated with the child branch starts. This applies to all branching contexts where logical replication subscriptions could be duplicated on a child branch, including creating a child branch, resetting a child branch, and restoring a child branch.

## Logical replication and scale to zero

Neon's [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero) feature suspends a compute after 300 seconds (5 minutes) of inactivity. When you replicate data **from** Neon (Neon as publisher), a connected logical replication subscriber keeps the database in use, so the compute never becomes idle. Neon therefore does not suspend the compute; it remains active at all times while subscribers are connected. This applies only when Neon is the publisher (replicating from Neon to an external destination), not when Neon is the subscriber (replicating into Neon from an external source). Neon determines whether there are active replication connections by checking for `walsender` processes using the following query:

```sql
SELECT *
FROM pg_stat_replication
WHERE application_name != 'walproposer';
```

If the count is greater than 0, a Neon compute where the publishing Postgres instance runs will not be suspended.

## Unused replication slots

To prevent storage bloat, **Neon automatically removes _inactive_ replication slots after approximately 40 hours.

An inactive replication slot is one that doesn't acknowledge `flush_lsn` progress for more than approximately 40 hours. This is the same `flush_lsn` value found in the `pg_stat_replication` view in your Neon database.

An _inactive_ replication slot can be the result of a dead subscriber, where the replication slot has not been removed after a subscriber is deactivated or becomes unavailable. An inactive replication slot can also result from a long replication delay configured on the subscriber. For example, subscribers like Fivetran or Airbyte let you to configure the replication frequency or set a replication delay to minimize usage.

### How to avoid removal of replication slots

- If replication frequency configured on the subscriber is more than 40 hours, you can prevent replication slots from being dropped by changing the replication frequency to less than 40 hours.

  This will ensure that your subscriber reports `flush_lsn` progress more frequently than every 40 hours. If increasing replication frequency is not possible, please contact [Neon Support](https://neon.com/docs/introduction/support) for alternatives.

- If using Debezium, set [lsn.flush.mode](https://debezium.io/documentation/reference/stable/connectors/postgresql.html#postgresql-property-lsn-flush-mode) to `connector` so that the connector reports `flush_lsn` progress. (The older property `flush.lsn.source=true` is deprecated but is automatically mapped to `lsn.flush.mode=connector` for backward compatibility.) For other subscriber platforms, check for an equivalent setting to make sure it's configured to acknowledge progress on the subscriber.

### What to do if your replication slot is removed

If you find that a replication slot was removed and you need to add it back, please see [Create a replication slot](https://neon.com/docs/guides/logical-replication-neon#create-a-replication-slot) for instructions or refer to the replication slot creation instructions for your subscriber.

## Replication roles

It is recommended that you create a dedicated Postgres role for replicating data from Neon to a subscriber. This role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon Console, CLI, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege. Roles created via SQL do not have this privilege, and the `REPLICATION` privilege cannot be granted.

You can verify that your role has the `REPLICATION` privilege by running the following query:

```sql
SELECT rolname, rolreplication
FROM pg_roles
WHERE rolname = '<role_name>';
```

## Subscriber access

A subscriber must be able to access the Neon database that is acting as a publisher. In Neon, no action is required unless you use Neon's **IP Allow** feature to limit IP addresses that can connect to Neon.

**Important:** When a subscriber connects to a Neon publisher, use a direct connection string, not a pooled one. Logical replication requires a persistent connection and is not compatible with connection poolers. Make sure the connection string you give the subscriber does not include the `-pooler` suffix in the hostname. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

If you use Neon's **IP Allow** feature:

1. Determine the IP address or addresses of the subscriber.
2. In your Neon project, add the IPs to your **IP Allow** list, which you can find in your project's settings. For instructions, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

## Publisher access

When replicating data to Neon, you may need to allow connections from Neon on the publisher platform or service.

Neon uses 3 to 6 IP addresses per region for outbound communication, corresponding to each availability zone in the region. See [NAT Gateway IP addresses](https://neon.com/docs/introduction/regions#nat-gateway-ip-addresses) for Neon's NAT gateway IP addresses. When configuring access, be sure to open access to all of the NAT gateway IP addresses for your Neon project's region.

## Decoder plugins

Neon supports both `pgoutput` and `wal2json` replication output decoder plugins.

- `pgoutput`: This is the default logical replication output plugin for Postgres. Specifically, it's part of the Postgres built-in logical replication system, designed to read changes from the database's write-ahead log (WAL) and output them in a format suitable for logical replication.
- `wal2json`: This is also a logical replication output plugin for Postgres, but it differs from `pgoutput` in that it converts WAL data into `JSON` format. This makes it useful for integrating Postgres with systems and applications that work with `JSON` data. For usage information, see [The wal2json plugin](https://neon.com/docs/extensions/wal2json).

## Dedicated replication slots

Some data services and platforms require dedicated replication slots. You can create a dedicated replication slot using the standard PostgreSQL syntax. As mentioned above, Neon supports both `pgoutput` and `wal2json` replication output decoder plugins.

```sql
SELECT pg_create_logical_replication_slot('my_replication_slot', 'pgoutput');
```

```sql
SELECT pg_create_logical_replication_slot('my_replication_slot', 'wal2json');
```

## Publisher settings

The `max_wal_senders` and `max_replication_slots` configuration parameter settings on Neon are set to `10`.

```text
max_wal_senders = 10
max_replication_slots = 10
```

- The `max_wal_senders` parameter defines the maximum number of concurrent WAL sender processes that are responsible for streaming WAL data to subscribers. In most cases, you should have one WAL sender process for each subscriber or replication slot to ensure efficient and consistent data replication.
- The `max_replication_slots` defines the maximum number of replication slots used to manage database replication connections. Each replication slot tracks changes in the publisher database to ensure that the connected subscriber stays up to date. You'll want a replication slot for each replication connection. For example, if you expect to have 10 separate subscribers replicating from your database, you would set `max_replication_slots` to 10 to accommodate each connection.

If you require different values for these parameters, please contact Neon support.

## Replicating between databases on the same Neon project branch

Each branch in a Neon project has its own Postgres instance, and a Postgres instance is a database cluster, capable of supporting multiple databases. If your use case requires replicating data between two databases in the same database cluster, i.e., on the same Neon project branch, the setup is slightly different than configuring replication between separate Postgres instances. As described in the official PostgreSQL [CREATE SUBSCRIPTION Notes documentation](https://www.postgresql.org/docs/current/sql-createsubscription.html):

```text
Creating a subscription that connects to the same database cluster (for example, to replicate between databases in the same cluster or to replicate within the same database) will only succeed if the replication slot is not created as part of the same command. Otherwise, the `CREATE SUBSCRIPTION` call will hang. To make this work, create the replication slot separately (using the function `pg_create_logical_replication_slot` with the plugin name `pgoutput`) and create the subscription using the parameter `create_slot = false`. This is an implementation restriction that might be lifted in a future release.
```

For example, on the publisher database, you would create the publication and the replication slot, as shown:

```sql
CREATE PUBLICATION my_publication FOR TABLES <table1>, <table2>;
SELECT pg_create_logical_replication_slot('my_replication_slot', 'pgoutput');
```

Then, on the subscriber database, you would create a subscription that references the replication slot with the `create_slot` option set to `false` and `slot_name` set to the name of the slot you created. The `connection_string` should be the connection string for the Postgres role used to connect to the publisher database. This role must have the `REPLICATION` privilege. Any Postgres role create created via the Neon Console, CLI, or API is a member of the `neon_superuser` role, which has the `REPLICATION` privilege by default. You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. See [Connect from any application](https://neon.com/docs/connect/connect-from-any-app). Be sure to select the correct role and database before copying the connection string.

```sql
CREATE SUBSCRIPTION my_subscription
    CONNECTION 'connection_string'
    PUBLICATION my_publication with (create_slot = false, slot_name = 'my_replication_slot');
```

--- [Document source](https://neon.com/docs/guides/logical-replication-postgres-to-neon.md) ---

> Summary: Logical replication from a self-hosted or third-party Postgres instance to Neon uses native publisher/subscriber mechanics. Set wal_level = logical on the source, create a publication, then run CREATE SUBSCRIPTION on the Neon destination. Use this guide when migrating or continuously replicating data from AWS RDS, Azure Database for PostgreSQL, or a local Postgres server into Neon. Steps cover replication role and GRANT setup, publication and schema preparation via pg_dump, subscription creation, row-count verification, and application cutover.

# Replicate data from Postgres to Neon

Learn how to replicate data from a local Postgres instance or another Postgres provider to Neon

Last updated: 2026-09-16

Neon's logical replication feature allows you to replicate data from a local Postgres instance or another Postgres provider to Neon. If you're looking to replicate data from one Lakebase Postgres instance to another, see [Replicate data from one Neon project to another](https://neon.com/docs/guides/logical-replication-neon-to-neon).

## Prerequisites

- A local Postgres instance or Postgres instance hosted on another provider containing the data you want to replicate. If you're just testing this out and need some data to play with, you can use the following statements to create a table with sample data:

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- A destination Neon project. For information about creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

## Prepare your source Postgres database

This section describes how to prepare your source Postgres database (the publisher) for replicating data to your destination Neon database (the subscriber).

### Enable logical replication in the source Neon project

On your source database, enable logical replication. The typical steps for a local Postgres instance are shown below. If you run Postgres on a provider, the steps may differ. Refer to your provider's documentation.

Enabling logical replication requires changing the Postgres `wal_level` configuration parameter from `replica` to `logical`.

1. Locate your `postgresql.conf` file. This is usually found in the PostgreSQL data directory. The data directory path can be identified by running the following query in your PostgreSQL database:

   ```sql
   SHOW data_directory;
   ```

2. Open the `postgresql.conf` file in a text editor. Find the `wal_level` setting in the file. If it is not present, you can add it manually. Set `wal_level` to `logical` as shown below:

   ```ini
   wal_level = logical
   ```

3. After saving the changes to `postgresql.conf`, you need to reload or restart PostgreSQL for the changes to take effect.

4. Confirm the change by running the following query in your PostgreSQL database:

   ```sql
   SHOW wal_level;
   wal_level
   -----------
   logical
   ```

### Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. For example:

```sql
CREATE ROLE replication_user WITH REPLICATION LOGIN PASSWORD 'your_secure_password';
```

### Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a publication on the source database

Publications are a fundamental part of logical replication in Postgres. They define what will be replicated.

To create a publication for a specific table:

```sql
CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

## Prepare your Neon destination database

This section describes how to prepare your destination Lakebase Postgres database (the subscriber) to receive replicated data.

### Prepare your database schema

When configuring logical replication in Postgres, the tables in the source database you are replicating from must also exist in the destination database, and they must have the same table names and columns. You can create the tables manually in your destination database or use utilities like `pg_dump` and `pg_restore` to dump the schema from your source database and load it to your destination database. See [Import a database schema](https://neon.com/docs/import/migrate-schema-only) for instructions.

If you're using the sample `playing_with_neon` table, you can create the same table on the destination database with the following statement:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

### Create a subscription

After creating a publication on the source database, you need to create a subscription on the destination database.

1. Use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), `psql`, or another SQL client to connect to your destination database.

2. Create the subscription using the using a `CREATE SUBSCRIPTION` statement.

   ```sql
   CREATE SUBSCRIPTION my_subscription
   CONNECTION 'host=<host-address-or-ip> port=5432 dbname=postgres user=replication_user password=replication_user_password'
   PUBLICATION my_publication;
   ```

   - `subscription_name`: A name you chose for the subscription.
   - `connection_string`: The connection string for the source Postgres database where you defined the publication.
   - `publication_name`: The name of the publication you created on the source Postgres database.

3. Verify the subscription was created by running the following command:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription has been created successfully.

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from the publisher to the subscriber database.

1. Run some data modifying queries on the source database (inserts, updates, or deletes). If you're using the `playing_with_neon` database, you can use this statement to insert some rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on the source and destination databases to make sure the result matches.

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   30
   (1 row)
   ```

Alternatively, you can run the following query on the subscriber to make sure the `last_msg_receipt_time` is as expected. For example, if you just ran an insert option on the publisher, the `last_msg_receipt_time` should reflect the time of that operation.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

## Switch over your application

After the replication operation is complete, you can switch your application over to the destination database by swapping out your source database connection details for your destination database connection details.

You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. See [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

--- [Document source](https://neon.com/docs/guides/logical-replication-postgres.md) ---

> Summary: Logical replication from Lakebase Postgres to an external (non-Neon) Postgres instance streams row-level changes over Postgres WAL by setting wal_level to logical, creating a publication on Lakebase Postgres, and creating a subscription on the destination database. Use this guide when you need to replicate data out of Neon to a self-hosted or third-party Postgres server; for Neon-to-Neon replication, a separate guide applies. Enabling logical replication is irreversible per project and restarts all computes, keeping them active while subscribers are connected.

# Replicate data to an external Postgres instance

Learn how to replicate data from Neon to an external Postgres instance

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from Neon to external subscribers. This guide shows you how to stream data from a Lakebase Postgres database to an external Postgres database (a Postgres destination other than Neon). If you're looking to replicate data from one Lakebase Postgres instance to another, see [Replicate data from one Neon project to another](https://neon.com/docs/guides/logical-replication-neon-to-neon).

## Prerequisites

- A Neon project with a database containing the data you want to replicate. If you're just testing this out and need some data to play with, you can use the following statements to create a table with sample data:

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

  For information about creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- A destination Postgres instance other than Neon.

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Prepare your source Neon database

This section describes how to prepare your source Neon database (the publisher) for replicating data to your destination Neon database (the subscriber).

### Enable logical replication in the source Neon project

In the Neon project containing your source database, enable logical replication. You only need to perform this step on the source Neon project.

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication restarts all computes in your Neon project, meaning that active connections will be dropped and have to reconnect.

To enable logical replication:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query:

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

### Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/reference/api/branches/create-project-branch-role)

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

### Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a publication on the source database

Publications are a fundamental part of logical replication in Postgres. They define what will be replicated.

To create a publication for a specific table:

```sql
CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

## Prepare your destination database

This section describes how to prepare your destination Postgres database (the subscriber) to receive replicated data.

### Prepare your database schema

When configuring logical replication in Postgres, the tables in the source database you are replicating from must also exist in the destination database, and they must have the same table names and columns. You can create the tables manually in your destination database or use utilities like `pg_dump` and `pg_restore` to dump the schema from your source database and load it to your destination database. See [Import a database schema](https://neon.com/docs/import/migrate-schema-only) for instructions.

If you're using the sample `playing_with_neon` table, you can create the same table on the destination database with the following statement:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

### Create a subscription

After creating a publication on the source database, you need to create a subscription on the destination database.

1. Use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), `psql`, or another SQL client to connect to your destination database.

2. Create the subscription using the using a `CREATE SUBSCRIPTION` statement.

   ```sql
   CREATE SUBSCRIPTION my_subscription
   CONNECTION 'postgresql://neondb_owner:<password>@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require'
   PUBLICATION my_publication;
   ```

   - `subscription_name`: A name you chose for the subscription.
   - `connection_string`: The connection string for the source Neon database where you defined the publication.
   - `publication_name`: The name of the publication you created on the source Neon database.

3. Verify the subscription was created by running the following command:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription has been created successfully.

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from the publisher to the subscriber database.

1. Run some data modifying queries on the source database (inserts, updates, or deletes). If you're using the `playing_with_neon` database, you can use this statement to insert some rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on the source and destination databases to make sure the result matches.

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   30
   (1 row)
   ```

Alternatively, you can run the following query on the subscriber to make sure the `last_msg_receipt_time` is as expected. For example, if you just ran an insert option on the publisher, the `last_msg_receipt_time` should reflect the time of that operation.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

## Switch over your application

After the replication operation is complete, you can switch your application over to the destination database by swapping out your source database connection details for your destination database connection details.

You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. See [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

--- [Document source](https://neon.com/docs/guides/logical-replication-rds-to-neon.md) ---

> Summary: Migrate from Amazon RDS PostgreSQL to Neon with minimal downtime using logical replication. Set rds.logical_replication=1 on RDS, create a publication, then create a matching subscription on Neon to stream row-level changes. The guide covers enabling WAL logical level on RDS, allowlisting Neon NAT gateway IPs in the RDS security group, schema preparation, and application cutover.

# Replicate data from Amazon RDS Postgres

Learn how to replicate data from Amazon RDS Postgres to Neon

Last updated: 2026-09-16

**Note: New feature**

If you are looking to migrate your database to Neon, you may want to try our new **Migration Assistant**, which can help. Read the [guide](https://neon.com/docs/import/migration-assistant) to learn more.

Neon's logical replication feature allows you to replicate data from Amazon RDS PostgreSQL to Neon using Lakebase Postgres.

## Prerequisites

- A source database in Amazon RDS for PostgreSQL containing the data you want to replicate. If you're just testing this out and need some data to play with, you can use the following statements to create a table with sample data:

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- A destination Neon project. For information about creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

## Prepare your source database

This section describes how to prepare your source Amazon RDS Postgres instance (the publisher) for replicating data to Neon.

### Enable logical replication in the source Amazon RDS PostgreSQL instance

Enabling logical replication in Postgres requires changing the `wal_level` configuration parameter from `replica` to `logical`. Before you begin, you can check your current setting with the following command:

```bash
SHOW wal_level;
 wal_level
-----------
 replica
(1 row)
```

**Note:** For information about connecting to RDS from `psql`, see [Connect to a PostgreSQL DB instance](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_GettingStarted.CreatingConnecting.PostgreSQL.html#CHAP_GettingStarted.Connecting.PostgreSQL).

If your current setting is `replica`, follow these steps to enable logical replication. If you are using the default parameter group, you will need to create a new parameter group to set the value. You can do so by selecting **Parameter groups** > **Create parameter group** from the sidebar and filling in the required fields.

To enable logical replication:

1. Navigate to the **Configuration** tab of your RDS instance.
2. Under the **Configuration** heading, click on the **DB instance parameter group** link.
3. Click **Edit**. In the **Filter parameters** search field, search for `rds.logical_replication`.
4. Set the value to `1`, and click **Save Changes**.
5. If you created a new parameter group, navigate back to your RDS instance page, click **Modify**, and scroll down to select your new parameter group. Click **Continue**, and select **Apply immediately** to make the change now, then click **Modify DB instance**.
6. Reboot your instance to apply the new setting. From the **Actions** menu for your database, select **Reboot**.
7. Make sure that the `wal_level` parameter is now set to `logical`:

   ```sql
   SHOW wal_level;
   wal_level
   -----------
   logical
   (1 row)
   ```

### Allow connections from Neon

You need to allow inbound connections to your AWS RDS Postgres instance from Neon. You can do this by editing your instance's **CIDR/IP - Inbound** security group, which you can find a link to from your AWS RDS Postgres instance page.

1. Click on the security group name.

2. Click on the security group ID.

3. From the **Actions** menu, select **Edit inbound rules**.

4. Add rules that allow traffic from each of the IP addresses for your Neon project's region.

   Neon uses 3 to 6 IP addresses per region for outbound communication, corresponding to each availability zone in the region. See [NAT Gateway IP addresses](https://neon.com/docs/introduction/regions#nat-gateway-ip-addresses) for Neon's NAT gateway IP addresses.

5. When you're finished, click **Save rules**.

   **Note:** You can specify a rule for `0.0.0.0/0` to allow traffic from any IP address. However, this configuration is not considered secure.

### Create a publication on the source database

Publications are a fundamental part of logical replication in Postgres. They define what will be replicated.

To create a publication for a specific table:

```sql
CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION my_publication FOR TABLE users, departments;
```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

## Prepare your destination database

This section describes how to prepare your destination Lakebase Postgres database (the subscriber) to receive replicated data from your AWS RDS Postgres instance.

### Prepare your database schema

When configuring logical replication in Postgres, the tables in the source database you are replicating from must also exist in the destination database, and they must have the same table names and columns. You can create the tables manually in your destination database or use utilities like `pg_dump` and `pg_restore` to dump the schema from your source database and load it to your destination database. See [Import a database schema](https://neon.com/docs/import/migrate-schema-only) for instructions.

If you're using the sample `playing_with_neon` table, you can create the same table on the destination database with the following statement:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

### Create a subscription

After creating a publication on the source database, you need to create a subscription on your Neon destination database.

1. Use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), `psql`, or another SQL client to connect to your destination database.

2. Create the subscription using the using a `CREATE SUBSCRIPTION` statement.

   ```sql
   CREATE SUBSCRIPTION my_subscription CONNECTION 'postgresql://postgres:password@database-1.czmwaio8k05k.us-east-2.rds.amazonaws.com/postgres' PUBLICATION my_publication;
   ```

   - `subscription_name`: A name you chose for the subscription.
   - `connection_string`: The connection string for the source AWS RDS Postgres database where you defined the publication.
   - `publication_name`: The name of the publication you created on the source AWS RDS Postgres database.

3. Verify the subscription was created by running the following command:

   ```sql
   SELECT * FROM pg_stat_subscription;

   subid |     subname     | pid  | leader_pid | relid | received_lsn |      last_msg_send_time       |     last_msg_receipt_time     | latest_end_lsn |        latest_end_time
   ------+-----------------+------+------------+-------+--------------+-------------------------------+-------------------------------+----------------+-------------------------------
   16471 | my_subscription | 1080 |            |       | 0/300003A0   | 2024-08-13 20:25:08.011501+00 | 2024-08-13 20:25:08.013521+00 | 0/300003A0     | 2024-08-13 20:25:08.011501+00
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription was created.

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from the publisher to the subscriber database.

1. Run some data modifying queries on the source database (inserts, updates, or deletes). If you're using the `playing_with_neon` database, you can use this statement to insert some rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on the source and destination databases to make sure the result matches.

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   30
   (1 row)
   ```

Alternatively, you can run the following query on the subscriber to make sure the `last_msg_receipt_time` is as expected. For example, if you just ran an insert option on the publisher, the `last_msg_receipt_time` should reflect the time of that operation.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

## Switch over your application

After the replication operation is complete, you can switch your application over to the destination database by swapping out your AWS RDS source database connection details for your Neon destination database connection details.

You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. See [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

--- [Document source](https://neon.com/docs/guides/logical-replication-schema-changes.md) ---

> Summary: Postgres logical replication does not replicate DDL or schema changes, so developers must manually apply and coordinate schema modifications across publisher and subscriber to avoid replication errors. Additive changes (such as adding a column) should be applied to the subscriber first. Non-additive changes (such as dropping a column) should be applied to the publisher first, optionally after pausing writes. Also covers verifying replication health with pg_stat_subscription and using migration tools like Flyway and Liquibase to keep environments in sync.

# Managing schema changes in a logical replication setup

Learn about managing schema changes in a logical replication setup

Last updated: 2026-06-05

When working with Postgres logical replication, managing schema changes is a task that requires careful planning. As stated in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication-restrictions.html):

"_The database schema and DDL commands are not replicated. The initial schema can be copied by hand using `pg_dump --schema-only`. Subsequent schema changes would need to be kept in sync manually. (Note, however, that there is no need for the schemas to be absolutely the same on both sides.) Logical replication is robust when schema definitions change in a live database: When the schema is changed on the publisher and replicated data starts arriving at the subscriber but does not fit into the table schema, replication will error until the schema is updated. In many cases, intermittent errors can be avoided by applying additive schema changes to the subscriber first._"

This guidelines below outline some recommended practices for handling schema changes in a logical replication setup.

## Schema management in a logical replication context

Logical replication in Postgres is designed to replicate data changes (inserts, updates, and deletes) but not schema changes (DDL commands). This means that any modifications to the database schema, such as adding or dropping columns, need to be manually applied to both the publisher and the subscriber databases.

Since the schemas do not need to be exactly the same on both sides, you have some flexibility. However, inconsistencies in the schema can lead to replication errors if the subscriber cannot accommodate incoming data due to schema mismatches.

To ensure that schema changes are successful, we recommend the following practices:

### 1. Apply additive schema changes to the subscriber first

Additive changes, such as adding a new column or creating an index, should be applied to the subscriber before they are applied to the publisher. This approach ensures that when the new data is replicated from the publisher, the subscriber is already prepared to handle it. For example:

- **Add a new column on the subscriber:**

  ```sql
  ALTER TABLE your_table_name ADD COLUMN new_column_name data_type;
  ```

- **Add the same column on the publisher:**

  ```sql
  ALTER TABLE your_table_name ADD COLUMN new_column_name data_type;
  ```

Applying additive schema changes in this order will help prevent replication errors caused by the subscriber not recognizing the additive change in the incoming data.

### 2. Handle non-additive schema changes with caution

Non-additive changes, such as dropping a column or altering a column's data type, require careful handling. When performing a non-additive schema change like dropping a column, apply the change on the publisher first, then on the subscriber.

Non-additive changes are often feasible if applied in the correct order (publisher first). However, always carefully assess how the schema change will impact replication to the subscriber. Will writes still succeed on the subscriber after the change on the publisher? It's best practice to test schema changes before implementing them in production. For example, test whether writes to the modified publisher schema still execute successfully on the unmodified subscriber schema.

Mistakes in the schema update process could disrupt replication on the subscriber, requiring troubleshooting and reestablishing replication.

For an added degree of safety or for complex schema changes, consider temporarily pausing write activity on the publisher before applying schema changes. The steps for this approach include:

- **Pausing writes on the publisher:** Pause writes on the publisher by stopping or pausing the application that handles inserts, updates, and deletes, or by revoking write permissions on the roles that write to the database. Other methods may also be available depending on your environment.
- **Applying schema changes on the publisher:** Apply the necessary schema changes to the publisher.
- **Applying schema changes on the subscriber:** Once the publisher changes are complete, apply the schema changes to the subscriber.
- **Resuming writes:** After verifying that the changes are successful, resume normal write operations.

### 3. Monitor and verify replication

After applying schema changes and resuming writes, verify that data is being replicated between the publisher and subscriber.

To do this, you can run the following query on the subscriber to make sure the `last_msg_receipt_time` is recent:

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time FROM pg_catalog.pg_stat_subscription;
```

You can also perform a row count on the publisher and subscriber databases to make sure results are as expected. If you're actively adding rows, the results may be close but not exactly the same.

```sql
SELECT COUNT(*) FROM your_table_name;
```

## Schema migration tools

Tools like [Flyway](https://flywaydb.org/) and [Liquibase](https://www.liquibase.org/) can assist in managing schema changes by ensuring they are applied consistently across multiple databases. These tools track the history of each change and ensure updates are applied in the correct sequence. Integrating these tools into your workflow can improve the reliability and organization of your schema migrations, but may require adjustments to your existing process.

If you're unfamiliar with these tools, check out the following guides to get started with Neon:

- [Get started with Flyway and Neon](https://neon.com/docs/guides/flyway)
- [Get started with Liquibase and Neon](https://neon.com/docs/guides/liquibase)

For guidance on managing schemas across multiple databases using Flyway or Liquibase, see:

- [Flyway: A simple way to manage multiple environment deployments](https://www.red-gate.com/blog/a-simple-way-to-manage-multi-environment-deployments)
- [How to set up Liquibase with an Existing Project and Multiple Environments](https://docs.liquibase.com/workflows/liquibase-community/existing-project.html)

Some Object Relational Mappers (ORMs) also support managing schemas across multiple database environments. For example, with Prisma ORM, you can configure multiple `.env` files. Learn more at [Using multiple .env files](https://www.prisma.io/docs/orm/more/development-environment/environment-variables#using-multiple-env-files).

Regardless of the schema management tool you choose, ensure that changes adhere to the guidelines for [additive](https://neon.com/docs/guides/logical-replication-schema-changes#1-apply-additive-schema-changes-to-the-subscriber-first) and [non-additive](https://neon.com/docs/guides/logical-replication-schema-changes#2-handle-non-additive-schema-changes-with-caution) schema changes.

If you have suggestions, tips, or requests regarding schema management in a replication setup, please let us know via the [Feedback](https://console.neon.tech/app/projects?modal=feedback) form in the Neon Console or through our [feedback channel](https://discord.com/channels/1176467419317940276/1176788564890112042) on Discord.

## References

- [PostgreSQL logical replication restrictions](https://www.postgresql.org/docs/current/logical-replication-restrictions.html)
- [Import a database schema](https://neon.com/docs/import/migrate-schema-only)

--- [Document source](https://neon.com/docs/guides/logical-replication-stacksync.md) ---

> Summary: Stacksync connects a Lakebase Postgres database to CRMs, ERPs, and other destinations via real-time one-way or two-way sync, using Postgres logical replication (wal_level=logical) as the change data capture method. Use this guide when you need to sync Neon table data to a Stacksync-supported connector without a third-party ETL tool. Each synced table must have a single-column auto-generated primary key, and you must use a direct connection string (no connection pooler) when configuring the Postgres source.

# Replicate data with Stacksync

Learn how to replicate data from Neon with Stacksync

Last updated: 2026-10-09

Neon's logical replication feature allows you to replicate data from your Lakebase Postgres database to external destinations.

[Stacksync](https://www.stacksync.com/) connects databases with CRMs, ERPs, and other systems using real-time, two-way sync. In this guide, you will configure Stacksync to replicate data from your Lakebase Postgres database to a [supported destination](https://www.stacksync.com/connectors).

## Prerequisites

- A [Stacksync account](https://www.stacksync.com/)
- A [Neon account](https://console.neon.tech/)
- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin

**Important: Compute and billing**

Replication keeps compute active (no [scale to zero](https://neon.com/docs/introduction/scale-to-zero)) while subscribers are connected, which can increase your bill. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Prepare your Neon database

### Enable logical replication in Neon

**Important:** Enabling logical replication modifies the Postgres `wal_level` configuration parameter, changing it from `replica` to `logical` for all databases in your Neon project. Once the `wal_level` setting is changed to `logical`, it cannot be reverted. Enabling logical replication also restarts all computes in your Neon project, meaning active connections will be temporarily dropped before automatically reconnecting.

To enable logical replication in Neon:

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then **Logical replication**.
4. Click **Enable** to enable logical replication.

You can verify that logical replication is enabled by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor):

```sql
SHOW wal_level;
 wal_level
-----------
 logical
```

### Create a Postgres role for replication

It is recommended that you create a dedicated Postgres role for replicating data. The role must have the `REPLICATION` privilege. The default Postgres role created with your Neon project and roles created using the Neon CLI, Console, or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the required `REPLICATION` privilege.

**CLI**

The following CLI command creates a role. To view the CLI documentation for this command, see [Neon CLI commands — roles](https://neon.com/docs/cli/roles)

```bash
neon roles create --name replication_user
```

**Console**

To create a role in the Neon Console:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add Role**.
6. In the role creation dialog, specify a role name, such as `replication_user`.
7. Click **Create**. The role is created, and you are provided with the password for the role.

**API**

The following Neon API method creates a role. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-role).

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "replication_user"
  }
}' | jq
```

> Replace `{project_id}` and `{branch_id}` with your actual Neon project and branch IDs, and set the `NEON_API_KEY` environment variable with your Neon API key.

### Grant schema access to your Postgres role

If your replication role does not own the schemas and tables you are replicating from, make sure to grant access. For example, the following commands grant access to all tables in the `public` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA public TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

### Create a publication

**Important:** Stacksync requires every table you sync to have a single-column, auto-generated primary key (for example, a `serial` integer or a `uuid`). Tables with composite primary keys, no primary key, or a primary key without a default value will not appear in Stacksync. See [Stacksync Postgres connector requirements](https://docs.stacksync.com/two-way-sync/connectors/postgres).

Create the Postgres publication. Include all tables you want to replicate as part of the publication:

```sql
CREATE PUBLICATION stacksync_pub FOR TABLE <tbl1, tbl2, tbl3>;
```

The publication name is customizable. Refer to the [Postgres docs](https://www.postgresql.org/docs/current/logical-replication-publication.html) if you need to add or remove tables from your publication.

## Create a Postgres connection in Stacksync

1. Log in to your [Stacksync](https://www.stacksync.com/) account.

2. On the **All Resources** page, click **Create Resource**.

3. Under **Jump right in, create a resource**, click **Connections**.

4. Select **Postgres**.

5. Enter your Neon database connection details. Click **Connect** in the Console nav, select the replication role you created earlier (not the default `neondb_owner` role), and click **Copy snippet**. Use a direct connection string; the hostname must not include `-pooler`. Logical replication is not compatible with connection poolers.

6. If you have disabled **Allow traffic via the public internet** under **Networking** in Neon's **Settings**, select **I confirm I have allowlisted these Stacksync IPs on my side** in Stacksync, and copy the IP addresses into your trusted IP addresses in Neon's settings under **Networking**.

7. In Stacksync, click **Next**.

8. Enter a name for **Connection Name**.

9. Click **Create**.

## Create a connection to your destination in Stacksync

Skip this step if you already have a destination connection configured in Stacksync.

1. Log in to your [Stacksync](https://www.stacksync.com/) account.
2. On the **All Resources** page, click **Create Resource**.
3. Under **Jump right in, create a resource**, click **Connections**.
4. Select the connector for your destination from one of [Stacksync's connectors](https://www.stacksync.com/connectors).
5. Follow the prompt in the **Configure connection** popup.
6. If you have disabled public internet access in Neon, allowlist the Stacksync IPs as described in the [Create a Postgres connection in Stacksync](https://neon.com/docs/guides/logical-replication-stacksync#create-a-postgres-connection-in-stacksync) section above.
7. In Stacksync, click **Next**.
8. Enter a name for **Connection Name**.
9. Click **Create**.

   **Tip:** There are in-depth connection setup guides on [Stacksync's connector docs](https://docs.stacksync.com/two-way-sync/connectors).

## Create a sync

Skip this step if you already have a sync configured.

1. Log in to your [Stacksync](https://www.stacksync.com/) account.

2. On the **All Resources** page, click **Create Resource**.

3. Under **Jump right in, create a resource**, click **Syncs**.

4. Enter a **Sync Name**.

5. Select **Postgres** and choose the saved connection you created in the [Create a Postgres connection in Stacksync](https://neon.com/docs/guides/logical-replication-stacksync#create-a-postgres-connection-in-stacksync) section.

6. On the schema screen, click the **Postgres** connection and select **Logical replication** under **Change Data Capture Method**.

   ![Stacksync Logical Replication](https://neon.com/docs/guides/stacksync-logical-replication.png)

7. Click one of the apps you have created a connection for in the [Create a connection to your destination in Stacksync](https://neon.com/docs/guides/logical-replication-stacksync#create-a-connection-to-your-destination-in-stacksync) section.

8. Click **Link Tables**.

9. Select a table you would like to sync under **Postgres**.

10. Select a table you would like to sync the data to under your destination.

11. Select if you would like the sync to be [one-way or two-way](https://www.stacksync.com/data-sync/two-way-vs-one-way-sync).

12. Repeat from the previous step for any additional tables you would like to link.

13. Click **Map Columns** to configure which columns to sync and the sync direction for each. Stacksync auto-maps columns by default; select or deselect columns as needed. See [Stacksync's two-way sync docs](https://docs.stacksync.com/two-way-sync/features/two-way-sync) for details on field selection and sync direction.

14. Click **Create**.

15. On the next page, turn on the sync by clicking the toggle in the top right.

16. Optionally, update the **Data sync frequency** under **Settings**.

## References

- [Stacksync Generic PostgreSQL Setup Guide](https://docs.stacksync.com/two-way-sync/connectors/postgres)

--- [Document source](https://neon.com/docs/guides/logical-replication-supabase-to-neon.md) ---

> Summary: Logical replication from Supabase to Neon streams live Postgres data changes by creating a publication on Supabase and a subscription on Neon. A direct IPv4 connection string is required (the Supabase IPv4 add-on), and Neon NAT Gateway IPs must be allowlisted in Supabase network restrictions. Use this page when migrating or syncing a Supabase Postgres database to Neon with minimal downtime. Supabase enables wal_level=logical by default; replication slot limits vary by plan and may require an instance upgrade for large datasets.

# Replicate data from Supabase

Learn how to replicate data from Supabase to Neon

Last updated: 2026-09-16

This guide describes how to replicate data from Supabase to Neon using native Postgres logical replication with Lakebase Postgres. The steps in this guide follow those described in [Replicate to another Postgres database using Logical Replication](https://supabase.com/docs/guides/database/postgres/setup-replication-external), in the _Supabase documentation_.

## Prerequisites

- A Supabase project with a Postgres database containing the data you want to replicate. If you're just testing this out and need some data to play with, you can use the following statements in your Supabase SQL Editor to create a table with sample data:

  ```sql
  CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
  INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
  ```

- A Neon project with a Postgres database to receive the replicated data. For information about creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

## Prepare your Supabase source database

This section describes how to prepare your source Supabase Postgres instance (the publisher) for replicating data to Neon.

### Enable logical replication

Logical replication is enabled by default in Supabase. You can verify that `wal_level` is set to `logical` by running the following query in your Supabase SQL Editor or using `psql` connected to your Supabase database:

```sql
SHOW wal_level;
```

The output should be:

```text
wal_level
-----------
logical
(1 row)
```

If `wal_level` is not `logical`, contact Supabase support to enable it.

### Allow connections from Neon

You need to allow inbound connections to your Supabase Postgres database from the Neon NAT Gateway IP addresses. This allows Neon to connect to your Supabase database for logical replication. Follow these steps to configure network restrictions in Supabase:

1. **Obtain Neon NAT Gateway IP Addresses**: See [NAT Gateway IP addresses](https://neon.com/docs/introduction/regions#nat-gateway-ip-addresses) for the IP addresses for your Neon project's region. You will need to allow connections from these IP addresses in your Supabase project.
2. **Configure Network Restrictions in Supabase**:
   - Go to your Supabase project dashboard.
   - Navigate to **Project Settings** > **Database** > **Network restrictions**.
   - Ensure you have **Owner** or **Admin** permissions for the Supabase project to configure network restrictions.
   - Add inbound rules to allow connections from the Neon NAT Gateway IP addresses you obtained in the previous step. Add each IP address individually.
     ![Supabase Network Restrictions](https://neon.com/docs/guides/supabase_network_restrictions.png)

### Obtain a direct connection string

Logical replication requires a direct connection string, not a pooled connection string.

1. **Enable IPv4 Add-on**: In your Supabase project dashboard, navigate to **Project Settings** > **Add-ons**. Enable the **IPv4** add-on. This add-on is required to obtain a direct IPv4 connection string. Note that this add-on might incur extra costs.

   ![Supabase IPv4 Add-on](https://neon.com/docs/guides/supabase_ipv4_addon_image.png)

2. **Get the Direct Connection String**: After enabling the IPv4 add-on, copy the direct connection string from the **Connect** button in the Navigation bar of your Supabase dashboard. This connection string is required to create a subscription in Neon.

   ![Supabase Direct Connection String](https://neon.com/docs/guides/supabase_direct_connection_string.png)

   **Warning:** Avoid using pooled connection strings (Transaction and session poolers) for logical replication. Use the direct connection string obtained after enabling the IPv4 add-on.

### Create a publication on the source database

Publications are a fundamental part of logical replication in Postgres. They define what will be replicated. You can run the following SQL statements in your Supabase SQL Editor or using [psql](https://neon.com/docs/connect/query-with-psql-editor) to create a publication for the tables you want to replicate.

- To create a publication for a specific table, use the `CREATE PUBLICATION` statement. For example, to create a publication for the `playing_with_neon` table:

  ```sql
  CREATE PUBLICATION my_publication FOR TABLE playing_with_neon;
  ```

- To create a publication for multiple tables, provide a comma-separated list of tables:

  ```sql
  CREATE PUBLICATION my_publication FOR TABLE users, departments;
  ```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

## Prepare your Neon destination database

This section describes how to prepare your Lakebase Postgres database (the subscriber) to receive replicated data from your Supabase Postgres instance.

### Prepare your database schema

When configuring logical replication in Postgres, the tables defined in your publication on the source database you are replicating from must also exist in the destination database, and they must have the same table names and columns. You can create the tables manually in your destination database or use utilities like `pg_dump` and `pg_restore` to dump the schema from your source database and load it to your destination database. See [Import a database schema](https://neon.com/docs/import/migrate-schema-only) for instructions.

If you're using the sample `playing_with_neon` table, you can create the same table on the destination database with the following statement in your Neon SQL Editor or using `psql`:

```sql
CREATE TABLE IF NOT EXISTS playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
```

### Create a subscription

After creating a publication on the source database, you need to create a subscription on your Neon destination database.

1. Use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), `psql`, or another SQL client to connect to your Neon database.

2. Create the subscription using the `CREATE SUBSCRIPTION` statement. Use the **direct connection string** you obtained from Supabase in the previous steps.

   ```sql
   CREATE SUBSCRIPTION my_subscription
   CONNECTION 'postgresql://<supabase_connection_string>'
   PUBLICATION my_publication;
   ```

   Replace the following placeholders in the statement:

   - `my_subscription`: A name you chose for the subscription.
   - `postgresql://<supabase_connection_string>`: The **direct connection string** for your Supabase database, obtained with the IPv4 add-on enabled.
   - `my_publication`: The name of the publication you created on the Supabase database.

3. Verify that the subscription was created in Neon by running the following query:

   ```sql
   SELECT * FROM pg_stat_subscription;

   subid   | subname         | worker_type | pid  | leader_pid | relid | received_lsn |     last_msg_send_time        |   last_msg_receipt_time      | latest_end_lsn |      latest_end_time
   --------|-----------------|-------------|------|------------|-------|--------------|-------------------------------|------------------------------|----------------|-------------------------------
   216502  | my_subscription |    apply    | 1069 |            |       | 0/75B1000    | 2025-02-11 10:00:04.142994+00 | 2025-02-11 10:00:04.14277+00 |   0/75B1000    | 2025-02-11 10:00:04.142994+00
   ```

   The subscription (`my_subscription`) should be listed, confirming that your subscription was created successfully.

**Note:** **Replication Slots Limits**: Supabase has limits on `max_replication_slots` and `max_wal_senders` which vary based on your Supabase instance size/plan. If you encounter issues, you might need to upgrade your Supabase instance to perform logical replication, especially for larger datasets or multiple replication slots. Check [Supabase documentation](https://supabase.com/docs/guides/platform/compute-and-disk#limits-and-constraints) for the limits on your instance size.

## Test the replication

Testing your logical replication setup ensures that data is being replicated correctly from the publisher to the subscriber database.

1. Run some data modifying queries on the source database (inserts, updates, or deletes) in your Supabase SQL Editor or using `psql`. If you're using the `playing_with_neon` database, you can use this statement to insert 10 rows:

   ```sql
   INSERT INTO playing_with_neon(name, value)
   SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
   ```

2. Perform a row count on both the Supabase source and Neon destination databases to make sure the result matches. In both databases, run:

   ```sql
   SELECT COUNT(*) FROM playing_with_neon;

   count
   -------
   20
   (1 row)
   ```

   The count should be the same in both databases, reflecting the newly inserted rows.

Alternatively, you can run the following query on the subscriber (Neon) to make sure the `last_msg_receipt_time` is updated and as expected.

```sql
SELECT subname, received_lsn, latest_end_lsn, last_msg_receipt_time
FROM pg_catalog.pg_stat_subscription;
```

## Switch over your application

After the replication operation is complete and you have verified that data is being replicated correctly, you can switch your application over to the Neon database.

1. Stop writes to your Supabase database.
2. Wait for any final transactions to be replicated to Neon. Monitor `pg_stat_subscription` in Neon until `received_lsn` and `latest_end_lsn` are close or equal, indicating minimal replication lag.
3. Update your application's connection string to point to your Neon database.

You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For details, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Reference

For more information about logical replication and Postgres client utilities, refer to the following topics in the Postgres and Neon documentation:

- [Postgres - Logical replication](https://www.postgresql.org/docs/current/logical-replication.html)
- [Neon logical replication guide](https://neon.com/docs/guides/logical-replication-guide)
- [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html)
- [psql](https://www.postgresql.org/docs/current/app-psql.html)
- [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html)

--- [Document source](https://neon.com/docs/guides/logical-replication-tips.md) ---

> Summary: Practical tips for migrating to Neon with logical replication, drawn from real customer migrations. Covers compute scaling for initial data loads, deferring index creation, raising wal_sender_timeout and wal_receiver_timeout beyond the default, and reducing the history window to limit storage growth. Use this page when troubleshooting replication timeouts, slow initial copies, or extension compatibility blockers. Also explains why FOR ALL TABLES publications prevent later table additions or removals, with the correct per-table CREATE PUBLICATION syntax as an alternative.

# Logical replication tips

Learn how to optimize for logical replication

Last updated: 2026-06-05

The following tips are based on actual customer data migrations to Neon using logical replication:

- Initial data copying during logical replication can significantly increase the load on both the publisher and subscriber. For large data migrations, consider increasing compute resources (CPU and RAM) for the initial copy. On Neon, you can do this by [enabling autoscaling](https://neon.com/docs/guides/autoscaling-guide) and selecting a larger maximum compute size. The publisher (source database instance) typically experiences higher load, as it serves other requests while the subscriber only receives replicated data.
- For large datasets, avoid creating indexes when setting up the schema on the destination database (subscriber) to reduce the initial data load time. Indexes can be added back after the data copy is complete.
- If you encounter replication timeout errors, consider increasing `wal_sender_timeout` on the publisher and `wal_receiver_timeout` on the subscriber to a higher value, such as 5 minutes (default is 1 minute). On Neon, adjusting these settings requires assistance from [Neon Support](https://neon.com/docs/introduction/support).
- To minimize storage consumption during data replication to Neon, reduce your [history window](https://neon.com/docs/introduction/history-window) setting. For example, set it to 1 hour or 0 during the initial copy, and restore it to the desired value afterward.
- Ensure that any Postgres extensions that you depend on are also supported by Neon. For extensions and extension versions supported by Neon, see [Supported Postgres extensions](https://neon.com/docs/extensions/pg-extensions). If you find that support is missing for a particular extension or extension version that would prevent you from migrating your data to Neon, please reach out to [Neon Support](https://neon.com/docs/introduction/support).
- Avoid defining publications with `FOR ALL TABLES` if you want to add or drop tables from the publication later. It is not possible to add or drop tables from a publication defined with `FOR ALL TABLES`.

  ```sql
  ALTER PUBLICATION test_publication ADD TABLE users;
  ERROR:  publication "my_publication" is defined as FOR ALL TABLES
  DETAIL:  Tables cannot be added to or dropped from FOR ALL TABLES publications.

  ALTER PUBLICATION test_publication DROP TABLE products;
  ERROR:  publication "my_publication" is defined as FOR ALL TABLES
  DETAIL:  Tables cannot be added to or dropped from FOR ALL TABLES publications.
  ```

  Instead, you can create a publication for a specific table using the following syntax:

  ```sql
  CREATE PUBLICATION my_publication FOR TABLE users;
  ```

  To create a publication for multiple tables, specify a comma-separated list of tables:

  ```sql
  CREATE PUBLICATION my_publication FOR TABLE users, departments;
  ```

  For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

If you have logical replication or data migration tips you would like to share, please let us know via the [Feedback](https://console.neon.tech/app/projects?modal=feedback) form in the Neon Console or our [feedback channel](https://discord.com/channels/1176467419317940276/1176788564890112042) on Discord.

--- [Document source](https://neon.com/docs/guides/medusajs.md) ---

> Summary: Self-hosting Medusa, an open-source headless e-commerce platform, with Neon serverless Lakebase Postgres uses a Neon connection string passed via `--db-url` to `create-medusa-app`, which runs database migrations and seeds demo data automatically. A non-pooled connection string is required during initial setup for migrations; switch to the pooled string afterward for better production performance. Deployment options covered include local development and self-hosted environments such as DigitalOcean, AWS EC2, Render, and Fly.io.

# Self-Host Medusa with Neon

Learn how to self-host Medusa using Lakebase Postgres as your database.

Last updated: 2026-10-28

[Medusa](https://medusajs.com/) is an open-source headless e-commerce platform that provides a flexible backend for e-commerce applications. It uses Postgres as its primary database to store all product, order, and customer data.

In this guide, you'll learn how to set up and self-host Medusa using [Neon](https://neon.com) as your Postgres database. Neon is the backend for apps and agents. Lakebase Postgres is serverless, with autoscaling and scale-to-zero, so it suits a Medusa backend.

## Prerequisites

Before you begin, ensure you have the following:

1. **Neon Account:** You'll need a Neon account. If you don't have one, sign up [here](https://console.neon.tech/signup).
2. **Node.js & package manager:** Node.js 22.23.4 or later, which the generated Medusa project requires, and a package manager (`npm`, `yarn`, or `pnpm`).
   > This guide uses Node.js with `npm`, but you can adapt the commands to your preferred package manager.

## Setting up your Neon database

You'll first need to create a Neon database. Follow these steps:

1. Create a new Neon project from the [Neon Console](https://console.neon.tech). For instructions, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

   **Tip:** When creating your Neon project, choose a region that is geographically close to your Medusa server to minimize latency and improve overall performance of your Medusa application.

2. Copy your database connection string by clicking **Connect** in the Console nav.

   **Important:** Use the non-pooled connection string for setup. Medusa needs it to run the initial migrations. After installation you can switch to the pooled version to improve performance.

   ![Connection modal](https://neon.com/docs/connect/connection_details_without_connection_pooling.png)

   > Choose the **Branch**, **Database**, and **Role** as per your setup

   Your connection string will look similar to this:

   ```text
   postgres://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require
   ```

## Initialize the Medusa application

The Medusa CLI tool, `create-medusa-app`, simplifies the process of setting up a new Medusa project. It can automatically configure your Medusa backend to connect to your Neon database, run the necessary migrations, and seed initial data.

### Run the setup command

Execute the following command in your terminal. Replace the example string with the exact connection string you copied from the Neon Console.

```bash
npx create-medusa-app@latest --db-url "YOUR_NEON_CONNECTION_STRING"
```

### Installation steps

1. **Follow the prompts:** The CLI will ask a few questions to configure your setup:
   - **Project name:** Enter a name for your project (for example, `medusa-neon-store`).
   - **Frontend starter:** Choose whether to install the Next.js Starter Storefront or skip it depending on your preference.
2. **Automatic setup:**
   - The tool will install the Medusa backend and optionally the Next.js Starter Storefront.
   - **Crucially**, it will use your Neon connection string to:
     - Update the backend's configuration file.
     - **Run the initial database migrations** (creating all Medusa tables) on your Neon database.
     - **Seed initial data** (sample products, regions, etc.) into your Neon database.

You should see output similar to the following once the setup is complete:

```bash
$ npx create-medusa-app@latest --db-url "YOUR_NEON_CONNECTION_STRING"
? What's the name of your project? medusa-neon-store
? Would you like to install the Next.js Starter Storefront? You can also install it later. Yes
🚀 Starting project setup, this may take a few minutes.
✔ Created project directory
✔ Installed Next.js Starter Storefront successfully in the my-medusa-store-storefront directory.
✔ Installed Dependencies
✔ Ran Migrations
✔ Seeded database with demo data
✔ Finished Preparation
✔ Project Prepared
Starting Medusa...

> medusa-neon-store@0.0.1 dev
> medusa develop

- Creating server
✔ Server is ready on port: 9000 – 11ms
```

## Create an Admin user

After creating the Medusa application, a browser window should open automatically pointing to the Medusa Admin interface. Create your admin user by filling out the registration form.

![Medusa Admin Registration](https://neon.com/docs/guides/medusa-admin-registration.png)

Following successful registration, you will be redirected to the Medusa Admin dashboard where you can manage your store.

If the browser doesn't open, or you prefer the terminal, create the admin user from the backend directory:

```bash
cd medusa-neon-store/apps/backend
npx medusa user -e admin@example.com -p AbC123dEf
```

## Verify the connection

After the installation is complete, you can optionally verify the tables in the Neon Console:

1. Open your project in the Neon Console.
2. In the sidebar, select **Postgres database** > **Tables**.
3. You should see all the Medusa tables created in your database.

![Medusa Tables in Neon](https://neon.com/docs/guides/medusa-neon-tables.png)

## Running and deploying Medusa

Your Medusa application is now fully configured to use Neon as its database. You can now start the application locally or deploy it to your self-hosted environment.

### Local development

1. Navigate into your new project directory:
   ```bash
   cd medusa-neon-store
   ```
2. Start the Medusa backend server:
   ```bash
   npm run dev
   ```
   Your Medusa backend should now be running locally and accessible at `http://localhost:9000/app`.

### Deployment to a self-hosted environment

For deployment to a VPS (like DigitalOcean, AWS EC2) or a dedicated platform (like Render, Fly.io), the process is the same as deploying any standard Medusa application. Ensure you configure the database connection to point to your Neon database.

1. Set the `DATABASE_URL` environment variable in your deployment environment to your Neon connection string.
2. Follow the self-hosting deployment instructions in the [Medusa documentation](https://docs.medusajs.com/resources/deployment#self-hosting-medusa) to deploy your Medusa backend and the storefront.

You can optionally enable IP whitelisting in the Neon Console to restrict database access to only your Medusa server's IP address for enhanced security. Learn more: [Neon IP Allow](https://neon.com/docs/introduction/ip-allow)

## Resources

- [Neon Documentation](https://neon.com/docs)
- [Medusa Official Documentation](https://docs.medusajs.com/)
- [Medusa Application Deployment Guide](https://docs.medusajs.com/learn/deployment/general)

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/micronaut-kotlin.md) ---

> Summary: Connect a Kotlin-based Micronaut microservice to Lakebase Postgres using Hikari connection pooling, Flyway schema migrations, and Micronaut Data JDBC to expose CRUD REST endpoints. Use this guide when building a Micronaut app that needs a production-ready Postgres connection with automatic schema management. The setup uses the micronaut-data-jdbc, jdbc-hikari, and flyway Micronaut features alongside the org.postgresql JDBC driver.

# Connect a Micronaut Kotlin application to Lakebase Postgres

Learn how to make server-side queries to Postgres from a Micronaut Kotlin application

Last updated: 2026-08-04

Pre-built prompt for connecting Micronaut Kotlin applications to Lakebase Postgres [View prompt](https://neon.com/prompts/micronaut-kotlin-prompt.md)

[Micronaut](https://micronaut.io/) is a JVM-based, full-stack framework for building microservice and serverless applications. This guide describes how to create a database on Neon and connect to it from a Micronaut Kotlin application.

The final application will expose REST endpoints to perform CRUD (Create, Read, Update, Delete) operations on a `book` table in your Neon database.

To create a Neon project and access it from a Micronaut Kotlin application, you will:

1. [Create a Neon project](https://neon.com/docs/guides/micronaut-kotlin#create-a-neon-project)
2. [Create a Micronaut Kotlin project](https://neon.com/docs/guides/micronaut-kotlin#create-a-micronaut-kotlin-project)
3. [Configure your database connection](https://neon.com/docs/guides/micronaut-kotlin#configure-your-database-connection)
4. [Build the application components](https://neon.com/docs/guides/micronaut-kotlin#build-the-application-components)
5. [Run and test the application](https://neon.com/docs/guides/micronaut-kotlin#run-and-test-the-application)

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Save your connection details. You will need them in a later step.

## Create a Micronaut Kotlin project

You can create a new Micronaut project using either the Micronaut CLI or the [Micronaut Launch](https://launch.micronaut.io/) website.

This guide uses the Micronaut CLI.

> Install the Micronaut CLI by following the instructions in the [Micronaut documentation](https://micronaut.io/download/). The Micronaut 5 CLI runs on JDK 25 (it fails on older JDKs such as 17). The application you create targets JDK 21, so install JDK 21 as well.

Run the following command in your terminal. This command creates a new application and includes features for Postgres connectivity, JDBC connection pooling (Hikari), database migrations (Flyway), data access, and YAML configuration. The `com.example.` prefix sets the base package to `com.example`, which the code in this guide uses. Without a prefix, the CLI derives a different package from the app name, and Micronaut doesn't find classes in `com.example`.

```bash
mn create-app com.example.with-micronaut-kotlin \
  --lang=kotlin \
  --jdk=21 \
  --features=postgres,jdbc-hikari,flyway,data-jdbc,yaml
```

After creating the project, open the `build.gradle.kts` file and add the following block at the top level of the file (the generated file doesn't include a `kotlin` block) so the build uses JDK 21:

```kotlin filename="build.gradle.kts"
kotlin {
    jvmToolchain(21)
}
```

## Configure your database connection

The project creation process generated a configuration file at `src/main/resources/application.yml`. You need to edit this file to add your Neon database credentials.

Add the `url`, `username`, and `password` fields under the `datasources.default` section. Your updated `application.yml` file should look like this:

```yaml {8-10}
# src/main/resources/application.yml

micronaut:
  application:
    name: with-micronaut-kotlin
datasources:
  default:
    url: 'jdbc:postgresql://[neon_hostname]/[dbname]?sslmode=require&channelBinding=require'
    username: '[user]'
    password: '[password]'
    driver-class-name: org.postgresql.Driver
    db-type: postgres
    dialect: POSTGRES
flyway:
  datasources:
    default:
      enabled: true
```

> Replace `[neon_hostname]`, `[dbname]`, `[user]`, and `[password]` with the connection details you saved earlier. JDBC takes the host and database in the URL and the user and password as separate settings, and writes `channel_binding` as `channelBinding`.

## Build the application components

Now you can create the components for a simple book inventory API: an entity, a repository, a controller, and a database migration script.

### 1. Create the database schema with Flyway

Flyway handles database migrations automatically when the application starts. Create a SQL file at `src/main/resources/db/migration/V1__create_book_table.sql` to define your table schema and add some initial data.

```sql
-- src/main/resources/db/migration/V1__create_book_table.sql

CREATE TABLE IF NOT EXISTS book (
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    author VARCHAR(255) NOT NULL
);

INSERT INTO book (title, author) VALUES ('The Hobbit', 'J.R.R. Tolkien');
INSERT INTO book (title, author) VALUES ('1984', 'George Orwell');
```

### 2. Create the entity

Create a data class that maps to the `book` table. The `@Serdeable` annotations are required for Micronaut to handle JSON serialization and deserialization for your API.

```kotlin
// src/main/kotlin/com/example/entity/Book.kt

package com.example.entity

import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.MappedEntity
import io.micronaut.serde.annotation.Serdeable

@MappedEntity
@Serdeable
data class Book(
    @field:Id
    @field:GeneratedValue
    var id: Long? = null,
    var title: String,
    var author: String
)
```

### 3. Create the repository

Create a repository interface that extends `CrudRepository`. This interface provides CRUD operations for the `Book` entity.

```kotlin
// src/main/kotlin/com/example/repository/BookRepository.kt

package com.example.repository

import com.example.entity.Book
import io.micronaut.data.jdbc.annotation.JdbcRepository
import io.micronaut.data.model.query.builder.sql.Dialect
import io.micronaut.data.repository.CrudRepository

@JdbcRepository(dialect = Dialect.POSTGRES)
interface BookRepository : CrudRepository<Book, Long>
```

### 4. Create the controller

Finally, create a controller to expose the REST endpoints for interacting with the books.

```kotlin
// src/main/kotlin/com/example/controller/BookController.kt

package com.example.controller

import com.example.entity.Book
import com.example.repository.BookRepository
import io.micronaut.http.annotation.*
import io.micronaut.scheduling.TaskExecutors
import io.micronaut.scheduling.annotation.ExecuteOn

@Controller("/books")
class BookController(private val bookRepository: BookRepository) {

    @Get
    @ExecuteOn(TaskExecutors.IO)
    fun getAll(): List<Book> = bookRepository.findAll().toList()

    @Get("/{id}")
    @ExecuteOn(TaskExecutors.IO)
    fun getById(id: Long): Book? = bookRepository.findById(id).orElse(null)

    @Post
    @ExecuteOn(TaskExecutors.IO)
    fun save(@Body book: Book): Book = bookRepository.save(book)
}
```

## Run and test the application

You are now ready to run your application.

1. Start the application using the Gradle wrapper:

   ```bash
   ./gradlew run
   ```

   You should see output similar to the following:

   ```bash
   $ ./gradlew run

   [test-resources-service] 15:48:33.940 [main] INFO  i.m.c.DefaultApplicationContext$RuntimeConfiguredEnvironment - Established active environments: [test]

   > Task :run
   __  __ _                                  _
   |  \/  (_) ___ _ __ ___  _ __   __ _ _   _| |_
   | |\/| | |/ __| '__/ _ \| '_ \ / _` | | | | __|
   | |  | | | (__| | | (_) | | | | (_| | |_| | |_
   |_|  |_|_|\___|_|  \___/|_| |_|\__,_|\__,_|\__|
   15:48:43.830 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Starting...
   15:48:45.974 [main] INFO  com.zaxxer.hikari.pool.HikariPool - HikariPool-1 - Added connection org.postgresql.jdbc.PgConnection@30506c0d
   15:48:45.975 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Start completed.
   15:48:46.126 [main] INFO  i.m.flyway.AbstractFlywayMigration - Running migrations for database with qualifier [default]
   15:48:46.298 [main] INFO  org.flywaydb.core.FlywayExecutor - Database: jdbc:postgresql://endpoint.neon.tech/examples?sslmode=require&channelBinding=require (PostgreSQL 17.5)
   15:48:48.110 [main] INFO  o.f.c.i.s.JdbcTableSchemaHistory - Schema history table "public"."flyway_schema_history" does not exist yet
   15:48:48.250 [main] INFO  o.f.core.internal.command.DbValidate - Successfully validated 1 migration (execution time 00:00.432s)
   15:48:49.524 [main] INFO  o.f.c.i.s.JdbcTableSchemaHistory - Creating Schema History table "public"."flyway_schema_history" ...
   15:48:51.817 [main] INFO  o.f.core.internal.command.DbMigrate - Current version of schema "public": << Empty Schema >>
   15:48:52.243 [main] INFO  o.f.core.internal.command.DbMigrate - Migrating schema "public" to version "1 - create book table"
   15:48:54.757 [main] INFO  o.f.core.internal.command.DbMigrate - Successfully applied 1 migration to schema "public", now at version v1 (execution time 00:00.969s)
   15:48:55.841 [main] INFO  io.micronaut.runtime.Micronaut - Startup completed in 12788ms. Server Running: http://localhost:8080 :run
   <============-> 92% EXECUTING [38s]
   > :run
   > IDLE
   ```

   The logs indicate the following sequence of events:

   - HikariCP initializes the connection pool to the Lakebase Postgres database.
   - Flyway checks the database schema and found that the `flyway_schema_history` table does not exist.
   - Flyway creates the `flyway_schema_history` table and applies the migrations present in the migration folder.
   - The `book` table is created as per the migration script (i.e., `V1__create_book_table.sql`).
   - The application starts successfully and is ready to handle requests.

   Now with the application running, you can test the API endpoints.

2. Test the API endpoints using `curl` or any API client:

   ```bash
   # Get all books
   curl http://localhost:8080/books
   # Expected Output: [{"id":1,"title":"The Hobbit","author":"J.R.R. Tolkien"},{"id":2,"title":"1984","author":"George Orwell"}]

   # Get a specific book by ID
   curl http://localhost:8080/books/1
   # Expected Output: {"id":1,"title":"The Hobbit","author":"J.R.R. Tolkien"}

   # Create a new book
   curl -X POST \
     -H "Content-Type: application/json" \
     -d '{"title":"The Great Gatsby","author":"F. Scott Fitzgerald"}' \
     http://localhost:8080/books
   # Expected Output: {"id":3,"title":"The Great Gatsby","author":"F. Scott Fitzgerald"}
   ```

Your Micronaut Kotlin application is now connected to your Lakebase Postgres database.

## Resources

- [Micronaut Documentation](https://docs.micronaut.io/)
- [Micronaut API Reference](https://docs.micronaut.io/latest/api/)
- [Micronaut Schema Migration with Flyway](https://guides.micronaut.io/latest/micronaut-flyway-maven-java.html)
- [Micronaut Data JDBC documentation](https://micronaut-projects.github.io/micronaut-data/latest/guide/index.html#jdbc)
- [Micronaut Hikari JDBC Connection Pool documentation](https://micronaut-projects.github.io/micronaut-sql/latest/guide/index.html#jdbc)
- [Flyway](https://www.red-gate.com/products/flyway/community/)

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/migrate-neon-to-lakebase.md) ---

> Summary: Step-by-step migration from Neon Serverless Postgres to Databricks Lakebase Postgres using pg_dump and pg_restore, covering the Neon-specific ownership and ACL mismatch that requires --no-owner and --no-acl flags during restore. Use this guide when moving a Neon database to Lakebase. For a lower-downtime migration, Lakebase can also subscribe to a Neon publication using logical replication. For pg_restore, use a native Postgres password role because Lakebase OAuth tokens expire approximately every hour.

# Migrate Neon to Lakebase

End-to-end migration from Neon Serverless Postgres to Databricks Lakebase Postgres

Last updated: 2026-10-21

This guide describes how to migrate a **Neon** database to **Databricks Lakebase Postgres** using **`pg_dump`** and **`pg_restore`**.

**Note: Logical replication**

If you need to keep downtime low, you can migrate with logical replication instead. Lakebase can subscribe to a publication on your Neon database, copy the existing data, and keep it current until you cut over. See [Replicate data from Neon to Lakebase Postgres on Databricks](https://neon.com/docs/guides/logical-replication-neon-to-lakebase).

To replicate data from Neon to the **Databricks Lakehouse** instead, see [Replicate data to Databricks with Lakeflow Connect](https://neon.com/docs/guides/logical-replication-databricks).

## Prerequisites

- A Neon **source** project with the database you are migrating.
- A Databricks account with permission to create **Lakebase** resources in the target region.
- **Postgres major versions** aligned when possible between Neon and Lakebase.
- `pg_dump` and `pg_restore` on a **stable** machine. For install instructions, see [Backups with pg_dump](https://neon.com/docs/manage/backup-pg-dump).

**Important:** Lakebase **OAuth** database tokens expire about every hour ([OAuth token authentication](https://docs.databricks.com/aws/en/oltp/projects/authentication#oauth-token-authentication)), so for **`pg_restore`** use a **native Postgres password role** and the connection string from the **Connect** modal (the URI includes the password).

## Plan the migration

- **Verify Lakebase supports what you need.** Migration assumes Lakebase can run your workload. See **[Lakebase Postgres](https://docs.databricks.com/aws/en/oltp)** for product scope, regions, and operations.
- **Extensions.** On Neon, list installed extensions (for example run `SELECT * FROM pg_extension;`). Compare each one to **[Postgres extensions](https://docs.databricks.com/aws/en/oltp/projects/extensions)** on Databricks. If an extension you depend on is not available on Lakebase, plan an alternative.

## Create a Lakebase project and get a connection string

1. Create a **Lakebase Postgres** project and the target **database**. See [Lakebase Postgres](https://docs.databricks.com/aws/en/oltp).
2. Add a **native Postgres password role** for restore. See [Create Postgres roles](https://docs.databricks.com/aws/en/oltp/projects/postgres-roles).
3. Open the **Connect** modal, select that role, and copy the connection string for use with **pg_restore**. See [Connect to your database](https://docs.databricks.com/aws/en/oltp/projects/connect).

## Export data from Neon

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

Dump your Neon database with **`pg_dump`**.

1. In the Neon Console, open your project and click **Connect**. Turn **Connection pooling** to **off** and copy the connection string.
2. Run:

```bash
pg_dump -Fc -v -d "<neon_connection_string>" -f neon-export.dump
```

See [Backups with pg_dump](https://neon.com/docs/manage/backup-pg-dump) for the full procedure and flags.

## Restore into Lakebase

Use the **Lakebase connection string** you copied from **Connect** for your password role as the **`pg_restore`** target.

Neon dumps include **ownership** and **privileges** for Neon-specific roles (for example `neondb_owner`, `neon_superuser`, roles used in `ALTER DEFAULT PRIVILEGES`). Those roles do not exist on Lakebase, so a plain `pg_restore` often errors on `ALTER ... OWNER TO ...` and default-privilege grants. That does not mean your tables and data failed to restore; it means ownership and ACL replay could not be applied.

Use **`--no-owner`** so objects are created as the user you connect with, and **`--no-acl`** (or **`-x`**) so Neon-specific `GRANT` / `ALTER DEFAULT PRIVILEGES` statements are skipped. You can grant privileges on Lakebase afterward if your security model needs it.

```bash
pg_restore -v --no-owner --no-acl -d "postgresql://user:password@host/dbname?sslmode=require" neon-export.dump
```

For more on ownership when moving between providers, see [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations) in **Migrate data from Postgres**.

## Decommission Neon (optional)

After you have **tested** the Lakebase database (for example with queries and application checks), **cut over** your apps to Lakebase, and confirmed that everything behaves as expected, you can delete the Neon project if you no longer need it. See [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

## Related docs

**Neon**

- [Region migration](https://neon.com/docs/import/region-migration)
- [Replicate data from Neon to Lakebase Postgres on Databricks](https://neon.com/docs/guides/logical-replication-neon-to-lakebase)
- [Migrate data from Postgres](https://neon.com/docs/import/migrate-from-postgres)

**Databricks Lakebase**

- [Lakebase Postgres](https://docs.databricks.com/aws/en/oltp)
- [Authentication overview](https://docs.databricks.com/aws/en/oltp/projects/authentication)
- [Create Postgres roles](https://docs.databricks.com/aws/en/oltp/projects/postgres-roles)
- [Postgres compatibility](https://docs.databricks.com/aws/en/oltp/projects/compatibility)
- [Postgres extensions](https://docs.databricks.com/aws/en/oltp/projects/extensions)
- [Connect to your database](https://docs.databricks.com/aws/en/oltp/projects/connect)
- [Authenticate to a database instance](https://docs.databricks.com/aws/en/oltp/instances/authentication)

--- [Document source](https://neon.com/docs/guides/multitenancy.md) ---

> Summary: Neon's project-per-user model gives each tenant a dedicated Neon project with independent compute, per-customer point-in-time recovery, and near-instant provisioning through the Neon API. This provides instance-level isolation without the DevOps overhead of managing individual RDS instances. Choose this approach over shared-schema or schema-per-user designs when complete data isolation, regional compliance, or independent PITR per tenant is required. Also covers catalog database design, automated cross-project schema migrations with Drizzle ORM and GitHub Actions, and scheduled pg_dump backups to AWS S3.

# Multitenancy with Neon

How to configure Neon for multitenancy - plus a few design tips

Last updated: 2026-08-27

With its serverless and API-first nature, Neon is an excellent choice for building database-per-user applications (or apps where each user/customer has their own Postgres database). Neon is particularly well-suited for architectures that prioritize maximum database isolation, achieving the equivalent of instance-level isolation.

This guide will help you get started with implementing this architecture.

## Multitenant architectures in Postgres

In a multitenant architecture, a single system supports multiple users (tenants), each with access to manage their own data. In a database like Postgres, this setup requires careful structuring to keep each tenant's data private, secure, and isolated, all while remaining efficient to manage and scale.

Following these principles, there are three primary routes you could follow to implement multitenant architectures in Postgres:

- Creating one separate database per user (the focus of this guide);
- Creating one schema-per-user, within the same database;
- And keeping your tenants separate within a shared schema.

To better situate our use case, let's briefly outline the differences between these architectures:

### Database-per-user

![Database-per-user](https://neon.com/docs/guides/multitenancy/database_per_user.png)

In a database-per-user design, each user's data is fully isolated in its own database, eliminating any risk of data overlap. This setup is straightforward to design and highly secure. However, implementing this in managed Postgres databases has traditionally been challenging. For users of AWS RDS or similar services, two primary options have existed for achieving a database-per-user design:

1. **Using one large instance to host multiple user databases.** This option can be tempting due to the reduced number of instances to manage and (probably) lower infrastructure costs. But the trade-off is a higher demand for DBA expertise; this is a design that requires careful planning, especially at scale. Hosting all users on shared resources can impact performance, particularly if users have varying workload patterns, and if the instance fails, all customers are affected. Migrations and upgrades also become complex.

2. **Handling multiple instances, each hosting a single production database.** In this scenario, each instance scales independently, preventing resource competition between users and minimizing the risk of widespread failures. This is a much simpler design from the perspective of the database layer, but managing hundreds of instances in AWS can get very costly and complex. As the number of instances grows into the thousands, management becomes nearly impossible.

As we'll see later throughout this guide, Neon offers a third alternative by providing a logical equivalent to the instance-per-customer model with near-infinite scalability, without the heavy DevOps overhead. This solution involves creating one Neon project per customer.

### Schema-per-user

![Schema-per-user](https://neon.com/docs/guides/multitenancy/schema_per_user.png)

But before focusing on database-per-user, let's briefly cover another multitenancy approach in Postgres: the schema-per-user model. Instead of isolating data by database, this design places all users in a single database, with a unique schema for each.

In Neon, we generally don't recommend this approach for SaaS applications, unless this is a design you're already experienced with. This approach doesn't reduce operational complexity or costs if compared to the many-databases approach, but it does introduce additional risks; it also limits the potential of Neon features like instant Point-in-Time Recovery (PITR), which in a project-per-customer model allows you to restore customer databases independently without impacting the entire fleet's operations. More about this later.

### Shared schema

![Shared schema](https://neon.com/docs/guides/multitenancy/shared_schema.png)

Lastly, Postgres's robustness actually makes it possible to ensure tenant isolation within a shared schema. In this model, all users' data resides within the same tables, with isolation enforced through foreign keys and row-level security.

While this is a common choice (and can be a good starting point if you're just beginning to build your app), we still recommend the project-per-user route if possible. Over time, as your app scales, meeting requirements within a shared schema setup becomes increasingly challenging. Enforcing compliance and managing access restrictions at the schema level grows more complex as you add more users.

You'll also need to manage very large Postgres tables, as all customer data is stored in the same tables. As these tables grow, additional Postgres fine-tuning will be required to maintain performance.

## Setting up Neon for Database-per-user

Now that we've reviewed your options, let's focus on the design choice we recommend for multitenancy in Neon: creating isolated databases for each user, with each database hosted on its own project.

### Database-per-user = Project-per-user

![Project per user](https://neon.com/docs/guides/multitenancy/project_per_user.png)

We recommend setting up one project per user, rather than, for example, using a branch per customer. A Neon [project](https://neon.com/docs/concepts/the-object-model) serves as the logical equivalent of an "instance" but without the management overhead. Here's why we suggest this design:

- **Straightforward scalability**  
  Instead of learning how to handle large Postgres databases, this model allows you to simply create a new project when a user joins, something that can be handled automatically via the Neon API. This approach is very cost-effective, as we'll see below. Databases remain small, keeping management at the database level simple.

- **Better performance with lower costs**  
  This design is also highly efficient in terms of compute usage. Each project has its own dedicated compute, which scales up and down independently per customer; a spike in usage for one tenant doesn't affect others, and inactive projects remain practically free.

- **Complete data isolation**  
  By creating a dedicated project for each customer, their data remains completely separate from others, ensuring the highest level of security and privacy.

- **Easier regional compliance**  
  Each Neon project can be deployed in a specific region, making it easy to host customer data closer to their location.

- **Per-customer PITR**  
  Setting up a project per customer allows you to run [PITR on individual customers](https://neon.com/docs/guides/branch-restore) instantly, without risking disruption to your entire fleet.

## Managing many projects

As you scale, following a project-per-user design means eventually managing thousands of Neon projects. This might sound overwhelming, but it's much simpler in practice than it seems; some Neon users [manage hundreds of thousands of projects](https://neon.com/blog/how-retool-uses-retool-and-the-neon-api-to-manage-300k-postgres-databases) with just one engineer. Here's why that's possible:

- **You can manage everything with the Neon API**  
  The API allows you to automate every step of project management, including setting resource limits per customer and configuring resources.

- **No infrastructure provisioning**  
  New Neon projects are ready in milliseconds. You can set things up to create new projects instantly when new customers join, without the need to manually pre-provision instances.

- **You only pay for active projects**  
  Empty projects are virtually free thanks to Neon's [scale-to-zero](https://neon.com/docs/guides/auto-suspend-guide) feature. If, on a given day, you have a few hundred projects that were only active for a few minutes, that's fine; your bill won't suffer.

- **Subscription plans**  
  To support this usage pattern, our paid plans include a generous number of projects.

### Dev/test environments

In Neon, [database branching](https://neon.com/docs/introduction/branching) lets you create fast, isolated copies of your data for development and testing. You can use child branches as ephemeral environments that mirror your main testing database but operate independently, without adding to storage costs. This feature is a game-changer for dev/test workflows, as it reduces the complexity of managing multiple test databases while lowering non-prod costs significantly.

To handle [dev/test](https://neon.com/use-cases/dev-test) in a project-per-user design, consider creating a dedicated Neon project as your non-prod environment. This Neon project can serve as a substitute for the numerous non-prod instances you might maintain in RDS.

The methodology:

- **Within the non-prod project, load your testing data into the production branch.** This production branch will serve as the primary source for all dev/test environments.
- **Create ephemeral environments via child branches.** For each ephemeral environment, create a child branch from the production branch. These branches are fully isolated in terms of resources and come with an up-to-date copy of your testing dataset.
- **Automate the process.** Use CI/CD and automations to streamline your workflow. You can reset child branches with one click to keep them in sync with the production branch as needed, maintaining data consistency across your dev/test environments.

## Designing a Control Plane

Once you have everything set up, as your number of projects grows, you might want to create a control plane to stay on top of everything in a centralized manner.

### The catalog database

![catalog database](https://neon.com/docs/guides/multitenancy/catalog_database.png)

The catalog database is a centralized repository that tracks and manages all Neon projects and databases. It holds records for every Neon project your system creates. You can also use it to keep track of tenant-specific configurations, such as database names, regions, schema versions, and so on.

You can set up your catalog database as a separate Neon project. When it's time to design its schema, consider these tips:

- Use foreign keys to link tables like `project` and `payment` to `customer`.
- Choose data types carefully: `citext` for case-insensitive text, `uuid` for unique identifiers to obscure sequence data, and `timestamptz` for tracking real-world time.
- Track key operational data, like `schema_version`, in the `project` table.
- Index wisely! While the catalog will likely remain smaller than user databases, it will grow, especially with recurring events like payments, so indexing is crucial for control plane performance at scale.
- Start with essential data fields and plan for future extensions as needs evolve.
- Standard Neon metadata (for example, compute size, branch info) is accessible via the console. Avoid duplicating it in the catalog database unless separate access adds significant complexity.

### Automations

To effectively scale a multitenant architecture, leveraging automation tools is essential. The Neon API will allow you to automate various tasks, such as creating and managing projects, setting usage limits, and configuring resources. Beyond the API, Neon offers several integrations to streamline your workflows:

- **GitHub Actions**  
  Neon's [GitHub integration](https://neon.com/docs/guides/neon-github-integration) allows you to automate database branching workflows directly from your repositories. By connecting a Neon project to a GitHub repository, you can set up actions that create or delete database branches in response to pull request events, facilitating isolated testing environments for each feature or bug fix.

- **Vercel Integration**  
  You can [connect your Vercel projects to Neon](https://neon.com/docs/guides/neon-github-integration), creating database branches for each preview deployment.

- **CI/CD pipelines**  
  By combining Neon branching into your CI/CD, you can simplify your dev/test workflows by creating and deleting ephemeral environments automatically as child branches.

- **Automated backups to your own S3**  
  If you must keep your own data copy, you can [schedule regular backups](https://neon.com/docs/manage/backups-aws-s3-backup-part-2) using tools like `pg_dump` in conjunction with GitHub Actions.

## The Application Layer

Although the application layer isn't our main focus, a common question developers ask us when approaching a multitenant architecture is: _Do I deploy one application environment per database, or connect all databases to a single application environment?_

Both approaches are viable, each with its own pros and cons.

### Shared application environments

![shared application environments](https://neon.com/docs/guides/multitenancy/shared_application_environments.png)

#### Pros of shared environments

- Managing a single application instance minimizes operational complexity.
- Updates and new features are easy to implement since changes apply universally.
- Operating one environment reduces infrastructure and maintenance costs.

#### Cons of shared environments

- A single application environment makes it difficult to offer tailored experiences for individual customers.
- Compliance becomes challenging when users' databases span multiple regions.
- Updates apply to all users simultaneously, which can be problematic for those needing specific software versions.
- A single environment heightens the risk of data breaches, as vulnerabilities can impact all users.

#### Advice

- **Implement robust authorization**  
  Ensure secure access as all users share the same application environment.

- **Define user authentication and data routing**
  - Users provide their organization details during login.
  - Users access the application via an organization-specific subdomain.
  - The system identifies the user's organization based on their credentials.

- **Monitor usage and performance**  
  Regularly track application usage to prevent performance bottlenecks.

- **Plan maintenance windows carefully**  
  Minimize disruptions for all users by scheduling maintenance during low-usage periods.

### Isolated application environments

![isolated application environments](https://neon.com/docs/guides/multitenancy/isolated_application_environments.png)

In this architecture, each customer has instead a dedicated application environment alongside their own database. Similar to the shared environment option, this design has pros and cons:

#### Pros of isolated environments

- Since each customer can now have a unique application environment, it's easier to implement personalized features and configurations, to keep separate versions for particular customers, and so on.
- Compliance is also simpler if you're handling multiple regions. Deploying the application in multiple regions can also help with latency.
- This design also opens the door for customers to control their own upgrade schedules, for example, via defining their own maintenance windows.

#### Cons of isolated environments

- This design has an obvious tradeoff: it comes with higher complexity of deployment, monitoring, and maintenance.
- You'll need to think about how to route optimal resource utilization across multiple environments, and how to keep observability on-point to diagnose issues.
- Operating separate environments for each customer might also lead to higher costs.

#### Advice

If you decide to implement isolated environments, here's some advice to consider:

- Design your architecture to accommodate growth, even if your setup is small today.
- Similarly as you're doing with Neon projects, take advantage of automation tools to streamline the creation and management of your application environments.
- Set up proper monitoring to track key metrics across all environments.

## Migrating Schemas

In a database-per-user design, it is common to have the same schema for all users/databases. Any changes to the user schema will most likely be rolled out to all individual databases simultaneously. In this section, we teach you how to use DrizzleORM, GitHub Actions, the Neon API, and a couple of custom template scripts to manage many databases using the same database schema.

### Example app

To walk you through it, we've created example code [in this repository](https://github.com/PaulieScanlon/neon-database-per-tenant-drizzle). The example includes 4 Neon databases, all using Postgres 16 and all deployed to AWS us-east-1.

The schema consists of three tables, `users`, `projects` and `tasks`. You can see the schema here: [schema.ts](https://github.com/PaulieScanlon/neon-database-per-tenant-drizzle/blob/main/src/db/schema.ts), and for good measure, here's the raw SQL equivalent: [schema.sql](https://github.com/PaulieScanlon/neon-database-per-tenant-drizzle/blob/main/schema.sql). This default schema is referenced by each of the `drizzle.config.ts` files that have been created for each customer.

### Workflow using Drizzle ORM and GitHub Actions

#### Creating Neon projects via a CLI script

Our example creates new Neon projects via the command line, using the following script:

```javascript
// src/scripts/create.js

import { Command } from 'commander';
import { createNeonClient } from '@neon/sdk';
import 'dotenv/config';

const program = new Command();
const neonApi = createNeonClient({
  apiKey: process.env.NEON_API_KEY,
  throwOnError: true,
});

program.option('-n, --name <name>', 'Name of the company').parse(process.argv);

const options = program.opts();

if (options.name) {
  console.log(`Company Name: ${options.name}`);

  (async () => {
    try {
      const project = await neonApi.projects.create({
        name: options.name,
        pg_version: 16,
        region_id: 'aws-us-east-1',
      });

      console.log(project);
    } catch (error) {
      console.error('Error creating project:', error);
    }
  })();
} else {
  console.log('No company name provided');
}
```

This script uses the `commander` library to create a simple command-line interface (CLI) and the Neon Management SDK's `neonApi.projects.create()` method to set up a new project. Ensure that your Neon API key is stored in an environment variable named `NEON_API_KEY`.

To execute the script and create a new Neon project named "ACME Corp" with PostgreSQL version 16 in the aws-us-east-1 region, run:

```bash
npm run create -- --name="ACME Corp"
```

In this example, the same approach was used to create the following projects:

- ACME Corp
- Payroll Inc
- Finance Co
- Talent Biz

To interact with the Neon API, you'll need to generate an API key. For more information, refer to the Neon documentation on [creating an API key](https://neon.com/docs/reference/api/api-keys/create-api-key).

#### Generating a workflow to prepare for migrations

```javascript
// src/scripts/generate.js

import { existsSync, mkdirSync, writeFileSync } from 'fs';
import { execSync } from 'child_process';
import { createNeonClient } from '@neon/sdk';
import { Octokit } from 'octokit';
import 'dotenv/config';

import { encryptSecret } from '../utils/encrypt-secret.js';
import { drizzleConfig } from '../templates/drizzle-config.js';
import { githubWorkflow } from '../templates/github-workflow.js';

const octokit = new Octokit({ auth: process.env.PERSONAL_ACCESS_TOKEN });
const neonApi = createNeonClient({
  apiKey: process.env.NEON_API_KEY,
  throwOnError: true,
});

const repoOwner = 'neondatabase-labs';
const repoName = 'neon-database-per-tenant-drizzle';
let secrets = [];

(async () => {
  // Ensure configs directory exists
  if (!existsSync('./configs')) {
    mkdirSync('./configs');
  }

  // Ensure .github/workflows directory exists
  if (!existsSync('./.github/workflows')) {
    mkdirSync('./.github/workflows', { recursive: true });
  }

  try {
    // Get all projects
    const projects = await neonApi.projects.list().all();

    // Loop through each project
    for (const project of projects) {
      // Get connection details for the project
      const connectionString = await neonApi.postgres.connectionString({
        projectId: project.id,
        branchId: project.default_branch_id,
        databaseName: 'neondb',
        roleName: 'neondb_owner',
      });

      // Create a drizzle config file for each project
      const configFileName = `${project.name.toLowerCase().replace(/\s+/g, '-')}.config.ts`;
      writeFileSync(`./configs/${configFileName}`, drizzleConfig(connectionString, project.name));

      // Create a GitHub workflow file for each project
      const workflowFileName = `${project.name.toLowerCase().replace(/\s+/g, '-')}.yml`;
      writeFileSync(
        `./.github/workflows/${workflowFileName}`,
        githubWorkflow(project.name, configFileName)
      );

      // Encrypt the connection string for GitHub Actions
      const publicKey = await octokit.request(
        'GET /repos/{owner}/{repo}/actions/secrets/public-key',
        {
          owner: repoOwner,
          repo: repoName,
        }
      );

      const secretName = `${project.name.toUpperCase().replace(/\s+/g, '_')}_CONNECTION_STRING`;
      const encryptedValue = await encryptSecret(connectionString, publicKey.data.key);

      secrets.push({
        secret_name: secretName,
        encrypted_value: encryptedValue,
        key_id: publicKey.data.key_id,
      });
    }

    // Output instructions for setting up GitHub secrets
    console.log('Generated config files and workflows for all projects.');
    console.log('\nTo set up GitHub secrets, run the following commands:');

    for (const secret of secrets) {
      console.log(`\nnpx octokit request PUT /repos/${repoOwner}/${repoName}/actions/secrets/${secret.secret_name} \\
  -H "Accept: application/vnd.github.v3+json" \\
  -f encrypted_value="${secret.encrypted_value}" \\
  -f key_id="${secret.key_id}"`);
    }
  } catch (error) {
    console.error('Error generating files:', error);
  }
})();
```

This script automates the setup process for managing multiple Neon databases. It:

1. Retrieves all Neon projects using the Neon API.
2. For each project, it generates a Drizzle configuration file with the appropriate connection string.
3. Creates a GitHub workflow file for each project to handle schema migrations.
4. Encrypts the connection strings for secure storage as GitHub secrets.
5. Outputs instructions for setting up the required GitHub secrets.

The script uses template files for the Drizzle configuration and GitHub workflow, which are defined in separate modules:

```javascript
// src/templates/drizzle-config.js

export const drizzleConfig = (connectionString, projectName) => {
  return `import type { Config } from 'drizzle-kit';

export default {
  schema: './src/db/schema.ts',
  out: './drizzle',
  driver: 'pg',
  dbCredentials: {
    connectionString: process.env.${projectName.toUpperCase().replace(/\s+/g, '_')}_CONNECTION_STRING || '${connectionString}',
  },
  verbose: true,
  strict: true,
} satisfies Config;
`;
};
```

```javascript
// src/templates/github-workflow.js

export const githubWorkflow = (projectName, configFileName) => {
  const secretName = projectName.toUpperCase().replace(/\s+/g, '_');
  const jobName = projectName.toLowerCase().replace(/\s+/g, '-');

  return `name: ${projectName} DB Migration

on:
  push:
    branches:
      - main
    paths:
      - 'src/db/schema.ts'
  workflow_dispatch:

jobs:
  migrate-${jobName}:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run migration
        env:
          ${secretName}_CONNECTION_STRING: \${{ secrets.${secretName}_CONNECTION_STRING }}
        run: npx drizzle-kit push:pg --config=./configs/${configFileName}
`;
};
```

The encryption utility for GitHub secrets is implemented as follows:

```javascript
// src/utils/encrypt-secret.js

import { createPublicKey, publicEncrypt } from 'crypto';
import { Buffer } from 'buffer';

export const encryptSecret = async (secret, publicKeyString) => {
  const publicKey = createPublicKey({
    key: Buffer.from(publicKeyString, 'base64'),
    format: 'der',
    type: 'spki',
  });

  const encryptedSecret = publicEncrypt(
    {
      key: publicKey,
      padding: 1, // RSA_PKCS1_PADDING
    },
    Buffer.from(secret)
  );

  return encryptedSecret.toString('base64');
};
```

To generate the configuration files and GitHub workflows for all your Neon projects, run:

```bash
npm run generate
```

This will create:

1. A Drizzle configuration file for each project in the `configs` directory.
2. A GitHub workflow file for each project in the `.github/workflows` directory.
3. Instructions for setting up the required GitHub secrets.

#### Running migrations

Once everything is set up, you can run migrations manually for a specific project using:

```bash
npx drizzle-kit push:pg --config=./configs/acme-corp.config.ts
```

Or, if you've set up the GitHub workflows as described, migrations will automatically run whenever you push changes to the `src/db/schema.ts` file on the main branch.

### S3 Backups

In addition to managing schemas, you might want to set up regular backups of your databases. This section explains how to configure AWS IAM roles and policies for GitHub Actions to securely access S3 for backing up your Neon databases.

#### AWS IAM configuration

First, GitHub must be added as an identity provider to allow the Action to use your AWS credentials. To create a new Identity Provider, navigate to IAM > Access Management > Identity Providers, and click Add provider.

![S3 backup IAM configuration](https://neon.com/docs/guides/multitenancy/s3_backup_iam_config.png)

On the next screen select OpenID Connect and add the following to the Provider URL and Audience fields.

1. Provider URL: [https://token.actions.githubusercontent.com](https://token.actions.githubusercontent.com)
2. Audience: sts.amazonaws.com

Now, you must create a role, which is an identity that you can assume to obtain temporary security credentials for specific tasks or actions within AWS. Navigate to **IAM > Access Management > Roles**, and click **Create role**.

On the next screen you can create a Trusted Identity for the Role. Select **Trusted Identity**. On the next screen, select **Web Identity**, then select `token.actions.githubusercontent.com` from the **Identity Provider** dropdown menu.

![S3 backup select trusted entity](https://neon.com/docs/guides/multitenancy/s3_select_trusted_entity.png)

Once you select the Identity Provider, you'll be shown a number of fields to fill out. Select `sts.amazonaws.com` from the **Audience** dropdown menu, then fill out the GitHub repository details as per your requirements. When you're ready, click **Next**. For reference, the options shown in the image below are for this repository.

![S3 backup web identity](https://neon.com/docs/guides/multitenancy/s3_web_identity.png)

You can skip selecting anything from the Add Permissions screen and click **Next** to continue.

On this screen give the **Role** a name and description. You'll use the Role name in the code for the GitHub Action. When you're ready click **Create role**.

Now you need to create a policy for the role. Navigate to **IAM > Access Management > Policies**, and click **Create policy**.

On the next screen, select the **JSON** tab and paste the following policy. This policy allows the role to list, get, put, and delete objects in the specified S3 bucket. Replace `your-bucket-name` with the name of your S3 bucket.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["s3:ListBucket"],
      "Resource": ["arn:aws:s3:::your-bucket-name"]
    },
    {
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::your-bucket-name/*"]
    }
  ]
}
```

Click **Next** and give the policy a name and description. When you're ready, click **Create policy**.

Now you need to attach the policy to the role. Navigate to **IAM > Access Management > Roles**, and click on the role you created earlier. Click **Add permissions**, then **Attach policies**. Search for the policy you just created, select it, and click **Add permissions**.

#### GitHub secrets

You'll need to add the following secrets to your GitHub repository:

- `AWS_ACCOUNT_ID`: Your AWS account ID
- `IAM_ROLE`: In my case this would be, neon-multiple-db-s3-backups-github-action

### Scheduled pg_dump/restore GitHub Action

Before diving into the code, here's a look at this example in the Neon console dashboard. There are three databases set up for three fictional customers, all running Postgres 16 and all are deployed to us-east-1. We will be backing up each database into its own folder within an S3 bucket, with different schedules and retention periods. All the code in this example lives [in this repository](https://github.com/neondatabase-labs/neon-multiple-db-s3-backups).

![S3 backup three databases](https://neon.com/docs/guides/multitenancy/s3_backup_three_databases.png)

Using the same naming conventions, there are three new files in the `.github/workflows` folder in the repository:

1. `paycorp-payments-prod.yml`
2. `acme-analytics-prod.yml`
3. `paycorp-payments-prod.yml`

All the Actions are technically the same, (besides the name of the file), but there are several areas where they differ.

These are:

1. The workflow name
2. The `DATABASE_URL`
3. The `RETENTION` period

For example, in the first `.yml` file, the workflow name is `acme-analytics-prod`, the `DATABASE_URL` points to `secrets.ACME_ANALYTICS_PROD`, and the `RETENTION` period is 7 days.

Here's the full Action, and below the code snippet, we'll explain how it all works.

```yaml
// .github/workflows/acme-analytics-prod.yml

name: acme-analytics-prod

on:
  schedule:
    - cron: '0 0 * * *' # Runs at midnight UTC
  workflow_dispatch:

jobs:
  db-backup:
    runs-on: ubuntu-latest

    permissions:
      id-token: write

    env:
      RETENTION: 7
      DATABASE_URL: ${{ secrets.ACME_ANALYTICS_PROD }}

      IAM_ROLE: ${{ secrets.IAM_ROLE }}
      AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
      S3_BUCKET_NAME: ${{ secrets.S3_BUCKET_NAME }}
      AWS_REGION: 'us-east-1'
      PG_VERSION: '16'

    steps:
      - name: Install PostgreSQL
        run: |
          sudo apt install -y postgresql-common
          yes '' | sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
          sudo apt install -y postgresql-${{ env.PG_VERSION }}

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT_ID }}:role/${{ env.IAM_ROLE }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Set file, folder and path variables
        run: |
          GZIP_NAME="$(date +'%B-%d-%Y@%H:%M:%S').gz"
          FOLDER_NAME="${{ github.workflow }}"
          UPLOAD_PATH="s3://${{ env.S3_BUCKET_NAME }}/${FOLDER_NAME}/${GZIP_NAME}"

          echo "GZIP_NAME=${GZIP_NAME}" >> $GITHUB_ENV
          echo "FOLDER_NAME=${FOLDER_NAME}" >> $GITHUB_ENV
          echo "UPLOAD_PATH=${UPLOAD_PATH}" >> $GITHUB_ENV

      - name: Create folder if it doesn't exist
        run: |
          if ! aws s3api head-object --bucket ${{ env.S3_BUCKET_NAME }} --key "${{ env.FOLDER_NAME }}/" 2>/dev/null; then
            aws s3api put-object --bucket ${{ env.S3_BUCKET_NAME }} --key "${{ env.FOLDER_NAME }}/"
          fi

      - name: Run pg_dump
        run: |
          /usr/lib/postgresql/${{ env.PG_VERSION }}/bin/pg_dump ${{ env.DATABASE_URL }} | gzip > "${{ env.GZIP_NAME }}"

      - name: Empty bucket of old files
        run: |
          THRESHOLD_DATE=$(date -d "-${{ env.RETENTION }} days" +%Y-%m-%dT%H:%M:%SZ)
          aws s3api list-objects --bucket ${{ env.S3_BUCKET_NAME }} --prefix "${{ env.FOLDER_NAME }}/" --query "Contents[?LastModified<'${THRESHOLD_DATE}'] | [?ends_with(Key, '.gz')].{Key: Key}" --output text | while read -r file; do
            aws s3 rm "s3://${{ env.S3_BUCKET_NAME }}/${file}"
          done

      - name: Upload to bucket
        run: |
          aws s3 cp "${{ env.GZIP_NAME }}" "${{ env.UPLOAD_PATH }}" --region ${{ env.AWS_REGION }}
```

Starting from the top, there are a few configuration options:

#### Action configuration

```yaml
name: acme-analytics-prod

on:
  schedule:
    - cron: '0 0 * * *' # Runs at midnight UTC
  workflow_dispatch:
```

- `name`: This is the workflow name and will also be used when creating the folder in the S3 bucket.
- `cron`: This determines how often the Action will run, take a look a the GitHub docs where the [POSIX cron syntax](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) is explained.

#### Environment variables

```yaml
env:
  RETENTION: 7
  DATABASE_URL: ${{ secrets.ACME_ANALYTICS_PROD }}

  IAM_ROLE: ${{ secrets.IAM_ROLE }}
  AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
  S3_BUCKET_NAME: ${{ secrets.S3_BUCKET_NAME }}
  AWS_REGION: 'us-east-1'
  PG_VERSION: '16'
```

- `RETENTION`: This determines how long a backup file should remain in the S3 bucket before it's deleted.
- `DATABASE_URL`: This is the Lakebase Postgres connection string for the database you're backing up.
- `IAM_ROLE`: This is the name of the AWS IAM Role.
- `AWS_ACCOUNT_ID`: This is your AWS Account ID.
- `S3_BUCKET_NAME`: This is the name of the S3 bucket where all backups are being stored.
- `AWS_REGION`: This is the region where the S3 bucket is deployed.
- `PG_VERSION`: This is the version of Postgres to install.

#### GitHub Secrets

As we mentioned above, several of the above environment variables are defined using secrets. These variables can be added to **Settings > Secrets and variables > Actions**.

Here's a screenshot of the GitHub repository secrets including the connection string for the fictional ACME Analytics Prod database.

![S3 backup three databases](https://neon.com/docs/guides/multitenancy/github_secrets.png)

#### Action steps

This step installs Postgres into the GitHub Action's virtual environment. The version to install is defined by the `PG_VERSION` environment variable.

**Install Postgres**

```yaml
- name: Install PostgreSQL
        run: |
          sudo apt install -y postgresql-common
          yes '' | sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
          sudo apt install -y postgresql-${{ env.PG_VERSION }}
```

**Configure AWS credentials**

This step configures AWS credentials within the GitHub Action virtual environment, allowing the workflow to interact with AWS services securely.

```yaml
- name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT_ID }}:role/${{ env.IAM_ROLE }}
          aws-region: ${{ env.AWS_REGION }}
```

**Set file, folder and path variables**

In this step I've created three variables that are all output to `GITHUB_ENV`. This allows me to access the values from other steps in the Action.

```yaml
     - name: Set file, folder and path variables
        run: |
          GZIP_NAME="$(date +'%B-%d-%Y@%H:%M:%S').gz"
          FOLDER_NAME="${{ github.workflow }}"
          UPLOAD_PATH="s3://${{ env.S3_BUCKET_NAME }}/${FOLDER_NAME}/${GZIP_NAME}"

          echo "GZIP_NAME=${GZIP_NAME}" >> $GITHUB_ENV
          echo "FOLDER_NAME=${FOLDER_NAME}" >> $GITHUB_ENV
          echo "UPLOAD_PATH=${UPLOAD_PATH}" >> $GITHUB_ENV
```

The three variables are as follows:

1. `GZIP_NAME`: The name of the `.gz` file derived from the date which would produce a file name similar to, `October-21-2024@07:53:02.gz`
2. `FOLDER_NAME`: The folder where the `.gz` files are to be uploaded
3. `UPLOAD_PATH`: This is the full path that includes the S3 bucket name, folder name and `.gz` file

**Create folder if it doesn't exist**

This step creates a new folder (if one doesn't already exist) inside the S3 bucket using the `FOLDER_NAME` as defined in the previous step.

## Final remarks

You can create as many of these Actions as you need. Just be careful to double check the `DATABASE_URL` to avoid backing up a database to the wrong folder.

**Important:** GitHub Actions will timeout after ~6 hours. The size of your database and how you've configured it will determine how long the `pg_dump` step takes. If you do experience timeout issues, you can self host [GitHub Action runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners).

--- [Document source](https://neon.com/docs/guides/neon-github-integration.md) ---

> Summary: The Neon GitHub integration connects a Lakebase Postgres project on Neon to a GitHub repository by installing a GitHub App that stores a NEON_API_KEY secret and NEON_PROJECT_ID variable in the repo. GitHub Actions workflows use these to create a database branch when a pull request opens and delete it on close. Choose this page to install the integration, add the sample branching workflow, or build custom workflows with the create-branch, delete-branch, schema-diff, and reset-branch actions. Also covers disconnecting a project, removing the integration, and example apps for Vercel, Cloudflare Pages, and Fly.io preview deployments.

# The Neon GitHub integration

Connect Lakebase Postgres on Neon to a GitHub repository and build GitHub Actions workflows

Last updated: 2026-08-04

The Neon GitHub integration connects your Neon project to a GitHub repository, streamlining database development within your overall application development workflow. For instance, you can configure GitHub Actions to create a database branch for each pull request and automatically apply schema changes to that database branch. To help you get started, we provide a [sample GitHub Actions workflow](https://neon.com/docs/guides/neon-github-integration#add-the-github-actions-workflow-to-your-repository).

## How it works

The integration installs the GitHub App, letting you select which repositories you want to make accessible to Neon. When you connect a Neon project to a GitHub repository, the integration sets a Neon API key secret and Neon project ID variable in your repository, which are used by your GitHub Actions workflow to interact with your Neon project.

**Note:** The [sample GitHub Actions workflow](https://neon.com/docs/guides/neon-github-integration#add-the-github-actions-workflow-to-your-repository) we provide is intended as a basic template you can expand on or customize to build your own workflows.

This guide walks you through the following steps:

- Installing the GitHub App
- Connecting a Neon project to a GitHub repository
- Adding the sample GitHub Actions workflow to your repository

## Prerequisites

- You have a Neon account and project. If not, see [Sign up for a Neon account](https://neon.com/docs/get-started/signing-up).
- You have a GitHub account with an application repository that you want to connect to your Neon project.

## Install the GitHub App and connect your Neon project

To get started:

1. In the Neon Console, navigate to the **Integrations** page in your Neon project.
2. Locate the **GitHub** card and click **Add**.
   ![GitHub App card](https://neon.com/docs/guides/github_card.png)
3. On the **GitHub** drawer, click **Install GitHub App**.
4. If you have more than one GitHub account, select the account where you want to install the GitHub app.
5. Select whether to install and authorize the GitHub app for **All repositories** in your GitHub account or **Only select repositories**.
   - Selecting **All repositories** authorizes the app on all repositories in your GitHub account, meaning that you can to connect your Neon project to any of them.
   - Selecting **Only select repositories** authorizes the app on one or more repositories, meaning that you can only connect your Neon project to the selected repositories (you can authorize additional repositories later if you need to).
6. If you authorized the app on **All repositories** or multiple repositories, select a GitHub repository to connect to the current Neon project, and click **Connect**. If you authorized the GitHub app on a single GitHub repository, you have already completed this step.

   You are directed to the **Actions** tab on the final page of the setup, where a sample GitHub Actions workflow is provided. You can copy this workflow to your GitHub repository to establish a basic database branching process. For instructions, see [Add the GitHub Actions workflow to your repository](https://neon.com/docs/guides/neon-github-integration#add-the-github-actions-workflow-to-your-repository).

## Add the GitHub Actions workflow to your repository

The sample GitHub Actions workflow includes:

- A [Create branch action](https://neon.com/docs/guides/branching-github-actions#create-branch-action) that creates a new Neon branch in your Neon project when you open or reopen a pull request in the connected GitHub repository.
- Code that you can uncomment to add a database migration command to your workflow.
- Code that you can uncomment to add a [Schema diff action](https://neon.com/docs/guides/branching-github-actions#schema-diff-action) that diffs database schemas and posts the diff as a comment in your pull request.
- A [Delete branch action](https://neon.com/docs/guides/branching-github-actions#delete-branch-action) that deletes the Neon branch from your Neon project when you close the pull request.

```yaml
name: Create/Delete Branch for Pull Request

on:
  pull_request:
    types:
      - opened
      - reopened
      - synchronize
      - closed

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}

jobs:
  setup:
    name: Setup
    outputs:
      branch: ${{ steps.branch_name.outputs.current_branch }}
    runs-on: ubuntu-latest
    steps:
      - name: Get branch name
        id: branch_name
        uses: tj-actions/branch-names@v8

  create_neon_branch:
    name: Create Neon Branch
    outputs:
      db_url: ${{ steps.create_neon_branch_encode.outputs.db_url }}
      db_url_with_pooler: ${{ steps.create_neon_branch_encode.outputs.db_url_with_pooler }}
    needs: setup
    if: |
      github.event_name == 'pull_request' && (
      github.event.action == 'synchronize'
      || github.event.action == 'opened'
      || github.event.action == 'reopened')
    runs-on: ubuntu-latest
    steps:
      - name: Create Neon Branch
        id: create_neon_branch
        uses: neondatabase/create-branch-action@v5
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          branch_name: preview/pr-${{ github.event.number }}-${{ needs.setup.outputs.branch }}
          api_key: ${{ secrets.NEON_API_KEY }}

  # The step above creates a new Neon branch.
  # You may want to do something with the new branch, such as run migrations, run tests
  # on it, or send the connection details to a hosting platform environment.
  # The branch DATABASE_URL is available to you via:
  # "${{ steps.create_neon_branch.outputs.db_url_with_pooler }}".
  # It's important you don't log the DATABASE_URL as output as it contains a username and
  # password for your database.
  #
  # For example, you can uncomment the lines below to run a database migration command:
  #      - name: Run Migrations
  #        run: npm run db:migrate
  #        env:
  #          DATABASE_URL: "${{ steps.create_neon_branch.outputs.db_url_with_pooler }}"
  #
  # You can also add a Schema Diff action to compare the database schema on the new
  # branch with the base branch. This action automatically writes the schema differences
  # as a comment on your GitHub pull request, making it easy to review changes.

  # Following the step above, which runs database migrations, you may want to check
  # for schema changes in your database. We recommend using the following action to
  # post a comment to your pull request with the schema diff. For this action to work,
  # you also need to give permissions to the workflow job to be able to post comments
  # and read your repository contents. Add the following permissions to the workflow job:
  #
  # permissions:
  #   contents: read
  #   pull-requests: write
  #
  # You can also check out https://github.com/neondatabase/schema-diff-action for more
  # information on how to use the schema diff action.
  # You can uncomment the lines below to enable the schema diff action.
  #      - name: Post Schema Diff Comment to PR
  #        uses: neondatabase/schema-diff-action@v1
  #        with:
  #          project_id: \${{ vars.NEON_PROJECT_ID }}
  #          compare_branch: preview/pr-\${{ github.event.number }}-\${{ needs.setup.outputs.branch }}
  #          api_key: \${{ secrets.NEON_API_KEY }}

  delete_neon_branch:
    name: Delete Neon Branch
    needs: setup
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Delete Neon Branch
        uses: neondatabase/delete-branch-action@v3
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          branch: preview/pr-${{ github.event.number }}-${{ needs.setup.outputs.branch }}
          api_key: ${{ secrets.NEON_API_KEY }}
```

**Tip:** The step outputs from the `create_neon_branch` action will only be available within the same job (`create_neon_branch`). Therefore, write all test code, migrations, and related steps in that job itself. The outputs are marked as secrets. If you need separate jobs, refer to [GitHub's documentation on workflow commands](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#workflow) for patterns on how to handle this.

To add the workflow to your repository:

1. In your repository, create a workflow file in the `.github/workflows` directory; for example, create a file named `neon_workflow.yml`.

   - If the `.github/workflows` directory already exists, add the file.
   - If your repository doesn't have a `.github/workflows` directory, add the file `.github/workflows/neon-workflow.yml`. This creates the `.github` and `workflows` directories and the `neon-workflow.yml` file.

   If you need more help with this step, see [Creating your first workflow](https://docs.github.com/en/actions/quickstart#creating-your-first-workflow), in the _GitHub documentation_.

   **Note:** For GitHub to discover GitHub Actions workflows, you must save the workflow files in a directory called `.github/workflows` in your repository. You can name the workflow file whatever you like, but you must use `.yml` or `.yaml` as the file name extension.

2. Copy the workflow code into your `neon-workflow.yml` file.

3. Commit your changes.

### Using the GitHub Actions workflow

To use the sample workflow, create a pull request in your GitHub application repository. This will trigger the `Create Neon Branch` action. You can verify that a branch was created on the **Branches** page in the Neon Console. You should see a new branch with a `preview/pr-` name prefix.

Closing the pull request removes the Neon branch from the Neon project, which you can also verify on the **Branches** page in the Neon Console.

To view workflow results in GitHub, follow the instructions in [Viewing your workflow results](https://docs.github.com/en/actions/quickstart#viewing-your-workflow-results), in the _GitHub documentation_.

## Building your own GitHub Actions workflow

The sample workflow provided by the GitHub integration serves as a template, which you can expand on or customize. The workflow uses Neon's create branch, delete branch, and schema diff GitHub Actions, which you can find here:

- [Create a Neon Branch](https://github.com/neondatabase/create-branch-action)
- [Delete a Neon Branch](https://github.com/neondatabase/delete-branch-action)
- [Schema Diff](https://github.com/neondatabase/schema-diff-action)

Neon also offers a [Reset a Neon Branch](https://github.com/neondatabase/reset-branch-action) action that allows you to reset a database branch to match the current state of its parent branch. This action is useful in a feature-development workflow, where you may need to reset a development branch to the current state of your production branch before beginning work on a new feature.

To incorporate the reset action into your workflow, you can use code like this, tailored to your specific requirements:

```yaml
reset_neon_branch:
  name: Reset Neon Branch
  needs: setup
  if: |
    contains(github.event.pull_request.labels.*.name, 'Reset Neon Branch') &&
    github.event_name == 'pull_request' &&
    (github.event.action == 'synchronize' ||
     github.event.action == 'opened' ||
     github.event.action == 'reopened' ||
     github.event.action == 'labeled')
  runs-on: ubuntu-latest
  steps:
    - name: Reset Neon Branch
      uses: neondatabase/reset-branch-action@v1
      with:
        project_id: ${{ vars.NEON_PROJECT_ID }}
        parent: true
        branch: preview/pr-${{ github.event.number }}-${{ needs.setup.outputs.branch }}
        api_key: ${{ secrets.NEON_API_KEY }}
```

You can integrate Neon's GitHub Actions into your workflow, develop custom actions, or combine Neon's actions with those from other platforms or services.

If you're new to GitHub Actions and workflows, GitHub's [Quickstart for GitHub Actions](https://docs.github.com/en/actions/quickstart) is a good place to start.

## Example applications with GitHub Actions workflows

The following example applications use GitHub Actions workflows to create and delete branches in Neon. These examples can serve as references when building your own workflows.

**Note:** The Neon GitHub integration configures a `NEON_API_KEY` secret and a `PROJECT_ID` variable in your GitHub repository. Depending on the specific example application, additional or different variables and secrets may have been used. As you develop your workflows, you might also need to incorporate various other variables and secrets.

- [Automated Database Branching with GitHub Actions](https://neon.com/guides/neon-github-actions-authomated-branching): Learn how to automate database branching for your application using Neon and GitHub Actions
- [Preview branches with Cloudflare Pages](https://github.com/neondatabase/preview-branches-with-cloudflare): Demonstrates using GitHub Actions workflows to create a Neon branch for every Cloudflare Pages preview deployment
- [Preview branches with Vercel](https://github.com/neondatabase/preview-branches-with-vercel): Demonstrates using GitHub Actions workflows to create a Neon branch for every Vercel preview deployment
- [Preview branches with Fly.io](https://github.com/neondatabase/preview-branches-with-fly): Demonstrates using GitHub Actions workflows to create a Neon branch for every Fly.io preview deployment

## Connect more Neon projects with the GitHub App

If you've installed the GitHub app previously, it's available to use with any project in your Neon account.

To connect another Neon project to a GitHub repository:

1. In the Neon Console, navigate to the **Integrations** page in your Neon project.
2. Locate the **GitHub** integration and click **Add**.
   ![GitHub App card](https://neon.com/docs/guides/github_card.png)
3. Select a GitHub repository to connect to your Neon project, and click **Connect**.

**Note:** Connecting to the same GitHub repository from different Neon projects is not supported.

## Secret and variable set by the GitHub integration

When connecting a Neon project to a GitHub repository, the GitHub integration performs the following actions:

- Generates a Neon API key for your Neon account
- Creates a `NEON_API_KEY` secret in your GitHub repository
- Adds a `NEON_PROJECT_ID` variable to your GitHub repository

The `NEON_API_KEY` allows you to run any [Neon API](https://neon.com/docs/reference/api) method or [Neon CLI](https://neon.com/docs/cli) command, which means you can develop actions and workflows that create, update, and delete various objects in Neon such as projects, branches, databases, roles, and computes.

The `NEON_PROJECT_ID` variable defines the Neon project that is connected to the repository. Operations run on Neon via the Neon API or CLI typically require specifying the Neon project ID, as a Neon account may have more than one Neon project.

The sample GitHub Actions workflow provided by the Neon GitHub integration depends on these variables and secrets to perform actions in Neon.

**Note:** The variables and secrets are removed if you disconnect a Neon project from the associated GitHub repository. The items are removed for all Neon projects and associated repositories if you remove the Neon GitHub integration from your Neon account. See [Remove the GitHub integration](https://neon.com/docs/guides/neon-github-integration#remove-the-github-integration).

### Neon API key

To view the Neon API key created by the integration:

1. In the [Neon Console](https://console.neon.tech), click your profile at the top right corner of the page.
2. Select **Settings** (under **Account**).
3. Select **API keys**.

The API key created by the integration should be listed with a name similar to the following: **API key for GitHub (cool-darkness-12345678)**. You cannot view the key itself, only the name it was given, the time it was created, and when the key was last used.

### Neon project ID variable and Neon API key secret

To view the variable containing your Neon project ID:

1. Navigate to your GitHub account page.
2. From your GitHub profile menu, select **Your repositories**.
3. Select the repository that you chose when installing the Neon GitHub integration.
4. On the repository page, select the **Settings** tab.
5. Select **Secrets and variables** > **Actions** from the sidebar.

Your `NEON_API_KEY` secret is listed on the **Secrets** tab, and the `NEON_PROJECT_ID` variable is listed on the **Variables** tab.

## Disconnect a Neon project from a GitHub repository

Disconnecting a Neon project from a GitHub repository performs the following actions for the Neon project:

- Removes the Neon API key created for this integration from your Neon account.
- Removes the GitHub secret containing the Neon API key from the associated GitHub repository.
- Removes the GitHub variable containing your Neon project ID from the associated GitHub repository.

Any GitHub Actions workflows you've added to the GitHub repository that are dependent on these secrets and variables will no longer work.

To disconnect your Neon project:

1. In the Neon Console, navigate to the **Integrations** page for your project.
2. Locate the GitHub integration and click **Manage** to open the **GitHub integration** drawer.
3. Click **Disconnect**.

## Remove the GitHub integration

Removing the GitHub integration performs the following actions for all Neon projects that you connected to a GitHub repository using the GitHub integration:

- Removes the Neon API keys created for Neon-GitHub integrations from your Neon account.
- Removes GitHub secrets containing the Neon API keys from the associated GitHub repositories.
- Removes the GitHub variables containing your Neon project IDs from the associated GitHub repositories.

Any GitHub Actions workflows you've added to GitHub repositories that are dependent on these secrets and variables will no longer work.

To remove the GitHub integration:

1. In the Neon Console, navigate your account Profile.
2. Select **Settings** (under **Account**).
3. Select **Integrations**.
4. Click **Remove**.

## Resources

- [Creating GitHub Actions](https://docs.github.com/en/actions/creating-actions)
- [Quickstart for GitHub Actions](https://docs.github.com/en/actions/quickstart)
- [Database Branching Workflows](https://neon.com/branching)
- [Database branching workflow guide for developers](https://neon.com/blog/database-branching-workflows-a-guide-for-developers)

## Feedback and future improvements

If you've got feature requests or feedback about what you'd like to see from the Neon GitHub integration, let us know via the [Feedback](https://console.neon.tech/app/projects?modal=feedback) form in the Neon Console or our [feedback channel](https://discord.com/channels/1176467419317940276/1176788564890112042) on Discord.

--- [Document source](https://neon.com/docs/guides/neon-managed-vercel-integration.md) ---

> Summary: The Neon-Managed Vercel Integration connects an existing Neon project to a Vercel project via Connectable Accounts, keeping billing in Neon and automatically creating an isolated database branch named `preview/<git-branch>` for each Vercel preview deployment. Use this integration instead of the Vercel-Managed Integration when you already have a Neon account or need direct billing control. The two integrations cannot coexist in the same Vercel project, and each Neon project maps to exactly one Vercel project. When connecting, you can choose which Neon branch feeds Vercel's Production environment variables. The integration injects `DATABASE_URL`, `DATABASE_URL_UNPOOLED`, and legacy `PG*` variables per deployment, with optional automatic branch cleanup when Git branches are deleted.

# Connecting with the Neon-Managed Integration

Link an existing Neon project to Vercel and keep billing in Neon

Last updated: 2026-10-23

**What you will learn:**

- [The purpose of the Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration#about-this-integration)
- [How to install it from Connectable Accounts](https://neon.com/docs/guides/neon-managed-vercel-integration#installation-steps)
- [How to choose which branch feeds Vercel Production](https://neon.com/docs/guides/neon-managed-vercel-integration#choose-a-production-branch)
- [How automated Preview Branching works](https://neon.com/docs/guides/neon-managed-vercel-integration#how-preview-branching-works)
- [How to manage environment variables and branch cleanup](https://neon.com/docs/guides/neon-managed-vercel-integration#managing-the-integration)

**Related topics**

- [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration)
- [Manual Connections](https://neon.com/docs/guides/vercel-manual)

---

## About this integration

The **Neon-Managed Integration** links your existing Neon project to a Vercel project while keeping billing in Neon. Instead of sharing a single database across all preview deployments, this integration creates an isolated database branch for each preview deployment.

**Key features:**

- One-click connection from Vercel Marketplace
- Automatic database branches for each preview deployment
- Environment variable injection (`DATABASE_URL`, `DATABASE_URL_UNPOOLED`, `PG*` variables)
- Automatic cleanup when branches are deleted

**Note: Who should use this integration?**

Choose the Neon-Managed Integration if you already have a Neon account/project or prefer to manage billing directly with Neon.

---

## Prerequisites

Before you begin, ensure you have:

- A Neon account with at least one project and database role
- A Vercel account with a project linked to GitHub, GitLab, or Bitbucket

---

## Installation steps

## Connect from Neon Console

In the [Neon Console](https://console.neon.tech), navigate to **Integrations** and click **Add** under Vercel.

Click **Install from Vercel Marketplace** to open the integration in Vercel.

## Add the integration in Vercel

On the Vercel page, click **Install**.

This opens the **Install Neon** modal where you can choose between two options. Select **Link Existing Neon Account**, then click **Continue**.

![Install on Existing Neon Account](https://neon.com/docs/guides/vercel_install_neon_modal_existing_account.png)

**Tip:** Alternatively, if you're accessing this directly from the Vercel Marketplace, locate the **Connectable Accounts** section, find **Neon**, and click **Add**. This differs from the **Native Integrations** section in the Vercel Marketplace.

![Add Neon from Connectable Accounts](https://neon.com/docs/guides/vercel_add_connected_neon_account.png)

## Configure the connection

Choose which Vercel account and projects can use this integration. Each Neon project connects to exactly one Vercel project. Selecting **All projects** makes the integration available to other Vercel projects.

![Connect Neon Account Projects](https://neon.com/docs/guides/vercel_connect_neon_account_projects.png)

## Set up project integration

In the **Integrate Neon** dialog:

1. **Select your Vercel project**

   ![Select a Vercel project](https://neon.com/docs/guides/vercel_select_project.png)

2. **Choose your Neon account, project, production branch, database, and role**

   ![Connect to Neon](https://neon.com/docs/guides/vercel_connect_neon.png)

   Under **Production branch**, pick the Neon branch whose credentials Vercel should use for **Production** deployments. If you leave the default selection, Production uses your project's default branch. The read-only **Default branch** field shows the branch that preview branches are created from.

   The branch you select must:

   - Belong to the chosen Neon project
   - Include the database and role you selected
   - Not be a Vercel preview branch (for example, `preview/<git-branch>`)
   - Not have branch expiration (TTL) enabled

3. **Configure optional settings:**
   - Enable **Create a branch for your development environment** to create a persistent `vercel-dev` branch
     and set Vercel development environment variables for it. The `vercel-dev` branch is a clone of your project's default branch (`main`) that you can modify without affecting data on your default branch.
   - Enable **Automatically delete obsolete Neon branches** (recommended) to clean up branches when git branches are deleted.

4. Click **Connect**, then **Done**

![Confirm integration settings](https://neon.com/docs/guides/vercel_confirm_settings.png)

![Vercel integration success](https://neon.com/docs/guides/vercel_success.png)

### Choose a production branch

By default, Neon uses your project's **default branch** for Vercel's Production environment variables. When your live application data lives on a different branch (for example, a protected `production` branch while `main` remains the default), select that branch during setup instead.

| Vercel environment | Neon branch used                                                                                 |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| **Production**     | The branch you choose at connect (or the project default if unchanged)                           |
| **Preview**        | A new `preview/<git-branch>` branch per deployment, parented from the project **default** branch |
| **Development**    | The optional `vercel-dev` branch, created as a clone of the project **default** branch           |

Only Production credentials come from your chosen branch. Preview and Development environments are unchanged. Neon resolves that branch's read-write compute endpoint and the password for the role you selected on that branch (role passwords can differ across branches).

If [Managed Better Auth](https://neon.com/docs/auth/overview) is enabled on your production branch, Production deployments receive `NEON_AUTH_BASE_URL` and `VITE_NEON_AUTH_URL` from that branch. Preview deployments still get isolated auth on their own preview branches.

The production branch is independent of your project's default branch. If you later change the default branch, Production keeps using the branch you chose.

To change the production branch after setup, go to **Neon Console → Integrations**, click **Manage** next to **Vercel** under **Added**, and open the **Branches** tab. Select a different branch under **Production branch** and click **Save**. Changing a branch that's already set asks you to confirm first. Redeploy your production deployment in Vercel so it picks up the new branch's credentials. The branch you choose must meet the requirements listed above and have a read-write compute.

While the integration is connected, the production branch and its read-write compute can't be deleted. To delete that branch, choose a different production branch first, or disconnect the integration.

### What happens after installation

Once connected successfully, you'll see:

**In Neon Console:**

- A `vercel-dev` branch (if enabled) under **Branches**
- Future preview branches will appear here automatically

![Neon branches](https://neon.com/docs/guides/vercel_neon_branches.png)

**In Vercel:**

- `DATABASE_URL` and other environment variables under **Settings → Environment Variables**

![Vercel environment variables](https://neon.com/docs/guides/vercel_env_variables.png)

---

## How Preview Branching works

The integration automatically creates isolated database environments for each preview deployment:

**Tip: Managed Better Auth support for preview deployments**

If you've enabled [Managed Better Auth](https://neon.com/docs/auth/overview) on your production branch, it's automatically provisioned on preview branches too. Preview deployments receive `NEON_AUTH_BASE_URL` and `VITE_NEON_AUTH_URL` environment variables, letting you test authentication in isolated environments. Auth data branches with your database, so each preview has its own independent user profiles and sessions. Preview branches are always parented from your project's **default branch**, even when Production uses a different branch.

## Developer pushes to feature branch

When you push commits to a feature branch, Vercel triggers a preview deployment.

## Integration creates Neon branch

The integration receives a webhook from Vercel and creates a new Neon branch named `preview/<git-branch>` using the Neon API.

## Environment variables injected

Vercel receives the new connection string and injects it as environment variables for that specific deployment only.

This isolation allows you to test data and schema changes safely in each pull request. To apply schema changes automatically, add migration commands to your Vercel build configuration:

1. Go to **Vercel Dashboard → Settings → Build and Deployment Settings**
2. Enable **Override** and add your build commands, including migrations, for example:
   ```bash
   npx prisma generate && npx prisma migrate deploy && npm run build
   ```

This ensures schema changes in your commits are applied to each preview deployment's database branch.

![Vercel build commands](https://neon.com/docs/guides/vercel_build_command.png)

![Neon preview deployment branch](https://neon.com/docs/guides/vercel_deployments.png)

![Neon preview deployment branch](https://neon.com/docs/guides/vercel_neon_app_update.png)

![Vercel preview settings](https://neon.com/docs/guides/vercel_preview_settings.png)

---

## Managing the integration

### Environment variables

By default, the integration sets `DATABASE_URL` and `DATABASE_URL_UNPOOLED` for Production and Development environments. You can also select `PGHOST`, `PGHOST_UNPOOLED`, `PGUSER`, `PGDATABASE`, and `PGPASSWORD`. Preview variables are injected dynamically per deployment.

- `DATABASE_URL`: Pooled connection (recommended for most applications). For Production, sourced from the [production branch you chose at connect](https://neon.com/docs/guides/neon-managed-vercel-integration#choose-a-production-branch).
- `DATABASE_URL_UNPOOLED`: Direct connection (for tools requiring direct database access)
- `NEON_AUTH_BASE_URL`, `VITE_NEON_AUTH_URL`: Managed Better Auth endpoints. For Production, the values come from your production branch. You can select these variables on the **Settings** tab once Managed Better Auth is enabled on your production branch.

**To customize which variables are used:**

1. Go to **Neon Console → Integrations**, click **Manage** next to **Vercel**, and open the **Settings** tab
2. Under **Vercel environment variables**, select the variables you want (for example, `PGHOST` or `PGUSER`)
3. Click **Save changes**

![Select Vercel variables](https://neon.com/docs/guides/vercel_select_variables.png)

### Password rotation behavior

When you rotate the selected role password in Neon, the integration automatically syncs updated credentials to Vercel environment variables for connected projects.

If deployments still use older credentials, open the **Settings** tab (**Neon Console → Integrations → Manage**) and click **Save changes** to force a resync.

### Branch cleanup

**Automatic cleanup (recommended):**
Enable **Automatically delete obsolete Neon branches** during setup to remove preview branches automatically when the corresponding Git branch is merged or deleted. You can change this setting later on the **Branches** tab (**Neon Console → Integrations → Manage**), under **Automation workflows**. Cleanup runs the next time a preview deployment is created.

Unlike the [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration), this cleanup is not affected by Vercel's deployment retention policies. For a full comparison and additional cleanup options, see [Managing Vercel preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup).

**Manual cleanup:**
If needed, you can delete branches manually:

- **Neon Console:** delete branches from your project's **Branches** page. See [Delete a branch](https://neon.com/docs/manage/branches#delete-a-branch).
- **API/CLI:** Use the [Neon CLI](https://neon.com/docs/cli/branches#delete) or [Neon API](https://neon.com/docs/manage/branches#delete-a-branch-with-the-api) for programmatic cleanup

**Warning: Important cleanup considerations**

- **Don't rename branches:** Renaming either the Git branch or Neon branch breaks name-matching logic and may cause unintended deletions
- **Avoid child branches:** Creating child branches on preview branches prevents automatic deletion
- **Role dependency:** The integration depends on the selected role; removing it will break the integration

### Disconnect integration

To disconnect the integration, go to **Neon Console → Integrations**, click **Manage** next to **Vercel**, open the **Disconnect** tab, and click **Disconnect**. This stops Neon from setting environment variables in Vercel. It doesn't remove existing branches or the integration itself. To fully remove the integration, uninstall it from your Vercel project's **Settings**.

---

## Limitations

- **One-to-one relationship:** Each Neon project connects to exactly one Vercel project
- **Integration exclusivity:** Cannot coexist with the Vercel-Managed Integration in the same Vercel project
- **Role dependency:** Integration requires the selected PostgreSQL role to remain active

---

## Next steps

## After Installation

- [ ] [Test preview branching](https://neon.com/docs/guides/neon-managed-vercel-integration#how-preview-branching-works)
    Create a feature branch and push changes to verify preview deployments work correctly
- [ ] [Configure build commands](https://neon.com/docs/guides/neon-managed-vercel-integration#how-preview-branching-works)
    Add migration commands to Vercel's build settings if using an ORM like Prisma
- [ ] [Set up branch cleanup](https://neon.com/docs/guides/neon-managed-vercel-integration#branch-cleanup)
    Enable automatic cleanup or establish a manual cleanup process
- [ ] [Customize environment variables](https://neon.com/docs/guides/neon-managed-vercel-integration#environment-variables)
    Review and adjust which database variables are injected into your deployments

---

## Troubleshooting

### Environment variable conflicts

If you see "Failed to set environment variables" during setup, remove conflicting variables in Vercel first:

1. Go to **Vercel → Settings → Environment Variables**
2. Remove or rename existing `DATABASE_URL`, `PGHOST`, `PGUSER`, `PGDATABASE`, or `PGPASSWORD` variables
3. Retry the integration setup

### Integration stops working

**Issue:** Preview branches no longer created
**Cause:** The PostgreSQL role selected during setup was deleted
**Solution:** Reinstall the integration with a valid role, or change the role under **Default database and role** on the **Settings** tab (**Neon Console → Integrations → Manage**)

--- [Document source](https://neon.com/docs/guides/neon-private-networking.md) ---

> Summary: Neon Private Networking routes database traffic through AWS PrivateLink, keeping connections entirely within AWS's private network rather than the public internet. Use this page when your client application runs on AWS and you need to eliminate public internet exposure for a Neon project on the Scale or Business plan (org Admin required). Removed VPC endpoints cannot be re-added to the same organization.

# Neon Private Networking

Learn how to connect to your Neon database via AWS PrivateLink

Last updated: 2026-10-09

**Info: Private Networking availability**

Private Networking is available on Neon's [Scale](https://neon.com/docs/introduction/plans#scale) plan. If you're on a different plan, you can request a trial from the **Network Security** page in your project's settings.

The **Neon Private Networking** feature enables secure connections to your Neon databases via [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html), bypassing the open internet for enhanced security.

## Overview

In a standard setup, the client application connects to a Neon database over the open internet via the Neon proxy.

With **Neon Private Networking**, you can connect to your database via AWS PrivateLink instead of the open internet. In this setup, the client application connects through an [AWS endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html) (provided by Neon) to a Neon proxy instance that is not accessible from the public internet. This endpoint service is available only within the same AWS region as your client application. With **Neon Private Networking**, all traffic between the client application and the Neon database stays within AWS's private network, rather than crossing the public internet.

![Neon Private Networking diagram](https://neon.com/docs/guides/neon_private_access.jpg)

## Prerequisites

- You must be a Neon [Business](https://neon.com/docs/introduction/plans#business) and [Scale](https://neon.com/docs/introduction/plans#scale) account user, and your user account must be [Neon organization](https://neon.com/docs/manage/organizations) Admin account. You'll encounter an access error if you attempt the setup from a personal Neon account or on a Neon plan that does not offer Private Networking.
- **Ensure that your client application is deployed on AWS in the same region as the Neon database you plan to connect to.** The Private Networking feature is available in all [Neon-supported AWS regions](https://neon.com/docs/introduction/regions#aws-regions). Both your private access client application and Neon database must be in one of these regions.
- Neon Private Networking supports both [IPv4](https://en.wikipedia.org/wiki/Internet_Protocol_version_4) and [IPv6](https://en.wikipedia.org/wiki/IPv6).
- Install the Neon CLI. You will use it to add your VPC endpoint ID to your Neon organization. For installation instructions, see [Neon CLI — Install and connect](https://neon.com/docs/cli/install).

## Configuration steps

To configure Neon Private Networking, perform the following steps:

## Create an AWS VPC endpoint

**Important:** Do not enable **private DNS names** for the VPC endpoint until [Step 3](https://neon.com/docs/guides/neon-private-networking#enable-private-dns). You must add the VPC endpoint to your Neon organization first, as described in [Step 2](https://neon.com/docs/guides/neon-private-networking#add-your-vpc-endpoint-id-to-your-neon-organization).

**Important: Add all service names for your region**

A region can list multiple endpoint service names. When you create the endpoint, add **all** of the names listed for your region below (under **Service settings**). Neon adds service names over time as it expands capacity and updates this page, so re-check that list after a regional expansion. Adding those later additions is optional but improves capacity and reliability. Expansions are announced in the [changelog](https://neon.com/docs/changelog).

1. Go to the AWS **VPC > Endpoints** dashboard and select **Create endpoint**. Make sure you create the endpoint in the same VPC as your client application.

   ![VPC Dashboard](https://neon.com/docs/guides/pl_vpc_dashboard.png)

2. Optionally, enter a **Name tag** for the endpoint (for example, `My Neon Private Networking`).

3. For **Type**, select the **Endpoint services that use NLBs and GWLBs** category.

   ![VPC Create endpoint](https://neon.com/docs/guides/pl_vpc_create_endpoint.png)

4. Under **Service settings**, specify the **Service name**. Some regions require specifying multiple service names, and service names vary by region:

   - **us-east-1**: Create entries, one for each of the following:
     - `com.amazonaws.vpce.us-east-1.vpce-svc-01aeec2f4b558bc22`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-01b3c73657ed9bd29`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-02a0abd91f32f1ed7`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-040132f4a2dc43d76`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0492424e0bf471d59`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-074ac4111275eaf07`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-07e0ce252b3a16acc`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0824666dc46176a87`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0adffb07ac0333ac0`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0b676a43303caf7d8`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0bef3dbe6e4a2df49`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0c4afbefbfdf6b031`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0d07f7f68c9a99f3b`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0de57c578b0e614a9`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0e018376e3c90bfae`
     - `com.amazonaws.vpce.us-east-1.vpce-svc-0f37140e9710ee3af`
   - **us-east-2**: Create entries, one for each of the following:
     - `com.amazonaws.vpce.us-east-2.vpce-svc-0056bdfba63cc6ea1`
     - `com.amazonaws.vpce.us-east-2.vpce-svc-010736480bcef5824`
     - `com.amazonaws.vpce.us-east-2.vpce-svc-0125f603817b3d7f7`
     - `com.amazonaws.vpce.us-east-2.vpce-svc-0234a2d750f731a18`
     - `com.amazonaws.vpce.us-east-2.vpce-svc-0465c21ce8ba95fb2`
     - `com.amazonaws.vpce.us-east-2.vpce-svc-0a59493ecf790eccf`
     - `com.amazonaws.vpce.us-east-2.vpce-svc-0ce57d490de78526a`
     - `com.amazonaws.vpce.us-east-2.vpce-svc-0d421498ff01becac`
     - `com.amazonaws.vpce.us-east-2.vpce-svc-0fcb5fccfc8573aa3`
   - **eu-central-1**: Create entries, one for each of the following:
     - `com.amazonaws.vpce.eu-central-1.vpce-svc-0260f9dcc9bf59e3e`
     - `com.amazonaws.vpce.eu-central-1.vpce-svc-04bac3120b20929cd`
     - `com.amazonaws.vpce.eu-central-1.vpce-svc-05554c35009a5eccb`
     - `com.amazonaws.vpce.eu-central-1.vpce-svc-0575a0aedec0492b8`
     - `com.amazonaws.vpce.eu-central-1.vpce-svc-05a252e6836f01cfd`
     - `com.amazonaws.vpce.eu-central-1.vpce-svc-05a5b03b56954593a`
     - `com.amazonaws.vpce.eu-central-1.vpce-svc-07617c7fc17794cc7`
     - `com.amazonaws.vpce.eu-central-1.vpce-svc-0fef417ecf84ed325`
   - **eu-west-2**: Create entries, one for each of the following:
     - `com.amazonaws.vpce.eu-west-2.vpce-svc-0375428488d22c05b`
     - `com.amazonaws.vpce.eu-west-2.vpce-svc-0c6fedbe99fced2cd`
   - **us-west-2**: Create entries, one for each of the following:
     - `com.amazonaws.vpce.us-west-2.vpce-svc-045eebdf710e1066d`
     - `com.amazonaws.vpce.us-west-2.vpce-svc-060e0d5f582365b8e`
     - `com.amazonaws.vpce.us-west-2.vpce-svc-07b750990c172f22f`
     - `com.amazonaws.vpce.us-west-2.vpce-svc-0a7b662960507808f`
     - `com.amazonaws.vpce.us-west-2.vpce-svc-0ed672a4d41b5e687`
   - **ap-southeast-1**: Create entries, one for each of the following:
     - `com.amazonaws.vpce.ap-southeast-1.vpce-svc-00eb29496a51d8bee`
     - `com.amazonaws.vpce.ap-southeast-1.vpce-svc-01c64edf7fe936ac7`
     - `com.amazonaws.vpce.ap-southeast-1.vpce-svc-028cc7060eb23ff43`
     - `com.amazonaws.vpce.ap-southeast-1.vpce-svc-07c68d307f9f05687`
   - **ap-southeast-2**:
     - `com.amazonaws.vpce.ap-southeast-2.vpce-svc-031161490f5647f32`
   - **sa-east-1**: Create entries, one for each of the following:
     - `com.amazonaws.vpce.sa-east-1.vpce-svc-03cf6c871b7ae95e8`
     - `com.amazonaws.vpce.sa-east-1.vpce-svc-061204a851dbd1a47`

5. Click **Verify service**. If successful, you should see a `Service name verified` message.

   ![VPC Create endpoint](https://neon.com/docs/guides/pl_vpc_service_name_verified.png)

   If not successful, ensure that your service name matches the region where you're creating the VPC endpoint.

6. Select the VPC where your application is deployed.

7. Add the availability zones and associated subnets you want to support.

8. Click **Create endpoint** to complete the setup of the endpoint service.

   ![VPC Create endpoint](https://neon.com/docs/guides/pl_vpc_network_settings.png)

9. Note your **VPC Endpoint ID**. You will need it in the next step.

   ![VPC Create endpoint](https://neon.com/docs/guides/pl_vpc_endpoint_id.png)

## Add your VPC Endpoint ID to your Neon organization

Assign your **VPC Endpoint ID** to your Neon organization. If the region has multiple **Service Names**, please assign all **VPC Endpoint IDs**. You can do this using the Neon CLI or API.

**Note:** Please note that you must assign the **VPC Endpoint ID**, not the VPC ID.

**CLI**

In the following example, the VPC endpoint ID is assigned to a Neon organization in the specified AWS region using the [neon vpc endpoint](https://neon.com/docs/cli/vpc#endpoint) command.

```bash
neon vpc endpoint assign vpce-1234567890abcdef0 --org-id org-bold-bonus-12345678 --region-id aws-us-east-2
```

You can find your Neon organization ID in your Neon organization settings, or you can run this Neon CLI command: `neon orgs list`

**API**

You can use the [Assign or update a VPC endpoint](https://neon.com/docs/reference/api/organizations/assign-organization-vpc-endpoint) API to assign a VPC endpoint ID to a Neon organization. You will need to provide your Neon organization ID, region ID, VPC endpoint ID, and a [Neon API key](https://neon.com/docs/manage/api-keys).

```bash
curl --request POST \
 --url https://console.neon.tech/api/v2/organizations/org-bold-bonus-12345678/vpc/region/aws-us-east-2/vpc_endpoints/vpce-1234567890abcdef0 \
 --header 'accept: application/json' \
 --header 'authorization: Bearer $NEON_API_KEY' \
 --header 'content-type: application/json'
```

Optionally, you can limit access to a Neon project by allowing connections only from a specific VPC endpoint. For instructions, see [Assigning a VPC endpoint restrictions](https://neon.com/docs/guides/neon-private-networking#assigning-a-vpc-endpoint-restriction).

## Enable Private DNS

After adding your VPC endpoint ID to your Neon organization, enable private DNS lookup for the VPC endpoint in AWS.

1. In AWS, select the VPC endpoint you created.
2. Choose **Modify private DNS name**.
3. Select **Enable for this endpoint**.
4. Save your changes.
   ![Enable private DNS](https://neon.com/docs/guides/pl_enable_private_dns.png)

## Check your database connection string

Your Neon database connection string does not change when using Private Networking.

To verify that your connection is working correctly, you can perform a DNS lookup on your Neon endpoint hostname from within your AWS VPC. It should resolve to the private IP address of the VPC endpoint.

For example, if your Neon database connection string is:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

You can run the following command from an EC2 instance inside your AWS VPC:

```bash
nslookup ep-cool-darkness-123456.us-east-2.aws.neon.tech
```

## Restrict public internet access

At this point, it's still possible to connect to a database in your Neon project over the public internet using a database connection string.

You can restrict public internet access to your Neon project via the Neon CLI or API.

**CLI**

To block access via the Neon CLI, use the [neon projects update](https://neon.com/docs/cli/projects#update) command with the `--block-public-connections` option.

```bash
neon projects update orange-credit-12345678 --block-public-connections true
```

In the example above, `orange-credit-12345678` is the Neon project ID. You can find _your_ Neon project ID under your project's settings in the Neon Console, or by running this Neon CLI command: `neon projects list`

**API**

To block access via the Neon API, use the [Update project](https://neon.com/docs/reference/api/projects/update-project) endpoint with the `block_public_connections` settings object attribute.

```bash
curl --request PATCH \
 --url https://console.neon.tech/api/v2/projects/orange-credit-12345678 \
 --header 'accept: application/json' \
 --header 'authorization: Bearer $NEON_API_KEY' \
 --header 'content-type: application/json' \
 --data '
{
"project": {
    "settings": {
    "block_public_connections": true
    }
}
}
'
```

## Assigning a VPC endpoint restriction

You can limit access to a Neon project by allowing connections only from specified VPC endpoints. Use the Neon CLI or API to set a restriction.

**CLI**

You can specify a CLI command similar to the following to restrict project access:

```bash
neon vpc project restrict vpce-1234567890abcdef0 --project-id orange-credit-12345678
```

You will need to provide the VPC endpoint ID and your Neon project ID. If the region has multiple **Service Names**, all **VPC Endpoint IDs** must be restricted in the way as above. You can find your Neon project ID under your project's settings in the Neon Console, or by running this Neon CLI command: `neon projects list`

After adding a restriction, you can check the status of the VPC endpoint to view the restricted project using the [vpc endpoint status command](https://neon.com/docs/cli/vpc#endpoint). You will need to provide your VPC endpoint ID, region ID, and Neon organization ID.

```bash
neon vpc endpoint status vpce-1234567890abcdef0 --region-id=aws-eu-central-1 --org-id=org-nameless-block-72040075
VPC Endpoint ID              vpce-1234567890abcdef0
State                        new
Num Restricted Projects      1
Example Restricted Projects  orange-credit-12345678
```

**API**

The Neon API supports managing project restrictions using the [Assign or update a VPC endpoint restriction](https://neon.com/docs/reference/api/projects/assign-project-vpc-endpoint) endpoint. You will need to provide your VPC endpoint ID, Neon project ID, and a [Neon API key](https://neon.com/docs/manage/api-keys).

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/orange-credit-12345678/vpc_endpoints/vpce-1234567890abcdef0 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '{"label":"my_vpc"}'
```

After adding a restriction, you can check the status of the VPC endpoint to view the restricted project using the [Retrieve VPC endpoint details](https://neon.com/docs/reference/api/organizations/get-organization-vpc-endpoint-details) API. You will need to provide your VPC endpoint ID, region ID, Neon organization ID, and a Neon API key.

```bash
curl --request GET \
     --url https://console.neon.tech/api/v2/organizations/org-nameless-block-72040075/vpc/region/aws-eu-central-1/vpc_endpoints/vpce-1234567890abcdef0 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

## Managing Private Networking using the Neon CLI

You can use the Neon CLI `vpc` command to manage Private Networking configurations in Neon.

The `vpc` command includes `endpoint` and `project` subcommands for managing VPC endpoints and project-level VPC endpoint restrictions:

- **`vpc endpoint`** – List, assign, remove, and retrieve the status of VPC endpoints for a Neon organization.
- **`vpc project`** – List, configure, or remove VPC endpoint restrictions for specific Neon projects.

For more details and examples, see [Neon CLI commands — vpc](https://neon.com/docs/cli/vpc).

## Managing Private Networking using the Neon API

The Neon API provides endpoints for managing VPC endpoints and project-level VPC endpoint restrictions:

### APIs for managing VPC endpoints

- [List VPC endpoints](https://neon.com/docs/reference/api/organizations/list-organization-vpc-endpoints)
- [Assign or update a VPC endpoint](https://neon.com/docs/reference/api/organizations/assign-organization-vpc-endpoint)
- [Retrieve VPC endpoint configuration details](https://neon.com/docs/reference/api/organizations/get-organization-vpc-endpoint-details)
- [Delete a VPC endpoint](https://neon.com/docs/reference/api/organizations/delete-organization-vpc-endpoint)

### APIs for managing VPC endpoint restrictions

- [Get VPC endpoint restrictions](https://neon.com/docs/reference/api/projects/list-project-vpc-endpoints)
- [Assign or update a VPC endpoint restriction](https://neon.com/docs/reference/api/projects/assign-project-vpc-endpoint)
- [Delete a VPC endpoint restriction](https://neon.com/docs/reference/api/projects/delete-project-vpc-endpoint)

## Private Networking limits

The Private Networking feature supports a maximum of **20 private networking configurations per AWS region**. Supported AWS regions are listed [above](https://neon.com/docs/guides/neon-private-networking#create-an-aws-vpc-endpoint).

## Limitations

If you remove a VPC endpoint from a Neon organization, that VPC endpoint cannot be added back to the same Neon organization. Attempting to do so will result in an error. In this case, you must set up a new VPC endpoint.

--- [Document source](https://neon.com/docs/guides/neon-twin-full-pg-dump-restore.md) ---

> Summary: Full Neon Twin workflow that copies a complete production database into a Neon development database using `pg_dump` (custom `-Fc` format) and `pg_restore` inside a GitHub Actions job scheduled daily via cron or triggered on merged pull requests. Choose this workflow over schema-only or incremental approaches when you need a full data refresh and GitHub Actions is your CI platform. Requires unpooled connection strings for both source and target databases; GitHub Actions enforces a 6-hour per-job limit, so very large databases may require self-hosted runners.

# pg_dump / pg_restore — Full Twin

Create a full Twin of your production database

Last updated: 2026-06-05

This workflow will create a full Neon Twin using `pg_dump` and `pg_restore`.

**Note:** To use this workflow, you'll need the Postgres connection string for your Neon database. Follow our [Getting Started Guide](https://neon.com/docs/get-started/signing-up#sign-up) to learn how.

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) for `PROD_DATABASE_URL` and `DEV_DATABASE_URL` when they point to Neon.

## Create the workflow

To create the Twin workflow in any GitHub-hosted repository:

1. Create a new directory named `.github` at the root of your project.
2. Inside this directory, create another directory named `workflows`.
3. Within the `workflows` directory, create a new file named `create-neon-twin.yml`.

```
.github
  |-- workflows
      |-- create-neon-twin.yml
```

Add the following code to `create-neon-twin.yml`.

```yml
name: Create Neon Twin

on:
  schedule:
    - cron: '0 0 * * *' # Runs at midnight UTC
  workflow_dispatch:

env:
  PROD_DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }} # Production or primary database
  DEV_DATABASE_URL: ${{ secrets.DEV_DATABASE_URL }} # Development database
  PG_VERSION: '17'

jobs:
  dump-and-restore:
    runs-on: ubuntu-latest

    steps:
      - name: Install PostgreSQL
        run: |
          sudo apt update
          yes '' | sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
          sudo apt install -y postgresql-${{ env.PG_VERSION }}

      - name: Set PostgreSQL binary path
        run: echo "POSTGRES=/usr/lib/postgresql/${{ env.PG_VERSION }}/bin" >> $GITHUB_ENV

      - name: Dump and restore data
        run: |
          $POSTGRES/pg_dump -Fc -f "${{ github.workspace }}/dump-file.bak" "${{ env.PROD_DATABASE_URL }}"
          $POSTGRES/pg_restore --clean --no-owner --no-acl --if-exists -d "${{ env.DEV_DATABASE_URL }}" "${{ github.workspace }}/dump-file.bak"
```

## GitHub Action explained

Below is an explanation of each part of the GitHub Action.

### on

- `name`: The name of the Action as it appears in the GitHub UI.
- `cron`: The [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07) that defines when the Action will run.
- `workflow_dispatch`: Enables manual triggering through the GitHub UI.

### env

- `PROD_DATABASE_URL`: The PostgreSQL connection string for your production database.
- `DEV_DATABASE_URL`: The PostgreSQL connection string for your Neon database.
- `PG_VERSION`: The version of PostgreSQL to install in the Action environment.

### steps

- `Install PostgreSQL`: Installs the specified version of PostgreSQL into the Action environment from the [Apt](https://wiki.debian.org/Apt) repository.
- `Set PostgreSQL binary path`: Creates `$POSTGRES` variable for use in subsequent steps.
- `Dump and restore data`: Uses `pg_dump` to create a `dump-file.bak` and `pg_restore` to read the `dump-file.bak` and apply it to the `DEV_DATABASE_URL`.

### pg_dump flags

The table below provides an explanation of each flag used by `pg_dump`.

| Flag | Meaning                                                         |
| ---- | --------------------------------------------------------------- |
| -FC  | Dumps the database in a custom format.                          |
| -f   | Specifies the output file where the schema dump will be stored. |

### pg_restore flags

The table below provides an explanation of each flag used by `pg_restore`.

| Flag        | Meaning                                                                                                        |
| ----------- | -------------------------------------------------------------------------------------------------------------- |
| --clean     | Drops existing database objects before recreating them, ensuring a clean restore.                              |
| --no-owner  | Ignores ownership information in the dump file, so restored objects are owned by the user running the restore. |
| --no-acl    | Excludes access control (GRANT/REVOKE) statements from the restore, preventing permission changes.             |
| --if-exists | Ensures that `DROP` commands (used with `--clean`) only execute if the object exists, preventing errors.       |
| -d          | Specifies the target database to restore into.                                                                 |

## Setting repository secrets

Before running the Action, ensure that both `PROD_DATABASE_URL` and `DEV_DATABASE_URL` are added to your GitHub repository secrets.

In your repository, go to **Settings** > **Secrets and variables** > **Actions** to add them.

![GitHub repository secrets](https://neon.com/docs/guides/twin_diagram_github_secrets.png)

## Testing the workflow

To manually trigger your workflow go to **Actions** > **Create Neon Twin** then click **Run workflow**. From the dropdown, click the **Run workflow** button.

![GitHub Actions run workflow](https://neon.com/docs/guides/twin_diagram_test_workflow.png)

## Syncing with migration changes

The GitHub Action runs on a recurring schedule, but you may also want it to trigger when migration changes are applied and a Pull Request is merged. To enable this, update the Action with the following code:

### Handling Pull Request Events

Add a `pull_request` event and configure it to listen for merges into the main `branch`.

```diff

on:
  schedule:
    - cron: '0 0 * * *' # Runs at midnight UTC
  pull_request:
    types: [closed]
    branches:
      - main
  workflow_dispatch:

```

### Add Concurrency and Conditions

To prevent conflicts between scheduled runs and runs triggered by a Pull Request, set `cancel-in-progress` to `true` under `concurrency`. Additionally, add an `if` statement to ensure the job only executes when specific conditions are met.

```diff

jobs:
  dump-and-restore:
    runs-on: ubuntu-latest
    concurrency:
      group: 'dump-and-restore'
      cancel-in-progress: true
    if: |
      github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.merged == true)

```

## Limitations

Be aware of [usage limits](https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits): Each GitHub Action job can run for up to 6 hours. If a job exceeds this limit, it will be terminated and fail to complete.

If your dump/restore process takes longer, consider using [self-hosted runners](https://neon.com/guides/gihub-actions-self-hosted-runners).

## Further reading

- [Neon Twin: Move Dev/Test/Staging to Neon, Keep Production on RDS](https://neon.com/blog/optimizing-dev-environments-in-aws-rds-with-neon-postgres-part-ii-using-github-actions-to-mirror-rds-in-neon)
- [Neon Twin: How to deploy a change tested in Neon to prod in RDS](https://neon.com/blog/neon-twin-deploy-workflow)

--- [Document source](https://neon.com/docs/guides/neon-twin-intro.md) ---

> Summary: A Neon Twin is a full or partial clone of your production or staging database hosted on Neon, giving developers isolated, sandboxed environments that stay automatically synchronized with production. Use a Neon Twin when you want to run development and testing against real schema and data without touching production, with instant branches spun up per developer or feature. Choosing between a full Twin (pg_dump/pg_restore of the entire database) and a partial Twin (schema plus selected tables only) depends on data volume and how much production fidelity your workflow requires.

# Create a Neon Twin

Learn how to Twin your production database with Neon

Last updated: 2026-06-23

> **Explore our dev/test use case**
>
> Move development and testing to Neon; keep production right where it is.Read more about our dev/test use case [here](https://neon.com/use-cases/dev-test).

## What is a Neon Twin?

A Neon Twin is a full or partial clone of your production or staging database, providing developers and teams with isolated, sandboxed environments that closely mirror production.

![Dev/Test Twin Workflow](https://neon.com/use-cases/dev-test-twin-workflow.png)

## Designed for efficiency

Creating a Neon Twin will streamline development workflows, enhance productivity, and help teams ship faster, all while being more cost-effective and easier to manage than traditional development/testing environments.

## Automatically synced

The workflows in this section enable automatic synchronization between your production database and your Neon Twin.

## Instant Branches

With a Neon Twin created, [branches](https://neon.com/docs/introduction/branching) can be quickly spun up or torn down, enabling developers to build new features or debug issues, all within their own isolated environments with a dedicated compute resource.

Branches can be created and managed through the [Neon console](https://console.neon.tech/) or programmatically via the [API](https://neon.com/docs/reference/api).

## Get started

Pick the workflow that fits your needs. A full Twin mirrors your entire production database; a partial Twin clones only the schema and selected tables, which is faster and useful when you don't need every row of production data.

- [Create a full Twin](https://neon.com/docs/guides/neon-twin-full-pg-dump-restore): Clone your entire production database to Neon using pg_dump and pg_restore in a GitHub Actions workflow.
- [Create a partial Twin](https://neon.com/docs/guides/neon-twin-partial-pg-dump-restore): Clone only the schema and selected tables from production using pg_dump, pg_restore, and psql.

--- [Document source](https://neon.com/docs/guides/neon-twin-partial-pg-dump-restore.md) ---

> Summary: A GitHub Actions workflow that mirrors a production PostgreSQL schema and a row-limited data subset into a Neon development database using `pg_dump --schema-only`, `psql \copy`, and `pg_restore`. Use this approach when you need a lightweight dev environment that reflects production structure without copying the full dataset. The workflow runs on a daily cron schedule, supports multi-table foreign key relationships, requires unpooled connection strings, and is subject to GitHub Actions' 6-hour job limit.

# pg_dump / pg_restore — Partial Twin

Create a partial Twin of your production database

Last updated: 2026-06-05

This workflow will create a partial Neon Twin using `pg_dump`, `pg_restore` and `psql`.

**Note:** To use this workflow, you'll need the Postgres connection string for your Neon database. Follow our [Getting Started Guide](https://neon.com/docs/get-started/signing-up#sign-up) to learn how.

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) for `PROD_DATABASE_URL` and `DEV_DATABASE_URL` when they point to Neon.

## Create the workflow

To create the Twin workflow in any GitHub-hosted repository:

1. Create a new directory named `.github` at the root of your project.
2. Inside this directory, create another directory named `workflows`.
3. Within the `workflows` directory, create a new file named `create-neon-twin.yml`.

```
.github
  |-- workflows
      |-- create-neon-twin.yml
```

Add the following code to `create-neon-twin.yml`.

```yml
name: Create Neon Twin

on:
  schedule:
    - cron: '0 0 * * *' # Runs at midnight UTC
  workflow_dispatch:

env:
  PROD_DATABASE_URL: ${{ secrets.PROD_DATABASE_URL }} # Production or primary database
  DEV_DATABASE_URL: ${{ secrets.DEV_DATABASE_URL }} # Development database
  PG_VERSION: '17'

jobs:
  dump-and-restore:
    runs-on: ubuntu-latest

    steps:
      - name: Install PostgreSQL
        run: |
          sudo apt update
          yes '' | sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
          sudo apt install -y postgresql-${{ env.PG_VERSION }}

      - name: Set PostgreSQL binary path
        run: echo "POSTGRES=/usr/lib/postgresql/${{ env.PG_VERSION }}/bin" >> $GITHUB_ENV

      - name: Dump schema
        run: |
          $POSTGRES/pg_dump -Fc --schema-only -f "${{ github.workspace }}/all-schema.bak" "${{ env.PROD_DATABASE_URL }}"

      - name: Dump data
        run: |
          $POSTGRES/psql "${{ env.PROD_DATABASE_URL }}" -c "\copy (SELECT * FROM users ORDER BY user_id DESC LIMIT 50) TO '${{ github.workspace }}/users-subset.csv' WITH CSV HEADER"

      - name: Drop tables and schema
        run: |
          $POSTGRES/psql "${{ env.DEV_DATABASE_URL }}" -c "DROP SCHEMA IF EXISTS public CASCADE;"
          $POSTGRES/psql "${{ env.DEV_DATABASE_URL }}" -c "CREATE SCHEMA public;"

      - name: Restore schema
        run: |
          $POSTGRES/pg_restore --clean --no-owner --no-acl --if-exists --schema-only -d "${{ env.DEV_DATABASE_URL }}" "${{ github.workspace }}/all-schema.bak"

      - name: Restore data
        run: |
          $POSTGRES/psql "${{ env.DEV_DATABASE_URL }}" -c "\copy public.users FROM '${{ github.workspace }}/users-subset.csv' WITH CSV HEADER"
```

## GitHub Action explained

Below is an explanation of each part of the GitHub Action.

### on

- `name`: The name of the Action as it appears in the GitHub UI.
- `cron`: The [POSIX cron syntax](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html#tag_20_25_07) that defines when the Action will run.
- `workflow_dispatch`: Enables manual triggering through the GitHub UI.

### env

- `PROD_DATABASE_URL`: The PostgreSQL connection string for your production database.
- `DEV_DATABASE_URL`: The PostgreSQL connection string for your Neon database.
- `PG_VERSION`: The version of PostgreSQL to install in the Action environment.

### steps

- `Install PostgreSQL`: Installs the specified version of PostgreSQL into the Action environment from the [Apt](https://wiki.debian.org/Apt) repository.
- `Set PostgreSQL binary path`: Creates `$POSTGRES` variable for use in subsequent steps.
- `Dump schema`: Exports the database schema (table structures, indexes, constraints) from the production database into a backup file.
- `Dump data`: Extracts a subset of data (50 most recent users) from the production database into a CSV file.
- `Drop tables and schema`: Completely removes the existing schema in the development database and recreates it to ensure a clean state.
- `Restore schema` : Imports the previously dumped schema into the development database, re-creating table structures and constraints.
- `Restore data` : Loads the extracted data subset from the CSV file into the corresponding table in the development database.

### pg_dump flags

The table below provides an explanation of each flag used by `pg_dump`.

| Flag          | Meaning                                                                          |
| ------------- | -------------------------------------------------------------------------------- |
| -FC           | Dumps the database in a custom format.                                           |
| --schema-only | Dumps only the schema (table structures, indexes, constraints) without any data. |
| -f            | Specifies the output file where the schema dump will be stored.                  |

### psql flags

The table below provides an explanation of each flag used by `pg_dump`.

| Flag | Meaning                                    |
| ---- | ------------------------------------------ |
| -c   | Executes a single command and then exits.  |
| -d   | Specifies the database name to connect to. |

### pg_restore flags

The table below provides an explanation of each flag used by `pg_restore`.

| Flag          | Meaning                                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| --clean       | Drops existing database objects before recreating them, ensuring a clean restore.                              |
| --no-owner    | Ignores ownership information in the dump file, so restored objects are owned by the user running the restore. |
| --no-acl      | Excludes access control (GRANT/REVOKE) statements from the restore, preventing permission changes.             |
| --if-exists   | Ensures that `DROP` commands (used with `--clean`) only execute if the object exists, preventing errors.       |
| --schema-only | Restores only the schema (table structures, indexes, constraints) without inserting any data.                  |
| -d            | Specifies the target database to restore into.                                                                 |

## Working with multiple tables

The action above works well for dumping data from a single table. However, when working with multiple tables that have foreign key relationships, it's important to ensure that those relationships remain intact.

For example, if you're dumping a subset of data from a transactions table that references a `product_id` from the products table and a `user_id` from the users table, you must also query the corresponding products and users data.

This ensures that all referenced `product_id` and `user_id` values exist in the restored dataset, maintaining valid foreign key constraints.

To account for this, you may need to adjust the **Dump data** and **Restore data** steps accordingly.

For example, here is an amended example for the **Dump data** step.

```yml
- name: Dump data
    run: |
        $POSTGRES/psql "${{ env.PROD_DATABASE_URL }}" -c "\copy (SELECT * FROM products ORDER BY product_id DESC LIMIT 50) TO '${{ github.workspace }}/products-subset.csv' WITH CSV HEADER"
        $POSTGRES/psql "${{ env.PROD_DATABASE_URL }}" -c "\copy (SELECT * FROM transactions WHERE product_id IN (SELECT product_id FROM products ORDER BY product_id DESC LIMIT 10)) TO '${{ github.workspace }}/transactions-subset.csv' WITH CSV HEADER"
        $POSTGRES/psql "${{ env.PROD_DATABASE_URL }}" -c "\copy (SELECT * FROM users WHERE user_id IN (SELECT user_id FROM transactions WHERE product_id IN (SELECT product_id FROM products ORDER BY product_id DESC LIMIT 50))) TO '${{ github.workspace }}/users-subset.csv' WITH CSV HEADER"
```

And here is an example for the amended **Restore data** step.

```yml
- name: Restore data
    run: |
        $POSTGRES/psql "${{ env.DEV_DATABASE_URL }}" -c "\copy public.users FROM '${{ github.workspace }}/users-subset.csv' WITH CSV HEADER"
        $POSTGRES/psql "${{ env.DEV_DATABASE_URL }}" -c "\copy public.products FROM '${{ github.workspace }}/products-subset.csv' WITH CSV HEADER"
        $POSTGRES/psql "${{ env.DEV_DATABASE_URL }}" -c "\copy public.transactions FROM '${{ github.workspace }}/transactions-subset.csv' WITH CSV HEADER"
```

## Setting repository secrets

Before running the Action, ensure that both `PROD_DATABASE_URL` and `DEV_DATABASE_URL` are added to your GitHub repository secrets.

In your repository, go to **Settings** > **Secrets and variables** > **Actions** to add them.

![GitHub repository secrets](https://neon.com/docs/guides/twin_diagram_github_secrets.png)

## Testing the workflow

To manually trigger your workflow go to **Actions** > **Create Neon Twin** then click **Run workflow**. From the dropdown, click the **Run workflow** button.

![GitHub Actions run workflow](https://neon.com/docs/guides/twin_diagram_test_workflow.png)

## Syncing with migration changes

The GitHub Action runs on a recurring schedule, but you may also want it to trigger when migration changes are applied and a Pull Request is merged. To enable this, update the Action with the following code:

### Handling Pull Request Events

Add a `pull_request` event and configure it to listen for merges into the main `branch`.

```diff

on:
  schedule:
    - cron: '0 0 * * *' # Runs at midnight UTC
  pull_request:
    types: [closed]
    branches:
      - main
  workflow_dispatch:

```

### Add Concurrency and Conditions

To prevent conflicts between scheduled runs and runs triggered by a Pull Request, set `cancel-in-progress` to `true` under `concurrency`. Additionally, add an `if` statement to ensure the job only executes when specific conditions are met.

```diff

jobs:
  dump-and-restore:
    runs-on: ubuntu-latest
    concurrency:
      group: 'dump-and-restore'
      cancel-in-progress: true
    if: |
      github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.merged == true)

```

## Limitations

Be aware of [usage limits](https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits): Each GitHub Action job can run for up to 6 hours. If a job exceeds this limit, it will be terminated and fail to complete.

If your dump/restore process takes longer, consider using [self-hosted runners](https://neon.com/guides/gihub-actions-self-hosted-runners).

## Further reading

- [Automate Partial Data Dumps with PostgreSQL and GitHub Actions](https://neon.com/blog/automate-partial-data-dumps-with-postgresql-and-github-actions)
- [Neon Twin: How to deploy a change tested in Neon to prod in RDS](https://neon.com/blog/neon-twin-deploy-workflow)

--- [Document source](https://neon.com/docs/guides/nestjs.md) ---

> Summary: NestJS-to-Neon integration uses a DatabaseModule that provisions a connection pool via node-postgres, postgres.js, or the Neon serverless driver and injects it as a NestJS provider. Choose this guide when adding a Lakebase Postgres database on Neon to a TypeScript NestJS project without an ORM. The steps cover Neon project creation, DATABASE_URL configuration in .env, and wiring a service and GET controller endpoint to query the database.

# Connect a NestJS application to Neon

Set up a Neon project in seconds and connect from a NestJS application

Last updated: 2026-10-05

Pre-built prompt for connecting NestJS applications to Lakebase Postgres [View prompt](https://neon.com/prompts/nestjs-prompt.md)

[NestJS](https://docs.nestjs.com/) is a framework for building Node.js server-side applications. This guide explains how to connect a NestJS application to Neon.

To create a Neon project and access it from a NestJS application:

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a NestJS project and add dependencies

1. Create a NestJS project if you do not have one. For instructions, see [First steps](https://docs.nestjs.com/first-steps) in the NestJS documentation.

2. Add project dependencies using one of the following commands. Each installs the driver and `dotenv`, which the database module uses to load your connection string.

   **node-postgres**

   ```shell
   npm install pg dotenv
   npm install -D @types/pg
   ```

   **postgres.js**

   ```shell
   npm install postgres dotenv
   ```

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless dotenv
   ```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection string to it. You can find your connection details by clicking **Connect** in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

## Create a sample table

The example endpoint reads from a table named `playing_with_neon`. Create it and add a few rows by running the following SQL in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or with `psql`:

```sql
CREATE TABLE playing_with_neon(id SERIAL PRIMARY KEY, name TEXT NOT NULL, value REAL);
INSERT INTO playing_with_neon(name, value)
  SELECT LEFT(md5(i::TEXT), 10), random() FROM generate_series(1, 10) s(i);
```

## Configure the Postgres client

New NestJS projects use ES modules, so the relative imports below include the `.js` extension. The `.js` extension also works in projects that compile to CommonJS.

### 1. Create a database module

To manage the connection to your Neon database, create a `DatabaseModule` in `src/database/database.module.ts`. This module creates the Postgres client and provides it to the rest of your application.

**node-postgres**

```typescript
import { config } from 'dotenv';
import { Module } from '@nestjs/common';
import pg from 'pg';

// Load Environment Variables
config({
  path: ['.env', '.env.production', '.env.local'],
});

const sql = new pg.Pool({ connectionString: process.env.DATABASE_URL });

const dbProvider = {
  provide: 'POSTGRES_POOL',
  useValue: sql,
};

@Module({
  providers: [dbProvider],
  exports: [dbProvider],
})
export class DatabaseModule {}
```

**postgres.js**

```typescript
import { config } from 'dotenv';
import { Module } from '@nestjs/common';
import postgres from 'postgres';

// Load Environment Variables
config({
  path: ['.env', '.env.production', '.env.local'],
});

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

const dbProvider = {
  provide: 'POSTGRES_POOL',
  useValue: sql,
};

@Module({
  providers: [dbProvider],
  exports: [dbProvider],
})
export class DatabaseModule {}
```

**Neon serverless driver**

```typescript
import { config } from 'dotenv';
import { Module } from '@nestjs/common';
import { neon } from '@neondatabase/serverless';

// Load Environment Variables
config({
  path: ['.env', '.env.production', '.env.local'],
});

const sql = neon(process.env.DATABASE_URL!);

const dbProvider = {
  provide: 'POSTGRES_POOL',
  useValue: sql,
};

@Module({
  providers: [dbProvider],
  exports: [dbProvider],
})
export class DatabaseModule {}
```

### 2. Create a service for database interaction

Next, replace `src/app.service.ts` with a service that queries your database through the client provided by `DatabaseModule`.

**node-postgres**

```typescript
import { Injectable, Inject } from '@nestjs/common';
import type { Pool } from 'pg';

@Injectable()
export class AppService {
  constructor(@Inject('POSTGRES_POOL') private readonly sql: Pool) {}

  async getRows() {
    const { rows } = await this.sql.query('SELECT * FROM playing_with_neon');
    return rows;
  }
}
```

**postgres.js**

```typescript
import { Injectable, Inject } from '@nestjs/common';
import type { Sql } from 'postgres';

@Injectable()
export class AppService {
  constructor(@Inject('POSTGRES_POOL') private readonly sql: Sql) {}

  async getRows() {
    return await this.sql`SELECT * FROM playing_with_neon`;
  }
}
```

**Neon serverless driver**

```typescript
import { Injectable, Inject } from '@nestjs/common';
import type { NeonQueryFunction } from '@neondatabase/serverless';

@Injectable()
export class AppService {
  constructor(@Inject('POSTGRES_POOL') private readonly sql: NeonQueryFunction<false, false>) {}

  async getRows() {
    return await this.sql`SELECT * FROM playing_with_neon`;
  }
}
```

### 3. Integrate the database module and service

Import `DatabaseModule` and `AppService` in `src/app.module.ts`. This makes the database client and service available throughout your application.

```typescript
import { Module } from '@nestjs/common';
import { AppController } from './app.controller.js';
import { AppService } from './app.service.js';
import { DatabaseModule } from './database/database.module.js';

@Module({
  imports: [DatabaseModule],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

### 4. Define a controller endpoint

Finally, replace `src/app.controller.ts` with a `GET` endpoint that returns the rows from your table through `AppService`.

```typescript
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service.js';

@Controller('/')
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  async getRows() {
    return this.appService.getRows();
  }
}
```

If your project has the default `src/app.controller.spec.ts`, update or remove it: it tests `getHello()`, which the new controller replaces.

## Run the app

When you run `npm run start` you can expect to see output similar to the following at [localhost:3000](http://localhost:3000):

```json
[{"id":1,"name":"c4ca4238a0","value":0.39330545},{"id":2,"name":"c81e728d9d","value":0.14468245}]
```

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/netlify-functions.md) ---

> Summary: End-to-end tutorial for querying a Lakebase Postgres database from a Netlify Function using the @neondatabase/serverless driver and ES module (.mjs) syntax. The guide walks through creating a Neon project, writing a Node.js serverless handler with the neon() tagged-template client, and deploying via the Netlify CLI with DATABASE_URL set as an environment variable. Choose this page when the goal is serverless backend database access inside a Netlify Function, not edge middleware or static site build steps.

# Use Neon with Netlify Functions

Connect a Lakebase Postgres database to your Netlify Functions application

Last updated: 2026-10-09

[Netlify Functions](https://www.netlify.com/products/functions/) provide a serverless execution environment for building and deploying backend functionality without managing server infrastructure. It's integrated with Netlify's ecosystem, making it ideal for augmenting web applications with server-side logic, API integrations, and data processing tasks in a scalable way.

This guide will show you how to connect to a Lakebase Postgres database from your Netlify Functions project. We'll use the [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver) to connect to the database and make queries.

## Prerequisites

Before starting, ensure you have:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- A Netlify account for deploying your site with `Functions`. Sign up at [Netlify](https://netlify.com) if necessary. While Netlify can deploy directly from a GitHub repository, we'll use the `Netlify` CLI tool to deploy our project manually.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed locally for developing and deploying your Functions.

## Setting up your Neon database

### Initialize a new project

After logging into the Neon Console, proceed to the [Projects](https://console.neon.tech/app/projects) section.

1. Click `New Project` to start a new one.

2. In the Neon Console, use **Postgres database** > **SQL Editor** from the sidebar to execute the SQL command below, creating a new table for coffee blends:

   ```sql
   CREATE TABLE favorite_coffee_blends (
       id SERIAL PRIMARY KEY,
       name TEXT,
       origin TEXT,
       notes TEXT
   );
   ```

   Populate the table with some initial data:

   ```sql
   INSERT INTO favorite_coffee_blends (name, origin, notes)
   VALUES
       ('Morning Joy', 'Ethiopia', 'Citrus, Honey, Floral'),
       ('Dark Roast Delight', 'Colombia', 'Rich, Chocolate, Nutty'),
       ('Arabica Aroma', 'Brazil', 'Smooth, Caramel, Fruity'),
       ('Robusta Revolution', 'Vietnam', 'Strong, Bold, Bitter');
   ```

### Retrieve your database connection string

You can find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

## Setting up your Netlify Functions project

We'll use the Netlify CLI to create a new project and add functions to it. To install the CLI, run:

```bash
npm install netlify-cli -g
```

To authenticate the CLI with your Netlify account, run:

```bash
netlify login
```

This command opens a browser window to authenticate your terminal session with Netlify. After logging in, you can close the browser window and interact with your Netlify account from the terminal.

### Create a new Netlify project

We will create a simple HTML webpage that fetches the coffee blends from the Neon database using a Netlify Function and displays them. To create a new `Netlify Site` project, run:

```bash
mkdir neon-netlify-example && cd neon-netlify-example
netlify sites:create
```

You will be prompted to select a team and site name. Choose a unique name for your site. This command then links the current directory to a `Site` project in your Netlify account.

```
❯ netlify sites:create
? Team: Ishan Anand's team
? Site name (leave blank for a random name; you can change it later): neon-netlify-example

Site Created

Admin URL: https://app.netlify.com/sites/neon-netlify-example
URL:       https://neon-netlify-example.netlify.app
Site ID:   ed43ba05-ff6e-40a9-9a68-8f58b9ad9937

Linked to neon-netlify-example
```

### Implement the function

We'll create a new function to fetch the coffee blends from the database. To set up the function entrypoint script, you can run the command below and use the settings provided:

```bash
❯ netlify functions:create get_coffee_blends

? Select the type of function you'd like to create Serverless function (Node/Go/Rust)
? Select the language of your function JavaScript
? Pick a template javascript-hello-world
◈ Creating function get_coffee_blends
◈ Created ./netlify/functions/get_coffee_blends/get_coffee_blends.js

Function created!
```

This command creates a new directory `netlify/functions/get_coffee_blends` with a `get_coffee_blends.js` file inside it. We are using the ES6 `import` syntax to implement the request handler, so we will change the script extension to `.mjs` for the runtime to recognize it.

We also install the `Neon serverless` driver as a dependency to connect to the database and fetch the data.

```bash
mv netlify/functions/get_coffee_blends/get_coffee_blends.js netlify/functions/get_coffee_blends/get_coffee_blends.mjs
npm install @neondatabase/serverless
```

Now, replace the contents of the function script with the following code:

```javascript
// netlify/functions/get_coffee_blends/get_coffee_blends.mjs
import { neon } from '@neondatabase/serverless';

export async function handler(event) {
  const sql = neon(process.env.DATABASE_URL);
  try {
    const rows = await sql`SELECT * FROM favorite_coffee_blends`;
    return {
      statusCode: 200,
      body: JSON.stringify(rows),
    };
  } catch (error) {
    return {
      statusCode: 500,
      body: JSON.stringify({ error: error.message }),
    };
  }
}
```

This function connects to the database and fetches the list of your favorite coffee blends.

### Implement the frontend

To make use of the `Function` implemented above, we will create a simple HTML page that fetches and displays the coffee information by calling the function.

Create a new file `index.html` at the root of your project with the following content:

```html
<!doctype html>
<html>
  <head>
    <title>Coffee Blends</title>
  </head>
  <body>
    <h1>My favourite coffee blends</h1>
    <ul id="blends"></ul>
    <script>
      (async () => {
        try {
          const response = await fetch('/.netlify/functions/get_coffee_blends');
          const blends = await response.json();
          const blendsList = document.getElementById('blends');
          blends.forEach((blend) => {
            const li = document.createElement('li');
            li.innerText = `${blend.name} - ${blend.notes}`;
            blendsList.appendChild(li);
          });
        } catch (error) {
          console.error('Error:', error);
        }
      })();
    </script>
  </body>
</html>
```

### Test the site locally

Set the `DATABASE_URL` environment variable in a `.env` file at the root of your project:

```text
DATABASE_URL=YOUR_NEON_CONNECTION_STRING
```

We are now ready to test our Netlify site project locally. Run the following command to start a local development server:

```bash
netlify dev
```

The Netlify CLI will print the local server URL where your site is running. Open the URL in your browser to see the coffee blends fetched from the database.

### Deploying your Netlify Site and Function

Deploying is straightforward with the Netlify CLI. However, we need to set the `DATABASE_URL` environment variable for the Netlify deployed site too. You can use the CLI to set it.

```bash
netlify env:set DATABASE_URL "YOUR_NEON_CONNECTION_STRING"
```

Now, to deploy your site and function, run the following command. When asked to provide a publish directory, enter `.` to deploy the entire project.

```bash
netlify deploy --prod
```

The CLI will build and deploy your site and functions to Netlify. After deployment, Netlify provides a URL for your live function. Navigate to the URL in your browser to check that the deployment was successful.

## Removing the example application and Neon project

For cleanup, delete your Netlify site and functions via the Netlify dashboard or CLI. Consult the [Netlify documentation](https://docs.netlify.com/) for detailed instructions.

To remove your Neon project, follow the deletion steps in Neon's documentation under [Manage Projects](https://neon.com/docs/manage/projects#delete-a-project).

## Resources

- [Netlify Functions](https://www.netlify.com/products/functions/)
- [Netlify CLI](https://docs.netlify.com/cli/get-started/)
- [Neon](https://neon.tech)

--- [Document source](https://neon.com/docs/guides/nextjs.md) ---

> Summary: Connection guide for wiring a Next.js application to Lakebase Postgres on Neon using node-postgres, postgres.js, or the Neon serverless driver (@neondatabase/serverless). Choose this page when you need working DATABASE_URL setup and driver code for App Router (Server Components, Server Actions), Pages Router (getServerSideProps, getStaticProps), Serverless Functions, or Edge Functions. The guide also explains how to query on every request with Next.js Cache Components (connection() and Suspense).

# Connect a Next.js application to Neon

Set up a Neon project in seconds and connect from a Next.js application

Last updated: 2026-10-08

**Realtime with Next.js:**

Build full-stack reactive apps with SSR and end-to-end type-safety using [Neon Realtime with Next.js](https://neon.com/docs/realtime/examples/nextjs).

Pre-built prompt for connecting Next.js applications to Neon [View prompt](https://neon.com/prompts/nextjs-prompt.md)

Next.js by Vercel is an open-source web development framework that enables React-based web applications. This topic describes how to create a Neon project and access it from a Next.js application.

## Video walkthrough

Watch **Getting started with Neon** for an end-to-end setup with Next.js and Drizzle.

[Watch on YouTube](https://youtube.com/watch?v=XtMiMnX0hDg)

To create a Neon project and access it from a Next.js application:

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Next.js project and add dependencies

1. Create a Next.js project if you do not have one. For instructions, see [Create a Next.js App](https://nextjs.org/docs/app/getting-started/installation), in the Vercel documentation. The examples in this guide are TypeScript, which `create-next-app` uses by default.

2. Add project dependencies using one of the following commands. If you're not sure which to use, use `@neondatabase/serverless`: it connects over HTTP instead of TCP, which works in Next.js Edge Functions and other environments without TCP support, and needs no extra SSL configuration.

   **node-postgres**

   ```shell
   npm install pg
   npm install -D @types/pg
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **Neon serverless driver (Recommended)**

   ```shell
   npm install @neondatabase/serverless
   ```

## Store your Neon credentials

Add a `.env.local` file to your project directory and add your Neon connection string to it. You can find your Neon database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

**Note:** `pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. If you use node-postgres, change `sslmode=require` to `sslmode=verify-full` to keep the current behavior and remove the warning.

## Configure the Postgres client

There are multiple ways to make server-side requests with Next.js. See below for the different implementations.

### App Router

There are two methods for fetching and mutating data using server-side requests in Next.js App Router:

1. `Server Components` fetch data on the server.
2. `Server Actions` run on the server to perform data mutations.

#### Server Components

New Next.js projects enable [Cache Components](https://nextjs.org/docs/app/getting-started/caching) (`cacheComponents: true` in `next.config.ts`). With Cache Components, Next.js prerenders pages at build time unless a component opts into request-time rendering. To query the database on every request, call [`connection()`](https://nextjs.org/docs/app/api-reference/functions/connection) before the query and wrap the component in `<Suspense>`, as in the examples below. Without these, `npm run build` fails with `Next.js encountered uncached data during prerendering`.

In your server components using the App Router, add the following code snippet to connect to your Neon database:

**node-postgres**

```tsx
import { Suspense } from 'react';
import { connection } from 'next/server';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

async function Version() {
  await connection();
  const client = await pool.connect();
  try {
    const { rows } = await client.query('SELECT version()');
    return <>{rows[0].version}</>;
  } finally {
    client.release();
  }
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Version />
    </Suspense>
  );
}
```

**postgres.js**

```tsx
import { Suspense } from 'react';
import { connection } from 'next/server';
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

async function Version() {
  await connection();
  const response = await sql`SELECT version()`;
  return <>{response[0].version}</>;
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Version />
    </Suspense>
  );
}
```

**Neon serverless driver (Recommended)**

```tsx
import { Suspense } from 'react';
import { connection } from 'next/server';
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);

async function Version() {
  await connection();
  const response = await sql`SELECT version()`;
  return <>{response[0].version}</>;
}

export default function Page() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <Version />
    </Suspense>
  );
}
```

If your project doesn't enable Cache Components, you can drop `connection()` and `<Suspense>` and add `export const dynamic = 'force-dynamic';` to the page instead. Don't use `dynamic` with Cache Components: the build fails with `Route segment config "dynamic" is not compatible with nextConfig.cacheComponents`. To cache query results instead of running them on every request, see [Caching](https://nextjs.org/docs/app/getting-started/caching) in the Next.js docs.

#### Server Actions

In your server actions using the App Router, add the following code snippet to connect to your Neon database:

**node-postgres**

```tsx
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export default function Page() {
  async function create(formData: FormData) {
    'use server';
    const client = await pool.connect();
    try {
      await client.query('CREATE TABLE IF NOT EXISTS comments (comment TEXT)');
      const comment = String(formData.get('comment'));
      await client.query('INSERT INTO comments (comment) VALUES ($1)', [comment]);
    } finally {
      client.release();
    }
  }
  return (
    <form action={create}>
      <input type="text" placeholder="write a comment" name="comment" />
      <button type="submit">Submit</button>
    </form>
  );
}
```

**postgres.js**

```tsx
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

export default function Page() {
  async function create(formData: FormData) {
    'use server';
    await sql`CREATE TABLE IF NOT EXISTS comments (comment TEXT)`;
    const comment = String(formData.get('comment'));
    await sql`INSERT INTO comments (comment) VALUES (${comment})`;
  }
  return (
    <form action={create}>
      <input type="text" placeholder="write a comment" name="comment" />
      <button type="submit">Submit</button>
    </form>
  );
}
```

**Neon serverless driver (Recommended)**

```tsx
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);

export default function Page() {
  async function create(formData: FormData) {
    'use server';
    await sql`CREATE TABLE IF NOT EXISTS comments (comment TEXT)`;
    const comment = String(formData.get('comment'));
    await sql`INSERT INTO comments (comment) VALUES (${comment})`;
  }
  return (
    <form action={create}>
      <input type="text" placeholder="write a comment" name="comment" />
      <button type="submit">Submit</button>
    </form>
  );
}
```

### Pages Router

There are two methods for fetching data using server-side requests in Next.js Pages Router:

1. `getServerSideProps` fetches data at runtime so that content is always fresh.
2. `getStaticProps` pre-renders pages at build time for data that is static or changes infrequently. The database must be reachable when you run `npm run build`.

#### getServerSideProps

From `getServerSideProps` using the Pages Router, add the following code snippet to connect to your Neon database:

**node-postgres**

```tsx
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function getServerSideProps() {
  const client = await pool.connect();
  try {
    const response = await client.query('SELECT version()');
    return { props: { data: response.rows[0].version } };
  } finally {
    client.release();
  }
}

export default function Page({ data }: { data: string }) {
  return <>{data}</>;
}
```

**postgres.js**

```tsx
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

export async function getServerSideProps() {
  const response = await sql`SELECT version()`;
  return { props: { data: response[0].version } };
}

export default function Page({ data }: { data: string }) {
  return <>{data}</>;
}
```

**Neon serverless driver (Recommended)**

```tsx
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);

export async function getServerSideProps() {
  const response = await sql`SELECT version()`;
  return { props: { data: response[0].version } };
}

export default function Page({ data }: { data: string }) {
  return <>{data}</>;
}
```

#### getStaticProps

From `getStaticProps` using the Pages Router, add the following code snippet to connect to your Neon database:

**node-postgres**

```tsx
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function getStaticProps() {
  const client = await pool.connect();
  try {
    const response = await client.query('SELECT version()');
    return { props: { data: response.rows[0].version } };
  } finally {
    client.release();
  }
}

export default function Page({ data }: { data: string }) {
  return <>{data}</>;
}
```

**postgres.js**

```tsx
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

export async function getStaticProps() {
  const response = await sql`SELECT version()`;
  return { props: { data: response[0].version } };
}

export default function Page({ data }: { data: string }) {
  return <>{data}</>;
}
```

**Neon serverless driver (Recommended)**

```tsx
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);

export async function getStaticProps() {
  const response = await sql`SELECT version()`;
  return { props: { data: response[0].version } };
}

export default function Page({ data }: { data: string }) {
  return <>{data}</>;
}
```

### Serverless Functions

From your Serverless Functions, add the following code snippet to connect to your Neon database:

**node-postgres**

```typescript
import type { NextApiRequest, NextApiResponse } from 'next';
import { Pool } from 'pg';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const client = await pool.connect();
  try {
    const { rows } = await client.query('SELECT version()');
    const { version } = rows[0];
    res.status(200).json({ version });
  } finally {
    client.release();
  }
}
```

**postgres.js**

```typescript
import type { NextApiRequest, NextApiResponse } from 'next';
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const response = await sql`SELECT version()`;
  const { version } = response[0];
  res.status(200).json({ version });
}
```

**Neon serverless driver (Recommended)**

```typescript
import type { NextApiRequest, NextApiResponse } from 'next';
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const response = await sql`SELECT version()`;
  const { version } = response[0];
  res.status(200).json({ version });
}
```

### Edge Functions

From your Edge Functions, add the following code snippet and connect to your Neon database using the [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver):

```typescript
import { neon } from '@neondatabase/serverless';

export const config = {
  runtime: 'edge',
};

const sql = neon(process.env.DATABASE_URL!);

export default async function handler(req: Request) {
  const response = await sql`SELECT version()`;
  const { version } = response[0];
  return Response.json({ version });
}
```

## Run the app

When you run `npm run dev` you can expect to see the following on `localhost:3000`:

```shell
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

## Connection issues

- If you see an `endpoint ID is not specified` error, the TLS client your Postgres driver depends on doesn't support Server Name Indication (SNI), which Neon uses to route connections. For `pg` (node-postgres), this means an outdated `libpq`-compatible TLS stack; upgrading `pg` usually resolves it.
- If you encounter an `SSL SYSCALL error: EOF detected` (or a similar connection-reset error), this typically happens when an application tries to reuse a connection after the Neon compute has been suspended due to inactivity. This mainly affects the `pg` and `postgres.js` examples above when used outside a serverless request lifecycle, since they can hold a connection open; reconnecting on error resolves it. `@neondatabase/serverless` isn't affected, since it opens a new HTTP connection per query.

### Where to upload and serve files?

Use [Object Storage](https://neon.com/docs/storage/overview), Neon's S3-compatible storage that branches with your database. To use an external provider instead, see [File storage](https://neon.com/docs/guides/file-storage).

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/quick-start/nextjs-api-only): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/examples/nextjs): Build realtime Next.js apps on Neon with SSR and end-to-end type safety

--- [Document source](https://neon.com/docs/guides/node.md) ---

> Summary: Step-by-step connection guide for Node.js, Express, and Next.js apps targeting a Lakebase Postgres database on Neon, with working code for three clients: the Neon serverless driver (@neondatabase/serverless), node-postgres (pg), and Postgres.js. Use this page when you need to wire up environment-variable-based SSL credentials and pick the right client for your project. Also covers the ENDPOINT_ID workaround required by older clients that lack SNI support, which newer node-postgres and Postgres.js releases do not need.

# Connect a Node.js application to Neon

Set up a Neon project in seconds and connect from a Node.js application

Last updated: 2026-09-16

Pre-built prompt for connecting Node.js applications to Neon. [View prompt](https://neon.com/prompts/javascript-prompt.md)

This guide describes how to create a Neon project and connect to it from a Node.js application. Examples are provided for the [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver), [node-postgres](https://www.npmjs.com/package/pg), and [Postgres.js](https://www.npmjs.com/package/postgres). Use the client you prefer.

**Note:** The same configuration steps can be used for Express and Next.js applications.

To connect to Neon from a Node.js application:

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Node.js project and add dependencies

1. Create a Node.js project and change to the newly created directory.

   ```shell
   mkdir neon-nodejs-example
   cd neon-nodejs-example
   npm init -y
   ```

2. Add project dependencies using one of the following commands:

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless dotenv
   ```

   **node-postgres**

   ```shell
   npm install pg dotenv
   ```

   **postgres.js**

   ```shell
   npm install postgres dotenv
   ```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection details to it. You can find your Neon database connection details by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Select Node.js from the **Connection string** dropdown. If you have a connection string instead (`postgresql://[user]:[password]@[neon_hostname]/[dbname]`), copy its parts into the matching variables. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
PGHOST='[neon_hostname]'
PGDATABASE='[dbname]'
PGUSER='[user]'
PGPASSWORD='[password]'
ENDPOINT_ID='[endpoint_id]'
```

**Note:** A special `ENDPOINT_ID` variable is included in the `.env` file above. This variable can be used with older Postgres clients that do not support Server Name Indication (SNI), which Neon relies on to route incoming connections. Its value is the first part of your `PGHOST` hostname, including `-pooler` if you use a pooled connection (for example, `ep-cool-darkness-123456-pooler`). If you are using a newer [node-postgres](https://node-postgres.com/) or [postgres.js](https://github.com/porsager/postgres) client, you won't need it. For more information, see [Endpoint ID variable](https://neon.com/docs/guides/node#endpoint-id-variable).

**Important:** To ensure the security of your data, never expose your Neon credentials to the browser.

## Configure the Postgres client

Add an `app.js` file to your project directory and add the following code snippet to connect to your Neon database:

**Neon serverless driver**

```javascript
require('dotenv').config();

const { neon } = require('@neondatabase/serverless');

const { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;

const sql = neon(
  `postgresql://${PGUSER}:${PGPASSWORD}@${PGHOST}/${PGDATABASE}?sslmode=require&channel_binding=require`
);

async function getPgVersion() {
  const result = await sql`SELECT version()`;
  console.log(result[0]);
}

getPgVersion();
```

**node-postgres**

```javascript
require('dotenv').config();

const { Pool } = require('pg');

const { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;

const pool = new Pool({
  host: PGHOST,
  database: PGDATABASE,
  user: PGUSER,
  password: PGPASSWORD,
  port: 5432,
  ssl: true,
});

async function getPgVersion() {
  const client = await pool.connect();
  try {
    const result = await client.query('SELECT version()');
    console.log(result.rows[0]);
  } finally {
    client.release();
    await pool.end();
  }
}

getPgVersion();
```

**postgres.js**

```javascript
require('dotenv').config();

// postgres.js 4 and later is ESM-only; .default returns the postgres function
const postgres = require('postgres').default;

const { PGHOST, PGDATABASE, PGUSER, PGPASSWORD } = process.env;

const sql = postgres({
  host: PGHOST,
  database: PGDATABASE,
  username: PGUSER,
  password: PGPASSWORD,
  port: 5432,
  ssl: 'require',
});

async function getPgVersion() {
  const result = await sql`select version()`;
  console.log(result[0]);
  await sql.end();
}

getPgVersion();
```

## Run app.js

Run `node app.js` to view the result.

```shell
{
  version: 'PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit'
}
```

## Endpoint ID variable

For older clients that do not support Server Name Indication (SNI), the `postgres.js` example below shows how to include the `ENDPOINT_ID` variable in your application's connection configuration. This is a workaround that is not required if you are using a newer [node-postgres](https://node-postgres.com/) or [postgres.js](https://github.com/porsager/postgres) client. For more information about this workaround and when it is required, see [The endpoint ID is not specified](https://neon.com/docs/connect/connection-errors#the-endpoint-id-is-not-specified).

```javascript
// app.js

require('dotenv').config();

const postgres = require('postgres').default;

const { PGHOST, PGDATABASE, PGUSER, PGPASSWORD, ENDPOINT_ID } = process.env;

const sql = postgres({
  host: PGHOST,
  database: PGDATABASE,
  username: PGUSER,
  password: PGPASSWORD,
  port: 5432,
  ssl: 'require',
  connection: {
    options: `endpoint=${ENDPOINT_ID}`,
  },
});

async function getPgVersion() {
  const result = await sql`select version()`;
  console.log(result[0]);
  await sql.end();
}

getPgVersion();
```

## Community resources

- [Serverless Node.js Tutorial – Neon Serverless Postgres, AWS Lambda, Next.js, Vercel](https://youtu.be/cxgAN7T3rq8)

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/nuxt.md) ---

> Summary: Connect Nuxt (Vue meta-framework) to serverless Postgres on Neon: use the Neon CLI to create the project and pull DATABASE_URL into your .env, then run SQL from a Nitro server route with the Neon serverless driver. Choose this guide when building a full-stack Nuxt app that needs server-side Postgres queries, covering CLI setup, driver selection (Neon serverless driver, node-postgres, or postgres.js), and reading the connection string in server code.

# Connect Nuxt to Postgres on Neon

Learn how to make server-side queries to Postgres using Nitro API routes

Last updated: 2026-10-08

Pre-built prompt for connecting Nuxt applications to Neon. [View prompt](https://neon.com/prompts/nuxt-neon-prompt.md)

[Nuxt](https://nuxt.com/) is an open-source full-stack meta framework that enables Vue-based web applications. This topic describes how to connect a Nuxt application to a Postgres database on Neon.

To create a Neon project and access it from a Nuxt.js application:

## Create a Neon project

Create a Neon project with the [Neon CLI](https://neon.com/docs/cli/install) or the Console.

**Neon CLI**

Install the CLI (`npm i -g neon`), then sign in and create the project:

```bash filename="Terminal"
neon login
neon projects create --name my-app
```

If you belong to more than one organization, the CLI prompts you to choose one. To skip the prompt, pass `--org-id <id>` (find it with `neon orgs list`).

You'll link this project and pull its credentials in a later step.

**Console**

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Nuxt project and add dependencies

1. Create a Nuxt project if you do not have one, then change into its directory. The scaffolder is interactive (it asks about the template, package manager, git, and modules); for CI or an AI agent, pass those as flags to run non-interactively. See [Create a Nuxt Project](https://nuxt.com/docs/getting-started/installation#new-project) for details. The CLI commands in the next step run from this directory.

   ```bash filename="Terminal"
   # Interactive (human):
   npm create nuxt@latest my-app && cd my-app

   # Non-interactive (CI / AI agents):
   npm create nuxt@latest my-app -- --template minimal --packageManager npm --no-gitInit --modules "" && cd my-app
   ```

2. Add a Postgres driver. This guide's examples use the Neon serverless driver, which suits serverless and edge deployments; for long-lived servers, `pg` or `postgres.js` are recommended. See [Choosing your connection method](https://neon.com/docs/connect/choose-connection).

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **node-postgres**

   ```shell
   npm install pg
   npm install -D @types/pg
   ```

## Store your Neon credentials

Get your `DATABASE_URL` into a `.env` file the app can read.

**Neon CLI**

From your project directory, link the app to your Neon project and pull its connection string:

```bash filename="Terminal"
neon link                    # connects this directory to your project (writes .neon)
neon env pull --file .env    # writes DATABASE_URL from your default branch into .env
```

Notes:

- Not signed in yet? Run `neon login` first.
- `neon link` prompts for an org and project. To skip the prompts, pass `--org-id <id>` and `--project-id <id>` (find IDs with `neon orgs list` and `neon projects list`), plus `--branch <name>` to pin a branch, or `-y` to pin the default branch.
- For Nuxt, pass in `--file .env` to `neon env pull` as it writes to `.env.local` by default, and `nuxt dev` only reads `.env` by default.
- Which branch? `neon env pull` uses your project's default branch: `main` for CLI-created projects, `production` for Console-created ones (`neon branches list` shows yours). To use a different branch, run `neon checkout <branch>` first; it re-pins the branch in `.neon` so the next `env pull` reads from it.

**Console**

Add a `.env` file and paste your connection string, which you can copy from the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell filename=".env"
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

## Configure the Postgres client

The connection string is a server-side secret, so query it from Nitro server code, which reads `process.env.DATABASE_URL` directly (no `runtimeConfig` needed).

Create a server utility that holds the database client. Use the tab for the driver you installed:

**Neon serverless driver**

```typescript filename="server/utils/db.ts"
import { neon } from '@neondatabase/serverless';

export const sql = neon(process.env.DATABASE_URL!);
```

**postgres.js**

```typescript filename="server/utils/db.ts"
import postgres from 'postgres';

export const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });
```

**node-postgres**

```typescript filename="server/utils/db.ts"
import pg from 'pg';

export const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
```

Then use it in a server API route. Files in `server/utils/` are auto-imported, so `sql` (or `pool`) is available without an import:

**Neon serverless driver**

```typescript filename="server/api/version.get.ts"
export default defineEventHandler(async () => {
  const [row] = await sql`SELECT version()`;
  return row;
});
```

**postgres.js**

```typescript filename="server/api/version.get.ts"
export default defineEventHandler(async () => {
  const [row] = await sql`SELECT version()`;
  return row;
});
```

**node-postgres**

```typescript filename="server/api/version.get.ts"
export default defineEventHandler(async () => {
  const { rows } = await pool.query('SELECT version()');
  return rows[0];
});
```

To type-check the server code with `npx nuxt typecheck`, install `typescript`, `vue-tsc`, and `@types/node` as dev dependencies (`npm install -D typescript vue-tsc @types/node`).

If you use node-postgres, `pg` 8.23 and later print a `SECURITY WARNING` for `sslmode=require`. Change it to `sslmode=verify-full` in `.env` to keep the same behavior without the warning.

**Note:** Keep the database client in `server/` only. Never import `server/utils/db.ts` from a Vue component or `app/` code; the connection string must stay server-side.

## Run the app

Start the dev server:

```bash filename="Terminal"
npm run dev
```

Then open `localhost:3000/api/version`. The route returns your Postgres version, confirming the connection:

```json
{ "version": "PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc ..." }
```

`nuxt dev` loads `.env`, but the production server doesn't. After `npm run build`, start it with the variable in its environment, for example `node --env-file=.env .output/server/index.mjs`.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/quickstart): Build realtime apps with end-to-end reactivity »

--- [Document source](https://neon.com/docs/guides/oauth-integration.md) ---

> Summary: Neon OAuth integration lets partner applications act on Neon user accounts without storing credentials, using an OpenID Connect server at oauth2.neon.tech with predefined project and organization scopes. Use this page when building a third-party integration that must read, create, update, or delete Neon projects and organizations on behalf of end users via the authorization code grant flow. Access is limited to active Neon commercial partners. The page covers the consent screen, authorization URL construction, code-for-token exchange, and refresh token scopes.

# Neon OAuth integration

Last updated: 2026-07-15

The Neon OAuth integration enables your application to interact with Neon user accounts, carrying out permitted actions on their behalf. Our integration does not require direct access to user login credentials and is conducted with their approval, ensuring data privacy and security.

**Note:** We only provide OAuth integrations for partners we have active commercial relationships with. If you already partner with Neon, the information below documents our OAuth integration. Reach out to your Neon point of contact if you have any questions.

## How the OAuth integration works

Here is a high-level overview of how Neon's OAuth implementation works:

![OAuth flow diagram](https://neon.com/docs/oauth/flow.png)

1. The user sends a request to your API endpoint to initiate the OAuth flow by clicking a button or link in your application.
2. An authorization URL is generated.
3. The user is redirected to Neon's OAuth consent screen to authorize the application.
4. The user logs in and authorizes the application, granting it the necessary permissions.
5. The user is redirected to your callback endpoint with an access token that allows the application to manage Neon resources on the user's behalf.

## About the Neon OAuth server

The Neon OAuth server implements the OpenID Connect protocol and supports [OpenID Connect Discovery specification](https://openid.net/specs/openid-connect-discovery-1_0.html). The server metadata is published at the following well-known URL: [https://oauth2.neon.tech/.well-known/openid-configuration](https://oauth2.neon.tech/.well-known/openid-configuration).

Here is an example response:

```json
{
  "issuer": "https://oauth2.neon.tech/",
  "authorization_endpoint": "https://oauth2.neon.tech/oauth2/auth",
  "token_endpoint": "https://oauth2.neon.tech/oauth2/token",
  "jwks_uri": "https://oauth2.neon.tech/.well-known/jwks.json",
  "subject_types_supported": ["public"],
  "response_types_supported": [
    "code",
    "code id_token",
    "id_token",
    "token id_token",
    "token",
    "token id_token code"
  ],
  "claims_supported": ["sub"],
  "grant_types_supported": [
    "authorization_code",
    "implicit",
    "client_credentials",
    "refresh_token"
  ],
  "response_modes_supported": ["query", "fragment"],
  "userinfo_endpoint": "https://oauth2.neon.tech/userinfo",
  "scopes_supported": ["offline_access", "offline", "openid"],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic",
    "private_key_jwt",
    "none"
  ],
  "userinfo_signing_alg_values_supported": ["none", "RS256"],
  "id_token_signing_alg_values_supported": ["RS256"],
  "request_parameter_supported": true,
  "request_uri_parameter_supported": true,
  "require_request_uri_registration": true,
  "claims_parameter_supported": false,
  "revocation_endpoint": "https://oauth2.neon.tech/oauth2/revoke",
  "backchannel_logout_supported": true,
  "backchannel_logout_session_supported": true,
  "frontchannel_logout_supported": true,
  "frontchannel_logout_session_supported": true,
  "end_session_endpoint": "https://oauth2.neon.tech/oauth2/sessions/logout",
  "request_object_signing_alg_values_supported": ["RS256", "none"],
  "code_challenge_methods_supported": ["plain", "S256"]
}
```

**Note:** You must add `offline` and `offline_access` scopes to your request to receive the `refresh_token`.

Depending on the OpenID client you're using, you might not need to explicitly interact with the API endpoints listed below. OAuth 2.0 clients typically handle this interaction automatically. For example, the [Neon CLI](https://neon.com/docs/cli), written in Typescript, interacts with the API endpoints automatically to retrieve the `refresh_token` and `access_token`. Here's a simplified example of how the Neon CLI performs the token exchange using the `openid-client` library:

```typescript
const configuration = await client.discovery(
  new URL(oauthHost),
  clientId,
  { token_endpoint_auth_method: 'none' },
  client.None()
);

// After the user authenticates in the browser, the CLI's local
// callback server receives the redirect as `request`. The full
// callback URL is built from that request plus the server's own
// port (`listen_port`):
const tokenSet = await client.authorizationCodeGrant(
  configuration,
  new URL(request.url, `http://127.0.0.1:${listen_port}`),
  {
    pkceCodeVerifier: codeVerifier,
    expectedState: state,
  }
);
// tokenSet.access_token and tokenSet.refresh_token are now available
```

In this example, the `oauthHost` is `https://oauth2.neon.tech`.

## Supported OAuth Scopes

The following OAuth scopes allow varying degrees of access to Neon resources:

| **Project scopes** | **Scope Name**                      |
| :----------------- | :---------------------------------- |
| Create Projects    | `urn:neoncloud:projects:create`     |
| Read Projects      | `urn:neoncloud:projects:read`       |
| Modify Projects    | `urn:neoncloud:projects:update`     |
| Delete Projects    | `urn:neoncloud:projects:delete`     |
| Manage Projects    | `urn:neoncloud:projects:permission` |

| **Organization scopes**         | **Scope Name**                  |
| :------------------------------ | :------------------------------ |
| Create Organizations            | `urn:neoncloud:orgs:create`     |
| Read Organizations              | `urn:neoncloud:orgs:read`       |
| Update Organizations            | `urn:neoncloud:orgs:update`     |
| Delete Organizations            | `urn:neoncloud:orgs:delete`     |
| Manage Organization Permissions | `urn:neoncloud:orgs:permission` |

You must choose from these predefined scopes when requesting access; custom scopes are not supported.

Let's now go through the full flow, step by step:

## Initiating the OAuth flow

To initiate the OAuth flow, you need to generate an authorization URL. You can do that by directing your users to `https://oauth2.neon.tech/oauth2/auth` while passing the following query parameters:

- `client_id`: your OAuth application's ID (provided by Neon when your OAuth application is registered)

- `redirect_uri`: the full URL that Neon should redirect users to after authorizing your application. The URL should match at least one of the callback URLs you provided when setting up your OAuth application.

- `scope`: This is a space-separated list of predefined scopes that define the level of access you want to request. For a full list of supported scopes and their meanings, see the [Supported OAuth Scopes](https://neon.com/docs/guides/oauth-integration#supported-oauth-scopes) section.

  **Example:**

  ```text
  urn:neoncloud:projects:create urn:neoncloud:projects:read urn:neoncloud:projects:update urn:neoncloud:projects:delete urn:neoncloud:orgs:read
  ```

- `response_type`: This should be set to `code` to indicate that you are using the [Authorization Code grant type](https://oauth.net/2/grant-types/authorization-code/).

- `code_challenge`: This is a random string that is used to verify the integrity of the authorization code.

- `state`: This is a random string that is returned to your callback URL. You can use this parameter to verify that the request came from your application and not from a third party.

## Authorization URL

Here is an example of what the authorization URL might look like:

```text
https://oauth2.neon.tech/oauth2/auth?client_id=neon-experimental&scope=openid%20offline%20offline_access%20urn%3Aneoncloud%3Aprojects%3Acreate%20urn%3Aneoncloud%3Aprojects%3Aread%20urn%3Aneoncloud%3Aprojects%3Aupdate%20urn%3Aneoncloud%3Aprojects%3Adelete&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fapi%2Fauth%2Fcallback%2Fneon&grant_type=authorization_code&state=H58y-rSTebc3QmNbRjNTX9dL73-IyoU2T_WNievO9as&code_challenge=99XcbwOFU6iEsvXr77Xxwsk9I0GL4c4c4Q8yPIVrF_0&code_challenge_method=S256
```

## OAuth consent screen

After being redirected to the authorization URL, the user is presented with Neon's OAuth consent screen, which is pre-populated with the scopes you requested. From the consent screen, the user is able to review the scopes and authorize the application to connect their Neon account.

![Neon OAuth consent screen](https://neon.com/docs/oauth/consent.png)

**Note:** The [Neon API](https://neon.com/docs/reference/api) provides a [Get current user details](https://neon.com/docs/reference/api/users/get-current-user-info) endpoint for retrieving information about the currently authorized Neon user.

## Authorization code is returned to your callback URL

After successfully completing the authorization flow, the user is redirected to the callback URL with the following query parameters appended to the URL:

- `code`: an authorization code that will be exchanged for an access token
- `scope`: the scopes that the user authorized your application to access
- `state`: you can compare the value of this parameter with the original `state` you provided in the previous step to ensure that the request came from your application and not from a third party

## Exchanging the authorization code for an access token

You can now exchange the authorization code returned from the previous step for an access token. To do that, you need to send a `POST` request to `https://oauth2.neon.tech/oauth2/token` with the following parameters:

- `client_id`: your OAuth application's ID.
- `redirect_uri`: the full URL that Neon should redirect users to after authorizing your application. The URL should match at least one of the callback URLs you provided when setting up your OAuth application.
- `client_secret`: your OAuth application's secret
- `grant_type`: set this to `authorization_code` to indicate that you are using the [Authorization Code grant type](https://oauth.net/2/grant-types/authorization-code/)
- `code`: the authorization code returned from the previous step

The response object includes an `access_token` value, required for making requests to the [Neon API](https://neon.com/docs/reference/api) on your users' behalf. This value must be supplied in the Authorization header of the HTTP request when sending requests to the Neon API.

## Example OAuth application

For a complete working example of a Neon OAuth integration, check out the **Neon Branches Visualizer** application. This app demonstrates how to:

- Implement the OAuth flow with Neon
- Handle user authorization and token exchange
- Make authenticated API requests to manage Neon resources
- Build a user-friendly interface for Neon account management

* [View live demo](https://neon-experimental.vercel.app): Try the live demo application
* [View on GitHub](https://github.com/neondatabase/neon-branches-visualizer): Explore the source code and implementation

The source code provides a practical reference for implementing OAuth with Neon in your own applications.

--- [Document source](https://neon.com/docs/guides/opentelemetry.md) ---

> Summary: Neon's OpenTelemetry integration exports Postgres metrics and logs to any OTLP-compatible platform, including Grafana OSS, Grafana Cloud, New Relic, and Honeycomb, using HTTP or gRPC transport. Use this page when you need to forward connection counts, CPU, memory, replication lag, or Postgres log events to an external observability backend. Configuration requires only a base OTLP endpoint URL and auth credentials. Neon automatically appends signal-specific paths (/v1/metrics, /v1/logs) and collects data from all computes in a project.

# OpenTelemetry

Send Neon metrics and Postgres logs to any OTEL-compatible observability platform

Last updated: 2026-10-23

**Note: Beta**

**OpenTelemetry integration** is in beta. Share your feedback on [Discord](https://neon.com/discord) or via the [Neon Console](https://console.neon.tech/app/projects?modal=feedback).

**What you will learn:**

- How to configure OpenTelemetry exports from Neon
- Setup with Grafana OSS and Tempo
- Integration with Grafana Cloud
- Example config using New Relic

**External docs**

- [OpenTelemetry Protocol (OTLP) Specification](https://opentelemetry.io/docs/specs/otlp/)
- [Grafana Labs OpenTelemetry Documentation](https://grafana.com/docs/opentelemetry/)
- [New Relic OpenTelemetry guide](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/)

Available for Scale plan users, the Neon OpenTelemetry integration lets you export metrics and Postgres logs to any OpenTelemetry Protocol (OTLP) compatible observability platform. This gives you the flexibility to send your Neon data to your preferred monitoring solution, whether that's New Relic, Grafana Cloud, Honeycomb, or any other OTEL-compatible service.

## How it works

The integration uses the OpenTelemetry Protocol (OTLP) to securely transmit Neon metrics and Postgres logs to your chosen destination. By configuring the integration with your OTEL endpoint and authentication credentials, Neon automatically sends data from all computes in your project.

**Note:** Data is sent for all computes in your Neon project. For example, if you have multiple branches, each with an attached compute, both metrics and logs will be collected and sent for each compute.

### Neon metrics

The integration exports a comprehensive set of metrics including:

- **Connection counts** — Tracks active and idle database connections.
- **Database size** — Monitors total size of all databases in bytes.
- **Replication delay** — Measures replication lag in bytes and seconds.
- **Compute metrics** — Includes CPU and memory usage statistics for your compute.

### Postgres logs

**Note: Beta**

**Postgres logs export** is in beta. Share your feedback on [Discord](https://neon.com/discord) or via the [Neon Console](https://console.neon.tech/app/projects?modal=feedback).

The Neon OpenTelemetry integration can forward Postgres logs to your destination platform. These logs provide visibility into database activity, errors, and performance.

## Prerequisites

Before getting started, ensure the following:

- You have a Neon account and project. If not, see [Sign up for a Neon account](https://neon.com/docs/get-started/signing-up).
- You have an OpenTelemetry-compatible observability platform account and know your OTLP endpoint URL and authentication credentials (API key, bearer token, or basic auth).

## Set up your observability platform

Choose your preferred observability platform and follow the setup instructions:

### Grafana OSS with Docker OTEL LGTM

For a cost-effective, open-source monitoring stack, you can set up the complete LGTM stack (Loki for logs, Grafana for visualization, Tempo for traces, and Mimir for metrics) with OpenTelemetry integration.

**Quick setup with Docker:**

1. **Clone and start the stack**:
   ```bash
   git clone https://github.com/grafana/docker-otel-lgtm.git
   cd docker-otel-lgtm
   docker compose up -d
   ```

This provides:

- **Grafana** at [http://localhost:3000](http://localhost:3000) (admin/admin)
- **OpenTelemetry Collector** at [http://localhost:4318](http://localhost:4318) (HTTP) and localhost:4317 (gRPC)
- **Prometheus/Mimir**, **Loki**, and **Tempo** for complete observability

For detailed configuration, see the [docker-otel-lgtm documentation](https://github.com/grafana/docker-otel-lgtm).

### Grafana Cloud

For a fully managed solution, see the dedicated [Grafana Cloud integration guide](https://neon.com/docs/guides/grafana-cloud).

### New Relic

If you use New Relic, you'll need to sign up for an account and get your license key.

1. Sign up for a free account at [newrelic.com](https://newrelic.com) if you haven't already.
2. Once signed in, you'll need your New Relic license key for authentication.

   If you're onboarding for the first time, copy the license key when it's offered to you (this is your **Original account** key).

   **Tip:** If you get stuck in New Relic's onboarding screens and don't see a way to proceed, try opening the Logs or Data Explorer pages in a new browser tab. This can sometimes let you access the main New Relic UI and continue with your setup.

   If you missed copying your license key during onboarding, you can create a new one: choose **Ingest - License** as the type.

   <details>

   <summary>Create New Relic license key</summary>

   1. Click on your user menu in the bottom left corner.
   2. Select **API Keys** from the menu.

   ![New Relic profile menu showing API Keys option](https://neon.com/docs/guides/new_relic_api_keys.png) 3. Click **Create a key** → choose **Ingest - License**. Copy the key immediately (you can't view it again later).

   ![New Relic API Keys page showing license key types](https://neon.com/docs/guides/new_relic_copy_key.png)

   Your license key will look something like `eu01xxaa1234567890abcdef1234567890NRAL` (the format varies by region).

   </details>

## Open the OpenTelemetry integration

1. In the Neon Console, navigate to the **Integrations** page in your Neon project.
2. Locate the **OpenTelemetry** card and click **Add**.

   ![open telemetry integration card](https://neon.com/docs/guides/open_telemetry_card.png)

   The sidebar form opens for you to enter your platform's details.

   ![OpenTelemetry integration configuration form](https://neon.com/docs/guides/opentelemetry_config_form.png)

## Select data to export

Choose what data you want to export (at the top of the form):

- **Metrics**: System metrics and database statistics (CPU, memory, connections, etc.)
- **Postgres logs**: Error messages, warnings, connection events, and system notifications

You can enable either or both options based on your monitoring needs.

## Configure the connection

1. **Select your connection protocol**: For most platforms, choose **HTTP** (recommended), which uses HTTP/2 for efficient data transmission. Some environments may require **gRPC** instead.

2. **Enter your Endpoint URL** based on your platform:

   **For Grafana OSS (docker-otel-lgtm)**:

   - `http://localhost:4318` (if running locally)
   - `http://your-server-ip:4318` (if running on a remote server)

   **For Grafana Cloud**:

   - Use your Grafana Cloud OTLP endpoint (typically `https://otlp-gateway-{region}.grafana.net/otlp`)
   - See the [Grafana Cloud guide](https://neon.com/docs/guides/grafana-cloud) for details

   **For New Relic**:

   - US: `https://otlp.nr-data.net`
   - Europe: `https://otlp.eu01.nr-data.net`
   - See [New Relic's endpoint documentation](https://docs.newrelic.com/docs/opentelemetry/best-practices/opentelemetry-otlp/#configure-endpoint-port-protocol) for other regions

   **Note:**

   When you configure an OTLP endpoint URL in Neon, you should provide only the **base URL** of your collector or observability platform. The OpenTelemetry Collector automatically appends the correct signal-specific paths:

   - `/v1/metrics` for metrics
   - `/v1/logs` for logs
   - `/v1/traces` for traces

   For example, if you enter:

   ```
   https://dev-thanos-receive.example.com/api/v1/otlp
   ```

   the Collector will send requests to:

   ```
   https://dev-thanos-receive.example.com/api/v1/otlp/v1/metrics
   ```

   and

   ```
   https://dev-thanos-receive.example.com/api/v1/otlp/v1/logs
   ```

   Make sure your observability platform is configured to receive data at these appended paths. If your platform expects data directly at the base URL without suffixes, you may need to adjust the configuration on that side.

3. Configure authentication:

   **For Grafana OSS**:

   - No authentication required for local docker setup

   **For Grafana Cloud**:

   - Use **Basic** authentication with Base64 encoded `<opentelemetry-instance-id>:<grafana-cloud-token>`
   - Get your instance ID and API token from the Grafana Cloud Portal by clicking on the **OpenTelemetry** card

   **For New Relic**:

   - Use **Bearer** or **API Key** with your New Relic license key

   **For other platforms**: Choose the appropriate method:

   - **Bearer**: Enter your bearer token or API key
   - **Basic**: Provide your username and password credentials
   - **API Key**: Enter your API key. You can optionally set a **Custom header name** for the key; it defaults to `X-API-Key` if not specified. Some backends (for example, Honeycomb) expect a different header name, so use this option to match your platform's requirements.

## Configure resource attributes

In the **Resource** section, set the `service.name` attribute to the name your Postgres logs should appear under in your observability platform, such as `neon-postgres-production`.

Logs are event messages; metrics are numeric values sampled over time. This name labels your logs only. Metrics are not tagged with it; they arrive under fixed, Neon-assigned service names. Your data appears as follows:

| Data             | Service name                   | Includes                                                            |
| ---------------- | ------------------------------ | ------------------------------------------------------------------- |
| Postgres logs    | Your configured `service.name` | Errors, warnings, connection events, and other Postgres activity    |
| Database metrics | `sql-metrics`                  | Connections, database size, replication delay, and other statistics |
| Compute metrics  | `compute-host-metrics`         | CPU, memory, and load                                               |

The metric service names are also exposed as the `job` label on each metric.

`service.name` is the only resource attribute Neon exports. Custom resource attributes and custom request headers are not currently supported.

## Complete the setup

Click **Add** to save your configuration and start the data export.

**Tip:** You can edit your integration settings at any time from the **Integrations** page in the Neon Console. This allows you to update your endpoint URL, change authentication credentials, or modify resource attributes without having to delete and recreate the integration. If you change the endpoint URL, protocol, or an endpoint override, enter your authentication credentials again. Neon doesn't reuse stored credentials for a new destination.

## Verify your integration is working

Your Neon data should start appearing in your observability platform within a few minutes.

### For Grafana (OSS and Cloud) users

1. **Access Grafana Explore**: Visit `http://localhost:3000` (admin/admin) or your Grafana Cloud Instance and navigate to **Explore**

2. **Check metrics**: Select your **Prometheus** data source and use this query to check if data is flowing::

   ```promql
   neon_connection_counts
   ```

3. **Create dashboards**: You can visualize using [Grafana Drilldown apps](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/) or use the dashboard JSON from [Grafana Cloud Documentation](https://neon.com/docs/guides/grafana-cloud#create-a-monitoring-dashboard)

### For New Relic users

Use these queries to check if data is flowing:

```sql
FROM Metric SELECT * SINCE 1 hour ago
FROM Log SELECT * SINCE 1 hour ago
```

**Success looks similar to this:**

_Metrics flowing into New Relic_
![Neon metrics appearing in New Relic](https://neon.com/docs/guides/new_relic_metrics_success.png)

_Postgres logs flowing into New Relic_
![Neon PostgreSQL logs appearing in New Relic](https://neon.com/docs/guides/new_relic_logs_success.png)

**Find your data under APM & Services**
![Multiple Neon services in New Relic APM & Services](https://neon.com/docs/guides/new_relic_services.png)

- **Logs**: Check your configured service name in APM & Services (for example, `neon-postgres-production`)
- **Metrics**: Look for the auto-created `compute-host-metrics` and `sql-metrics` services. Metrics are not tagged with your configured `service.name`; see [Configure resource attributes](https://neon.com/docs/guides/opentelemetry#configure-resource-attributes).

**Note:** You can modify these settings later by editing your integration configuration from the **Integrations** page.

**Note:** Neon computes only send logs and metrics when they are active. If the [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero) feature is enabled and a compute is suspended due to inactivity, no logs or metrics will be sent during the suspension. This may result in gaps in your data. If you notice missing data, check if your compute is suspended. You can verify a compute's status as `Idle` or `Active` on the **Branches** page in the Neon console, and review **Suspend compute** events on the **System operations** tab of the **Monitoring** page.

Additionally, if you are setting up the OpenTelemetry integration for a project with an inactive compute, you'll need to activate the compute before it can send data. To activate it, simply run a query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any connected client.

## Troubleshooting

- **Data isn't appearing in your observability platform**
  1. **Verify your endpoint URL** - Ensure the OTLP endpoint URL is correct for your platform.
  2. **Check authentication** - Verify that your API key, bearer token, or credentials are valid and have the necessary permissions.
  3. **Confirm compute activity** - Make sure your Neon compute is active and running queries.
  4. **Review platform-specific requirements** - Some platforms may have specific configuration requirements for OTLP data ingestion.

- **404 errors on OTLP endpoint**

  If you see errors like the following in your logs:

  ```bash
  Exporting failed. Dropping data. {"error": "not retryable error: Permanent error: rpc error: code = Unimplemented desc = error exporting items, request to https://example.com/otlp/v1/metrics responded with HTTP Status Code 404"}
  ```

  This usually means your observability platform is not accepting data on the signal-specific paths automatically appended by the OpenTelemetry Collector.

  The Collector appends these suffixes to the base URL you configure:

  - `/v1/metrics` for metrics
  - `/v1/logs` for logs
  - `/v1/traces` for traces

  **How to fix:**

  - Double-check that your platform supports OTLP ingestion on these paths.
  - If your platform expects data directly at the base URL without suffixes, you may need to change its configuration or use a compatible OTLP gateway.

## Available metrics

Neon exports a comprehensive set of metrics including system metrics (CPU, RAM), database metrics (connections, rows, deadlocks), and PgBouncer connection pooling metrics (client and server connections).

For a complete list of all metrics and log fields exported by Neon, see the [Metrics and logs reference](https://neon.com/docs/reference/metrics-logs).

--- [Document source](https://neon.com/docs/guides/phoenix.md) ---

> Summary: Connecting a Phoenix (Elixir) application to Neon requires configuring Ecto with SSL certificate verification, which recent Postgrex releases enforce by default using the `:cacerts` or `:cacertfile` option. Use this page when setting up a new or existing Phoenix project with Neon, covering project creation, DATABASE_URL credential storage, and config updates for dev, test, and runtime environments.

# Connect from Phoenix to Neon

Set up a Neon project in seconds and connect from Phoenix

Last updated: 2026-09-16

Pre-built prompt for connecting Phoenix applications to Lakebase Postgres [View prompt](https://neon.com/prompts/phoenix-prompt.md)

This guide describes how to connect Neon in a [Phoenix](https://www.phoenixframework.org) application. [Ecto](https://hexdocs.pm/ecto/3.11.2/Ecto.html) provides an API and abstractions for interacting databases, enabling Elixir developers to query any database using similar constructs.

It is assumed that you have a working installation of [Elixir](https://elixir-lang.org/install.html) 1.15 or later.

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details, including your password. You need them when you configure the app and start the server.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Store your Neon credentials

Copy your connection string. You can find it by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```text
postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require
```

You pass this value to the app as the `DATABASE_URL` environment variable when you start the server in production.

You will need the connection string details later in the setup.

## Create a Phoenix project

[Create a Phoenix project](https://hexdocs.pm/phoenix/installation.html#phoenix) if you do not have one:

```bash
# install phx.new if you haven't already
# mix archive.install hex phx_new
mix phx.new hello
```

When prompted, choose to not install the dependencies yet.

## Configure database connections

Update the following configuration files with your database connection details from the connection string you copied earlier.

1. Update `config/dev.exs`:

   ```elixir {2-5,9}
   config :hello, Hello.Repo,
      username: "[user]",
      password: "[password]",
      hostname: "[neon_hostname]",
      database: "neondb",
      stacktrace: true,
      show_sensitive_data_on_connection_error: true,
      pool_size: 10,
      ssl: [cacerts: :public_key.cacerts_get()]
   ```

   **Note:** The `:ssl` option is required to connect to the database. Postgrex, since v0.18, verifies the server SSL certificate and you need to select CA trust store using `:cacerts` or `:cacertfile` options. You can use the OS-provided CA store by setting `cacerts: :public_key.cacerts_get()`. While not recommended, you can disable certificate verification by setting `ssl: [verify: :verify_none]`.

2. Update `config/runtime.exs`:

   ```elixir {2}
   config :hello, Hello.Repo,
      ssl: [cacerts: :public_key.cacerts_get()],
      url: database_url,
      pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
      socket_options: maybe_ipv6
   ```

3. Update `config/test.exs`:

   ```elixir {2,3,4,8}
   config :hello, Hello.Repo,
      username: "[user]",
      password: "[password]",
      hostname: "[neon_hostname]",
      database: "with_phoenix_test#{System.get_env("MIX_TEST_PARTITION")}",
      pool: Ecto.Adapters.SQL.Sandbox,
      pool_size: System.schedulers_online() * 2,
      ssl: [cacerts: :public_key.cacerts_get()]
   ```

   **Tip:** This guide configures the test environment for completeness but doesn't cover running tests. For production workflows, consider using [Neon branches](https://neon.com/docs/introduction/branching) instead of a separate test database. Branches provide isolated, cost-effective copies of your database that are ideal for testing and CI/CD pipelines.

## Install dependencies and create databases

1. Install the dependencies:

   ```bash
   mix deps.get
   ```

2. Create the development and test databases:

   ```bash
   mix ecto.create
   MIX_ENV=test mix ecto.create
   ```

   The first command creates the development database (`neondb`). The second creates the test database (`with_phoenix_test`).

## Build and run the Phoenix application

To compile the app in production mode, run the following command:

```bash
MIX_ENV=prod mix compile
```

To compile assets for the production mode, run the following command:

```bash
MIX_ENV=prod mix assets.deploy
```

For each deployment, a secret key is required for encrypting and signing data. Run the following command to generate the key:

```bash
mix phx.gen.secret
```

When you run the following command, you can expect to see the Phoenix application at [http://localhost:4001](http://localhost:4001):

```bash
PORT=4001 \
MIX_ENV=prod \
PHX_HOST=localhost \
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/neondb?sslmode=require&channel_binding=require" \
SECRET_KEY_BASE=".../..." \
mix phx.server
```

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/platform-integration-overview.md) ---

> Summary: Neon platform integration overview compares four embedding and partnership paths: AI Agents, Claimable Database, Embedded Postgres, and OAuth. Use this page to decide which approach fits your product before reading the individual integration guides. Real-world implementations include TanStack Vite plugin, Netlify DB, and Hasura Cloud.

# Integrating with Neon

Choose the right integration path for your platform or application

Last updated: 2026-10-26

Neon provides multiple options for integrating Postgres into your platform, application, or service. Choose the integration approach that best matches your use case.

## AI Agents integration

**Best for:** AI agent and codegen platforms that need database versioning and isolated environments

Use this approach if you're building an AI agent platform or code generation service where agents create and manage databases programmatically. This integration includes everything from the embedded Postgres approach, plus specific features for agent workflows.

**Key features:**

- Two-organization structure (free tier sponsored by Neon, paid tier for your paying users)
- Database versioning with snapshots and point-in-time recovery
- Isolated development environments per user
- Project transfers between organizations when users upgrade
- Agent-specific pricing and rate limits
- Dedicated support channel

**Example use cases:**

- AI agent platforms
- Code generation platforms
- LLM-powered development tools
- Autonomous database management tools

* [Agent plan](https://neon.com/docs/introduction/agent-plan): Learn about the Neon Agent plan and how to enroll
* [AI Agent integration guide](https://neon.com/docs/guides/ai-agent-integration): Learn about the agent-specific integration
* [Database versioning](https://neon.com/docs/ai/ai-database-versioning): Learn about database versioning for AI agents

---

## Claimable database flow

**Best for:** Plugins and platforms that want to offer instant database provisioning as part of their developer experience without requiring user signup

Use this approach when you want to create databases for your users without requiring them to create a Neon account first. Users receive a connection string immediately and can optionally claim ownership of the database later by creating a Neon account. This is ideal for CLI tools, framework plugins, and platforms that want to streamline onboarding.

**Key features:**

- Instant database provisioning with no user signup required
- 72-hour database lifespan if not claimed
- Seamless ownership transfer when users are ready
- Claiming moves the project into the user's organization. neon.new keeps the connection string; Claimable Neon rotates `DATABASE_URL`
- Configurable transfer request expiration

**Example use cases:**

- Framework plugins and CLI tools (like TanStack's Vite plugin)
- Demo environments and trial experiences
- Educational platforms providing databases to students
- Development tools that need instant database access
- SaaS applications with deferred account creation
- AI agents requiring database access without authentication overhead

**Example implementations:**

- [TanStack](https://neon.com/blog/neon-joins-tanstack-instant-postgres-integration-for-faster-javascript-development): Official database partner offering instant Postgres through their Vite plugin and create-tanstack CLI
- [Netlify DB](https://www.netlify.com/blog/netlify-db-database-for-ai-native-development/): One-click Postgres databases for Netlify projects, built on the claimable database flow
- [Claimable Neon](https://neon.com/claimable-neon): instant Neon project without signup, via the Neon CLI or [auth.md](https://neon.com/auth.md)

* [Claimable database guide](https://neon.com/docs/workflows/claimable-database-integration): Learn how to implement claimable databases
* [Claimable Neon documentation](https://neon.com/docs/reference/claimable-neon): See Claimable Neon implementation details

---

## Embedded Postgres integration

**Best for:** SaaS platforms and services that offer Postgres databases to their users

Use the embedded Postgres approach when you want to provision and manage Postgres databases on behalf of your users as part of your platform's offering. This is the **project-per-user model** where you create isolated Neon projects for each of your users via the Neon API.

**Key features:**

- Instant database provisioning (< 1 second)
- Complete data isolation per user
- Scale-to-zero for cost efficiency
- Configure consumption limits per user
- Track usage for billing
- Full API control over resources

**Example use cases:**

- SaaS platforms offering Postgres as a feature
- Low-code/no-code platforms
- Development platforms
- Enterprise platforms requiring isolated databases per customer

* [Embedded Postgres guide](https://neon.com/docs/guides/embedded-postgres): Learn how to embed Postgres in your platform
* [Neon API Reference](https://neon.com/docs/reference/api): Explore the Neon API

---

## OAuth integration

**Best for:** Tools and applications that need to interact with existing Neon user accounts

Use OAuth when you're building a tool or service that connects to existing Neon accounts. Your application will interact with user accounts and perform authorized actions like creating, reading, and modifying Neon database projects on their behalf, without requiring direct access to user credentials.

**Key features:**

- Secure, user-authorized access to Neon accounts
- Access control through OAuth scopes
- Users maintain full ownership of their Neon accounts

**Example use cases:**

- Database management tools
- Monitoring and observability platforms
- CI/CD integrations that connect to existing Neon projects
- Tools that visualize or analyze Neon resources

**Example implementation:**

- [Hasura Cloud](https://hasura.io/): Uses OAuth to seamlessly authenticate users and provision Neon databases from Hasura projects

* [OAuth integration guide](https://neon.com/docs/guides/oauth-integration): Learn how to integrate with Neon using OAuth
* [Example OAuth app](https://github.com/neondatabase/neon-branches-visualizer): See a working OAuth integration example

## Built On Databricks partner program

Built-On Neon is part of the [Built On Databricks](https://databrickslabs.github.io/partner-architecture/built-on) partner program. Platforms that use Neon can be validated as Databricks Built-On partners once they meet all program requirements. Validation is nomination-only and is aimed at a small number of large platforms. It's a fit if your platform:

- Uses Neon as the operational database layer of a commercial product, with a dedicated Neon project for each customer, app, or agent
- Runs a large fleet of tenant databases in production
- Generates significant revenue on Neon
- Has, or wants, a joint go-to-market motion with Databricks

If you're interested, first [register as a Databricks partner](https://www.databricks.com/partners/partner-program), then email [partners@databricks.com](mailto:partners@databricks.com) with any questions. If you're still building your integration or running at a smaller scale, start with the integration paths above instead.

Even if you're not pursuing the program, the [Built-On Neon reference architecture](https://databrickslabs.github.io/partner-architecture/built-on/neon) is a useful guide for designing database-per-tenant provisioning, scaling, connectivity, and metering. For requirements and the nomination process, see [Built-On Neon validation](https://databrickslabs.github.io/partner-architecture/built-on/neon/validation).

## Still not sure?

If you're uncertain which path is right for you, here's a quick decision tree:

1. **Are you building an AI agent or codegen platform?**  
   → Use [Neon for AI Agents](https://neon.com/docs/guides/ai-agent-integration)

2. **Are you building a plugin, CLI tool, or platform that needs instant Postgres without requiring user signup?**  
   → Use [Claimable database flow](https://neon.com/docs/workflows/claimable-database-integration)

3. **Are you offering Postgres databases as part of your SaaS platform?**  
   → Use [Embedded Postgres](https://neon.com/docs/guides/embedded-postgres)

4. **Are you building an application or service that will manage/monitor/interact with existing Neon accounts?**  
   → Use [OAuth integration](https://neon.com/docs/guides/oauth-integration)

## Get help

We're here to support you through every step of your integration.

- [Talk to our team](https://neon.com/contact-sales): Schedule a meeting with our team
- [Contact support](https://neon.com/docs/introduction/support): Get technical support

--- [Document source](https://neon.com/docs/guides/postgrest.md) ---

> Summary: PostgREST is a standalone web server that turns a Lakebase Postgres schema into a fully functional REST API with CRUD endpoints, filtering, and pagination without writing any backend code. Use this guide when you want to expose your database as a REST API locally using Docker, including JWT-based authentication and row-level security for per-user access control.

# Create a REST API from Postgres with PostgREST

Generate a REST API automatically from your Lakebase Postgres database schema

Last updated: 2026-10-09

**What you will learn:**

- What is PostgREST and how it works
- Setting up a Lakebase Postgres project for PostgREST
- Running PostgREST with Docker
- Adding authentication with JWT
- Implementing Row-Level Security

**Related resources**

- [PostgREST Documentation](https://docs.postgrest.org/en/v12/)
- [PostgREST Tutorials](https://postgrest.org/en/v12/tutorials/tut0.html)

**Source code**

- [PostgREST GitHub Repository](https://github.com/PostgREST/postgrest)

**Note:** Neon also provides a built-in [Data API](https://neon.com/docs/data-api/overview) that automatically creates REST endpoints for the database without requiring PostgREST or any additional setup. The Data API is fully managed and includes built-in authentication support.

## What is PostgREST?

PostgREST is a standalone web server that automatically turns your PostgreSQL database schema into a RESTful API. It uses the database's structure, constraints, and permissions to create API endpoints without requiring you to write any backend code. The API follows REST conventions and supports full CRUD operations, filtering, pagination, and even complex joins.

This guide shows you how to set up PostgREST with a Lakebase Postgres database using Docker for local development. You'll learn how to configure basic read access, add authenticated endpoints with JWT tokens, and implement row-level security for fine-grained access control.

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Set up your database

From the SQL Editor or any SQL client such as [psql](https://neon.com/docs/connect/query-with-psql-editor), set up your database using the following queries:

```sql
CREATE SCHEMA api;

CREATE TABLE api.students (
  id SERIAL PRIMARY KEY,
  first_name TEXT NOT NULL,
  last_name TEXT NOT NULL
);

INSERT INTO api.students (first_name, last_name) VALUES
('Ada', 'Lovelace'),
('Alan', 'Turing');

CREATE ROLE anonymous NOLOGIN;
GRANT anonymous TO neondb_owner;
GRANT USAGE ON SCHEMA api TO anonymous;
GRANT SELECT ON ALL TABLES IN SCHEMA api TO anonymous;
ALTER DEFAULT PRIVILEGES IN SCHEMA api GRANT SELECT ON TABLES TO anonymous;
```

**Tip:** While this example uses SERIAL for simplicity, consider using UUID as a primary key in production systems, especially in distributed environments, when exposing identifiers in URLs, or when avoiding predictable sequences is important.

## Copy your database connection string

Retrieve an unpooled database connection string. PostgREST requires a direct connection to your database.

1. Open your project in the Neon Console.
2. Click the **Connect** button to open the **Connect to your branch** modal.
3. Toggle **Connection pooling** to disable it; you need an unpooled connection string.
4. Copy the connection string.

![Connect to your database modal](https://neon.com/docs/guides/postgrest_connection_string.png)

## Run PostgREST

Use Docker to run PostgREST locally, specifying the **unpooled** database connection string.

**Linux**

```bash
docker run --rm --net=host \
  -e PGRST_DB_URI="<non-pooled-connection-string-from-neon-console>" \
  -e PGRST_DB_SCHEMA="api" \
  -e PGRST_DB_ANON_ROLE="anonymous" \
  postgrest/postgrest
```

**macOS**

```bash
docker run --rm \
  -e PGRST_DB_URI="<non-pooled-connection-string-from-neon-console>" \
  -e PGRST_DB_SCHEMA="api" \
  -e PGRST_DB_ANON_ROLE="anonymous" \
  -p 3000:3000 \
  postgrest/postgrest
```

**Windows**

```bash
docker run --rm \
  -e PGRST_DB_URI="<non-pooled-connection-string-from-neon-console>" \
  -e PGRST_DB_SCHEMA="api" \
  -e PGRST_DB_ANON_ROLE="anonymous" \
  -p 3000:3000 \
  postgrest/postgrest
```

Once running, visit [http://localhost:3000/students](http://localhost:3000/students) to confirm the API is working. You should see the following records in your browser:

![local host students](https://neon.com/docs/guides/postgrest_local_host_students.png)

## Add authenticated access

To support full CRUD operations (inserts, updates, and deletes), you need to set up permissions in your database by creating a role for authenticated users. Here, we create an `authenticated` role, assign privileges, and grant the role to our database owner (`neondb_owner`). Run these commands from the Neon SQL Editor or an SQL client.

```sql
CREATE ROLE authenticated NOLOGIN;
GRANT authenticated TO neondb_owner;
GRANT USAGE ON SCHEMA api TO authenticated;
GRANT ALL ON ALL TABLES IN SCHEMA api TO authenticated;
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA api TO authenticated;
```

## Run PostgREST with a JWT secret

Run PostgREST again, this time with a JWT secret that will be used by PostgREST to verify the JWT that we will attach to our requests in a later step.

**Linux**

```bash
docker run --rm --net=host \
  -e PGRST_DB_URI="<non-pooled-connection-string-from-neon-console>" \
  -e PGRST_DB_SCHEMA="api" \
  -e PGRST_JWT_SECRET="reallyreallyreallyreallyverysafe" \
  -e PGRST_DB_ANON_ROLE="anonymous" \
  postgrest/postgrest
```

**macOS**

```bash
docker run --rm \
  -e PGRST_DB_URI="<non-pooled-connection-string-from-neon-console>" \
  -e PGRST_DB_SCHEMA="api" \
  -e PGRST_JWT_SECRET="reallyreallyreallyreallyverysafe" \
  -e PGRST_DB_ANON_ROLE="anonymous" \
  -p 3000:3000 \
  postgrest/postgrest
```

**Windows**

```bash
docker run --rm \
  -e PGRST_DB_URI="<non-pooled-connection-string-from-neon-console>" \
  -e PGRST_DB_SCHEMA="api" \
  -e PGRST_JWT_SECRET="reallyreallyreallyreallyverysafe" \
  -e PGRST_DB_ANON_ROLE="anonymous" \
  -p 3000:3000 \
  postgrest/postgrest
```

## Authenticate requests using JWT

Now that we have defined our JWT secret above (`reallyreallyreallyreallyverysafe`), we'll create a sample JWT that's signed with this secret. If you didn't change the secret used above, you can use this JWT:

```text
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.XOGSeHS8usEzEELkUl8SWOrsOLP7xWmHckRSTgpyP3o
```

**Tip:** You can use [jwt.io](https://jwt.io/) to generate your own JWT. Make sure to use the **HS256** algorithm.

Now let's test different CRUD operations using standard HTTP methods. Notice that we've attached the JWT in the `Authorization` header as a bearer token.

**Insert a student:**

```bash
curl http://localhost:3000/students \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.XOGSeHS8usEzEELkUl8SWOrsOLP7xWmHckRSTgpyP3o" \
  -d '{"first_name": "Grace", "last_name": "Hopper"}'
```

You should see the following records after refreshing your browser:

![local host students](https://neon.com/docs/guides/postgrest_local_host_students_insert.png)

**Update a student:**

```bash
curl "http://localhost:3000/students?id=eq.1" \
  -X PATCH \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.XOGSeHS8usEzEELkUl8SWOrsOLP7xWmHckRSTgpyP3o" \
  -d '{"first_name": "Ada I.", "last_name": "Lovelace"}'
```

Refresh your browser to see the updated records:

![local host students](https://neon.com/docs/guides/postgrest_local_host_students_update.png)

**Delete a student:**

```bash
curl "http://localhost:3000/students?id=eq.3" \
  -X DELETE \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXV0aGVudGljYXRlZCJ9.XOGSeHS8usEzEELkUl8SWOrsOLP7xWmHckRSTgpyP3o"
```

You should now see these records:

![local host students](https://neon.com/docs/guides/postgrest_local_host_students_delete.png)

## Use Row-Level Security (RLS)

PostgREST supports Postgres RLS for fine-grained access control. Here's an example policy to restrict access to a user's own records. Run these statements on your database in the Neon SQL Editor or an SQL client.

```sql
ALTER TABLE api.students ENABLE ROW LEVEL SECURITY;

CREATE POLICY students_policy ON api.students
    FOR ALL
    TO authenticated
    USING (id = (SELECT current_setting('request.jwt.claims', true)::json->>'sub')::integer)
    WITH CHECK (id = (SELECT current_setting('request.jwt.claims', true)::json->>'sub')::integer);
```

The JWT token used in the CRUD examples above contains a payload with `{"role": "authenticated"}`, which tells PostgREST to use the `authenticated` role for those requests.

In a real application, you would want to:

- Generate tokens with proper expiration times
- Include user-specific claims in the JWT (most likely, a "sub" field which corresponds to users' IDs)
- Implement a proper authentication server/service (or use a third-party managed auth provider)

Now let's test this with a JWT that includes a user ID. We'll create a new JWT with a payload that includes a user ID in the "sub" claim:

Now, let's generate a new JWT that has the following payload defining the student ID (and sign it with the same JWT secret from above):

```
{
  "role": "authenticated",
  "sub": "1"
```

Here's the new token:

```text
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXV0aGVudGljYXRlZCIsInN1YiI6IjEifQ.U_EgeU0y0pAM5cTsMXndJe_cR1vG5Vf9dq4DkqfMAxs
```

Now, run this command with the new token:

```bash
$ curl "http://localhost:3000/students" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlIjoiYXV0aGVudGljYXRlZCIsInN1YiI6IjEifQ.U_EgeU0y0pAM5cTsMXndJe_cR1vG5Vf9dq4DkqfMAxs"
[{"id":1,"first_name":"Ada I.","last_name":"Lovelace"}]
```

Because the `students` table has a RLS policy attached to the student's ID, the student can only view their own records.

## Summary

The examples shown above are simple, but they illustrate how PostgREST works. With Neon and PostgREST, you can instantly turn your Postgres database into a REST API; no backend code required. This setup is ideal for rapid prototyping, internal tools, or even production workloads where you want to focus on your data and business logic rather than boilerplate API code.

## Next steps

Now that you have a basic PostgREST API running with Neon, here are some things you can try next:

- **Explore advanced querying**: Implement [filtering](https://docs.postgrest.org/en/v12/api.html#horizontal-filtering-rows), [ordering](https://docs.postgrest.org/en/v12/api.html#ordering), and [pagination](https://docs.postgrest.org/en/v12/api.html#limits-and-pagination) in your API requests
- **Add resource embedding**: Use [resource embedding](https://docs.postgrest.org/en/v12/api.html#resource-embedding) to fetch related data in a single request
- **Implement stored procedures**: Expose [PostgreSQL functions](https://docs.postgrest.org/en/v12/api.html#stored-procedures) as API endpoints for complex operations
- **Example applications**: Explore [example applications](https://docs.postgrest.org/en/v12/ecosystem.html#example-apps) built with PostgREST to get inspiration for your own projects
- **Try out templates**: These [templates](https://docs.postgrest.org/en/v12/ecosystem.html#templates) combine PostgREST with various frontend technologies

--- [Document source](https://neon.com/docs/guides/prisma-migrations.md) ---

> Summary: Prisma Migrate schema migrations on Neon require two connection strings: a pooled URL for application runtime and a direct URL so the Prisma CLI can apply DDL changes without going through PgBouncer. This tutorial builds a Node.js Express API, runs `prisma migrate dev` to generate and apply SQL migration files, then shows how iterative schema changes work and when to switch to `prisma migrate deploy` for production.

# Schema migrations with Prisma and Neon

Learn how to manage database schema changes using Prisma Migrate with Neon

Last updated: 2026-10-05

Pre-built prompt for connecting Node/TypeScript applications to Neon using Prisma ORM. [View prompt](https://neon.com/prompts/prisma-prompt.md)

This tutorial walks you through building a Node.js application with Prisma ORM and Neon, focusing on how to create and apply schema migrations. You'll build a simple book catalog API while learning the migration workflow.

**Tip:** If you just need to connect Prisma to Neon without a full tutorial, see [Connect from Prisma to Neon](https://neon.com/docs/guides/prisma).

## Prerequisites

- A [Neon account and project](https://neon.com/docs/get-started-with-neon/signing-up)
- [Node.js](https://nodejs.org/) 20.19+, 22.12+, or 24+ installed (required by Prisma ORM 7)
- Both connection strings from your Neon Console (pooled and direct)

## Create the project

Set up a new Node.js project with Express and Prisma:

```bash
mkdir neon-prisma-migrations && cd neon-prisma-migrations
npm init -y
npm pkg set type="module"
npm install express dotenv @prisma/client@7 @prisma/adapter-neon@7
npm install prisma@7 typescript tsx @types/node --save-dev
npx prisma init
```

## Configure Prisma for Neon

### Set up environment variables

Add both connection strings to your `.env` file. Get these from your Neon Console by clicking **Connect**:

```ini
# Pooled connection for your application (note the -pooler suffix)
DATABASE_URL="postgresql://[user]:[password]@[endpoint]-pooler.[region].aws.neon.tech/[dbname]?sslmode=require"

# Direct (unpooled) connection for Prisma CLI (migrations, introspection)
DATABASE_URL_UNPOOLED="postgresql://[user]:[password]@[endpoint].[region].aws.neon.tech/[dbname]?sslmode=require"
```

**Important:** Prisma Migrate requires a direct connection to perform schema changes. The pooled connection is used by your application at runtime.

### Configure prisma.config.ts

Update the `prisma.config.ts` file in your project root:

```typescript
import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL_UNPOOLED'),
  },
})
```

### Update the Prisma schema

Replace the contents of `prisma/schema.prisma`:

```prisma
generator client {
  provider = "prisma-client-js"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model Author {
  id        Int      @id @default(autoincrement())
  name      String
  bio       String?
  createdAt DateTime @default(now()) @map("created_at")
  books     Book[]

  @@map("authors")
}

model Book {
  id        Int      @id @default(autoincrement())
  title     String
  authorId  Int      @map("author_id")
  createdAt DateTime @default(now()) @map("created_at")
  author    Author   @relation(fields: [authorId], references: [id])

  @@map("books")
}
```

## Create and run your first migration

Run the following command to create your initial migration:

```bash
npx prisma migrate dev --name init
```

This command:

1. Creates a `prisma/migrations` folder with SQL migration files
2. Applies the migration to your Neon database
3. Generates the Prisma Client

You should see output confirming the migration was applied.

## Set up Prisma Client

Create `src/db.ts` to instantiate Prisma Client with the Neon adapter:

```typescript
import 'dotenv/config'
import { PrismaClient } from './generated/prisma'
import { PrismaNeon } from '@prisma/adapter-neon'

const adapter = new PrismaNeon({
  connectionString: process.env.DATABASE_URL!,
})

export const prisma = new PrismaClient({ adapter })
```

## Seed the database

Create `src/seed.ts` to populate the database with sample data:

```typescript
import { prisma } from './db'

async function seed() {
  const authors = [
    {
      name: 'J.R.R. Tolkien',
      bio: 'Creator of Middle-earth and author of The Lord of the Rings.',
      books: {
        create: [
          { title: 'The Hobbit' },
          { title: 'The Fellowship of the Ring' },
          { title: 'The Two Towers' },
        ],
      },
    },
    {
      name: 'George R.R. Martin',
      bio: 'Author of the epic fantasy series A Song of Ice and Fire.',
      books: {
        create: [
          { title: 'A Game of Thrones' },
          { title: 'A Clash of Kings' },
        ],
      },
    },
  ]

  for (const author of authors) {
    await prisma.author.create({ data: author })
  }

  console.log('✅ Database seeded')
}

seed()
  .catch(console.error)
  .finally(() => prisma.$disconnect())
```

Run the seed script:

```bash
npx tsx src/seed.ts
```

## Build the API

Create `src/index.ts` with Express endpoints:

```typescript
import express from 'express'
import { prisma } from './db'

const app = express()
const port = process.env.PORT || 3000

app.get('/authors', async (req, res) => {
  const authors = await prisma.author.findMany({
    include: { books: true },
  })
  res.json(authors)
})

app.get('/books', async (req, res) => {
  const books = await prisma.book.findMany({
    include: { author: true },
  })
  res.json(books)
})

app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`)
})
```

Add a start script to `package.json`:

```bash
npm pkg set scripts.start="tsx src/index.ts"
```

Start the server:

```bash
npm start
```

Visit `http://localhost:3000/authors` to see the data.

## Make a schema change

Now let's add a `country` field to the `Author` model to demonstrate the migration workflow.

### Update the model

Modify the `Author` model in `prisma/schema.prisma`:

```prisma
model Author {
  id        Int      @id @default(autoincrement())
  name      String
  bio       String?
  country   String?
  createdAt DateTime @default(now()) @map("created_at")
  books     Book[]

  @@map("authors")
}
```

### Generate and apply the migration

```bash
npx prisma migrate dev --name add-author-country
```

Prisma creates a new migration file and applies it. The Prisma Client is automatically regenerated.

### Verify the change

Restart your server and check `http://localhost:3000/authors`. Each author now has a `country` field (set to `null` for existing records).

## Migration workflow summary

The typical workflow for schema changes with Prisma and Neon:

1. **Modify your schema**: Update models in `prisma/schema.prisma`
2. **Generate migration**: Run `npx prisma migrate dev --name descriptive-name`
3. **Review the migration**: Check the generated SQL in `prisma/migrations/`
4. **Test locally**: Verify your application works with the changes
5. **Deploy**: In production, use `npx prisma migrate deploy`

**Tip:** For production deployments, always use `prisma migrate deploy` instead of `prisma migrate dev`. The `deploy` command only applies pending migrations without generating new ones.

## Source code

Find the complete source code for this tutorial on GitHub:

- [Migrations with Neon and Prisma](https://github.com/neondatabase/guide-neon-prisma): Run Neon database migrations using Prisma

## Next steps

- [Connect from Prisma to Neon](https://neon.com/docs/guides/prisma): Connection setup reference
- [Prisma Migrate documentation](https://www.prisma.io/docs/concepts/components/prisma-migrate): Deep dive into Prisma migrations
- [Neon branching](https://neon.com/docs/introduction/branching): Use database branches to test migrations safely

--- [Document source](https://neon.com/docs/guides/prisma.md) ---

> Summary: Prisma ORM (Node.js/TypeScript) connects to Neon using the `@prisma/adapter-neon` serverless driver adapter, which routes queries over WebSockets for compatibility with serverless environments. The setup requires two connection strings: a pooled URL (`DATABASE_URL`) for application queries and a direct URL (`DATABASE_URL_UNPOOLED`) for Prisma CLI commands such as migrations and `db push`. Newer Prisma versions configure the direct connection in a Prisma config file (`prisma.config.ts`, or `prisma7.config.ts` in 7.10+); older versions use the `directUrl` property in `schema.prisma`.

# Connect from Prisma to Neon

Learn how to connect to Neon from Prisma

Last updated: 2026-10-05

Pre-built prompt for connecting Node/TypeScript applications to Neon using Prisma ORM. [View prompt](https://neon.com/prompts/prisma-prompt.md)

Prisma is an open-source ORM for Node.js and TypeScript. This guide shows you how to connect a Prisma application to Neon using the recommended setup with the Neon serverless driver adapter.

## Prerequisites

- A [Neon account and project](https://neon.com/docs/get-started-with-neon/signing-up)
- Node.js 20.19+, 22.12+, or 24+ installed (required by Prisma ORM 7)
- A Node.js or TypeScript project (or create a new one)

## Setup

### Step 1: Install dependencies

```bash
npm install @prisma/client@7 @prisma/adapter-neon@7 dotenv
npm install prisma@7 tsx --save-dev
```

**Note:** This guide uses Prisma ORM 7. Install the `prisma` CLI, `@prisma/client`, and `@prisma/adapter-neon` at the same major version (`@7`). The `prisma` package's `latest` npm tag currently points to a Prisma 8 prerelease, so an unpinned `npm install prisma` installs a CLI that doesn't match the rest of this setup. If the Prisma CLI later prints an "Update available" notice for Prisma 8, ignore it for this guide.

### Step 2: Get your connection strings

From your Neon Console, click **Connect** and copy both connection strings:

- **Pooled connection** (has `-pooler` in the hostname): for your application
- **Direct (unpooled) connection**: for Prisma CLI commands (migrations, introspection)

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

Add them to your `.env` file:

```ini
# Pooled connection for your application
DATABASE_URL="postgresql://[user]:[password]@[endpoint]-pooler.[region].aws.neon.tech/[dbname]?sslmode=require&channel_binding=require"

# Direct (unpooled) connection for Prisma CLI
DATABASE_URL_UNPOOLED="postgresql://[user]:[password]@[endpoint].[region].aws.neon.tech/[dbname]?sslmode=require&channel_binding=require"
```

**Tip:** The pooled connection has `-pooler` in the hostname. The direct (unpooled) connection does not. Both are available in your Neon Console. If you only have the pooled string, remove `-pooler` from the hostname to get the direct one.

### Step 3: Configure your Prisma schema

If you don't have a Prisma schema yet, run `npx prisma init` to create one. Then update `prisma/schema.prisma`:

```prisma
generator client {
  provider = "prisma-client-js"
  output   = "../src/generated/prisma"
}

datasource db {
  provider = "postgresql"
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
}
```

**Note:** In Prisma 7+, do not include a `url` property in the datasource block. The connection is configured in the Prisma config file (Step 4) and the adapter.

### Step 4: Configure the Prisma CLI connection

The Prisma CLI reads its connection from a config file in your project root. If you ran `npx prisma init`, it already created one: `prisma7.config.ts` in Prisma 7.10 and later, or `prisma.config.ts` in earlier 7.x releases. Replace that file's contents with the following. If you don't have a config file yet, create `prisma.config.ts`:

```typescript
import 'dotenv/config'
import { defineConfig, env } from 'prisma/config'

export default defineConfig({
  schema: 'prisma/schema.prisma',
  datasource: {
    url: env('DATABASE_URL_UNPOOLED'),
  },
})
```

**Warning:** Keep only one Prisma config file. If both `prisma7.config.ts` and `prisma.config.ts` exist, the CLI loads `prisma7.config.ts` and ignores the other, so CLI commands can end up on the pooled connection. The first line of `npx prisma db push` output shows which file was loaded (`Loaded Prisma config from ...`).

### Step 5: Create your Prisma Client

Create a file to instantiate Prisma Client with the Neon adapter (for example, `src/db.ts`):

```typescript
import 'dotenv/config'
import { PrismaClient } from './generated/prisma'
import { PrismaNeon } from '@prisma/adapter-neon'

const adapter = new PrismaNeon({
  connectionString: process.env.DATABASE_URL!,
})

export const prisma = new PrismaClient({ adapter })
```

### Step 6: Generate client and push schema

```bash
npx prisma generate
npx prisma db push
```

You're connected. You can now use Prisma Client in your application:

```typescript
import { prisma } from './db'

const users = await prisma.user.findMany()
```

To verify the full setup, create a `src/main.ts` script that exercises CRUD operations:

```typescript
import { prisma } from './db'

async function main() {
  // CREATE
  const newUser = await prisma.user.create({
    data: { name: 'Alice', email: `alice-${Date.now()}@example.com` },
  })
  console.log('Created user:', newUser)

  // READ
  const foundUser = await prisma.user.findUnique({ where: { id: newUser.id } })
  console.log('Found user:', foundUser)

  // UPDATE
  const updatedUser = await prisma.user.update({
    where: { id: newUser.id },
    data: { name: 'Alice Smith' },
  })
  console.log('Updated user:', updatedUser)

  // DELETE
  await prisma.user.delete({ where: { id: newUser.id } })
  console.log('Deleted user.')
}

main()
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })
  .finally(async () => {
    await prisma.$disconnect()
  })
```

Run it with:

```bash
npx tsx src/main.ts
```

## Why two connection strings?

Neon uses connection pooling to manage database connections in serverless environments:

- **Pooled connection (`DATABASE_URL`)**: Your application connects through Neon's connection pooler, which suits serverless functions that create many short-lived connections.
- **Direct (unpooled) connection (`DATABASE_URL_UNPOOLED`)**: Prisma CLI commands like `prisma migrate` and `prisma db push` need a direct connection for schema operations.

## Advanced configuration

### Using a non-public Postgres schema

If you're using a Postgres schema other than `public`, pass a `schema` option when creating the adapter:

```typescript
const adapter = new PrismaNeon(
  { connectionString: process.env.DATABASE_URL! },
  { schema: 'myPostgresSchema' }
)
```

### Setting the search path for raw SQL queries

For raw SQL queries that reference tables without schema qualification, use the Postgres `options` parameter in your connection string:

```text
postgresql://[user]:[password]@[neon_hostname]/[dbname]?options=-c%20search_path%3Dmyschemaname
```

This works only on the direct (unpooled) connection. The pooler rejects `search_path` in startup options, so with the pooled `DATABASE_URL`, use the adapter's `schema` option or schema-qualified table names instead.

## Troubleshooting

<details>

<summary>**Connection timeouts**</summary>

If you see an error like:

```text
Error: P1001: Can't reach database server at `ep-example-123456.us-east-2.aws.neon.tech`:`5432`
```

This usually means the connection timed out before Neon activated the compute. Neon computes scale to zero after inactivity and take a few seconds to wake up.

Add a `connect_timeout` parameter to your connection string:

```text
DATABASE_URL="postgresql://...?sslmode=require&connect_timeout=15"
```

A value of `0` means no timeout.

</details>

<details>

<summary>**Connection pool timeouts**</summary>

With the Neon adapter, the connection pool belongs to the Neon serverless driver, not Prisma. In Prisma 7, the `connection_limit` and `pool_timeout` URL parameters have no effect. Pass pool options to the adapter instead:

```typescript
const adapter = new PrismaNeon({
  connectionString: process.env.DATABASE_URL!,
  max: 20, // maximum connections in the pool
  connectionTimeoutMillis: 15_000, // how long to wait for a connection
})
```

See Prisma's [connection pool guide](https://www.prisma.io/docs/orm/v7/prisma-client/setup-and-configuration/databases-connections/connection-pool) for details.

</details>

<details>

<summary>**Using Prisma 6 or earlier**</summary>

In Prisma 6 and earlier, you configure the connection directly in `schema.prisma` instead of a Prisma config file:

```prisma
datasource db {
  provider  = "postgresql"
  url       = env("DATABASE_URL")
  directUrl = env("DATABASE_URL_UNPOOLED")
}
```

The `directUrl` property is available in Prisma 4.10.0 and higher.

</details>

## Next steps

- [Schema migrations with Prisma](https://neon.com/docs/guides/prisma-migrations): Full tutorial for building an app with migrations
- [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver): Learn more about the driver powering the adapter

## Next steps: Neon backend services

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Resources

- [Prisma documentation](https://www.prisma.io/docs/)
- [Prisma connection management](https://www.prisma.io/docs/guides/performance-and-optimization/connection-management)
- [PostgreSQL connector reference](https://www.prisma.io/docs/concepts/database-connectors/postgresql)

<details>

<summary>**Notes for AI-assisted setup**</summary>

- Import `PrismaClient` from `./generated/prisma` (or your configured `output` path), not from `@prisma/client`. The import path changed in Prisma 7.
- Do not install `@neondatabase/serverless` or `ws` as separate packages. The `@prisma/adapter-neon` package bundles everything needed for the Neon connection.
- In Prisma 7+, do not include a `url` property in the `prisma/schema.prisma` datasource block. The connection is configured in the Prisma config file and the adapter.
- `npx prisma init` in Prisma 7.10+ creates `prisma7.config.ts`. Edit that file instead of adding a second `prisma.config.ts`; when both exist, the CLI loads `prisma7.config.ts`.
- You need both a pooled connection (`DATABASE_URL`) for your application and a direct (unpooled) connection (`DATABASE_URL_UNPOOLED`) for Prisma CLI commands.
- Call `prisma.$disconnect()` in a `.finally()` block when running standalone scripts. Omitting this can leave connections open.

</details>

--- [Document source](https://neon.com/docs/guides/project-collaboration-guide.md) ---

> Summary: Project collaboration lets Neon project owners invite external users by email to access a project through the Console, API, and CLI. Invited users don't receive deletion rights or organization membership. Use this page when sharing a single project with a contractor or external contributor rather than adding a full organization member. Collaborator usage counts against the project owner's plan allowances, and all costs are billed to the owning account.

# Project collaboration

Learn how to invite people to collaborate on your Neon project

Last updated: 2026-08-04

You can invite other users to collaborate with you on a Neon project. Project collaboration lets other users access and contribute to your project from all supported Neon interfaces, including the Neon Console, Neon API, and Neon CLI. Follow this guide to learn how.

**Important:** Project sharing is being deprecated and will be removed in a future release, so switch to organization-based collaboration now: add the person to your organization as a **Collaborator**, then grant them a permission on each project they need. See [Assign project access](https://neon.com/docs/manage/user-permissions#assign-project-access).

Project sharing still works today, and it remains the option for organizations on the [legacy permissions](https://neon.com/docs/manage/user-permissions#legacy-permissions) model, including [Vercel-managed organizations](https://neon.com/docs/guides/vercel-managed-integration).

Note that the **Collaborator** organization role is not the same as a project-sharing collaborator, even though the names match. A Collaborator is a member of your organization who you grant per-project permissions to. A project-sharing collaborator is an external Neon account invited to a single project, as described on this page.

**Note:** Use project collaboration to work with people outside your organization. If you're working with team members, create an [Organization](https://neon.com/docs/manage/organizations) instead. Organization members get access to projects based on their organization role and any per-project permissions you grant them.

## Set up Neon accounts

You can invite anyone outside your organization to collaborate on your Neon project. To collaborate on a project, the user must have a Neon account, which can be a Neon Free plan or a paid plan account.

1. If the user does not have a Neon account, ask them to sign up. You can provide your users with the following instructions: [Sign up](https://neon.com/docs/get-started/signing-up).
2. Request the email address the user signed up with. If the user signed up using Google or GitHub, request the email address associated with that account.

## Invite collaborators

After a user has provided you with the email address associated with their Neon account, you can invite them to your project.

**To invite a collaborator to your project:**

1. Navigate to the [Neon Console](https://console.neon.tech/app/projects).

2. Select the project you want to invite collaborators to.

3. In the Neon **Settings**, choose **Collaborators** from the sidebar.

   ![Invite collaborators](https://neon.com/docs/guides/sharing_grant_access.png)

4. Click **Invite**. In the modal that pops up, enter the email address of the person you'd like to invite. You can enter multiple emails separated by commas.

5. Click **Invite** in the modal to confirm; the specified email(s) will be added to the list of **Collaborators**.

6. Review the list of collaborators to verify the user was successfully added.

The invited users will be granted access to the project, but they will not have privileges to delete the project. They can also invite other users to join the collaboration. When they log into Neon, the project will appear under the **Projects** section, listed as **Shared with me**.

An email is sent to the invited users informing them of the project invitation, including an **Open project** link for easy access.

**Note: Invites not received?**

If invite emails aren't received, they may be in spam or quarantined. Recipients should check these folders and mark Neon emails as safe.

## Project collaboration limits

When you invite a user to your project, they operate under _your_ project allowances so long as they're using your project. For example, a Neon Free plan user is limited to 10 branches per project, but if they are using your project, there is no such restriction. For teams working together frequently across multiple projects, [organization](https://neon.com/docs/manage/organizations) membership offers a better collaboration experience.

### Access for collaborators via the Neon API or CLI

Collaborators you invite to a project can access it from all supported Neon interfaces, including the Neon Console, [Neon API](https://neon.com/docs/reference/api), and [Neon CLI](https://neon.com/docs/cli).

Collaborators can use their own API key to access the project via the Neon API. See [Manage API keys](https://neon.com/docs/manage/api-keys) for details on generating an API key.

When using the Neon CLI, collaborators authenticate as they normally would. They can access both their own Neon projects and any projects they are collaborating on. See [Neon CLI — Connect](https://neon.com/docs/cli/install#connect) for authentication instructions.

## Billing for projects with collaborators

All costs associated with a project are charged to the Neon account that owns it. For example, if you invite someone to collaborate on your project, any usage incurred by that collaborator will be billed to your Neon account.

--- [Document source](https://neon.com/docs/guides/protected-branches.md) ---

> Summary: Protected branches in Neon prevent deletion, reset, and archiving of critical branches such as production, and automatically generate new Postgres role passwords on child branches to block credential leakage. Use this feature when you need to lock down a branch against accidental or unauthorized changes. It can be combined with the IP Allow feature to restrict network access to protected branches only. Available on paid plans.

# Protected branches

Learn how to use Neon's protected branches feature to secure your critical data

Last updated: 2026-10-09

Neon's protected branches feature implements a series of protections:

- Protected branches cannot be deleted.
- Protected branches cannot be [reset](https://neon.com/docs/manage/branches#reset-a-branch-from-parent).
- Projects with protected branches cannot be deleted.
- Computes associated with a protected branch cannot be deleted.
- New passwords are automatically generated for Postgres roles on branches created from protected branches. [See below](https://neon.com/docs/guides/protected-branches#new-passwords-generated-for-postgres-roles-on-child-branches).
- With additional configuration steps, you can apply IP Allow restrictions to protected branches only. The [IP Allow](https://neon.com/docs/introduction/ip-allow) feature is available on the Neon [Scale](https://neon.com/docs/introduction/plans) plan. See [below](https://neon.com/docs/guides/protected-branches#how-to-apply-ip-restrictions-to-protected-branches).
- Protected branches are not [archived](https://neon.com/docs/guides/branch-archiving) due to inactivity.

The protected branches feature is available on Neon [paid plans](https://neon.com/docs/introduction/plans).

- The **Launch** plan supports up to 2 protected branches
- The **Scale** plan supports up to 5 protected branches

## Set a branch as protected

This example sets a branch as protected.

To set a branch as protected:

1. In the Neon Console, select a project.

2. Select **Branches** in the sidebar to view the branches for the project.

   ![Branch page](https://neon.com/docs/guides/ip_allow_branch_page.png)

3. Select a branch from the table. In this example, we'll configure our default branch (named `main` if the project was created with the CLI or API, or `production` if created in the Console) as a protected branch.

4. On the branch page, click **Protect**.

   ![Set as protected](https://neon.com/docs/guides/ip_allow_set_as_protected.png)

5. In the **Set as protected** confirmation dialog, click **Set as protected** to confirm your selection.

   ![Set as protected confirmation](https://neon.com/docs/guides/ip_allow_set_as_protected_confirmation.png)

   Your branch is now designated as protected, as indicated by the protected branch shield icon, shown below.

   ![Branch page badge](https://neon.com/docs/guides/ip_allow_branch_badge.png)

   The protected branch designation also appears on your **Branches** page.

   ![Branches page badge](https://neon.com/docs/guides/ip_allow_branch_badge_2.png)

## New passwords generated for Postgres roles on child branches

When you create a branch in Neon, it includes all Postgres databases and roles from the parent branch. By default, Postgres roles on the child branch will have the same passwords as on the parent branch. However, this does not apply to protected branches. When you create a child branch from a protected branch, new passwords are generated for the matching Postgres roles on the child branch.

This behavior is designed to prevent the exposure of passwords that could be used to access your protected branch. For example, if you have designated a production branch as protected, the automatic password change for child branches ensures that you can create child branches for development or testing without risking access to data on your production branch.

Please note that resetting or restoring a child branch from a protected parent branch preserves passwords for matching Postgres roles on the child branch. Please refer to the feature notes below for more.

**Important: Feature notes**

- The "new password" feature for child branches was released on July, 31, 2024. If you have existing CI scripts that create branches from protected branches, please be aware that passwords for matching Postgres roles on those newly created branches will now differ. If you depend on those passwords being the same, you'll need to make adjustments to get the correct connection details for those branches.
  - After a branch is created, the up-to-date connection string is returned in the output of the [Create Branch GitHub Action](https://neon.com/docs/guides/branching-github-actions#create-branch-action).
  - The [Reset Branch GitHub Action](https://neon.com/docs/guides/branching-github-actions#reset-from-parent-action) also outputs connection string values, in case you are using this action in your workflows.
  - The Neon CLI supports a [connection-string](https://neon.com/docs/cli/connection-string) command for retrieving a branch's connection string.
- Prior to September, 6, 2024, resetting or restoring a child branch from a protected parent branch restored passwords for matching Postgres roles on the child branch to those used on the protected parent branch. As of September, 6, 2024, passwords for matching Postgres roles on the child branch are preserved when resetting or restoring a child branch from a protected parent branch.

## How to apply IP restrictions to protected branches

On plans that support it, you can use the protected branches feature in combination with Neon's [IP Allow](https://neon.com/docs/introduction/ip-allow) feature to apply IP access restrictions to protected branches only. The basic setup steps are:

1. [Define an IP allowlist for your project](https://neon.com/docs/guides/protected-branches#define-an-ip-allowlist-for-your-project)
2. [Restrict IP access to protected branches only](https://neon.com/docs/guides/protected-branches#restrict-ip-access-to-protected-branches-only)
3. [Set a branch as protected](https://neon.com/docs/guides/protected-branches#set-a-branch-as-protected) (if you have not done so already)

### Define an IP allowlist for your project

**Neon Console**

To configure an allowlist:

1. Select a project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Networking**.
4. Under **Public internet access**, select **Only addresses on the allowlist**, then specify the IP addresses you want to permit. Separate multiple entries with commas.
5. Click **Save changes**.

**CLI**

The [Neon CLI ip-allow command](https://neon.com/docs/cli/ip-allow) supports IP Allow configuration. For example, the following `add` command adds IP addresses to the allowlist for an existing Neon project. Multiple entries are separated by a space. No delimiter is required.

```bash
neon ip-allow add 203.0.113.0 203.0.113.1
ID              wispy-haze-123456
Name            wispy-haze-123456
IP Addresses    203.0.113.0, 203.0.113.1
Protected Only  false
```

To apply an IP allowlist to protected branches only, you can use the `--protected-only` option:

```bash
neon ip-allow add 203.0.113.1 --protected-only
```

To reverse that setting, use `--protected-only false`.

```bash
neon ip-allow add 203.0.113.1 --protected-only false
```

**API**

The [Create project](https://neon.com/docs/reference/api/projects/create-project) and [Update project](https://neon.com/docs/reference/api/projects/update-project) methods support **IP Allow** configuration. For example, the following API call configures **IP Allow** for an existing Neon project. Separate multiple entries with commas. Each entry must be quoted. You can set the `"protected_branches_only` option to `true` to apply the allowlist to protected branches only, or `false` to apply it to all branches in your Neon project.

```bash
curl -X PATCH \
     https://console.neon.tech/api/v2/projects/falling-salad-31638542 \
     -H 'accept: application/json' \
     -H 'authorization: Bearer $NEON_API_KEY' \
     -H 'content-type: application/json' \
     -d '
{
  "project": {
    "settings": {
      "allowed_ips": {
        "protected_branches_only": true,
        "ips": [
          "203.0.113.0", "203.0.113.1"
        ]
      }
    }
  }
}
' | jq
```

For details about specifying IP addresses, see [How to specify IP addresses](https://neon.com/docs/manage/projects#how-to-specify-ip-addresses).

### Restrict IP access to protected branches only

After defining an IP allowlist, go to **Restricted branches** and select **Protected branches only**.

This option removes IP restrictions from _all branches_ in your Neon project and applies them to protected branches only. Every other branch keeps accepting any address.

After you've selected the protected branches option, click **Save changes** to apply the new configuration.

## Remove branch protection

Removing a protected branch designation can be performed by selecting **Set as unprotected** from the three-dot menu (⋮) on the branch page.

--- [Document source](https://neon.com/docs/guides/python.md) ---

> Summary: Connecting Python to Lakebase Postgres requires choosing between three drivers: psycopg (v3, synchronous), psycopg2 (legacy synchronous), and asyncpg (asyncio-based async). The guide covers project setup, .env connection string configuration, and full CRUD examples for all three drivers. Pick this over the SQLAlchemy or Django guides when you need raw SQL driver code rather than an ORM.

# Connect a Python application to Lakebase Postgres

Learn how to run SQL queries from Python using psycopg, psycopg2, or asyncpg

Last updated: 2026-10-09

Pre-built prompt for connecting Python applications to Neon [View prompt](https://neon.com/prompts/python-prompt.md)

This guide describes how to create a Neon project and connect to it from a Python application using three Postgres drivers: [Psycopg 3](https://www.psycopg.org/psycopg3/docs/), the current synchronous adapter, its predecessor [Psycopg 2 (psycopg2)](https://pypi.org/project/psycopg2-binary/), and [asyncpg](https://pypi.org/project/asyncpg/), an asynchronous adapter for use with `asyncio`.

You'll learn how to connect to the database from a Python application and perform basic Create, Read, Update, and Delete (CRUD) operations.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://console.neon.tech/signup).
- Python 3.10 or later. Current releases of `psycopg` and `psycopg2-binary` require Python 3.10+. If you do not have Python installed, install it from the [Python website](https://www.python.org/downloads/).

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Your project is created with a ready-to-use database named `neondb`. In the following steps, you will connect to this database from your Python application.

## Create a Python project

For your Python project, create a project directory, set up a virtual environment, and install the required libraries.

1. Create a project directory and change into it.

   ```bash
   mkdir neon-python-quickstart
   cd neon-python-quickstart
   ```

   > Open the directory in your preferred code editor (for example, VS Code, PyCharm).

2. Create and activate a Python virtual environment. This isolates your project's dependencies from your system's Python environment.

   **MacOS / Linux / Windows Subsystem for Linux (WSL)**

   ```bash
   # Create a virtual environment
   python3 -m venv venv

   # Activate the virtual environment
   source venv/bin/activate
   ```

   **Windows**

   ```bash
   # Create a virtual environment
   python -m venv venv

   # Activate the virtual environment
   .\venv\Scripts\activate
   ```

3. Install the required libraries using `pip`.

   - `psycopg`: The synchronous database adapter for connecting to Postgres (Psycopg 3). **Recommended** for new projects.
   - `psycopg2-binary`: The previous-generation synchronous database adapter.
   - `asyncpg`: The asynchronous database adapter for connecting to Postgres.
   - `python-dotenv`: A helper library to manage environment variables.

   ```bash
   pip install "psycopg[binary]" psycopg2-binary asyncpg python-dotenv
   ```

   > If you're not sure which driver to use, use `psycopg` (v3). It's the actively maintained successor to `psycopg2`. This guide provides examples for all three in case your project already depends on one of the others.

## Store your Neon connection string

Create a file named `.env` in your project's root directory. This file stores your database connection string outside your code.

1. In the [Neon Console](https://console.neon.tech), open your project.
2. Click **Connect** in the Console nav to open the **Connect to your branch** modal.
   ![Connection modal](https://neon.com/docs/connect/connect_to_branch_modal.png)
3. Copy the connection string, which includes your password.
4. Add the connection string to your `.env` file as shown below.
   ```text
   DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
   ```
   > Replace `[user]`, `[password]`, `[neon_hostname]`, and `[dbname]` with your actual database credentials.

## Examples

This section provides example Python scripts that demonstrate how to connect to your Neon database and perform basic operations such as [creating a table](https://neon.com/docs/guides/python#create-a-table-and-insert-data), [reading data](https://neon.com/docs/guides/python#read-data), [updating data](https://neon.com/docs/guides/python#update-data), and [deleting data](https://neon.com/docs/guides/python#delete-data). Pick one driver and use its tab for all four scripts.

### Create a table and insert data

In your project directory, create a file named `create_table.py` and add the code for your preferred library. This script connects to your Neon database, creates a table named `books`, and inserts some sample data into it.

**psycopg (v3)**

```python title="create_table.py"
import os

import psycopg
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Get the connection string from the environment variable
conn_string = os.getenv("DATABASE_URL")

try:
    with psycopg.connect(conn_string) as conn:
        print("Connection established")

        # Open a cursor to perform database operations
        with conn.cursor() as cur:
            # Drop the table if it already exists
            cur.execute("DROP TABLE IF EXISTS books;")
            print("Finished dropping table (if it existed).")

            # Create a new table
            cur.execute("""
                CREATE TABLE books (
                    id SERIAL PRIMARY KEY,
                    title VARCHAR(255) NOT NULL,
                    author VARCHAR(255),
                    publication_year INT,
                    in_stock BOOLEAN DEFAULT TRUE
                );
            """)
            print("Finished creating table.")

            # Insert a single book record
            cur.execute(
                "INSERT INTO books (title, author, publication_year, in_stock) VALUES (%s, %s, %s, %s);",
                ("The Catcher in the Rye", "J.D. Salinger", 1951, True),
            )
            print("Inserted a single book.")

            # Data to be inserted
            books_to_insert = [
                ("The Hobbit", "J.R.R. Tolkien", 1937, True),
                ("1984", "George Orwell", 1949, True),
                ("Dune", "Frank Herbert", 1965, False),
            ]

            # Insert multiple books at once
            cur.executemany(
                "INSERT INTO books (title, author, publication_year, in_stock) VALUES (%s, %s, %s, %s);",
                books_to_insert,
            )

            print("Inserted 3 rows of data.")
            # The transaction is committed automatically when the 'with' block exits in psycopg (v3)

except Exception as e:
    print("Connection failed.")
    print(e)
```

**psycopg2**

```python title="create_table.py"
import os

import psycopg2
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

# Get the connection string from the environment variable
conn_string = os.getenv("DATABASE_URL")
conn = None

try:
    with psycopg2.connect(conn_string) as conn:
        print("Connection established")

        # Open a cursor to perform database operations
        with conn.cursor() as cur:
            # Drop the table if it already exists
            cur.execute("DROP TABLE IF EXISTS books;")
            print("Finished dropping table (if it existed).")

            # Create a new table
            cur.execute("""
                CREATE TABLE books (
                    id SERIAL PRIMARY KEY,
                    title VARCHAR(255) NOT NULL,
                    author VARCHAR(255),
                    publication_year INT,
                    in_stock BOOLEAN DEFAULT TRUE
                );
            """)
            print("Finished creating table.")

            # Insert a single book record
            cur.execute(
                "INSERT INTO books (title, author, publication_year, in_stock) VALUES (%s, %s, %s, %s);",
                ("The Catcher in the Rye", "J.D. Salinger", 1951, True),
            )
            print("Inserted a single book.")

            # Data to be inserted
            books_to_insert = [
                ("The Hobbit", "J.R.R. Tolkien", 1937, True),
                ("1984", "George Orwell", 1949, True),
                ("Dune", "Frank Herbert", 1965, False),
            ]

            # Insert multiple books at once
            cur.executemany(
                "INSERT INTO books (title, author, publication_year, in_stock) VALUES (%s, %s, %s, %s);",
                books_to_insert,
            )

            print("Inserted 3 rows of data.")

            # Commit the changes to the database
            conn.commit()

except Exception as e:
    print("Connection failed.")
    print(e)
```

**asyncpg**

```python title="create_table.py"
import asyncio
import os

import asyncpg
from dotenv import load_dotenv

# Load environment variables from .env file
load_dotenv()

async def run():
    # Get the connection string from the environment variable
    conn_string = os.getenv("DATABASE_URL")
    conn = None

    try:
        conn = await asyncpg.connect(conn_string)
        print("Connection established")

        # Drop the table if it already exists
        await conn.execute("DROP TABLE IF EXISTS books;")
        print("Finished dropping table (if it existed).")

        # Create a new table
        await conn.execute("""
            CREATE TABLE books (
                id SERIAL PRIMARY KEY,
                title VARCHAR(255) NOT NULL,
                author VARCHAR(255),
                publication_year INT,
                in_stock BOOLEAN DEFAULT TRUE
            );
        """)
        print("Finished creating table.")

        # Insert a single book record (using $1, $2 for placeholders)
        await conn.execute(
            "INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4);",
            "The Catcher in the Rye",
            "J.D. Salinger",
            1951,
            True,
        )
        print("Inserted a single book.")

        # Data to be inserted
        books_to_insert = [
            ("The Hobbit", "J.R.R. Tolkien", 1937, True),
            ("1984", "George Orwell", 1949, True),
            ("Dune", "Frank Herbert", 1965, False),
        ]

        # Insert multiple books at once
        await conn.executemany(
            "INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4);",
            books_to_insert,
        )
        print("Inserted 3 rows of data.")

    except Exception as e:
        print("Connection failed.")
        print(e)
    finally:
        if conn:
            await conn.close()

# Run the asynchronous function
asyncio.run(run())
```

The above code does the following:

- Load the connection string from the `.env` file.
- Connect to the Neon database.
- Drop the `books` table if it already exists to ensure a clean slate.
- Create a table named `books` with columns for `id`, `title`, `author`, `publication_year`, and `in_stock`.
- Insert a single book record.
- Insert multiple book records.
- Commit the changes to the database (in `psycopg`, this happens automatically on exiting the `with` block).

Run the script using the following command:

```bash
python create_table.py
```

When the code runs successfully, it produces the following output:

```text title="Output"
Connection established
Finished dropping table (if it existed).
Finished creating table.
Inserted a single book.
Inserted 3 rows of data.
```

### Read data

In your project directory, create a file named `read_data.py`. This script connects to your Neon database and retrieves all rows from the `books` table.

**psycopg (v3)**

```python title="read_data.py"
import os

import psycopg
from dotenv import load_dotenv

load_dotenv()

conn_string = os.getenv("DATABASE_URL")

try:
    with psycopg.connect(conn_string) as conn:
        print("Connection established")
        with conn.cursor() as cur:
            # Fetch all rows from the books table
            cur.execute("SELECT * FROM books ORDER BY publication_year;")
            rows = cur.fetchall()

            print("\n--- Book Library ---")
            for row in rows:
                print(
                    f"ID: {row[0]}, Title: {row[1]}, Author: {row[2]}, Year: {row[3]}, In Stock: {row[4]}"
                )
            print("--------------------\n")

except Exception as e:
    print("Connection failed.")
    print(e)
```

**psycopg2**

```python title="read_data.py"
import os

import psycopg2
from dotenv import load_dotenv

load_dotenv()

conn_string = os.getenv("DATABASE_URL")
conn = None

try:
    with psycopg2.connect(conn_string) as conn:
        print("Connection established")
        with conn.cursor() as cur:
            # Fetch all rows from the books table
            cur.execute("SELECT * FROM books ORDER BY publication_year;")
            rows = cur.fetchall()

            print("\n--- Book Library ---")
            for row in rows:
                print(
                    f"ID: {row[0]}, Title: {row[1]}, Author: {row[2]}, Year: {row[3]}, In Stock: {row[4]}"
                )
            print("--------------------\n")

except Exception as e:
    print("Connection failed.")
    print(e)
```

**asyncpg**

```python title="read_data.py"
import asyncio
import os

import asyncpg
from dotenv import load_dotenv

load_dotenv()

async def run():
    conn_string = os.getenv("DATABASE_URL")
    conn = None

    try:
        conn = await asyncpg.connect(conn_string)
        print("Connection established")

        # Fetch all rows from the books table
        rows = await conn.fetch("SELECT * FROM books ORDER BY publication_year;")

        print("\n--- Book Library ---")
        for row in rows:
            # asyncpg rows can be accessed by index or column name
            print(
                f"ID: {row['id']}, Title: {row['title']}, Author: {row['author']}, Year: {row['publication_year']}, In Stock: {row['in_stock']}"
            )
        print("--------------------\n")

    except Exception as e:
        print("Connection failed.")
        print(e)
    finally:
        if conn:
            await conn.close()

asyncio.run(run())
```

The above code does the following:

- Load the connection string from the `.env` file.
- Connect to the Neon database.
- Use a SQL `SELECT` statement to fetch all rows from the `books` table, ordered by `publication_year`.
- Print each book's details in a formatted output.

Run the script using the following command:

```bash
python read_data.py
```

When the code runs successfully, it produces the following output:

```text title="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: True
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: True
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: True
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: False
--------------------
```

### Update data

In your project directory, create a file named `update_data.py`. This script connects to your Neon database and updates the stock status of the book 'Dune' to `True`.

**psycopg (v3)**

```python title="update_data.py"
import os

import psycopg
from dotenv import load_dotenv

load_dotenv()
conn_string = os.getenv("DATABASE_URL")

try:
    with psycopg.connect(conn_string) as conn:
        print("Connection established")
        with conn.cursor() as cur:
            # Update a data row in the table
            cur.execute(
                "UPDATE books SET in_stock = %s WHERE title = %s;", (True, "Dune")
            )
            print("Updated stock status for 'Dune'.")

except Exception as e:
    print("Connection failed.")
    print(e)
```

**psycopg2**

```python title="update_data.py"
import os

import psycopg2
from dotenv import load_dotenv

load_dotenv()
conn_string = os.getenv("DATABASE_URL")
conn = None

try:
    with psycopg2.connect(conn_string) as conn:
        print("Connection established")
        with conn.cursor() as cur:
            # Update a data row in the table
            cur.execute(
                "UPDATE books SET in_stock = %s WHERE title = %s;", (True, "Dune")
            )
            print("Updated stock status for 'Dune'.")

            # Commit the changes
            conn.commit()

except Exception as e:
    print("Connection failed.")
    print(e)
```

**asyncpg**

```python title="update_data.py"
import asyncio
import os

import asyncpg
from dotenv import load_dotenv

load_dotenv()

async def run():
    conn_string = os.getenv("DATABASE_URL")
    conn = None
    try:
        conn = await asyncpg.connect(conn_string)
        print("Connection established")

        # Update a data row in the table
        await conn.execute(
            "UPDATE books SET in_stock = $1 WHERE title = $2;", True, "Dune"
        )
        print("Updated stock status for 'Dune'.")

    except Exception as e:
        print("Connection failed.")
        print(e)
    finally:
        if conn:
            await conn.close()

asyncio.run(run())
```

The above code does the following:

- Load the connection string from the `.env` file.
- Connect to the Neon database.
- Use a SQL `UPDATE` statement to change the `in_stock` status of the book 'Dune' to `True`.
- Commit the changes to the database.

Run the script using the following command:

```bash
python update_data.py
```

After running this script, you can run `read_data.py` again to verify that the row was updated.

```bash
python read_data.py
```

When the code runs successfully, it produces the following output:

```text title="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: True
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: True
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: True
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: True
--------------------
```

> You can see that the stock status for 'Dune' has been updated to `True`.

### Delete data

In your project directory, create a file named `delete_data.py`. This script connects to your Neon database and deletes the book '1984' from the `books` table.

**psycopg (v3)**

```python title="delete_data.py"
import os

import psycopg
from dotenv import load_dotenv

load_dotenv()
conn_string = os.getenv("DATABASE_URL")

try:
    with psycopg.connect(conn_string) as conn:
        print("Connection established")
        with conn.cursor() as cur:
            # Delete a data row from the table
            cur.execute("DELETE FROM books WHERE title = %s;", ("1984",))
            print("Deleted the book '1984' from the table.")

except Exception as e:
    print("Connection failed.")
    print(e)
```

**psycopg2**

```python title="delete_data.py"
import os

import psycopg2
from dotenv import load_dotenv

load_dotenv()
conn_string = os.getenv("DATABASE_URL")
conn = None

try:
    with psycopg2.connect(conn_string) as conn:
        print("Connection established")
        with conn.cursor() as cur:
            # Delete a data row from the table
            cur.execute("DELETE FROM books WHERE title = %s;", ("1984",))
            print("Deleted the book '1984' from the table.")

            # Commit the changes
            conn.commit()

except Exception as e:
    print("Connection failed.")
    print(e)
```

**asyncpg**

```python title="delete_data.py"
import asyncio
import os

import asyncpg
from dotenv import load_dotenv

load_dotenv()

async def run():
    conn_string = os.getenv("DATABASE_URL")
    conn = None
    try:
        conn = await asyncpg.connect(conn_string)
        print("Connection established")

        # Delete a data row from the table
        await conn.execute("DELETE FROM books WHERE title = $1;", "1984")
        print("Deleted the book '1984' from the table.")

    except Exception as e:
        print("Connection failed.")
        print(e)
    finally:
        if conn:
            await conn.close()

asyncio.run(run())
```

The above code does the following:

- Load the connection string from the `.env` file.
- Connect to the Neon database.
- Use a SQL `DELETE` statement to remove the book '1984' from the `books` table.
- Commit the changes to the database.

Run the script using the following command:

```bash
python delete_data.py
```

After running this script, you can run `read_data.py` again to verify that the row was deleted.

```bash
python read_data.py
```

When the code runs successfully, it produces the following output:

```text title="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: True
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: True
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: True
--------------------
```

> You can see that the book '1984' has been deleted from the `books` table.

## Use an ORM or framework

While this guide demonstrates how to connect to Neon using raw SQL queries, for more advanced and maintainable data interactions in your Python applications, consider using an Object-Relational Mapping (ORM) framework. ORMs let you work with data as objects and manage schema changes through migrations, keeping your database structure in sync with your application models.

Explore the following resources to learn how to integrate ORMs with Neon:

- [Connect an SQLAlchemy application to Neon](https://neon.com/docs/guides/sqlalchemy)
- [Connect a Django application to Neon](https://neon.com/docs/guides/django)

## Next steps: Neon backend services

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

## Resources

- [Psycopg 3 documentation](https://www.psycopg.org/psycopg3/docs/)
- [Psycopg 2 documentation](https://www.psycopg.org/docs/)
- [asyncpg documentation](https://magicstack.github.io/asyncpg/current/)
- [Building an API with Django, Django REST Framework, and Lakebase Postgres](https://neon.com/guides/django-rest-api)

--- [Document source](https://neon.com/docs/guides/quarkus-jdbc.md) ---

> Summary: Quarkus JDBC connection to a Lakebase Postgres database uses the PostgreSQL JDBC driver with Agroal datasource and RESTEasy Reactive extensions, configured via `QUARKUS_DATASOURCE_*` environment variables in a `.env` file. Use this guide when connecting a Java Quarkus app to a Lakebase Postgres database over JDBC rather than a reactive driver. The guide covers Quarkus project scaffolding, datasource configuration with SSL required, and a working HTTP endpoint that queries the Postgres version.

# Connect Quarkus (JDBC) to Neon

Learn how to connect to a Lakebase Postgres database from Quarkus using JDBC

Last updated: 2026-09-16

Pre-built prompt for connecting Quarkus applications to Lakebase Postgres using JDBC [View prompt](https://neon.com/prompts/quarkus-jdbc-prompt.md)

[Quarkus](https://quarkus.io/) is a Java framework optimized for cloud environments. This guide shows how to connect to Neon from a Quarkus project using the PostgreSQL JDBC driver.

To connect to a Lakebase Postgres database from a Quarkus application using the Postgres JDBC driver:

## Prerequisites

- [JDK 21](https://www.oracle.com/java/technologies/downloads/) or later. The project that Quarkus creates compiles for Java 21.
- The [Quarkus CLI](https://quarkus.io/guides/cli-tooling).

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Quarkus project

Create a Quarkus project using the [Quarkus CLI](https://quarkus.io/guides/cli-tooling):

```shell
quarkus create app neon-with-quarkus-jdbc \
--name neon-with-quarkus-jdbc \
--package-name com.neon.tech \
--extensions jdbc-postgresql,quarkus-agroal,resteasy-reactive
```

You now have a Quarkus project in a folder named `neon-with-quarkus-jdbc` with the PostgreSQL JDBC driver, Agroal datasource implementation, and RESTEasy Reactive extensions installed.

## Configure a PostgreSQL data source

Create a `.env` file in the root of your Quarkus project directory. Configure a JDBC data source using the components of your database connection string and specifying the database kind as shown:

```text filename=".env"
QUARKUS_DATASOURCE_DB_KIND=postgresql
QUARKUS_DATASOURCE_USERNAME=[user]
QUARKUS_DATASOURCE_PASSWORD=[password]
QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://[neon_hostname]/[dbname]?sslmode=require&channelBinding=require
```

**Note:** You can find the connection details for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Use the PostgreSQL JDBC Driver

Create a `PostgresResource.java` file in the same directory as the `GreetingResource.java` that was generated by Quarkus during project creation. Paste the following content into the `PostgresResource.java` file:

```java
package com.neon.tech;

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import javax.sql.DataSource;
import jakarta.inject.Inject;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/postgres")
public class PostgresResource {
    @Inject
    DataSource dataSource;

    @GET
    @Path("/version")
    @Produces(MediaType.TEXT_PLAIN)
    public String getVersion() {
        try (Connection connection = dataSource.getConnection();
                Statement statement = connection.createStatement()) {

            ResultSet resultSet = statement.executeQuery("SELECT version()");

            if (resultSet.next()) {
                return resultSet.getString(1);
            }
        } catch (SQLException e) {
            e.printStackTrace();
        }
        return null;
    }
}
```

This code defines a HTTP endpoint that will query the database version and return it as a response to incoming requests.

## Run the application

Start the application in development mode using the Quarkus CLI from the root of the project directory:

```shell
quarkus dev
```

Visit [localhost:8080/postgres/version](http://localhost:8080/postgres/version) in your web browser. Your Neon database's Postgres version will be returned. For example:

```
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/quarkus-reactive.md) ---

> Summary: Quarkus Reactive SQL Client connects Java applications to Lakebase Postgres using non-blocking I/O via the Vert.x PgPool driver, instead of JDBC, making it the right choice when building reactive, cloud-native Quarkus services. The guide covers scaffolding a project with the reactive-pg-client extension, configuring QUARKUS_DATASOURCE_REACTIVE_URL with sslmode=require, and exposing a REST endpoint that queries the database asynchronously using Mutiny.

# Connect Quarkus (Reactive) to Neon

Learn how to connect to a Lakebase Postgres database from Quarkus using a Reactive SQL Client

Last updated: 2026-09-16

Pre-built prompt for connecting Quarkus applications to Lakebase Postgres using Reactive SQL Client [View prompt](https://neon.com/prompts/quarkus-reactive-prompt.md)

[Quarkus](https://quarkus.io/) is a Java framework optimized for cloud environments. This guide shows how to connect to Neon from a Quarkus project using a Reactive SQL Client.

To connect to a Lakebase Postgres database from a Quarkus application:

## Prerequisites

- [JDK 21](https://www.oracle.com/java/technologies/downloads/) or later. The project that Quarkus creates compiles for Java 21.
- The [Quarkus CLI](https://quarkus.io/guides/cli-tooling).

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Quarkus project

Create a Quarkus project using the [Quarkus CLI](https://quarkus.io/guides/cli-tooling):

```shell
quarkus create app neon-with-quarkus \
--name neon-with-quarkus \
--package-name com.neon.tech \
--extensions reactive-pg-client,resteasy-reactive
```

You now have a Quarkus project in a folder named `neon-with-quarkus` with the Reactive Postgres client and RESTEasy Reactive extensions installed.

## Configure a PostgreSQL data source

Create a `.env` file in the root of your Quarkus project directory. Configure a reactive data source using your database connection string and specifying the database kind as shown:

```text filename=".env"
QUARKUS_DATASOURCE_REACTIVE_URL=postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require
```

**Note:** You can find the connection details for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Use the Reactive PostgreSQL client

Create a `PostgresResource.java` file in the `src/main/java/com/neon/tech` directory of your project. Paste the following content into the `PostgresResource.java` file:

```java
package com.neon.tech;

import jakarta.inject.Inject;
import io.smallrye.mutiny.Multi;
import io.vertx.mutiny.sqlclient.Row;
import io.vertx.mutiny.sqlclient.RowSet;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/postgres")
public class PostgresResource {
    @Inject
    io.vertx.mutiny.pgclient.PgPool client;

    @GET
    @Path("/version")
    @Produces(MediaType.TEXT_PLAIN)
    public Multi<String> getVersion() {
        return client.query("SELECT version()")
                .execute()
                .onItem().transformToMulti(this::extractVersion);
    }

    private Multi<String> extractVersion(RowSet<Row> rowSet) {
        return Multi.createFrom().iterable(rowSet)
                .map(r -> r.getValue(0).toString());
    }
}
```

This code defines a HTTP endpoint that will query the database version and return it as a response to incoming requests.

## Run the application

Start the application in development mode using the Quarkus CLI from the root of the project directory:

```shell
quarkus dev
```

Visit [localhost:8080/postgres/version](http://localhost:8080/postgres/version) in your web browser. Your Neon database's Postgres version will be returned. For example:

```
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/rails-migrations.md) ---

> Summary: Ruby on Rails Active Record migrations against Lakebase Postgres require a direct (non-pooled) connection string in `DATABASE_URL` because PgBouncer pooled connections can cause migration errors. This guide walks through creating a Rails project, configuring `database.yml` to read `DATABASE_URL`, running `rails db:migrate` to create tables, and applying incremental schema changes such as adding a new column with a follow-on migration.

# Schema migration with Lakebase Postgres and Ruby on Rails

Set up a database on Neon and run migrations for your Rails project

Last updated: 2026-10-28

[Ruby on Rails](https://rubyonrails.org/) is a popular web application framework for Ruby developers. It provides an ORM (Object-Relational Mapping) layer called `Active Record`, that simplifies database interactions and schema management. Rails also includes a powerful migration system that allows you to define and manage database schema changes over time.

This guide demonstrates how to run schema migrations in your Ruby on Rails project backed by the Lakebase Postgres database. We'll create a simple Rails application and walk through the process of setting up the database, defining models, and generating and running migrations to manage schema changes.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.

- [Ruby](https://www.ruby-lang.org/) installed on your local machine.

  You can install Ruby using the instructions provided on the [official Ruby website](https://www.ruby-lang.org/en/documentation/installation/). We recommend using a newer version of Ruby, 3.0 or higher.

- [Rails](https://rubyonrails.org/) installed on your local machine. You can install Rails by running `gem install rails`.

  We recommend using Rails 6 or higher. This project uses `Rails 7.1.3.2`.

## Setting up your database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select a project or click the **New Project** button to create a new one.

### Retrieve your database connection string

You can find the connection string for your database by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

**Note:** Neon supports both direct and pooled database connection strings. You can find a connection string for your database by clicking the **Connect** button in the Console nav. A pooled connection string connects your application to the database via a PgBouncer connection pool, allowing for a higher number of concurrent connections. However, using a pooled connection string for migrations can be prone to errors. For this reason, we recommend using a direct (non-pooled) connection when performing migrations. For more information about direct and pooled connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Setting up the Rails project

### Create a new Rails project

Open your terminal and run the following command to create a new Rails project:

```bash
rails new guide-neon-rails --database=postgresql
```

This command creates a new Rails project named `guide-neon-rails` with Postgres as the default database. It will also generate the necessary project files and directories, and install the required dependencies.

### Set up the Database configuration

Create a `.env` file in the project root directory and add the `DATABASE_URL` environment variable to it. Use the connection string that you obtained from the Neon Console earlier:

```bash
# .env

DATABASE_URL=NEON_POSTGRES_CONNECTION_STRING
```

For Rails to load the environment variables automatically from the `.env` file, add the `dotenv-rails` gem to the `Gemfile` at the root of your project:

```ruby
# Gemfile

gem 'dotenv-rails', groups: [:development, :test]
```

Then, run `bundle install` to install the gem.

Finally, we open the `config/database.yml` file in your project directory and update the `default` section so that Rails uses the `DATABASE_URL` environment variable to connect to the `Neon` database.

```yaml
# database.yml

default: &default
  adapter: postgresql
  encoding: unicode
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  url: <%= ENV['DATABASE_URL'] %>

development:
  <<: *default

test:
  <<: *default

production:
  <<: *default
```

## Defining data models and running migrations

### Generate models and migrations

Next, we will create the data models for our application. Run the following commands to generate the `Author` and `Book` models:

```bash
rails generate model Author name:string bio:text
rails generate model Book title:string author:references
```

These commands generate model files and the corresponding migration files in the `app/models` and `db/migrate` directories, respectively.

### Run the migrations

To run the migrations and create the corresponding tables in the Lakebase Postgres database, run the following command:

```bash
rails db:migrate
```

This command executes the migration files and creates the `authors` and `books` tables in the database. Additionally, it also creates some tables for its internal bookkeeping.

### Seed the database

To populate the database with some initial data, open the `db/seeds.rb` file and add the following code:

```ruby
# db/seeds.rb

# Find or create authors
authors_data = [
  {
    name: "J.R.R. Tolkien",
    bio: "The creator of Middle-earth and author of The Lord of the Rings."
  },
  {
    name: "George R.R. Martin",
    bio: "The author of the epic fantasy series A Song of Ice and Fire."
  },
  {
    name: "J.K. Rowling",
    bio: "The creator of the Harry Potter series."
  }
]

authors_data.each do |author_attrs|
  Author.find_or_create_by(name: author_attrs[:name]) do |author|
    author.bio = author_attrs[:bio]
  end
end

# Find or create books
books_data = [
  { title: "The Fellowship of the Ring", author_name: "J.R.R. Tolkien" },
  { title: "The Two Towers", author_name: "J.R.R. Tolkien" },
  { title: "The Return of the King", author_name: "J.R.R. Tolkien" },
  { title: "A Game of Thrones", author_name: "George R.R. Martin" },
  { title: "A Clash of Kings", author_name: "George R.R. Martin" },
  { title: "Harry Potter and the Philosopher's Stone", author_name: "J.K. Rowling" },
  { title: "Harry Potter and the Chamber of Secrets", author_name: "J.K. Rowling" }
]

books_data.each do |book_attrs|
  author = Author.find_by(name: book_attrs[:author_name])
  Book.find_or_create_by(title: book_attrs[:title], author: author)
end
```

To run the seed file and populate the database with the initial data, run the following command:

```bash
rails db:seed
```

This command inserts the sample authors and books data into the database. Note that the script looks for existing records before creating new ones, so you can run it multiple times without duplicating the data.

## Implement the application

### Create controllers and views

Next, we will create controllers and views to display the authors and books in our application. Run the following commands to generate the controllers:

```bash
rails generate controller Authors index
rails generate controller Books index
```

These commands generate controller files and corresponding view files in the `app/controllers` and `app/views` directories.

Open the `app/controllers/authors_controller.rb` file and update the `index` action:

```ruby
# app/controllers/authors_controller.rb

class AuthorsController < ApplicationController
  def index
    @authors = Author.all
  end
end
```

Similarly, open the `app/controllers/books_controller.rb` file and update the `index` action:

```ruby
# app/controllers/books_controller.rb

class BooksController < ApplicationController
  def index
    @author = Author.find(params[:author_id])
    @books = @author.books
  end
end
```

Now, we update the corresponding views to display the data. Open the `app/views/authors/index.html.erb` file and add the following code:

```erb
<!-- app/views/authors/index.html.erb -->

<h1>Authors</h1>
<ul>
  <% @authors.each do |author| %>
    <li>
      <%= author.name %> - <%= link_to 'Books', author_books_path(author_id: author.id) %>
    </li>
  <% end %>
</ul>
```

Open the `app/views/books/index.html.erb` file and add the following code:

```erb
<!-- app/views/books/index.html.erb -->

<h1>Books by <%= @author.name %></h1>

<ul>
  <% @books.each do |book| %>
    <li><%= book.title %></li>
  <% end %>
</ul>
```

### Define routes

Open the `config/routes.rb` file and define the routes for the authors and books:

```ruby
# config/routes.rb

Rails.application.routes.draw do
    resources :authors, only: [:index]
    get '/books/:author_id', to: 'books#index', as: 'author_books'
end
```

### Run the Rails server

To start the Rails server and test the application, run the following command:

```bash
rails server
```

Navigate to the url `http://localhost:3000/authors` in your browser to view the list of authors. You can also view the books by a specific author by clicking on the "Books" link next to each author, which takes you to the `http://localhost:3000/books/:author_id` route.

## Applying schema changes

We will demonstrate how to handle schema changes by adding a new field `country` to the `Author` model, to store the author's country of origin.

### Generate a migration

To generate a migration file for adding the `country` field to the `authors` table, run the following command:

```bash
rails generate migration AddCountryToAuthors country:string
```

This command generates a new migration file in the `db/migrate` directory.

### Run the migration

To run the migration and apply the schema change, run the following command:

```bash
rails db:migrate
```

This command executes the migration file and adds the `country` column to the `authors` table in the database.

### Update the existing records

To update the existing records with the author's country, open the `db/seeds.rb` file and update the authors data with the country information:

```ruby
authors_data = [
  {
    name: "J.R.R. Tolkien",
    bio: "The creator of Middle-earth and author of The Lord of the Rings.",
    country: "United Kingdom"
  },
  {
    name: "George R.R. Martin",
    bio: "The author of the epic fantasy series A Song of Ice and Fire.",
    country: "United States"
  },
  {
    name: "J.K. Rowling",
    bio: "The creator of the Harry Potter series.",
    country: "United Kingdom"
  }
]

authors_data.each do |author_attrs|
  author = Author.find_or_initialize_by(name: author_attrs[:name])
  author.assign_attributes(author_attrs)
  author.save if author.changed?
end
```

Run the seed file again to update the existing records in the database:

```bash
rails db:seed
```

### Test the schema change

Update the `app/views/authors/index.html.erb` file to display the country alongside each author:

```erb
<!-- app/views/authors/index.html.erb -->

<h1>Authors</h1>
<ul>
  <% @authors.each do |author| %>
    <li>
      <%= author.name %> - <%= author.country %> - <%= link_to 'Books', author_books_path(author_id: author.id) %>
    </li>
  <% end %>
</ul>
```

Now, restart the Rails server:

```bash
rails server
```

Navigate to the url `http://localhost:3000/authors` to view the list of authors. The `country` field is now available for each author, reflecting the schema change.

## Conclusion

In this guide, we demonstrated how to set up a Ruby on Rails project with Lakebase Postgres, define database models, generate migrations, and run them. Rails' Active Record ORM and migration system make it easy to interact with the database and manage schema evolution over time.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Migrations with Neon and Rails](https://github.com/neondatabase/guide-neon-rails): Run migrations in a Neon-Rails project

## Resources

For more information on the tools and concepts used in this guide, refer to the following resources:

- [Ruby on Rails Guides](https://guides.rubyonrails.org/)
- [Active Record Migrations](https://guides.rubyonrails.org/active_record_migrations.html)
- [Neon](https://neon.com/docs)

--- [Document source](https://neon.com/docs/guides/railway.md) ---

> Summary: Connecting a Lakebase Postgres database to a Node.js application deployed on Railway lets you use GitHub-based continuous deployment with a serverless Postgres backend. Use this guide when you need a manual Express + pg setup with full control over schema creation, environment variables, and deployment steps. A faster alternative uses the Railway Next.js template with Claimable Postgres, which provisions a database instantly without signup and stays claimable for 72 hours.

# Use Lakebase Postgres with Railway

Connect a Lakebase Postgres database to your Node application deployed with Railway

Last updated: 2026-10-09

[Railway](https://railway.com?utm_medium=integration\&utm_source=button\&utm_campaign=neon) is a cloud deployment platform that allows users to deploy anything, anywhere, seamlessly. On Railway, develop locally, connect to a repository or image, and have infrastructure provisioned automatically. Railway integrates with GitHub for continuous deployment and supports a variety of programming languages and frameworks.

This guide shows how to deploy a simple Node.js application connected to a Lakebase Postgres database on Railway.

## Quick start alternative

If you want to get started quickly with Next.js and Lakebase Postgres on Railway, you can use the [Next.js with Neon Postgres template](https://railway.com/deploy/nextjs-with-neon-postgres?utm_medium=integration\&utm_source=button\&utm_campaign=neon). That template provisions a database without signup. The current no-signup project flow is [Claimable Neon](https://neon.com/docs/reference/claimable-neon). Unclaimed projects expire in 72 hours.

For a more detailed walkthrough using Node.js/Express with manual setup, continue with this guide below.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.com). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- A Railway account. If you do not have one, sign up at [Railway](https://railway.com?utm_medium=integration\&utm_source=button\&utm_campaign=neon) to get started.
- A GitHub account. Railway integrates with GitHub for continuous deployment. So, you'd need a GitHub account to upload your application code.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.

## Setting up your database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.

2. Click the `New Project` button to create a new project.

3. In the Neon Console, navigate to **Postgres database** > **SQL Editor** from the sidebar, and run the following SQL command to create a new table in your database:

   ```sql
   CREATE TABLE plant_care_log (
       id SERIAL PRIMARY KEY,
       plant_name VARCHAR(255) NOT NULL,
       care_date DATE NOT NULL
   );
   ```

   Next, we insert some sample data into the `plant_care_log` table, so we can query it later:

   ```sql
   INSERT INTO plant_care_log (plant_name, care_date)
   VALUES
       ('Monstera', '2024-01-10'),
       ('Fiddle Leaf Fig', '2024-01-15'),
       ('Snake Plant', '2024-01-20'),
       ('Spider Plant', '2024-01-25'),
       ('Pothos', '2024-01-30');
   ```

### Retrieve your Neon database connection string

You can find the connection string for your database by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

## Implementing the Node.js application

We'll create a simple Express application that connects to our Neon database and retrieves the list of plants tended to within the last month. Run the following commands in a terminal to set it up.

```bash
mkdir neon-railway-example && cd neon-railway-example
npm init -y && npm pkg set type="module"
npm install express pg
touch .env
```

We use the `npm pkg set type="module"` command to enable ES6 module support in our project. We also create a new `.env` file to store the `DATABASE_URL` environment variable, which we'll use to connect to our Neon database. Lastly, we install the `pg` library which is the Postgres driver we use to connect to our database.

```bash
# .env
DATABASE_URL=NEON_DATABASE_CONNECTION_STRING
```

Now, create a new file named `index.js` and add the following code:

```javascript
import express from 'express';
import pkg from 'pg';

const app = express();
const port = process.env.PORT || 3000;

// Parse JSON bodies for this app
app.use(express.json());

// Create a new pool using your Neon database connection string
const { Pool } = pkg;
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

app.get('/', async (req, res) => {
  try {
    // Fetch the list of plants from your database using the postgres connection
    const { rows } = await pool.query('SELECT * FROM plant_care_log;');
    res.json(rows);
  } catch (error) {
    console.error('Failed to fetch plants', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

// Start the server
app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});
```

This code sets up an Express server that listens for requests on port 3000. When a request is made to the `URL`, the server queries the `plant_care_log` table in your Neon database and returns the results as JSON.

We can test this application locally by running:

```bash
node --env-file=.env index.js
```

Now, navigate to `http://localhost:3000/` in your browser to check it returns the sample data from the `plant_care_log` table.

## Push Your application to GitHub

To deploy your application to Railway, you need to push your code to a GitHub repository. Create a new repository on GitHub by navigating to [GitHub - New Repo](https://github.com/new). You can then push your code to the new repository using the following commands:

```bash
echo "node_modules/" > .gitignore && echo ".env" >> .gitignore
echo "# neon-railway-example" >> README.md
git init && git add . && git commit -m "Initial commit"
git branch -M main
git remote add origin YOUR_GITHUB_REPO_URL
git push -u origin main
```

You can visit the GitHub repository to verify that your code has been pushed successfully.

## Deploying to Railway

### Creating a new Railway project

Log in to your Railway account and navigate to the dashboard. Click on the `New Project` button and select the `Deploy from GitHub repo` option. Pick the repository you created above, which sets off a Railway deployment.

Railway automatically figures out the type of application you're deploying and sets up the necessary build and start commands. However, we still need to add the `DATABASE_URL` environment variable to connect to our Neon database.

Select the project and navigate to the `Variables` tab. Add a new variable named `DATABASE_URL` and set its value to your Neon database connection string. You can redeploy the project by clicking on `Redeploy` from the context menu of the latest deployment.

### Verify Deployment

Once the deployment completes and is marked as `ACTIVE`, Railway provides a public URL for accessing the web service. Visit the provided URL to verify that your application is running and can connect to your Neon database.

Whenever you update your code and push it to your GitHub repository, Railway will automatically build and deploy the changes to your web service.

## Removing Your Application and Neon Project

To remove your application from Railway, select the project and navigate to the `Settings` tab. Scroll down to the end to find the "Delete Service" option.

To delete your Neon project, follow the steps outlined in the Neon documentation under [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

## Resources

- [Railway platform](https://railway.com?utm_medium=integration\&utm_source=button\&utm_campaign=neon)
- [Next.js with Neon Postgres Railway template](https://railway.com/deploy/nextjs-with-neon-postgres?utm_medium=integration\&utm_source=button\&utm_campaign=neon)
- [Claimable Neon](https://neon.com/docs/reference/claimable-neon)

--- [Document source](https://neon.com/docs/guides/react-router.md) ---

> Summary: React Router full-stack integration with Lakebase Postgres runs database queries server-side inside a route `loader` function, keeping credentials and SQL out of the browser. Use this guide when building a React Router app that needs a serverless Postgres backend, with driver options for node-postgres, postgres.js, or the Neon serverless driver.

# Connect a React Router application to Neon

Set up a project on Neon in seconds and connect from a React Router application

Last updated: 2026-10-08

[React Router](https://reactrouter.com/home) is a powerful routing library for React that also includes modern, full-stack framework features. This guide explains how to connect a React Router application to Neon using a server-side `loader` function.

To create a project on Neon and access it from a React Router application:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a React Router project and add dependencies

1. Create a React Router project using the following command:

   ```shell
   npx create-react-router@latest with-react-router --yes
   cd with-react-router
   ```

2. Add project dependencies using one of the following commands.

   **node-postgres**

   ```shell
   npm install pg
   npm install -D @types/pg
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless
   ```

## Store your Neon credentials

Add a `.env` file to your project's root directory and add your Neon connection string to it. You can find the connection string for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

**Note:** `pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. If you use node-postgres, change `sslmode=require` to `sslmode=verify-full` to keep the current behavior and remove the warning.

## Configure the Postgres client

With React Router, data fetching is handled in route modules. The following steps add a new route that connects to Neon in its `loader` function, which runs on the server.

### 1. Define the route

First, add a route to `app/routes.ts`. This tells React Router to render the new component when a user visits the `/version` path. Keep your existing `index` route as it is (new projects use `routes/home.tsx`).

```typescript {5} filename=app/routes.ts
import { type RouteConfig, route, index } from '@react-router/dev/routes';

export default [
  index('routes/home.tsx'),
  route('version', './routes/version.tsx'),
] satisfies RouteConfig;
```

### 2. Create the route module

Create a new file at `app/routes/version.tsx`. This file will contain both the server-side data loader and the client-side React component. The `loader` function will connect to Neon, query the database version, and pass the result to the `Component` via the `loaderData` prop.

**node-postgres**

```tsx filename=app/routes/version.tsx
import { Pool } from 'pg';
import type { Route } from './+types/version';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

// The loader function runs on the server
export async function loader() {
  const client = await pool.connect();
  try {
    const { rows } = await client.query('SELECT version()');
    return { version: rows[0].version };
  } finally {
    client.release();
  }
}

// The component runs in the browser
export default function Version({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      <h1>Database Version</h1>
      <p>{loaderData.version}</p>
    </div>
  );
}
```

**postgres.js**

```tsx filename=app/routes/version.tsx
import postgres from 'postgres';
import type { Route } from './+types/version';

const sql = postgres(process.env.DATABASE_URL as string);

// The loader function runs on the server
export async function loader() {
  const response = await sql`SELECT version()`;
  return { version: response[0].version };
}

// The component runs in the browser
export default function Version({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      <h1>Database Version</h1>
      <p>{loaderData.version}</p>
    </div>
  );
}
```

**Neon serverless driver**

```tsx filename=app/routes/version.tsx
import { neon } from '@neondatabase/serverless';
import type { Route } from './+types/version';

// The loader function runs on the server
export async function loader() {
  const sql = neon(process.env.DATABASE_URL as string);
  const response = await sql`SELECT version()`;
  return { version: response[0].version };
}

// The component runs in the browser
export default function Version({ loaderData }: Route.ComponentProps) {
  return (
    <div>
      <h1>Database Version</h1>
      <p>{loaderData.version}</p>
    </div>
  );
}
```

## Run the app

### Generate types

Run the following command to generate types for your routes:

```shell
npm run typecheck
```

### Start the development server

With the types generated, start the development server:

```shell
npm run dev
```

Now, navigate to [http://localhost:5173/version](http://localhost:5173/version) in your browser. You should see a page displaying the version of your database.

```text
Database Version
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

**Note:** `npm run dev` loads `.env` automatically. The production server (`npm run build` then `npm start`) does not, so set `DATABASE_URL` in your environment before you start it.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/quick-start/react): Add managed authentication that branches with your database
- [Realtime](https://neon.com/docs/realtime/sdks/typescript#react): Build realtime React apps on Neon with end-to-end reactivity and type-safety »

--- [Document source](https://neon.com/docs/guides/react.md) ---

> Summary: React connection hub for Lakebase Postgres, directing developers to server-side integration guides for Next.js, React Router, Remix, and TanStack Start. Use this page when setting up a Lakebase Postgres connection from a React meta-framework, since Lakebase Postgres must be accessed server-side in React apps. Neon Auth quick starts for Next.js and TanStack Router are also linked here.

# Connect a React application to Neon

Set up a Neon project in seconds and connect from a React application

Last updated: 2026-10-08

React is an open-source JavaScript library for building component-based user interfaces.

Connect to Lakebase Postgres from the server side of a React application, never from the browser. The following React frameworks each have a guide for configuring a server-side connection.

## React frameworks

- [TanStack Start](https://neon.com/docs/guides/tanstack-start): Connect a TanStack Start application to Neon
- [Next.js](https://neon.com/docs/guides/nextjs): Connect a Next.js application to Neon
- [React Router](https://neon.com/docs/guides/react-router): Connect a React Router application to Neon
- [Remix](https://neon.com/docs/guides/remix): Connect a Remix application to Neon

## Managed Better Auth

After you connect your database, add managed authentication with [Managed Better Auth](https://neon.com/docs/auth/overview). Quick starts are available for these React frameworks:

- [Next.js](https://neon.com/docs/auth/quick-start/nextjs-api-only): Set up Managed Better Auth with Next.js
- [TanStack Router](https://neon.com/docs/auth/quick-start/tanstack-router): Set up Managed Better Auth with TanStack Router

For React Router, follow the [React Auth quick start](https://neon.com/docs/auth/quick-start/react).

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/sdks/typescript#react): Build realtime React apps on Neon with end-to-end reactivity and type safety

--- [Document source](https://neon.com/docs/guides/read-only-access-read-replicas.md) ---

> Summary: Neon read replicas let you grant read-only database access to partners, third-party apps, or analysts by routing SELECT queries to an isolated compute that blocks all writes (SQLSTATE 25006). Use this approach when you need to share live data for reporting or audits without risking changes to production. Setup requires creating the replica in the Console and sharing its connection string.

# Provide read-only access with Read Replicas

Leverage read replicas to provide read-only access to your data

Last updated: 2026-09-16

When you create a read replica in Neon, you gain the ability to provide read-only access to your data. Use it when you want to grant access to users, partners, or third-party applications that only need to run queries to analyze data, generate reports, or audit your database. Since no write operations are permitted on read replicas, it ensures the integrity of your data while allowing others to work with up-to-date information.

Suppose you need to give a partner read-only access to your sales data so they can generate custom reports for your business. Here's how you would go about doing that:

1. **Create a read replica**

   **Note:** On paid plans, you can add up to 6 read replicas per branch. The Free plan is limited to 3 read replica computes per project.

   Follow these steps to create a read replica for your database branch:

   - In the Neon Console, go to **Branches**.
   - Select the branch that contains your data.
   - Click **Add Read Replica** to create a dedicated compute instance for read operations.

2. **Provide the connection string**

   Once the read replica is created, obtain the connection string from the Neon Console:

   - You can find the connection details for your database by clicking the **Connect** button in the Console nav. Select the branch, the database, and the role.
   - Choose **Replica** compute under the compute settings.
   - Copy the connection string and provide it to your partner. The connection string might look something like this:

     ```bash
     postgresql://partner:partner_password@ep-read-replica-12345.us-east-2.aws.neon.tech/sales_db?sslmode=require&channel_binding=require
     ```

3. **Read-only access for the partner**

   The partner can now use this connection string to connect to the read replica and run any `SELECT` queries they need for reporting purposes, such as:

   ```sql
   SELECT product_id, SUM(sale_amount) as total_sales
   FROM sales
   WHERE sale_date >= (CURRENT_DATE - INTERVAL '1 year')
   GROUP BY product_id;
   ```

   This query will run on the read replica without impacting the performance of your production database, since read replicas run on an isolated read-only compute.

4. **Write operations are not permitted**

   Since the connection is to a read replica, the partner will not be able to run any write operations. If they attempt to run a `DELETE`, `INSERT`, or `UPDATE` query, they will receive an error message like this:

   ```bash
   ERROR: cannot execute INSERT in a read-only transaction (SQLSTATE 25006)
   ```

--- [Document source](https://neon.com/docs/guides/read-replica-adhoc-queries.md) ---

> Summary: Neon Read Replicas provide dedicated read-only compute for running ad-hoc queries, one-off analytics, and exploratory SQL without loading the primary database. Use this page when you need to offload impromptu aggregations, troubleshooting queries, or custom reports to an isolated replica rather than running them against production. Replicas share primary storage at no extra cost and automatically suspend after 5 minutes of inactivity.

# Run ad-hoc queries with Read Replicas

Leverage read replicas for running ad-hoc queries

Last updated: 2026-10-09

In many situations, you may need to run quick, one-time queries to retrieve specific data or test an idea. These are known as **ad-hoc queries**. Ad-hoc queries work well for tasks like analytics, troubleshooting, or exploring your data without setting up complex reports. However, running resource-intensive queries on your production database can degrade performance, especially if they target heavily used tables.

This is where **Neon Read Replicas** come in handy. With read replicas, you can quickly create a replica that runs on dedicated read-only compute, allowing you to run ad-hoc queries without impacting your primary database's performance. Once you're done, the read replica can automatically scale to zero, or you can delete it. The key advantages of using Neon Read Replicas for ad-hoc queries include the following:

- You can add a fully functional read replica in seconds.
- There's no additional storage cost or data replication, as the replica uses the same storage as your primary compute.
- The read replica compute automatically scales to zero based on your [scale to zero](https://neon.com/docs/introduction/scale-to-zero) settings. A compute suspends due to inactivity after 5 minutes of inactivity.
- You can remove a read replica as quickly as you created it or just leave it for next time. The compute will remain suspended until you run your next query.

## What is an ad-hoc query?

An ad-hoc query is an impromptu query used to retrieve specific data from your database. These queries are not part of routine reporting or pre-written scripts; they are created on the fly to answer immediate questions or perform temporary analysis. For example, if you want to quickly calculate the total sales for a product over the last month, you might write an SQL query like this:

```sql
SELECT product_id, SUM(sale_amount)
FROM sales
WHERE sale_date >= (CURRENT_DATE - INTERVAL '1 month')
GROUP BY product_id;
```

## Why run ad-hoc queries on a read replica?

Running ad-hoc queries on a read replica can help you:

- **Avoid performance issues**: Heavy ad-hoc queries, such as large aggregations or joins, can slow down your production database. A read replica offloads that work.
- **Isolate query load**: Since ad-hoc queries may be exploratory and involve significant data scanning, running them on a replica prevents unplanned queries from affecting your production traffic.
- **Ensure data consistency**: With Neon, read replicas access the same data as your primary compute, ensuring your ad-hoc queries reflect up-to-date information.

## Setting up a read replica for ad-hoc queries

**Note:** On paid plans, you can add up to 6 read replicas per branch. The Free plan is limited to 3 read replica computes per project.

You can add a read replica compute to any branch in your Neon project by following these steps:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Click **Add Read Replica**.
4. On the **Add new compute** dialog, select **Read replica** as the **Compute type**.
5. Specify the **Compute size settings**. You can configure a fixed-size compute with a specific amount of RAM (the default) or enable autoscaling by configuring a minimum and maximum compute size using the slider. On paid plans, you can adjust the **Scale to zero time** setting, which controls whether a compute suspends due to inactivity after 5 minutes.

   **Note:** The compute size configuration determines the processing power of your database.
6. When you finish making your selections, click **Create**.

Your read replica is provisioned and appears on the **Computes** tab under **Postgres database**. The following section describes how to connect to your read replica.

Alternatively, you can create read replicas using the [Neon CLI](https://neon.com/docs/cli/branches#create) or [Neon API](https://neon.com/docs/reference/api/endpoints/create-project-endpoint).

**CLI**

```bash
neon branches add-compute mybranch --type read_only
```

**API**

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/late-bar-27572981/endpoints \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "endpoint": {
    "type": "read_only",
    "branch_id": "br-young-fire-15282225"
  }
}
' | jq
```

### Connect to the read replica

1. Once the read replica is created, click **Connect** at the top of the sidebar.
2. In the **Connect to your branch** modal, select the replica compute.
3. Copy the connection string and use it to connect to the replica, either via `psql` or your application.

   Your connection string will look something like this:

   ```bash
   postgresql://user:password@ep-read-replica-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

### Running ad-hoc queries

Once connected to the read replica, you can run your ad-hoc queries without worrying about impacting your production database. For example, let's say you need to run a quick analysis to get sales data for specific products over the past year:

```sql
SELECT product_id, SUM(sale_amount) AS total_sales
FROM sales
WHERE sale_date >= (CURRENT_DATE - INTERVAL '1 year')
GROUP BY product_id;
```

This query will execute on the read replica, leaving your primary database free to handle regular traffic and operations.

## Ad-hoc query scenarios

Here are a few common scenarios where ad-hoc queries on a read replica can be useful:

- **Sales Analysis**: Calculate total sales for a product or category without affecting your production system.
- **Data Exploration**: Explore data patterns, such as checking anomalies or trends in your dataset.
- **Custom Reporting**: Generate one-time reports for business meetings or audits without waiting for a prebuilt report.
- **Checking queries for write attempts**: Since read replicas are designed for read-only operations, any unintended write actions will result in an error. For example, if someone tries to insert data into the sales table on the read replica, they will get an error message like this:

  ```bash
  ERROR: cannot execute INSERT in a read-only transaction (SQLSTATE 25006)
  ```

  This ensures that the replica is used solely for reading data, preserving the integrity of your production system.

--- [Document source](https://neon.com/docs/guides/read-replica-data-analysis.md) ---

> Summary: Neon read replicas provide a dedicated read-only compute that shares the same storage as your primary branch, letting you run costly SQL analytics and reporting queries without degrading production throughput. Use this guide when you need to offload aggregations, BI tool queries (such as Metabase), or batch reporting jobs from your primary database. Each replica can be created in seconds via the Console, CLI, or API, and scales to zero automatically after 5 minutes of inactivity.

# Run analytics queries with Read Replicas

Leverage read replicas for running data-intensive analytics queries

Last updated: 2026-09-25

With Neon's read replica feature, you can instantly create a dedicated read replica for running data-intensive analytics or reporting queries. This allows you to avoid disruption or performance degradation on your production database.

A read replica reads data from the same source as your primary read-write compute. There's no data replication, so creating a read replica is a near-instant process. For more information about Neon's read replica architecture, see [Read replicas](https://neon.com/docs/introduction/read-replicas).

## Scenario

Suppose you have a `sales` table in your production database. The table and data might look something like this:

```sql
CREATE TABLE sales (
    id SERIAL PRIMARY KEY,
    product_id INT NOT NULL,
    sale_amount DECIMAL(10,2) NOT NULL,
    sale_date DATE NOT NULL
);

INSERT INTO sales (product_id, sale_amount, sale_date) VALUES
(1, 20.50, '2022-07-24'),
(2, 35.99, '2022-08-24'),
(1, 20.50, '2022-09-24'),
(3, 15.00, '2023-01-24'),
(1, 20.50, '2023-04-24');
...
```

You want to find the total sale amount for each product in the past year, but due to the large number of products and sales in your database, you know this is a costly query that could impact performance on your production system.

This guide walks you through creating a read replica, connecting to it, running your query, and optionally deleting the read replica when finished.

**Tip: Metabase Analytics Use Case**

[Metabase](https://www.metabase.com/) is an open-source business intelligence (BI) company that provides a platform for visualizing and analyzing data. With Metabase and Neon, you can:

- Create a read replica in Neon
- Configure [Autoscaling](https://neon.com/docs/introduction/autoscaling) to define minimum and maximum limits for compute resources
- Configure [scale to zero](https://neon.com/docs/introduction/scale-to-zero) to define whether the read replica scales to zero when not being used
- Configure a connection to the read replica from Metabase.

With this setup, your read replica only wakes up when Metabase connects, scales to sync job requirements without affecting your production database, and scales back to zero after the job sync is finished.

## Create a read replica

Creating a read replica involves adding a read replica compute to a branch.

**Note:** On paid plans, you can add up to 6 read replicas per branch. The Free plan is limited to 3 read replica computes per project.

You can add a read replica compute to any branch in your Neon project by following these steps:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Click **Add Read Replica**.
4. On the **Add new compute** dialog, select **Read replica** as the **Compute type**.
5. Specify the **Compute size settings**. You can configure a fixed size compute with a specific amount of RAM (the default) or enable autoscaling by configuring a minimum and maximum compute size using the slider. You can also configure a **Scale to zero** setting, which determines whether a compute suspends due to inactivity after 5 minutes.

   **Note:** The compute size configuration determines the processing power of your database.
6. When you finish making your selections, click **Create**.

Your read replica is provisioned and appears on the **Computes** tab under **Postgres database**. The following section describes how to connect to your read replica.

Alternatively, you can create read replicas using the [Neon CLI](https://neon.com/docs/cli/branches#create) or [Neon API](https://neon.com/docs/reference/api/endpoints/create-project-endpoint), providing the flexibility required to integrate read replicas into your workflows or CI/CD processes.

**CLI**

```bash
neon branches add-compute mybranch --type read_only
```

**API**

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/late-bar-27572981/endpoints \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "endpoint": {
    "type": "read_only",
    "branch_id": "br-young-fire-15282225"
  }
}
' | jq
```

## Connect to the read replica

Connecting to a read replica is the same as connecting to any branch, except you connect via a read replica compute instead of your primary read-write compute. The following steps describe how to connect to your read replica with connection details obtained from the Neon Console.

1. Click the **Connect** button in the Console nav. On the **Connect to your branch** modal, select the branch, the database, and the role you want to connect with.

2. Under **Compute**, select the **Replica** compute.

3. Select a **Database** and the **Role** you want to connect with.

4. Copy the connection string. This is the information you need to connect to the read replica from your client or application.

   The connection string appears similar to the following:

   ```bash
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   If you expect a high number of connections, enable the **Connection pooling** toggle to add the `-pooler` flag to the connection string.

   The information in your connection string corresponds to the following connection details:

   - role: `alex`
   - password:`AbC123dEf`
   - hostname: `ep-cool-darkness-123456.us-east-2.aws.neon.tech`
   - database name: `dbname`. Your database name may differ.

   When you connect to a read replica, no write operations are permitted on the connection.

5. Connect to your application from a client such as `psql` or add the connection details to your application. For example, to connect using `psql`, issue the following command:

   ```bash
   psql postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

## Run the analytics query on the read replica

An analytics query on your `sales` table might look something like this:

```sql
SELECT product_id, SUM(sale_amount) as total_sales
FROM sales
WHERE sale_date >= (CURRENT_DATE - INTERVAL '1 year')
GROUP BY product_id;
```

If you have a lot of products and sales, this query might impact performance on your production system, but running the query on your read replica, which has its own dedicated compute resources, causes no disruption.

## Delete the read replica

When you are finished running analytics queries, you can delete the read replica if it's no longer required. Deleting a read replica is a permanent action, but you can quickly create a new read replica when you need one.

**Tip:** Alternatively, you can let the read replica scale to zero so that it's readily available the next time you need it. Neon's [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero) feature will suspend the compute until the next time you access it. Scale to zero occurs automatically after 5 minutes of inactivity.

To delete a read replica:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Find the read replica you want to delete.
4. Click **Edit** → **Delete compute**.

--- [Document source](https://neon.com/docs/guides/read-replica-guide.md) ---

> Summary: Neon read replica management guide covering how to add a read-only compute to any branch, connect to it, and adjust its size or Scale to Zero settings via the Console, CLI, or API. Use this page when you need step-by-step instructions for offloading read traffic (analytics, horizontal scaling, read-only access) to a separate compute endpoint on an existing Neon branch. Available on all Neon plans. Includes replication delay monitoring and automatic synchronization of max_connections and related Postgres parameters between primary and replica computes.

# Create and manage Read Replicas

Learn how to create and manage read replicas in Neon

Last updated: 2026-11-06

[Read replicas](https://neon.com/docs/introduction/read-replicas) are supported with all Neon plans. On paid plans, you can add up to 6 read replicas per branch. The Free plan is limited to 3 read replica computes per project. This guide steps you through the process of creating and managing read replicas.

The general purpose of read replicas is to segregate read-only work from your production database operations. This can be applied to different uses cases, such as:

- **Horizontal scaling**: Distributing read requests across replicas to improve performance and increase throughput
- **Analytics queries**: Offloading resource-intensive analytics and reporting workloads to reduce load on the primary compute
- **Read-only access**: Granting read-only access to users or applications that don't require write permissions

Regardless of the application, the steps for creating, configuring, and connecting to a read replica are the same. You can create one or more read replicas for any branch in your Neon project and configure the compute size allocated to each. Neon's _Autoscaling_ and _Scale to Zero_ features are also supported, providing you with control over read replica compute usage.

## Prerequisites

- A Neon account
- A [Neon project](https://neon.com/docs/manage/projects#create-a-project)

## Create a read replica

Creating a read replica involves adding a read replica compute to a branch. You can add a read replica compute to any branch in your Neon project using the Neon Console, [Neon CLI](https://neon.com/docs/cli/branches#create), or [Neon API](https://neon.com/docs/reference/api/endpoints/create-project-endpoint).

**Note:** On paid plans, you can add up to 6 read replicas per branch. The Free plan is limited to 3 read replica computes per project.

**Console**

To create a read replica from the Neon Console:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Click **Add Read Replica**.
4. On the **Add new compute** dialog, select **Read replica** as the **Compute type**.
5. Specify the **Compute size settings**. You can configure a **Fixed Size** compute with a specific amount of RAM (the default) or enable autoscaling by configuring a minimum and maximum compute size. You can also configure the **Suspend compute after inactivity** setting, which is the amount of idle time after which your compute is automatically suspended. The default setting is 5 minutes.

   **Note:** The compute size configuration determines the processing power of your database.
6. When you finish making your selections, click **Create**.

In a few seconds, your read replica is provisioned and appears on the **Computes** tab under **Postgres database**. The following section describes how to connect to your read replica.

**CLI**

To create a read replica using the Neon CLI, use the [branches](https://neon.com/docs/cli/branches) command, specifying the `add-compute` subcommand with `--type read_only`. If you have more than one Neon project, also include the `--project-id` option.

```bash
neon branches add-compute mybranch --type read_only
```

**API**

To create a read replica compute using the Neon API, use the [Create endpoint](https://neon.com/docs/reference/api/endpoints/create-project-endpoint) method. The `type` attribute in the following example specifies `read_only`, which creates a read replica compute. For information about obtaining the required `project_id` and `branch_id` parameters, refer to [Create an endpoint](https://neon.com/docs/reference/api/endpoints/create-project-endpoint), in the _Neon API Reference_.

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/<project_id>/endpoints \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "endpoint": {
    "type": "read_only",
    "branch_id": "<branch_id>"
  }
}
' | jq
```

## Connect to a read replica

Connecting to a read replica is the same as connecting to any branch, except you connect via a read replica compute instead of your primary read-write compute. The following steps describe how to connect to your read replica with connection details obtained from the Neon Console.

1. Click the **Connect** button in the Console nav. On the **Connect to your branch** modal, select the branch, the database, and the role you want to connect with.
2. Under **Compute**, select a **Replica**.
3. Select a connection string or a code example from the drop-down menu and copy it. This is the information you need to connect to the read replica from your client or application.

   A **psql** connection string appears similar to the following:

   ```bash
   postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require
   ```

   If you expect a high number of connections, enable the **Connection pooling** toggle to add the `-pooler` flag to the connection string or example.

   **Note:** Write operations are not permitted on a read replica connection.

## View read replicas

You can view read replicas using the Neon Console or [Neon API](https://neon.com/docs/reference/api/endpoints/create-project-endpoint).

**Console**

To view read replicas for a branch, in the Neon Console select your branch from the project/branch menu at the top of the sidebar, then select **Postgres database** > **Computes**. Read replicas are listed on the **Computes** tab.

![View read replicas](https://neon.com/docs/guides/view_read_replica.png)

**API**

To view read replica computes with the [Neon API](https://neon.com/docs/reference/api/endpoints/create-project-endpoint), use the [Get endpoints](https://neon.com/docs/reference/api/endpoints/list-project-endpoints) method.

```bash
curl -X 'GET' \
  'https://console.neon.tech/api/v2/projects/<project_id>/endpoints' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

For information about obtaining the required `project_id` parameter for this command, refer to [Get endpoints](https://neon.com/docs/reference/api/endpoints/list-project-endpoints), in the _Neon API Reference_. For information about obtaining a Neon API key, see [Create an API key](https://neon.com/docs/manage/api-keys#create-an-api-key).

In the response body for this method, read replica computes are identified by the `type` value, which is `read_only`.

## Edit a read replica

You can edit a read replica using the Neon Console or [Neon API](https://neon.com/docs/reference/api) to change the [Compute size](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration) or [Scale to Zero](https://neon.com/docs/manage/computes#scale-to-zero-configuration) configuration.

**Console**

To edit a read replica compute using the Neon Console:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Identify the read replica compute you want to modify, and click **Edit**.
4. Make the changes to your compute settings, and click **Save**.

**API**

To edit a read replica compute with the Neon API, use the [Update endpoint](https://neon.com/docs/reference/api/endpoints/update-project-endpoint) method.

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/<project_id>/endpoints/<endpoint_id> \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "endpoint": {
    "autoscaling_limit_min_cu": 25,
    "autoscaling_limit_max_cu": 3,
    "suspend_timeout_seconds": 604800,
    "provisioner": "k8s-neonvm"
  }
}
'
```

Computes are identified by their `project_id` and `endpoint_id`. For information about obtaining the required `project_id` and `endpoint_id` parameters, refer to [Update endpoint](https://neon.com/docs/reference/api/endpoints/update-project-endpoint), in the _Neon API Reference_. For information about obtaining a Neon API key, see [Create an API key](https://neon.com/docs/manage/api-keys#create-an-api-key).

## Delete a read replica

You can delete a read replica using the Neon Console or [Neon API](https://neon.com/docs/reference/api). Deleting a read replica is a permanent action, but you can quickly create a new read replica if you need one.

**Console**

To delete a read replica using the Neon Console:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Find the read replica you want to delete.
4. Click **Edit** → **Delete**.

**API**

To delete a read replica compute with the Neon API, use the [Delete endpoint](https://neon.com/docs/reference/api/endpoints/delete-project-endpoint) method.

```bash
curl --request DELETE \
     --url https://console.neon.tech/api/v2/projects/<project_id>/endpoints/<endpoint_id> \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY"
```

Computes are identified by their `project_id` and `endpoint_id`. For information about obtaining the required `project_id` and `endpoint_id` parameters, refer to [Delete endpoint](https://neon.com/docs/reference/api/endpoints/delete-project-endpoint), in the _Neon API Reference_. For information about obtaining a Neon API key, see [Create an API key](https://neon.com/docs/manage/api-keys#create-an-api-key).

## Monitoring read replicas

You can monitor replication delay between the primary compute and your read replica computes from the **Monitoring** page in the Neon Console. Two graphs are provided:

**Replication delay bytes**

![Replication delay bytes](https://neon.com/docs/introduction/rep_delay_bytes.png)

The **Replication delay bytes** graph shows the total size, in bytes, of the data that has been sent from the primary compute but has not yet been applied on the replica. A larger value indicates a higher backlog of data waiting to be replicated, which may suggest issues with replication throughput or resource availability on the replica. This graph is only visible when selecting a **Replica** compute from the **Compute** drop-down menu.

**Replication delay seconds**

![Replication delay seconds](https://neon.com/docs/introduction/rep_delay_seconds.png)

The **Replication delay seconds** graph shows the time delay, in seconds, between the last transaction committed on the primary compute and the application of that transaction on the replica. A higher value suggests that the replica is behind the primary, potentially due to network latency, high replication load, or resource constraints on the replica. This graph is only visible when selecting a **Replica** compute from the **Compute** drop-down menu.

## Read replica compute setting synchronization

For Neon [read replicas](https://neon.com/docs/introduction/read-replicas), certain Postgres settings should not have lower values than your primary read-write compute. For this reason, the following settings on read replica computes are synchronized with the settings on the primary read-write compute when the read replica compute is started:

- `max_connections`
- `max_prepared_transactions`
- `max_locks_per_transaction`
- `max_wal_senders`
- `max_worker_processes`

No users action is required. The settings are synchronized automatically when you create a read replica. However, if you change the compute size configuration on the primary read-write compute, you will need to restart your read replica computes to ensure that settings remain synchronized, as described in the next section.

### Replication delay issues

If your read replicas are falling behind, follow these steps to diagnose and resolve the issue:

1. **Check your replication lag metrics**  
   Refer to [Monitoring Read Replicas](https://neon.com/docs/guides/read-replica-guide#monitoring-read-replicas) for instructions on how to monitor replication lag.

2. **Verify configuration alignment**  
   If replication lag is detected, ensure that the configurations for the primary and read-replica computes are aligned. Specifically, confirm that the following parameters match between your primary compute and read-replica compute:
   - `max_connections`
   - `max_prepared_transactions`
   - `max_locks_per_transaction`
   - `max_wal_senders`
   - `max_worker_processes`

3. **Restart read-replica computes if configurations are misaligned**  
   If the configurations are not aligned, restart your read-replica computes to automatically update their settings. For instructions, see [Restart a Compute](https://neon.com/docs/manage/endpoints#restart-a-compute).

   **Tip:** When increasing the size of your primary read-write compute, always restart associated read replicas to ensure their configurations remain aligned.

## Resources

- [Scale your Next.js application with Drizzle ORM and Lakebase Postgres read replicas](https://neon.com/guides/read-replica-drizzle)

--- [Document source](https://neon.com/docs/guides/read-replica-integrations.md) ---

> Summary: Lakebase Postgres read replicas are independent read-only computes that share primary storage at no extra cost, letting you route SELECT queries to replicas and writes to the primary to increase read throughput. The page shows how to wire up that routing using each framework's built-in support: Prisma's `@prisma/extension-read-replicas`, Drizzle ORM's `withReplicas()`, Laravel's `read`/`write` database config, Django's `DATABASE_ROUTERS`, and Entity Framework Core's separate `DbContext` classes.

# Scale your application with Read Replicas

Scale your app with read replicas using built-in framework support

Last updated: 2026-08-04

In Neon, a read replica is an independent read-only compute that performs read operations on the same data as your primary read-write compute, which means adding a read replica to a Neon project requires no additional storage.

**Note:** On paid plans, you can add up to 6 read replicas per branch. The Free plan is limited to 3 read replica computes per project.

A key benefit of read replicas is that you can distribute read requests to one or more read replicas, enabling you to easily scale your applications and achieve higher throughput for both read-write and read-only workloads.

Many application frameworks offer built-in support for managing read replicas or multiple databases, making it easy to integrate Neon read replicas into an existing application. Below, we provide examples for popular frameworks and tools, but there are many others. Refer to your provider's documentation for specific details about integrating read replicas or multiple databases.

## Prisma

In Prisma, the read replicas extension, `@prisma/extension-read-replicas`, adds support for read replicas to Prisma Client.

You start by installing the extension:

```bash
npm install @prisma/extension-read-replicas
```

You can then initialize the extension by extending your Prisma Client instance and providing a connection string that points to your read replica in the `url` option of the extension:

```javascript
import { PrismaClient } from '@prisma/client';
import { readReplicas } from '@prisma/extension-read-replicas';

const prisma = new PrismaClient().$extends(
  readReplicas({
    url: process.env.DATABASE_URL_REPLICA,
  })
);

// Query is run against the database replica
await prisma.post.findMany();

// Query is run against the primary database
await prisma.post.create({
  data: {
    /** */
  },
});
```

All read operations, such as `findMany`, are executed against the read replica in the setup shown above. All write operations, such as create, update, and `$transaction` queries, are run against your primary compute.

For more, including configuring multiple read replicas, refer to [Read Replicas](https://www.prisma.io/docs/orm/prisma-client/setup-and-configuration/read-replicas) in the Prisma documentation.

**Example**: For a full example, see [Use Read Replicas with Prisma](https://neon.com/docs/guides/read-replica-prisma).

## Drizzle ORM

With Drizzle ORM, you can use the `withReplicas()` function to direct `SELECT` queries to read replicas, and create, delete, and update operations to your primary compute, as shown in the following example:

```javascript
import { sql } from 'drizzle-orm';
import { drizzle } from 'drizzle-orm/node-postgres';
import { boolean, jsonb, pgTable, serial, text, timestamp, withReplicas } from 'drizzle-orm/pg-core';
const usersTable = pgTable('users', {
  id: serial('id' as string).primaryKey(),
  name: text('name').notNull(),
  verified: boolean('verified').notNull().default(false),
  jsonb: jsonb('jsonb').$type<string[]>(),
  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
});
const primaryDb = drizzle("postgres://user:password@host:port/primary_db");
const read1 = drizzle("postgres://user:password@host:port/read_replica_1");
const read2 = drizzle("postgres://user:password@host:port/read_replica_2");
const db = withReplicas(primaryDb, [read1, read2]);
```

You can then use the `db` instance the same way you do already, and Drizzle will direct requests to read replicas and your primary compute automatically.

```sql
// Read from either the read1 connection or the read2 connection
await db.select().from(usersTable)

// Use the primary compute for the delete operation
await db.delete(usersTable).where(eq(usersTable.id, 1))
```

For more, refer to [Read Replicas](https://orm.drizzle.team/docs/read-replicas) in the Drizzle documentation.

**Example application**: For a full example, refer to this Neon community guide: [Scale your Next.js application with Drizzle ORM and Neon Postgres Read Replicas](https://neon.com/guides/read-replica-drizzle).

## Laravel

To scale your Laravel application with Neon read replicas, you can configure Laravel's database settings and use Eloquent ORM to route read operations to replicas and write operations to your primary compute.

For example, in your `config/database.php`, you can configure read and write connection settings and then route traffic accordingly.

```php
'pgsql' => [
    'driver' => 'pgsql',
    'read' => [
        'host' => env('DB_READ_HOST'),
    ],
    'write' => [
        'host' => env('DB_WRITE_HOST'),
    ],
    'sticky'    => true,
    'port' => env('DB_PORT', '5432'),
    'database' => env('DB_DATABASE', 'laravel'),
    'username' => env('DB_USERNAME', 'root'),
    'password' => env('DB_PASSWORD', ''),
    'charset' => env('DB_CHARSET', 'utf8'),
    'prefix' => '',
    'prefix_indexes' => true,
    'search_path' => 'public',
    'sslmode' => 'prefer',
],
```

**Example application**: For a full setup, refer to this Neon community guide: [Scale your Laravel application with Neon Postgres Read Replicas](https://neon.com/guides/read-replica-laravel).

## Django

In Django, you can use the `DATABASES` setting to tell Django about the primary and read replica databases you'll be using:

```python
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'your_database_name',
        'USER': 'your_username',
        'PASSWORD': 'your_password',
        'HOST': 'your_primary_host',
        'PORT': '5432',
    },
    'replica': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'your_database_name',
        'USER': 'your_username',
        'PASSWORD': 'your_password',
        'HOST': 'your_read_replica_host',
        'PORT': '5432',
    }
}
DATABASE_ROUTERS = ['notes.db_router.PrimaryReplicaRouter']
```

You can then use the `PrimaryReplicaRouter` class to define routing logic for read and write database operations.

```python
class PrimaryReplicaRouter:
    def db_for_read(self, model, **hints):
        return 'replica'
    def db_for_write(self, model, **hints):
        return 'default'
    def allow_relation(self, obj1, obj2, **hints):
        return True
    def allow_migrate(self, db, app_label, model_name=None, **hints):
        return True
```

For more, see [Multiple databases](https://docs.djangoproject.com/en/5.1/topics/db/multi-db/) in the Django documentation.

**Example application**: For a complete setup, refer to this Neon community guide: [Scale your Django application with Neon Postgres Read Replicas](https://neon.com/guides/read-replica-django).

## Entity Framework Core

To scale your .NET application with Neon read replicas, you can configure separate read and write contexts using Entity Framework Core's `DbContext` class.

```csharp
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Data
{
    public class TodoDbContext : DbContext
    {
        public TodoDbContext(DbContextOptions<TodoDbContext> options) : base(options) { }
        public DbSet<Todo> Todos => Set<Todo>();
    }

    public class TodoDbReadContext : DbContext
    {
        public TodoDbReadContext(DbContextOptions<TodoDbReadContext> options) : base(options) { }
        public DbSet<Todo> Todos => Set<Todo>();
    }
}
```

**Example application**: For a complete setup, refer to this Neon community guide: [Scale your .NET application with Entity Framework and Neon Postgres Read Replicas](https://neon.com/guides/read-replica-entity-framework).

--- [Document source](https://neon.com/docs/guides/read-replica-prisma.md) ---

> Summary: Neon read replicas for Prisma route read queries to independent read-only computes using the @prisma/extension-read-replicas package, distributing load without extra storage costs. Use this page when you want to offload SELECT queries from your primary compute in a Prisma app, keeping writes and $transaction calls on the primary. Newer Prisma versions require each replica to be a separate PrismaClient instance with a PrismaNeon adapter. Multiple replicas are selected randomly per query.

# Use Neon read replicas with Prisma

Learn how to scale Prisma applications with Neon read replicas

Last updated: 2026-10-05

A Neon read replica is an independent read-only compute that performs read operations on the same data as your primary read-write compute, which means adding a read replica to a Neon project requires no additional storage.

A key benefit of read replicas is that you can distribute read requests to one or more read replicas, enabling you to easily scale your applications and achieve higher throughput for both read-write and read-only workloads.

For more information about Neon's read replica feature, see [Read replicas](https://neon.com/docs/introduction/read-replicas).

This guide shows how to use Neon read replicas to scale Prisma applications using Prisma Client's read replica extension: [@prisma/extension-read-replicas](https://github.com/prisma/extension-read-replicas).

## Prerequisites

- An application that uses Prisma with a Neon database. If you haven't set up Prisma yet, see [Connect from Prisma to Neon](https://neon.com/docs/guides/prisma).

## Create a read replica

You can create read replicas for any branch in your Neon project.

**Note:** On paid plans, you can add up to 6 read replicas per branch. The Free plan is limited to 3 read replica computes per project.

You can add a read replica by following these steps:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Click **Add Read Replica**.
4. On the **Add new compute** dialog, select **Read replica** as the **Compute type**.
5. Specify the **Compute size settings** options. You can configure a **Fixed Size** compute with a specific amount of RAM (the default) or enable autoscaling by configuring a minimum and maximum compute size. You can also configure the **Scale to zero** setting, which controls whether your read replica compute is automatically suspended due to inactivity after 5 minutes.

   **Note:** The compute size configuration determines the processing power of your database. More memory means more processing power but also higher compute costs. For information about compute costs, see [Billing metrics](https://neon.com/docs/introduction/billing).
6. When you finish making selections, click **Create**.

   Your read replica compute is provisioned and appears on the **Computes** tab under **Postgres database**.

Alternatively, you can create read replicas using the [Neon API](https://neon.com/docs/reference/api/endpoints/create-project-endpoint) or [Neon CLI](https://neon.com/docs/cli/branches#create).

**API**

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/late-bar-27572981/endpoints \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "endpoint": {
    "type": "read_only",
    "branch_id": "br-young-fire-15282225"
  }
}
' | jq
```

**CLI**

```bash
neon branches add-compute mybranch --type read_only
```

## Retrieve the connection string for your read replica

Connecting to a read replica is the same as connecting to any branch in a Neon project, except you connect via a read replica compute instead of your primary read-write compute. The following steps describe how to retrieve the connection string (the URL) for a read replica from the Neon Console.

1. Click the **Connect** button in the Console nav. On the **Connect to your branch** modal, select the branch, the database, and the role you want to connect with.
2. Under **Compute**, select a **Replica** compute.
3. Select the connection string and copy it. This is the information you need to connect to the read replica from your Prisma Client. The connection string appears similar to the following:

   ```bash
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   If you expect a high number of connections, enable the **Connection pooling** toggle to add the `-pooler` flag to the connection string.

## Update your env file

In your `.env` file, set a `DATABASE_REPLICA_URL` environment variable to the connection string of your read replica. Your `.env` file should look something like this, with your regular `DATABASE_URL` and the newly added `DATABASE_REPLICA_URL`.

```text
DATABASE_URL="postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require"
DATABASE_REPLICA_URL="postgresql://alex:AbC123dEf@ep-damp-cell-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require"
```

Notice that the `endpoint_id` (`ep-damp-cell-123456`) for the read replica compute differs. The read replica is a different compute and therefore has a different `endpoint_id`.

## Configure Prisma Client to use a read replica

[@prisma/extension-read-replicas](https://github.com/prisma/extension-read-replicas) adds support to Prisma Client for read replicas. The following steps show you how to install the extension and configure it to use a Neon read replica.

1. Install the extension in your Prisma project:

   ```bash
   npm install @prisma/extension-read-replicas
   ```

2. Extend your Prisma Client instance by importing the extension and creating separate adapters for your primary and replica connections:

   ```javascript
   import 'dotenv/config';
   import { PrismaClient } from './generated/prisma'; // path set by `output` in your schema.prisma generator
   import { PrismaNeon } from '@prisma/adapter-neon';
   import { readReplicas } from '@prisma/extension-read-replicas';

   // Create adapter for primary connection
   const mainAdapter = new PrismaNeon({
     connectionString: process.env.DATABASE_URL
   });

   // Create adapter for replica connection
   const replicaAdapter = new PrismaNeon({
     connectionString: process.env.DATABASE_REPLICA_URL
   });

   // Create replica client
   const replicaClient = new PrismaClient({ adapter: replicaAdapter });

   // Create primary client and extend with read replicas
   const prisma = new PrismaClient({ adapter: mainAdapter }).$extends(
     readReplicas({
       replicas: [replicaClient],
     })
   );
   ```

   **Note:** In Prisma 7, the read replicas extension requires you to pass an array of PrismaClient instances configured with adapters, not connection URLs. Each replica needs its own adapter and client instance.

   **Note:**

   You can pass multiple replica clients if you want to use multiple read replicas. Neon supports adding multiple read replicas to a database branch. A replica is selected randomly for each read query.

   ```javascript
   // Create adapters for multiple replicas
   const replicaAdapter1 = new PrismaNeon({
     connectionString: process.env.DATABASE_REPLICA_URL_1
   });
   const replicaAdapter2 = new PrismaNeon({
     connectionString: process.env.DATABASE_REPLICA_URL_2
   });

   // Create replica clients
   const replicaClient1 = new PrismaClient({ adapter: replicaAdapter1 });
   const replicaClient2 = new PrismaClient({ adapter: replicaAdapter2 });

   // Extend primary client with multiple replicas
   const prisma = new PrismaClient({ adapter: mainAdapter }).$extends(
     readReplicas({
       replicas: [replicaClient1, replicaClient2],
     })
   );
   ```

   When your application runs, read operations are sent to the read replica. If you specify multiple read replicas, a read replica is selected randomly.

   All write and `$transaction` queries are sent to the primary compute defined by `DATABASE_URL`, which is your read/write compute.

   **Warning:** Read replicas are read-only. Sending a write (`INSERT`, `UPDATE`, `DELETE`, or DDL) to a read replica fails with `ERROR: cannot execute INSERT in a read-only transaction (SQLSTATE 25006)`. Make sure `DATABASE_REPLICA_URL` points at a read replica compute and `DATABASE_URL` points at your read/write compute so writes are routed to the primary. See [cannot execute ... in a read-only transaction](https://neon.com/docs/connect/connection-errors#error-read-only-transaction).

   If you want to read from the primary compute and bypass read replicas, you can use the `$primary()` method in your extended Prisma Client instance:

   ```bash
   const posts = await prisma.$primary().post.findMany()
   ```

   This Prisma Client query will be routed to your primary database.

## Examples

This example demonstrates how to use the [@prisma/extension-read-replicas](https://github.com/prisma/extension-read-replicas) extension in Prisma Client. It uses a simple TypeScript script to read and write data in a Postgres database.

- [Prisma read replicas demo](https://github.com/prisma/read-replicas-demo): A TypeScript example showing how to use the @prisma/extension-read-replicas extension in Prisma Client

--- [Document source](https://neon.com/docs/guides/redwoodsdk.md) ---

> Summary: RedwoodSDK is a full-stack framework for Cloudflare Workers. This guide walks through creating a project on Neon, installing the Neon serverless driver (@neondatabase/serverless), storing the DATABASE_URL connection string in .env, and querying the database from a route in TypeScript. Use this page when building a RedwoodSDK app on Cloudflare that needs a serverless Postgres backend.

# Connect a RedwoodSDK application to Neon

Set up a project on Neon in seconds and connect from a Redwood application

Last updated: 2026-09-16

Pre-built prompt for connecting RedwoodSDK applications to Lakebase Postgres [View prompt](https://neon.com/prompts/redwood-sdk-prompt.md)

[RedwoodSDK](https://rwsdk.com/) is a framework for building full-stack applications on Cloudflare. This guide describes how to create a Neon project and access it from a RedwoodSDK application.

To create a project on Neon and access it from a RedwoodSDK application:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a RedwoodSDK project and add dependencies

1. Create a RedwoodSDK project if you do not have one. Run the following command and follow the prompts:

   ```shell
   npx create-rwsdk@latest my-redwood-app
   ```

   For more information, see the [RedwoodSDK Quickstart](https://docs.rwsdk.com/getting-started/quick-start/).

2. Navigate into your new project directory and install the RedwoodSDK dependencies:

   ```shell
   cd my-redwood-app
   npm install
   ```

3. Install the Neon serverless driver. It connects over HTTP or WebSockets, so it works in Cloudflare Workers:

   ```shell
   npm install @neondatabase/serverless
   ```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection string to it. You can find your Neon database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

RedwoodSDK reads this file during local development. Don't commit `.env` to version control.

## Configure the Postgres client

In your RedwoodSDK application, open `src/app/pages/home.tsx`. This is the starter home page. Replace its contents with the following code. It imports the driver, reads `DATABASE_URL` from the Workers `env` object, and queries the database inside the route handler:

```typescript filename="src/app/pages/home.tsx"
import { RequestInfo } from "rwsdk/worker";
import { neon } from '@neondatabase/serverless';
import { env } from "cloudflare:workers";

async function getData() {
  const sql = neon(env.DATABASE_URL);
  const response = await sql`SELECT version()`;
  return response[0].version;
}

export async function Home({ ctx }: RequestInfo) {
  const data = await getData();
  return <>{data}</>;
}
```

## Run your RedwoodSDK application

Generate the required Wrangler types for RedwoodSDK to detect environment variables:

```bash
npx wrangler types
```

Start the development server:

```bash
npm run dev
```

Navigate to [localhost:5173](http://localhost:5173) in your browser. You should see a response similar to the following, indicating a successful connection to your Neon database:

```text
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

> The specific version may vary depending on the PostgreSQL version of your Neon project.

## Resources

- [RedwoodSDK Documentation](https://docs.rwsdk.com/)
- [Connect to a PostgreSQL database with Cloudflare Workers](https://developers.cloudflare.com/workers/tutorials/postgres/)

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/reflex.md) ---

> Summary: Connecting a Reflex Python web app to Lakebase Postgres requires setting a DATABASE_URL in rxconfig.py via python-dotenv, defining sqlmodel ORM models, and running Alembic migrations. Use this page when building a Python full-stack application with Reflex that needs a serverless Postgres backend, covering virtual environment setup, psycopg installation, schema migrations, and a working CRUD example.

# Build a Python App with Reflex and Lakebase Postgres

Learn how to build a Python Full Stack application with Reflex and Lakebase Postgres

Last updated: 2026-09-16

Pre-built prompt for connecting Reflex applications to Lakebase Postgres [View prompt](https://neon.com/prompts/reflex-prompt.md)

[Reflex](https://reflex.dev/) is a Python web framework that allows you to build full-stack applications with Python.

Using Reflex, you can build frontend and backend applications using Python to manage the interaction between the frontend UI and the state with the server-side logic. To make the application data-driven, you can connect to a Lakebase Postgres database.

To connect to a Lakebase Postgres database from a Reflex application:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

To create a Neon project:

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Set up a Reflex project

To set up a Reflex project, you need to install the Reflex CLI and create a new project.

### Create the project directory

Create a new directory for your Reflex project and navigate to it:

```bash
mkdir with_reflex
cd with_reflex
```

### Create a virtual environment

It's recommended to use a virtual environment to manage your project dependencies. In this example, `venv` is used to create a virtual environment. You can use any other virtual environment manager of your choice like `poetry`, `pipenv`, or `uv`.

To create a virtual environment, run the following command in your project directory:

**MacOS/Linux**

```bash
python3 -m venv .venv
source .venv/bin/activate
```

**Windows**

```shell
py -3 -m venv .venv
.venv\Scripts\activate
```

### Install the required packages

Install Reflex, `python-dotenv` to manage environment variables, the `db` extra for the database tools that `reflex db` commands use, and `psycopg` to connect to Postgres:

```bash
pip install "reflex[db]" python-dotenv "psycopg[binary]"
```

To initialize the Reflex app, run the following command:

```bash
reflex init
```

When prompted, choose **A blank Reflex app** (option 0). Don't choose the AI builder (option 1), which opens a browser window instead. You should see output similar to the following:

```bash
$ reflex init
Info: Initializing the web directory.

Get started with a template:
(0) A blank Reflex app.
(1) Try our AI builder.
Which template would you like to use? (0): 0
Info: Initializing the app directory.
Success: Initialized with_reflex using the blank template.
```

When the project is initialized, Reflex CLI creates a project directory. This directory will contain the following files and directories:

```
with_reflex
├── .web
├── assets
├── with_reflex
│   ├── __init__.py
│   └── with_reflex.py
└── rxconfig.py
```

The `rxconfig.py` file contains the project configuration settings. This is where the database connection settings will be defined.

## Configure Reflex connection settings

Now that you have set up a Reflex project, you can configure the connection settings to connect to Neon.

### Create a .env file

Create a `.env` file in the root of your project directory to store your Neon connection string. Add the following line to the `.env` file, replacing the placeholder values with your actual Neon connection details:

```dotenv title=".env"
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

You can find the connection string for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

### Update the rxconfig.py file

1. Open the `rxconfig.py` file in the project directory.

2. Update the file to load the environment variables from the `.env` file and set the `db_url` parameter with the `DATABASE_URL` environment variable:

   ```python {1-2,5,14}
   import os
   from dotenv import load_dotenv
   import reflex as rx

   load_dotenv()

   config = rx.Config(
     app_name="with_reflex",
     plugins=[
        rx.plugins.SitemapPlugin(),
        rx.plugins.TailwindV4Plugin(),
        rx.plugins.RadixThemesPlugin(),
     ],
     db_url=os.environ.get("DATABASE_URL")
   )
   ```

3. Save the changes to the `rxconfig.py` file.

   Now, you can run the Reflex app and start building your Python full-stack application with Reflex and Neon.

### Generate the Alembic migration files

Reflex uses [Alembic](https://alembic.sqlalchemy.org/en/latest/) to manage database migrations. Run this command before you add the data model. If you run it after the model exists, it writes the first migration for that model instead, and `makemigrations` has nothing new to add. To generate the Alembic migration files, run the following command in your project directory:

```bash
reflex db init
```

## Creating a data model

To create a data model in Reflex, you can define a Python class that represents the data structure. Define models with [SQLModel](https://sqlmodel.tiangolo.com/), which is built on [SQLAlchemy](https://neon.com/docs/guides/sqlalchemy).

Add the following code to `with_reflex/with_reflex.py` to create a `Customer` model:

```python {8-14}
"""Welcome to Reflex! This file outlines the steps to create a basic app."""

import reflex as rx

from rxconfig import config
from sqlmodel import Field, SQLModel

class Customer(SQLModel, table=True):
    """The customer model."""
    id: int | None = Field(default=None, primary_key=True)
    name: str
    email: str
    phone: str
    address: str

class State(rx.State):
    """The app state."""


def index() -> rx.Component:
    # Welcome Page (Index)
    return rx.container(
        rx.color_mode.button(position="top-right"),
        rx.vstack(
            rx.heading("Welcome to Reflex!", size="9"),
            rx.text(
                "Get started by editing ",
                rx.code(f"{config.app_name}/{config.app_name}.py"),
                size="5",
            ),
            rx.link(
                rx.button("Check out our docs!"),
                href="https://reflex.dev/docs/getting-started/introduction/",
                is_external=True,
            ),
            spacing="5",
            justify="center",
            min_height="85vh",
        ),
    )


app = rx.App()
app.add_page(index)
```

This code defines a `Customer` model with an `id` primary key and fields for `name`, `email`, `phone`, and `address`. The `table=True` argument tells Reflex to create a table in the database for this class. The guide uses SQLModel directly because `rx.Model` is deprecated and will be removed in Reflex 1.0.

### Create and apply the migration

Run the following command to create a new migration file that reflects the changes made to the data model:

```bash
reflex db makemigrations --message 'create customer model'
```

After creating the migration file, apply the migration to the database by running:

```bash
reflex db migrate
```

This command applies the migration to the database, updating the schema to match the model definition.

You can verify that the `customer` table has been created in your Neon database by visiting the **Tables** section in the Neon Console.

## Create the Reflex app

Update the `with_reflex/with_reflex.py` file to create a simple Customer Data App that allows you to add and view customer records.

```python
"""Welcome to Reflex! This file outlines the steps to create a basic app."""

import reflex as rx
from rxconfig import config
from sqlmodel import Field, SQLModel, select


class Customer(SQLModel, table=True):
    """The customer model."""

    id: int | None = Field(default=None, primary_key=True)
    name: str
    email: str
    phone: str
    address: str


class State(rx.State):
    """The app state."""

    # Form fields
    name: str = ""
    email: str = ""
    phone: str = ""
    address: str = ""

    # Setters for the form fields
    def set_name(self, value: str):
        self.name = value

    def set_email(self, value: str):
        self.email = value

    def set_phone(self, value: str):
        self.phone = value

    def set_address(self, value: str):
        self.address = value

    # List of customers
    customers: list[Customer] = []

    def load_customers(self):
        """Load all customers from the database."""
        with rx.session() as session:
            self.customers = session.exec(select(Customer)).all()

    def add_customer(self):
        """Add a new customer to the database."""
        if self.name and self.email:
            with rx.session() as session:
                customer = Customer(
                    name=self.name,
                    email=self.email,
                    phone=self.phone,
                    address=self.address,
                )
                session.add(customer)
                session.commit()

            # Clear form fields
            self.name = ""
            self.email = ""
            self.phone = ""
            self.address = ""

            # Reload customers
            self.load_customers()

    def delete_customer(self, customer_id: int):
        """Delete a customer from the database."""
        with rx.session() as session:
            customer = session.get(Customer, customer_id)
            if customer:
                session.delete(customer)
                session.commit()

        # Reload customers
        self.load_customers()


def index() -> rx.Component:
    return rx.box(
        rx.color_mode.button(position="top-right"),
        rx.vstack(
            # Header
            rx.heading(
                "Customer Management",
                size="8",
                weight="bold",
                margin_bottom="2rem",
            ),
            # Add Customer Section
            rx.card(
                rx.vstack(
                    rx.heading("➕ Add New Customer", size="5", weight="medium"),
                    rx.grid(
                        rx.input(
                            placeholder="Name *",
                            value=State.name,
                            on_change=State.set_name,
                            size="3",
                        ),
                        rx.input(
                            placeholder="Email *",
                            value=State.email,
                            on_change=State.set_email,
                            size="3",
                        ),
                        rx.input(
                            placeholder="Phone",
                            value=State.phone,
                            on_change=State.set_phone,
                            size="3",
                        ),
                        rx.input(
                            placeholder="Address",
                            value=State.address,
                            on_change=State.set_address,
                            size="3",
                        ),
                        columns="4",
                        spacing="4",
                        width="100%",
                    ),
                    rx.button(
                        "Add Customer",
                        on_click=State.add_customer,
                        size="3",
                        variant="solid",
                        color_scheme="blue",
                        width="auto",
                    ),
                    spacing="4",
                    width="100%",
                ),
                size="3",
                width="100%",
            ),
            # Spreadsheet Table
            rx.card(
                rx.vstack(
                    rx.heading(
                        f"📊 Customer List ({State.customers.length()} total)",
                        size="5",
                        weight="medium",
                    ),
                    rx.box(
                        rx.table.root(
                            rx.table.header(
                                rx.table.row(
                                    rx.table.column_header_cell("ID", width="80px"),
                                    rx.table.column_header_cell("Name"),
                                    rx.table.column_header_cell("Email"),
                                    rx.table.column_header_cell("Phone"),
                                    rx.table.column_header_cell("Address"),
                                    rx.table.column_header_cell(
                                        "Actions", width="120px"
                                    ),
                                ),
                            ),
                            rx.table.body(
                                rx.foreach(
                                    State.customers,
                                    lambda customer, index: rx.table.row(
                                        rx.table.cell(
                                            rx.badge(
                                                customer.id,
                                                color_scheme="gray",
                                                variant="soft",
                                            ),
                                        ),
                                        rx.table.cell(
                                            rx.text(customer.name, weight="medium"),
                                        ),
                                        rx.table.cell(
                                            rx.text(customer.email),
                                        ),
                                        rx.table.cell(
                                            rx.text(customer.phone),
                                        ),
                                        rx.table.cell(
                                            rx.text(customer.address),
                                        ),
                                        rx.table.cell(
                                            rx.button(
                                                rx.icon("trash-2", size=16),
                                                on_click=lambda: State.delete_customer(
                                                    customer.id
                                                ),
                                                size="2",
                                                variant="soft",
                                                color_scheme="red",
                                            ),
                                        ),
                                        align="center",
                                    ),
                                ),
                            ),
                            variant="surface",
                            size="3",
                            width="100%",
                        ),
                        width="100%",
                        overflow_x="auto",
                    ),
                    spacing="4",
                    width="100%",
                ),
                size="3",
                width="100%",
            ),
            spacing="6",
            width="100%",
            max_width="1400px",
            padding="2rem",
        ),
        width="100%",
        display="flex",
        justify_content="center",
        min_height="100vh",
        background="var(--gray-1)",
        on_mount=State.load_customers,
    )


app = rx.App()
app.add_page(index)
```

The following features are included in this Customer Data App:

- Add new customers with name, email, phone, and address.
- View a list of all customers in a table format.
- Delete customers from the list.

## Run the Reflex app

To run the Reflex app, use the following command in your project directory:

```bash
reflex run
```

This command starts the Reflex development server. You can access the app by navigating to `http://localhost:3000` in your web browser.

You should see the Customer Data App interface, where you can add, view, and delete customer records stored in your database.

![Reflex Customer Data App](https://neon.com/docs/guides/reflex_customer_data_app.png)

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/remix.md) ---

> Summary: Connecting an existing Remix v2 application to Lakebase Postgres requires a server-side `db.server` file that holds the database connection, preventing credentials from leaking into the client bundle. This guide walks through creating a project on Neon, storing the DATABASE_URL in `.env`, and wiring up a loader route using node-postgres, postgres.js, or the Neon serverless driver.

# Connect a Remix application to Neon

Set up a project on Neon in seconds and connect from a Remix application

Last updated: 2026-10-08

**Note:** Remix v2 is now part of React Router and is in maintenance mode. This guide covers existing Remix v2 applications. If you are starting a new project, use React Router instead. Follow our [React Router guide](https://neon.com/docs/guides/react-router) to connect to Neon.

For more information, see the [Remix announcement](https://remix.run/blog/merging-remix-and-react-router).

Remix is an open-source full stack JavaScript framework that lets you focus on building out the user interface using familiar web standards. This guide explains how to connect Remix with Lakebase Postgres using a secure server-side request.

To create a project on Neon and access it from a Remix application:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Add dependencies to your Remix project

1. Open your existing Remix v2 project in a terminal. The `~/` import path in this guide maps to the `app` directory in the default Remix template.

2. Add project dependencies using one of the following commands:

   **node-postgres**

   ```shell
   npm install pg
   npm install -D @types/pg
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless
   ```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection string to it. You can find the connection string for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

**Note:** `pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. If you use node-postgres, change `sslmode=require` to `sslmode=verify-full` in `DATABASE_URL` to keep the same behavior and remove the warning.

## Configure the Postgres client

There are two parts to connecting a Remix application to Neon. The first is `db.server`. Remix ensures any code added to this file isn't included in the client bundle. The second is the route where the connection to the database is used.

### db.server

Create a `db.server.ts` file at the root of your `app` directory and add the following code snippet to connect to your Neon database:

**node-postgres**

```typescript filename="app/db.server.ts"
import pg from 'pg';

const pool = new pg.Pool({
  connectionString: process.env.DATABASE_URL,
});

export { pool };
```

**postgres.js**

```typescript filename="app/db.server.ts"
import postgres from 'postgres';

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

export { sql };
```

**Neon serverless driver**

```typescript filename="app/db.server.ts"
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL!);

export { sql };
```

### Create a route

Create a file named `app/routes/version.tsx`. Remix maps this file to the `/version` path. The `loader` function runs on the server, so the database call stays out of the browser bundle.

**node-postgres**

```typescript filename="app/routes/version.tsx"
import { useLoaderData } from '@remix-run/react';
import { pool } from '~/db.server';

export const loader = async () => {
  const client = await pool.connect();
  try {
    const response = await client.query('SELECT version()');
    return response.rows[0].version;
  } finally {
    client.release();
  }
};

export default function Page() {
  const data = useLoaderData<typeof loader>();
  return <>{data}</>;
}
```

**postgres.js**

```typescript filename="app/routes/version.tsx"
import { useLoaderData } from '@remix-run/react';
import { sql } from '~/db.server';

export const loader = async () => {
  const response = await sql`SELECT version()`;
  return response[0].version;
};

export default function Page() {
  const data = useLoaderData<typeof loader>();
  return <>{data}</>;
}
```

**Neon serverless driver**

```typescript filename="app/routes/version.tsx"
import { useLoaderData } from '@remix-run/react';
import { sql } from '~/db.server';

export const loader = async () => {
  const response = await sql`SELECT version()`;
  return response[0].version;
};

export default function Page() {
  const data = useLoaderData<typeof loader>();
  return <>{data}</>;
}
```

## Run the app

Start the development server:

```shell
npm run dev
```

Open [localhost:5173/version](http://localhost:5173/version) in your browser. Vite serves the app on port 5173 in development. You should see output similar to the following:

```text
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

**Note:** `npm run dev` loads the `.env` file automatically. The production server does not. To run a production build, set `DATABASE_URL` in your environment, then run `npm run build` and `npm start`. The server listens on [localhost:3000](http://localhost:3000). Without the variable, the app fails to connect.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/sdks/typescript#react): Build realtime React apps on Neon with end-to-end reactivity and type-safety »

--- [Document source](https://neon.com/docs/guides/render.md) ---

> Summary: Connecting a Node.js Express application to a Lakebase Postgres database and deploying it on Render covers project scaffolding, pg driver configuration, and pushing to GitHub to trigger automatic Render deployments. Use this guide when you want a serverless Postgres backend for a Render web service without using Render's native database. The guide uses Node.js with the pg library and Render's Git-based continuous deployment.

# Use Lakebase Postgres with Render

Connect a Lakebase Postgres database to your Node application deployed with Render

Last updated: 2026-10-09

[Render](https://render.com) is a comprehensive cloud service that provides hosting for web applications and static sites, with PR previews, zero-downtime deployments, and more. Render supports full-stack applications, offering both web services and background workers.

This guide shows how to deploy a simple Node.js application connected to a Lakebase Postgres database on Render.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- A Render account. If you do not have one, sign up at [Render](https://render.com) to get started.
- A GitHub account. Render integrates with public GitHub providers for continuous deployment. So, you'd need a GitHub account to upload your application code.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.

## Setting up your database

### Initialize a new project

Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.

- Click the `New Project` button to create a new project.

- In the Neon Console, navigate to **Postgres database** > **SQL Editor** from the sidebar, and run the following SQL command to create a new table in your database:

  ```sql
  CREATE TABLE books_to_read (
      id SERIAL PRIMARY KEY,
      title TEXT,
      author TEXT
  );
  ```

  Next, we insert some sample data into the `books_to_read` table, so we can query it later:

  ```sql
  INSERT INTO books_to_read (title, author)
  VALUES
      ('The Way of Kings', 'Brandon Sanderson'),
      ('The Name of the Wind', 'Patrick Rothfuss'),
      ('Coders at Work', 'Peter Seibel'),
      ('1984', 'George Orwell');
  ```

### Retrieve your Neon database connection string

You can find the connection string for your database by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

## Implementing the Node.js application

We'll create a simple Express application that connects to our Neon database and retrieve the sample data from the `books_to_read` table. Run the following commands in a terminal to set it up.

```bash
mkdir neon-render-example && cd neon-render-example
npm init -y && npm pkg set type="module"
npm install express pg
touch .env
```

We use the `npm pkg set type="module"` command to enable ES6 module support in our project. We also create a new `.env` file to store the `DATABASE_URL` environment variable, which we'll use to connect to our Neon database. Lastly, we install the `pg` library which is the Postgres driver we use to connect to our database.

```bash
# .env
DATABASE_URL=NEON_DATABASE_CONNECTION_STRING
```

Now, create a new file named `index.js` and add the following code:

```javascript
import express from 'express';
import pkg from 'pg';

const app = express();
const port = process.env.PORT || 3000;

// Parse JSON bodies for this app
app.use(express.json());

// Create a new pool using your Neon database connection string
const { Pool } = pkg;
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

app.get('/', async (req, res) => {
  try {
    // Fetch books from your database using the postgres connection
    const { rows } = await pool.query('SELECT * FROM books_to_read;');
    res.json(rows);
  } catch (error) {
    console.error('Failed to fetch books', error);
    res.status(500).json({ error: 'Internal Server Error' });
  }
});

// Start the server
app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});
```

This code sets up an Express server that listens for requests on port 3000. When a request is made to the `URL`, the server queries the `books_to_read` table in your Neon database and returns the results as JSON.

We can test this application locally by running:

```bash
node --env-file=.env index.js
```

Now, navigate to `http://localhost:3000/` in your browser to check that it returns the sample data from the `books_to_read` table.

## Push Your application to GitHub

To deploy your application to Render, you need to push your code to a GitHub repository. Create a new repository on GitHub by navigating to [GitHub - New Repo](https://github.com/new). You can then push your code to the new repository using the following commands:

```bash
echo "node_modules/" > .gitignore && echo ".env" >> .gitignore
echo "# neon-render-example" >> README.md
git init && git add . && git commit -m "Initial commit"
git branch -M main
git remote add origin YOUR_GITHUB_REPO_URL
git push -u origin main
```

You can visit the GitHub repository to verify that your code has been pushed successfully.

## Deploying to Render

### Create a New Web Service on Render

Log in to your Render account and navigate to the dashboard. Click on the `New +` button and select "Web Service". Pick the option to `build and deploy` from a Git repository.

Next, choose the GitHub repository hosting the Node.js application we created above. Configure your web service as follows: - **Environment**: Select "Node". - **Build Command**: Enter `npm install`. - **Start Command**: Enter `node index.js`. - **Environment Variables**: Add your Neon database connection string from earlier as an environment variable: - Name: `DATABASE_URL` - Value: `{NEON_DATABASE_CONNECTION_STRING}`

Click "Create Web Service" to finish. Render will automatically deploy your application and redirect you to the service dashboard, showing the deployment progress and the logs.

### Verify Deployment

Once the deployment completes, Render provides a public URL for accessing the web service. Visit the provided URL to verify that your application is running and can connect to your Neon database.

Whenever you update your code and push it to your GitHub repository, Render will automatically build and deploy the changes to your web service.

## Removing Your Application and Neon Project

To remove your application from Render, navigate to the dashboard, select `Settings` for the deployed application, and scroll down to find the "Delete Web Service" option.

To delete your Neon project, follow the steps outlined in the Neon documentation under [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

## Resources

- [Render platform](https://render.com/)
- [Neon](https://neon.tech)

--- [Document source](https://neon.com/docs/guides/reset-from-parent.md) ---

> Summary: Reset from parent instantly overwrites all databases on a Neon child branch with the latest schema and data from its parent, discarding any local changes. Use this feature to refresh a development or staging branch from production without creating a backup. Unlike Instant restore, it does not preserve a backup and is intended for syncing rather than data recovery. Root branches cannot be reset, and branches with their own children must have those children deleted first.

# Reset from parent

Learn how to reset a branch from its parent

Last updated: 2026-09-25

Neon's **Reset from parent** feature lets you instantly reset all databases on a branch to the latest schema and data from its parent branch, helping you recover from issues, start on new feature development, or keep the different branches in your environment in sync.

## Example scenario

When working with database branches, you might find yourself in a situation where you need to update your working branch to the latest data from your production branch.

For example, let's say you have two child branches `staging` and `development` forked from your `production` branch. You have been working on the `development` branch and find it is now too far out of date with `production`.

You have no schema changes in `development` to consider or preserve; you just want a quick refresh of the data. With the **Reset from parent** feature, you can perform a clean, instant reset to the latest data from the parent in a single operation, saving you the complication of manually creating and restoring branches.

## How Reset from parent works

When you reset a branch to its parent, the data and schema is completely replaced with the latest data and schema from its parent.

### Key points

- You can only reset a branch to the latest data from its parent. Point-in-time resets based on timestamp or LSN are possible using [Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore), a similar feature, with some differences: instant restore leaves a backup branch and is in general is intended more for data recovery than development workflow.
- This reset is a complete overwrite of the branch's databases, not a refresh or a merge. Any local changes to the branch's Postgres data or Managed Better Auth state are lost during the reset, and there is no way to exclude `neon_auth`. Unlike instant restore, a reset leaves no backup branch, so keep any auth work you want to preserve on its own branch.
- Object Storage is reset along with the database. The branch's buckets and objects return to the parent's current state, so any uploads, overwrites, and deletes you made on the branch are discarded. This is different from [Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore), which leaves Object Storage untouched. Functions are not part of the database timeline, so a reset does not affect them.
- Existing connections will be temporarily interrupted during the reset. However, your connection details _do not change_. All connections are re-established as soon as the reset is done.
- Root branches (like your project's `production` branch or schema-only branches) cannot be reset because they have no parent branch to reset to.

### Branch expiration behavior

When you reset a branch that has an expiration set, the expiration timer restarts from the reset time using the original duration.

For example, if your branch was originally set to expire in 24 hours, resetting gives it another full 24 hours from the reset time. This process recalculates the new `expires_at` value using the preserved `ttl_interval_seconds`, but the TTL interval itself remains unchanged.

For more details about branch expiration, see [branch expiration](https://neon.com/docs/guides/branch-expiration).

## How to Reset from parent

You can reset any branch to its parent using any of our tools.

**Console**

On the **Branches** page in the Neon Console, select the branch that you want to reset.

The console opens to the details page for your branch, giving you key information about the branch and its child status: its parent, the last time it was reset, and other relevant detail.

To reset the branch, select **Reset from parent** from the three-dot menu (⋮), or click the **Reset from parent** button in the **Branch** panel.

![Reset from parent](https://neon.com/docs/manage/reset_from_parent.png)

**Note:** If this branch has children of its own, resetting is blocked. The resulting error dialog lets you delete these child branches, after which you can continue with the reset.

**CLI**

Using the CLI, you can reset a branch from parent using the following command:

```bash
neon branches reset <id|name> --parent
```

In the `id|name` field, specify the branch ID or name of the child branch whose data you want to reset. The `--parent` parameter is a boolean specifying the kind of reset action that Neon will perform.

If you have multiple projects in your account, you'll also have to include the `project-id` in the command along with the branch.

```bash
neon branches reset <id|name> --parent --project-id <project id>
```

Example:

```bash
neon branches reset development --parent --project-id noisy-pond-12345678
```

Alternatively, you can set the `project-id` as a background context for your CLI session, letting you perform other actions against that project without having to include the `project-id` in every command. The setting is saved in a `context-file` and remains in place until you set a new context, or you remove the `context-file`.

```bash
neon set-context --project-id <project id>
```

Read more about performing branching actions from the CLI in [CLI - branches](https://neon.com/docs/cli/branches), and more about setting contexts in [CLI - set-context](https://neon.com/docs/cli/set-context).

**API**

To reset a branch to its parent using the API, use the [Restore branch](https://neon.com/docs/reference/api/branches/restore-project-branch) endpoint, specifying the parent branch ID as the `source_branch_id`:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/{NEON_PROJECT_ID}/branches/{BRANCH_ID}/restore \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "source_branch_id": "br-autumn-tree-a4a9k5g8"
}
'
```

For details, see [Instant restore using the API](https://neon.com/docs/postgres/backup-restore/branch-restore#how-to-use-instant-restore)

## Integrating branch resets in CI/CD workflows

You can include resetting database branches as part of your CI/CD workflow. For example, when **starting a new feature** or **refreshing staging**.

### For new features

Start feature development with a clean slate by resetting your development branch to align with staging or production (whichever is its parent). This replaces the branch's current Postgres database and Managed Better Auth state with the parent's latest data and schema. Use the command:

```bash
neon branches reset dev-branch --parent
```

This strategy preserves a stable connection string for your development environment, while still ensuring every new feature begins with a consistent baseline that includes your database and Managed Better Auth state.

### Refresh staging

Reset **staging** to match its parent branch (i.e., **production**) for a reliable Postgres database testing baseline. Automate staging updates with:

```bash
neon branches reset staging --parent
```

This ensures staging accurately reflects the current production database state for reliable testing.

## Limitations

- **Reset from parent is unavailable for up to 24 hours after a parent is restored from a snapshot.** If a parent branch is restored from a snapshot, its child branches cannot be reset from that parent for up to 24 hours. If you need to update a child branch during this period, consider using [Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore) to restore the child branch from the parent directly.

--- [Document source](https://neon.com/docs/guides/rls-drizzle.md) ---

> Summary: Drizzle ORM's `crudPolicy` and `pgPolicy` helpers let you declare Row-Level Security policies directly in your TypeScript schema, replacing repetitive per-table SQL with a single migration step that enforces access rules at the Postgres level. Use this page when you want to define, version, and migrate RLS policies through Drizzle rather than write raw SQL. Patterns covered include user-owned data, role-based access, and relationship-based rules. For running queries that respect those policies at runtime, see the companion page on RLS query execution with Drizzle.

# Simplify RLS with Drizzle

Use Drizzle ORM to declaratively manage Row-Level Security policies in your schema

Last updated: 2026-10-14

**What you'll learn**

- How to simplify Row-Level Security using `crudPolicy`
- Common RLS patterns with Drizzle
- How to use custom Postgres roles with your policies
- How to use Drizzle RLS with the Data API
- How to use Drizzle RLS with the serverless driver

**Related docs**

- [Row-Level Security with Neon](https://neon.com/docs/guides/row-level-security)
- [Data API](https://neon.com/docs/data-api/get-started)
- [RLS in Drizzle](https://orm.drizzle.team/docs/rls)

Row-Level Security (RLS) is an important last line of defense for protecting your data at the database level. It ensures that users can only access the data they are permitted to see. When exposing your database directly to clients (for example, through the [Data API](https://neon.com/docs/data-api/get-started)), RLS policies are highly recommended to keep your data secure.

However, implementing RLS natively requires writing and maintaining separate SQL policies for each table, and often for each CRUD operation (Create, Read, Update, Delete). This can quickly become tedious and error-prone.

Drizzle ORM provides a declarative way to manage these policies directly within your TypeScript database schema, making them much easier to write, review, and maintain. Once you define policies in your Drizzle schema and run migrations, they are automatically created in your Postgres database and reliably enforced for all queries.

## The baseline: RLS in plain SQL

Before seeing how Drizzle simplifies things, it helps to understand the underlying SQL it replaces. Below is a sample schema for a basic todo application, where users should only be able to view and manage their own tasks:

```sql
CREATE TABLE IF NOT EXISTS "todos" (
    "id" bigint PRIMARY KEY,
    "user_id" text DEFAULT (auth.user_id()) NOT NULL,
    "task" text NOT NULL,
    "is_complete" boolean DEFAULT false NOT NULL
);

-- This boilerplate SQL code is required for every table you want to secure
ALTER TABLE "todos" ENABLE ROW LEVEL SECURITY;

CREATE POLICY "manage todos" ON "todos"
FOR ALL
TO "authenticated"
USING ((select auth.user_id()) = user_id);
```

These SQL policies guarantee strict, per-user access control at the database level. The `USING` clause defines the condition under which a row is accessible (readable). Since `WITH CHECK` is omitted, Postgres automatically applies the `USING` condition to also restrict inserts and updates.

### Understanding authentication context

Notice the `auth.user_id()` function in the SQL above. When you use Neon's [Data API](https://neon.com/docs/data-api/get-started) alongside your database, this function automatically extracts the user identifier from the active [JWT claims](https://neon.com/blog/wtf-are-jwts). This makes the authenticated user's identity securely available directly in your database policies without needing extra backend logic.

While this plain SQL approach is secure and explicit, managing multiple policies across many tables can become repetitive. Drizzle's declarative `crudPolicy` and `pgPolicy` helpers eliminate this boilerplate, letting you define your security logic directly alongside your tables for better maintainability.

## Simplifying RLS with crudPolicy

Drizzle provides a convenient `crudPolicy` helper to simplify the creation of RLS policies. With `crudPolicy`, you can achieve the same result declaratively. For example:

```typescript {17-21}
import { pgTable, text, bigint, boolean } from 'drizzle-orm/pg-core';
import { crudPolicy, authenticatedRole, authUid } from 'drizzle-orm/neon';
import { sql } from 'drizzle-orm';

export const todos = pgTable(
  'todos',
  {
    id: bigint('id', { mode: 'number' }).primaryKey(),
    userId: text('user_id')
      .notNull()
      .default(sql`(auth.user_id())`),
    task: text('task').notNull(),
    isComplete: boolean('is_complete').notNull().default(false),
  },
  (table) => [
    // Apply RLS policies for the 'authenticated' role
    crudPolicy({
      role: authenticatedRole,
      read: authUid(table.userId), // Users can only read their own todos
      modify: authUid(table.userId), // Users can only create, update, or delete their own todos
    }),
  ]
);
```

**Note:** **About Drizzle's role:** Drizzle is used to **declare and migrate RLS policies** in TypeScript. When migrations are run, these policies are created in your Postgres database and enforced automatically regardless of how queries are executed. Run these migrations over a direct (non-pooled) connection string, not a pooled one. See [Schema migration with Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations) and [Connection pooling](https://neon.com/docs/connect/connection-pooling).

You can run queries that respect these policies using either the [Data API client](https://neon.com/docs/data-api/get-started#connect-and-query) (frontend) or the [Neon serverless driver](https://neon.com/docs/guides/rls-drizzle#using-drizzle-with-the-serverless-driver) using the Drizzle query builder (backend).

### Configuration parameters

The `crudPolicy` function from `drizzle-orm/neon` is a high-level helper that declaratively generates Row-Level Security (RLS) policies for your tables. It accepts the following parameters:

- **`role`**: The Postgres role or array of roles the policy applies to. Neon provides `authenticatedRole` and `anonymousRole` out of the box, but you can also use custom roles.
- **`read`**: Controls access to `SELECT` operations. Accepts:
  - `true` to allow all reads for the role
  - `false` to deny all reads
  - a custom SQL expression for fine-grained access (for example, `authUid(table.userId)`)
  - `null` to skip generating a `SELECT` policy
- **`modify`**: Controls access to `INSERT`, `UPDATE`, and `DELETE` operations. Accepts:
  - `true` to allow all modifications
  - `false` to deny all modifications
  - a custom SQL expression for conditional access (for example, `authUid(table.userId)`)
  - `null` to skip generating policies for these operations

The `crudPolicy` helper generates an array of RLS policy definitions for all CRUD operations (select, insert, update, delete) based on these parameters. For most use cases, this lets you express common access patterns with minimal boilerplate.

> The `authUid(column)` helper generates the SQL condition `(select auth.user_id() = column)`, which is used to restrict access to rows owned by the current user for use in `read` and `modify` policies.

## Fine-grained control with pgPolicy

While `crudPolicy` is ideal for scenarios where a role has the same permissions for reading and modifying data, there are cases where you need more granular control. For these situations, you can use Drizzle's `pgPolicy` function, which provides the flexibility to define custom policies for each operation.

Using `pgPolicy` is ideal when you need to:

- Define different logic for `INSERT` vs. `UPDATE` operations.
- Create a policy for a single command, like `DELETE` only.
- Implement complex conditions where the `USING` and `WITH CHECK` clauses differ significantly.

For example, you might want to allow only users with an `admin` role to update or delete rows in a table, while regular users can insert new rows and view only their own data. This kind of scenario where different roles have different permissions for each operation is easy to express using `pgPolicy`, giving you fine-grained control over who can perform which actions on your data.

### Replicating `crudPolicy` with `pgPolicy`

To understand how `pgPolicy` works, let's rewrite the `todos` example using it. The following `pgPolicy` definition is exactly what `crudPolicy` would generate from your simpler configuration.

```typescript {18-22}
import { pgTable, text, bigint, boolean, pgPolicy } from 'drizzle-orm/pg-core';
import { authenticatedRole, authUid } from 'drizzle-orm/neon';
import { sql } from 'drizzle-orm';

export const todos = pgTable(
  'todos',
  {
    id: bigint('id', { mode: 'number' }).primaryKey(),
    userId: text('user_id')
      .notNull()
      .default(sql`(auth.user_id())`),
    task: text('task').notNull(),
    isComplete: boolean('is_complete').notNull().default(false),
  },
  (table) => {
    return [
      // Single policy for all CRUD operations
      pgPolicy('manage todos', {
        for: 'all',
        to: authenticatedRole,
        using: authUid(table.userId), // users can only access their own todos
      }),
    ];
  }
);
```

This single `pgPolicy` definition with `for: 'all'` is exactly what `crudPolicy` would generate from your simpler configuration. Note that `withCheck` is omitted because when it's not specified, PostgreSQL automatically uses the `USING` clause for both read and write checks. This eliminates unnecessary repetition while maintaining the same security guarantees.

You can apply this approach to additional tables and operations, allowing you to define increasingly sophisticated and tailored security policies as your application's requirements evolve.

### Example: Time limited updates

Here is how you can implement a rule that `crudPolicy` can't handle alone: **A user can update their todo, but only within 24 hours of creating it.** They should still be able to view and delete it anytime.

This requires a different `WITH CHECK` condition for `UPDATE` than the `USING` condition.

```typescript {17,20,24-28,31-35,38-42,45-50}
import { pgTable, text, bigint, timestamp, pgPolicy, boolean } from 'drizzle-orm/pg-core';
import { authenticatedRole } from 'drizzle-orm/neon';
import { sql } from 'drizzle-orm';

export const todos = pgTable(
  'todos',
  {
    id: bigint('id', { mode: 'number' }).primaryKey(),
    userId: text('user_id')
      .notNull()
      .default(sql`(auth.user_id())`),
    task: text('task').notNull(),
    isComplete: boolean('is_complete').notNull().default(false),
    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
  },
  (table) => {
    const userOwnsTodo = sql`(select auth.user_id() = ${table.userId})`;

    // Condition for updates: user must own the todo AND it must be less than 24 hours old.
    const canUpdateTodo = sql`(${userOwnsTodo} and ${table.createdAt} > now() - interval '24 hours')`;

    return [
      // View policy remains the same.
      pgPolicy('view todos', {
        for: 'select',
        to: authenticatedRole,
        using: userOwnsTodo,
      }),

      // Insert policy also remains the same.
      pgPolicy('create todos', {
        for: 'insert',
        to: authenticatedRole,
        withCheck: userOwnsTodo,
      }),

      // Delete policy remains the same.
      pgPolicy('delete todos', {
        for: 'delete',
        to: authenticatedRole,
        using: userOwnsTodo,
      }),

      // The update policy now has a different, stricter WITH CHECK condition.
      pgPolicy('update todos (time-limited)', {
        for: 'update',
        to: authenticatedRole,
        using: userOwnsTodo, // User must own the row to even attempt an update.
        withCheck: canUpdateTodo, // The updated row must satisfy this stricter condition.
      }),
    ];
  }
);
```

This example demonstrates how `pgPolicy` gives you precise, command-level control over your security rules, making it easy to implement complex business logic directly in your database schema.

## Securing database views with RLS

Row-Level Security (RLS) can also be enabled on Postgres views, allowing you to control access to view data at the row level. For details on how to enable RLS on views and apply policies using Drizzle, refer to the [Drizzle documentation](https://orm.drizzle.team/docs/rls#rls-on-views). This approach makes it possible to expose curated or joined subsets of your data while ensuring users only see the rows they are authorized to access.

## Common RLS patterns

Using `crudPolicy` and `pgPolicy`, you can implement a variety of security models. Here are some of the most common ones:

### User-Owned Data

This is the most common RLS pattern, where each user can access only the records they own. It's ideal for applications such as personal to-do lists, user profile settings, or any scenario where users should have full control over their own data and no visibility into others' information. As demonstrated in the todos example above, this approach ensures strict data isolation and privacy.

A typical `crudPolicy` and a `pgPolicy` for this scenario might look like:

**Drizzle (crudPolicy)**

```typescript
[
  crudPolicy({
    role: authenticatedRole,
    read: authUid(table.userId),
    modify: authUid(table.userId),
  }),
];
```

**Drizzle (pgPolicy)**

```typescript
[
  pgPolicy('manage todos', {
    for: 'all',
    to: authenticatedRole,
    using: authUid(table.userId),
  }),
];
```

### Role-based access control

Assign different permissions to anonymous users and authenticated users. For example, in a blog application, anyone can read posts, but only authenticated users can modify their own content. This setup uses separate policies for the `anonymousRole` (public read access) and the `authenticatedRole` (user-specific modifications), making it ideal for applications that distinguish between public and logged-in user actions.

A typical Drizzle schema with `crudPolicy` and `pgPolicy` for this scenario might look like:

**Drizzle (crudPolicy)**

```typescript {17-21,23-27}
import { sql } from 'drizzle-orm';
import { crudPolicy, authenticatedRole, authUid, anonymousRole } from 'drizzle-orm/neon';
import { bigint, boolean, pgTable, text } from 'drizzle-orm/pg-core';

export const posts = pgTable(
  'posts',
  {
    id: bigint({ mode: 'number' }).primaryKey().generatedAlwaysAsIdentity(),
    userId: text('user_id')
      .notNull()
      .default(sql`(auth.user_id())`),
    content: text().notNull(),
    published: boolean().notNull().default(false),
  },
  (table) => [
    // Public read access
    crudPolicy({
      role: anonymousRole,
      read: true, // Anyone can read
      modify: false, // No one can modify anonymously
    }),
    // Policy for authenticated users
    crudPolicy({
      role: authenticatedRole,
      read: true, // Can also read all posts
      modify: authUid(table.userId), // Can only modify their own posts
    }),
  ]
);
```

**Drizzle (pgPolicy)**

```typescript {17-21,24-28}
import { sql } from 'drizzle-orm';
import { authenticatedRole, authUid, anonymousRole } from 'drizzle-orm/neon';
import { bigint, boolean, pgPolicy, pgTable, text } from 'drizzle-orm/pg-core';

export const posts = pgTable(
  'posts',
  {
    id: bigint({ mode: 'number' }).primaryKey(),
    userId: text()
      .notNull()
      .default(sql`(auth.user_id())`),
    content: text().notNull(),
    published: boolean().notNull().default(false),
  },
  (table) => [
    // Anonymous users can read but not modify
    pgPolicy('Anonymous users can read posts', {
      to: anonymousRole,
      for: 'all',
      using: sql`true`, // can read all posts
      withCheck: sql`false`, // cannot create/modify posts
    }),

    // Authenticated users can read all, modify their own
    pgPolicy('Authenticated users manage their own posts', {
      to: authenticatedRole,
      for: 'all',
      using: sql`true`, // can read all posts
      withCheck: authUid(table.userId), // can only create/modify their own
    }),
  ]
);
```

### Complex relationships & shared data

Secure data based on relationships in other tables, such as allowing access to a shared document only if the user is part of a specific group or project. This often involves more complex SQL queries and may require additional metadata to be stored alongside your main data.

This is where Drizzle really helps: expressing these relationship based policies declaratively in your schema is much less error-prone and far easier to maintain than writing raw SQL policies by hand.

For example, suppose you have a `notes` table and a `paragraphs` table that contains the text of each note. You want to ensure that users can only access paragraphs from notes they own or that are shared with them.

```typescript {17-21,23-27,40-44,46-50}
import { sql } from 'drizzle-orm';
import { crudPolicy, authenticatedRole, authUid } from 'drizzle-orm/neon';
import { boolean, pgPolicy, pgTable, text, uuid } from 'drizzle-orm/pg-core';

export const notes = pgTable(
  'notes',
  {
    id: uuid('id').defaultRandom().primaryKey(),
    ownerId: text('owner_id')
      .notNull()
      .default(sql`auth.user_id()`),
    title: text('title').notNull().default('untitled note'),
    shared: boolean('shared').default(false),
  },
  (table) => [
    // Users can only access their own notes
    crudPolicy({
      role: authenticatedRole,
      read: authUid(table.ownerId),
      modify: authUid(table.ownerId),
    }),
    // Shared notes are visible to authenticated users
    pgPolicy('shared_policy', {
      for: 'select',
      to: authenticatedRole,
      using: sql`${table.shared} = true`,
    }),
  ]
);

export const paragraphs = pgTable(
  'paragraphs',
  {
    id: uuid('id').defaultRandom().primaryKey(),
    noteId: uuid('note_id').references(() => notes.id),
    content: text('content').notNull(),
  },
  (table) => [
    // Users can only access paragraphs from their own notes
    crudPolicy({
      role: authenticatedRole,
      read: sql`(select notes.owner_id = auth.user_id() from notes where notes.id = ${table.noteId})`,
      modify: sql`(select notes.owner_id = auth.user_id() from notes where notes.id = ${table.noteId})`,
    }),
    // Shared note paragraphs are visible to authenticated users
    pgPolicy('shared_policy', {
      for: 'select',
      to: authenticatedRole,
      using: sql`(select notes.shared from notes where notes.id = ${table.noteId})`,
    }),
  ]
);
```

In this example:

- Users can only access paragraphs from notes they own or that are shared with them.
- Shared paragraphs are visible to authenticated users.

This pattern can be adapted for other relationship-based access controls, such as project teams, organization memberships, or shared resources.

## Executing queries with RLS policies

Once your RLS policies are defined in your Drizzle schema, you can choose the appropriate client based on your application:

- Use the [Data API client](https://neon.com/docs/data-api/get-started#connect-and-query) for frontend applications
- Use the Neon serverless driver for backend applications. For a deeper dive, see [Run RLS queries with Drizzle ORM](https://neon.com/docs/guides/rls-query-execution).

--- [Document source](https://neon.com/docs/guides/rls-query-execution.md) ---

> Summary: Running RLS queries with Drizzle ORM on Neon requires custom Postgres roles with LOGIN and no BYPASSRLS, plus separate connection strings for authenticated vs. admin access. JWT claims are injected via set_config inside a transaction. Use this page after defining RLS policies in your Drizzle schema to wire up the runtime connection layer, whether from a frontend using the Data API or a backend using the Neon serverless driver.

# Run RLS queries with Drizzle ORM

Learn how to execute RLS queries securely with Drizzle ORM, including best practices for Postgres roles, connection management, and dynamic client setup.

Last updated: 2026-07-15

**What you'll learn**

- How to create and use custom Postgres roles for RLS with Drizzle
- Differences between authenticated and admin connection strings and when to use each
- How to use Drizzle and RLS with the Data API (frontend)
- Drizzle client setup using auth token callbacks (backend)

**Related docs**

- [Simplify RLS with Drizzle](https://neon.com/docs/guides/rls-drizzle)
- [Row-Level Security with Neon](https://neon.com/docs/guides/row-level-security)
- [RLS in Drizzle](https://orm.drizzle.team/docs/rls)

After defining Row-Level Security (RLS) policies [in your Drizzle schema](https://neon.com/docs/guides/rls-drizzle), you need to choose how to connect to Postgres and execute queries that respect these policies.

Depending on your application architecture, you might connect from a frontend (using the Data API) or a backend (using the Neon serverless driver).

Before diving into client implementations, it's important to understand how Postgres roles and connection strings affect RLS enforcement. The role you use to connect determines whether RLS policies are applied or bypassed, so configuring roles correctly is essential for maintaining security.

- **Admin connection strings** (e.g., `neondb_owner`) include the `BYPASSRLS` attribute, meaning they ignore RLS policies entirely. Use these only for administrative tasks such as migrations or privileged background jobs.
- **Authenticated roles** (e.g., the default `authenticated`, `anonymous` roles used by the Data API) have the `NOLOGIN` attribute, so they cannot be used for direct backend connections. To enforce RLS in your backend, you'll need a custom login-enabled role.

## Creating custom roles for RLS

To properly enforce RLS, avoid using default administrative roles like `neondb_owner`, as they bypass all policies. Instead, create a custom role that:

- Has login privileges (`LOGIN`)
- Does **not** have the `BYPASSRLS` attribute
- Is distinct from the built-in `authenticated` role.

Using custom roles allows you to enforce RLS consistently while tailoring permissions for different user groups (e.g., users, moderators, admins) based on your application's security requirements.

### 1. Create a custom role in Postgres

You can execute these commands in the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or via a custom database migration to set up the role and grant the necessary schema permissions.

**Tip: Why not use Drizzle migrations?**

Drizzle's migration system is focused on schema changes and does not currently support role management or permission grants. To configure roles, you'll need to run SQL commands directly in Postgres or include them in a custom (empty) migration file.

For example, the following SQL creates a role named `authenticated_backend` with login privileges and grants it access to the `public` schema and specific table `todos`. Optionally, use the commented sql commands to set default privileges for all present and future tables in the `public` schema.

```sql
-- Create a custom role to be used by your application backend to connect
CREATE ROLE authenticated_backend WITH LOGIN PASSWORD 'your_secure_password';

-- Grant schema access
GRANT USAGE ON SCHEMA public TO authenticated_backend;

-- Grant access to specific tables (e.g., todos, users)
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLE todos TO authenticated_backend;

-- Note: Repeat the GRANT statement for any other tables this role needs to access (e.g., users, projects, etc.)
-- GRANT SELECT, UPDATE, INSERT, DELETE ON ALL TABLES IN SCHEMA public TO authenticated_backend;

-- Set default privileges for future tables in the schema:
-- ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, UPDATE, INSERT, DELETE ON TABLES TO authenticated_backend;
```

### 2. Map the custom role in Drizzle

Once the role exists, map it in your Drizzle schema to apply RLS policies for that specific role.

```typescript {5,19-23}
import { sql } from 'drizzle-orm';
import { authUid, crudPolicy } from 'drizzle-orm/neon';
import { bigint, boolean, pgRole, pgTable, text } from 'drizzle-orm/pg-core';

export const backendRole = pgRole('authenticated_backend').existing();

export const todos = pgTable(
  'todos',
  {
    id: bigint({ mode: 'number' }).primaryKey(),
    userId: text()
      .notNull()
      .default(sql`(auth.user_id())`),
    task: text().notNull(),
    isComplete: boolean().notNull().default(false),
  },
  (table) => [
    // Users: can access and modify their own todos
    crudPolicy({
      role: backendRole,
      read: authUid(table.userId), // Can only read their own todos
      modify: authUid(table.userId), // Can only modify their own todos
    }),
  ]
);
```

Similarly, you can define additional custom roles (e.g., `moderator_backend`, `admin_backend`) with tailored permissions and map them in your Drizzle schema to support more advanced access control.

Add these as separate `crudPolicy` entries. For example, a `moderator_backend` role could have read access to all todos but only update its own, while an `admin_backend` role might have full read and write access across all todos.

<details>

<summary>Example with multiple roles</summary>

```typescript
import { sql } from 'drizzle-orm';
import { authUid, crudPolicy } from 'drizzle-orm/neon';
import { bigint, boolean, pgRole, pgTable, text } from 'drizzle-orm/pg-core';

export const backendRole = pgRole('authenticated_backend').existing();
export const moderatorRole = pgRole('moderator_backend').existing();
export const adminRole = pgRole('admin_backend').existing();

export const todos = pgTable(
  'todos',
  {
    id: bigint({ mode: 'number' }).primaryKey(),
    userId: text()
      .notNull()
      .default(sql`(auth.user_id())`),
    task: text().notNull(),
    isComplete: boolean().notNull().default(false),
  },
  (table) => [
    // Users: can access and modify their own todos
    crudPolicy({
      role: backendRole,
      read: authUid(table.userId), // Can only read their own todos
      modify: authUid(table.userId), // Can only modify their own todos
    }),
    // Moderators: can read all todos but only modify their own
    crudPolicy({
      role: moderatorRole,
      read: true, // Can read all todos
      modify: authUid(table.userId), // Can only modify their own todos
    }),
    // Admins: can read and modify all todos
    crudPolicy({
      role: adminRole,
      read: true, // Can read all todos
      modify: true, // Can modify all todos
    })
  ]
);
```

Ensure your backend uses the correct connection string for each role and that your application logic assigns roles based on user permissions.

For example, an admin dashboard might connect using the `admin_backend` role, while user-facing APIs use the `authenticated_backend` role.

</details>

## Managing connection strings for RLS

When building applications with RLS, a standard architectural pattern is splitting your database connections into two different URLs to limit risk:

1. **`DATABASE_AUTHENTICATED_URL`**: Used by your main application logic (handling user requests). It connects using your restricted custom role (e.g., `authenticated_backend`) so that RLS is strictly enforced.
2. **`DATABASE_URL` (or `DATABASE_ADMIN_URL`)**: The administrative connection string (e.g., `neondb_owner`). This bypasses RLS (`BYPASSRLS`) and has full privileges. It should **only** be used for running migrations, executing administrative webhooks, building dashboards, or background workers that require a system-wide view of the data.

An example `.env` file structure:

```bash
# Connects with 'authenticated_backend' - enforce RLS, used by user-facing backend APIs
DATABASE_AUTHENTICATED_URL="postgresql://authenticated_backend:xxx@ep-cool-snowflake-12345.us-east-2.aws.neon.tech/neondb?sslmode=require"

# Connects with 'neondb_owner' - bypass RLS, used for setup, migrations, and cron administrative tasks
DATABASE_URL="postgresql://neondb_owner:xxx@ep-cool-snowflake-12345.us-east-2.aws.neon.tech/neondb?sslmode=require"
```

Using the correct connection string ensures your user-facing queries are always secured by RLS, while letting background services accomplish administrative tasks without friction.

## How to run authenticated queries

After defining RLS policies, the next step is choosing how to run queries that respect these policies. Depending on your application architecture, you have two main options for running authenticated queries with RLS.

### Frontend: Use the Data API

For frontend applications, use the [Data API](https://neon.com/docs/data-api/get-started#connect-and-query), which provides a REST interface for your database. In this setup, Drizzle is used only to **declare and migrate RLS policies**; query execution is done with a PostgREST-compatible client such as `@neon/neon-js`, `postgrest-js` etc.

When requests go through the Data API, your database enforces RLS policies automatically based on the JWT claims included in the request. This means that as long as your frontend includes the appropriate authentication token, users will only be able to access the data they're authorized to see.

For complete examples of using Drizzle and RLS with the Data API, see:

- [Data API tutorial](https://neon.com/docs/data-api/demo) - Full note-taking app example built with Managed Better Auth, Drizzle RLS, and the Data API
- [Data API getting started](https://neon.com/docs/data-api/get-started) - Setup and basic queries

### Backend: Use Drizzle with the serverless driver

When connecting a backend API directly to the database using the Neon serverless driver, you have two options for handling authorization. The approach you choose depends on the Postgres role you use to connect.

As mentioned earlier, you must connect using a custom role to enforce RLS at the database level. If you connect using an administrative role (like `neondb_owner`), RLS is bypassed and you must enforce authorization manually in your queries.

Install the necessary dependencies for either approach:

```bash
npm install drizzle-orm @neondatabase/serverless jose
```

#### Secure Backend RLS Client setup

To enforce RLS across your backend securely, you can configure your Drizzle client to automatically apply the user's JWT.

When setting up connection pooling over WebSockets or TCP using `@neondatabase/serverless` and `Pool`, you must open a transaction and manually inject the verified claims using `set_config`.

Below is an abstracted function `getAuthenticatedDb` that transparently handles this lifecycle:

**Note:** The `$withAuth` method in Drizzle is deprecated; instead, set JWT claims in the transaction context as shown below.

```typescript
import { createRemoteJWKSet, jwtVerify, type JWTPayload } from 'jose';
import { Pool } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-serverless';
import { sql } from 'drizzle-orm';
import { todos } from './schema';

// Note: Use DATABASE_AUTHENTICATED_URL that connects via your scoped RLS role
const pool = new Pool({ connectionString: process.env.DATABASE_AUTHENTICATED_URL! });
const db = drizzle(pool);

const JWKS = createRemoteJWKSet(new URL(process.env.JWKS_URL!));

async function verifyJWT(token: string): Promise<JWTPayload> {
    const { payload } = await jwtVerify(token, JWKS, {
        issuer: new URL(process.env.JWKS_URL!).origin, // Update according to your JWT issuer
    });
    if (!payload.sub) throw new Error('JWT missing sub claim');
    return payload;
}

/**
 * Wraps your Drizzle instance in a transaction that automatically applies
 * the given JWT claims natively to Postgres block state.
 */
export const getAuthenticatedDb = async <T>(
    token: string,
    callback: (tx: any) => Promise<T>
): Promise<T> => {
    const claims = await verifyJWT(token);

    // Use a Drizzle transaction to set auth context and execute the provided callback
    return db.transaction(async (tx) => {
        // Inject the claims into the transaction session context
        await tx.execute(sql`select set_config('request.jwt.claims', ${claims}, true)`);

        // Run the user's query against the isolated session
        return callback(tx);
    });
};

// Example usage
getAuthenticatedDb('eyJh...', async (tx) => {
    const todosForUser = await tx.select().from(todos);
    console.log(todosForUser);
});
```

#### Using bypass RLS

When connecting with an administrative role like `neondb_owner` (which inherently has `BYPASSRLS`), RLS policies are **not enforced on the server edge**.

In this case, you must verify the JWT in your backend completely manually and apply access control explicitly inside your `WHERE` clauses.

**Important:** If you choose this approach, RLS policies in your database will be ignored. You must ensure that all queries correctly enforce access control based on the authenticated user's identity. This puts the responsibility for security solely on your backend code.

```typescript
import { drizzle } from 'drizzle-orm/neon-serverless';
import { Pool } from '@neondatabase/serverless';
import { todos } from './schema';
import { sql } from 'drizzle-orm';
import { jwtVerify, createRemoteJWKSet } from 'jose'

async function getTodosForUser(jwtToken: string) {
    // DATABASE_URL here connects with neondb_owner (BYPASSRLS)
    const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
    const db = drizzle(pool);

    try {
        const JWKS = createRemoteJWKSet(new URL("https://your-jwks-url.json"));
        const { payload } = await jwtVerify(jwtToken, JWKS, {
            issuer: "https://your-jwks-url.json"
        });

        // You MUST apply access control manually via WHERE
        const result = await db.select()
          .from(todos)
          .where(sql`${todos.userId} = ${payload.sub}`);

        return result;
    } finally {
        await pool.end();
    }
}
```

--- [Document source](https://neon.com/docs/guides/rls-tutorial.md) ---

> Summary: Step-by-step tutorial for securing a React note-taking app against cross-user data leaks using Postgres Row-Level Security on Neon, with JWT-based `auth.user_id()` and Drizzle's `crudPolicy`. Choose this page when you need to verify that database-level RLS policies hold even after removing application-layer `owner_id` filters, or when integrating Managed Better Auth, Auth0, or Clerk as a JWT provider. The tutorial uses `ALTER TABLE ... DISABLE ROW LEVEL SECURITY` to expose the leak, then shows how `crudPolicy` restores isolation without touching application code.

# Secure your app with RLS

Learn how Row-level Security (RLS) protects user data

Last updated: 2026-07-15

**Sample project**

- [Neon Data API + Managed Better Auth](https://github.com/neondatabase-labs/neon-data-api-neon-auth)

**Related docs**

- [Row-Level security in Drizzle](https://orm.drizzle.team/docs/rls)

In this tutorial, you'll clone and modify up a sample React.js note-taking app to demonstrate how Postgres Row-Level Security (RLS) provides an additional security layer beyond application logic. The app integrates with a Neon database via the Neon Data API.

For authentication, **Managed Better Auth** issues a unique `userId` in a JSON Web Token (JWT) for each user. This `userId` is passed to Postgres, where RLS policies enforce access control directly at the database level. This setup ensures each user can only interact with their own **notes**, even if application-side logic fails. While this example uses Managed Better Auth, any JWT-issuing provider like Auth0 or Clerk can be used.

## Prerequisites

To get started, you'll need:

- **Neon account**: Sign up at [Neon](https://neon.tech) and create your first project in **AWS** (note: Azure regions are not currently supported).
- **Neon Data API + Managed Better Auth example application**: Clone the sample [Neon Data API + Managed Better Auth repository](https://github.com/neondatabase-labs/neon-data-api-neon-auth):

  ```bash
  git clone https://github.com/neondatabase-labs/neon-data-api-neon-auth.git
  ```

  Follow the instructions in the README to set up Neon Data API with Managed Better Auth, configure environment variables, and run database migrations.

  > This sample app uses Managed Better Auth, so select **Managed Better Auth** when enabling the Data API. If you're using a different auth provider, see [Custom authentication providers](https://neon.com/docs/data-api/custom-authentication-providers).

## Create test users

Start the sample application:

```bash
npm run dev
```

Open the app in your browser using [`localhost:5173`](http://localhost:5173).

Now, let's create the two users we'll use to show how RLS policies can prevent data leaks between users, and what can go wrong if you don't. The sample app supports Google and GitHub logins, so let's create one of each. For this guide, we'll call our two users Alice and Bob.

Create your `Alice` user using Google. Then, using a private browser session, create your `Bob` user account using GitHub or other Google account.

Side by side, here's the empty state for both users:

![empty state two users in data api demo](https://neon.com/docs/guides/data_api_demo_empty_state.png)

When each user creates a note, it's securely linked to their `ownerId` in the database schema. Here's the structure of the `notes` table:

```typescript
{
    id: uuid("id").defaultRandom().primaryKey(),
    ownerId: text("owner_id")
      .notNull()
      .default(sql`auth.user_id()`),
    title: text("title").notNull().default("untitled note"),
    createdAt: timestamp("created_at", { withTimezone: true }).defaultNow(),
    updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow(),
    shared: boolean("shared").default(false),
}
```

The `ownerId` column is populated directly from the authenticated `(auth.user_id())` in the JWT, ensuring that each note is tied to the correct user.

## Create notes

Let's create some sample notes for both Alice and Bob.

![isolated note lists](https://neon.com/docs/guides/data_api_demo_isolated_notes.png)

The paragraphs in the notes are:

![paragraphs in notes](https://neon.com/docs/guides/data_api_demo_paragraphs_in_notes.png)

> The notes act as a top level container for paragraphs. Each paragraph is stored in `paragraphs` table, linked to the parent note by `noteId`.

### Notes are isolated

In this sample app, isolation of Notes to each user is handled both in the application logic and using Row-level Security (RLS) policies defined in our application's schema file.

Let's take a look at the `useNotes` function in the `src/routes/index.tsx` file:

```typescript
function useNotes() {
  const session = client.auth.useSession();
  return useQuery({
    queryKey: ['notes'],
    queryFn: async (): Promise<Array<Note>> => {
      if (!session.data) {
        throw new Error('User is not authenticated');
      }
      // `eq` filter is optional because of RLS. But we send it anyway for
      // performance reasons.
      const { data, error } = await client
        .from('notes')
        .select('id, title, created_at, owner_id, shared')
        .eq('owner_id', session.data.user.id)
        .order('created_at', { ascending: false });

      if (error) {
        throw error;
      }

      return data as Array<Note>;
    },
  });
}
```

The `eq` clause is technically enough to make sure data is properly isolated. Neon gets the user id from the Managed Better Auth JWT (`session.data.user.id`) and matches that to the `owner_id` column in the `notes` tables, so each user can only see their own notes.

Even though isolation is backed by our RLS policies, we include it here for performance reasons: it helps Postgres build a better query plan and use indexes where possible.

### RLS policy for viewing notes

In the application's `schema.ts` file, you can find the RLS policies written in Drizzle that provide access control at the database level. Here is a look at one of those policies:

```typescript
crudPolicy({
  role: authenticatedRole,
  read: authUid(table.ownerId),
  modify: authUid(table.ownerId),
});
```

`authUid` is a helper function that evaluates to

```
sql`(select auth.user_id() = owner_id)`
```

which is a SQL expression that checks if the `owner_id` of a row matches the `auth.user_id()` from the JWT.

This policy ensures that read (`SELECT`) queries only returns rows where the `owner_id` matches the `auth.user_id()` derived from the authenticated user's JWT. This means that users can only access their own notes. By enforcing this rule at the database level, the RLS policy provides an extra layer of security beyond the application layer.

## Remove access control from application code

Now, let's test what happens when we remove access control from the application layer to rely solely on RLS at the database level.

In the `src/routes/index.tsx` file, modify the `useNotes` function to remove the `eq` clause that filters notes by `owner_id`:

```typescript
function useNotes() {
  const session = client.auth.useSession();
  return useQuery({
    queryKey: ['notes'],
    queryFn: async (): Promise<Array<Note>> => {
      if (!session.data) {
        throw new Error('User is not authenticated');
      }
      const { data, error } = await client
        .from('notes')
        .select('id, title, created_at, owner_id, shared')
        // .eq("owner_id", session.data.user.id)
        .order('created_at', { ascending: false });

      if (error) {
        throw error;
      }

      return data as Array<Note>;
    },
  });
}
```

Check your two open Notes users, reload the page, and see what happens:

![isolated notes](https://neon.com/docs/guides/data_api_demo_isolated_notes.png)

Nothing happens. RLS is still in place, and isolation is maintained: no data leaks. 💪

## Disable RLS

Let's see what happens when we disable RLS on our notes and paragraphs tables. Go to your project in the Neon Console and in the SQL Editor run:

```sql
ALTER TABLE public.notes DISABLE ROW LEVEL SECURITY;
ALTER TABLE public.paragraphs DISABLE ROW LEVEL SECURITY;
```

![data leak](https://neon.com/docs/guides/data_api_demo_data_leak.png)

Bob can see all of Alice's notes and paragraphs within them, including the 'inquisitive cyan' note where her birthday party is planned. Alice now knows about her birthday party. Disabling RLS removed all RLS policies, including the `crudPolicy` on `read` queries that helped enforce data isolation. Birthday surprise is _ruined_.

### Re-enable RLS

Now, let's re-enable RLS from Neon:

```bash
ALTER TABLE public.notes ENABLE ROW LEVEL SECURITY;
ALTER TABLE public.paragraphs ENABLE ROW LEVEL SECURITY;
```

![isolated notes restored](https://neon.com/docs/guides/data_api_demo_isolated_notes.png)

With RLS back on, there are no more data leaks, despite the lack of access control in the application code. In this case, RLS acts as a backstop, preventing unintended data exposure due to application-side mistakes.

Order is restored, thanks to RLS. Now go fix your app before you forget:

```typescript
function useNotes() {
  const session = client.auth.useSession();
  return useQuery({
    queryKey: ['notes'],
    queryFn: async (): Promise<Array<Note>> => {
      if (!session.data) {
        throw new Error('User is not authenticated');
      }
      const { data, error } = await client
        .from('notes')
        .select('id, title, created_at, owner_id, shared')
        .eq('owner_id', session.data.user.id)
        .order('created_at', { ascending: false });

      if (error) {
        throw error;
      }

      return data as Array<Note>;
    },
  });
}
```

## Appendix: Understanding RLS policies in Drizzle

In this section, we provide an overview of the Row-Level Security (RLS) policies implemented in the Notes application, found in the `schema.ts` file.

These policies are written in Drizzle, which now supports defining RLS policies alongside your schema in code. Writing RLS policies can be complex, so we worked with Drizzle to develop the `crudPolicy` function – a wrapper that works with Neon's predefined roles (`authenticated` and `anonymous`), letting you consolidate all policies that apply to a given role into a single function. See [Row-level Security](https://orm.drizzle.team/docs/rls) in the Drizzle docs for details.

For the `notes` table, the `crudPolicy` function defines RLS policies for the `authenticated` role, which is assigned to users who have successfully logged in. The `read` and `modify` parameters use the `authUid` helper function to ensure that users can only read or modify rows where the `ownerId` matches their own `auth.user_id()` from the JWT.

```typescript
// for `notes` table
crudPolicy({
  role: authenticatedRole,
  read: authUid(table.ownerId),
  modify: authUid(table.ownerId),
});
```

For the `paragraphs` table, the `crudPolicy` function also applies to the `authenticated` role. However, since paragraphs are linked to notes via the `noteId`, the `read` and `modify` parameters use a SQL subquery to check that the `owner_id` of the associated note matches the `auth.user_id()` from the JWT. This ensures that users can only read or modify paragraphs that belong to notes they own.

```typescript
// for `paragraphs` table
crudPolicy({
  role: authenticatedRole,
  read: sql`(select notes.owner_id = auth.user_id() from notes where notes.id = ${table.noteId})`,
  modify: sql`(select notes.owner_id = auth.user_id() from notes where notes.id = ${table.noteId})`,
});
```

These policies together enforce strict access control at the database level, ensuring that users can only interact with their own notes and paragraphs, regardless of any application-side logic.

### Implementing Share Notes functionality

In the `schema.ts` file, you can find additional RLS policies than defined above, which support the "Share Notes" functionality in the application. This feature allows users to share specific notes with others by setting the `shared` column to `true`. The RLS policies for the `notes` table include a condition that permits read access to notes marked as shared, regardless of ownership. The final RLS policy for the `notes` and `paragraphs` tables looks like this:

```typescript
...schema definitions...

// for `notes` table
crudPolicy({
    role: authenticatedRole,
    read: authUid(table.ownerId),
    modify: authUid(table.ownerId),
}),

pgPolicy('shared_policy', {
    for: 'select',
    to: authenticatedRole,
    using: sql`${table.shared} = true`,
})

// for `paragraphs` table
crudPolicy({
    role: authenticatedRole,
    read: sql`(select notes.owner_id = auth.user_id() from notes where notes.id = ${table.noteId})`,
    modify: sql`(select notes.owner_id = auth.user_id() from notes where notes.id = ${table.noteId})`,
}),

pgPolicy('shared_policy', {
    for: 'select',
    to: authenticatedRole,
    using: sql`(select notes.shared from notes where notes.id = ${table.noteId})`,
});
```

The `shared_policy` enables any authenticated user to read notes marked as shared (`shared = true`), allowing others to view shared notes even if they are not the owner. This policy applies similarly to paragraphs, checking if the linked note is shared.

Although RLS permits read access to shared notes for all authenticated users, the shared notes are not directly visible in other users' UI. Instead, sharing occurs via the "Share" button, which copies the note's URL to the clipboard. This URL includes the note's ID, enabling authenticated users to access the shared note and its paragraphs within a read-only mode.

### RLS policies table

To check out the RLS policies defined for the `notes` table in Postgres, run this query:

```sql
   SELECT * FROM pg_policies WHERE tablename = 'notes';
```

Here is the output, showing columns `policyname, cmd, qual, with_check` only:

```sql
policyname                      | cmd    | qual                                        | with_check
--------------------------------+--------+---------------------------------------------+---------------------------------------
crud-authenticated-policy-select | SELECT | (SELECT (auth.user_id() = notes.owner_id)) |
crud-authenticated-policy-insert | INSERT |                                            | (SELECT (auth.user_id() = notes.owner_id))
crud-authenticated-policy-update | UPDATE | (SELECT (auth.user_id() = notes.owner_id)) | (SELECT (auth.user_id() = notes.owner_id))
crud-authenticated-policy-delete | DELETE | (SELECT (auth.user_id() = notes.owner_id)) |
shared_policy                    | SELECT | (shared = true)                            |
(5 rows)
```

To get an understanding of `auth.user_id()` and the role it plays in these policies, see this [explanation](https://neon.com/docs/data-api/get-started#what-is-authuserid-and-authuid).

--- [Document source](https://neon.com/docs/guides/row-level-security.md) ---

> Summary: Row-Level Security (RLS) in Neon restricts table access to individual rows based on the authenticated user, and is required on every table exposed through the Neon Data API. Use this page when adding RLS policies to a Data API project or using Drizzle ORM's crudPolicy helper to simplify per-user access control in a Postgres database.

# Row-Level Security with Neon

How Neon features use Postgres Row-Level Security

Last updated: 2026-06-05

**What you will learn:**

- How the Data API uses Row-Level Security

**Related docs**

- [Data API](https://neon.com/docs/data-api/get-started)
- [Simplify RLS with Drizzle](https://neon.com/docs/guides/rls-drizzle)
- [Postgres RLS Tutorial](https://neon.com/postgresql/postgresql-administration/postgresql-row-level-security)

Row-Level Security (RLS) is a Postgres feature that controls access to individual rows in a table based on the current user. Here's a simple example that limits the `notes` a user can see by matching rows where their `user_id` matches the session's `auth.user_id()`:

```sql
-- Enable RLS on a table
ALTER TABLE notes ENABLE ROW LEVEL SECURITY;

-- Create a policy that only allows users to access their own notes
CREATE POLICY "users_can_only_access_own_notes" ON notes
  FOR ALL USING (auth.user_id() = user_id);
```

When using the Data API for client-side querying, RLS policies are required to secure your data.

## Data API with RLS

The **Data API** turns your database tables on a given branch into a REST API, and it requires RLS policies on all tables to ensure your data is secure.

### How it works

- The Data API handles JWT validation and provides the `auth.user_id()` function.
- Your RLS policies use `auth.user_id()` to control access.
- All tables accessed via the Data API must have RLS enabled.

* [Get started](https://neon.com/docs/data-api/get-started): Learn how to enable and use the Data API with RLS policies
* [Building a note-taking app](https://neon.com/docs/data-api/demo): See a complete example of the Data API with RLS in action

## RLS with Drizzle ORM

Drizzle makes it simple to write RLS policies that work with the Data API. We highly recommend using its `crudPolicy` helper to simplify common RLS patterns.

- [Simplify RLS with Drizzle](https://neon.com/docs/guides/rls-drizzle): Learn how to use Drizzle's crudPolicy function to simplify RLS policies

## Postgres RLS Tutorial

To learn the fundamentals of Row-Level Security in Postgres, including detailed concepts and examples, see the Postgres tutorial:

- [Postgres RLS Tutorial](https://neon.com/postgresql/postgresql-administration/postgresql-row-level-security): A complete guide to Postgres Row-Level Security concepts and implementation

--- [Document source](https://neon.com/docs/guides/ruby-on-rails.md) ---

> Summary: Ruby on Rails connection guide that shows how to configure DATABASE_URL in a .env file so a Rails app connects to a Lakebase Postgres database, covering project creation, role CREATEDB privileges, and running db:create. Use this page when setting up a new or existing Rails project. A separate sibling page covers Rails schema migrations.

# Connect a Ruby on Rails application to Lakebase Postgres

Set up a project on Neon in seconds and connect from a Ruby on Rails application

Last updated: 2026-09-16

Pre-built prompt for connecting Ruby on Rails to Lakebase Postgres [View prompt](https://neon.com/prompts/ruby-on-rails-prompt.md)

[Ruby on Rails](https://rubyonrails.org/), also known simply as Rails, is an open-source web application framework written in Ruby. It uses a model-view-controller architecture, making it a good choice for developing database-backed web applications. This guide shows how to connect a Ruby on Rails application to a Lakebase Postgres database.

To connect to a Lakebase Postgres database from a Ruby on Rails application:

**Note:** This guide was tested using Ruby v4.0.9 and Rails v8.1.4.1. Rails 8.1 requires Ruby 3.2 or later.

## Create a Neon Project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Rails Project

Create a Rails project using the [Rails CLI](https://guides.rubyonrails.org/command_line.html), and specify PostgreSQL as the database type:

```shell
gem install rails
rails new neon-with-rails --database=postgresql
```

You now have a Rails project in a folder named `neon-with-rails`.

## Configure a PostgreSQL Database using Rails

Create a `.env` file in the root of your Rails project, and add the connection string for your Neon compute. Do not specify a database name after the forward slash in the connection string. Rails will choose the correct database depending on the environment.

```text filename=".env"
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/?sslmode=require&channel_binding=require"
```

Rails doesn't read `.env` files on its own. Add the `dotenv-rails` gem to load the file in the development and test environments:

```shell
cd neon-with-rails
bundle add dotenv-rails --group development,test
```

**Note:** You can find the connection string for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

**Important:** The role you specified in the `DATABASE_URL` must have **CREATEDB** privileges. Roles created in the Neon Console or API, including the default role created with a Neon project, are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which has the `CREATEDB` privilege. Roles created with `neon roles create --access` don't have it. Alternatively, you can create roles with SQL to grant specific privileges. See [Manage database access](https://neon.com/docs/manage/database-access).

Create the development database by running the following command from the root of your project directory:

```shell
bin/rails db:create
```

## Create a Rails Controller to Query the Database

Run the following command to create a controller and view. The controller will query the database version and supply it to the view file to render a web page that displays the PostgreSQL version.

```shell
bin/rails generate controller home index
```

Replace the controller contents at `app/controllers/home_controller.rb` with:

```ruby
class HomeController < ApplicationController
  def index
    @version = ActiveRecord::Base.connection.execute("SELECT version();").first['version']
  end
end
```

Replace the contents of the view file at `app/views/home/index.html.erb` with:

```erb
<% if @version %>
  <p><%= @version %></p>
<% end %>
```

Replace the contents of `config/routes.rb` with the following code to serve your home view as the root page of the application:

```ruby
Rails.application.routes.draw do
  get "up" => "rails/health#show", as: :rails_health_check

  # Defines the root path route ("/")
  root 'home#index'
end
```

## Run the application

Start the application using the Rails CLI from the root of the project:

```shell
bin/rails server -e development
```

Visit [localhost:3000/](http://localhost:3000/) in your web browser. Your Neon database's Postgres version will be displayed. For example:

```
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

## Schema migration with Ruby on Rails

For schema migration with Ruby on Rails, see our guide:

- [Ruby on Rails Migrations](https://neon.com/docs/guides/rails-migrations): Schema migration with Lakebase Postgres and Ruby on Rails

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database.
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential.

--- [Document source](https://neon.com/docs/guides/rust.md) ---

> Summary: Connecting a Rust application to Lakebase Postgres using either the synchronous `postgres` crate or the async `tokio-postgres` crate with the Tokio runtime. Both options require SSL/TLS via postgres-openssl. Use this page when you need working Rust code for each CRUD operation, including when to use `execute`, `batch_execute`, or `query` for each SQL pattern.

# Connect a Rust application to Lakebase Postgres

Learn how to run SQL queries from Rust using the postgres or tokio-postgres crates

Last updated: 2026-10-09

Pre-built prompt for connecting Rust applications to Lakebase Postgres [View prompt](https://neon.com/prompts/rust-prompt.md)

This guide describes how to create a project on Neon and connect to it from a Rust application using two popular Postgres drivers: [rust-postgres](https://crates.io/crates/postgres), a synchronous driver, and [tokio-postgres](https://crates.io/crates/tokio-postgres), an asynchronous driver for use with the [Tokio](https://tokio.rs/) runtime.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://console.neon.tech/signup).
- The Rust toolchain. If you do not have it installed, install it from the [official Rust website](https://www.rust-lang.org/tools/install).
- OpenSSL. The `openssl` crate links to your system's OpenSSL library. On Debian or Ubuntu, install `pkg-config` and `libssl-dev`. See the [openssl crate documentation](https://docs.rs/openssl/latest/openssl/#automatic) for other platforms.

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

Your project is created with a ready-to-use database named `neondb`. In the following steps, you will connect to this database from your Rust application.

## Create a Rust project

For your Rust project, use `cargo` to create a new project and add the required library dependencies (called "crates").

1. Create a project directory and change into it.

   ```bash
   cargo new neon-rust-quickstart
   cd neon-rust-quickstart
   ```

   This command creates a new directory named `neon-rust-quickstart` containing a `src/main.rs` file for your code and a `Cargo.toml` file for your project's configuration and dependencies. To set up a project in an existing directory instead, run `cargo init` in that directory.

   > Open the directory in your preferred code editor (for example, VS Code, RustRover, etc.) to edit the files.

2. Add the required crates using `cargo add`. Choose the synchronous `postgres` crate for scripts and command-line tools, or the asynchronous `tokio-postgres` crate if your application already uses Tokio (for example, a web server built on Axum or Actix). Use the same tab for the code examples that follow.

   **postgres (sync)**

   ```bash
   cargo add postgres postgres-openssl openssl dotenvy
   ```

   **tokio-postgres (async)**

   ```bash
   cargo add tokio --features "tokio/full" tokio-postgres postgres-openssl openssl dotenvy
   ```

   **Note: What are features?**

   The `--features` flag tells Cargo to enable optional functionality within a crate. Many crates are designed to be modular, and features allow you to include only the code you actually need. In this case, you are enabling the full Tokio runtime, which includes all components necessary for asynchronous programming.

   You can learn more about features in [The Cargo Book: Features](https://doc.rust-lang.org/cargo/reference/features.html).

   > Neon requires a secure SSL/TLS connection. In the commands above, the `postgres-openssl` crate provides the necessary OpenSSL bindings that both the synchronous `postgres` and asynchronous `tokio-postgres` drivers use to enable TLS.

3. Configure multiple executables.

   You will create separate Rust scripts for each of the CRUD operations (Create, Read, Update, Delete). Each script will be a separate binary target in your project (`create_table.rs`, `read_data.rs`, `update_data.rs`, and `delete_data.rs`).

   To manage separate CRUD examples (`create_table`, `read_data`, etc.), you need to tell Cargo that your project has multiple binary targets.

   Open your `Cargo.toml` file and add the following `[[bin]]` sections to the end of it:

   ```toml filename="Cargo.toml"
   [[bin]]
   name = "create_table"
   path = "src/create_table.rs"

   [[bin]]
   name = "read_data"
   path = "src/read_data.rs"

   [[bin]]
   name = "update_data"
   path = "src/update_data.rs"

   [[bin]]
   name = "delete_data"
   path = "src/delete_data.rs"
   ```

   You can now safely delete the default `src/main.rs` file. Since you have defined specific binary targets (like `create_table`) in `Cargo.toml`, Cargo no longer needs the default `main.rs` entry point.

   ```bash
   rm src/main.rs
   ```

## Store your Neon connection string

Create a file named `.env` in your project's root directory. This file stores your database connection string. Don't commit it to source control.

1. In the [Neon Console](https://console.neon.tech), open your project.
2. Click **Connect** in the Console nav to open the **Connect to your branch** modal.
   ![Connection modal](https://neon.com/docs/connect/connect_to_branch_modal.png)
3. Copy the connection string, which includes your password.
4. Add the connection string to your `.env` file as shown below.
   ```text
   DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
   ```
   > Replace `[user]`, `[password]`, `[neon_hostname]`, and `[dbname]` with your actual database credentials.

## Choosing the right method to execute SQL commands

The `postgres` and `tokio-postgres` crates provide several methods for executing SQL commands. The right method depends on your use case:

- `client.execute`:
  Use this for a single DML/DDL statement (`INSERT`, `UPDATE`, `DELETE`) or a fire-and-forget query. It supports parameter placeholders (`$1`, `$2`, etc.) and returns the number of rows affected (`u64`).

- `client.batch_execute`:  
  Ideal for running multiple SQL commands in one shot (schema migrations, DDL, seed data). Supply a semicolon-separated SQL string. This method does not support parameters and returns `()` on success.

- `client.query`:  
  The go-to for any `SELECT` that returns rows. It accepts placeholders and returns a `Vec<Row>`, so you can iterate over rows and extract typed values.

### Quick comparison

| Method                 | Use case                                                              | Parameters | Returns               |
| ---------------------- | --------------------------------------------------------------------- | ---------- | --------------------- |
| `client.execute`       | Single DML/DDL or ad-hoc query                                        | Yes        | `u64` (rows affected) |
| `client.batch_execute` | Multiple statements in one SQL blob <br/>(DDL, migrations, seed data) | No         | `()`                  |
| `client.query`         | Fetching rows from a `SELECT`                                         | Yes        | `Vec<Row>`            |

The examples below use all three methods (`execute`, `batch_execute`, and `query`).

## Examples

This section provides example Rust scripts that demonstrate how to connect to your Neon database and perform basic operations such as [creating a table](https://neon.com/docs/guides/rust#create-a-table-and-insert-data), [reading data](https://neon.com/docs/guides/rust#read-data), [updating data](https://neon.com/docs/guides/rust#update-data), and [deleting data](https://neon.com/docs/guides/rust#delete-data).

### Create a table and insert data

In your project's `src` directory, create a file named `create_table.rs` and add the code for your preferred driver. This script connects to your Neon database, creates a table named `books`, and inserts some sample data into it.

**postgres (sync)**

```rust filename="src/create_table.rs"
use dotenvy::dotenv;
use postgres::Client;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::env;

fn main() -> Result<(), Box<dyn std::error::Error>> {

    // Load environment variables from .env file
    dotenv()?;
    let conn_string = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());

    let mut client = Client::connect(&conn_string, connector)?;
    println!("Connection established");

    client.batch_execute("DROP TABLE IF EXISTS books;")?;
    println!("Finished dropping table (if it existed).");

    client.batch_execute(
        "CREATE TABLE books (
            id SERIAL PRIMARY KEY,
            title VARCHAR(255) NOT NULL,
            author VARCHAR(255),
            publication_year INT,
            in_stock BOOLEAN DEFAULT TRUE
        );"
    )?;
    println!("Finished creating table.");

    // Insert a single book record
    client.execute(
        "INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4)",
        &[&"The Catcher in the Rye", &"J.D. Salinger", &1951, &true],
    )?;
    println!("Inserted a single book.");

    // Start a transaction
    let mut transaction = client.transaction()?;
    println!("Starting transaction to insert multiple books...");

    // Data to be inserted
    let books_to_insert = [
        ("The Hobbit", "J.R.R. Tolkien", 1937, true),
        ("1984", "George Orwell", 1949, true),
        ("Dune", "Frank Herbert", 1965, false),
    ];

    // Loop and insert within the transaction
    for book in &books_to_insert {
        transaction.execute(
            "INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4)",
            &[&book.0, &book.1, &book.2, &book.3],
        )?;
    }

    // Commit the transaction
    transaction.commit()?;
    println!("Inserted 3 rows of data.");

    Ok(())
}
```

**tokio-postgres (async)**

```rust filename="src/create_table.rs"
use dotenvy::dotenv;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {

    // Load environment variables from .env file
    dotenv()?;
    let conn_string = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());

    let (mut client, connection) = tokio_postgres::connect(&conn_string, connector).await?;
    println!("Connection established");

    tokio::spawn(async move {
        if let Err(e) = connection.await {
            eprintln!("connection error: {}", e);
        }
    });

    client.batch_execute("DROP TABLE IF EXISTS books;").await?;
    println!("Finished dropping table (if it existed).");

    client.batch_execute(
        "CREATE TABLE books (
            id SERIAL PRIMARY KEY,
            title VARCHAR(255) NOT NULL,
            author VARCHAR(255),
            publication_year INT,
            in_stock BOOLEAN DEFAULT TRUE
        );"
    ).await?;
    println!("Finished creating table.");

    // Insert a single book record
    client.execute(
        "INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4)",
        &[&"The Catcher in the Rye", &"J.D. Salinger", &1951, &true],
    ).await?;
    println!("Inserted a single book.");

    // Start a transaction
    let transaction = client.transaction().await?;
    println!("Starting transaction to insert multiple books...");

    // Data to be inserted
    let books_to_insert = [
        ("The Hobbit", "J.R.R. Tolkien", 1937, true),
        ("1984", "George Orwell", 1949, true),
        ("Dune", "Frank Herbert", 1965, false),
    ];

    // Loop and insert within the transaction
    for book in &books_to_insert {
        transaction.execute(
            "INSERT INTO books (title, author, publication_year, in_stock) VALUES ($1, $2, $3, $4)",
            &[&book.0, &book.1, &book.2, &book.3],
        ).await?;
    }

    // Commit the transaction
    transaction.commit().await?;
    println!("Inserted 3 rows of data.");

    Ok(())
}
```

The above code does the following:

- Load the connection string from the `.env` file.
- Connect to the Neon database using a secure TLS connection.
- Drop the `books` table if it already exists to ensure a clean slate.
- Create a new table named `books` with columns for `id`, `title`, `author`, `publication_year`, and `in_stock`.
- Insert a single book record.
- Start a transaction to insert multiple book records in a single operation.

  **Info: Why use a transaction for inserting multiple rows?**

  Unlike database drivers in some other languages that offer a single high-level method for bulk inserts (like [Python's](https://neon.com/docs/guides/python#create-a-table-and-insert-data) `executemany` in `psycopg2`), the idiomatic Rust approach is to loop through the data inside a transaction.

  This guarantees atomicity: all rows are inserted successfully, or none are inserted if an error occurs.

Run the script using the following command:

```bash
cargo run --bin create_table
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established
Finished dropping table (if it existed).
Finished creating table.
Inserted a single book.
Starting transaction to insert multiple books...
Inserted 3 rows of data.
```

### Read data

In your `src` directory, create a file named `read_data.rs`. This script connects to your database and retrieves all rows from the `books` table.

**postgres (sync)**

```rust filename="src/read_data.rs"
use dotenvy::dotenv;
use postgres::Client;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::env;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv()?;
    let conn_string = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());

    let mut client = Client::connect(&conn_string, connector)?;
    println!("Connection established");

    // Fetch all rows from the books table
    let rows = client.query("SELECT * FROM books ORDER BY publication_year;", &[])?;

    println!("\n--- Book Library ---");
    for row in rows {
        let id: i32 = row.get("id");
        let title: &str = row.get("title");
        let author: &str = row.get("author");
        let year: i32 = row.get("publication_year");
        let in_stock: bool = row.get("in_stock");
        println!("ID: {}, Title: {}, Author: {}, Year: {}, In Stock: {}", id, title, author, year, in_stock);
    }
    println!("--------------------\n");

    Ok(())
}
```

**tokio-postgres (async)**

```rust filename="src/read_data.rs"
use dotenvy::dotenv;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv()?;
    let conn_string = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());

    let (client, connection) = tokio_postgres::connect(&conn_string, connector).await?;
    println!("Connection established");

    tokio::spawn(async move {
        if let Err(e) = connection.await {
            eprintln!("connection error: {}", e);
        }
    });

    // Fetch all rows from the books table
    let rows = client.query("SELECT * FROM books ORDER BY publication_year;", &[]).await?;

    println!("\n--- Book Library ---");
    for row in rows {
        let id: i32 = row.get("id");
        let title: &str = row.get("title");
        let author: &str = row.get("author");
        let year: i32 = row.get("publication_year");
        let in_stock: bool = row.get("in_stock");
        println!("ID: {}, Title: {}, Author: {}, Year: {}, In Stock: {}", id, title, author, year, in_stock);
    }
    println!("--------------------\n");

    Ok(())
}
```

The above code does the following:

- Load the connection string from the `.env` file.
- Connect to the Neon database using a secure TLS connection.
- Use a `client.query` method to fetch all rows from the `books` table, ordered by `publication_year`.
- Print each book's details in a formatted output.

Run the script using the following command:

```bash
cargo run --bin read_data
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: false
--------------------
```

### Update data

In your `src` directory, create a file named `update_data.rs`. This script updates the stock status of the book 'Dune' to `true`.

**postgres (sync)**

```rust filename="src/update_data.rs"
use dotenvy::dotenv;
use postgres::Client;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::env;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv()?;
    let conn_string = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());

    let mut client = Client::connect(&conn_string, connector)?;
    println!("Connection established");

    // Update a data row in the table
    let updated_rows = client.execute(
        "UPDATE books SET in_stock = $1 WHERE title = $2",
        &[&true, &"Dune"],
    )?;

    if updated_rows > 0 {
        println!("Updated stock status for 'Dune'.");
    } else {
        println!("'Dune' not found or stock status already up to date.");
    }

    Ok(())
}
```

**tokio-postgres (async)**

```rust filename="src/update_data.rs"
use dotenvy::dotenv;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv()?;
    let conn_string = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());

    let (client, connection) = tokio_postgres::connect(&conn_string, connector).await?;
    println!("Connection established");

    tokio::spawn(async move {
        if let Err(e) = connection.await {
            eprintln!("connection error: {}", e);
        }
    });

    // Update a data row in the table
    let updated_rows = client.execute(
        "UPDATE books SET in_stock = $1 WHERE title = $2",
        &[&true, &"Dune"],
    ).await?;

    if updated_rows > 0 {
        println!("Updated stock status for 'Dune'.");
    } else {
        println!("'Dune' not found or stock status already up to date.");
    }

    Ok(())
}
```

The above code does the following:

- Load the connection string from the `.env` file.
- Connect to the Neon database using a secure TLS connection.
- Use a `client.execute` method to update the stock status of the book 'Dune' to `true`.

Run the script using the following command:

```bash
cargo run --bin update_data
```

After running this script, you can run `read_data` again to verify that the row was updated.

```bash
cargo run --bin read_data
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 3, Title: 1984, Author: George Orwell, Year: 1949, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the stock status for 'Dune' has been updated to `true`.

### Delete data

In your `src` directory, create a file named `delete_data.rs`. This script deletes the book '1984' from the `books` table.

**postgres (sync)**

```rust filename="src/delete_data.rs"
use dotenvy::dotenv;
use postgres::Client;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::env;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv()?;
    let conn_string = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());

    let mut client = Client::connect(&conn_string, connector)?;
    println!("Connection established");

    // Delete a data row from the table
    let deleted_rows = client.execute(
        "DELETE FROM books WHERE title = $1",
        &[&"1984"],
    )?;

    if deleted_rows > 0 {
        println!("Deleted the book '1984' from the table.");
    } else {
        println!("'1984' not found in the table.");
    }

    Ok(())
}
```

**tokio-postgres (async)**

```rust filename="src/delete_data.rs"
use dotenvy::dotenv;
use openssl::ssl::{SslConnector, SslMethod};
use postgres_openssl::MakeTlsConnector;
use std::env;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    dotenv()?;
    let conn_string = env::var("DATABASE_URL")?;

    let builder = SslConnector::builder(SslMethod::tls())?;
    let connector = MakeTlsConnector::new(builder.build());

    let (client, connection) = tokio_postgres::connect(&conn_string, connector).await?;
    println!("Connection established");

    tokio::spawn(async move {
        if let Err(e) = connection.await {
            eprintln!("connection error: {}", e);
        }
    });

    // Delete a data row from the table
    let deleted_rows = client.execute(
        "DELETE FROM books WHERE title = $1",
        &[&"1984"],
    ).await?;

    if deleted_rows > 0 {
        println!("Deleted the book '1984' from the table.");
    } else {
        println!("'1984' not found in the table.");
    }

    Ok(())
}
```

The above code does the following:

- Load the connection string from the `.env` file.
- Connect to the Neon database using a secure TLS connection.
- Use a `client.execute` method to delete the book '1984' from the `books` table.

Run the script using the following command:

```bash
cargo run --bin delete_data
```

After running this script, run `read_data` again to verify that the row was deleted.

```bash
cargo run --bin read_data
```

When the code runs successfully, it produces the following output:

```text filename="Output"
Connection established

--- Book Library ---
ID: 2, Title: The Hobbit, Author: J.R.R. Tolkien, Year: 1937, In Stock: true
ID: 1, Title: The Catcher in the Rye, Author: J.D. Salinger, Year: 1951, In Stock: true
ID: 4, Title: Dune, Author: Frank Herbert, Year: 1965, In Stock: true
--------------------
```

> You can see that the book '1984' has been successfully deleted from the `books` table.

## Resources

- [The Rust Programming Language Book](https://doc.rust-lang.org/book/)
- [rust-postgres crate documentation](https://docs.rs/postgres/latest/postgres/)
- [tokio-postgres crate documentation](https://docs.rs/tokio-postgres/latest/tokio_postgres/)
- [Tokio async runtime](https://tokio.rs/)

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/scale-to-zero-guide.md) ---

> Summary: Scale to Zero for Neon computes suspends idle compute instances after a configurable inactivity period, defaulting to 5 minutes, to eliminate costs when the database is unused. Use this page to enable, disable, or tune the suspend threshold per compute or project-wide. Disabling scale to zero requires a paid plan, and threshold adjustment is available only on the Scale plan. Computes larger than 16 CU are always active and cannot scale to zero. When Neon acts as a logical replication publisher, a connected subscriber also prevents suspension.

# Configuring Scale to Zero for Neon computes

Learn how to configure Neon's Scale to Zero feature

Last updated: 2026-10-09

Neon's [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero) feature controls whether a Neon compute transitions to an idle state due to inactivity. For example, if scale to zero is enabled, your compute will transition to an idle state after it's been inactive for 5 minutes. Neon's paid plans allow you to disable scale to zero to keep your compute active. On the Scale plan, you can configure the scale to zero threshold.

**Important:** If you disable scale to zero entirely, your compute will remain active, and you will have to manually restart your compute to pick up the latest updates to Neon's compute images. Neon typically releases compute-related updates weekly. Not all releases contain critical updates, but a weekly compute restart is recommended to ensure that you do not miss anything important. For how to restart a compute, see [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

This guide demonstrates how to configure the scale to zero setting for a new project, for an existing project, or for an individual compute.

### Scale to zero limits

Paid plans permit disabling scale to zero. On the Scale plan, you can configure the scale to zero threshold.

| Plan      | Scale to zero after                  | Can be disabled? |
| :-------- | :----------------------------------- | :--------------- |
| Free plan | 5 minutes                            |                  |
| Launch    | 5 minutes                            | ✓                |
| Scale     | Configurable (1 minute to always on) | ✓                |

**Note:** Scale to zero is only available for computes up to 16 CU in size. Computes larger than 16 CU remain always active to ensure best performance.

## Enable or disable scale to zero

To enable or disable scale to zero:

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Click **Edit**.
4. Enable or disable the scale to zero setting, and save your selection.

> Disabling scale to zero is only supported on paid plans.

### Configuring the scale to zero time

On the Scale plan, you can configure "Scale to zero after" time to increase or decrease the amount of time after which a compute scales to zero. For example, decreasing the time to 1 minute means that your compute will scale to zero faster (after the compute is inactive for 1 minute), or increasing the value to an hour means that your compute will only scale to zero after being inactive for an hour.

Initial configuration of the scale to zero time is only supported via an [Update compute endpoint](https://neon.com/docs/reference/api/endpoints/update-project-endpoint) or [Update project](https://neon.com/docs/reference/api/projects/update-project) API call. Use the `Update compute endpoint` API to change the setting for an existing compute. The `Update project` API sets a default for all compute endpoints created in the future; it does not change the configuration of existing computes.

**Update compute endpoint**

```bash
# change the setting for an existing compute

curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project-id}/endpoints/{endpoint-id} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "endpoint": {
    "suspend_timeout_seconds": 60
  }
}
'
```

**Update project**

```bash
# Change the default setting for computes created in the future

curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/{project-id} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "project": {
    "default_endpoint_settings": {
      "suspend_timeout_seconds": 60
    }
  }
}
'
```

**API parameters:**

- The `suspend_timeout_seconds` setting is defined in seconds
- The default setting is 300 seconds (5 minutes)
- The minimum setting is 60 seconds
- The maximum setting is 604800 seconds (1 week)
- You must supply an [API key](https://neon.com/docs/manage/api-keys), your [project ID](https://neon.com/docs/reference/glossary#project-id), and the [endpoint ID](https://neon.com/docs/reference/glossary#endpoint-id)

After configuring a non-default value via the Neon API, you'll be able to adjust the setting via the console. Setting a non-default value makes the time selector control visible on the **Edit compute** modal.

![Scale to zero control on the Edit compute page](https://neon.com/docs/guides/scale_to_zero_setting.png)

### Configure the scale to zero default

Configuring the scale to zero setting in your project's settings sets the project's default, which is applied to all computes created from that point forward. The scale to zero settings for existing computes are unaffected. See [Change your project's default compute settings](https://neon.com/docs/manage/projects#change-your-projects-default-compute-settings) for more info about compute defaults.

To configure the scale to zero default for an existing project:

1. Select a project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres** and find the **Compute defaults** section.
4. Select **Modify defaults**.
5. Enable or disable the scale to zero setting, and save your selection.

## Monitor scale to zero

You can monitor scale to zero on the **Branches** page in the Neon Console. A compute reports either an **Active** or **Idle** status.

![Compute status](https://neon.com/docs/introduction/compute_state.png)

You can also see each branch's compute status and when it was last active on the **Branches** page.

User actions that activate an idle compute include [connecting from a client such as psql](https://neon.com/docs/connect/query-with-psql-editor), running a query on your database from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), or accessing the compute via the [Neon API](https://neon.com/docs/reference/api).

**Info:** The Neon API includes a [Start endpoint](https://neon.com/docs/reference/api/endpoints/start-project-endpoint) method for the specific purpose of activating and suspending a compute.

You can try any of these methods and watch the status of your compute as it transitions from an **Idle** to an **Active** state.

## Logical replication and scale to zero

When you [replicate data from Neon](https://neon.com/docs/guides/logical-replication-guide#replicate-data-from-neon) (Neon as the publisher), a connected logical replication subscriber keeps the database active, so the compute will not scale to zero and you will have ongoing compute usage. This applies only when Neon is the publisher, not when replicating data into Neon from an external source. For details and other replication notices, see [Logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices).

## Session context considerations

When a compute suspends and later restarts, the [session context](https://neon.com/docs/reference/compatibility#session-context) resets. This includes in-memory statistics, temporary tables, prepared statements, and autovacuum thresholds, among other session-specific data. If your workflow requires persistent session data, consider disabling scale to zero on a paid plan to keep your compute active continuously. On the Free plan, scale to zero is always enabled and automatically suspends your compute after 5 minutes of inactivity.

--- [Document source](https://neon.com/docs/guides/schema-diff-tutorial.md) ---

> Summary: Schema Diff tutorial for comparing a feature branch against a production branch in Neon using a side-by-side, GitHub-style diff. Available from the Console, the `neon branches schema-diff` CLI command, or the compare-schema REST API. Use this page when you need a concrete end-to-end example: create a database on production, branch it to a dev branch, alter the schema, then run Schema Diff to see exactly which tables, sequences, and constraints differ before merging or restoring.

# Schema diff tutorial

Step-by-step guide showing you how to compare two development branches using Schema Diff

Last updated: 2026-10-09

In this guide we will create an initial schema on a new database called `people` on our `production` branch. We'll then create a development branch called `feature/address`, following one possible convention for naming feature branches. After making schema changes on `feature/address`, we'll use the **Schema Diff** tool on the **Branches** page to get a side-by-side, GitHub-style visual comparison between the `feature/address` development branch and `production`.

## Before you start

To complete this tutorial, you'll need:

- A Neon account. Sign up [here](https://neon.com/docs/get-started/signing-up).
- To interact with your Neon database from the command line:
  - Install the [Neon CLI](https://neon.com/docs/cli/install)
  - Download and install the [psql](https://www.postgresql.org/download/) client

## Create the Initial Schema

First, create a new database called `people` on the `production` branch and add some sample data to it.

**Console**

1. Create the database.

   In the **Neon Console**, go to **Postgres database** > **Databases** → **Add database**. Make sure your `production` branch is selected, then create the new database called `people`.

2. Add the schema.

   Go to **Postgres database** > **SQL Editor**, enter the following SQL statement and click **Run** to apply.

   ```sql
   CREATE TABLE person (
       id SERIAL PRIMARY KEY,
       name TEXT NOT NULL,
       email TEXT UNIQUE NOT NULL
   );
   ```

**CLI**

1. Create the database.

   Use the following CLI command to create the `people` database.

   ```bash
   neon databases create --name people
   ```

   **Note:**

   If you have multiple projects, include `--project-id`. Or set the project context so you don't have to specify project id in every command. Example:

   ```bash
   neon set-context --project-id empty-glade-66712572
   ```

   You can find your project ID on the **Settings** page in the Neon Console.

2. Copy your connection string:

   ```bash
   neon connection-string --database-name people
   ```

3. Connect to the `people` database with psql:

   ```bash
   psql 'postgresql://neondb_owner:*********@ep-crimson-frost-a5i6p18z.us-east-2.aws.neon.tech/people?sslmode=require&channel_binding=require'
   ```

4. Create the schema:

   ```sql
   CREATE TABLE person (
       id SERIAL PRIMARY KEY,
       name TEXT NOT NULL,
       email TEXT UNIQUE NOT NULL
   );
   ```

**API**

1. Use the [Create database](https://neon.com/docs/reference/api/branches/create-project-branch-database) API to create the `people` database, specifying the `project_id`, `branch_id`, database `name`, and database `owner_name` in the API call.

   ```bash
   curl --request POST \
   --url https://console.neon.tech/api/v2/projects/royal-band-06902338/branches/br-bitter-bird-a56n6lh4/databases \
   --header 'accept: application/json' \
   --header 'authorization: Bearer $NEON_API_KEY' \
   --header 'content-type: application/json' \
   --data '{
      "database": {
         "name": "people",
         "owner_name": "alex"
      }
   }'
   ```

2. Retrieve your database connection string using [Get connection URI](https://neon.com/docs/reference/api/projects/get-connection-uri) endpoint, specifying the required `project_id`, `branch_id`, `database_name`, and `role_name` parameters.

   ```bash
   curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/royal-band-06902338/connection_uri?branch_id=br-bitter-bird-a56n6lh4&database_name=people&role_name=alex' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
   ```

   The API call will return an connection string similar to this one:

   ```json
   {
     "uri": "postgresql://alex:*********@ep-green-surf-a5yaumj3-pooler.us-east-2.aws.neon.tech/people?sslmode=require&channel_binding=require"
   }
   ```

3. Connect to the `people` database with `psql`:

   ```bash
   psql 'postgresql://alex:*********@ep-green-surf-a5yaumj3-pooler.us-east-2.aws.neon.tech/people?sslmode=require&channel_binding=require'
   ```

4. Create the schema:

   ```sql
   CREATE TABLE person (
       id SERIAL PRIMARY KEY,
       name TEXT NOT NULL,
       email TEXT UNIQUE NOT NULL
   );
   ```

## Create a development branch

Create a new development branch off of `production`. This branch will be an exact, isolated copy of `production`.

For the purposes of this tutorial, name the branch `feature/address`, which could work as a good convention for creating isolated branches for working on specific features.

**Console**

1. Create the development branch

   On the **Branches** page, click **Create Branch**, making sure of the following:

   - Select `production` as the parent branch.
   - Name the branch `feature/address`.

2. Verify the schema on your new branch

   From the **SQL Editor**, use the meta-command `\d person` to inspect the schema of the `person` table. Make sure that the `people` database on the branch `feature/address` is selected.

   ![use metacommand to inspect schema](https://neon.com/docs/guides/schema_diff_d_metacommand.png)

**CLI**

1. Create the branch

   If you're still in `psql`, exit using `\q`.

   Using the Neon CLI, create the development branch. Include `--project-id` if you have multiple projects.

   ```bash
   neon branches create --name feature/address --parent production
   ```

2. Verify the schema

   To verify that this branch includes the initial schema created on `production`, connect to `feature/address`, then view the `person` table.

   1. Get the connection string for the `people` database on branch `feature/address` using the CLI.

      ```bash
      neon connection-string feature/address --database-name people
      ```

      This gives you the connection string which you can then copy.

      ```bash
      postgresql://neondb_owner:*********@ep-hidden-rain-a5pe72oi.us-east-2.aws.neon.tech/people?sslmode=require&channel_binding=require
      ```

   2. Connect to `people` using psql.

      ```bash
      psql 'postgresql://neondb_owner:*********@ep-hidden-rain-a5pe72oi.us-east-2.aws.neon.tech/people?sslmode=require&channel_binding=require'
      ```

   3. View the schema for the `person` table we created earlier.

      ```bash
      \d person
      ```

      Which shows you the schema:

      ```bash
      Table "public.person"
      Column |  Type   | Collation | Nullable |              Default
      --------+---------+-----------+----------+------------------------------------
      id     | integer |           | not null | nextval('person_id_seq'::regclass)
      name   | text    |           | not null |
      email  | text    |           | not null |
      Indexes:
          "person_pkey" PRIMARY KEY, btree (id)
          "person_email_key" UNIQUE CONSTRAINT, btree (email)
      ```

      You can do the same thing for your `production` branch and get identical results.

**API**

Using the [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch) API, create a development branch named `feature/address`. You'll need to specify the `project_id`, `parent_id`, branch `name`, and add a `read_write` compute (you need a compute to connect to the branch).

```bash
curl --request POST \
--url https://console.neon.tech/api/v2/projects/royal-band-06902338/branches \
--header 'accept: application/json' \
--header 'authorization: Bearer $NEON_API_KEY' \
--header 'content-type: application/json' \
--data '{
   "branch": {
      "name": "feature/address",
      "parent_id": "br-bitter-bird-a56n6lh4"
   },
   "endpoints": [
      {
      "type": "read_write"
      }
   ]
}'
```

## Update schema on a dev branch

Let's introduce some differences between the two branches. Add a new table to store addresses on the `feature/address` branch.

**Console**

In the **SQL Editor**, make sure you select `feature/address` as the branch and `people` as the database.

Enter this SQL statement to create a new `address` table.

```sql
CREATE TABLE address (
    id SERIAL PRIMARY KEY,
    person_id INTEGER NOT NULL,
    street TEXT NOT NULL,
    city TEXT NOT NULL,
    state TEXT NOT NULL,
    zip_code TEXT NOT NULL,
    FOREIGN KEY (person_id) REFERENCES person(id)
);
```

**CLI**

1. Connect to your `feature/address` branch

   By adding `--psql` to the CLI command, you can start the `psql` connection without having to enter the connection string directly:

   ```bash
   neon connection-string feature/address --database-name people --psql
   ```

   Response:

   ```bash
   Connecting to the database; launching psql...
   psql (16.1, server 16.2)
   SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
   Type "help" for help.

   people=>
   ```

2. Add a new address table

   ```sql
   CREATE TABLE address (
       id SERIAL PRIMARY KEY,
       person_id INTEGER NOT NULL,
       street TEXT NOT NULL,
       city TEXT NOT NULL,
       state TEXT NOT NULL,
       zip_code TEXT NOT NULL,
       FOREIGN KEY (person_id) REFERENCES person(id)
   );
   ```

**API**

1. Retrieve the database connection string for the `feature/address` branch using [Get connection URI](https://neon.com/docs/reference/api/projects/get-connection-uri) endpoint:

   ```bash
   curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/royal-band-06902338/connection_uri?branch_id=br-mute-dew-a5930esi&database_name=people&role_name=alex' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
   ```

   The API call will return an connection string similar to this one:

   ```json
   {
     "uri": "postgresql://alex:*********@ep-hidden-sun-a5de9i5h-pooler.us-east-2.aws.neon.tech/people?sslmode=require&channel_binding=require"
   }
   ```

2. Connect to the `people` database on the `feature/address` branch with `psql`:

   ```bash
   psql 'postgresql://alex:*********@ep-hidden-sun-a5de9i5h-pooler.us-east-2.aws.neon.tech/people?sslmode=require&channel_binding=require'
   ```

3. Add a new `address` table.

   ```sql
   CREATE TABLE address (
       id SERIAL PRIMARY KEY,
       person_id INTEGER NOT NULL,
       street TEXT NOT NULL,
       city TEXT NOT NULL,
       state TEXT NOT NULL,
       zip_code TEXT NOT NULL,
       FOREIGN KEY (person_id) REFERENCES person(id)
   );
   ```

## View the schema differences

Now that you have some differences between your branches, you can view the schema differences.

**Console**

1. Click on `feature/address` to open the detailed view, then click **Schema diff**.

   ![select branches for schema diff](https://neon.com/docs/guides/schema_diff_make_selection.png)

2. Make sure you select `people` as the database and then click **Compare**.

   ![schema diff results](https://neon.com/docs/guides/schema_diff_result.png)

You will see the schema differences between `feature/address` and its parent `production`, including the new address table that we added to the `feature/address` branch.

You can also launch Schema Diff from the **Restore** page, usually as part of verifying schemas before you restore a branch to its own or another branch's history. See [Instant restore](https://neon.com/docs/guides/branch-restore) for more info.

**CLI**

Compare the schema of `feature/address` to its parent branch using the `schema-diff` command.

```bash
neon branches schema-diff production feature/address --database people
```

The result shows a comparison between the `feature/address` branch and its parent branch for the database `people`. The output indicates that the `address` table and its related sequences and constraints have been added in the `feature/address` branch but are not present in its parent branch `production`.

```diff
--- Database: people (Branch: br-falling-dust-a5bakdqt)
+++ Database: people (Branch: br-morning-heart-a5ltt10i)
@@ -20,8 +20,46 @@

 SET default_table_access_method = heap;

 --
+-- Name: address; Type: TABLE; Schema: public; Owner: neondb_owner
+--
+
+CREATE TABLE public.address (
+    id integer NOT NULL,
+    person_id integer NOT NULL,
+    street text NOT NULL,
+    city text NOT NULL,
+    state text NOT NULL,
+    zip_code text NOT NULL
+);
+
+
+ALTER TABLE public.address OWNER TO neondb_owner;
+
+...
```

**API**

Compare the schema of the `feature/address` branch to its parent branch using the `compare-schema` API.

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/royal-band-06902338/branches/br-mute-dew-a5930esi/compare_schema?base_branch_id=br-bitter-bird-a56n6lh4&db_name=neondb' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' | jq -r '.diff'
```

| Parameter          | Description                                                                              | Required | Example                   |
| ------------------ | ---------------------------------------------------------------------------------------- | -------- | ------------------------- |
| `<project_id>`     | The ID of your Neon project.                                                             | Yes      | `royal-band-06902338`     |
| `<branch_id>`      | The ID of the target branch to compare.                                                  | Yes      | `br-mute-dew-a5930esi`    |
| `<base_branch_id>` | The ID of the base branch for comparison (the parent branch in this case).               | Yes      | `br-bitter-bird-a56n6lh4` |
| `<db_name>`        | The name of the database in the target branch.                                           | Yes      | `people`                  |
| `Authorization`    | Bearer token for API access (your [Neon API key](https://neon.com/docs/manage/api-keys)) | Yes      | `$NEON_API_KEY`           |

**Note:** The optional `jq -r '.diff'` command extracts the diff field from the JSON response and outputs it as plain text to make it easier to read. This command would not be necessary when using the endpoint programmatically.

The result shows a comparison between the `feature/address` branch and its parent branch for the database `people`. The output indicates that the `address` table and its related sequences and constraints have been added to the `feature/address` branch but are not present in its parent branch.

```diff
--- a/people
+++ b/people
@@ -21,6 +21,44 @@
 SET default_table_access_method = heap;

 --
+-- Name: address; Type: TABLE; Schema: public; Owner: alex
+--
+
+CREATE TABLE public.address (
+    id integer NOT NULL,
+    person_id integer NOT NULL,
+    street text NOT NULL,
+    city text NOT NULL,
+    state text NOT NULL,
+    zip_code text NOT NULL
+);
+
+
+ALTER TABLE public.address OWNER TO alex;
+
+--
+-- Name: address_id_seq; Type: SEQUENCE; Schema: public; Owner: alex
+--
+
+CREATE SEQUENCE public.address_id_seq
+    AS integer
+    START WITH 1
+    INCREMENT BY 1
+    NO MINVALUE
+    NO MAXVALUE
+    CACHE 1;
+
+
+ALTER SEQUENCE public.address_id_seq OWNER TO alex;
+
+--
+-- Name: address_id_seq; Type: SEQUENCE OWNED BY; Schema: public; Owner: alex
+--
+
+ALTER SEQUENCE public.address_id_seq OWNED BY public.address.id;
+
+
+--
 -- Name: person; Type: TABLE; Schema: public; Owner: alex
 --

@@ -56,6 +94,13 @@


 --
+-- Name: address id; Type: DEFAULT; Schema: public; Owner: alex
+--
+
+ALTER TABLE ONLY public.address ALTER COLUMN id SET DEFAULT nextval('public.address_id_seq'::regclass);
+
+
+--
 -- Name: person id; Type: DEFAULT; Schema: public; Owner: alex
 --

@@ -63,6 +108,14 @@


 --
+-- Name: address address_pkey; Type: CONSTRAINT; Schema: public; Owner: alex
+--
+
+ALTER TABLE ONLY public.address
+    ADD CONSTRAINT address_pkey PRIMARY KEY (id);
+
+
+--
 -- Name: person person_email_key; Type: CONSTRAINT; Schema: public; Owner: alex
 --

@@ -79,6 +132,14 @@


 --
+-- Name: address address_person_id_fkey; Type: FK CONSTRAINT; Schema: public; Owner: alex
+--
+
+ALTER TABLE ONLY public.address
+    ADD CONSTRAINT address_person_id_fkey FOREIGN KEY (person_id) REFERENCES public.person(id);
+
+
+--
 -- Name: DEFAULT PRIVILEGES FOR SEQUENCES; Type: DEFAULT ACL; Schema: public; Owner: cloud_admin
 --
```

--- [Document source](https://neon.com/docs/guides/schema-diff.md) ---

> Summary: Schema Diff is Neon's SQL schema comparison tool that shows differences between any two branches side-by-side. Access it from the Neon Console, the `neon branches schema-diff` CLI command, or the `compare_schema` API endpoint, which supports LSN and timestamp parameters. Use it to verify intended schema changes before a reset-from-parent, branch restore, or migration merge. Also useful for automating schema checks in CI/CD pipelines or AI agent workflows. A Schema Diff GitHub Action is available to post diff comments on pull requests.

# Schema diff

Learn how to use Neon's Schema Diff tool to compare branches of your database

Last updated: 2026-07-15

Neon's Schema Diff tool lets you compare an SQL script of the schemas for two selected branches in a side-by-side view (or line-by-line on mobile devices).

## How Schema Diff works

Schema Diff is available in the Neon Console for use in two ways:

- Compare a branch's schema to its parent
- Compare selected branches during an instant restore operation

You can also use the `branches schema-diff` command in the Neon CLI or `compare-schema` endpoint in the Neon API to effect a variety of comparisons.

### Compare to parent

In the detailed view for any child branch, you can check the schema differences between the selected branch and its parent. Use this view to verify the state of these schemas before you [Reset from parent](https://neon.com/docs/guides/reset-from-parent).

### Compare to another branch's history

Built into the Time Travel assist editor, you can use Schema Diff to help when restoring branches, letting you compare states of your branch against its own or another branch's history before you complete a [branch restore](https://neon.com/docs/guides/branch-restore) operation.

### Comparisons using the CLI or API

You can use the Neon CLI to compare a branch to any point in its own or any other branch's history. The `branches schema-diff` command offers full flexibility for any type of schema comparison: between a branch and its parent, a branch and its earlier state, or a branch to the head or prior state of another branch. The Neon API provides a `compare-schema` endpoint that lets you compare schemas between Neon branches programmatically, supporting CI/CD automation and AI agent use cases.

### Practical Applications

- **Pre-Migration Reviews**: Before migrating schemas from a development branch into main, use Schema Diff to ensure only intended schema changes are applied.
- **Audit Changes**: Historically compare schema changes to understand the evolution of your database structure.
- **Consistency Checks**: Ensure environment consistency by comparing schemas across development, staging, and production branches.
- **Automation**: Integrate schema-diff into CI/CD pipelines to automatically compare schemas during deployments.
- **AI Agents**: Enable AI agents to retrieve schema differences programmatically to support agent-driven database migrations.

## How to Use Schema Diff

You can launch the Schema Diff viewer from the **Branches** and **Restore** pages in the Neon Console.

### From the Branches page

Open the detailed view for the child branch whose schema you want to inspect. Open the three-dot menu and select **Compare to parent**.

![Schema diff from branches page](https://neon.com/docs/guides/schema_diff_compare_parent.png)

### From the Restore page

Just like with [Time Travel Assist](https://neon.com/docs/guides/branch-restore#using-time-travel-assist), your first step is to choose the branch you want to restore, then choose where you want to restore from: **From history** (its own history) or **From another branch** (from another branch's history).

Click the **Schema Diff** button, verify that your selections are correct, then click **Compare**.

The two-pane view shows the schema for both your target and your selected branches.

![schema diff results](https://neon.com/docs/guides/schema_diff_result.png)

### Using the Neon CLI

You can use the Neon CLI to:

- Compare the latest schemas of any two branches
- Compare against a specific point in its own or another branch's history

For a git-style unified diff between two branches, you can also use the top-level [`neon diff`](https://neon.com/docs/cli/diff) shortcut.

Use the `schema-diff` subcommand from the `branches` command:

```bash
neon branches schema-diff [base-branch] [compare-source[@(timestamp|lsn)]]
```

The operation will compare a selected branch (`[compare-source]`) against the latest (head) of your base branch (`[base-branch]`). For example, if you want to compare recent changes you made to your development branch `development` against your production branch `main`, identify `main` as your base branch and `development` as your compare-source.

```bash
neon branches schema-diff production development
```

You have a few options here:

- Append a timestamp or LSN to compare to a specific point in `development` branch's history.
- If you are regularly comparing development branches against `production`, include `production` in your `set-context` file. You can then leave out the [base-branch] from the command.
- Use aliases to shorten the command.
- Include `--database` to reduce the diff to a single database. If you don't specify a database, the diff will include all databases on the branch.

Here is the same command using aliases, with `production` included in `set-context`, pointing to an LSN from `development` branch's history, and limiting the diff to the database `people`:

```bash
neon branch sd development@0/123456 --db people
```

To find out what other comparisons you can make, see [Neon CLI commands — branches](https://neon.com/docs/cli/branches#schema-diff) for full documentation of the command.

### Using the Neon API

The [compare_schema](https://neon.com/docs/reference/api/branches/get-project-branch-schema-comparison) endpoint lets you compare schemas between Neon branches to track schema changes. The response highlights differences in a `diff` format, making it a useful tool for integrating schema checks into CI/CD workflows.

Another use case for schema diff via the Neon API is AI agent-driven workflows. The `compare_schema` endpoint allows AI agents to programmatically retrieve schema differences by comparing two branches.

To compare schemas between two branches, you can cURL command similar to the one below, which compares the schema of a target branch to the schema of a base branch. For example, the target branch could be a development branch where a schema change was applied, and the base branch could be the parent of the development branch. By comparing the two, you can inspect the changes that have been made on the development branch.

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/wispy-butterfly-25042691/branches/br-rough-boat-a54bs9yb/compare_schema?base_branch_id=br-royal-star-a54kykl2&db_name=neondb' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' | jq -r '.diff'
```

The `compare_schema` endpoint supports the following parameters:

| Parameter          | Description                                                                              | Required | Example                    |
| ------------------ | ---------------------------------------------------------------------------------------- | -------- | -------------------------- |
| `<project_id>`     | The ID of your Neon project.                                                             | Yes      | `wispy-butterfly-25042691` |
| `<branch_id>`      | The ID of the target branch to compare (the branch with the modified schema).            | Yes      | `br-rough-boat-a54bs9yb`   |
| `<base_branch_id>` | The ID of the base branch for comparison.                                                | Yes      | `br-royal-star-a54kykl2`   |
| `<db_name>`        | The name of the database in the target branch.                                           | Yes      | `neondb`                   |
| `lsn`              | The LSN on the target branch for which the schema is retrieved.                          | No       | `0/1EC5378`                |
| `timestamp`        | The point in time on the target branch for which the schema is retrieved.                | No       | `2022-11-30T20:09:48Z`     |
| `base_lsn`         | The LSN for the base branch schema.                                                      | No       | `0/2FC6321`                |
| `base_timestamp`   | The point in time for the base branch schema.                                            | No       | `2022-11-30T20:09:48Z`     |
| `Authorization`    | Bearer token for API access (your [Neon API key](https://neon.com/docs/manage/api-keys)) | Yes      | `$NEON_API_KEY`            |

**Note: notes**

- The optional `jq -r '.diff'` command appended to the example above extracts the diff field from the JSON response and outputs it as plain text to make it easier to read. This command is not  necessary when using the endpoint programmatically.
- `timestamp` or `lsn` / `base_timestamp` or `base_lsn` values can be used to compare schemas as they existed as a precise time or [LSN](https://neon.com/docs/reference/glossary#lsn).
- `timestamp` / `base_timestamp` values must be provided in [RFC 3339 format](https://tools.ietf.org/html/rfc3339#section-5.6) (Date and Time on the Internet: Timestamps - RFC 3339 specification for timestamp formats used in Internet protocols.).

Here's an example of the `compare_schema` diff output for the `neondb` database after comparing target branch `br-rough-boat-a54bs9yb` with the base branch `br-royal-star-a54kykl2`.

```diff
--- a/neondb
+++ b/neondb
@@ -27,7 +27,8 @@
 CREATE TABLE public.playing_with_neon (
     id integer NOT NULL,
     name text NOT NULL,
-    value real
+    value real,
+    created_at timestamp without time zone DEFAULT CURRENT_TIMESTAMP
 );
```

**Output explanation:**

- `-` (minus) identifies Lines that were removed from the base branch schema.
- `+` (plus) identifies lines that were added in the target branch schema.

In the example above, the `created_at` column was added to the `public.playing_with_neon` table on the target branch.

## Schema Diff GitHub Action

Neon supports a [Schema Diff GitHub Action](https://neon.com/docs/guides/branching-github-actions#schema-diff-action) that performs a database schema diff on specified Neon branches for each pull request and writes a comment to the pull request highlighting the schema differences.

This action supports workflows where schema changes are made on a branch. When you create or update a pull request containing schema changes, the action automatically generates a comment within the pull request. By including the schema diff as part of the comment, reviewers can easily assess the changes directly within the pull request.

To learn more, see the [Schema Diff GitHub Action](https://neon.com/docs/guides/branching-github-actions#schema-diff-action).

## Tutorial

For a step-by-step guide showing you how to compare two development branches using Schema Diff, see [Schema diff tutorial](https://neon.com/docs/guides/schema-diff-tutorial).

--- [Document source](https://neon.com/docs/guides/sequelize.md) ---

> Summary: Sequelize ORM integration with Lakebase Postgres walks through connecting a Node.js project, generating models with sequelize-cli, and running `npx sequelize db:migrate` to apply schema changes. Use this guide when you need to set up Sequelize migrations against a Lakebase Postgres database, including defining foreign key relationships and seeding data. A direct (non-pooled) connection string is required for migrations, as pooled connections via PgBouncer cause migration errors.

# Schema migration with Lakebase Postgres and Sequelize

Set up a database on Neon and run migrations for your Javascript project using Sequelize ORM

Last updated: 2026-09-16

[Sequelize](https://sequelize.org/) is a promise-based Node.js ORM that supports multiple relational databases. In this guide, we'll explore how to use `Sequelize` ORM with a Lakebase Postgres database in a JavaScript project.

We'll create a Node.js application, configure `Sequelize`, and show how to set up and run migrations with `Sequelize`.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your local machine. We'll use Node.js to build and test the application locally.

## Setting up your database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select an existing project or click the `New Project` button to create a new one.

### Retrieve your database connection string

You can find the connection string for your database by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

**Note:** Neon supports both direct and pooled database connection strings. You can find the connection string for your database by clicking the **Connect** button in the Console nav. A pooled connection string connects your application to the database via a PgBouncer connection pool, allowing for a higher number of concurrent connections. However, using a pooled connection string for migrations can be prone to errors. For this reason, we recommend using a direct (non-pooled) connection when performing migrations. For more information about direct and pooled connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Setting Up the Node application

### Create a new Node project

We'll create a simple catalog with API endpoints that query the database for authors and a list of their books. Run the following commands in your terminal to set up a new project using `Express.js`:

```bash
mkdir neon-sequelize-guide && cd neon-sequelize-guide
npm init -y && touch .env index.js
npm install express dotenv
```

Add the `DATABASE_URL` environment variable to the `.env` file, which you'll use to connect to your Neon database. Use the connection string that you obtained from the Neon Console earlier:

```bash
# .env
DATABASE_URL=NEON_DATABASE_CONNECTION_STRING
```

To use the `Sequelize` ORM to run queries, we need to install the `sequelize` package and the `pg` driver to connect to Postgres from Node.js. We also need to install the `sequelize-cli` package to manage data models and run migrations. Run the following commands to install the required packages:

```bash
npm install sequelize pg pg-hstore
npm install sequelize-cli --save-dev
```

### Configure Sequelize

Run the following command to initialize the `sequelize` configuration:

```bash
npx sequelize init
```

This command creates `config`, `migrations`, `models`, and `seeders` directories at the project root.

The `config` directory contains the `config.json` file, which holds the database configuration. We want to have the database URL read as an environment variable, so we replace it with a `config.js` file. Create a `config.js` file in your `config/` directory and add the following code:

```javascript
// config/config.js

const dotenv = require('dotenv');
dotenv.config();

module.exports = {
  development: {
    url: process.env.DATABASE_URL,
    dialect: 'postgres',
    dialectOptions: { ssl: { require: true } },
  },
};
```

To make the `sequelize` CLI aware of the path to the new configuration file, we need to create a `.sequelizerc` file at the project root and add the following code:

```javascript
// .sequelizerc

const path = require('path');

module.exports = {
  config: path.resolve('config', 'config.js'),
};
```

### Create models and set up migrations

We'll create an `Author` and a `Book` model to represent the tables in our database. Run the following commands to create the models:

```bash
npx sequelize model:generate --name Author --attributes name:string,bio:string
npx sequelize model:generate --name Book --attributes title:string
```

Sequelize creates a new file for each model in the `models/` directory and a corresponding migration file in the `migrations/` directory. Sequelize automatically adds an `id` field as the primary key for each model, and `createdAt` and `updatedAt` fields to track the creation and update times of each record.

We still need to define the relationships between the `Author` and `Book` models. Update the `book.js` file with the following code:

```javascript
// models/book.js

'use strict';
const { Model } = require('sequelize');

module.exports = (sequelize, DataTypes) => {
  class Book extends Model {
    static associate(models) {
      Book.belongsTo(models.Author, {
        foreignKey: 'authorId',
        as: 'author',
        onDelete: 'CASCADE',
      });
    }
  }
  Book.init(
    {
      title: { type: DataTypes.STRING, allowNull: false },
      authorId: { type: DataTypes.INTEGER, allowNull: false },
    },
    {
      sequelize,
      modelName: 'Book',
    }
  );
  return Book;
};
```

Sequelize does not automatically regenerate the migration files when you update the models. So, we need to manually update the migration files to add the foreign key constraint.

Update the migration file corresponding to the `Book` model with the following code:

```javascript
'use strict';
/** @type {import('sequelize-cli').Migration} */
module.exports = {
  async up(queryInterface, Sequelize) {
    await queryInterface.createTable('Books', {
      id: {
        allowNull: false,
        autoIncrement: true,
        primaryKey: true,
        type: Sequelize.INTEGER,
      },
      title: {
        type: Sequelize.STRING,
      },
      createdAt: {
        allowNull: false,
        type: Sequelize.DATE,
      },
      updatedAt: {
        allowNull: false,
        type: Sequelize.DATE,
      },
      authorId: {
        type: Sequelize.INTEGER,
        onDelete: 'CASCADE',
        references: {
          model: 'Authors',
          key: 'id',
        },
      },
    });
  },
  async down(queryInterface, Sequelize) {
    await queryInterface.dropTable('Books');
  },
};
```

Run the following command to apply the migrations and create the tables in the database:

```bash
npx sequelize db:migrate
```

If `Sequelize` successfully connects to the database and runs the migrations, you should see a success message in the terminal.

### Add sample data to the database

We'll add some sample data to the database using the `Sequelize` ORM. Create a new file named `seed.js` at the project root and add the following code:

```javascript
// seed.js

const { Sequelize, DataTypes } = require('sequelize');
const { config } = require('dotenv');

config();
if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL is not set');
}

const sequelize = new Sequelize(process.env.DATABASE_URL, {
  dialectOptions: {
    ssl: {
      require: true,
    },
  },
});

const Author = require('./models/author')(sequelize, DataTypes);
const Book = require('./models/book')(sequelize, DataTypes);

const seedDatabase = async () => {
  const author = await Author.create({
    name: 'J.K. Rowling',
    bio: 'The creator of the Harry Potter series',
  });
  await Book.create({ title: "Harry Potter and the Philosopher's Stone", authorId: author.id });
  await Book.create({ title: 'Harry Potter and the Chamber of Secrets', authorId: author.id });

  const author2 = await Author.create({
    name: 'J.R.R. Tolkien',
    bio: 'The creator of Middle-earth and author of The Lord of the Rings.',
  });
  await Book.create({ title: 'The Hobbit', authorId: author2.id });
  await Book.create({ title: 'The Fellowship of the Ring', authorId: author2.id });
  await Book.create({ title: 'The Two Towers', authorId: author2.id });
  await Book.create({ title: 'The Return of the King', authorId: author2.id });

  const author3 = await Author.create({
    name: 'George R.R. Martin',
    bio: 'The author of the epic fantasy series A Song of Ice and Fire.',
  });
  await Book.create({ title: 'A Game of Thrones', authorId: author3.id });
  await Book.create({ title: 'A Clash of Kings', authorId: author3.id });

  await sequelize.close();
};

seedDatabase();
```

Run the following command to seed the database with the sample data:

```bash
node seed.js
```

Sequelize will print logs to the terminal as it connects to the database and adds the sample data.

### Create API endpoints

Now that the database is set up and populated with data, we can implement the API to query the authors and their books. We'll use [Express](https://expressjs.com/), which is a minimal web application framework for Node.js.

Create an `index.js` file at the project root, and add the following code to set up your Express server:

```javascript
// index.js

const express = require('express');
const { Sequelize, DataTypes } = require('sequelize');
const { config } = require('dotenv');

config();
if (!process.env.DATABASE_URL) {
  throw new Error('DATABASE_URL is not set');
}

const sequelize = new Sequelize(process.env.DATABASE_URL, {
  dialectOptions: { ssl: { require: true } },
});

// Set up the models
const Author = require('./models/author')(sequelize, DataTypes);
const Book = require('./models/book')(sequelize, DataTypes);

// Create a new Express application
const app = express();
const port = process.env.PORT || 3000;

app.get('/', async (req, res) => {
  res.send('Hello World! This is a book catalog.');
});

app.get('/authors', async (req, res) => {
  try {
    const authors = await Author.findAll();
    res.json(authors);
  } catch (error) {
    console.error('Error fetching authors:', error);
    res.status(500).send('Error fetching authors');
  }
});

app.get('/books/:author_id', async (req, res) => {
  const authorId = parseInt(req.params.author_id);
  try {
    const books = await Book.findAll({
      where: {
        authorId: authorId,
      },
    });
    res.json(books);
  } catch (error) {
    console.error('Error fetching books for author:', error);
    res.status(500).send('Error fetching books for author');
  }
});

// Start the server
app.listen(port, () => {
  console.log(`Server running on http://localhost:${port}`);
});
```

This code sets up a simple API with two endpoints: `/authors` and `/books/:authorId`. The `/authors` endpoint returns a list of all the authors, and the `/books/:authorId` endpoint returns a list of books written by the specific author for the given `authorId`.

Run the application using the following command:

```bash
node index.js
```

This will start the server at `http://localhost:3000`. Navigate to `http://localhost:3000/authors` and `http://localhost:3000/books/1` in your browser to check that the API works as expected.

## Conclusion

In this guide, we set up a new Javascript project using `Express.js` and the `Sequelize` ORM, and connected it to a `Neon` Postgres database. We created a schema for the database, generated and ran migrations, and implemented API endpoints to query the database.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Migrations with Neon and Sequelize](https://github.com/neondatabase/guide-neon-sequelize): Run Neon database migrations using Sequelize

## Resources

For more information on the tools used in this guide, refer to the following resources:

- [Sequelize](https://sequelize.org/)
- [Express.js](https://expressjs.com/)

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/serverless-connection-pooling.md) ---

> Summary: Learn how to manage database connection lifecycles and prevent connection exhaustion when using Neon from highly elastic serverless platforms such as AWS Fargate, Google Cloud Run, Modal, and Vercel.

# Using Neon from highly elastic serverless platforms

Manage connection lifecycles and prevent connection exhaustion in highly elastic serverless environments

Last updated: 2026-09-16

Highly elastic serverless platforms such as AWS Fargate, Google Cloud Run, Modal, and Vercel can scale compute from zero to hundreds of concurrent instances within seconds. While Neon's [lakebase architecture](https://neon.com/docs/introduction/architecture-overview) is designed for dynamic workloads, rapidly scaling out hundreds of workers can overwhelm your database unless connection lifecycles and local pool sizes are carefully managed.

This guide explains how database connection protocols interact with serverless runtimes, provides strategies to prevent connection leaks during container suspension, and demonstrates how to implement safe, resilient connection pooling configurations.

## The problem with serverless and databases

To understand why serverless architectures require a specialized database connection strategy, it helps to understand how different cloud platforms handle concurrent traffic.

### The serverless connection storm

Traditional relational databases including PostgreSQL were designed under the assumption of persistent, long-lived connections from a static number of application servers. Each PostgreSQL connection spawns a dedicated backend process on the database host, consuming memory and CPU.

Serverless architectures completely invert these design assumptions by introducing three new behaviors that can overwhelm a database:

1. **Massive Fan-out:** Highly elastic serverless platforms can scale compute from zero to hundreds of concurrent instances within seconds to handle sudden spikes in traffic.
2. **Ephemeral lifecycles:** Containers are continuously provisioned, suspended, and terminated as traffic fluctuates, leading to severe connection churn.
3. **High latency overhead:** Establishing a standard Postgres connection over TCP requires a TCP handshake, TLS negotiation, authentication, and backend process initialization, which typically takes **50 to 100 milliseconds** per request.

Without proper pooling and lifecycle management, this behavior can quickly exhaust your database's connection capacity and degrade application performance.

### How modern platforms handle parallel requests

To mitigate connection churn and cold starts, serverless platforms have evolved. They generally handle bursts of parallel requests in one of two ways, and your database pooling strategy depends entirely on which model your platform uses:

#### Multi request concurrency (Google Cloud Run, AWS Fargate, Vercel Fluid Compute, Modal Functions)

These platforms allow a single container instance to process multiple requests or tasks concurrently inside the same memory space using async threads or runtime loops.

If 10 parallel requests hit a single container, they can safely share a single global, client-side TCP connection pool. This drops query latency to near zero on subsequent requests without overwhelming the database.

#### Single request isolation (AWS Lambda)

By default, traditional serverless functions enforce strict isolation, executing only one request or task per instance at any given millisecond.

If 10 parallel requests arrive, the platform instantly spins up 10 separate instances. By default, most standard database clients automatically initialize a local connection pool (typically 5 to 10 connections) out of the box. Unless optimized, these 10 instances will attempt to open up to 100 total database connections, causing a sudden connection spike that risks immediate database exhaustion.

### Choosing your connection strategy

#### The HTTP Driver (For single request isolation)

If you are deploying to strictly ephemeral or single-request environments like AWS Lambda, traditional client-side connection pooling can cause "zombie" connections when instances are abruptly frozen or destroyed.

The workaround is to use HTTP-based drivers like [`@neondatabase/serverless`](https://neon.com/docs/serverless/serverless-driver). These skip the heavy TCP/TLS handshake entirely, reducing connection setup from ~8 network roundtrips to ~3, making it safe to open and close connections on every single invocation without overloading the database.

#### The safe pooling strategy (For multi request concurrency)

If you are using a concurrent platform like Cloud Run, Fargate, Vercel Fluid Compute, or Modal, you _should_ use a traditional client-side TCP connection pool. You can initialize the database client globally at container startup to reuse it across hundreds of subsequent requests.

To safely throttle your database connection count when these platforms inevitably scale out to hundreds of worker instances globally, you can restrict the max pool size per container instance (often to a small number).

## Why container suspension leaks connections

In standard server environments, database connection pools cleanly close idle connections using internal background timers. However, in serverless environments, **container suspension introduces a connection leak blind spot**.

When a serverless instance becomes idle, the platform's orchestration layer suspends the container in memory. During suspension:

- The container's CPU allocation is paused.
- Internal client-side timers (such as `idleTimeoutMillis` in Node.js or pool cleanup threads in Python) **stop executing**.
- Because these timers cannot run, the client-side pooler never closes idle connections.
- The physical TCP socket remains open on the database or proxy side until either the container is fully terminated by the platform or the server-side idle timeout closes the connection.

During a traffic burst or a new application deployment, this state of suspension can cause "phantom" connection accumulation, where hundreds of inactive containers hold open sockets, blocking new instances from connecting.

## The math of serverless connection pooling

To manage connections effectively, you must coordinate client-side pool sizes with your platform's concurrency limits.

The total number of database connections attempted during a peak traffic event is determined by:

```bash
Total Connections = C × P
```

Where:

- C is the number of active, concurrent containers/functions.
- P is the client-side pool size configured inside each container.

### Comparing connection footprints by compute model

| Compute model               | Concurrent containers (C) | Local pool size (P) | Total pool clients | Key Risk                                                  |
| :-------------------------- | :------------------------ | :------------------ | :----------------- | :-------------------------------------------------------- |
| **Monolithic Server**       | 5                         | 20                  | 100                | Static, easily predictable.                               |
| **Unconfigured Serverless** | 300                       | 10                  | **3,000**          | Instantly exhausts `max_connections` or PgBouncer limits. |
| **Optimized Serverless**    | 300                       | 1                   | **300**            | Clean execution; matches live concurrency.                |

To support massive serverless scale-out, keep your client-side pool sizes small (1–2 connections per container) and rely on Neon's built-in PgBouncer pooling to multiplex traffic to Postgres.

## Best practices for serverless connection pooling

### Always use Neon's pooled endpoint

Neon provides built-in connection pooling through PgBouncer in transaction mode. The pooled endpoint accepts up to **10,000 concurrent client connections** and multiplexes them into a smaller number of actual Postgres connections.

Use the pooled connection string with `-pooler` in the hostname for all your serverless app traffic:

![Pooled Connection String](https://neon.com/docs/connect/connect_to_branch_modal.png)

> Ensure **Connection pooling** is enabled when you copy the connection string from the Neon Console.

```text
# App traffic: use the pooled endpoint
DATABASE_URL="postgresql://user:pass@ep-cool-rain-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require"
```

Reserve the direct connection string no `-pooler` suffix, for administrative tasks that need session-level state, such as database migrations (e.g., `prisma migrate dev` or `drizzle-kit push`) or `pg_dump`:

```text
# Migrations only: direct Postgres connection
DIRECT_URL="postgresql://user:pass@ep-cool-rain-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require"
```

Checkout the [Connection pooling](https://neon.com/docs/connect/connection-pooling) guide for a deeper explanation of how Neon's managed PgBouncer pooling works and the `max_connections` limits that govern your Postgres connection capacity for each compute size.

### Keep client-side pool sizes small

On a traditional fixed server, a pool size of `max: 20` is standard. In serverless, the number of containers is dynamic, if 200 containers each hold 10 connections, that's 2,000 simultaneous connections before you've processed a single query.

Set your local pool's maximum to **1 or 2 per container**. Let Neon's PgBouncer handle the multiplexing to Postgres.

### Initialize your pool globally

Never create your database client or pool inside a request handler. Doing so opens a new connection on every invocation, degrading performance and exhausting connections almost immediately.

Always declare your pool in the global scope, outside your handler function. This lets the runtime reuse the same connections across warm invocations:

**TypeScript**

```typescript
// ✅ Correct: global scope, reused across invocations
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 2,
});

export default async function handler(req) {
  const client = await pool.connect();
  // ...
}

// ❌ Wrong: inside handler, new connection every request
export default async function handler(req) {
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const client = await pool.connect();
  // ...
}
```

**Python**

```python
import os
from psycopg_pool import ConnectionPool

# ✅ Correct: global scope, reused across invocations
pool = ConnectionPool(
    conninfo=os.environ["DATABASE_URL"],
    min_size=1,
    max_size=2,
    open=True,
)

def handler(request):
    with pool.connection() as conn:
        # ...

# ❌ Wrong: inside handler, new pool every request
def handler(request):
    pool = ConnectionPool(
        conninfo=os.environ["DATABASE_URL"],
        min_size=1,
        max_size=2,
        open=True,
    )
    with pool.connection() as conn:
        # ...
```

### Handle suspension leaks

When a container goes idle, you need to close its database connections before the platform suspends the container. Some platforms provide lifecycle hooks that let you clean up just before suspension or termination. The implementation differs by platform:

**Vercel Fluid Compute**

On Vercel Fluid Compute, use `attachDatabasePool` from `@vercel/functions`. It keeps the instance alive just long enough to close idle connections before suspension:

```typescript
import { Pool } from 'pg';
import { attachDatabasePool } from '@vercel/functions';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 2,
  idleTimeoutMillis: 5000,
});
attachDatabasePool(pool);
```

**Modal**

Modal provides lifecycle hooks for container startup and shutdown. Use `@modal.enter()` to open your pool when the container starts and `@modal.exit()` to close it before the container exits (including preemption, with a 30-second grace period). These hooks run once per container regardless of how many concurrent inputs it processes.

When using Modal's input concurrency, match your pool's `max_size` to number of concurrent inputs per container.

```python
import os
import modal
from psycopg_pool import ConnectionPool

app = modal.App("neon-resilient-worker")

CONCURRENCY = 10

@app.cls(
    secrets=[modal.Secret.from_name("neon-db-secrets")],
)
@modal.concurrent(max_inputs=CONCURRENCY)
class DatabaseWorker:
    @modal.enter()
    def open_pool(self):
        self.pool = ConnectionPool(
            conninfo=os.environ["DATABASE_URL"],
            min_size=1,
            max_size=CONCURRENCY,
            open=True,
        )

    @modal.method()
    def process_task(self, task_id: int):
        with self.pool.connection() as conn:
            # Run queries
            pass

    @modal.exit()
    def close_pool(self):
        self.pool.close()
```

See the [Modal lifecycle hooks guide](https://modal.com/docs/guide/lifecycle-functions#modalexit) and [concurrent inputs guide](https://modal.com/docs/guide/concurrent-inputs) for details.

**Google Cloud Run**

Google Cloud Run doesn't expose a pre-suspension hook, but it sends a `SIGTERM` signal before terminating a container (with a configurable grace period). Register a signal handler to close the pool, and set a short idle timeout so connections don't linger while idle:

```python
import os
import signal
import sys
from psycopg_pool import ConnectionPool

pool = ConnectionPool(
    conninfo=os.environ["DATABASE_URL"],
    min_size=1,
    max_size=2,
    timeout=10,
)

def shutdown(signum, frame):
    pool.close()
    sys.exit(0)

signal.signal(signal.SIGTERM, shutdown)
signal.signal(signal.SIGINT, shutdown)
```

For platforms without dedicated lifecycle hooks, configure a short **idle timeout** of 5 to 10 seconds on your pool, and listen for shutdown signals (`SIGTERM`, `SIGINT`) to close connections cleanly.

### Coordinate with Neon autoscaling

Neon's [autoscaling](https://neon.com/docs/introduction/autoscaling) adjusts your database compute based on load. Connection limits scale with compute size. A 0.25 CU instance handles far fewer connections than a 1 CU instance. While PgBouncer accepts up to 10,000 client connections, the number of active parallel transactions it sends to Postgres is capped by `default_pool_size` (set to `0.9 × max_connections` for [your compute](https://neon.com/docs/connect/connection-pooling).

#### Neon's connection limits

Neon enforces three layers of connection limits. Understanding how they stack is essential for sizing your serverless tier:

| Limit               | Value                    | Controls                                   | What happens when exceeded                                          |
| :------------------ | :----------------------- | :----------------------------------------- | :------------------------------------------------------------------ |
| `max_client_conn`   | 10,000                   | Client connections to PgBouncer            | New connections rejected                                            |
| `default_pool_size` | 90% of `max_connections` | Active transactions per user, per database | Queries queue, then fail after 120s (`query_wait_timeout`)          |
| `max_connections`   | Varies by compute size   | Direct Postgres connections                | New connections rejected: "remaining connection slots are reserved" |

The `max_connections` limit and therefore your `default_pool_size` depends on your compute size:

| Compute size (CU) | RAM         | max\_connections | default\_pool\_size (90%) |
| :---------------- | :---------- | :--------------- | :------------------------ |
| 0.25              | 1 GB        | 104              | 93                        |
| 0.50              | 2 GB        | 209              | 188                       |
| 1                 | 4 GB        | 419              | 377                       |
| 2                 | 8 GB        | 839              | 755                       |
| 3                 | 12 GB       | 1258             | 1132                      |
| 4                 | 16 GB       | 1678             | 1510                      |
| 9 – 56            | 36 – 224 GB | 4000 (capped)    | 3600                      |

**Note:** Seven connections are reserved for the Neon superuser account. On a 0.25 CU compute, this leaves 97 connections available to your application (104 − 7) via direct connections. The pooled endpoint's `default_pool_size` already reserves similar headroom.

For the complete up-to-date table including intermediate compute sizes, see [Postgres settings that differ by compute size](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size).

If your database idles at a small compute size and your serverless tier suddenly bursts to 500 containers running heavy queries, some requests will queue in PgBouncer. After **120 seconds** in the queue, they fail with a `query_wait_timeout` error.

To prevent this, set your **minimum compute size** high enough to handle expected traffic bursts. A minimum of 1 or 2 CU gives your baseline connection pool enough headroom to absorb spikes without waiting for a scaling event. See the [autoscaling guide](https://neon.com/docs/guides/autoscaling-guide) for details.

You can monitor pooler client and server connections on the [Monitoring page](https://neon.com/docs/introduction/monitoring-page) in the Neon Console.

## The Bulkhead Pattern: Protecting Transactional APIs

In many architectures, different systems share a single database. If high-concurrency background workers (such as image processors or batch jobs) scale up, they can consume all available slots in the database pool, starving your user-facing APIs.

To prevent this, implement the **Bulkhead Pattern** by isolating your workloads at the database layer.

PgBouncer manages connection pools based on the distinct combination of **database user (role) and database name**. You can exploit this behavior to partition your database limits:

### Create distinct roles in PostgreSQL

```sql
-- Create a role for your web API
CREATE ROLE web_api_user WITH LOGIN PASSWORD 'secure_web_pass';
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO web_api_user;

-- Create a role for your background workers
CREATE ROLE worker_user WITH LOGIN PASSWORD 'secure_worker_pass';
GRANT SELECT, INSERT ON ALL TABLES IN SCHEMA public TO worker_user;
```

### Configure different credentials in your systems

- **Web application:** Use a connection string signed in as `web_api_user`.
- **Background worker:** Use a connection string signed in as `worker_user`.

Because the roles are different, PgBouncer assigns them to separate internal pools. This gives you soft isolation: if your background workers saturate their share of the connection pool, your web application still has breathing room under its own pool. However, both pools share the same total connection budget from Postgres, so heavy worker activity can still reduce the connections available to your web app.

For hard isolation with guaranteed per-role connection limits, you would need to run your own PgBouncer instance and configure per-user `pool_size` or `max_db_connections` settings in `pgbouncer.ini`

## Troubleshooting

### `max_connections` errors

```
Remaining connection slots are reserved for roles with the SUPERUSER attribute
```

You're connecting directly to Postgres bypassing PgBouncer or your client-side pool sizes are too large for the number of containers running. Check that your `DATABASE_URL` contains `-pooler` in the hostname and reduce pool sizes to `max: 1` or `max: 2`. See [Connection errors](https://neon.com/docs/connect/connection-errors) for more.

### Double pooling

If you use a client-side pooler like Prisma's connection manager with large pool sizes on top of Neon's pooled endpoint, containers will hoard idle connections that other containers need. Set client-side pool sizes to `1` or `2` and use a short idle timeout 10 seconds works well. See [Choose a connection method](https://neon.com/docs/connect/choose-connection) for guidance.

### `query_wait_timeout` errors

```
query_wait_timeout SSL connection has been closed unexpectedly
```

A sudden burst of queries exceeded what your current compute size could handle. Queries sat in PgBouncer's queue for longer than 120 seconds and timed out. Optimize slow queries and increase your **minimum compute size** to 1 or 2 CU to raise the baseline execution capacity. See [Connection errors](https://neon.com/docs/connect/connection-errors) for more.

**Note:** Neon's autoscaling handles gradual traffic increases well, but sudden bursts from serverless scale-outs can outpace it. A higher minimum compute size gives you a safety buffer.

## Resources

- [Connection pooling](https://neon.com/docs/connect/connection-pooling)
- [Autoscaling guide](https://neon.com/docs/guides/autoscaling-guide)
- [Connection latency and timeouts](https://neon.com/docs/connect/connection-latency)
- [Vercel connection methods](https://neon.com/docs/guides/vercel-connection-methods)
- [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver)

--- [Document source](https://neon.com/docs/guides/solid-start.md) ---

> Summary: SolidStart integration with Neon walks through creating a Neon project and querying a serverless Postgres database from a SolidJS meta-framework app. Covers server-side data loading and API routes using node-postgres, postgres.js, or the Neon serverless driver.

# Connect a SolidStart application to Neon

Set up a Neon project in seconds and connect from a SolidStart application

Last updated: 2026-09-16

Pre-built prompt for connecting SolidStart applications to Neon [View prompt](https://neon.com/prompts/solidstart-prompt.md)

SolidStart is an open-source meta-framework designed to integrate the components that make up a web application.[1](https://docs.solidjs.com/solid-start#overview). This guide explains how to connect SolidStart with Neon using a secure server-side request.

**Note:** This guide uses SolidStart 2, which requires Node.js 24 or later. Run `node --version` to check your version.

To create a Neon project and access it from a SolidStart application:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a SolidStart project and add dependencies

1. Create a SolidStart 2 project if you do not have one. The `-s` and `--v2` flags select SolidStart 2 without prompts. For more options, see the [SolidStart documentation](https://docs.solidjs.com/solid-start).

   ```shell
   npm create solid@latest my-solidstart-app -- -s --v2 -t basic --ts
   cd my-solidstart-app
   ```

2. Add project dependencies using one of the following commands:

   **node-postgres**

   ```shell
   npm install pg
   npm install -D @types/pg
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless
   ```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection string to it. You can find the connection string for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

**Note:** `pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. If you use node-postgres, change `sslmode=require` to `sslmode=verify-full` in `DATABASE_URL` to keep the same behavior and remove the warning.

## Configure the Postgres client

There are multiple ways to make server-side requests with SolidStart. See below for the different implementations.

### Server-side data loading

To [load data on the server](https://docs.solidjs.com/solid-start/building-your-application/data-loading#data-loading-always-on-the-server) in SolidStart, add the following code snippet to `src/routes/index.tsx` to connect to your Neon database:

**node-postgres**

```typescript filename="src/routes/index.tsx"
import pg from 'pg';
import { createAsync, query } from "@solidjs/router";

const getVersion = query(async () => {
    "use server";
    const client = new pg.Client({
        connectionString: process.env.DATABASE_URL,
    });
    await client.connect();
    try {
      const response = await client.query('SELECT version()');
      return response.rows[0].version;
    } finally {
      await client.end();
    }
}, 'version')

export const route = {
  preload: () => getVersion(),
};

export default function Page() {
  const version = createAsync(() => getVersion());
  return <>{version()}</>;
}
```

**postgres.js**

```typescript filename="src/routes/index.tsx"
import postgres from 'postgres';
import { createAsync, query } from "@solidjs/router";

const getVersion = query(async () => {
    "use server";
    const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });
    const response = await sql`SELECT version()`;
    return response[0].version;
}, 'version')

export const route = {
  preload: () => getVersion(),
};

export default function Page() {
  const version = createAsync(() => getVersion());
  return <>{version()}</>;
}
```

**Neon serverless driver**

```typescript filename="src/routes/index.tsx"
import { neon } from "@neondatabase/serverless";
import { createAsync, query } from "@solidjs/router";

const getVersion = query(async () => {
    "use server";
    const sql = neon(process.env.DATABASE_URL!);
    const response = await sql`SELECT version()`;
    const { version } = response[0];

    return version;
}, 'version')

export const route = {
  preload: () => getVersion(),
};

export default function Page() {
  const version = createAsync(() => getVersion());
  return <>{version()}</>;
}
```

### Server endpoints (API routes)

In your server endpoints (API routes) in your SolidStart application, use the following code snippet to connect to your Neon database. Create the file at `src/routes/api/test.ts`:

**node-postgres**

```typescript filename="src/routes/api/test.ts"
import { Pool } from 'pg';
import { json } from '@solidjs/router';

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

export async function GET() {
  const client = await pool.connect();
  let data = {};
  try {
    const { rows } = await client.query('SELECT version()');
    data = rows[0];
  } finally {
    client.release();
  }
  return json(data);
}
```

**postgres.js**

```typescript filename="src/routes/api/test.ts"
import postgres from 'postgres';
import { json } from '@solidjs/router';

export async function GET() {
  const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });
  const response = await sql`SELECT version()`;

  return json(response[0]);
}
```

**Neon serverless driver**

```typescript filename="src/routes/api/test.ts"
import { neon } from '@neondatabase/serverless';
import { json } from '@solidjs/router';

export async function GET() {
  const sql = neon(process.env.DATABASE_URL!);
  const response = await sql`SELECT version()`;

  return json(response[0]);
}
```

**Note:** If `tsc` or your editor reports `Cannot find name 'process'`, the default template doesn't include Node.js types. Run `npm install -D @types/node` to add them.

## Run the app

When you run `npm run dev` you can expect to see the following on [localhost:3000](http://localhost:3000):

```shell
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

The API route returns the same value as JSON at [localhost:3000/api/test](http://localhost:3000/api/test).

**Note:** `npm run dev` loads the `.env` file automatically. The production server does not. To run a production build, set `DATABASE_URL` in your environment, then run `npm run build` and `npm start`. Without the variable, the app fails to connect.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/sqlalchemy-migrations.md) ---

> Summary: SQLAlchemy with Alembic autogenerates and applies versioned schema migrations to a Lakebase Postgres database using `alembic revision --autogenerate` and `alembic upgrade head`. A direct (non-pooled) connection string is required to avoid migration errors. Use this guide when you need to track and apply incremental DDL changes (such as adding columns) without writing manual SQL. The guide builds a FastAPI app with SQLAlchemy ORM models and walks through an end-to-end schema evolution cycle.

# Schema migration with Lakebase Postgres and SQLAlchemy

Manage database migrations in your Python project with SQLAlchemy and Alembic

Last updated: 2026-10-28

[SQLAlchemy](https://www.sqlalchemy.org/) is a popular SQL toolkit and Object-Relational Mapping (ORM) library for Python. SQLAlchemy provides a powerful way to interact with databases and manage database schema changes using [Alembic](https://alembic.sqlalchemy.org/), a lightweight database migration tool.

This guide demonstrates how to use SQLAlchemy/Alembic to manage schema migrations for a Lakebase Postgres database. We create a simple API using the [FastAPI](https://fastapi.tiangolo.com/) web framework and define database models using SQLAlchemy. We then generate and run migrations to manage schema changes over time.

## Prerequisites

To follow along with this guide, you will need:

- A Neon account. If you do not have one, sign up at [Neon](https://neon.tech). Your Neon project comes with a ready-to-use Postgres database named `neondb`. We'll use this database in the following examples.
- [Python](https://www.python.org/) installed on your local machine. We recommend using a newer version of Python, 3.8 or higher.

## Setting up your database

### Initialize a new project

1. Log in to the Neon Console and navigate to the [Projects](https://console.neon.tech/app/projects) section.
2. Select a project or click the **New Project** button to create a new one.

### Retrieve your database connection string

You can find the connection string for your database by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Keep your connection string handy for later use.

**Note:** Neon supports both direct and pooled database connection strings. You can find a connection string for your database by clicking the **Connect** button in the Console nav. A pooled connection string connects your application to the database via a PgBouncer connection pool, allowing for a higher number of concurrent connections. However, using a pooled connection string for migrations can be prone to errors. For this reason, we recommend using a direct (non-pooled) connection when performing migrations. For more information about direct and pooled connections, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Setting up the Web application

### Set up the Python environment

To manage our project dependencies, we create a new Python virtual environment. Run the following commands in your terminal to set it up.

```bash
python -m venv myenv
```

Activate the virtual environment by running the following command:

```bash
# On macOS and Linux
source myenv/bin/activate

# On Windows
myenv\Scripts\activate
```

With the virtual environment activated, we can create a new directory for our FastAPI project and install the required packages:

```bash
mkdir guide-neon-sqlalchemy && cd guide-neon-sqlalchemy
pip install sqlalchemy alembic "psycopg2-binary"
pip install fastapi uvicorn python-dotenv
pip freeze > requirements.txt
```

We installed SQLAlchemy, Alembic, and the `psycopg2-binary` package to connect to the Lakebase Postgres database. We then installed the `FastAPI` package to create the API endpoints and `uvicorn` as the web server. We then saved the installed packages to a `requirements.txt` file so the project can be easily recreated in another environment.

### Set up the Database configuration

Create a `.env` file in the project root directory and add the `DATABASE_URL` environment variable to it. Use the connection string that you obtained from the Neon Console earlier:

```bash
# .env
DATABASE_URL=NEON_POSTGRES_CONNECTION_STRING
```

We create an `app` directory at the project root to store the database models and configuration files.

```bash
mkdir app
touch guide-neon-sqlalchemy/app/__init__.py
```

Next, create a new file named `database.py` in the `app` subdirectory and add the following code:

```python
# app/database.py

import os

import dotenv
from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

dotenv.load_dotenv()
SQLALCHEMY_DATABASE_URL = os.getenv("DATABASE_URL")

engine = create_engine(SQLALCHEMY_DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()
```

This code sets up the database connection using SQLAlchemy. It reads the `DATABASE_URL` environment variable, creates a database engine, and defines a `SessionLocal` class for database sessions. The `Base` class is used as a base class for defining database models.

## Defining data models and running migrations

### Specify the data model

Create a new file named `models.py` in the `app` subdirectory and define the database models for your application:

```python
# app/models.py

from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey
from sqlalchemy.orm import relationship
from sqlalchemy.sql import func

from .database import Base

class Author(Base):
    __tablename__ = "authors"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(100), nullable=False)
    bio = Column(Text)
    created_at = Column(DateTime(timezone=True), server_default=func.now())

    books = relationship("Book", back_populates="author")

class Book(Base):
    __tablename__ = "books"

    id = Column(Integer, primary_key=True, index=True)
    title = Column(String(200), nullable=False)
    author_id = Column(Integer, ForeignKey("authors.id"), nullable=False)
    created_at = Column(DateTime(timezone=True), server_default=func.now())

    author = relationship("Author", back_populates="books")
```

This code defines two models: `Author` and `Book`. The `Author` model represents an author with fields for `name`, `bio`, and a `created_at` timestamp. The `Book` model represents a book with fields for `title`, `author` (as a foreign key to the `Author` model), and a `created_at` timestamp. The `relationship` function is used to define the one-to-many relationship between `Author` and `Book`.

### Initialize Alembic

To initialize Alembic for managing database migrations, run the following command in your terminal:

```bash
alembic init alembic
```

This command creates a new directory named `alembic` with the necessary files for managing migrations. Open the `env.py` file in the `alembic` directory and update the `target_metadata` variable to include the models defined in the `models.py` file:

```python
# alembic/env.py

from app.models import Base

target_metadata = Base.metadata
```

We update the `alembic/env.py` file again to load the database URL from the `.env` file at project root and set it as the `sqlalchemy.url` configuration option.

```python
# alembic/env.py

import dotenv
import os

dotenv.load_dotenv()

config.set_main_option('sqlalchemy.url', os.getenv('DATABASE_URL', ""))
```

### Generate the initial migration

To generate the initial migration based on the defined models, run the following command:

```bash
alembic revision --autogenerate -m "init-setup"
```

This command detects the `Author` and `Book` models and generates a new migration file in the `alembic/versions` directory.

### Apply the migration

To apply the migration and create the corresponding tables in the Lakebase Postgres database, run the following command:

```bash
alembic upgrade head
```

This command executes the migration file and creates the necessary tables in the database.

### Seed the database

To seed the database with some initial data, create a new file named `seed.py` in the project root and add the following code:

```python
# seed.py

from database import SessionLocal
from models import Author, Book

def seed_data():
    db = SessionLocal()

    # Create authors
    authors = [
        Author(
            name="J.R.R. Tolkien",
            bio="The creator of Middle-earth and author of The Lord of the Rings."
        ),
        Author(
            name="George R.R. Martin",
            bio="The author of the epic fantasy series A Song of Ice and Fire."
        ),
        Author(
            name="J.K. Rowling",
            bio="The creator of the Harry Potter series."
        ),
    ]
    db.add_all(authors)
    db.commit()

    # Create books
    books = [
        Book(title="The Fellowship of the Ring", author=authors[0]),
        Book(title="The Two Towers", author=authors[0]),
        Book(title="The Return of the King", author=authors[0]),
        Book(title="A Game of Thrones", author=authors[1]),
        Book(title="A Clash of Kings", author=authors[1]),
        Book(title="Harry Potter and the Philosopher's Stone", author=authors[2]),
        Book(title="Harry Potter and the Chamber of Secrets", author=authors[2]),
    ]
    db.add_all(books)
    db.commit()

    print("Data seeded successfully.")

if __name__ == "__main__":
    seed_data()
```

Now, run the `seed.py` script to seed the database with the initial data:

```bash
python seed.py
```

## Implement the web application

### Create API endpoints

Create a file named `main.py` in the project root directory and define the FastAPI application with endpoints for interacting with authors and books:

```python
# main.py

from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session
import uvicorn

from app.models import Author, Book, Base
from app.database import SessionLocal, engine

Base.metadata.create_all(bind=engine)

app = FastAPI()

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/authors/")
def read_authors(db: Session = Depends(get_db)):
    authors = db.query(Author).all()
    return authors


@app.get("/books/{author_id}")
def read_books(author_id: int, db: Session = Depends(get_db)):
    books = db.query(Book).filter(Book.author_id == author_id).all()
    return books

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)
```

This code defines endpoints for creating and retrieving authors and books. It uses SQLAlchemy's `Session` to interact with the database and Pydantic models (`schemas`) for request and response data validation and serialization.

### Run the FastAPI server

To start the FastAPI server using `uvicorn` and test the application, run the following command:

```bash
python main.py
```

Now, you can navigate to `http://localhost:8000/authors` in your browser to view the list of authors. To view the books by a specific author, navigate to `http://localhost:8000/books/{author_id}` where `{author_id}` is the ID of the author.

## Applying schema changes

Let's demonstrate how to handle schema changes by adding a new field `country` to the `Author` model, to store the author's country of origin.

### Update the data model

Open the `models.py` file and add a new field to the `Author` model:

```python
# models.py
class Author(Base):
    __tablename__ = "authors"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(100), nullable=False)
    bio = Column(Text)
    country = Column(String(100))
    created_at = Column(DateTime(timezone=True), server_default=func.now())

    books = relationship("Book", back_populates="author")
```

### Generate and run the migration

To generate a new migration file for the schema change, run the following command:

```bash
alembic revision --autogenerate -m "add-country-to-author"
```

This command detects the updated `Author` model and generates a new migration file to add the new field to the corresponding table in the database.

Now, to apply the migration, run the following command:

```bash
alembic upgrade head
```

### Test the schema change

Restart the FastAPI development server.

```bash
python main.py
```

Navigate to `http://localhost:8000/authors` in your browser to view the list of authors. You should see the new `country` field included in each author's record, reflecting the schema change.

## Conclusion

In this guide, we demonstrated how to set up a FastAPI project with `Neon` Postgres, define database models using SQLAlchemy, generate migrations using Alembic, and run them. Alembic makes it easy to interact with the database and manage schema evolution over time.

## Source code

You can find the source code for the application described in this guide on GitHub.

- [Migrations with Neon and SQLAlchemy](https://github.com/neondatabase/guide-neon-sqlalchemy): Run migrations in a Neon-SQLAlchemy project

## Resources

For more information on the tools and concepts used in this guide, refer to the following resources:

- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [SQLAlchemy Documentation](https://docs.sqlalchemy.org/)
- [Alembic Documentation](https://alembic.sqlalchemy.org/)
- [Neon](https://neon.com/docs)

--- [Document source](https://neon.com/docs/guides/sqlalchemy.md) ---

> Summary: SQLAlchemy, a Python SQL toolkit and ORM, connects to Lakebase Postgres by installing psycopg (v3) and passing a postgresql+psycopg connection string to SQLAlchemy's create_engine function. Use this guide to build a working connection, then resolve Lakebase-specific errors caused by compute scale-to-zero suspension, including SSL connection drops when idle connections are reused. A recent version of SQLAlchemy is required to avoid idle connection reuse bugs. Set pool_recycle or pool_pre_ping to prevent SSL SYSCALL EOF errors.

# Connect an SQLAlchemy application to Lakebase Postgres

Set up a project on Neon in seconds and connect from an SQLAlchemy application

Last updated: 2026-09-16

Pre-built prompt for connecting SQLAlchemy to Lakebase Postgres [View prompt](https://neon.com/prompts/sqlalchemy-prompt.md)

SQLAlchemy is a Python SQL toolkit and Object Relational Mapper (ORM). This guide describes how to create a project on Neon and connect to it from SQLAlchemy.

**Prerequisites:**

- Python 3.11 or later (required by SQLAlchemy 2.1).
- A Python virtual environment for your project.

The instructions below use `psycopg` (v3), the default Postgres driver in SQLAlchemy 2.1.

To connect to a Lakebase Postgres database from SQLAlchemy:

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Install SQLAlchemy and a driver

Install SQLAlchemy, the `psycopg` driver, and `python-dotenv` in your virtual environment:

```shell
pip install sqlalchemy "psycopg[binary]" python-dotenv
```

For more installation options, see [Installation](https://docs.sqlalchemy.org/en/20/intro.html#installation) in the SQLAlchemy documentation.

## Store your connection string

Add a `.env` file to your project directory with your connection string. You can find it by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

Change the scheme from `postgresql://` to `postgresql+psycopg://` so that SQLAlchemy uses the `psycopg` driver on any SQLAlchemy 2.x version:

```shell
DATABASE_URL="postgresql+psycopg://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

**Note:** To use `psycopg2` instead, install `psycopg2-binary` and use the `postgresql+psycopg2://` scheme. SQLAlchemy 2.0 uses `psycopg2` for plain `postgresql://` URLs; SQLAlchemy 2.1 uses `psycopg`.

## Create an SQLAlchemy engine and run a query

SQLAlchemy uses an engine to manage database connections. Create a file named `main.py` that creates an engine from your connection string and runs a query:

```python
import os

from dotenv import load_dotenv
from sqlalchemy import create_engine, text

load_dotenv()

engine = create_engine(os.environ["DATABASE_URL"], pool_pre_ping=True)

with engine.connect() as conn:
    result = conn.execute(text("SELECT 'hello neon'"))
    print(result.scalar())
```

`pool_pre_ping=True` checks that a pooled connection is still alive before using it, which avoids errors after your compute scales to zero.

Run the script:

```shell
python main.py
```

The output is:

```text
hello neon
```

For additional information about connecting from SQLAlchemy, refer to the following topics in the SQLAlchemy documentation:

- [Establishing Connectivity - the Engine](https://docs.sqlalchemy.org/en/20/tutorial/engine.html)
- [Connecting to PostgreSQL with SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/engines.html#postgresql)

## SQLAlchemy connection errors

- SQLAlchemy versions prior to 2.0.33 may reuse idle connections, leading to connection errors. If this occurs, you could encounter an `SSL connection has been closed unexpectedly` error. To resolve this, upgrade to SQLAlchemy 2.0.33 or later. For more details, see the [SQLAlchemy 2.0.33 changelog](https://docs.sqlalchemy.org/en/20/changelog/changelog_20.html#change-2.0.33-postgresql).
- If you encounter an `SSL SYSCALL error: EOF detected` when connecting to the database, this typically happens because the application is trying to reuse a connection after the Neon compute has been suspended due to inactivity. To resolve this issue, try one of the following options:

  - Set the SQLAlchemy `pool_recycle` parameter to a value less than or equal to the scale to zero setting configured for your compute.
  - Set the SQLAlchemy `pool_pre_ping` parameter to `True`. This ensures that your engine checks if the connection is alive before executing a query.

  For more details on the `pool_recycle` and `pool_pre_ping` parameters, refer to [SQLAlchemy: Connection Pool Configuration](https://docs.sqlalchemy.org/en/20/core/pooling.html#connection-pool-configuration) and [Dealing with Disconnects](https://docs.sqlalchemy.org/en/20/core/pooling.html#dealing-with-disconnects). For information on configuring Neon's scale to zero setting, see [Configuring Scale to Zero for Neon computes](https://neon.com/docs/guides/scale-to-zero-guide).

## Schema migration with SQLAlchemy

For schema migration with SQLAlchemy, see:

- [SQLAlchemy Migrations](https://neon.com/docs/guides/sqlalchemy-migrations): Schema migration with Lakebase Postgres and SQLAlchemy

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/sveltekit.md) ---

> Summary: SvelteKit integration with Lakebase Postgres connects a SvelteKit app to a serverless Postgres database through a secure server-side route using node-postgres, postgres.js, or the Neon serverless driver. Use this guide when setting up a new SvelteKit project that needs a Postgres backend, covering project creation, db.server.ts configuration, and a +page.server.ts load function. Requires a DATABASE_URL connection string with sslmode=require and channel_binding=require.

# Connect a Sveltekit application to Neon

Set up a project on Neon in seconds and connect from a Sveltekit application

Last updated: 2026-10-08

Pre-built prompt for connecting SvelteKit applications to Lakebase Postgres. [View prompt](https://neon.com/prompts/sveltekit-prompt.md)

SvelteKit is the application framework for Svelte. This guide explains how to connect a SvelteKit app to Neon and query your database in a server-side `load` function. It uses SvelteKit 3, which reads environment variables through `$app/env/private` and requires Svelte 5 runes in components.

To create a project on Neon and access it from a SvelteKit application:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a SvelteKit project and add dependencies

1. Create a SvelteKit project using the following commands:

   ```shell
   npx sv create my-app --template minimal --no-add-ons --types ts
   cd my-app
   ```

2. Add project dependencies using one of the following commands:

   **node-postgres**

   ```shell
   npm install pg
   npm install -D @types/pg
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless
   ```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection string to it. You can find the connection string for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

If you use node-postgres, `pg` 8.23 and later print a `SECURITY WARNING` for `sslmode=require`. Change it to `sslmode=verify-full` to keep the same behavior without the warning.

Then declare the variable in `src/env.ts`. SvelteKit loads `.env` in development and reads declared variables from the environment when the app starts, so your password isn't built into the app:

```typescript filename="src/env.ts"
import { defineEnvVars } from '@sveltejs/kit/env';

export const variables = defineEnvVars({
  DATABASE_URL: {
    description: 'Neon connection string',
  },
});
```

## Configure the Postgres client

There are two parts to connecting a SvelteKit application to Neon. The first is `db.server.ts`, which contains the database configuration. The second is the server-side route where the connection to the database will be used.

### Database module

Create a `db.server.ts` file at the root of your `src` directory and add the following code to connect to your Neon database. The `.server` suffix keeps the module, and your connection string, out of client-side code.

**node-postgres**

```typescript filename="src/db.server.ts"
import pg from 'pg';
import { DATABASE_URL } from '$app/env/private';

export const pool = new pg.Pool({
  connectionString: DATABASE_URL,
  ssl: true,
});
```

**postgres.js**

```typescript filename="src/db.server.ts"
import postgres from 'postgres';
import { DATABASE_URL } from '$app/env/private';

export const sql = postgres(DATABASE_URL, { ssl: 'require' });
```

**Neon serverless driver**

```typescript filename="src/db.server.ts"
import { neon } from '@neondatabase/serverless';
import { DATABASE_URL } from '$app/env/private';

export const sql = neon(DATABASE_URL);
```

### Server load function

Create a `src/routes/+page.server.ts` file and import the database configuration:

**node-postgres**

```typescript
import { pool } from '../db.server';

export async function load() {
  const client = await pool.connect();
  try {
    const { rows } = await client.query('SELECT version()');
    const { version } = rows[0];
    return {
      version,
    };
  } finally {
    client.release();
  }
}
```

**postgres.js**

```typescript
import { sql } from '../db.server';

export async function load() {
  const response = await sql`SELECT version()`;
  const { version } = response[0];
  return {
    version,
  };
}
```

**Neon serverless driver**

```typescript
import { sql } from '../db.server';

export async function load() {
  const response = await sql`SELECT version()`;
  const { version } = response[0];
  return {
    version,
  };
}
```

### Page component

Replace the contents of `src/routes/+page.svelte` to display the data. SvelteKit 3 uses Svelte 5 runes, so read `data` with `$props()` (`export let data` fails with `Cannot use export let in runes mode`):

```svelte filename="src/routes/+page.svelte"
<script lang="ts">
  import type { PageProps } from './$types';

  let { data }: PageProps = $props();
</script>

<h1>Database Version</h1>
<p>{data.version}</p>
```

## Run the app

When you run `npm run dev` you can expect to see the following on [localhost:5173](http://localhost:5173):

```shell
Database Version
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

To run a production build on Node.js, switch the adapter in `vite.config.ts` from `@sveltejs/adapter-auto` to [`@sveltejs/adapter-node`](https://svelte.dev/docs/kit/adapter-node) (`npm install -D @sveltejs/adapter-node`), run `npm run build`, and start the server with `DATABASE_URL` in its environment, for example `node --env-file=.env build`.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/quickstart): Build realtime apps with end-to-end reactivity »

--- [Document source](https://neon.com/docs/guides/symfony.md) ---

> Summary: Connecting Symfony to Lakebase Postgres via Doctrine ORM requires only setting the DATABASE_URL in your .env file to a Lakebase Postgres connection string with sslmode=require and channel_binding=require. Choose this page when adding a serverless Postgres backend to a Symfony project using Doctrine for database access.

# Connect from Symfony with Doctrine to Neon

Set up a project on Neon in seconds and connect from Symfony with Doctrine

Last updated: 2026-09-16

Pre-built prompt for connecting Symfony applications to Lakebase Postgres using Doctrine ORM. [View prompt](https://neon.com/prompts/symfony-prompt.md)

Symfony is a free and open-source PHP web application framework. Symfony uses the Doctrine library for database access. Connecting to a Lakebase Postgres database from Symfony with Doctrine is the same as connecting to a standalone Postgres installation from Symfony with Doctrine. Only the connection details differ.

To connect to a Lakebase Postgres database from Symfony with Doctrine:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Install Doctrine

If your Symfony project doesn't use Doctrine yet, install the ORM pack. Your PHP installation also needs the `pdo_pgsql` and `pgsql` extensions. Check for them with `php -m | grep pgsql`.

```shell
composer require symfony/orm-pack
```

## Configure the connection

Symfony reads the default `DATABASE_URL` from `.env`, which points to a local PostgreSQL server. Add the Neon project connection string that you copied in the first step to `.env.local`. Symfony loads that file on top of `.env`, and the default `.gitignore` excludes it, so your password stays out of version control.

```text filename=".env.local"
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?charset=utf8&sslmode=require&channel_binding=require"
```

You can find the connection string for your database by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Test the connection

Run a query with the Doctrine console command. The output shows the Postgres version of your Neon database.

```shell
php bin/console dbal:run-sql "SELECT version()"
```

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/tables.md) ---

> Summary: The Tables page in the Neon Console is a visual, interactive editor powered by Drizzle Studio. It supports reading, inserting, updating, deleting, filtering, and exporting Postgres table data, plus managing schemas, views, enums, roles, and RLS policies without writing SQL. Choose this page over the SQL Editor when you want point-and-click record editing, column filtering, bulk deletion, or JSON/CSV export.

# Managing your data and schemas in the Neon Console

Use the Tables page to easily view, edit, and manage your data and schemas

Last updated: 2026-09-17

The **Tables** page in the Neon Console offers a dynamic, visual interface for managing data and schemas. Fully interactive, this view lets you add, update, and delete records, filter data, modify columns, drop or truncate tables, export data in both .json and .csv formats, and manage schemas, tables, views, and enums.

**Note:** The **Tables** page is powered by a Drizzle Studio integration. For tracking updates, see [Tables page enhancements and updates](https://neon.com/docs/guides/tables#tables-page-enhancements-and-updates).

## Edit records

Edit individual entries directly within the table interface. Click on a cell to modify its contents. You don't have to press `Enter` (though you can). Just move your cursor to the next cell you want to modify. Click `Save x changes` when you're done.

![edit table records](https://neon.com/docs/manage/edit_record_drizzle.png)

## Add records

Add new records to your tables using the **Add record** button.

![add record to table](https://neon.com/docs/manage/add_record_drizzle.png)

A couple of things to note:

- You need to hit `Enter` for your input to register. When editing existing fields, you don't have to do this. But for new fields, if you tab to the next cell, you'll lose your input.
- You can leave `DEFAULT` fields untouched and the cell will inherit the right value based on your schema definition. For example, defaults for boolean fields are automatically applied when you click `Save changes`.

## Toggle columns

You can simplify your view by hiding (or showing) individual columns in the table. You're not modifying content here; deselect a checked column to hide it, and re-select the column to show it again. Your selections are saved as a persistent filter.

![toggle columns in table view](https://neon.com/docs/manage/toggle_columns_drizzle.gif)

## Add filters

Filters let you store simplified views of your data that you can come back to later. You can use dropdown-filtering to select columns, conditions, and input text for the filter.

![add filter to table view](https://neon.com/docs/manage/filter_drizzle.gif)

Each new filter is added as a **View** under your list of Tables.

![view filter views under tables](https://neon.com/docs/manage/view_filters_drizzle.gif)

## Delete records

Use the checkboxes to mark any unwanted records for deletion, or use the select-all checkbox for bulk deletion. Click `Delete x records` to complete the process.

![delete record from table](https://neon.com/docs/manage/delete_record_drizzle.png)

## Export data

You can also use the checkboxes to mark records for export. Select the records you want to include in your export, then choose `Export selected...` from the export dropdown.

Or just choose `Export all...` to download the entire contents of the table.

You can export to either JSON or CSV. You can also copy or export selected rows as SQL `INSERT` statements, and copy a table's `CREATE TABLE` statement to the clipboard.

![export data from table](https://neon.com/docs/manage/export_drizzle.png)

**Tip: Keyboard shortcuts**

The **Tables** page supports keyboard shortcuts for common actions, including selecting all rows (`Cmd/Ctrl + A`), adding a row (`Option/Alt + N`), filtering (`Option/Alt + F`), and refreshing (`Cmd/Ctrl + R`).

## Manage schemas

In addition to managing data, you can manage your database schema directly from the **Tables** page. Schema management options include:

- Creating, altering, and dropping schemas
- Creating and altering tables
- Creating and altering views
- Creating enums
- Refreshing the database schema

![Drizzle Studio Schema Management UI](https://neon.com/docs/changelog/drizzle_schema_mgmt.png)

## Create Postgres roles

You can create Postgres roles from the **Tables** page. Define a role name, select from a list of commonly granted privileges, set a password, and click **Review and Create**.

![Create roles on the tables page](https://neon.com/docs/changelog/tables_page_create_roles.png)

> Neon role and privilege limitations apply. See [Manage roles](https://neon.com/docs/manage/roles).

## Add privileges

For more advanced privilege assignments, click the **Add privilege** link when creating a role to build your `GRANT` statements.

![Add privileges on the tables page](https://neon.com/docs/changelog/tables_page_add_privileges.png)

> Neon role and privilege limitations apply. See [Manage roles](https://neon.com/docs/manage/roles).

## Define RLS policies

Create Postgres RLS policies using the templates provided. Templates like "based on user_id" restrict each user to their own rows. When using the Data API, access is matched to the `auth.user_id()` function.

![Set RLS policies on the tables page](https://neon.com/docs/changelog/tables_page_rls_policies.png)

### Database studio view

The **Database studio** view makes it easy to explore your database objects (including schemas, tables, views, roles, and policies) all in one place.

To open the view, select **Database studio** from the **Tables** page:

![Select database studio view](https://neon.com/docs/changelog/tables_page_select_studio_view.png)

Use the top navbar to navigate:

![Studio view](https://neon.com/docs/changelog/tables_page_studio_view.png)

## Tables page updates

The **Tables** page in the Neon Console is powered by a Drizzle Studio integration. You can check the Drizzle Studio integration version in your browser by inspecting the Tables page. For example, in Chrome, right-click, select **Inspect**, and go to the **Console** tab to view the current `Tables version`. You can cross-reference this version with the [Neon Drizzle Studio Integration Changelog](https://github.com/neondatabase/neon-drizzle-studio-changelog/blob/main/CHANGELOG.md) to track updates.

## Reporting errors

If you see an error message on the **Tables** page, this could be due to a DNS resolution issue.

Please refer to [DNS resolution issues](https://neon.com/docs/connect/connection-errors#dns-resolution-issues) for workarounds.

If it's not a DNS resolution issue, other troubleshooting steps you can try include:

- **Refreshing the page**: This can resolve temporary glitches.
- **Clearing browser cache**: Cached files might cause issues, so clearing the cache could help.
- **Disabling browser extensions**: Extensions may interfere with the page's functionality.
- **Using a different browser or device**: Check if the issue occurs on another browser or device.
- **Trying incognito mode**: Using an incognito window can help bypass issues related to cookies or extensions.

If the issue persists, please follow these steps to report the error:

1. [Open a support ticket](https://console.neon.tech/app/projects?modal=support) and provide a detailed description of what you were doing when the error occurred. Please include any screen captures or files that will help us reproduce the issue. We'll work with our partners at Drizzle to investigate and resolve the issue.
2. If you're on the Free plan, you can report the issue on [Discord](https://neon.com/discord).

--- [Document source](https://neon.com/docs/guides/tanstack-start.md) ---

> Summary: TanStack Start integration guide for Lakebase Postgres covers creating a Lakebase Postgres project, installing a supported driver (node-postgres, postgres.js, or the Neon serverless driver), and writing server functions that query the database. Choose this page when building a type-safe React or Solid app with TanStack Start and need working code for both regular and static server functions backed by Lakebase Postgres.

# Connect a TanStack Start application to Neon

Set up a project on Neon in seconds and connect from a TanStack Start application

Last updated: 2026-10-08

**Realtime with TanStack:**

Build full-stack reactive apps with SSR and end-to-end type-safety using [Neon Realtime with TanStack Start + DB](https://neon.com/docs/realtime/examples/tanstack).

Pre-built prompt for connecting TanStack Start applications to Lakebase Postgres [View prompt](https://neon.com/prompts/tanstack-start-prompt.md)

TanStack Start is an open-source, type-safe web framework for building React and Solid applications with the TanStack ecosystem.

To create a project on Neon and access it from a Start application:

## Create a Neon project

If you do not have one already, create a Neon project.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a Start project and add dependencies

1. Create a Start project if you do not have one. For instructions see the [quick start guides](https://tanstack.com/start/latest), in the [TanStack](https://tanstack.com/) documentation.

2. Add project dependencies using one of the following commands:

   **node-postgres**

   ```shell
   npm install pg
   npm install -D @types/pg
   ```

   **postgres.js**

   ```shell
   npm install postgres
   ```

   **Neon serverless driver**

   ```shell
   npm install @neondatabase/serverless
   ```

   If you plan to use [static server functions](https://neon.com/docs/guides/tanstack-start#static-server-functions), also install the static functions middleware:

   ```shell
   npm install @tanstack/start-static-server-functions
   ```

## Store your Neon credentials

Add a `.env` file to your project directory and add your Neon connection string to it. You can find your Neon database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

```shell
DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
```

**Note:** `pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. If you use node-postgres, change `sslmode=require` to `sslmode=verify-full` to keep the current behavior and remove the warning.

If you haven't created a project yet, [Claimable Neon](https://neon.com/claimable-neon) provisions a temporary Neon project without an account. A human can claim the project into a Neon account before it expires. See [Claimable Neon](https://neon.com/docs/reference/claimable-neon).

## Configure the Postgres client

There are multiple ways to make server-side requests with TanStack Start. See below for the different implementations.

### Server Functions

In your server functions, add the following code snippet to connect to your Neon database:

**node-postgres**

```typescript filename="src/data/get-neon-data.ts"
import { Pool } from 'pg';
import { createServerFn } from "@tanstack/react-start";

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: true,
});

export const getData = createServerFn({ method: "GET" }).handler(async () => {
  const client = await pool.connect();
  try {
    const { rows } = await client.query('SELECT version()');
    return rows[0].version;
  } finally {
    client.release();
  }
});
```

**postgres.js**

```typescript filename="src/data/get-neon-data.ts"
import postgres from 'postgres';
import { createServerFn } from "@tanstack/react-start";

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

export const getData = createServerFn({ method: "GET" }).handler(async () => {
  const response = await sql`SELECT version()`;
  return response[0].version;
});
```

**Neon serverless driver**

```typescript filename="src/data/get-neon-data.ts"
import { neon } from "@neondatabase/serverless";
import { createServerFn } from "@tanstack/react-start";

export const getData = createServerFn({ method: "GET" }).handler(async () => {
  const sql = neon(process.env.DATABASE_URL!);
  const response = await sql`SELECT version()`;

  return response[0].version;
});
```

Then consume the data in your start application, like you would normally, with any other data fetching operation.

```typescript filename="src/routes/index.tsx"
import { createFileRoute } from "@tanstack/react-router";
import { getData } from "../data/get-neon-data.ts";

export const Route = createFileRoute("/")({
  loader: async () => {
    return getData();
  },

  component: RouteComponent,
});

export default function RouteComponent() {
  const data = Route.useLoaderData();

  return <>{data}</>;
}
```

### Static Server Functions

In your static server functions, add the following code snippet to connect to your Neon database:

**node-postgres**

```typescript filename="src/data/get-neon-data.ts"
import { Pool } from 'pg';
import { createServerFn } from "@tanstack/react-start";
import { staticFunctionMiddleware } from "@tanstack/start-static-server-functions";

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: true,
});

export const getData = createServerFn({ method: "GET" })
.middleware([staticFunctionMiddleware])
.handler(async () => {
  const client = await pool.connect();
  try {
    const { rows } = await client.query('SELECT version()');
    return rows[0].version;
  } finally {
    client.release();
  }
});
```

**postgres.js**

```typescript filename="src/data/get-neon-data.ts"
import postgres from 'postgres';
import { createServerFn } from "@tanstack/react-start";
import { staticFunctionMiddleware } from "@tanstack/start-static-server-functions";

const sql = postgres(process.env.DATABASE_URL!, { ssl: 'require' });

export const getData = createServerFn({ method: "GET" })
.middleware([staticFunctionMiddleware])
.handler(async () => {
  const response = await sql`SELECT version()`;
  return response[0].version;
});
```

**Neon serverless driver**

```typescript filename="src/data/get-neon-data.ts"
import { neon } from "@neondatabase/serverless";
import { createServerFn } from "@tanstack/react-start";
import { staticFunctionMiddleware } from "@tanstack/start-static-server-functions";

export const getData = createServerFn({ method: "GET" })
.middleware([staticFunctionMiddleware])
.handler(async () => {
  const sql = neon(process.env.DATABASE_URL!);
  const response = await sql`SELECT version()`;

  return response[0].version;
});
```

Then like before you can consume the data in your components.

_Be aware Static Server Functions are executed at build time, and cached as a static asset for pre-rendering or static generation_.

```typescript filename="src/routes/index.tsx"
import { createFileRoute } from "@tanstack/react-router";
import { getData } from "../data/get-neon-data.ts";

export const Route = createFileRoute("/")({
  loader: async () => {
    return getData();
  },

  component: RouteComponent,
});

export default function RouteComponent() {
  const data = Route.useLoaderData();

  return <>{data}</>;
}
```

## Run the app

When you run `npm run dev` you can expect to see the following on [localhost:3000](http://localhost:3000/):

```shell
PostgreSQL 18.6 (ac70818) on aarch64-unknown-linux-gnu, compiled by gcc (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0, 64-bit
```

### Where to upload and serve files?

Use [Object Storage](https://neon.com/docs/storage/overview), Neon's S3-compatible storage that branches with your database. To use an external provider instead, see [File storage](https://neon.com/docs/guides/file-storage).

## Source code

You can find the source code for the applications described in this guide on GitHub.

- [Get started with TanStack Start Server Functions and Neon](https://github.com/neondatabase/examples/tree/main/with-tanstack-start-server-functions): Get started with TanStack Start Server Functions and Neon
- [Get started with TanStack Start Static Server Functions and Neon](https://github.com/neondatabase/examples/tree/main/with-tanstack-start-static-server-functions): Get started with TanStack Start Static Server Functions and Neon

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/quick-start/tanstack-router): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential
- [Realtime](https://neon.com/docs/realtime/examples/tanstack): Build realtime TanStack apps on Neon with SSR, end-to-end type safety, and reactive client-side development using TanStack DB

--- [Document source](https://neon.com/docs/guides/time-travel-tutorial.md) ---

> Summary: Neon Time Travel tutorial that shows how to use the SQL Editor's Time Travel toggle to run point-in-time SELECT queries and confirm exactly when a feature flag changed state after a CI/CD deployment. Reach for this guide when you need to debug a production regression by comparing database state before and after a specific timestamp, without restoring a branch or snapshot. The tutorial covers creating a feature_flags table, recording the activation timestamp from query history, and verifying pre- and post-activation values with time-scoped queries.

# Time Travel tutorial

Use Time Travel to analyze changes made to your database over time

Last updated: 2026-06-05

This tutorial shows how to use Time Travel to debug a common problem: an issue that appears right after a CI/CD deployment to production.

In this scenario, your team has released a streamlined checkout process behind a `new_checkout_process` feature flag. Soon after the flag was turned on, customer support started getting complaints about checkout. You need to confirm whether the complaints line up with the moment the feature was activated.

## Before you start

To follow this tutorial, you need:

- A Neon account. If you don't have one, see [Sign up](https://neon.com/docs/get-started/signing-up).
- A [history window](https://neon.com/docs/postgres/backup-restore/history-window) that covers the time period you want to query. Time Travel can only query points in time inside your history window.

## Prepare your database

To simulate this scenario, create a `feature_flags` table that controls which features are available.

1. In the Neon Console, select your branch, then open **Postgres database** > **SQL Editor**. This tutorial uses the default `neondb` database.

2. Create the `feature_flags` table:

   ```sql
   CREATE TABLE feature_flags (
       feature_name TEXT PRIMARY KEY,
       enabled BOOLEAN NOT NULL
   );
   ```

3. Add a feature flag that starts out disabled:

   ```sql
   INSERT INTO feature_flags (feature_name, enabled)
   VALUES ('new_checkout_process', FALSE);
   ```

This mirrors a typical release stage: the feature is deployed, but it stays inactive until the flag is turned on.

## Enable the feature flag

Run the following statement in the **SQL Editor** to turn on the feature:

```sql
UPDATE feature_flags SET enabled = TRUE WHERE feature_name = 'new_checkout_process';
```

In production, a step like this usually runs as part of your CI/CD pipeline.

## Find when the feature was enabled

Because the complaints started right after the release, your first step is to pin down exactly when the `new_checkout_process` flag was turned on. In a real investigation, you'd get this timestamp from your deployment logs or CI/CD pipeline history. In this tutorial, the activation time is `2025-08-06 at 10:52 PM IST`.

To find the timestamp of your own `UPDATE`, select **History** in the left pane of the **SQL Editor**:

![SQL Editor History pane showing the timestamp of the UPDATE statement](https://neon.com/docs/guides/time_travel_tutorial_activation.png)

**Note:** The Neon Console shows timestamps in your local time zone. The time in this screenshot, `2025-08-06 at 10:52 PM IST`, is `2025-08-06 at 5:22 PM UTC`.

## Check the flag before activation

Confirm that the feature was disabled just before the flag was turned on.

1. Select the **Time Travel** (🕣) icon in the **SQL Editor** and turn on **Time Travel Enabled**.

2. In the date and time selector, choose a time just before the activation timestamp. This example uses `2025-08-06 at 10:51 PM IST`, one minute before activation.

3. Run the query:

   ```sql
   SELECT * FROM feature_flags WHERE feature_name = 'new_checkout_process';
   ```

   The flag shows `f` (false), as expected.

   ![Time Travel query showing the flag disabled one minute before activation](https://neon.com/docs/guides/time_travel_tutorial_before.png)

## Check the flag after activation

Now check the flag's state just after activation.

1. In the date and time selector, choose a time just after the activation timestamp. This example uses `2025-08-06 at 10:53 PM IST`, one minute after activation.

2. Run the same query again:

   ```sql
   SELECT * FROM feature_flags WHERE feature_name = 'new_checkout_process';
   ```

   The flag now shows `t` (true).

   ![Time Travel query showing the flag enabled one minute after activation](https://neon.com/docs/guides/time_travel_tutorial_after.png)

The flag changed state at the same moment the complaints started, which points to the new checkout process as the likely cause. From here, you can turn off the flag, fix the problem, and update stakeholders.

## Use Time Travel from the CLI

You can run the same point-in-time queries without the Console. The Neon CLI returns a connection string for a branch at a specific timestamp (RFC 3339 format), and `--psql` connects you directly:

```bash
neon connection-string main@2025-08-06T17:21:00Z --psql
```

Then run the same `SELECT` query. For more options, including connecting at a specific LSN, see [Time Travel](https://neon.com/docs/postgres/backup-restore/time-travel-assist).

--- [Document source](https://neon.com/docs/guides/tortoise-orm.md) ---

> Summary: Tortoise ORM is an asyncio-native Python ORM (inspired by Django) that connects to Lakebase Postgres via the asyncpg driver, enabling non-blocking database access in FastAPI, Starlette, and other async frameworks. Use this guide for setup including virtual environment configuration, connection string formatting with ssl=true, model definition, schema generation, and transaction rollback with in_transaction(). It walks through installing tortoise-orm[asyncpg], loading credentials from a .env file with python-dotenv, and avoiding hanging processes by calling Tortoise.close_connections() or using run_async().

# Connect a Tortoise ORM application to Neon

Set up a project on Neon in seconds and connect from a Python async application

Last updated: 2026-09-16

Pre-built prompt for connecting Tortoise ORM applications to Lakebase Postgres [View prompt](https://neon.com/prompts/tortoise-orm-prompt.md)

[Tortoise ORM](https://tortoise.github.io/) is an easy-to-use `asyncio` Object Relational Mapper (ORM) inspired by Django. It is designed specifically for asynchronous Python applications, making it a great choice for building efficient, non-blocking database interactions in frameworks like FastAPI, Starlette, or any custom async application.

In this guide, you'll learn how to set up a Lakebase Postgres project and connect to it using Tortoise ORM with the `asyncpg` driver.

## Prerequisites

To complete the steps in this guide, ensure that you have Python 3.10+ installed. If you do not have Python installed, refer to the [official Python website](https://www.python.org/downloads/) for installation instructions.

To connect to a Lakebase Postgres database from Tortoise ORM:

## Create a Neon project

If you do not have one already, create a Neon project. Save your connection details, including your password. They are required when defining connection settings.

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create**.

## Set up your Python project

Create a new directory for your project and navigate into it:

```bash
mkdir tortoise-neon-demo
cd tortoise-neon-demo
```

Optionally, create and activate a virtual environment to manage your dependencies:

**Tip: Why use a virtual environment?**

Using a virtual environment allows you to manage dependencies for your project in isolation, preventing conflicts with other Python projects on your system. It also makes it easier to maintain and share your project with others.

```bash
python3 -m venv venv
source venv/bin/activate   # macOS / Linux
# venv\Scripts\activate    # Windows
```

## Install dependencies

Install Tortoise ORM, the `asyncpg` Postgres driver, and `python-dotenv` to manage environment variables securely. Tortoise provides a handy extra requirement flag to install `asyncpg` automatically.

Run the following command inside your virtual environment:

```shell
pip install "tortoise-orm[asyncpg]" python-dotenv
```

## Get your connection string

Find your database connection string by clicking the **Connect** button in the Console nav to open the **Connect to your branch** modal. Check the **Parameters only** option, which provides the individual components of the connection string that you will use to construct a connection URL.
![Connection details modal](https://neon.com/docs/connect/connection_details_parameters_only.png)

Create a `.env` file in your project's root directory and add a `DATABASE_URL` variable with the following format:

```text
DATABASE_URL="postgres://[PGUSER]:[PGPASSWORD]@[PGHOST]/[PGDATABASE]?ssl=true"
```

> Replace the placeholders `[PGUSER]`, `[PGPASSWORD]`, `[PGHOST]`, and `[PGDATABASE]` with the corresponding values from your Neon connection details. Make sure to include `ssl=true` to ensure a secure connection.

If you copy a full connection string from the Console instead, remove `-pooler` from the host and replace `sslmode=require&channel_binding=require` with `ssl=true`. Tortoise doesn't accept the `sslmode` parameter.

**Important:** Use a direct (non-pooled) connection string when generating schemas or running migrations (for example, with Aerich). Neon's pooled connection uses PgBouncer in transaction mode, which doesn't support all session-level operations that schema changes rely on, so running them over a pooled connection can lead to errors. Make sure the hostname does not include the `-pooler` suffix. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Create the application

Create a file named `main.py` and add the following code. This script initializes Tortoise ORM, creates a simple `User` schema in your Neon database, inserts a record, and queries it back.

```python
import os
from dotenv import load_dotenv
from tortoise import Tortoise, fields, run_async
from tortoise.models import Model

load_dotenv()

# 1. Define your models
class User(Model):
    id = fields.IntField(primary_key=True)
    name = fields.CharField(max_length=50)
    created_at = fields.DatetimeField(auto_now_add=True)

    class Meta:
        table = "demo_users"

    def __str__(self):
        return self.name

# 2. Define the main async function
async def main():
    database_url = os.getenv("DATABASE_URL")

    try:
        # Initialize Tortoise ORM
        print("Connecting to Neon Postgres...")
        await Tortoise.init(
            db_url=database_url,
            modules={"models": ["__main__"]},  # Looks for models in the current file
        )

        # Generate the schema (creates tables if they don't exist)
        await Tortoise.generate_schemas()

        # Insert a new user
        await User.create(name="Neon User")

        # Query the database
        users = await User.all()
        print(f"Successfully queried the database. Users found: {len(users)}")
        for user in users:
            print(f"- {user.name} (Created: {user.created_at})")

    finally:
        # 3. Clean up and close connections
        print("Closing database connections...")
        await Tortoise.close_connections()

if __name__ == "__main__":
    # run_async is a Tortoise helper that ensures connections are closed
    # if the script exits unexpectedly.
    run_async(main())
```

In this script, the `User` class defines your database schema, mapping Python types directly to PostgreSQL columns. The `Tortoise.init()` method connects to Neon using your connection string, while `generate_schemas()` safely creates the tables if they don't already exist. For real-world applications, you would typically define models in a dedicated file (like `models.py`) and load them into the initialization config using `modules={"models": ["my_project.models"]}`.

Run the script from your terminal:

```bash
python main.py
```

You should see output indicating that the connection was successful, the table was created, and the user was successfully saved and queried.

## Execute a transaction

Tortoise ORM provides an `in_transaction()` async context manager to ensure database operations succeed or fail together. Create a `transactions.py` file to test this:

```python
import os
from dotenv import load_dotenv
from tortoise import Tortoise, run_async
from tortoise.transactions import in_transaction
from main import User

load_dotenv()

async def transaction_demo():
    await Tortoise.init(
        db_url=os.getenv("DATABASE_URL"), modules={"models": ["__main__"]}
    )

    try:
        # Execute operations inside a transaction block
        async with in_transaction():
            user = await User.create(name="Alice")
            print(f"Created: {user.name}")

            # Simulating an error that triggers a rollback
            raise ValueError("Something went wrong! Rolling back...")

            await User.create(name="Bob")  # This won't happen

    except ValueError as e:
        print(f"Error caught: {e}")

    # Verify Alice was not saved
    count = await User.filter(name="Alice").count()
    print(f"Records named 'Alice' in database: {count}")

    await Tortoise.close_connections()


if __name__ == "__main__":
    run_async(transaction_demo())
```

The `in_transaction()` block ensures an all-or-nothing execution. Because the simulated `ValueError` interrupts the process, Tortoise automatically rolls back the transaction, preventing the partial insertion of "Alice" into the database.

<details>

<summary>**Notes for AI-assisted setup**</summary>

- Do not install packages globally. Always use a virtual environment and run commands with `venv/bin/pip` and `venv/bin/python` (or the activated equivalent).
- Install Tortoise ORM with the `asyncpg` extra: `pip install "tortoise-orm[asyncpg]"`.
- Tortoise picks the `asyncpg` driver from the `postgres://` or `postgresql://` scheme. Use `postgres://` as shown in this guide.
- Always include `ssl=true` in your connection string to ensure a secure connection to Neon. Don't use `sslmode=require`. The asyncpg backend in Tortoise rejects it with a `TypeError`.
- Always ensure `await Tortoise.close_connections()` is called during application teardown or use the `tortoise.run_async()` wrapper to prevent hanging python processes.
- Do not hardcode credentials in initialization scripts. Use environment variables via `python-dotenv` and `os.getenv()`.

</details>

## Resources

- [Tortoise ORM documentation](https://tortoise.github.io/)
- [asyncpg documentation](https://magicstack.github.io/asyncpg/current/)

## Next steps

- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/trigger-serverless-functions.md) ---

> Summary: Inngest integration lets Neon database changes trigger serverless functions on Vercel, AWS Lambda, or Cloudflare Workers by routing logical replication events through Inngest. Use this guide when you need event-driven workflows (onboarding emails, ETL, AI pipelines) that react to Postgres row inserts, updates, or deletes without polling. Covers enabling logical replication, installing the Inngest client, writing TypeScript Inngest functions, and syncing with the Inngest platform across all three serverless runtimes.

# Trigger serverless functions

Use Inngest to trigger serverless functions from your Neon database changes

Last updated: 2026-09-16

Combining your serverless Neon database with [Inngest](https://www.inngest.com/?utm_source=neon\&utm_medium=trigger-serverless-functions-guide) enables you to **trigger serverless functions** running on Vercel, AWS, and Cloudflare Worker **based on database changes.**

By enabling your serverless functions to react to database changes, you open the door to many use cases. From onboarding to ETL and AI workflows, the possibilities are endless.

![trigger serverless functions with inngest](https://neon.com/docs/guides/inngest.jpg)

This guide describes setting up a Neon database, configuring the Inngest integration, and connecting your Serverless functions to your Neon database with Inngest. It covers:

- Creating a Neon project and enabling [Logical Replication](https://neon.com/docs/guides/logical-replication-guide).
- Configuring the Inngest integration on your Neon database.
- Configure your Vercel, AWS, or Cloudflare functions to react to your Neon database changes using Inngest.

## Prerequisites

- A Neon account. If you do not have one, see [Sign up](https://neon.com/docs/get-started/signing-up) for instructions.
- An Inngest account. You can create a free Inngest account by [signing up](https://app.inngest.com/sign-up?utm_source=neon\&utm_medium=trigger-serverless-functions-guide).

## Create a Neon project

If you do not have one already, create a Neon project:

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.

## Create a table in Neon

To create a table, navigate to **Postgres database** > **SQL Editor** in the [Neon Console](https://console.neon.tech/):

In the SQL Editor, run the following queries to create a `users` table and insert some data:

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

INSERT INTO users (name, email)
VALUES
    ('Alice', 'alice@example.com'),
    ('Bob', 'bob@example.com'),
    ('Charlie', 'charlie@example.com'),
    ('Dave', 'dave@example.com'),
    ('Eve', 'eve@example.com');
```

## Enabling Logical Replication on your database

The Inngest Integration relies on Neon's Logical Replication feature to get notified upon database changes.

Navigate to your Neon Project using the Neon Console and open the **Settings** > **Postgres** page. From here, follow the instructions to enable Logical Replication:

![Neon dashboard settings with option to enable logical replication](https://neon.com/docs/guides/neon-console-settings-logical-replication.png)

## Configuring the Inngest integration

Your Neon database is now ready to work with Inngest.

To configure the Inngest Neon Integration, navigate to the Inngest Platform, open the [Integrations page](https://app.inngest.com/settings/integrations?utm_source=neon\&utm_medium=trigger-serverless-functions-guide), and follow the instructions of the [Neon Integration installation wizard](https://app.inngest.com/settings/integrations/neon/connect?utm_source=neon\&utm_medium=trigger-serverless-functions-guide):

![Neon integration card inside the Inngest integrations page](https://neon.com/docs/guides/inngest-integrations-page.png)

The Inngest Integration requires Postgres admin credentials to complete its setup. _These credentials are not stored and are only used during the installation process_.

![Neon authorization step inside the Inngest integrations page](https://neon.com/docs/guides/inngest-integration-neon-authorize-step.png)

You can find the connection string for your database by clicking the **Connect** button in the Console nav.

![Connection modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

## Triggering Serverless functions from database changes

Any changes to your Neon database are now dispatched to your Inngest account.  
To enable your Serverless functions to react to database changes, we will:

- Install the Inngest client to your Serverless project
- Expose a serverless endpoint enabling Inngest to discover your Serverless functions
- Configure your Serverless application environment variables
- Connect a Serverless function to any change performed to the `users` table.

### 1. Configuring the Inngest client

First, install the Inngest client:

```bash
npm i inngest
```

Then, create a `inngest/client.ts` (_or `inngest/client.js`_) file as follows:

```typescript
// inngest/client.ts
import { Inngest } from 'inngest';

export const inngest = new Inngest({ id: 'neon-inngest-project' });
```

### 2. Listen for new `users` rows

Any change performed on our Neon database will trigger an [Inngest Event](https://www.inngest.com/docs/features/events-triggers?utm_source=neon\&utm_medium=trigger-serverless-functions-guide) as follows:

```json
{
  "name": "db/users.inserted",
  "data": {
    "new": {
      "id": {
        "data": 2,
        "encoding": "i"
      },
      "name": {
        "data": "Charly",
        "encoding": "t"
      },
      "email": {
        "data": "charly@inngest.com",
        "encoding": "t"
      }
    },
    "table": "users",
    "txn_commit_time": "2024-09-24T14:41:19.75149Z",
    "txn_id": 36530520
  },
  "ts": 1727146545006
}
```

Inngest enables you to create [Inngest Functions](https://www.inngest.com/docs/features/inngest-functions?utm_source=neon\&utm_medium=trigger-serverless-functions-guide) that react to Inngest events (here, database changes).

Let's create an Inngest Function listening for `"db/users.inserted"` events:

```typescript
// inngest/functions/new-user.ts
import { inngest } from '../client'

export newUser = inngest.createFunction(
  { id: "new-user" },
  { event: "db/users.inserted" },
  async ({ event, step }) => {
    const user = event.data.new

    await step.run("send-welcome-email", async () => {
      // Send welcome email
      await sendEmail({
        template: "welcome",
        to: user.email,
      });
    });

    await step.sleep("wait-before-tips", "3d");

    await step.run("send-new-user-tips-email", async () => {
      // Follow up with some helpful tips
      await sendEmail({
        template: "new-user-tips",
        to: user.email,
      });
    });
  }
)
```

### 3. Exposing your Serverless Functions to Inngest

To allow Inngest to run your Inngest Functions, add the following Serverless Function, which serves as a router:

**Vercel**

```typescript
// src/app/api/inngest/route.ts
import { serve } from 'inngest/next';
import { inngest } from '@lib/inngest/client';
import newUsers from '@lib/inngest/functions/newUsers'; // Your own functions

export const { GET, POST, PUT } = serve({
  client: inngest,
  functions: [newUsers],
});
```

**AWS Lambda**

```typescript
import { serve } from 'inngest/lambda';
import { inngest } from './client';
import newUsers from './functions/newUsers'; // Your own function

export const handler = serve({
  client: inngest,
  functions: [newUsers],
});
```

**Cloudflare Workers**

```js
// /functions/api/inngest.js
import { serve } from 'inngest/cloudflare';
import { inngest } from './client';
import newUsers from './functions/newUsers';

export default {
  fetch: serve({
    client: inngest,
    functions: [newUsers],
  }),
};
```

**Note:** You can find more information about serving Inngest Functions in [Inngest's documentation](https://www.inngest.com/docs/reference/serve?utm_source=neon\&utm_medium=trigger-serverless-functions-guide#serve-client-functions-options).

### 4. Configuring your Serverless application

We can now configure your Serverless application to sync with the Inngest Platform:

- **Vercel:** Configure the [Inngest Vercel Integration](https://www.inngest.com/docs/deploy/vercel?utm_source=neon\&utm_medium=trigger-serverless-functions-guide).
- **AWS Lambda:** Configure a [Lambda function URLs](https://docs.aws.amazon.com/lambda/latest/dg/lambda-urls.html) and [sync your serve Lambda with Inngest](https://www.inngest.com/docs/apps/cloud?utm_source=neon\&utm_medium=trigger-serverless-functions-guide#sync-a-new-app-in-inngest-cloud).
- **Cloudflare Workers:** [Add the proper environment variables](https://www.inngest.com/docs/deploy/cloudflare?utm_source=neon\&utm_medium=trigger-serverless-functions-guide) to your Cloudflare Pages project and [sync with Inngest](https://www.inngest.com/docs/apps/cloud?utm_source=neon\&utm_medium=trigger-serverless-functions-guide#sync-a-new-app-in-inngest-cloud).

### 5. Testing our Serverless function

We are now all set!

Go to the **Tables** page in the Neon Console and add a new record to the `users` table:

![You can add a new record to the users table directly from the Neon console](https://neon.com/docs/guides/inngest-integration-neon-console-users-table-add-new-record.png)

You should see a new run of the `new-user` function appear on the [Inngest Platform](https://app.inngest.com/?utm_source=neon\&utm_medium=trigger-serverless-functions-guide):

![The Inngest Platform lists all the runs](https://neon.com/docs/guides/inngest-integrations-inngest-platform-new-runs.png)

## Going further

Your Serverless functions can now react to your Neon database changes.

In addition to being good for system design, Inngest has some special features that work great with database triggers:

- **[Fan-out](https://www.inngest.com/docs/guides/fan-out-jobs?utm_source=neon\&utm_medium=trigger-serverless-functions-guide)**: Lets **one database event start multiple functions** at the same time. For example, when a new user is added, it could send a welcome email and set up a free trial, all at once.
- **[Batching](https://www.inngest.com/docs/guides/batching?utm_source=neon\&utm_medium=trigger-serverless-functions-guide)** **Groups many database changes together** to handle them more efficiently. It's useful when you need to update lots of things at once, like when working with online stores.
- **[Flow control](https://www.inngest.com/docs/guides/flow-control?utm_source=neon\&utm_medium=trigger-serverless-functions-guide)**: Helps manage how often functions run. It can slow things down to **avoid overloading systems, or wait a bit to avoid doing unnecessary work**. This is helpful when working with other services that have limits on how often you can use them.

--- [Document source](https://neon.com/docs/guides/typeorm.md) ---

> Summary: TypeORM connects to Lakebase Postgres through the `pg` driver: install `pg`, set the `DataSource` type to `postgres`, load the connection string from `DATABASE_URL` with `dotenv`, and enable `ssl: true`. Serverless deployments should use a pooled connection string (add `-pooler` to the endpoint ID) to handle high concurrency without exhausting connections. If you set TypeORM's `connectTimeoutMS`, leave room for a suspended compute to start.

# Connect from TypeORM to Neon

Learn how to connect to Lakebase Postgres from TypeORM

Last updated: 2026-09-16

Pre-built prompt for connecting Node.js applications to Lakebase Postgres using TypeORM. [View prompt](https://neon.com/prompts/typeorm-prompt.md)

TypeORM is an open-source ORM for TypeScript and JavaScript. This guide assumes you have a TypeORM project. To create one, run `npx typeorm init --name my-project --database postgres`. This guide covers the following topics:

- [Connect to a database on Neon from TypeORM](https://neon.com/docs/guides/typeorm#connect-to-a-database-on-neon-from-typeorm)
- [Use connection pooling with TypeORM](https://neon.com/docs/guides/typeorm#use-connection-pooling-with-typeorm)
- [Connection timeouts](https://neon.com/docs/guides/typeorm#connection-timeouts)

## Connect to a database on Neon from TypeORM

To establish a basic connection from TypeORM to a database on Neon, perform the following steps:

1. Retrieve your database connection string. You can find the connection string for your database by clicking the **Connect** button in the Console nav. Select a branch, a user, and the database you want to connect to. A connection string is constructed for you.
   ![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)
   The connection string includes the user name, password, hostname, and database name.

2. Install the `pg` driver, which TypeORM uses for Postgres, and `dotenv` to load your `.env` file. `npx typeorm init` doesn't install `pg`.

   ```bash
   npm install pg dotenv
   ```

3. Update the TypeORM `DataSource` initialization in your application (`src/data-source.ts` in a project created with `typeorm init`) to the following. Replace the `host`, `port`, `username`, `password`, and `database` options with `url`, and keep your other options, such as `entities` and `migrations`.

   ```typescript {1,7,8}
   import 'dotenv/config';
   import 'reflect-metadata';
   import { DataSource } from 'typeorm';

   export const AppDataSource = new DataSource({
     type: 'postgres',
     url: process.env.DATABASE_URL,
     ssl: true,
     entities: [
       /*list of entities*/
     ],
   });
   ```

   The `import 'dotenv/config'` line loads `.env` before the `DataSource` reads `process.env.DATABASE_URL`. Without it, `DATABASE_URL` is undefined and TypeORM tries to connect to `localhost`.

4. Create a `.env` file in your project root, add a `DATABASE_URL` variable, and set it to the connection string you copied in the first step. Add `.env` to your `.gitignore` so you don't commit the password.

   ```text
   DATABASE_URL="postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require"
   ```

   `pg` 8.23 and later print a `SECURITY WARNING` when a connection string uses `sslmode=require`. Change `sslmode=require` to `sslmode=verify-full` to keep the current behavior and remove the warning. For more about SSL modes, see [Connect securely](https://neon.com/docs/connect/connect-securely).

5. Run your application. In a project created with `typeorm init`, run `npm start`. The sample app inserts a user and prints the users it loads from your database.

**Tip:** TypeORM uses a [node-postgres](https://node-postgres.com) `Pool` to connect to your Postgres database. Installing [pg-native](https://npmjs.com/package/pg-native) and setting the `NODE_PG_FORCE_NATIVE` environment variable to `true` switches the `pg` driver to `pg-native`, which uses the `libpq` C library.

## Use connection pooling with TypeORM

Serverless functions can require a large number of database connections as demand increases. If you use serverless functions in your application, we recommend that you use a pooled Neon connection string, as shown:

```ini
# Pooled Neon connection string
DATABASE_URL="postgresql://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require"
```

A pooled Neon connection string adds `-pooler` to the endpoint ID, which tells Neon to use a pooled connection. You can add `-pooler` to your connection string manually or copy a pooled connection string from the **Connect to your branch** modal, which you can access by clicking **Connect** in the Console nav. Enable the **Connection pooling** toggle to add the `-pooler` suffix.

**Important:** Use a pooled connection string for your application at runtime, but use a direct (non-pooled) connection string when running TypeORM migrations. Neon's pooled connection uses PgBouncer in transaction mode, which doesn't support all session-level operations that migration tools rely on, so running migrations over a pooled connection can lead to errors. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Connection timeouts

If your compute has been suspended after a period of inactivity, the first connection starts it again. This usually takes a few hundred milliseconds. See [Scale to zero](https://neon.com/docs/introduction/scale-to-zero).

By default, TypeORM waits for a connection with no timeout. If you set a timeout with TypeORM's `connectTimeoutMS` option, give it enough time for the compute to start:

```typescript {5}
export const AppDataSource = new DataSource({
  type: 'postgres',
  url: process.env.DATABASE_URL,
  ssl: true,
  connectTimeoutMS: 10000,
  entities: [
    /*list of entities*/
  ],
});
```

When the timeout is reached, `pg` throws `Error: Connection terminated due to connection timeout`.

**Note:** TypeORM ignores the `connect_timeout` parameter in the connection string. Use `connectTimeoutMS` instead.

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/guides/uploadcare.md) ---

> Summary: Uploadcare and Lakebase Postgres integration pattern stores uploaded files on Uploadcare's CDN while persisting each file's UUID, CDN URL, and user ID as metadata rows in a Lakebase Postgres table. Use this guide when you need a dedicated CDN for images, videos, and documents but want queryable, structured metadata in Postgres rather than in Uploadcare alone. Code examples cover a Node.js/Hono server and a Python Flask server, both writing to an uploadcare_files table with optional Row Level Security.

# Media storage with Uploadcare

Store files via Uploadcare and track metadata in Lakebase Postgres

Last updated: 2026-09-16

[Uploadcare](https://uploadcare.com/) provides a cloud platform designed to simplify file uploading, processing, storage, and delivery via a fast CDN. It offers tools that manage and optimize media like images, videos, and documents for your applications.

**Neon now offers native storage:**

Neon Object Storage is S3-compatible object storage built into the Neon backend. Object storage branches with your database: each branch gets its own isolated namespace, so you can test file uploads in preview branches without touching production. No separate cloud account needed. Use any S3-compatible SDK with your existing Neon credential.

For more information, see [Neon Object Storage](https://neon.com/docs/storage/overview).

This guide demonstrates how to integrate Uploadcare with Lakebase Postgres by storing file metadata in your Lakebase Postgres database while using Uploadcare for file uploads and storage.

## Setup steps

## Create a project on Neon

1. Navigate to the Neon Console to create a new project.
2. Copy the connection string by clicking the **Connect** button in the Console nav. For more information, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## Create an Uploadcare account and project

1. Sign up for an account at [Uploadcare.com](https://uploadcare.com/).
2. Create a new project within your Uploadcare dashboard.
3. Navigate to your project's **API Keys** section.
4. Note your **Public Key** and **Secret Key**. They are needed to interact with the Uploadcare API and widgets.
   ![Uploadcare API Keys](https://neon.com/docs/guides/uploadcare-api-keys.png)

## Create a table for file metadata

We need to create a table to store metadata about the files uploaded to Uploadcare. This table will include fields for the file's unique identifier, URL, upload timestamp, and any other relevant metadata you want to track.

1. You can run the create table statement using the SQL Editor or from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) that is connected to your database. Here is an example SQL statement to create a simple table for file metadata which includes a file ID, URL, user ID, and upload timestamp:

   ```sql
   CREATE TABLE IF NOT EXISTS uploadcare_files (
       id SERIAL PRIMARY KEY,
       file_id TEXT NOT NULL UNIQUE,
       file_url TEXT NOT NULL,
       user_id TEXT NOT NULL,
       upload_timestamp TIMESTAMPTZ DEFAULT NOW()
   );
   ```

2. Run the SQL statement. You can add other relevant columns (file size, content type, etc.) depending on your application needs.

**Note: Securing metadata with RLS**

If you use [Neon's Row Level Security (RLS)](https://neon.com/blog/introducing-neon-authorize), remember to apply appropriate access policies to the `uploadcare_files` table. This controls who can view or modify the object references stored in Neon based on your RLS rules.

Note that these policies apply _only_ to the metadata stored in Neon. Access to the actual files is managed by Uploadcare's access controls and settings.

## Upload files to Uploadcare and store metadata in Neon

You can integrate file uploads using any of Uploadcare's [many options](https://uploadcare.com/docs/integrations/), which include UI widgets and SDKs tailored for specific languages and frameworks. For the examples in this guide, we will use the Uploadcare API directly. Feel free to choose the integration method that best fits your project; the fundamental approach of storing metadata in Neon remains the same.

**JavaScript**

For this example, we'll build a simple Node.js server using [Hono](https://hono.dev/) to handle file uploads. It will use the [`@uploadcare/upload-client`](https://www.npmjs.com/package/@uploadcare/upload-client) package to upload files to Uploadcare and [`@neondatabase/serverless`](https://www.npmjs.com/package/@neondatabase/serverless) package to save metadata into your Neon database.

First, install the necessary dependencies:

```bash
npm install @uploadcare/upload-client @neondatabase/serverless @hono/node-server hono
```

Create a `.env` file in your project root and add your Uploadcare and Neon connection details which you obtained in the previous steps:

```env
UPLOADCARE_PUBLIC_KEY=your_uploadcare_public_key
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```javascript
import { serve } from '@hono/node-server';
import { Hono } from 'hono';
import { uploadFile } from '@uploadcare/upload-client';
import { neon } from '@neondatabase/serverless';
import 'dotenv/config';

const sql = neon(process.env.DATABASE_URL);
const app = new Hono();

// Replace this with your actual user authentication logic, by validating JWTs/Headers, etc.
const authMiddleware = async (c, next) => {
  c.set('userId', 'user_123'); // Example: Get user ID after validation
  await next();
};

app.post('/upload', authMiddleware, async (c) => {
  try {
    // 1. Get User ID and File Data
    const userId = c.get('userId');
    const formData = await c.req.formData();
    const file = formData.get('file');
    const fileName = formData.get('fileName') || file.name;
    const buffer = Buffer.from(await file.arrayBuffer());

    // 2. Upload to Uploadcare
    const result = await uploadFile(buffer, {
      publicKey: process.env.UPLOADCARE_PUBLIC_KEY,
      fileName: fileName,
      contentType: file.type,
    });

    // 3. Save Metadata to Neon
    // Uses file_id (Uploadcare UUID), file_url (CDN URL), and user_id
    await sql`
            INSERT INTO uploadcare_files (file_id, file_url, user_id)
            VALUES (${result.uuid}, ${result.cdnUrl}, ${userId})
        `;

    console.log(`Uploaded ${result.uuid} for user ${userId} to ${result.cdnUrl}`);

    return c.json({ success: true, fileUrl: result.cdnUrl });
  } catch (error) {
    console.error('Upload Error:', error);
    return c.json({ success: false, error: 'Upload failed' }, 500);
  }
});

const port = 3000;
serve({ fetch: app.fetch, port }, (info) => {
  console.log(`Server running at http://localhost:${info.port}`);
});
```

**Explanation**

1. **Setup:** It initializes the Neon database client and the Hono web framework. It relies on environment variables (`DATABASE_URL`, `UPLOADCARE_PUBLIC_KEY`) being set, via a `.env` file.
2. **Authentication:** A placeholder `authMiddleware` is included. **Crucially**, this needs to be replaced with real authentication logic. It currently just sets a static `userId` for demonstration.
3. **Upload Endpoint (`/upload`):**
   - It expects a `POST` request with `multipart/form-data`.
   - It retrieves the user ID set by the middleware.
   - It extracts the `file` data and `fileName` from the form data.
   - It uploads the file content directly to Uploadcare.
   - Upon successful upload, Uploadcare returns details including a unique `uuid` and a `cdnUrl`.
   - It executes an `INSERT` statement using the Neon serverless driver to save the `uuid`, `cdnUrl`, and the `userId` into a `uploadcare_files` table in your database.
   - It sends a JSON response back to the client containing the `fileUrl` from Uploadcare.

**Python**

For this example, we'll build a simple [Flask](https://flask.palletsprojects.com/en/stable/) server to handle file uploads. It will use the [`pyuploadcare`](https://pypi.org/project/pyuploadcare/) package to upload files to Uploadcare and [`psycopg2`](https://pypi.org/project/psycopg2/) to save metadata into your Neon database.

First, install the necessary dependencies:

```bash
pip install Flask pyuploadcare psycopg2-binary python-dotenv
```

Create a `.env` file in your project root and add your Uploadcare and Neon connection details which you obtained in the previous steps:

```env
UPLOADCARE_PUBLIC_KEY=your_uploadcare_public_key
UPLOADCARE_SECRET_KEY=your_uploadcare_secret_key
DATABASE_URL=your_neon_database_connection_string
```

The following code snippet demonstrates this workflow:

```python
import os

import psycopg2
from dotenv import load_dotenv
from flask import Flask, jsonify, request
from pyuploadcare import Uploadcare

load_dotenv()


# Use a global PostgreSQL connection instead of creating a new one for each request in production
def get_database():
    return psycopg2.connect(os.getenv("DATABASE_URL"))


# Replace this with your actual user authentication logic, by validating JWTs/Headers, etc.
def get_authenticated_user_id(request):
    return "user_123"  # Example: Get user ID after validation


uploadcare = Uploadcare(
    public_key=os.getenv("UPLOADCARE_PUBLIC_KEY"),
    secret_key=os.getenv("UPLOADCARE_SECRET_KEY"),
)

app = Flask(__name__)


@app.route("/upload", methods=["POST"])
def upload_file():
    try:
        # 1. Get User ID and File from the request
        user_id = get_authenticated_user_id(request)
        file = request.files["file"]

        if file:
            # 2. Upload the file to Uploadcare
            response = uploadcare.upload(file)
            file_url = response.cdn_url

            # 3. Save Metadata to Neon
            # Uses file_id (Uploadcare UUID), file_url (CDN URL), and user_id
            conn = get_database()
            cursor = conn.cursor()
            cursor.execute(
                "INSERT INTO uploadcare_files (file_id, file_url, user_id) VALUES (%s, %s, %s)",
                (response.uuid, file_url, user_id),
            )
            conn.commit()
            cursor.close()
            conn.close()

            return jsonify({"success": True, "fileUrl": response.cdn_url})
        else:
            return jsonify({"success": False, "error": "No file provided"})
    except Exception as e:
        print(f"Upload Error: {e}")
        return jsonify({"success": False, "error": "File upload failed"}), 500


if __name__ == "__main__":
    app.run(port=3000, debug=True)
```

**Explanation**

1. **Setup:** Initializes the Flask web framework, Uploadcare client, and the PostgreSQL client (`psycopg2`) using environment variables.
2. **Authentication:** A placeholder `get_authenticated_user_id` function is included. **Replace this with real authentication logic.**
3. **Upload Endpoint (`/upload`):**
   - It expects a `POST` request with `multipart/form-data`.
   - It retrieves the user ID set by the authentication function.
   - It extracts the `file` data from the form data.
   - It uploads the file content directly to Uploadcare.
   - Upon successful upload, Uploadcare returns details including a unique `uuid` and a `cdnUrl`.
   - It executes an `INSERT` statement using `psycopg2` to save the `uuid`, `cdnUrl`, and the `userId` into a `uploadcare_files` table in your database.
   - It sends a JSON response back to the client containing the `fileUrl` from Uploadcare.
4. In production, you should use a global PostgreSQL connection instead of creating a new one for each request. This is important for performance and resource management.

## Testing the upload endpoint

Once your server (Node.js or Python example) is running, you can test the `/upload` endpoint to ensure files are correctly sent to Uploadcare and their metadata is stored in Neon.

You'll need to send a `POST` request with `multipart/form-data` containing a field named `file`.

Open your terminal and run a command similar to this, replacing `/path/to/your/image.jpg` with the actual path to a file you want to upload:

```bash
curl -X POST http://localhost:3000/upload \
    -F "file=@/path/to/your/image.jpg" \
    -F "fileName=my-test-image.jpg"
```

- `-X POST`: Specifies the HTTP method.
- `http://localhost:3000/upload`: The URL of your running server's endpoint.
- `-F "file=@/path/to/your/image.jpg"`: Specifies a form field named `file`. The `@` symbol tells cURL to read the content from the specified file path.
- `-F "fileName=my-test-image.jpg"`: Sends an additional form field `fileName`.

**Expected outcome:**

- You should receive a JSON response similar to:
  ```json
  {
    "success": true,
    "fileUrl": "https://ucarecdn.com/xxxxxx-xxxxxx-xxxxx/"
  }
  ```

You can now integrate calls to this `/upload` endpoint from various parts of your application (for example, web clients, mobile apps, backend services) to handle file uploads.

## Accessing file metadata and files

Storing metadata in Neon allows your application to easily retrieve references to the files uploaded to Uploadcare.

Query the `uploadcare_files` table from your application's backend when needed.

**Example SQL query:**

Retrieve files for user 'user_123':

```sql
SELECT
    id,              -- Your database primary key
    file_id,         -- Uploadcare UUID
    file_url,        -- Uploadcare CDN URL
    user_id,         -- The user associated with the file
    upload_timestamp
FROM
    uploadcare_files
WHERE
    user_id = 'user_123'; -- Use actual authenticated user ID
```

**Using the data:**

- The query returns rows containing the file metadata stored in Neon.
- The crucial piece of information is the `file_url`. This is the direct link (CDN URL) to the file stored on Uploadcare.
- You can use this `file_url` in your application (for example, in frontend `<img>` tags, API responses, download links) wherever you need to display or provide access to the file.

This pattern separates file storage and delivery (handled by Uploadcare) from structured metadata management (handled by Neon).

## Resources

- [Uploadcare documentation](https://uploadcare.com/docs/)
- [Uploadcare access control with signed URLs](https://uploadcare.com/docs/security/secure-delivery/)

--- [Document source](https://neon.com/docs/guides/vercel-branch-cleanup.md) ---

> Summary: Neon preview branch cleanup in the Vercel-Managed integration is triggered by Vercel deployment deletion, not Git branch deletion, so branches can persist up to 6 months under Vercel's default retention policy. To clean up sooner, lower Vercel's pre-production retention period, delete deployments manually via the Vercel CLI or API, or add a GitHub Action using neondatabase/delete-branch-action that fires on pull_request closed events. Stale branches count toward plan branch limits and incur storage costs even after being auto-archived.

# Managing Vercel preview branch cleanup

Understand cleanup timing and reduce branch accumulation for the Vercel-Managed integration

Last updated: 2026-09-25

**What you will learn:**

- [How branch cleanup differs between integration types](https://neon.com/docs/guides/vercel-branch-cleanup#how-cleanup-works)
- [Why Vercel's retention policy delays cleanup](https://neon.com/docs/guides/vercel-branch-cleanup#why-branches-arent-cleaned-up-immediately)
- [How to reduce the retention period](https://neon.com/docs/guides/vercel-branch-cleanup#reducing-vercels-retention-policy)
- [How to set up immediate cleanup via GitHub Actions](https://neon.com/docs/guides/vercel-branch-cleanup#workarounds-for-immediate-cleanup)

**Related topics**

- [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration)
- [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration)
- [Branch archiving](https://neon.com/docs/guides/branch-archiving)
- [Branch expiration](https://neon.com/docs/guides/branch-expiration)

---

## How cleanup works

When you use Neon's Vercel integration, a Neon database branch is created for each Git branch that has a preview deployment. These are called preview branches. The two integration types handle cleanup of these branches differently:

- **Vercel-Managed Integration**: Neon deletes a preview branch when its last associated Vercel deployment is deleted. This can happen in two ways:
  - Vercel **automatically** removes it through its [deployment retention policy](https://vercel.com/docs/deployment-retention) (which can take months).
  - You **manually** delete the Vercel deployment (which triggers immediate Neon cleanup)
- **Neon-Managed Integration**: Neon deletes a preview branch when the corresponding Git branch no longer exists in your repository. This is triggered the next time a preview deployment is created.

**Tip: Using the Neon-Managed integration?**

If you're using the **Neon-Managed integration**, your branch cleanup is based on Git branch deletion and is not affected by Vercel's deployment retention policies. The rest of this page applies to the **Vercel-Managed integration** only. For Neon-Managed cleanup details, see [Branch cleanup](https://neon.com/docs/guides/neon-managed-vercel-integration#branch-cleanup).

---

## Why branches aren't cleaned up immediately

If you're using the **Vercel-Managed integration**, you might expect preview branches to be deleted when you close a PR or delete a Git branch. That doesn't happen because cleanup is tied to **deployment deletion**, not Git branch deletion. Manually deleting a Vercel deployment triggers immediate Neon branch cleanup, but most teams rely on Vercel's automatic retention, which follows this timeline:

1. **Vercel retains preview deployments for 6 months by default.** As of [October 2025](https://vercel.com/changelog/updated-defaults-for-deployment-retention), Vercel's default retention for pre-production deployments is 180 days. The clock starts when the deployment is created, not when the PR is closed.
2. **Vercel's cleanup job runs asynchronously.** Vercel marks an expired deployment for deletion within about 48 hours. If a [retention exception](https://neon.com/docs/guides/vercel-branch-cleanup#retention-exceptions) still protects it, deletion waits until the exception no longer applies, and that re-evaluation can take up to 30 days. Vercel offers a [30-day recovery window](https://vercel.com/docs/deployment-retention#restoring-a-deleted-deployment) to restore deleted deployments, but this does not delay cleanup for connected integrations.
3. **Neon deletes the branch when Vercel deletes the deployment.** Neon receives a cleanup webhook and removes the corresponding preview branch immediately.

Vercel's current default retention periods:

| Plan               | Canceled | Errored | Pre-Production (Preview) | Production |
| ------------------ | -------- | ------- | ------------------------ | ---------- |
| Hobby              | 30 days  | 30 days | 30 days                  | 30 days    |
| Pro and Enterprise | 30 days  | 90 days | 180 days                 | 1 year     |

Preview deployments use the Pre-Production column. Production retention matters here too, because production deployments count toward the "last 10 deployments" exception described below.

In the worst case (a deployment created moments before the PR is closed), this means up to **~6 months** before the Neon branch is automatically deleted, and longer, potentially never, if a [retention exception](https://neon.com/docs/guides/vercel-branch-cleanup#retention-exceptions) keeps one of the branch's deployments alive.

**Warning: Restoring deleted deployments**

Vercel lets you [restore deleted deployments](https://vercel.com/docs/deployment-retention#restoring-a-deleted-deployment) within a 30-day recovery window. However, restoring a Vercel deployment does **not** restore the associated Neon branch. The restored deployment will have no database behind it. To recover, you would need to recreate the Neon branch manually or push a new commit to trigger the integration.

### Retention exceptions

Vercel keeps some deployments regardless of your retention setting. A deployment is kept while any of these is true (see [Vercel's retention exceptions](https://vercel.com/docs/deployment-retention#exceptions-to-the-retention-policy) for the full list):

- It is one of the last 10 deployments created in the project (production and preview combined).
- It is one of the last 20 non-production (preview) deployments in state Ready.
- It is the latest preview deployment for a Git branch whose pull request is still open. While a PR is open, that branch's latest preview deployment, and the Neon branch behind it, stay protected. A branch whose PR was merged or closed, or that never had a PR at all, does not get this protection, so its preview deployment is cleaned up on the normal retention schedule.
- It has a custom alias assigned.

These exceptions protect _deployments_, not branches, and they are the usual reason a preview branch is "never" cleaned up. In particular, a project with fewer than about 20 preview deployments may never auto-delete any preview branch, because every preview stays within the last-20 set. For those projects, reducing retention does nothing on its own, and the [GitHub Action approach](https://neon.com/docs/guides/vercel-branch-cleanup#github-action-on-pr-close-recommended) is the reliable path.

The following screenshot shows Vercel's default retention policy settings, where pre-production deployments are set to 180 days:

![Vercel retention policy defaults](https://neon.com/docs/guides/vercel_retention_policy_defaults.png)

---

## Reducing Vercel's retention policy

Lowering the retention period reduces how long Vercel keeps deployments before deleting them. This is most effective for projects with many preview deployments. For projects with low deployment activity, [retention exceptions](https://neon.com/docs/guides/vercel-branch-cleanup#retention-exceptions) may prevent automatic cleanup entirely, and the [GitHub Action approach](https://neon.com/docs/guides/vercel-branch-cleanup#github-action-on-pr-close-recommended) is a better option.

To adjust your retention settings:

1. Open your Vercel project dashboard
2. Open **Settings**
3. Find the **Deployment Retention Policy** section (currently under **Build and Deployment**)
4. Set **Pre-Production Deployments** to the shortest available duration
5. Save

After the retention period expires, Vercel marks the deployment for deletion within about 48 hours, and longer if an exception still applies. To avoid waiting for retention entirely, you can [delete deployments manually](https://neon.com/docs/guides/vercel-branch-cleanup#delete-vercel-deployments) or use a [GitHub Action](https://neon.com/docs/guides/vercel-branch-cleanup#github-action-on-pr-close-recommended).

For more details, see [Vercel's deployment retention documentation](https://vercel.com/docs/deployment-retention#setting-a-deployment-retention-policy).

**Note:** You can also set a default retention policy for all new projects in your **Team Settings**, in the **Deployment Retention Policy** section.

---

## Workarounds for immediate cleanup

If reducing retention isn't fast enough, you can trigger immediate cleanup by deleting deployments or branches directly.

### Delete Vercel deployments

You can delete Vercel preview deployments from the Vercel dashboard, or programmatically using the [Vercel CLI](https://vercel.com/docs/cli/remove) (`vercel remove`) or the [Vercel API](https://vercel.com/docs/rest-api/endpoints/deployments#delete-a-deployment) (`DELETE /v13/deployments/{id}`). When you delete the last deployment associated with a Git branch, Neon receives a webhook and deletes the corresponding preview branch immediately. This avoids leaving behind a broken preview deployment, since both the deployment and the database branch are removed together.

This approach is practical for cleaning up a small number of branches manually. You can also automate Vercel deployment deletion in CI by calling the Vercel API on PR close. See Vercel's [Managing Deployments](https://vercel.com/docs/deployments/managing-deployments) documentation for details on deleting deployments programmatically.

### GitHub Action on PR close (recommended)

Neon's [`delete-branch-action`](https://github.com/neondatabase/delete-branch-action) deletes a Neon branch by name. Add this workflow to your repository to clean up the preview branch as soon as a PR is closed or merged:

```yaml
name: Cleanup Neon preview branch
on:
  pull_request:
    types: [closed]
jobs:
  delete-branch:
    runs-on: ubuntu-latest
    steps:
      - uses: neondatabase/delete-branch-action@v3
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          branch: preview/${{ github.head_ref }}
          api_key: ${{ secrets.NEON_API_KEY }}
```

The Vercel integration creates Neon branches using the naming pattern `preview/<git-branch>`, so this action targets the same branches the integration creates. This works for both integration types.

This workflow requires a `NEON_PROJECT_ID` [repository variable](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) and a `NEON_API_KEY` [repository secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions). Find your project ID on the **Project Settings** page in the Neon Console, and create an API key under **Account Settings > API Keys**.

This action is safe to use alongside automatic cleanup. If the action deletes the branch first, the cleanup webhook that eventually fires from Vercel will find the branch already gone and handle it gracefully.

**Note:** Deleting a Neon branch invalidates any Vercel preview deployments that depend on it. Those deployments will fail on database connections. This is usually acceptable since the PR is already closed, but be aware if your team revisits preview URLs after merging.

For more GitHub Actions branching workflows, see [Automate branching with GitHub Actions](https://neon.com/docs/guides/branching-github-actions).

### Neon CLI or API

You can also delete branches programmatically using the [Neon CLI](https://neon.com/docs/cli/branches#delete) or the [Neon API](https://neon.com/docs/manage/branches#delete-a-branch-with-the-api). This is useful for building custom automation or scheduled cleanup scripts.

### Branch expiration

[Branch expiration](https://neon.com/docs/guides/branch-expiration) lets you set a time-to-live on branches so they're automatically deleted after a fixed duration. The Vercel-Managed integration doesn't set expiration on preview branches automatically. To use this approach, you'd need a separate automation step (for example, a GitHub Action triggered on push) that sets `expires_at` on newly created preview branches via the [Neon API](https://neon.com/docs/manage/branches#branching-with-the-neon-api). See [Branch expiration](https://neon.com/docs/guides/branch-expiration) for details and setup instructions.

---

## Cleaning up existing stale branches

If you already have accumulated preview branches, start by listing what you have:

```bash
neon branches list --project-id <project-id>
```

This shows all branches with their names, states, and creation dates. Look for branches with the `preview/` prefix that correspond to merged or deleted Git branches.

To remove stale branches:

- **Neon Console**: Go to the **Branches** page and delete branches individually
- **Neon CLI**: Use `neon branches delete <branch-id-or-name>` to remove specific branches. See [CLI branches reference](https://neon.com/docs/cli/branches#delete).
- **Neon API**: Use `DELETE /projects/{project_id}/branches/{branch_id}`. See [Delete a branch with the API](https://neon.com/docs/manage/branches#delete-a-branch-with-the-api).

---

## Cost impact of stale branches

Preview branches that aren't cleaned up still consume resources and count toward your plan limits. Branches inactive for 24 hours and older than 14 days are automatically [archived](https://neon.com/docs/guides/branch-archiving) to lower-cost storage, which reduces storage costs but doesn't eliminate them. Archived branches still count toward your plan's [branch limits](https://neon.com/docs/introduction/plans#extra-branches). If you exceed the branch limit included in your plan, the extra branches are billed at the rate shown on the [Extra usage](https://neon.com/docs/introduction/extra-usage) page.

---

## Frequently asked questions

### Why aren't my preview branches being deleted?

The most common cause is Vercel's deployment retention policy. With the default 6-month retention, preview branches can persist for months after a PR is closed. To fix this:

1. [Reduce your Vercel retention policy](https://neon.com/docs/guides/vercel-branch-cleanup#reducing-vercels-retention-policy) for pre-production deployments
2. [Set up a GitHub Action](https://neon.com/docs/guides/vercel-branch-cleanup#github-action-on-pr-close-recommended) to delete branches immediately on PR close

### I reduced retention but branches are still not being deleted

Vercel keeps some deployments regardless of your retention setting (see [Retention exceptions](https://neon.com/docs/guides/vercel-branch-cleanup#retention-exceptions)). On low-activity projects, every preview can stay within the protected set, so reducing retention may change nothing. Use the [GitHub Action workaround](https://neon.com/docs/guides/vercel-branch-cleanup#github-action-on-pr-close-recommended) or [manual cleanup](https://neon.com/docs/guides/vercel-branch-cleanup#cleaning-up-existing-stale-branches).

### Which integration type gives faster cleanup?

It depends on your deployment cadence.

The [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration) deletes branches based on Git branch deletion rather than Vercel's deployment retention policy, so it avoids the months-long delays described on this page. But cleanup only runs when the next preview deployment is created. At that point, Neon checks for deleted Git branches and removes the corresponding Neon branches. If no new preview deployments happen, stale branches accumulate until activity resumes.

The **Vercel-Managed Integration** has predictable but slow cleanup tied to deployment retention. The **Neon-Managed Integration** has fast cleanup during active development but no cleanup during idle periods. Both benefit from the [GitHub Action approach](https://neon.com/docs/guides/vercel-branch-cleanup#github-action-on-pr-close-recommended), which works regardless of integration type and removes branches immediately on PR close.

### How do I clean up branches that already accumulated?

See [Cleaning up existing stale branches](https://neon.com/docs/guides/vercel-branch-cleanup#cleaning-up-existing-stale-branches) above for options including the Neon Console, CLI, and API.

--- [Document source](https://neon.com/docs/guides/vercel-connection-methods.md) ---

> Summary: Vercel Fluid compute connection methods for Neon compares TCP, HTTP, and WebSocket protocols by setup roundtrip cost to explain why Fluid compute makes standard Postgres TCP with connection pooling the recommended approach. Classic serverless could not safely pool connections, requiring the @neondatabase/serverless HTTP driver; Vercel Fluid solves this by closing idle connections before function suspension, making TCP pooling (node-postgres, Drizzle ORM with attachDatabasePool) the lowest-latency option. Use this page instead of the integration guides when deciding which connection method to use based on your Vercel compute model.

# Connecting to Neon from Vercel

Learn how Vercel Fluid compute optimizes database connections and why standard TCP is the recommended method.

Last updated: 2026-06-05

**What you will learn:**

- [What connection pooling is and why it mattered for serverless](https://neon.com/docs/guides/vercel-connection-methods#the-core-change-connection-pooling)
- [The difference between "Classic Serverless" and Vercel's "Fluid compute"](https://neon.com/docs/guides/vercel-connection-methods#the-two-scenarios-classic-serverless-versus-fluid-compute)
- [How TCP, HTTP, and WebSocket connections compare on latency](https://neon.com/docs/guides/vercel-connection-methods#comparison-of-connection-methods)
- [Our recommendation for connecting from Vercel](https://neon.com/docs/guides/vercel-connection-methods#our-recommendation)

**Related topics**

- [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration)
- [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration)
- [Benchmarking latency](https://neon.com/docs/guides/benchmarking-latency)

---

## Connecting to Neon from Vercel: Understanding Fluid compute

Vercel's **Fluid** compute model fundamentally changes the performance trade-offs for connecting to your Neon database.

**The short answer:** With Vercel Fluid, we recommend you use a **standard Postgres TCP connection** (for example, with the [node-postgres package](https://node-postgres.com/)) and a connection pool. This is the new fastest and most robust method.

This guide explains why this is a change, the difference between connection methods, and what you should use.

---

## The core change: Connection pooling

The most important concept to understand is **connection pooling**.

- **Database connection:** Establishing a connection to a Postgres database is an expensive, multi-step process (called a "handshake") that takes time.
- **Connection pooling:** A connection pool is a "cache" of active database connections. When your function needs to talk to the database, it quickly grabs a connection from the pool, uses it, and then returns it (also quickly).

The key problem with "classic" serverless was that you could not safely maintain a connection pool. Functions would be suspended while holding idle connections, leading to "leaks" that could exhaust your database's connection limit.

---

## The two scenarios: Classic serverless versus Fluid compute

How you connect depends entirely on your compute environment.

### Classic serverless (the "old way")

In a traditional serverless environment, each request spins up a new, isolated function instance. That instance runs its code and then shuts down.

- **The problem:** Because connection pools were not safe (as noted above), you had to establish a _new_ database connection on _every single request_.
- **The latency hit:** A standard TCP connection (the default for Postgres) takes the most "roundtrips" (~8) to establish. This adds significant latency to _every API call_.
- **The solution (HTTP/WebSocket):** To solve this, Neon provides the [@neondatabase/serverless](https://neon.com/docs/serverless/serverless-driver) driver, which connects over HTTP or WebSockets. These protocols have _fewer setup roundtrips_ (~3-4), making them much faster _for the first query_.

### Vercel Fluid compute (the "new way")

Vercel's Fluid model allows function runs to _reuse warm compute instances_ and share resources.

- **The opportunity:** This reuse is the key. It makes **connection pooling possible and safe** in a serverless environment.
- **How Fluid makes pooling safe:** Vercel Fluid solves the "leaked connection" problem. It keeps a function alive _just long enough_ to safely close idle connections _before_ the function is suspended, making pooling reliable.
- **The new "fastest" method:** You can now establish a TCP connection _once_ and place it in a pool. Subsequent function calls reuse that "warm" connection, skipping the ~8 roundtrip setup cost entirely.
- **The result:** Once the connection is established, a direct Postgres TCP connection is the lowest-latency and most performant way to query your database.

---

## Comparison of connection methods

This table breaks down the trade-offs, which are all about setup cost versus query speed.

| Connection Method  | Protocol      | Setup Cost (Roundtrips) | Best For...                                                                                           |
| :----------------- | :------------ | :---------------------- | :---------------------------------------------------------------------------------------------------- |
| **Postgres (TCP)** | `postgres://` | High (\~8)              | **Fluid compute / Long-running servers.** (Render, Railway). Once established, it's the fastest.      |
| **HTTP**           | `http://`     | Lowest (\~3)            | **Classic Serverless.** Fastest for a _single query_ where you can't pool connections.                |
| **WebSocket**      | `ws://`       | Low (\~4)               | **Classic Serverless.** A good alternative to HTTP, especially in environments that don't support it. |

_Note: Roundtrip counts are estimates and vary based on authentication and configuration._

---

## Our recommendation

### If you are using Vercel's Fluid compute:

We recommend using a standard Postgres TCP driver (like [node-postgres](https://node-postgres.com/)) and implementing a connection pool. This will give you the best performance by paying the connection cost once and reusing the connection for subsequent queries. See Vercel's [Connection pooling with Vercel Functions](https://vercel.com/guides/connection-pooling-with-functions) guide for implementation details.

Here is a complete example using Drizzle ORM with `attachDatabasePool` from `@vercel/functions`:

```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 });
```

`attachDatabasePool` handles the connection lifecycle for you: the first request establishes a TCP connection, subsequent requests reuse it instantly, and idle connections close gracefully before Vercel suspends the function.

**Note: A note on benchmarking**

Before migrating, we recommend you benchmark both connection methods on your own app. While TCP with pooling is the new default, some applications with a very high number of cold starts might, in edge cases, still see an advantage from the low initial connection time of the HTTP driver.

### If you are on a "classic" serverless platform (without connection pooling):

Continue using the [@neondatabase/serverless](https://neon.com/docs/serverless/serverless-driver) driver. Its HTTP-based connection is optimized for low-latency "first queries," which is the most important metric in that environment.

You can see a live latency comparison of these three methods here: [Function latency comparison](https://function-database-latency-sigma.vercel.app)

--- [Document source](https://neon.com/docs/guides/vercel-managed-integration.md) ---

> Summary: The Vercel-Managed Integration (also called Neon Postgres Native Integration) provisions a Lakebase Postgres database from the Vercel Marketplace and routes all billing through your Vercel invoice, injecting DATABASE_URL and related environment variables automatically. Choose this path over the Neon-Managed Integration when you have no existing Neon account or want a single Vercel bill; it does not support the `neon login` CLI command. Automated Preview Branching creates an isolated copy-on-write Lakebase Postgres branch for every Vercel Preview Deployment, with branches cleaned up according to Vercel's 6-month default deployment retention policy.

# Connecting with the Vercel-Managed Integration

Create and manage Neon databases directly from your Vercel dashboard

Last updated: 2026-10-23

**What you will learn:**

- [What the Vercel-Managed Integration is](https://neon.com/docs/guides/vercel-managed-integration#about-this-integration)
- [How to install it from the Vercel Marketplace](https://neon.com/docs/guides/vercel-managed-integration#installation-walkthrough)
- [How (and why) to enable automated Preview Branching](https://neon.com/docs/guides/vercel-managed-integration#enable-automated-preview-branching-recommended)
- [How to choose which branch feeds Vercel Production](https://neon.com/docs/guides/vercel-managed-integration#choose-a-production-branch)
- [Where to manage billing and configuration](https://neon.com/docs/guides/vercel-managed-integration#managing--billing)

**Related topics**

- [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration)
- [Manual Connections](https://neon.com/docs/guides/vercel-manual)

---

## About this integration

**Vercel-Managed Integration** (also known as _Neon Postgres Native Integration_) lets you add a Lakebase Postgres database to your Vercel project **with billing handled entirely inside Vercel**. Installing it:

- Creates a Neon account + project for you (if you don't already have one)
- For existing Neon users, adds a new organization named `Vercel: <team-name>` to your account
- Injects the required database environment variables (`DATABASE_URL`, etc.) into your Vercel project
- Optionally creates a dedicated database branch for every Preview Deployment so you can test schema changes safely

**Note: Who should use this path?**

Choose the Vercel-Managed Integration if you **do not already have a Neon account** _or_ you prefer to consolidate payment for Neon inside your Vercel invoice.

---

## Installation walkthrough

## Open Neon integration

Open the [Neon integration on the Vercel Marketplace](https://vercel.com/marketplace/neon) and click **Install**.

## Add the integration in Vercel

This opens the **Install Neon** modal where you can choose between two options. Select **Create New Neon Account**, then click **Continue**.

## Complete Vercel's configuration

Under **Configuration and Plan**, choose a region and set the optional services:

- **Auth**: provisions [Managed Better Auth](https://neon.com/docs/auth/overview) for your app's users, with profiles synced to Postgres.
- **Realtime**: enables [Neon Realtime](https://neon.com/docs/realtime/overview) (beta) on the database's default branch. Preview branches get their own. You can only turn on Realtime when you create a database, not for an existing one.

Then pick a plan, accept the terms, and name your database. (Remember: a "Database" in Vercel is a **Project** in Neon.)

## View storage settings

After creation you'll land on Vercel's **Storage** tab that includes status, plan, connection string, billing plan, and more.

## Optionally open the project in the Neon Console

From the **Storage** tab, click **Open in Neon** to jump straight to your new Neon project in the Neon Console. You'll notice it lives in an organization named `Vercel: <your-vercel-team>`.

---

## Connecting the database to a Vercel project

1. In **Storage → `<your database>` → Connect Project**, choose the Vercel **Project** and the **Environments** that should receive database variables (Development, Preview, Production).
2. (Optional) Under **Create database branch for deployment**, select **Preview** to turn on _Preview Branching_ (see next section). Leave **Production** unchecked. It creates a new branch for every production deployment, which the recommended setup doesn't need: production deployments use your [production branch](https://neon.com/docs/guides/vercel-managed-integration#choose-a-production-branch).
3. (Optional) Set a **Custom Prefix** for the environment variables. You only need one if your Vercel project already uses the unprefixed variable names, for example from a database you connected earlier.
4. Click **Connect**.

---

## Enable automated preview branching (recommended)

Preview branching creates an isolated Neon branch (copy-on-write) for every Vercel Preview Deployment so database schema changes can be tested safely.

**Tip: Managed Better Auth support for preview deployments**

If you've enabled [Managed Better Auth](https://neon.com/docs/auth/overview) on your production branch, it's automatically provisioned on preview branches too. Preview deployments receive `NEON_AUTH_BASE_URL` and `VITE_NEON_AUTH_URL` environment variables, letting you test authentication in isolated environments. Auth data branches with your database, so each preview has its own independent user profiles and sessions.

To enable it, select **Preview** under **Create database branch for deployment** when you connect the project (step above).

Once enabled, the flow looks like this:

1. Developer pushes to feature branch → Vercel kicks off Preview Deployment.
2. Vercel sends a webhook to Neon → Neon creates branch `preview/<git-branch>`.
3. Environment variables for the branch connection are injected via webhook at deployment time, overriding preview environment variables for this deployment only (cannot be accessed or viewed in your Vercel project's environment variable settings).
4. (Optional) Run migrations in build step so schema matches code.

   ![Vercel build commands](https://neon.com/docs/guides/vercel_build_command.png)

   To apply schema changes automatically, add migration commands to your Vercel build configuration:

   1. Go to **Vercel Dashboard → Settings → Build and Deployment Settings**
   2. Enable **Override** and add your build commands, including migrations, for example:

      ```bash
      npx prisma migrate deploy && npm run build
      ```

   This ensures schema changes in your commits are applied to each preview deployment's database branch.

### Test the setup

To verify preview branching works:

1. Create a local branch: `git checkout -b test-feature`
2. Make any change and commit: `git commit -a -m "Test change"`
3. Push: `git push`
4. Check Vercel deployments and Neon Console branches to confirm the preview branch was created

---

## Choose a production branch

Your Vercel Production deployments use a dedicated **production branch** in Neon. When the integration creates your database, the production branch is your project's default branch. Preview branches are always created from the default branch.

The production branch is independent of the default branch. If you later change the project's default branch, Production keeps using the same production branch. To point Production at a different branch, for example a protected `production` branch:

1. In the Neon Console, open your project and go to **Integrations**.
2. Under **Added**, click **Settings** next to **Vercel**.
3. Under **Production branch**, select the branch you want and click **Save**. If a production branch is already set, confirm the change.
4. Redeploy your production deployment in Vercel so it picks up the new branch's credentials.

The branch you choose can't be a preview branch or have [branch expiration](https://neon.com/docs/guides/branch-expiration) set, and it needs a read-write compute. Branches created before January 14, 2024 aren't listed.

While the integration is connected, the production branch and its read-write compute can't be deleted. To delete that branch, choose a different production branch first.

---

## Automatic branch cleanup

Preview branches are automatically deleted when their corresponding Vercel deployments are removed. The timing of this cleanup depends on [Vercel's deployment retention policy](https://vercel.com/docs/deployment-retention), which retains preview deployments for 6 months by default.

**Important: Preview branches may not be deleted for months**

Because of Vercel's default retention settings, preview branches can persist long after a PR is closed. To understand the full timeline, reduce your retention policy, or set up immediate cleanup, see [Managing Vercel preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup).

---

## Managing & billing

Because your database is managed by Vercel, you can only perform these actions **in the Vercel dashboard**:

- Change plan, billing tier, or scale settings (compute size, autoscaling, scale-to-zero)
- View or modify database configuration via **Storage → Settings → Change Configuration**
- Monitor usage via **Storage → Usage** (also available in Neon Console)
- Create additional databases (each becomes a new Neon project)
- Rename or delete a database (deleting removes the underlying Neon project permanently)
- Manage members / collaborators (handled through Vercel "Members", not the Neon Console) - (see [FAQ](https://neon.com/docs/guides/vercel-managed-integration#frequently-asked-questions) for details)
- Delete the Neon organization (only happens automatically if you uninstall the integration)
- Update connection-string environment variables (prefix changes, etc.)

Everything else (querying data, branching, monitoring usage) works exactly the same in the Neon Console.

If you're on Neon's Scale plan, you can open support tickets for any Neon issue directly from the Neon Console. See [Support tickets](https://neon.com/docs/introduction/support#support-tickets) for details.

### Team member synchronization

Team membership changes in Vercel automatically sync to your Neon organization:

- **Initial access**: Team members must click **Open in Neon** from the Vercel integration page and complete authentication before they appear in the Neon organization. This one-time step links their Vercel identity to Neon.
- **Role changes**: When a team member's role changes in Vercel, their Neon role updates based on Vercel's JWT token mapping (see [FAQ](https://neon.com/docs/guides/vercel-managed-integration#why-do-vercel-team-members-with-member-role-have-the-admin-role-in-neon) for details). Most Vercel roles (Owner, Admin, Member) map to 'Admin' in Neon, while read-only roles (Viewer, Billing) map to 'Member' in Neon.
- **Removals**: When a user is removed from your Vercel team, they're automatically removed from the associated Neon organization.

This ensures both platforms stay aligned for security and access control.

**Note:** Organizations managed through the Vercel-managed integration use Neon's legacy roles (Admin and Member), as described above. The newer [organization roles and per-project permissions](https://neon.com/docs/manage/user-permissions) don't apply to Vercel-managed organizations.

### Project transfers between teams

When you transfer a Vercel project to another team, the linked Neon project automatically moves to the new team's Neon organization:

- The linked Neon project moves from the old organization to the new one.
- Environment variables and settings transfer with it.
- If the destination's plan doesn't support the project's requirements (autoscaling limits, point-in-time [history window](https://neon.com/docs/introduction/history-window), etc.), you'll be prompted to upgrade.

This eliminates the need to manually reconfigure integrations when reorganizing projects.

This is separate from Neon's [project transfer](https://neon.com/docs/manage/orgs-project-transfer) feature, which doesn't support Vercel-managed organizations as a source or destination.

---

## Common operations

### Add another database (project)

1. Go to **Integrations → Neon Postgres → Manage → More Products → Install**
2. Select region, scale settings, and plan
3. Specify a **Database Name** and click **Create**

### Change compute / scale settings

**Storage → Settings → Change Configuration** lets you resize compute, adjust scale-to-zero, or switch Neon plan tiers. Changes apply to _all_ databases in the installation.

**Important:** Changing your plan affects **all databases** in this integration, not just the current one.

### Delete the database

Deleting from Vercel permanently removes the Neon project and all data. This cannot be undone.
To delete:

1. Vercel Dashboard → Storage → Settings
2. Select your database
3. Find Delete Database section and confirm

### Disconnect a project from database

To disconnect a Vercel project without deleting the database:

1. Go to **Storage → `<your database>` → Projects**
2. Select your project and choose **Remove Project Connection**

This removes database environment variables from your Vercel project but keeps the database intact. Previously created preview branches remain but new ones won't be created.

### Manage branches created by the integration

You can manually delete preview branches at any time via the [Neon Console](https://neon.com/docs/manage/branches#delete-a-branch), [Neon CLI](https://neon.com/docs/cli/branches#delete), or [Neon API](https://neon.com/docs/manage/branches#delete-a-branch-with-the-api). For automated cleanup options, including GitHub Actions, see [Managing Vercel preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup).

**Note: Unused branches are archived**

Branches you don't delete are eventually [archived](https://neon.com/docs/guides/branch-archiving), reducing storage costs but still consuming archive storage space.

---

## Environment variables set by the integration

| Variable                                                          | Purpose                                                                                                                                                     |
| :---------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DATABASE_URL`                                                    | Pooled connection string (PgBouncer)                                                                                                                        |
| `DATABASE_URL_UNPOOLED`                                           | Direct connection string                                                                                                                                    |
| `PGHOST`, `PGHOST_UNPOOLED`, `PGUSER`, `PGDATABASE`, `PGPASSWORD` | Raw pieces to build custom strings                                                                                                                          |
| `POSTGRES_*` (legacy)                                             | Provided for backwards compatibility with Vercel Postgres templates                                                                                         |
| `NEON_AUTH_BASE_URL`, `VITE_NEON_AUTH_URL`                        | Managed Better Auth endpoints (when enabled on production branch)                                                                                           |
| `NEON_REALTIME_URL`, `NEON_REALTIME_SECRET`                       | [Neon Realtime](https://neon.com/docs/realtime/overview) endpoint and secret (when Realtime is enabled). Preview deployments get their own branch's values. |

---

## Limitations

- You cannot use this integration with the **Neon-Managed integration** in the same Vercel project
- **Neon CLI access**: Requires API key authentication (the `neon login` command won't work since the account is Vercel-managed)
- Cannot install if you currently use Vercel Postgres (deprecated) - contact Vercel about transitioning
- **Project transfer**: Neon's [project transfer](https://neon.com/docs/manage/orgs-project-transfer) doesn't work into or out of a Vercel-managed organization. Instead, [transfer the Vercel project to another team](https://neon.com/docs/guides/vercel-managed-integration#project-transfers-between-teams).
- **Preview deployment environment variables**: Branch-specific connection variables cannot be accessed or viewed in your Vercel project's environment variable settings (they're injected at deployment time only and not stored to avoid manual cleanup when branches are deleted)

## Frequently asked questions

### Why can't I see Vercel team members in the Neon Console?

Users added to your Vercel team aren't automatically visible in the Neon organization. Team members only appear in Neon when they:

1. Click the **Open in Neon** button from the Vercel integration page
2. Complete the authentication flow

### Why do Vercel team members with 'Member' role have the 'Admin' role in Neon?

This occurs due to how Vercel's JWT tokens map roles to the integration. According to [Vercel's documentation](https://vercel.com/docs/integrations/create-integration/marketplace-api#user-authentication), the JWT token's `user_role` claim doesn't directly map Vercel team roles:

- **ADMIN role in JWT**: Granted to users capable of installing integrations (includes Vercel Owner, Admin, and Member roles) → maps to Admin in Neon.
- **USER role in JWT**: Only granted to users with read-only Vercel roles (includes Billing and Viewer roles) → maps to Member in Neon.

As a result, most active Vercel team members receive Admin access in the Neon organization. This is expected behavior and ensures team members can fully manage database resources.

--- [Document source](https://neon.com/docs/guides/vercel-manual.md) ---

> Summary: Manual Vercel-Neon connection wires a Lakebase Postgres database to a Vercel project by setting DATABASE_URL (or granular PGUSER, PGHOST, PGDATABASE, PGPASSWORD, PGPORT vars) directly in Vercel's environment variable settings, without a Marketplace integration. Choose this path over the Vercel-Managed or Neon-Managed integrations when deploying through a custom CI pipeline, a monorepo, or any setup requiring direct control over branch naming, seeding, and migrations.

# Connect Vercel and Neon manually

Learn how to connect a Vercel project to a Neon database manually

Last updated: 2026-09-16

**What you will learn:**

- [When to use manual connections over integrations](https://neon.com/docs/guides/vercel-manual#when-to-choose-this-path)
- [How to connect using environment variables](https://neon.com/docs/guides/vercel-manual#connection-steps)
- [Advanced CI/CD automation options](https://neon.com/docs/guides/vercel-manual#cicd-based-preview-branching-github-actions)

**Related topics**

- [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration)
- [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration)
- [Automate branching with GitHub Actions](https://neon.com/docs/guides/branching-github-actions)

---

## When to choose this path

Choose manual connection if you prefer not to install a Marketplace integration. This approach is ideal when you:

- Deploy via a custom pipeline (self-hosted CI, monorepo, etc.)
- Need non-Vercel hosting (for example Cloudflare Workers + Vercel Functions hybrid)
- Want full control over branch naming, seeding, migration, or teardown

If you simply want Neon and Vercel with minimal setup, stick to the managed integrations. They're simpler and include UI support.

---

## Prerequisites

- Neon project with database (get a connection string via **Connect** in the Console)
- Deployed Vercel project

---

## Connection steps

1. Copy the connection string from the [Neon Console](https://console.neon.tech). Click **Connect** in the Console nav, select the branch, role, and database you want, then copy the _Connection string_.

   ![Neon connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

   For example:

   ```text
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
                ^              ^                                               ^
                |- <role>      |- <hostname>                                   |- <database>
   ```

2. In the Vercel dashboard, open your project and navigate to **Settings → Environment Variables**.

3. Add either:

   ```text
   Key: DATABASE_URL
   Value: <your connection string>
   ```

   _or_ the granular `PG*` variables:

   ```text
   PGUSER=alex
   PGHOST=ep-cool-darkness-123456.us-east-2.aws.neon.tech
   PGDATABASE=dbname
   PGPASSWORD=AbC123dEf
   PGPORT=5432
   ```

   **Note:** Neon uses the default Postgres port, `5432`.

4. Select which environments need database access (Production, Preview, Development) and click **Save**.

5. Redeploy your application (or wait for your next deployment) for the variables to take effect.

That's it. Your Vercel app now connects to Neon just like any other Postgres database.

---

## CI/CD-based Preview Branching (GitHub Actions)

Looking for a full CI/CD recipe? See **[Automate branching with GitHub Actions](https://neon.com/docs/guides/branching-github-actions)**.

--- [Document source](https://neon.com/docs/guides/vercel-overview.md) ---

> Summary: Lakebase Postgres-Vercel integration decision guide covering three connection paths: Vercel-Managed (new users, billing through Vercel), Neon-Managed (existing Neon account, billing through Neon), and Manual (custom CI/CD via env vars). Both managed integrations auto-provision Lakebase Postgres database branches for Vercel preview deployments and support Managed Better Auth; they differ in branch cleanup timing, where Vercel-Managed follows deployment retention policy and Neon-Managed triggers on Git branch deletion. Choose this page to select the right integration before following the path-specific setup guide.

# Integrating Neon with Vercel

Choose the right connection path in seconds

Last updated: 2026-10-08

## Overview

This page helps you quickly choose the best Neon–Vercel integration for your project. Whether you're starting fresh or have existing infrastructure, we'll guide you to the right solution.

**Tip: Quick decision guide**

Choose the **Vercel-Managed Integration** if you're new to Neon and want unified billing through Vercel.
Choose the **Neon-Managed Integration** if you already have a Neon account or prefer to manage billing directly with Neon.

---

## Compare the options at a glance

| Feature / Attribute             | [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration)                 | [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration)                     | [Manual Connection](https://neon.com/docs/guides/vercel-manual) |
| :------------------------------ | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------- |
| **Ideal for**                   | New users, teams wanting a single Vercel bill                                                         | Existing Neon users, direct Neon billing                                                                     | Integration not required or custom                              |
| **Neon account**                | Created automatically via Vercel                                                                      | Pre-existing Neon account                                                                                    | Pre-existing Neon account                                       |
| **Billing**                     | Paid **through Vercel**                                                                               | Paid **through Neon**                                                                                        | Paid **through Neon**                                           |
| **Setup method**                | Vercel Marketplace → Native Integrations → "Neon Postgres"                                            | Vercel Marketplace → Connectable Accounts → "Neon"                                                           | Manual env-vars                                                 |
| **Preview Branching**           | ✅                                                                                                     | ✅                                                                                                            | ✖️                                                              |
| **Managed Better Auth support** | ✅ Auto-provisioned on preview branches                                                                | ✅ Auto-provisioned on preview branches                                                                       | Manual setup required                                           |
| **Branch cleanup**              | Automatic (deployment-based)                                                                          | Automatic (Git-branch-based)                                                                                 | N/A                                                             |
| **Implementation type**         | [Native Integration](https://vercel.com/docs/integrations/install-an-integration/product-integration) | [Connectable Account](https://vercel.com/docs/integrations/install-an-integration/add-a-connectable-account) | N/A                                                             |

**Note: Branch cleanup timing**

Branch cleanup behavior differs between the two integrations. Vercel-Managed cleanup depends on Vercel's deployment retention policy, which can delay branch deletion by months. Neon-Managed cleanup is triggered by Git branch deletion. See [Managing Vercel preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup) for details, workarounds, and recommendations.

---

## Choose your integration path

**Important: Do you need custom CI/CD control?**

**If you want to build preview branching into your own CI/CD pipelines (for example, via GitHub Actions)**, use a **[manual connection](https://neon.com/docs/guides/vercel-manual)** instead of the automated integrations below.

For automated integrations, follow this simple flow:

## Do you have an existing Neon account?

**Do you already have a Neon account or project you want to keep using?**

- **✅ Yes** → Use **[Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration)**
- **❌ No** → Continue below

## Choose your billing preference

**Where would you like to manage billing for Neon?**

- **Through my Vercel account** → Use **[Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration)**
- **Directly with Neon** → Use **[Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration)**

---

## Integration options overview

- [Vercel-Managed Integration](https://neon.com/docs/guides/vercel-managed-integration): Create and manage Neon databases directly from your Vercel dashboard. Supports preview branches.
- [Neon-Managed Integration](https://neon.com/docs/guides/neon-managed-vercel-integration): Link an existing Neon project to Vercel and keep billing in Neon. Supports preview branches.
- [Manual Connection](https://neon.com/docs/guides/vercel-manual): Connect your Vercel project to a Neon database manually.

---

## Next steps

## Get Started Checklist

- [ ] Choose your integration type
    Select Vercel-Managed, Neon-Managed, or Manual based on the decision flow above
- [ ] Follow the setup guide
    Click through to your chosen integration's detailed documentation
- [ ] Configure preview branching
    Set up database branching for your development workflow
- [ ] Test your connection
    Verify your database connection works in both production and preview environments

--- [Document source](https://neon.com/docs/guides/vue.md) ---

> Summary: Connecting a Vue.js application to a Lakebase Postgres database requires server-side access because the database cannot be queried directly from the browser. Use a Vue meta-framework such as Nuxt.js or Quasar Framework to run database queries on the server and expose data to your Vue frontend.

# Connect a Vue.js application to Neon

Set up a project on Neon in seconds and connect from a Vue.js application

Last updated: 2026-08-04

Vue.js is a progressive JavaScript framework for building user interfaces.

Lakebase Postgres should be accessed from the server side in Vue.js applications. You can achieve this using Vue.js meta-frameworks like Nuxt.js or Quasar Framework.

## Vue Meta-Frameworks

Find detailed instructions for connecting to Neon from Vue.js meta-frameworks.

- [Nuxt.js](https://neon.com/docs/guides/nuxt): Connect a Nuxt.js application to Neon

## Next steps

- [Set up Managed Better Auth](https://neon.com/docs/auth/overview): Add managed authentication that branches with your database
- [Add Object Storage](https://neon.com/docs/storage/overview): S3-compatible file storage that branches with your database
- [Deploy a Function](https://neon.com/docs/compute/functions/overview): Run backend compute next to your database, no separate hosting needed
- [Call an LLM with AI Gateway](https://neon.com/docs/ai-gateway/overview): Access foundation models from Anthropic, OpenAI, Google, and more with one credential

--- [Document source](https://neon.com/docs/import/azure-regions-deprecation.md) ---

> Summary: Neon Azure regions (azure-eastus2, azure-westus3, azure-gwc) were deprecated on April 7, 2026: new project creation is blocked. After October 5, 2026, these regions stop receiving Neon feature updates, and projects in Free organizations inactive for 90 days or more are subject to deletion; active and paid projects keep running. This guide covers the timeline, what to do (migrate to a Neon AWS region, migrate to Databricks Lakebase, delete, or export), and how to confirm which region a project is in.

# Azure regions deprecation

What's changing, what to do, and answers to common questions

Last updated: 2026-10-17

**Warning:** Neon Azure regions were deprecated on April 7, 2026, and stopped receiving platform updates on October 5, 2026.

[Migrate or delete any projects in Azure regions](https://neon.com/docs/import/azure-regions-deprecation#what-to-do-next) immediately.

Neon's Azure regions were deprecated on April 7, 2026. New projects can no longer be created in those regions, and as of October 5, 2026, these regions no longer receive Neon platform updates.

Projects still running in Azure regions should be [migrated to another region or deleted](https://neon.com/docs/import/azure-regions-deprecation#what-to-do-next) immediately. Projects on Free plans that have been inactive for 90 days or more are subject to deletion.

Users with projects in Neon Azure regions have already received email about specific projects and next steps. This guide explains what's changing and what to do.

## Affected regions

Only projects in these Azure regions are affected:

- 🇺🇸 Azure East US 2 (Virginia) - `azure-eastus2`
- 🇺🇸 Azure West US 3 (Phoenix) - `azure-westus3`
- 🇩🇪 Azure Germany West Central (Frankfurt) - `azure-gwc`

Projects in AWS regions are not affected.

## Deprecation timeline

| Date                      | What happens                                                                                                                                          |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **April 7, 2026**         | Azure regions deprecated. New projects cannot be created in Azure regions. Existing projects keep running.                                            |
| **October 5, 2026**       | Azure regions will not receive new Neon features. Projects in Free organizations that have been inactive for 90 days or more are subject to deletion. |
| **After October 5, 2026** | A final end-of-service date will be announced.                                                                                                        |

## What to do next

**Migrate any projects you want to keep to an alternate region before October 5, 2026.** Migrating now keeps your project on actively developed infrastructure and lets you act on your own schedule.

There are three options for moving your Neon projects off of Azure regions:

1. **Migrate to a Neon AWS region.** Best if you don't need Azure data residency, and an AWS region in a similar location will suffice. See [Migrate to another Neon region](https://neon.com/docs/import/migrate-neon-to-another-region).
2. **Migrate to Databricks Lakebase.** Best if you need to keep your Postgres data in Azure. Lakebase is powered by the same serverless Postgres technology as Neon, under the Databricks product line, and supports the deprecated Azure regions. See [Migrate Neon to Lakebase](https://neon.com/docs/guides/migrate-neon-to-lakebase).
3. **Delete the project** if you no longer need it. This stops storage costs from accruing. See [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

If none of these fit, [export your data in Postgres-compatible form](https://neon.com/docs/guides/export-neon-postgres-compatible) so you can store it elsewhere.

## Frequently asked questions

### Why are these regions being deprecated?

We're focusing our infrastructure investment where our customers want to run Neon. Most Neon projects run in AWS regions, so concentrating there lets us ship features and reliability improvements faster, rather than splitting effort to maintain Azure in parallel. For teams that need Azure, [Databricks Lakebase](https://neon.com/docs/guides/migrate-neon-to-lakebase) runs the same Postgres technology as Neon and supports Azure regions.

### How do I find out which region a project is in?

You can check from the Console, the CLI, or the API:

- **Console.** Open your project, then check the **Project** panel on the **Overview** page. The region is shown in the **Region** row.
- **CLI.** Run `neon projects list`. The `Region ID` column shows each project's region.
- **API.** Call `GET /projects` and check the `region_id` field on each project.

![Project settings widget showing the project region](https://neon.com/docs/import/azure-regions-deprecation/project-settings-region.png)

### Which AWS region should I migrate to?

To keep latency similar, choose the AWS region closest to your current Azure region. For the deprecated Azure regions, the nearest AWS equivalents are:

| Azure region                                              | Nearest AWS region                               |
| --------------------------------------------------------- | ------------------------------------------------ |
| 🇺🇸 Azure East US 2 (Virginia) - `azure-eastus2`         | 🇺🇸 AWS US East (N. Virginia) - `aws-us-east-1` |
| 🇺🇸 Azure West US 3 (Phoenix) - `azure-westus3`          | 🇺🇸 AWS US West (Oregon) - `aws-us-west-2`      |
| 🇩🇪 Azure Germany West Central (Frankfurt) - `azure-gwc` | 🇩🇪 AWS Europe (Frankfurt) - `aws-eu-central-1` |

If your workload has specific latency or data residency requirements, pick the region closest to your users.

### What changes about my project when I migrate to a new region?

A region migration creates a **new** Neon project in the target region. The new project gets a new hostname, so you'll need to update connection strings in your application. The new project also has a different project ID. Project-level settings (branches, integrations, autoscaling, IP Allow rules, monitoring) are configured per project. See the [migration guide](https://neon.com/docs/import/migrate-neon-to-another-region) for method-specific steps.

### Should I take a backup before migrating?

If your migration method uses `pg_dump` and `pg_restore`, the dump itself is a backup. If you're using Postgres logical replication, it's good practice to take a `pg_dump` snapshot of your source database first. See [Backups](https://neon.com/docs/manage/backups).

### How do I contact Neon about my Azure projects?

Keep an eye on your inbox for communication from us. If you have specific constraints, such as regulatory requirements or migration dependencies, reply to any migration outreach you receive or contact [Neon Support](https://console.neon.tech/app/projects?modal=support).

--- [Document source](https://neon.com/docs/import/import-data-assistant.md) ---

> Summary: Import Data Assistant is a guided, automated tool in the Neon console that migrates a Postgres database under 10 GB to Neon using only a connection string, with no manual pg_dump steps required. Use it to migrate from any supported Postgres platform (excluding Supabase and Heroku) or to move data between Neon projects for a version upgrade or region change. For databases over 10 GB, use pg_dump and pg_restore instead.

# Import Data Assistant

Import a database under 10 GB to Neon using our automated import tool

Last updated: 2026-09-16

The **Import Data Assistant** can help you automatically import your existing database. The assistant supports databases **smaller than 10 GB**; you only need a connection string to get started.

**Note: Beta**

**Import Data Assistant** is in beta. Share your feedback on [Discord](https://neon.com/discord) or via the [Neon Console](https://console.neon.tech/app/projects?modal=feedback).

**Tip: Migrate between Neon projects**

In addition to migrating from other Postgres platforms, you can use the **Import Data Assistant** to migrate data between Neon projects. Use it to upgrade to a newer Postgres version (for example, from Postgres 16 to 17) or move your database to a different region. The assistant steps you through creating a new Neon project.

## Before you start

You'll need:

- A **Neon account**. Sign up at [Neon](https://neon.tech) if you don't have one.

- A **connection string** to your current database in this format:

  ```
  postgresql://username:password@host:port/database?sslmode=require&channel_binding=require
  ```

  If you are migrating a database from one Neon project to another, you need the connection string for the source database, which you can access from the **Connect** modal (**Connect** in the Console nav). When the source is a Neon project, use a direct (unpooled) connection string, not a pooled one. Make sure the hostname does not include the `-pooler` suffix. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

- **Admin privileges** on your source database. We recommend using a superuser if migrating from another platform, or a user with the necessary `CREATE`, `SELECT`, `INSERT`, and `REPLICATION` privileges.

- A database **smaller than 10 GB** in size for automated import. For larger databases, use [Migrate data from Postgres with pg_dump and pg_restore](https://neon.com/docs/import/migrate-from-postgres).

- Unless you are intentionally migrating to a different region, we recommend migrating to a Neon project created in the same region as your current database for a faster import. There is a 1-hour time limit on import operations.

- For other constraints that apply to this flow, see [Known limitations](https://neon.com/docs/import/import-data-assistant#known-limitations).

## Launch the assistant

Launch the assistant from the **Projects** page:

![Import Data Assistant from Projects page](https://neon.com/docs/import/import_data_assistant_project.png)

## Check compatibility

Enter your database connection string and click **Run Checks**.

![Import Data Assistant run checks](https://neon.com/docs/import/import_data_assistant_run_checks.png)

We'll verify the following:

- Database size is within the 10 GB limit
- Postgres version compatibility (Postgres 14 to 17)
- Extension compatibility
- Region availability

## Create a new Neon project

Click the **Create new Neon project** button, specify your project settings including the **Postgres version** and **region**, and click **Create**.

## Start import process

Back in the assistant, click the **Start import process** button.

**Note:** During import, your source database remains untouched. We only read from it to create a copy in Neon.

### Known limitations

- Supabase and Heroku databases are not supported due to unsupported Postgres extensions.
- Databases running on **IPv6 are not supported**.
- AWS RDS is generally supported, though some incompatibilities may exist. Support for other providers may vary.

## Next steps

After a successful import:

1. Run some test queries to ensure everything imported correctly.
2. If you've migrated from another Neon project, remove your old project if it's no longer needed.
3. Switch the connection string in your app to point to your new Neon database.

--- [Document source](https://neon.com/docs/import/import-from-csv.md) ---

> Summary: Loading CSV data into a Lakebase Postgres table uses the psql `\copy` meta-command to stream rows directly from a local file into an existing table. Use this page when you need to bulk-load tabular data without application code, using only a psql connection string from the Neon Console. The target table must exist in advance with columns that match the CSV header; `\copy` returns the row count on success.

# Import data from CSV

Last updated: 2026-09-16

To import data from a CSV file into your Neon database, create the target table first, then run the psql `\copy` meta-command from a session connected to your database. `\copy` streams the CSV from your local machine over the existing connection, so it works without any special server-side file access. This topic walks through the process with a simple example.

**Note: Use psql, not the SQL Editor, for \copy**

`\copy` is a psql client-side meta-command, so it runs in psql rather than on the Postgres server. The Neon SQL Editor doesn't support it, and the server-side `COPY ... FROM '/path/to/file.csv'` form can't read from Neon's server filesystem. Run `\copy` from psql or a Postgres GUI such as DBeaver or pgAdmin. For a large or messy CSV that needs encoding fixes, type casts, or parallel loading, [pgloader](https://pgloader.readthedocs.io/) is a good alternative.

The instructions require a working installation of [psql](https://www.postgresql.org/download/). The `psql` client is the native command-line client for Postgres. It provides an interactive session for sending commands to Postgres. For installation instructions, see [How to install psql](https://neon.com/docs/connect/query-with-psql-editor#how-to-install-psql).

The following example uses the ready-to-use `neondb` database that is created with your Neon project, a table named `customer`, and a data file named `customer.csv`. Data is loaded from the `customer.csv` file into the `customer` table.

## Connect to your database

Connect to the `neondb` database using `psql`. For example:

```bash
psql "<your_neon_database_connection_string>"
```

You can find your connection string by clicking **Connect** in the Console nav. Use the drop-down menu to copy a full `psql` connection command.

**Note:** For more information about connecting to Neon with `psql`, see [Connect with psql](https://neon.com/docs/connect/query-with-psql-editor).

## Create the target table

Create the `customer` table: the table you are importing to must exist in your database and the columns must match your CSV file.

```sql
CREATE TABLE customer (
   id SERIAL,
   first_name VARCHAR(50),
   last_name VARCHAR(50),
   email VARCHAR(255),
   PRIMARY KEY (id)
)
```

**Tip:** You can also create tables using the **SQL Editor** in the Neon Console. See [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor).

## Prepare the CSV file

Prepare a `customer.csv` file with the following data. Note that the columns in the CSV file match the columns in the table you created in the previous step.

```text
First Name,Last Name,Email
1,Casey,Smith,casey.smith@example.com
2,Sally,Jones,sally.jones@example.com
```

## Load the data

From your `psql` prompt, load the data from the `customer.csv` file using the `\copy` option.

```bash
\copy customer FROM '/path/to/customer.csv' DELIMITER ',' CSV HEADER
```

If the command runs successfully, it returns the number of records copied to the database:

```bash
COPY 2
```

For more information about the `\copy` option, refer to the [psql reference](https://www.postgresql.org/docs/current/app-psql.html), in the _PostgreSQL Documentation_.

--- [Document source](https://neon.com/docs/import/import-sample-data.md) ---

> Summary: Curated Postgres sample datasets with load instructions using psql, pg_restore, or the Neon CLI for learning, testing, and exploration. Choose this page when you need real data in a Neon database fast; larger datasets require a paid plan because the Free plan caps storage per branch. Includes Pagila, Chinook, Employees, Wikipedia vector embeddings (pgvector), and Postgres Air.

# Postgres sample data

Import sample data for learning, testing, and exploring Neon

Last updated: 2026-09-29

This guide describes how to download and install sample data for use with Neon.

## Prerequisites

- [wget](https://www.gnu.org/software/wget/) for downloading datasets, unless otherwise instructed. If your system does not support `wget`, you can paste the source file address in your browser's address bar.
- A `psql` client for connecting to your Neon database and loading data. This client is included with a standalone PostgreSQL installation. See [PostgreSQL Downloads](https://www.postgresql.org/download/).
- A `pg_restore` client if you are loading the [employees](https://neon.com/docs/import/import-sample-data#employees-database) or [postgres_air](https://neon.com/docs/import/import-sample-data#postgres-air-database) database. The `pg_restore` client is included with a standalone PostgreSQL installation. See [PostgreSQL Downloads](https://www.postgresql.org/download/).
- A Neon database connection string. After creating a database, you can find the connection details by clicking the **Connect** button in the Console nav. In the instructions that follow, replace `postgresql://[user]:[password]@[neon_hostname]/[dbname]` with your connection string.
- A Neon [paid plan](https://neon.com/docs/introduction/plans) if you intend to install a dataset larger than 1 GB.
- Instructions for each dataset require that you create a database. You can do so from a client such as `psql` or from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor).

**Note:** You can also load sample data using the Neon CLI. See [Load sample data with the Neon CLI](https://neon.com/docs/import/import-sample-data#load-sample-data-with-the-neon-cli).

## Sample data

Sample datasets are listed in order of the smallest to largest installed size. Please be aware that the Neon Free plan has a storage limit of 1 GB per project. Datasets larger than 1 GB cannot be loaded on the Free plan.

| Name                                                                                                       | Tables | Records  | Source file size | Installed size |
| ---------------------------------------------------------------------------------------------------------- | ------ | -------- | ---------------- | -------------- |
| [Periodic table data](https://neon.com/docs/import/import-sample-data#periodic-table-data)                 | 1      | 118      | 17 KB            | 7.2 MB         |
| [World Happiness Index](https://neon.com/docs/import/import-sample-data#world-happiness-index)             | 1      | 156      | 9.4 KB           | 7.2 MB         |
| [Titanic passenger data](https://neon.com/docs/import/import-sample-data#titanic-passenger-data)           | 1      | 1309     | 220 KB           | 7.5 MB         |
| [Netflix data](https://neon.com/docs/import/import-sample-data#netflix-data)                               | 1      | 8807     | 3.2 MB           | 11 MB          |
| [Pagila database](https://neon.com/docs/import/import-sample-data#pagila-database)                         | 33     | 62322    | 3 MB             | 15 MB          |
| [Chinook database](https://neon.com/docs/import/import-sample-data#chinook-database)                       | 11     | 77929    | 1.8 MB           | 17 MB          |
| [Lego database](https://neon.com/docs/import/import-sample-data#lego-database)                             | 8      | 633250   | 13 MB            | 42 MB          |
| [Employees database](https://neon.com/docs/import/import-sample-data#employees-database)                   | 6      | 3919015  | 34 MB            | 333 MB         |
| [Wikipedia vector embeddings](https://neon.com/docs/import/import-sample-data#wikipedia-vector-embeddings) | 1      | 25000    | 1.7 GB           | 850 MB         |
| [Postgres air](https://neon.com/docs/import/import-sample-data#postgres-air-database)                      | 10     | 67228600 | 1.2 GB           | 6.7 GB         |

**Note:** Installed size is measured using the query: `SELECT pg_size_pretty(pg_database_size('your_database_name'))`. The reported size for small datasets may appear larger than expected due to inherent Postgres storage overhead.

### Periodic table data

A table containing data about the periodic table of elements.

1. Create a `periodic_table` database:

   ```sql
   CREATE DATABASE periodic_table;
   ```

2. Download the source file:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/periodic_table.sql
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   psql -d "postgresql://[user]:[password]@[neon_hostname]/periodic_table" -f periodic_table.sql
   ```

4. Connect to the `periodic_table` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/periodic_table
   ```

5. Look up the element with the Atomic Number 10:

   ```sql
   SELECT * FROM periodic_table WHERE "AtomicNumber" = 10;
   ```

- Source: [https://github.com/andrejewski/periodic-table](https://github.com/andrejewski/periodic-table)
- License: [ISC License](https://github.com/andrejewski/periodic-table/blob/master/LICENSE)
- `Copyright (c) 2017, Chris Andrejewski <christopher.andrejewski@gmail.com>`

### World Happiness Index

A dataset with multiple indicators for evaluating the happiness of countries of the world.

1. Create a `world_happiness` database:

   ```sql
   CREATE DATABASE world_happiness;
   ```

2. Download the source file:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/happiness_index.sql
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   psql -d "postgresql://[user]:[password]@[neon_hostname]/happiness_index" -f happiness_index.sql
   ```

4. Connect to the `titanic` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/world_happiness_index
   ```

5. Find the countries where the happiness score is above average but the GDP per capita is below average:

   ```sql
   SELECT
       country_or_region,
       score,
       gdp_per_capita
   FROM
       "2019"
   WHERE
       score > (SELECT AVG(score) FROM "2019")
       AND
       gdp_per_capita < (SELECT AVG(gdp_per_capita) FROM "2019")
   ORDER BY
       score DESC;
   ```

- Source: [https://www.kaggle.com/datasets/unsdsn/world-happiness](https://www.kaggle.com/datasets/unsdsn/world-happiness)
- License: [CC0: Public Domain](https://creativecommons.org/publicdomain/zero/1.0/)

### Titanic passenger data

A dataset containing information on the passengers aboard the RMS Titanic, which sank on its maiden voyage in 1912.

1. Create a `titanic` database:

   ```sql
   CREATE DATABASE titanic;
   ```

2. Download the source file:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/titanic.sql
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   psql -d "postgresql://[user]:[password]@[neon_hostname]/titanic" -f titanic.sql
   ```

4. Connect to the `titanic` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/titanic
   ```

5. Query passengers with the most expensive fares:

   ```sql
   SELECT name, fare
   FROM passenger
   ORDER BY fare DESC
   LIMIT 10;
   ```

- Source: [https://www.kaggle.com/datasets/ibrahimelsayed182/titanic-dataset](https://www.kaggle.com/datasets/ibrahimelsayed182/titanic-dataset)
- License: [Unknown](https://www.kaggle.com/datasets/vinicius150987/titanic3)

### Netflix data

A dataset containing information about movies and tv shows on Netflix.

1. Create a `netflix` database:

   ```sql
   CREATE DATABASE netflix;
   ```

2. Download the source file:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/netflix.sql
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   psql -d "postgresql://[user]:[password]@[neon_hostname]/netflix" -f netflix.sql
   ```

4. Connect to the `netflix` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/netflix
   ```

5. Find the directors with the most movies in the database:

   ```sql
   SELECT
       director,
       COUNT(*) AS "Number of Movies"
   FROM
       netflix_shows
   WHERE
       type = 'Movie'
   GROUP BY
       director
   ORDER BY
       "Number of Movies" DESC
   LIMIT 5;
   ```

- Source: [https://www.kaggle.com/datasets/shivamb/netflix-shows](https://www.kaggle.com/datasets/shivamb/netflix-shows)
- License: [CC0: Public Domain](https://creativecommons.org/publicdomain/zero/1.0/)

### Pagila database

Sample data for a fictional DVD rental store. Pagila includes tables for films, actors, film categories, stores, customers, payments, and more.

1. Create a `pagila` database:

   ```sql
   CREATE DATABASE pagila;
   ```

2. Download the source file:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/pagila.sql
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   psql -d "postgresql://[user]:[password]@[neon_hostname]/pagila" -f pagila.sql
   ```

4. Connect to the `pagila` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/pagila
   ```

5. Find the top 10 most popular film categories based on rental frequency:

   ```sql
   SELECT c.name AS category_name, COUNT(r.rental_id) AS rental_count
   FROM category c
   JOIN film_category fc ON c.category_id = fc.category_id
   JOIN inventory i ON fc.film_id = i.film_id
   JOIN rental r ON i.inventory_id = r.inventory_id
   GROUP BY c.name
   ORDER BY rental_count DESC
   LIMIT 10;
   ```

- Source: [https://github.com/devrimgunduz/pagila](https://github.com/devrimgunduz/pagila)
- License: [LICENSE.txt](https://github.com/devrimgunduz/pagila/blob/master/LICENSE.txt)
- `Copyright (c) Devrim Gündüz <devrim@gunduz.org>`

### Chinook database

A sample database for a digital media store, including tables for artists, albums, media tracks, invoices, customers, and more.

1. Create a `chinook` database:

   ```sql
   CREATE DATABASE chinook;
   ```

2. Download the source file:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/chinook.sql
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   psql -d "postgresql://[user]:[password]@[neon_hostname]/chinook" -f chinook.sql
   ```

4. Connect to the `chinook` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/chinook
   ```

5. Find out the most sold item by track title:

   ```sql
   SELECT
   T."Name" AS "Track Title",
   SUM(IL."Quantity") AS "Total Sold"
   FROM
       "Track" T
   JOIN
       "InvoiceLine" IL ON T."TrackId" = IL."TrackId"
   GROUP BY
       T."Name"
   ORDER BY
       "Total Sold" DESC
   LIMIT 1;
   ```

- Source: [https://github.com/lerocha/chinook-database](https://github.com/lerocha/chinook-database)
- License: [LICENSE.md](https://github.com/lerocha/chinook-database/blob/master/LICENSE.md)
- `Copyright (c) 2008-2017 Luis Rocha`

### Lego database

A dataset containing information about various LEGO sets, their themes, parts, colors, and other associated data.

1. Create a `lego` database:

   ```sql
   CREATE DATABASE lego;
   ```

2. Download the source file:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/lego.sql
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   psql -d "postgresql://[user]:[password]@[neon_hostname]/lego" -f lego.sql
   ```

4. Connect to the `lego` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/lego
   ```

5. Find the top 5 LEGO themes by the number of sets:

   ```sql
   SELECT lt.name AS theme_name, COUNT(ls.set_num) AS number_of_sets
   FROM lego_themes lt
   JOIN lego_sets ls ON lt.id = ls.theme_id
   GROUP BY lt.name
   ORDER BY number_of_sets DESC
   LIMIT 5;
   ```

- Source: [https://www.kaggle.com/datasets/rtatman/lego-database](https://www.kaggle.com/datasets/rtatman/lego-database)
- License: [CC0: Public Domain](https://creativecommons.org/publicdomain/zero/1.0/)

### Employees database

A dataset containing details about employees, their departments, salaries, and more.

1. Create the database and schema:

   ```sql
   CREATE DATABASE employees;
   \c employees
   CREATE SCHEMA employees;
   ```

2. Download the source file:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/employees.sql.gz
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   pg_restore -d postgresql://[user]:[password]@[neon_hostname]/employees -Fc employees.sql.gz -c -v --no-owner --no-privileges
   ```

   Database objects are created in the `employees` schema rather than the `public` schema.

4. Connect to the `employees` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/employees
   ```

5. Find the top 5 departments with the highest average salary:

   ```sql
   SELECT d.dept_name, AVG(s.amount) AS average_salary
   FROM employees.salary s
   JOIN employees.department_employee de ON s.employee_id = de.employee_id
   JOIN employees.department d ON de.department_id = d.id
   WHERE s.to_date > CURRENT_DATE AND de.to_date > CURRENT_DATE
   GROUP BY d.dept_name
   ORDER BY average_salary DESC
   LIMIT 5;
   ```

- Source: The initial dataset was created by Fusheng Wang and Carlo Zaniolo from Siemens Corporate Research. Designing the relational schema was undertaken by Giuseppe Maxia while Patrick Crews was responsible for transforming the data into a format compatible with MySQL. Their work can be accessed here: [https://github.com/datacharmer/test_db](https://github.com/datacharmer/test_db). Subsequently, this information was adapted to a format suitable for PostgreSQL: [https://github.com/h8/employees-database](https://github.com/h8/employees-database). The data was generated, and there are inconsistencies.
- License: This work is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License. To view a copy of this license, visit [http://creativecommons.org/licenses/by-sa/3.0/](http://creativecommons.org/licenses/by-sa/3.0/) or send a letter to Creative Commons, 171 Second Street, Suite 300, San Francisco, California, 94105, USA.

### Wikipedia vector embeddings

An OpenAI example dataset containing pre-computed vector embeddings for 25000 Wikipedia articles. It is intended for use with the `pgvector` Postgres extension, which you must install first to create a table with `vector` type columns. For a Jupyter Notebook that uses this dataset with Neon, refer to the following GitHub repository: [neon-vector-search-openai-notebooks](https://github.com/neondatabase/neon-vector-search-openai-notebooks)

1. Download the zip file (~700MB):

   ```bash
   wget https://cdn.openai.com/API/examples/data/vector_database_wikipedia_articles_embedded.zip
   ```

2. Navigate to the directory where you downloaded the zip file, and run the following command to extract the source file:

   ```bash
   unzip vector_database_wikipedia_articles_embedded.zip
   ```

3. Create a `wikipedia` database:

   ```sql
   CREATE DATABASE wikipedia;
   ```

4. Connect to the `wikipedia` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/wikipedia
   ```

5. Install the `pgvector` extension:

   ```sql
   CREATE EXTENSION vector;
   ```

6. Create the following table in your database:

   ```sql
   CREATE TABLE IF NOT EXISTS public.articles (
       id INTEGER NOT NULL PRIMARY KEY,
       url TEXT,
       title TEXT,
       content TEXT,
       title_vector vector(1536),
       content_vector vector(1536),
       vector_id INTEGER
   );
   ```

7. Create vector search indexes:

   ```sql
   CREATE INDEX ON public.articles USING ivfflat (content_vector) WITH (lists = 1000);

   CREATE INDEX ON public.articles USING ivfflat (title_vector) WITH (lists = 1000);
   ```

8. Navigate to the directory where you extracted the source file, and run the following command:

   ```bash
   psql -d "postgresql://[user]:[password]@[neon_hostname]/wikipedia" -c "\COPY public.articles (id, url, title, content, title_vector, content_vector, vector_id) FROM 'vector_database_wikipedia_articles_embedded.csv' WITH (FORMAT CSV, HEADER true, DELIMITER ',');"
   ```

**Note:** If you encounter a memory error related to the `maintenance_work_mem` setting, refer to [Parameter settings that differ by compute size](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size) for how to increase this setting.

- Source: [OpenAI](https://github.com/openai/openai-cookbook/tree/main/examples/vector_databases)
- License: [MIT License](https://github.com/openai/openai-cookbook/blob/main/LICENSE)

### Postgres air database

An airport database containing information about airports, aircraft, bookings, passengers, and more.

1. Download the file (1.3 GB) from [Google drive](https://drive.google.com/drive/folders/13F7M80Kf_somnjb-mTYAnh1hW1Y_g4kJ)

2. Create a `postgres_air` database:

   ```sql
   CREATE DATABASE postgres_air;
   ```

3. Navigate to the directory where you downloaded the source file, and run the following command:

   ```bash
   pg_restore -d postgresql://[user]:[password]@[neon_hostname]/postgres_air -Fc postgres_air_2023.backup -c -v --no-owner --no-privileges
   ```

   Database objects are created in a `postgres_air` schema rather than the `public` schema.

4. Connect to the `postgres_air` database:

   ```bash
   psql postgresql://[user]:[password]@[neon_hostname]/postgres_air
   ```

5. Find the aircraft type with the most flights:

   ```sql
   SELECT ac.model, COUNT(f.flight_id) AS number_of_flights
   FROM postgres_air.aircraft ac
   JOIN postgres_air.flight f ON ac.code = f.aircraft_code
   GROUP BY ac.model
   ORDER BY number_of_flights DESC
   LIMIT 10;
   ```

- Source: [https://github.com/hettie-d/postgres_air](https://github.com/hettie-d/postgres_air)
- License: [BSD 3-Clause License](https://github.com/hettie-d/postgres_air/blob/main/LICENSE)
- `Copyright (c) 2020, hettie-d All rights reserved.`

## Load sample data with the Neon CLI

You can load data with the Neon CLI by passing the `--psql` option, which calls the `psql` command line utility.

The Neon CLI and `psql` must be installed on your system. For installation instructions, see:

- [Neon CLI — Install and connect](https://neon.com/docs/cli/install)
- [PostgreSQL Downloads](https://www.postgresql.org/download/) for `psql`

If you have multiple Neon projects or branches, we recommend setting your Neon CLI project and branch context so that you don't have to specify them explicitly when running a Neon CLI command. See [Neon CLI commands — set-context](https://neon.com/docs/cli/set-context).

To load sample data:

1. Download one of the data files listed above. For example:

   ```bash
   wget https://raw.githubusercontent.com/neondatabase/postgres-sample-dbs/main/periodic_table.sql
   ```

   Alternatively, supply your own data file.

2. Load the data using one of the following Neon CLI commands ([projects](https://neon.com/docs/cli/projects), [branches](https://neon.com/docs/cli/branches), or [connection-string](https://neon.com/docs/cli/connection-string)):
   - Create a new Neon project, connect to it with `psql`, and run the `.sql` file.

     ```bash
     neon projects create --psql -- -f periodic_table.sql
     ```

   - Create a branch, connect to it with `psql`, and run the `.sql` file.

     ```bash
     neon branches create --psql -- -f periodic_table.sql
     ```

   - Get a connection string, connect with `psql`, and run the `.sql` file.

     ```bash
     neon connection-string --psql -- -f periodic_table.sql
     ```

--- [Document source](https://neon.com/docs/import/migrate-aws-dms.md) ---

> Summary: AWS Database Migration Service (DMS) can migrate data to a Lakebase Postgres target from sources including PostgreSQL, MySQL, Oracle, and SQL Server by configuring a replication instance, source endpoint, and Neon target endpoint. Use this guide when migrating an existing hosted database to Neon via DMS, particularly when you need the endpoint-ID-in-password workaround that DMS requires to connect to Neon's SNI-based routing. The guide covers target endpoint setup, migration task configuration, table mapping, and post-migration verification in the Neon Console.

# Migrate with AWS Database Migration Service (DMS)

Last updated: 2026-09-16

This guide outlines the steps for using the AWS Database Migration Service (DMS) to migrate data to Neon from another hosted database server. AWS DMS supports a variety of database migration sources including PostgreSQL, MySQL, Oracle, and Microsoft SQL Server. For a complete list of data migration sources supported by AWS DMS, see [Source endpoints for data migration](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Introduction.Sources.html#CHAP_Introduction.Sources.DataMigration).

For additional information about particular steps in the migration process, refer to the [official AWS DMS documentation](https://docs.aws.amazon.com/dms/latest/userguide/Welcome.html). If you are not familiar with AWS DMS, we recommend stepping through the [Getting started with AWS Database Migration Service](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_GettingStarted.html) tutorial.

If you encounter problems with AWS DMS that are not related to defining Neon as a data migration target endpoint, please contact [AWS Customer Support](https://aws.amazon.com/contact-us/).

This guide uses the [AWS DMS sample Postgres database](https://github.com/aws-samples/aws-database-migration-samples/blob/master/PostgreSQL/sampledb/v1/README.md) for which the schema name is `dms_sample`.

## Before you begin

Complete the following steps before you begin:

- Create a [replication instance](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_ReplicationInstance.Creating.html) in AWS DMS.
- Configure a [source database endpoint](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Source.html) in AWS DMS.
- Set up a Neon project and a target database. See [Create a project](https://neon.com/docs/manage/projects#create-a-project), and [Create a database](https://neon.com/docs/manage/databases#delete-a-database) for instructions.
- If you are migrating from a database other than Postgres, use the [Schema Conversion Tool](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_GettingStarted.SCT.html) or [DMS Schema Conversion](https://docs.aws.amazon.com/dms/latest/userguide/getting-started.html) to convert and export the schema from the source database to the target database. Perform this step after creating the target endpoint for the Neon database but before the data migration. If migrating from a Postgres database, schema conversion is not required.

## Create a target endpoint for your Neon database

1. In the AWS Console, select **Database Migration Service**.

2. Select **Endpoints** from the sidebar.

3. Click **Create endpoint**.

4. Select **Target endpoint** as the **Endpoint type**.

5. Provide an **Endpoint identifier** label for your new target endpoint. In this guide, we use `neon` as the identifier.

6. In the **Target engine** drop-down menu, select `PostgreSQL`.

7. Under **Access to endpoint database**, select **Provide access information manually** and enter the information outlined below. You can obtain the connection details from your Neon connection string, which you can find by clicking **Connect** in the Console nav. Your connection string will look similar to this: `postgresql://daniel:AbC123dEf@ep-curly-term-54009904.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require"`.
   - **Server name**: Specify your Neon hostname, which is this portion of your connection string: `ep-curly-term-54009904.us-east-2.aws.neon.tech`

   - **Port**: `5432`

   - **User name**: Specify the Neon user.

   - **Password**: Specify the password in the following format: `endpoint=[endpoint_id]$[password]`, which looks similar to this when defined:

     ```text
     endpoint=ep-curly-term-54009904$AbC123dEf
     ```

     You can obtain the `endpoint_id` and password from your Neon connection string. The `endpoint_id` appears similar to this: `ep-curly-term-54009904`. For information about why this password format is required, see [Connection errors](https://neon.com/docs/connect/connection-errors#the-endpoint-id-is-not-specified). AWS DMS requires the [Option D workaround](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field).

   - **Secure Sockets Layer (SSL) mode**: Select `require`.

   - **Database name**: The name of your Neon database. In this example, we use a database named `neondb`

     When finished, your target endpoint configuration should look similar to this:
     ![Endpoint configuration dialog](https://neon.com/docs/import/endpoint_configuration.png)

8. Under **Test endpoint connection (optional)**, click **Run test** to test the connection. Running the test creates the endpoint and attempts to connect to it. If the connection fails, you can edit the endpoint definition and test the connection again.

9. Select **Create endpoint**.

## Create a database migration task

A database migration task defines the data to be migrated from the source database to the target database.

1. In AWS DMS, select **Database migration tasks** from the sidebar.
2. Select **Create task** to open a **Create database migration task** page.
3. Enter a **Task identifier** to identify the replication task. In this example, we name the identifier `dms-task`.
4. Select the **Replication instance**. In this guide, the replication instance is named `dms_instance`.
5. Select the **Source database endpoint**. In this guide, the replication instance is named `dms_postgresql`.
6. Select the **Target database endpoint**. In this guide, the target database endpoint identifier is `neon`.
7. Select a **Migration type**. In this example, we use the default `Migrate existing data` type.
   ![DMS database migration task configuration](https://neon.com/docs/import/dms_task_configuration.png)

### Task settings

Specify the following task settings:

1. For **Editing mode**, select **Wizard**.
2. For Target table preparation mode, select **Do nothing**. This option means that AWS DMS only creates tables in the target database if they do not exist.
3. For the **LOB column** setting, select **Don't include LOB columns**. Neon does not support LOB columns.
4. Optionally, under **Validation**, check **Turn on** to compare the data after the load operation finishes to ensure that data was migrated accurately. For more information about validation, refer to the [AWS data validation documentation](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_Validating.html).

You can also check **Enable CloudWatch logs** and set **Target Load** to **Debug** or **Detailed debug** to log information during the migration process. This data is useful for troubleshooting migration issues.
![DMS database migration task settings](https://neon.com/docs/import/dms_task_settings.png)

### Table mappings

Configure the table mapping:

1. For **Editing mode**, select **Wizard**.
2. Under **Selection rules**, click **Add new selection rule**.
3. For **Schema**, select **Enter a schema**.
4. For **Source name**, enter the name of your database schema. In this guide, `dms_sample` is specified as the schema name, which is the schema for the sample database. The `dms_sample` schema will be created in your Neon database, and all database objects will be created in the schema.
5. For the **Source table name**, leave the `%` wildcard character to load all tables in the schema.
6. For **Action**, select **Include** to migrate the objects specified by your selection rule.
   ![DMS database migration task table mappings](https://neon.com/docs/import/dms_task_table_mappings.png)

### Migration task startup configuration

1. Under ***Migration task startup configuration**, select **Automatically on create**.
2. Click **Start migration task** at the bottom of the page. The data migration task is created, and the data migration operation is initiated. You can monitor operation progress on the AWS DMS **Database migrations tasks** page.
   ![DMS database migration task status](https://neon.com/docs/import/dms_migration_status.png)

## Verify the migration in Neon

To verify that data was migrated to your Neon database:

1. In the Neon Console, select your Neon project.
2. Select **Postgres database** > **Tables** from the sidebar.
3. Select the **Branch**, **Database**, and **Schema** where you imported the data.
   ![Neon Tables view showing imported data](https://neon.com/docs/import/dms_neon_table_data.png).

## Migration notes

This section contains notes from our experience using AWS DMS to migrate data to Neon from an RDS Postgres database.

- When testing migration steps, the [Getting started with AWS Database Migration Service](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_GettingStarted.html) tutorial was our primary reference. As recommended in the tutorial, we created a VPC and created all resources within the VPC.

- We created all resources in the same region (`us-east-2a`)

- We created an RDS PostgreSQL 15 database called `dms_sample` as the source database. The Neon target database was also Postgres 15.

- We populated the RDS PostgreSQL source database using the [AWS DMS sample Postgres database](https://github.com/aws-samples/aws-database-migration-samples/blob/master/PostgreSQL/sampledb/v1/README.md). To do this, we created an EC2 instance to connect to the database following the steps in this topic: [Create an Amazon EC2 Client](https://docs.aws.amazon.com/dms/latest/userguide/CHAP_GettingStarted.Prerequisites.html#CHAP_GettingStarted.Prerequisites.client).

- The source database was populated using this `psql` command:

  ```bash
  psql -h dms-postgresql.abc123def456hgi.us-east-2.rds.amazonaws.com -p 5432 -U postgres -d dms_sample -a -f ~/aws-database-migration-samples/PostgreSQL/sampledb/v1/postgresql.sql
  ```

- To verify that data was loaded in the source database, we connected using the following `psql` command and ran a `SELECT` query:

  ```bash
  psql \
  --host=dms-postgresql.abc123def456hgi.us-east-2.rds.amazonaws.com \
  --port=5432 \
  --username=postgres \
  --password \
  --dbname=dms_sample


  dms_sample=> SELECT * from dms_sample.player LIMIT 100;
  ```

- When creating the source database endpoint for the RDS Postgres 15 database, we set **Secure Socket Layer (SSL) mode** to `require`. Without this setting, we encountered the following error:

  ```text
  Test Endpoint failed: Application-Status: 1020912, Application-Message: Failed to connect Network error has occurred, Application-Detailed-Message: RetCode: SQL_ERROR SqlState: 08001 NativeError: 101 Message: FATAL: no pg_hba.conf entry for host "10.0.1.135", user "postgres", database "dms_sample", no encryption
  ```

- When creating the target database endpoint for the Neon database, we encountered the following error when testing the connection:

  ```text
  Endpoint failed: Application-Status: 1020912, Application-Message: Cannot connect to ODBC provider Network error has occurred, Application-Detailed-Message: RetCode: SQL_ERROR SqlState: 08001 NativeError: 101 Message: timeout expired
  ```

  The replication instance, which was created in the private subnet where the source database resided, could not access the Neon database, which resides outside of the VPC. To allow the replication instance to access the Neon database, we added a NAT Gateway to the public subnet, allocated an Elastic IP address, and modified the **Route Table** associated with the private subnet to add a route via the NAT Gateway.

--- [Document source](https://neon.com/docs/import/migrate-from-azure-postgres.md) ---

> Summary: Migration guide for moving an Azure Database for PostgreSQL instance to Neon using Postgres logical replication, which streams row changes to minimize downtime during the cutover. Use this page when you need a live-replication approach rather than a full-stop dump: it walks through setting wal_level to LOGICAL in Azure, creating a replication role and publication, importing the schema with pg_dump, and creating a subscription on the Neon side. Alternative paths using pg_dump/pg_restore, pgAdmin, and CSV import are also described.

# Migrate from Azure PostgreSQL to Neon

Learn how to migrate your database from Azure PostgreSQL to Neon using logical replication

Last updated: 2026-09-16

This guide describes how to migrate your database from Azure Database for PostgreSQL to Neon, using logical replication.

Logical replication for Postgres transfers data from a source Postgres database to another, as a stream of tuples (records) or SQL statements. This allows for minimal downtime during the migration process, since all the records don't need to be copied at once.

## Prerequisites

- An Azure Database for PostgreSQL instance containing the data you want to migrate.

- A Neon project to move the data to.

  For detailed information on creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project). Make sure to create a project with the same Postgres version as your Azure PostgreSQL deployment.

- Read the [important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) before you begin.

- Review our [logical replication tips](https://neon.com/docs/guides/logical-replication-tips), based on real-world customer data migration experiences.

## Prepare your Azure PostgreSQL database

This section describes how to prepare your Azure PostgreSQL database (the publisher) for replicating data to your destination Neon database (the subscriber).

To illustrate the migration workflow, we set up the [AdventureWorks sample database](https://wiki.postgresql.org/wiki/Sample_Databases) on an Azure Database for PostgreSQL deployment. This database contains data corresponding to a fictional bicycle parts company, organized across 5 schemas and almost 70 tables.

### Enable logical replication in Azure PostgreSQL

1. Navigate to your Azure Database for PostgreSQL instance in the Azure portal.
2. From the left sidebar, select **Server parameters** under the **Settings** section.
3. Search for the `wal_level` parameter and set its value to `LOGICAL`.
4. Click **Save** to apply the changes.

   **Note:** Changing the `wal_level` parameter on Azure requires a server restart. This may cause a brief interruption to your database service.

### Create a PostgreSQL role for replication

It is recommended that you create a dedicated Postgres role for replicating data. Connect to your Azure PostgreSQL database using a tool like [psql](https://www.postgresql.org/docs/current/app-psql.html) or [Azure Data Studio](https://learn.microsoft.com/en-us/azure-data-studio/?view=sql-server-ver15), then create a new role with `REPLICATION` privileges:

```sql
CREATE ROLE replication_user WITH REPLICATION LOGIN PASSWORD 'your_secure_password';
```

### Grant schema access to your PostgreSQL role

Grant the necessary permissions to your replication role. For example, the following commands grant access to all tables in the `sales` schema to Postgres role `replication_user`:

```sql
GRANT USAGE ON SCHEMA sales TO replication_user;
GRANT SELECT ON ALL TABLES IN SCHEMA sales TO replication_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA sales GRANT SELECT ON TABLES TO replication_user;
```

Granting `SELECT ON ALL TABLES IN SCHEMA` instead of naming the specific tables avoids having to add privileges later if you add tables to your publication.

If you have data split across multiple schemas, you can run a similar command for each schema, or use a PL/pgSQL function to dynamically grant access to all schemas in the database.

```sql
-- Thanks to this Stackoverflow answer - https://dba.stackexchange.com/a/241266

DO $do$
DECLARE
    sch text;
BEGIN
    FOR sch IN SELECT nspname FROM pg_namespace
    where
        -- Exclude system schemas
        nspname != 'pg_toast'
        and nspname != 'pg_temp_1'
        and nspname != 'pg_toast_temp_1'
        and nspname != 'pg_statistic'
        and nspname != 'pg_catalog'
        and nspname != 'information_schema'
    LOOP
        EXECUTE format($$ GRANT USAGE ON SCHEMA %I TO replication_user $$, sch);
        EXECUTE format($$ GRANT SELECT ON ALL TABLES IN SCHEMA %I TO replication_user $$, sch);
        EXECUTE format($$ ALTER DEFAULT PRIVILEGES IN SCHEMA %I GRANT SELECT ON TABLES TO replication_user $$, sch);
    END LOOP;
END;
$do$;
```

### Create a publication on the source database

Publications are a fundamental part of logical replication in Postgres. They define what will be replicated. The following command examples create a publication named `azure_publication` with one or more tables.

To create a publication for a specific table:

```sql
CREATE PUBLICATION azure_publication FOR <tbl_name>;
```

To create a publication for multiple tables, provide a comma-separated list of tables:

```sql
CREATE PUBLICATION azure_publication FOR TABLE <tbl1, tbl2, tbl3>;
```

**Note:** Defining specific tables lets you add or remove tables from the publication later, which you cannot do when creating publications with `FOR ALL TABLES`.

For syntax details, see [CREATE PUBLICATION](https://www.postgresql.org/docs/current/sql-createpublication.html), in the PostgreSQL documentation.

### Allow inbound traffic from Neon

You need to allow inbound traffic from Neon servers so they can connect to your Azure database. To do this, follow these steps:

1. Log into the Azure portal and navigate to your Azure Postgres Server resource.

2. Click on the **Networking** option under the `Settings` section in the sidebar. Navigate to the **Firewall Rules** section under the `Public access` tab.

3. Click on `Add a Firewall Rule`, which generates a modal to add the range of IP addresses from which we want to allow connections. You will need to perform this step for each of the NAT gateway IP addresses associated with your Neon project's region. For each IP address, create a new rule and fill both the `Start IP` and `End IP` fields with the IP address.

   Neon uses 3 to 6 IP addresses per region for this outbound communication, corresponding to each availability zone in the region. See [NAT Gateway IP addresses](https://neon.com/docs/introduction/regions#nat-gateway-ip-addresses) for Neon's NAT gateway IP addresses.

4. To fetch the database schema using `pg_dump`, you also need to allow inbound traffic from your local machine (or where you are running `pg_dump`) so it can connect to your Azure database. Add another firewall rule entry with that IP address as the start and end IP address.

5. Click `Save` at the bottom to make sure all changes are saved.

## Prepare your Neon destination database

This section describes how to prepare your destination database (the subscriber) to receive replicated data.

You can find the connection details for your database by clicking the **Connect** button in the Console nav. See [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

### Create the Neon database

To keep parity with the Azure PostgreSQL deployment, create a new database with the same name. See [Create a database](https://neon.com/docs/manage/databases#create-a-database) for more information.

For this example, we run the following query to create a new database named `AdventureWorks` in the Neon project.

```sql
CREATE DATABASE "AdventureWorks";
```

### Import the database schema

To ensure that the Neon `AdventureWorks` database has the same schema as the Azure PostgreSQL database, we'll need to import the schema. You can use the `pg_dump` utility to export the schema and then `psql` to import it into Neon.

1. Export the schema from Azure PostgreSQL:

   ```shell
   pg_dump --schema-only --no-owner --no-privileges -h <azure-host> -U <azure-user> -d <azure-database> > schema.sql
   ```

2. Import the schema into your Neon database:

   ```shell
   psql <neon-connection-string> < schema.sql
   ```

### Create a subscription

After importing the schema, create a subscription on the Neon database:

1. Use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor), [psql](https://neon.com/docs/connect/query-with-psql-editor), or another SQL client to connect to your Neon database.

2. Create the subscription using the `CREATE SUBSCRIPTION` statement:

   ```sql
   CREATE SUBSCRIPTION neon_subscription
   CONNECTION 'host=<azure-host> port=5432 dbname=<azure-database> user=replication_user password=your_secure_password'
   PUBLICATION azure_publication;
   ```

3. Verify that the subscription was created by running the following query, and confirming that the subscription (`neon_subscription`) is listed:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

## Monitor and verify the replication

To ensure that data is being replicated correctly:

1. Monitor the replication status on Neon, by running the following query:

   ```sql
   SELECT * FROM pg_stat_subscription;
   ```

   This query should return an output similar to the following:

   ```text
    subid |      subname      | pid | leader_pid | relid | received_lsn |      last_msg_send_time       |     last_msg_receipt_time     | latest_end_lsn |        latest_end_time
    -------+-------------------+-----+------------+-------+--------------+-------------------------------+-------------------------------+----------------+-------------------------------
    24576 | neon_subscription | 540 |            |       | 1/3D0020A8   | 2024-09-11 11:34:24.841807+00 | 2024-09-11 11:34:24.869991+00 | 1/3D0020A8     | 2024-09-11 11:34:24.841807+00
    (1 row)
   ```

   - An active `pid` indicates that the subscription is active and running.
   - The `received_lsn` and `latest_end_lsn` columns show the LSN (Log Sequence Number) of the last received (at Neon) and last written data (at Azure source), respectively.
   - In this example, they have the same value, which means that all the data has been successfully replicated from Azure to Neon.

2. To verify that the data has been replicated correctly, compare row counts between Azure PostgreSQL and Neon for some key tables. For example, you can run the following query to check the number of rows in the `addresses` table:

   ```sql
   SELECT COUNT(*) FROM person.address;
   ```

   It returns the same output on both databases:

   ```text
     count
    -------
    19614
    (1 row)
   ```

3. Optionally, you can run some queries from your application against the Neon database to verify that it returns the same output as the Azure instance.

## Complete the migration

Once the initial data sync is complete and you've verified that ongoing changes are being replicated:

1. Stop writes to your Azure PostgreSQL database.
2. Wait for any final transactions to be replicated to Neon.
3. Update your application's connection string to point to your Neon database.

This ensures a much shorter downtime for the application, as you only need to wait for the last few transactions to be replicated before switching the application over to the Neon database.

**Note:** Remember to update any Azure-specific configurations or extensions in your application code to be compatible with Lakebase Postgres. For Lakebase Postgres parameter settings, see [Postgres parameter settings](https://neon.com/docs/reference/compatibility#postgres-parameter-settings). For Postgres extensions supported by Lakebase Postgres, see [Supported Postgres extensions](https://neon.com/docs/extensions/pg-extensions).

## Clean up

After successfully migrating and verifying your data on Neon, you can:

1. Drop the subscription on the Neon database:

   ```sql
   DROP SUBSCRIPTION neon_subscription;
   ```

2. Remove the publication from the Azure PostgreSQL database:

   ```sql
   DROP PUBLICATION azure_publication;
   ```

3. Consider backing up your Azure PostgreSQL database before decommissioning it.

## Other migration options

This section discusses migration options other than using logical replication.

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) when you run `pg_dump` or `pg_restore` against Neon.

- **pg_dump and pg_restore**

  If your database size is not large, you can use the `pg_dump` utility to create a dump file of your database, and then use `pg_restore` to restore the dump file to Neon. Please refer to the [Migrate from Postgres](https://neon.com/docs/import/migrate-from-postgres) guide for more information on this method.

- **Postgres GUI clients**

  Some Postgres clients offer backup and restore capabilities. These include [pgAdmin](https://www.pgadmin.org/docs/pgadmin4/latest/backup_and_restore.html) and [phppgadmin](https://github.com/phppgadmin/phppgadmin/releases), among others. We have not tested migrations using these clients, but if you are uncomfortable using command-line utilities, they may provide an alternative.

- **Table-level data migration using CSV files**

  Table-level data migration (using CSV files, for example) does not preserve database schemas, constraints, indexes, types, or other database features. You will have to create these separately. Table-level migration is simple but could result in significant downtime depending on the size of your data and the number of tables. For instructions, see [Import data from CSV](https://neon.com/docs/import/import-from-csv).

## Reference

For more information about logical replication and Postgres client utilities, refer to the following topics in the Postgres and Neon documentation:

- [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html)
- [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html)
- [psql](https://www.postgresql.org/docs/current/app-psql.html)
- [Postgres - Logical replication](https://www.postgresql.org/docs/current/logical-replication.html)
- [Neon logical replication guide](https://neon.com/docs/guides/logical-replication-guide)

--- [Document source](https://neon.com/docs/import/migrate-from-digital-ocean.md) ---

> Summary: Complete walkthrough for migrating a Postgres database from Digital Ocean managed Postgres to Neon using `pg_dump` (custom-format `-Fc`) and `pg_restore`, covering connection string retrieval, dump export, Neon database creation, and restore with `--no-owner` and `--no-acl` to avoid privilege conflicts. Choose this guide over the generic pg_dump guide when your source is Digital Ocean and you need provider-specific connection steps and flag guidance. For large databases or near-zero-downtime transfers, the page also references logical replication as an alternative.

# Migrate from Digital Ocean Postgres to Neon

Learn how to migrate your Postgres database from Digital Ocean to Neon using pg_dump and pg_restore

Last updated: 2026-10-09

This guide describes how to migrate a Postgres database from Digital Ocean to Neon using the `pg_dump` and `pg_restore` utilities, which are part of the Postgres client toolset. `pg_dump` works by dumping both the schema and data in a custom format that is compressed and suitable for input into `pg_restore` to rebuild the database.

## Prerequisites

- A Digital Ocean Postgres database containing the data you want to migrate.

- A Neon project to move the data to.
  For detailed information on creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project). Make sure to create a project with the same Postgres version as your Digital Ocean deployment.

- `pg_dump` and `pg_restore` utilities installed on your local machine. These typically come with a Postgres installation.

  We recommended that you use the `pg_dump` and `pg_restore` programs from the latest version of Postgres, to take advantage of enhancements that might have been made in these programs. To check the version of `pg_dump` or `pg_restore`, use the `-V` option. For example: `pg_dump -V`.

- Review our guide on [Importing data from Postgres](https://neon.com/docs/import/migrate-from-postgres) for more comprehensive information on using `pg_dump` and `pg_restore`.

## Prepare your Digital Ocean database

This section describes how to prepare your Digital Ocean database for exporting data.

To illustrate the migration workflow, we populate the Digital Ocean database with the [LEGO dataset](https://neon.com/docs/import/import-sample-data#lego-database). This database contains information about LEGO sets, parts, and themes.

### Retrieve Digital Ocean connection details

1. Log in to your Digital Ocean account and navigate to the Databases section.
2. Select your Postgres database.
3. In the **Connection Details** section under the **Overview** tab, you'll find the following information:
   - Host
   - Port
   - Database name
   - Username
   - Password (you may need to reset it if you don't have it)

You'll need these details to construct the connection string for `pg_dump`. Alternatively, you can toggle to the `Connection string` option to get the `postgresql://` connection string, which can be used directly with postgres CLI tools.

## Export data with pg_dump

Now that you have the Digital Ocean connection details, you can export your data using `pg_dump`:

```bash
pg_dump -Fc -v -d postgresql://[username]:[password]@[host]:[port]/[database] -f digitalocean_dump.bak
```

Replace `[username]`, `[password]`, `[host]`, `[port]`, and `[database]` with your Digital Ocean connection details.

This command includes these arguments:

- `-Fc`: Outputs the dump in custom format, which is compressed and suitable for input into `pg_restore`.
- `-v`: Runs `pg_dump` in verbose mode, allowing you to monitor the dump operation.
- `-d`: Specifies the connection string for your Digital Ocean database.
- `-f`: Specifies the output file name.

If the command was successful, you'll see output similar to the following:

```bash
pg_dump: saving encoding = UTF8
pg_dump: saving standard_conforming_strings = on
pg_dump: saving search_path =
pg_dump: saving database definition
pg_dump: dumping contents of table "public.lego_colors"
pg_dump: dumping contents of table "public.lego_inventories"
pg_dump: dumping contents of table "public.lego_inventory_parts"
pg_dump: dumping contents of table "public.lego_inventory_sets"
pg_dump: dumping contents of table "public.lego_part_categories"
pg_dump: dumping contents of table "public.lego_parts"
pg_dump: dumping contents of table "public.lego_sets"
pg_dump: dumping contents of table "public.lego_themes"
```

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

## Prepare your Neon destination database

This section describes how to prepare your destination Lakebase Postgres database to receive the imported data.

### Create the Neon database

Each Neon project comes with a default database named `neondb`. To maintain consistency with your Digital Ocean setup, create a new database with the same name.

1. Connect to your Neon project using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a Postgres client like `psql`.

2. Create a new database. For example, if your Digital Ocean database was named `lego`, run:

   ```sql
   CREATE DATABASE lego;
   ```

For more information, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).

### Retrieve Neon connection details

1. Open your project in the Neon Console.
2. Click **Connect** to open the **Connect to your branch** modal.
3. Copy the connection string. It will look similar to this:

   ```
   postgresql://[user]:[password]@[neon_hostname]/[dbname]
   ```

## Restore data to Neon with pg_restore

Now you can restore your data to the Neon database using `pg_restore`:

```bash
pg_restore -d <neon-connection-string> -v --no-owner --no-acl digitalocean_dump.bak
```

Replace `<neon-connection-string>` with your Neon connection details.

This command includes these arguments:

- `-d`: Specifies the connection string for your Neon database.
- `-v`: Runs `pg_restore` in verbose mode.
- `--no-owner`: Skips setting the ownership of objects as in the original database.
- `--no-acl`: Skips restoring access privileges for objects as in the original database.

We recommend using the `--no-owner` and `--no-acl` options to skip restoring these settings, as they may not be compatible between Digital Ocean and Neon. After migrating the data, review and configure the appropriate roles and privileges for all objects, as needed.

If the command was successful, you'll see output similar to the following:

```bash
pg_restore: connecting to database for restore
pg_restore: creating SCHEMA "public"
pg_restore: creating TABLE "public.lego_colors"
pg_restore: creating SEQUENCE "public.lego_colors_id_seq"
pg_restore: creating SEQUENCE OWNED BY "public.lego_colors_id_seq"
pg_restore: creating TABLE "public.lego_inventories"
pg_restore: creating SEQUENCE "public.lego_inventories_id_seq"
...
```

## Verify the migration

After the restore process completes, you should verify that your data has been successfully migrated:

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or `psql`.

2. Run some application queries to check your data. For example, if you're using the `LEGO` database, you can run the following:

   ```sql
   SELECT is_trans AS is_transparent, COUNT(*) FROM lego_colors GROUP BY is_trans;
   SELECT * FROM lego_sets ORDER BY num_parts DESC LIMIT 5;
   ```

3. Compare the results with those from running the same queries on your Digital Ocean database to ensure data integrity.

## Clean up

After successfully migrating and verifying your data on Neon, you can update your application's connection strings to point to your new Neon database. We recommend that you keep your Digital Ocean database dump file (`digitalocean_dump.bak`) as a backup until you've verified that the migration was successful.

## Other migration options

While this guide focuses on using `pg_dump` and `pg_restore`, there are other migration options available:

- **Logical replication**

  For larger databases or scenarios where you need to minimize downtime, you might consider using logical replication. See our guide on [Logical replication](https://neon.com/docs/guides/logical-replication-guide) for more information.

- **CSV export/import**

  For smaller datasets or specific tables, you might consider exporting to CSV from Digital Ocean and then importing to Neon. See [Import data from CSV](https://neon.com/docs/import/import-from-csv) for more details on this method.

## Reference

For more information on the Postgres utilities used in this guide, refer to the following documentation:

- [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html)
- [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html)
- [Migrating data to Neon](https://neon.com/docs/import/migrate-from-postgres)

--- [Document source](https://neon.com/docs/import/migrate-from-firebase.md) ---

> Summary: Firebase Firestore to Lakebase Postgres migration uses two custom Python scripts to export Firestore collections to line-delimited JSON files and import them into Postgres tables with id, parent_id, and JSONB data columns. Use this guide when replacing a NoSQL document store with a relational Postgres database that preserves Firestore subcollection hierarchies as parent-child rows. Alternatives for large datasets include the Google Cloud managed Firestore export service or open-source tools such as firestore-import-export.

# Migrate from Firebase Firestore to Lakebase Postgres

Learn how to migrate your data from Firebase Firestore to Lakebase Postgres using a custom Python script

Last updated: 2026-10-09

This guide describes how to migrate data from Firebase Firestore to Lakebase Postgres.

We'll use a custom Python script to export data from Firestore to a local file, and then import the data into Lakebase Postgres. This approach allows us to handle Firestore's document-based structure and convert it into the relational database format suitable for Postgres.

## Prerequisites

- A Firebase project containing the Firestore data you want to migrate.

- A Neon project to move the data to.

  For detailed information on creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- Python 3.10 or later installed on your local machine. Additionally, add the following packages to your Python virtual environment: `firebase_admin`, which is Google's python SDK for Firebase and `psycopg`, which is used to connect to the Lakebase Postgres database.

  You can install them using `pip`:

  ```bash
  pip install firebase-admin "psycopg[binary,pool]"
  ```

## Retrieve Firebase credentials

This section describes how to fetch the credentials to connect to your Firebase Firestore database.

1. Log in to your Firebase Console and navigate to your project.
2. Go to **Project settings** (the gear icon next to "Project Overview" in the left sidebar).
3. Under the **Service Accounts** tab, click **Generate new private key**. This will download a JSON file containing your credentials.
4. Save this JSON file securely on your local machine. We'll use it in our Python script.

For more information, please consult the [Firebase documentation](https://firebase.google.com/docs/admin/setup#initialize_the_sdk_in_non-google_environments).

## Export data from Firestore

In this step, we will use a Python script to export data from Firestore. This script will:

1. Connect to Firestore
2. Retrieve all collections and documents
3. Save the Firestore documents to a format suitable for ingesting into Postgres later

Here's the Python script:

```python
import argparse
import json
import os
from collections import defaultdict

import firebase_admin
from firebase_admin import credentials, firestore


def download_from_firebase(db, output_dir):
    # Create output directory if it doesn't exist
    if not os.path.exists(output_dir):
        os.makedirs(output_dir)

    # Initialize a defaultdict to store documents for each collection
    output: dict[str, list[dict]] = defaultdict(list)

    def _download_collection(collection_ref):
        print(f"Downloading from collection: {collection_ref.id}")

        # Determine the parent path for the current collection
        if collection_ref.parent:
            parent_path = collection_ref.parent.path
        else:
            parent_path = None

        # Iterate through all documents in the collection
        for doc in collection_ref.get():
            # Add document data to the output dictionary
            output[collection_ref.id].append(
                {
                    "id": doc.reference.path,
                    "parent_id": parent_path,
                    "data": doc.to_dict(),
                }
            )

            # Recursively handle subcollections
            for subcoll in doc.reference.collections():
                _download_collection(subcoll)

    # Start the download process with top-level collections
    for collection in db.collections():
        _download_collection(collection)

    # Save all (sub)collections to corresponding files
    for collection_id, docs in output.items():
        with open(os.path.join(output_dir, f"{collection_id}.json"), "w") as f:
            for doc in docs:
                f.write(json.dumps(doc) + "\n")


def main():
    parser = argparse.ArgumentParser(
        description="Download data from Firebase Firestore"
    )
    parser.add_argument(
        "--credentials", required=True, help="Path to Firebase credentials JSON file"
    )
    parser.add_argument(
        "--output",
        default="firestore_data",
        help="Output directory for downloaded data",
    )

    args = parser.parse_args()

    # Initialize Firebase app
    cred = credentials.Certificate(args.credentials)
    firebase_admin.initialize_app(cred)
    db = firestore.client()

    # Download data from Firebase
    download_from_firebase(db, args.output)
    print(f"Firestore data downloaded to {args.output}")


if __name__ == "__main__":
    main()
```

Save this script as `firebase-download.py`. To run the script, you need to provide the path to your Firebase credentials JSON file and the output directory for the downloaded data. Run the following command in your terminal:

```bash
python firebase-download.py --credentials path/to/your/firebase-credentials.json --output firestore_data
```

For each unique collection id, this script creates a line-delimited JSON file, and all documents in that collection (spanning different top-level documents) are saved to it. For example, if you have a collection with the following structure:

```
/users
  /user1
    /orders
      /order1
      /order2
        /items
          /item1
          /item2
  /user2
    /orders
      /order3
```

The script will create the following files:

- `users.json`: Contains all user documents, i.e., `user1`, `user2`.
- `orders.json`: Contains all order documents across all users - `order1`, `order2`, `order3`.
- `items.json`: Contains all item documents across all orders - `item1`, `item2`.

Each file contains a JSON object for each document. To illustrate, `order1` gets saved to `orders.json` in the following format:

```json
{
  "id": "users/user1/orders/order1",
  "parent_id": "users/user1",
  "data": {
    "order_date": "2023-06-15",
    "total_amount": 99.99
  }
}
```

This structure allows for easy reconstruction of the hierarchical relationships between users, orders, and items, while also providing a flat file structure that's easy to process and import into other systems.

## Prepare your Neon destination database

This section describes how to prepare your destination Lakebase Postgres database to receive the imported data.

### Create the Neon database

1. Open your project in the Neon Console.
2. In the sidebar, select **Postgres database** > **Databases**.
3. Click **Add database**.
4. Enter a name for your database and click **Create**.

For more information, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).

### Retrieve Neon connection details

1. Open your project in the Neon Console.
2. Click **Connect** to open the **Connect to your branch** modal, and select your database.
3. Copy the connection string. It will look similar to this:

   ```
   postgresql://[user]:[password]@[neon_hostname]/[dbname]
   ```

## Import data into Neon

We use another python script to import the firestore data we previously downloaded into Neon.

```python
import argparse
import json
import os

import psycopg
from psycopg.types.json import Jsonb


def upload_to_postgres(input_dir, conn_string):
    # Connect to the Postgres database
    conn = psycopg.connect(conn_string)

    # Iterate through all JSON files in the input directory
    for filename in os.listdir(input_dir):
        cur = conn.cursor()
        if filename.endswith(".json"):
            table_name = filename[:-5]  # Remove .json extension
            print("Writing to table: ", table_name)

            # Create table for the collection if it doesn't exist
            create_table_query = f"""
            CREATE TABLE IF NOT EXISTS {table_name} (
                id TEXT PRIMARY KEY,
                parent_id TEXT,
                data JSONB
            )
            """
            cur.execute(create_table_query)

            # Read and insert data from the JSON file
            with open(os.path.join(input_dir, filename), "r") as f:
                insert_query = f"""
                INSERT INTO {table_name} (id, parent_id, data)
                VALUES (%s, %s, %s)
                ON CONFLICT (id) DO UPDATE
                SET parent_id = EXCLUDED.parent_id, data = EXCLUDED.data
                """
                batch = []
                for line in f:
                    doc = json.loads(line)
                    batch.append((doc["id"], doc["parent_id"], Jsonb(doc["data"])))
                    if len(batch) == 20:
                        cur.executemany(insert_query, batch)
                        batch = []

                # Commit changes
                conn.commit()

    # Close the cursor and connection
    cur.close()
    conn.close()


def main():
    parser = argparse.ArgumentParser(description="Upload data to Postgres")
    parser.add_argument(
        "--input",
        default="firestore_data",
        help="Input directory containing JSON files",
    )
    parser.add_argument("--postgres", required=True, help="Postgres connection string")

    args = parser.parse_args()

    # Upload data to Postgres
    upload_to_postgres(args.input, args.postgres)
    print(f"Data from {args.input} uploaded to Postgres")


if __name__ == "__main__":
    main()
```

Save this script as `neon-import.py`. To run the script, you need to provide the path to the input directory containing the JSON files and the Neon connection string. Run the following command in your terminal:

```bash
python neon-import.py --input firestore_data --postgres "<neon-connection-string>"
```

This script iterates over each JSON file in the input directory, creates a table in the Neon database for each collection, and inserts the data into the table. It also handles conflicts by updating the existing data with the new data.

## Verify the migration

After running both the Firestore export and the Neon import scripts, you should verify that your data has been successfully migrated:

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or `psql`.

2. List all tables in your database:

   ```sql
   \dt
   ```

3. Run some sample queries to check that the data has been successfully imported. For example, the following query fetches all orders made by the first two customers:

   ```sql
   SELECT data FROM orders
   WHERE parent_id IN (
       SELECT id FROM customers
       LIMIT 2
   )
   ```

   Compare the results with those from your Firestore database to ensure data integrity. Note that using the `parent_id` field, we can navigate through the hierarchical structure of the original data.

## Other migration options

While this guide focuses on using a custom Python script, there are other migration options available:

- **Firestore managed export/import**

  If you have a large volume of data to migrate, you can use the [Google Cloud Firestore managed export and import service](https://firebase.google.com/docs/firestore/manage-data/export-import). It allows you to export your Firestore data to a Google Cloud Storage bucket, from where you can download and ingest it into Neon.

- **Open source utilities**

  There are also a number of open source utilities available that can help export data from Firestore to local files.

  - [firestore-import-export](https://github.com/dalenguyen/firestore-import-export)
  - [firestore-backup-restore](https://github.com/dalenguyen/firestore-backup-restore)

  However, these utilities are not as robust as the managed export/import service. If your data size is not big, we recommend using the sample code provided above or adapting it to your specific needs.

## Reference

For more information on the tools and libraries used in this guide, refer to the following documentation:

- [Migrating data to Neon](https://neon.com/docs/import/migrate-intro)
- [Firebase Admin SDK](https://firebase.google.com/docs/admin/setup)
- [Cloud Firestore API](https://cloud.google.com/python/docs/reference/firestore/latest/index.html)
- [psycopg](https://www.psycopg.org/docs/)

--- [Document source](https://neon.com/docs/import/migrate-from-heroku.md) ---

> Summary: Heroku to Neon migration using the Heroku CLI command `heroku pg:pull`, which runs pg_dump and pg_restore under the hood. Walks through creating a Neon project, obtaining the required unpooled connection string, and verifying the imported data in the Neon Console.

# Migrate from Heroku to Lakebase Postgres

Last updated: 2026-09-16

This guide describes how to import your data from Heroku Postgres to Neon.

**Note: New feature**

If you are looking to migrate your database to Neon, you may want to try our new **Migration Assistant**, which can help. Read the [guide](https://neon.com/docs/import/migration-assistant) to learn more.

The instructions assume that you have installed the Heroku CLI, which is used to transfer data from Heroku. For installation instructions, see [The Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).

## Create a Neon project and copy the connection string

1. Navigate to the [Projects](https://console.neon.tech/app/projects) page in the Neon Console.
2. Click **New Project**.
3. Specify your project settings and click **Create Project**.
4. After creating a project, click **Connect** in the Console nav to find your database connection details. Copy the connection string. It is required to import your data from Heroku.

   The example connection string used the instructions that follow is:

   ```text
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   **Important:** `heroku pg:pull` uses `pg_dump` toward your Neon database. Avoid using a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

## Retrieve your Heroku app name and database name

1. Log in to [Heroku](https://dashboard.heroku.com/) and select the project you want to import data from.
2. Select **Overview** and copy the name of the Heroku Postgres database, which appears under **Installed add-ons**.
3. Click **Settings** and copy your Heroku **App Name**.

**Note:** You can also retrieve the Heroku Postgres database name using the following Heroku CLI command:

```shell
heroku pg:links --app <app>
```

where `<app>` is the Heroku App Name.

For example:

```shell
$ heroku pg:links --app thawing-wave-57227
=== postgresql-trapezoidal-48645
```

## Import your data

From your terminal, run the following Heroku CLI command:

```shell
heroku pg:pull --app [app] [heroku-pg-database] [neon-connection-string]
```

where:

- `[app]` is the name of the Heroku app
- `[heroku-pg-database]` is the name of the Heroku PostgreSQL database
- `[neon-connection-string]` is the Neon connection string

For example:

```shell
$ heroku pg:pull --app thawing-wave-57227 postgresql-trapezoidal-48645 postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require

heroku-cli: Pulling postgresql-trapezoidal-48645 ---> postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require

pg_dump: last built-in OID is 16383
pg_dump: reading extensions
pg_dump: identifying extension members
pg_dump: reading schemas
pg_dump: reading user-defined tables
pg_dump: reading user-defined functions
pg_dump: reading user-defined types
pg_dump: reading procedural languages
pg_dump: reading user-defined aggregate functions
pg_dump: reading user-defined operators
pg_dump: reading user-defined access methods
pg_dump: reading user-defined operator classes
pg_dump: reading user-defined operator families
pg_dump: reading user-defined text search parsers
pg_dump: reading user-defined text search templates
pg_dump: reading user-defined text search dictionaries
pg_dump: reading user-defined text search configurations
pg_dump: reading user-defined foreign-data wrappers
pg_dump: reading user-defined foreign servers
pg_dump: reading default privileges
pg_dump: reading user-defined collations
pg_dump: reading user-defined conversions
pg_dump: reading type casts
pg_dump: reading transforms
pg_dump: reading table inheritance information
pg_dump: reading event triggers
pg_dump: finding extension tables
pg_dump: finding inheritance relationships
pg_dump: reading column info for interesting tables
pg_dump: finding the columns and types of table "public.customer"
pg_dump: finding the columns and types of table "public.order"
pg_dump: flagging inherited columns in subtables
pg_dump: reading indexes
pg_dump: reading indexes for table "public.customer"
pg_dump: reading indexes for table "public.order"
pg_dump: flagging indexes in partitioned tables
pg_dump: reading extended statistics
pg_dump: reading constraints
pg_dump: reading foreign key constraints for table "public.customer"
pg_dump: reading foreign key constraints for table "public.order"
pg_dump: reading triggers
pg_dump: reading triggers for table "public.customer"
pg_dump: reading triggers for table "public.order"
pg_dump: reading rewrite rules
pg_dump: reading policies
pg_dump: reading row-level security policies
pg_dump: reading publications
pg_dump: reading publication membership
pg_dump: reading subscriptions
pg_dump: reading large objects
pg_dump: reading dependency data
pg_dump: saving encoding = UTF8
pg_dump: saving standard_conforming_strings = on
pg_dump: saving search_path =
pg_dump: saving database definition
pg_dump: dumping contents of table "public.customer"
pg_restore: connecting to database for restore
pg_dump: dumping contents of table "public.order"
pg_restore: creating SCHEMA "heroku_ext"
pg_restore: creating TABLE "public.customer"
pg_restore: creating TABLE "public.order"
pg_restore: processing data for table "public.customer"
pg_restore: processing data for table "public.order"
pg_restore: creating CONSTRAINT "public.customer customer_pkey"
pg_restore: creating CONSTRAINT "public.order order_pkey"
pg_restore: creating FK CONSTRAINT "public.order order_customer_id_fkey"
heroku-cli: Pulling complete.
```

## Verify that your data was imported

1. Log in to the [Neon Console](https://console.neon.tech/app/projects).
2. Select the Neon project that you transferred data to.
3. In the sidebar, select **Postgres database** > **Tables**.
4. In the sidebar, verify that your database tables appear under the **Tables** heading.

--- [Document source](https://neon.com/docs/import/migrate-from-neon.md) ---

> Summary: Neon-to-Neon database migration using a single piped `pg_dump | pg_restore` command moves data between projects without writing an intermediate dump file to disk. Best for smaller databases or CLI workflows where a one-step transfer is acceptable. For large or complex datasets, use a separate dump and restore instead. Requires an unpooled connection string for both source and destination.

# Migrate data from another Neon project

Last updated: 2026-09-16

This guide describes how to migrate a database from one Neon project to another by **piping** output from **`pg_dump`** straight into **`pg_restore`** (`pg_dump ... | pg_restore ...`). That runs the dump and restore in one step without writing an intermediate dump file on disk.

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

## Important considerations

- **Upgrading the Postgres version**: When upgrading to a new version of Postgres, always test thoroughly before migrating your production systems or applications.
- **Piping considerations**: Piping simplifies the operation, but for large or complex datasets, we highly recommend a **separate** dump and restore. See [Migrate data from Postgres with pg_dump and pg_restore](https://neon.com/docs/import/migrate-from-postgres).

## Import data from another project

To import your data from another Neon project:

1. Create a new project with the desired region or Postgres version. See [Create a project](https://neon.com/docs/manage/projects#create-a-project) for instructions.

2. Create a database with the desired name in your new Neon project. See [Create a database](https://neon.com/docs/manage/databases#create-a-database) for instructions.

3. Retrieve the connection strings for the new and existing Neon databases.

   You can find the connection details for your database by clicking the **Connect** button in the Console nav. Connection strings have this format:

   ```bash
   postgresql://[user]:[password]@[neon_hostname]/[dbname]
   ```

4. Prepare your command to pipe data from one Neon project to the other. For the `pg_dump` command, specify connection details for the source database. For the `pg_restore` command, specify connection details for the destination database. The command should have the following format:

   ```bash
   pg_dump -Fc -v -d postgresql://[user]:[password]@[source_neon_hostname]/[dbname] | pg_restore -v -d postgresql://[user]:[password]@[destination_neon_hostname]/[dbname]
   ```

   With actual source and destination connection details, your command will appear similar to this:

   ```bash
   pg_dump -Fc -v -d postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/my_source_db?sslmode=require&channel_binding=require | pg_restore -v -d postgresql://alex:AbC123dEf@square-shadow-654321.us-east-2.aws.neon.tech/my_destination_db?sslmode=require&channel_binding=require
   ```

   **Note:** While your source and destination databases might have the same name, the hostnames will differ, as illustrated in the example above.

   The command includes these arguments:

   - `-Fc`: Sends the output to a custom-format archive suitable for input into `pg_restore`.
   - `-v`: Runs commands in verbose mode, allowing you to monitor what happens during the operation.
   - `-d`: Specifies the database name or connection string.

5. Run the command from your terminal or command window.

6. Run some test queries on the target database to ensure everything imported correctly.

7. Switch the connection string in your app to point to your new Neon database.

8. If you no longer need the old Neon project, you can remove it. See [Delete a project](https://neon.com/docs/manage/projects#delete-a-project) for instructions.

--- [Document source](https://neon.com/docs/import/migrate-from-planetscale.md) ---

> Summary: Migrating a PlanetScale MySQL (Vitess-compatible) database to Lakebase Postgres uses pgloader, which converts schema, maps types (MySQL AUTO_INCREMENT to Postgres SERIAL, TINYINT to BOOLEAN), and transfers data in a single point-in-time operation. Writes on PlanetScale must be paused during migration to prevent data loss. Use this guide when switching from PlanetScale to Neon and needing a full schema-plus-data transfer. Neon's Free plan supports up to 1 GB; larger databases require a paid plan. The Neon connection string needs the endpoint ID embedded in the password field as a pgloader workaround.

# Migrate from PlanetScale MySQL to Lakebase Postgres

Learn how to migrate your database from PlanetScale to Lakebase Postgres using pgloader

Last updated: 2026-10-01

This guide provides step-by-step instructions for migrating a PlanetScale MySQL database to Lakebase Postgres using the `pgloader` utility. `pgloader` is an open-source tool that facilitates data migration from various sources to Postgres, including MySQL databases like PlanetScale. It handles schema creation, data type mapping, and data transfer efficiently, making it a popular choice for MySQL to Postgres migrations.

## Prerequisites

Before you begin, make sure that you have the following:

- A PlanetScale account and a database you want to migrate. PlanetScale databases use MySQL-compatible Vitess.
- A Neon account and a project. See [Sign up](https://neon.com/docs/get-started/signing-up).
- A properly named database. For example, if you are migrating a database named `my_app`, you might want to create a database of the same name in Neon. See [Create a database](https://neon.com/docs/manage/databases#create-a-database) for instructions.
- Neon's Free plan supports 1 GB of data. If your data size is more than 1 GB, you'll need to upgrade to one of Neon's paid plans. See [Neon plans](https://neon.com/docs/introduction/plans) for more information.
- **Schedule migration downtime:** `pgloader` performs a point-in-time migration, which means that any changes made to the PlanetScale database after the migration process has started will not be reflected in the Neon database. You will need to pause writes to your PlanetScale database (schedule downtime) during the migration to avoid data loss.
- **Configure IP allowlisting:** Ensure that the machine running `pgloader` has its IP address permitted on both the PlanetScale and Neon sides. See [PlanetScale IP restrictions](https://planetscale.com/docs/postgres/connecting/ip-restrictions) and Neon [IP allow rules](https://neon.com/docs/manage/projects#configure-ip-allow).

Also, a close review of the [Pgloader MySQL to Postgres Guide](https://pgloader.readthedocs.io/en/latest/ref/mysql.html) is recommended before you start. This guide will provide you with a good understanding of `pgloader` capabilities and how to configure your `pgloader` configuration file, if necessary.

## Retrieve your PlanetScale database credentials

You'll need your PlanetScale database connection details to configure `pgloader` for the migration:

1. Log into the [PlanetScale dashboard](https://app.planetscale.com) and select your database.
2. Click the **Connect** button.
3. Select **MySQL CLI** to get the connection details. Make sure to select **Direct connection string** to get a standard MySQL connection string that you can use in your `pgloader` configuration file.

   ![PlanetScale Connect modal showing MySQL CLI connection string](https://neon.com/docs/import/planetscale_connect_modal.png)

Save your PlanetScale connection details.

## Retrieve your Neon database connection string

Log in to the [Neon Console](https://console.neon.tech). Find the connection string for your database by clicking the **Connect** button in the Console nav. Make sure the **Connection pooling** toggle is disabled to get a direct connection string.

![Neon Connect modal showing connection string](https://neon.com/docs/connect/connection_details_without_connection_pooling.png)

Your connection string should look similar to this:

```plaintext
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Update the connection string to include your **endpoint ID** (ep-cool-darkness-123456 in this example) along with your password by using the `endpoint` keyword. Also remove the `channel_binding` parameter, as it is not supported by `pgloader`. The modified connection string should look like this:

```plaintext
postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require
```

**Note:** Passing the `endpoint ID` with your password is a required workaround for some Postgres drivers, including the one used by `pgloader`. For more information about this workaround and why it's required, refer to our [connection workaround](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field) documentation.

Keep your Neon connection string handy for later use.

## Install pgloader

You'll need to have `pgloader` installed on your local machine to perform the migration:

1. Install the `pgloader` utility using your preferred installation method. Debian (apt), RPM package, and Docker methods are supported, as well as Homebrew for macOS (`brew install pgloader`). If your macOS has an ARM processor, use the Homebrew installation method.

   See [Installing pgloader](https://pgloader.readthedocs.io/en/latest/install.html) for Debian (apt), RPM package, and Docker installation instructions.

2. Create a `pgloader` configuration file (for example, `planetscale_to_neon.load`). Use your PlanetScale database credentials to define the connection string for your database source. Use the Neon database connection string you retrieved and modified in the previous step as the destination.

   **Note:** If you need to specify an SSL mode in your connection string, the following format is recommended: `sslmode=require`. Other formats may not work.

   Example configuration in `planetscale_to_neon.load`:

   ```plaintext
   load database
    from mysql://username:password@host/source_db?sslmode=require
    into postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require;
   ```

   > Replace `username`, `password`, `host`, and `source_db` with your PlanetScale database credentials (`DATABASE_USERNAME`, `DATABASE_PASSWORD`, `DATABASE_HOST`, and `DATABASE_NAME`). Also update the destination connection string with your modified Neon connection string.

## Run the migration with pgloader

To initiate the migration process, run:

```shell
pgloader planetscale_to_neon.load
```

The command output will look similar to this:

```bash
LOG report summary reset
             table name     errors       rows      bytes      total time
-----------------------  ---------  ---------  ---------  --------------
        fetch meta data          0          2                     0.727s
         Create Schemas          0          0                     0.346s
       Create SQL Types          0          0                     0.178s
          Create tables          0          2                     0.551s
         Set Table OIDs          0          1                     0.094s
-----------------------  ---------  ---------  ---------  --------------
    "db-test".dbname             0          1     0.0 kB          0.900s
-----------------------  ---------  ---------  ---------  --------------
COPY Threads Completion          0          4                     0.905s
 Index Build Completion          0          1                     0.960s
         Create Indexes          0          1                     0.257s
        Reset Sequences          0          0                     1.083s
           Primary Keys          0          1                     0.263s
    Create Foreign Keys          0          0                     0.000s
        Create Triggers          0          0                     0.169s
        Set Search Path          0          1                     0.427s
       Install Comments          0          0                     0.000s
-----------------------  ---------  ---------  ---------  --------------
      Total import time          ✓          1     0.0 kB          4.064s
```

**Warning: fell through ECASE expression error?**

If you encounter an `ERROR mysql: 255 fell through ECASE expression` (or similar) error when running the migration, this is a known issue that can occasionally occur. To fix this, you may need to build `pgloader` from source. For more information, refer to this [Stack Overflow thread](https://stackoverflow.com/questions/75493241/mysql-to-postgres-migration-pgloader-error-mysql-76-fell-through-ecase-express).

## Verify the migration

After the migration is complete, connect to your Neon database and run some queries to verify that the data has been transferred correctly:

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or [psql](https://neon.com/docs/connect/query-with-psql-editor).

2. Run a few queries to check your data. For example:

   ```sql
   SELECT COUNT(*) FROM your_table_name;
   SELECT id, name FROM your_table_name ORDER BY created_at DESC LIMIT 5;
   ```

3. Compare the results with the same queries run on your PlanetScale database to ensure data integrity.

## MySQL to Postgres considerations

MySQL and Postgres have different data types, SQL syntax, and features. `pgloader` handles most common type conversions automatically, but review the mapped types after migration.

For example, MySQL's `AUTO_INCREMENT` becomes Postgres `SERIAL`, `TINYINT` becomes `BOOLEAN`, and `DATETIME` becomes `TIMESTAMP`. Follow the [Pgloader MySQL Database Casting Rules](https://pgloader.readthedocs.io/en/latest/ref/mysql.html#mysql-database-casting-rules) if you need specific type casting or want to customize conversions according to your own requirements.

Here's an example of how to specify type casting in your `pgloader` configuration file:

```plaintext
load database
 from mysql://username:password@host/source_db?sslmode=require
 into postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require;

 CAST type datetime to timestamp drop default drop not null;
```

This example casts MySQL's `DATETIME` type to Postgres `TIMESTAMP` while dropping any default values and `NOT NULL` constraints. Adjust the casting rules as needed for your specific schema and data types.

## References

- [Installing pgloader](https://pgloader.readthedocs.io/en/latest/install.html)
- [Pgloader Tutorial: Migrating from MySQL to PostgreSQL](https://pgloader.readthedocs.io/en/latest/tutorial/tutorial.html#migrating-from-mysql-to-postgresql)
- [Pgloader MySQL to Postgres Guide](https://pgloader.readthedocs.io/en/latest/ref/mysql.html)
- [Pgloader MySQL Database Casting Rules](https://pgloader.readthedocs.io/en/latest/ref/mysql.html#mysql-database-casting-rules)

--- [Document source](https://neon.com/docs/import/migrate-from-postgres.md) ---

> Summary: Command reference for migrating a Postgres database to Neon using `pg_dump` and `pg_restore`, covering flags (-Fc, -j, -O/--no-owner), custom-format archives, and piping for small databases. Use this page when you need exact dump/restore commands. For region migration or logical replication decisions, see the Region migration page instead. Neon requires unpooled connection strings, and does not support `pg_dumpall` or the `-C/--create` option.

# Migrate data from Postgres with pg_dump and pg_restore

Last updated: 2026-11-04

This topic describes migrating data from one Postgres database to another using the `pg_dump` and `pg_restore`.

It is the **command reference** for dump and restore (flags, ownership, piping). If you are choosing **whether** to use another Neon region, Lakebase, logical replication, or the Import Data Assistant, read **[Region migration](https://neon.com/docs/import/region-migration)** first.

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string) (see PgBouncer issues [452](https://github.com/pgbouncer/pgbouncer/issues/452) & [976](https://github.com/pgbouncer/pgbouncer/issues/976) for details). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

Repeat the `pg_dump` and `pg_restore` process for each database you want to migrate.

If you are performing this procedure to migrate data from one Neon project to another to upgrade to a new Postgres version, read [Upgrading your Postgres version](https://neon.com/docs/postgresql/postgres-upgrade) first.

## Before you begin

- We recommended that you use the `pg_dump` and `pg_restore` programs from the latest version of Postgres, to take advantage of enhancements that might have been made in these programs. To check the version of `pg_dump` or `pg_restore`, use the `-V` option. For example: `pg_dump -V`.

- Neon supports PostgreSQL 14, 15, 16, and 17. We recommend that clients are the same version as source Postgres instance.

- Retrieve the connection parameters or connection string for your source Postgres database. This could be a Lakebase Postgres database or another Postgres database. The instructions below use a [connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING), but you can use the connection format you prefer. If you are logged in to a local Postgres instance, you may only need to provide the database name. Refer to the [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html) documentation for information about connection parameters.

- Optionally, create a role in Neon to perform the restore operation. The role that performs the restore operation becomes the owner of restored database objects. For example, if you want role `sally` to own database objects, create `role` sally in Neon and perform the restore operation as `sally`.

- If you have assigned database object ownership to different roles in your source database, read [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations). You may want to add the `-O, --no-owner` option to your `pg_restore` command to avoid errors.

- Create the target database in Neon. For example, if you are migrating a database named `pagila`, create a database named `pagila` in Neon. For instructions, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).

- Retrieve the connection string for the target Neon database. You can find the connection string by clicking the **Connect** button in the Console nav. It will look something like this:

  ```bash
  postgresql://[user]:[password]@[neon_hostname]/[dbname]
  ```

- Consider running a test migration first to ensure your actual migration goes smoothly. See [Run a test migration](https://neon.com/docs/import/migrate-from-postgres#run-a-test-migration).

- If your database is small, you can pipe `pg_dump` output directly to `pg_restore` to save time. See [Pipe pg_dump to pg_restore](https://neon.com/docs/import/migrate-from-postgres#pipe-pgdump-to-pgrestore).

## Export data with pg_dump

Export your data from the source database with `pg_dump`:

```bash
pg_dump -Fc -v -d <source_database_connection_string> -f <dump_file_name>
```

The `pg_dump` command above includes these arguments:

- `-Fc`: Sends the output to a custom-format archive suitable for input into `pg_restore`.
- `-v`: Runs `pg_dump` in verbose mode, allowing you to monitor what happens during the dump operation.
- `-d`: Specifies the source database name or [connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING).
- `-f`: The dump file name. It can be any name you choose (`mydumpfile.bak`, for example).

For more command options, see [Advanced pg_dump and pg_restore options](https://neon.com/docs/import/migrate-from-postgres#advanced-pgdump-and-pgrestore-options).

### Export a database as a plain SQL file

To export your database as a portable, human-readable `.sql` file instead of a custom-format archive, leave out the `-F` option. Plain text is the default `pg_dump` format:

```bash
pg_dump -d <source_database_connection_string> -f dump.sql
```

The result is a SQL script you can read, edit, version, or grep, and replay with `psql -f dump.sql`. You can narrow what you export with `--schema-only` (no data), `--data-only` (no DDL), or `-t <table_name>` (a single table). Add `--no-owner` to skip `ALTER OWNER` statements when you plan to restore to a different role. See [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations).

Choose the custom format (`-Fc`) shown above when you want `pg_restore` features such as selective or parallel restore. Choose plain SQL when you want to read or edit the output, or load it with `psql`. Note that `psql` only supports plain-text dumps.

## Restore data to Neon with pg_restore

Restore your data to the target database in Neon with `pg_restore`.

**Note:** If you assigned database object ownership to different roles in your source database, consider adding the `-O, --no-owner` option to your `pg_restore` command to avoid errors. See [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations).

```bash
pg_restore -v -d <neon_database_connection_string> <dump_file_name>
```

The example above includes these arguments:

- `-v`: Runs `pg_restore` in verbose mode, allowing you to monitor what happens during the restore operation.
- `-d`: Specifies the Neon database to connect to. The value is a Neon database connection string. See [Before you begin](https://neon.com/docs/import/migrate-from-postgres#before-you-begin).
- `<dump_file_name>` is the name of the dump file you created with `pg_dump`.

For more command options, see [Advanced pg_dump and pg_restore options](https://neon.com/docs/import/migrate-from-postgres#advanced-pgdump-and-pgrestore-options).

## pg_dump and pg_restore example

The following example shows how data from a `pagila` source database is dumped and restored to a `pagila` database in Neon using the commands described in the previous sections. (A database named `pagila` was created in Neon prior to running the restore operation.)

```bash
~$ cd mydump
~/mydump$ pg_dump -Fc -v -d postgresql://[user]:[password]@[neon_hostname]/pagila -f mydumpfile.bak

~/mydump$ ls
mydumpfile.bak

~/mydump$ pg_restore -v -d postgresql://[user]:[password]@[neon_hostname]/pagila mydumpfile.bak
```

## Pipe pg_dump to pg_restore

For small databases where the source and target Postgres instances and databases are presumed to be compatible, the standard output of `pg_dump` can be piped directly into a `pg_restore` command to minimize migration downtime:

```bash
pg_dump [args] | pg_restore [args]
```

For example:

```bash
pg_dump -Fc -v -d <source_database_connection_string> | pg_restore -v -d <neon-database-connection-string>
```

Piping is not recommended for large databases because it can fail during lengthy migration operations. Incompatibilities between the source and target Postgres instances or databases may also cause a piping operation to fail. If you're importing from another Postgres instance, review Neon's [compatibility](https://neon.com/docs/reference/compatibility) page to ensure that Lakebase Postgres is compatible with your source Postgres instance. If you're unsure or encounter issues, consider using separate dump and restore operations. This approach lets you adjust dump and restore options or modify the dump file directly to resolve migration challenges.

When piping `pg_dump` output directly to `pg_restore`, the custom output format (`-Fc`) is most efficient. The directory format (`-Fd`) format cannot be piped to `pg_restore`.

## Post-migration steps

After migrating your data, update your applications to connect to your new database in Neon. You will need the database connection string that you used in your `pg_restore` command. If you run into any problems, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app). After connecting your applications, test them thoroughly to ensure they function correctly with your new database.

## Database object ownership considerations

Roles created in the Neon Console, including the default role created with your Neon project, are automatically granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neon_superuser-role) role. This role can create roles and databases, select from all tables and views, and insert, update, or delete data in all tables. However, the `neon_superuser` is not a PostgreSQL `superuser`. It cannot run `ALTER OWNER` statements to grant ownership of database objects. As a result, if you granted ownership of database objects in your source database to different roles, your dump file will contain `ALTER OWNER` statements, and those statements will cause non-fatal errors when you restore data to your Neon database.

**Note:** Regardless of `ALTER OWNER` statement errors, a restore operation still succeeds because assigning ownership is not necessary for the data itself to be restored. The restore operation will still create tables, import data, and create other objects.

To avoid the non-fatal errors, you can ignore database object ownership statements when restoring data by specifying the `-O, --no-owner` option in your `pg_restore` command:

```bash
pg_restore -v -O -d postgresql://[user]:[password]@[neon_hostname]/pagila mydumpfile.bak
```

The Neon role performing the restore operation becomes the owner of all database objects.

## Advanced pg_dump and pg_restore options

The `pg_dump` and `pg_restore` commands provide numerous advanced options, some of which are described below. Full descriptions and more options are found in the PostgreSQL [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html) and [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html) documentation.

### pg_dump options

- `-Z`: Defines the compression level to use when using a compressible format. 0 means no compression, while 9 means maximum compression. In general, we recommend a setting of 1. A higher compression level slows the dump and restore process but also uses less disk space.
- `--lock-wait-timeout=20s`: Error out early in the dump process instead of waiting for an unknown amount of time if there is lock contention.
  Do not wait forever to acquire shared table locks at the beginning of the dump. Instead fail if unable to lock a table within the specified timeout.
- `-j <njobs>`: Consider this option for large databases to dump tables in parallel. Set `<njobs>` to the number of available CPUs. Refer to the [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html) documentation for more information.
- `--no-blobs`: Excludes large objects from your dump. See [Data migration notes](https://neon.com/docs/import/migrate-from-postgres#data-migration-notes).

### pg_restore options

- `-c --if-exists`: Drop database objects before creating them if they already exist. If you had a failed migration, you can use these options to drop objects created by the previous migration to avoid errors when retrying the migration.
- `-j <njobs>`: Consider this option for large databases to run the restore process in parallel. Set `<njobs>` to the number of available CPU cores based on your compute size. Refer to the [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html) documentation for more information.
- `--single-transaction`: Forces the operation to run as an atomic transaction, which ensures that no data is left behind when a restore operation fails. Retrying an import operation after a failed attempt that leaves data behind may result in "duplicate key value" errors.
- `--no-tablespaces`: Do not output commands to select tablespaces. See [Data migration notes](https://neon.com/docs/import/migrate-from-postgres#data-migration-notes).
- `-t <table_name>`: Allows you to restore individual tables from a custom-format database dump. Individual tables can also be imported from a CSV file. See [Import from CSV](https://neon.com/docs/import/import-from-csv).

## Run a test migration

It is recommended that you run a test migration before migrating your production database. Make sure you can successfully migrate data to the new database and connect to it. Before starting the actual migration, create a database dump and address any issues that show up. In Neon, you can quickly create a test database, obtain the connection string, and delete the database when you are finished with it. See [Create a database](https://neon.com/docs/manage/databases#create-a-database).

## Other migration options

This section discusses migration options other than `pg_dump` and `pg_restore`.

### Postgres GUI clients

Some Postgres clients offer backup and restore capabilities. These include [pgAdmin](https://www.pgadmin.org/docs/pgadmin4/latest/backup_and_restore.html) and [phppgadmin](https://github.com/phppgadmin/phppgadmin/releases), among others. We have not tested migrations using these clients, but if you are uncomfortable using command-line utilities, they may provide an alternative.

### Table-level data migration

Table-level data migration (using CSV files, for example) does not preserve database schemas, constraints, indexes, types, or other database features. You will have to create these separately. Table-level migration is simple but could result in significant downtime depending on the size of your data and the number of tables. For instructions, see [Import data from CSV](https://neon.com/docs/import/import-from-csv).

## Data migration notes

- You can load data using the `psql` utility, but it only supports plain-text SQL dumps, which you should only consider for small datasets or specific use cases. To create a plain-text SQL dump with `pg_dump` utility, leave out the `-F` format option. Plain-text SQL is the default `pg_dump` output format.
- `pg_dumpall` is not supported.
- `pg_dump` with the `-C, --create` option is not supported.
- Some PostgreSQL features, such as tablespaces and large objects, which require access to the local file system are not supported by Neon. To exclude selecting tablespaces, specify the `--no-tablespaces` option with `pg_restore`. To exclude large objects, specify the `--no-blobs` option with `pg_dump`.

## Reference

For information about the Postgres client utilities referred to in this topic, refer to the following topics in the Postgres documentation:

- [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html)
- [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html)
- [psql](https://www.postgresql.org/docs/current/app-psql.html)

--- [Document source](https://neon.com/docs/import/migrate-from-railway.md) ---

> Summary: Step-by-step guide for moving a Railway Postgres database to Neon using `pg_dump` and `pg_restore`. Covers how to retrieve Railway's `DATABASE_PUBLIC_URL` via the TCP Proxy setting and apply `--no-owner --no-acl` flags during restore to drop Railway-specific ownership and access control settings. Use this page when migrating from Railway specifically, as distinct from the general Postgres migration guide. Also covers logical replication and CSV import as alternatives for larger datasets or minimal-downtime requirements.

# Migrate from Railway Postgres to Lakebase Postgres

Learn how to migrate your database from Railway to Lakebase Postgres using pg_dump and pg_restore

Last updated: 2026-10-09

This guide describes how to migrate a database from Railway to Lakebase Postgres using the `pg_dump` and `pg_restore` utilities, which are part of the Postgres client toolset. `pg_dump` works by dumping both the schema and data in a custom format that is compressed and suitable for input into `pg_restore` to rebuild the database.

## Prerequisites

- A Railway project containing the Postgres database you want to migrate.

- A Neon project to move the data to.

  For detailed information on creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project). Make sure to create a project with the same Postgres version as your Railway deployment.

- `pg_dump` and `pg_restore` utilities installed on your local machine. These typically come with a Postgres client installation. Install the same version of Postgres client tools as the Postgres version used in your Railway database to ensure compatibility.

  To check the version of `pg_dump` or `pg_restore`, use the `-V` option. For example: `pg_dump -V`.

- Review the guide on [Migrating data from Postgres](https://neon.com/docs/import/migrate-from-postgres) for more comprehensive information on using `pg_dump` and `pg_restore`.

## Prepare your Railway database

This section describes how to prepare your Railway database for exporting data.

To illustrate the migration workflow, this guide uses the [LEGO Database](https://neon.com/docs/import/import-sample-data#lego-database). This database contains information about LEGO sets, parts, and themes. The LEGO database is loaded into Railway using the [psql](https://neon.com/docs/connect/query-with-psql-editor) command-line tool.

### Retrieve Railway connection details

1. Log in to your [Railway dashboard](https://railway.com/dashboard) and navigate to your project.
2. Select your Postgres service in the project canvas.
3. Click the **Variables** tab to view the environment variables.
4. Copy the value of the `DATABASE_PUBLIC_URL` variable.

   **Tip:** To connect to your Railway database from your local machine, ensure the [TCP Proxy](https://docs.railway.com/networking/tcp-proxy) is enabled for your database service. With the proxy active, you can use the `DATABASE_PUBLIC_URL` connection string to connect to your database from your local machine.
   ![TCP Proxy toggle in Railway dashboard](https://neon.com/docs/import/railway_tcp_proxy.png)

You'll need this connection string for `pg_dump` to connect to the Railway database.

## Export data with pg_dump

Now that you have your Railway connection details, you can export your data using `pg_dump`:

```bash
pg_dump -Fc -v -d <railway_database_url> --schema=public -f railway_dump.bak
```

Replace `<railway_database_url>` with your Railway `DATABASE_URL`.

This command includes these arguments:

- `-Fc`: Outputs the dump in custom format, which is compressed and suitable for input into `pg_restore`.
- `-v`: Runs `pg_dump` in verbose mode, allowing you to monitor the dump operation.
- `-d`: Specifies the connection string for your Railway database.
- `-f`: Specifies the output file name.
- `--schema=public`: Specifies the schema to dump. In this case, you only want to back up tables in the `public` schema.

If the command was successful, you'll see output similar to the following:

```bash

...
pg_dump: saving encoding = UTF8
pg_dump: saving standard_conforming_strings = on
pg_dump: saving search_path =
pg_dump: saving database definition
pg_dump: dumping contents of table "public.lego_colors"
pg_dump: dumping contents of table "public.lego_inventories"
pg_dump: dumping contents of table "public.lego_inventory_parts"
pg_dump: dumping contents of table "public.lego_inventory_sets"
pg_dump: dumping contents of table "public.lego_part_categories"
pg_dump: dumping contents of table "public.lego_parts"
pg_dump: dumping contents of table "public.lego_sets"
pg_dump: dumping contents of table "public.lego_themes"
```

## Prepare your Neon destination database

This section describes how to prepare your destination Lakebase Postgres database to receive the imported data.

### Create the Neon database

To maintain consistency with your Railway setup, you might want to create a new database in Neon with the same database name used in Railway.

1. Connect to your Neon project using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a Postgres client like `psql`.

2. Create a new database. For example, if your Railway database was named `lego`, run:

   ```sql
   CREATE DATABASE lego;
   ```

For more information, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).

### Retrieve Neon connection details

1. Open your project in the Neon Console.
2. Select **Connect** to open the **Connect to your branch** modal.
3. Select the user and database as needed for your connection. Make sure the **Connection pooling** toggle is disabled to get a direct connection string.
4. Copy the connection string. It will look similar to this:

   ```text
   postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require
   ```

## Restore data to Neon with pg_restore

Now you can restore your data to the Neon database using `pg_restore`:

```bash
pg_restore -d <neon-connection-string> -v --no-owner --no-acl railway_dump.bak
```

Replace `<neon-connection-string>` with your Neon connection string.

This command includes these arguments:

- `-d`: Specifies the connection string for your Neon database.
- `-v`: Runs `pg_restore` in verbose mode.
- `--no-owner`: Skips setting the ownership of objects as in the original database.
- `--no-acl`: Skips restoring access privileges for objects as in the original database.

Use the `--no-owner` and `--no-acl` options to skip restoring ownership and access control settings from Railway. After migrating the data, review and configure the appropriate roles and privileges for all objects, as needed. For more information, refer to the section on [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations).

If the command was successful, you'll see output similar to the following:

```bash
pg_restore: connecting to database for restore
pg_restore: creating SCHEMA "public"
pg_restore: creating TABLE "public.lego_colors"
pg_restore: creating SEQUENCE "public.lego_colors_id_seq"
pg_restore: creating SEQUENCE OWNED BY "public.lego_colors_id_seq"
pg_restore: creating TABLE "public.lego_inventories"
pg_restore: creating SEQUENCE "public.lego_inventories_id_seq"
...
```

## Verify the migration

After the restore process completes, you should verify that your data has been successfully migrated:

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or [psql](https://neon.com/docs/connect/query-with-psql-editor).

2. Run some application queries to check your data. For example, if you're using the LEGO database, you can run the following:

   ```sql
   SELECT * FROM lego_inventory_parts ORDER BY quantity DESC LIMIT 5;
   SELECT parent_id, COUNT(name) FROM lego_themes GROUP BY parent_id;
   ```

3. Compare the results with those from running the same queries on your Railway database to ensure data integrity.

## Clean up

After successfully migrating and verifying your data on Neon, you can update your application's connection strings to point to your new Neon database. Keep your Railway database dump file (`railway_dump.bak`) as a backup until you've verified that the migration was successful.

## Other migration options

While this guide focuses on using `pg_dump` and `pg_restore`, there are other migration options available:

- **Logical replication**

  For larger databases or scenarios where you need to minimize downtime, you might consider using logical replication. See the guide on [Logical replication](https://neon.com/docs/guides/logical-replication-guide) for more information.

- **CSV export/import**

  For smaller datasets or specific tables, you might consider exporting to CSV from Railway and then importing to Neon. See [Import data from CSV](https://neon.com/docs/import/import-from-csv) for more details on this method.

## Reference

For more information on the Postgres utilities used in this guide, refer to the following documentation:

- [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html)
- [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html)
- [Migrating data to Neon](https://neon.com/docs/import/migrate-from-postgres)

--- [Document source](https://neon.com/docs/import/migrate-from-render.md) ---

> Summary: Migration guide for moving a PostgreSQL database from Render to Neon using `pg_dump` and `pg_restore`. Retrieve the Render External Database URL, dump the public schema to a custom-format file (`-Fc`), then restore to Neon using an unpooled connection string with `--no-owner` and `--no-acl`. Choose this page over the general Postgres migration guide when Render is the source, as it covers Render-specific connection steps and the ownership flags required when moving between hosted providers. Also covers logical replication as an alternative for large databases with minimal downtime.

# Migrate from Render to Lakebase Postgres

Learn how to migrate your database from Render to Lakebase Postgres using pg_dump and pg_restore

Last updated: 2026-10-09

This guide describes how to migrate a database from Render to Lakebase Postgres.

We use the `pg_dump` and `pg_restore` utilities, which are part of the Postgres client toolset. `pg_dump` works by dumping both the schema and data in a custom format that is compressed and suitable for input into `pg_restore` to rebuild the database.

## Prerequisites

- A Render project containing the Postgres database you want to migrate.

- A Neon project to move the data to.

  For detailed information on creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project). Make sure to create a project with the same Postgres version as your Render deployment.

- `pg_dump` and `pg_restore` utilities installed on your local machine. These typically come with a Postgres installation.

  We recommended that you use the `pg_dump` and `pg_restore` programs from the latest version of Postgres, to take advantage of enhancements that might have been made in these programs. To check the version of `pg_dump` or `pg_restore`, use the `-V` option. For example: `pg_dump -V`.

- Review our guide on [Migrating data from Postgres](https://neon.com/docs/import/migrate-from-postgres) for more comprehensive information on using `pg_dump` and `pg_restore`.

## Prepare your Render database

This section describes how to prepare your Render database for exporting data.

To illustrate the migration workflow, we use the [LEGO Database](https://neon.com/docs/import/import-sample-data#lego-database). This database contains information about LEGO sets, parts, and themes. We load the LEGO database into Render using the [psql](https://neon.com/docs/connect/query-with-psql-editor) command-line tool.

### Retrieve Render connection details

1. Log in to your Render account and navigate to your project dashboard.
2. From the overview page, select the service (of the type `PostgreSQL`) corresponding to your database.
3. From the left sidebar, click on **Info** and under the **Connections** section, you'll find the connection parameters in different formats.
4. Copy the value for the `External Database URL` field.

You'll need this connection string for `pg_dump` to connect to the Render database.

## Export data with pg_dump

Now that you have your Render connection details, you can export your data using `pg_dump`:

```bash
pg_dump -Fc -v -d <render_external_database_url> --schema=public -f render_dump.bak
```

Replace `<render_external_database_url>` with your Render External Database URL.

This command includes these arguments:

- `-Fc`: Outputs the dump in custom format, which is compressed and suitable for input into `pg_restore`.
- `-v`: Runs `pg_dump` in verbose mode, allowing you to monitor the dump operation.
- `-d`: Specifies the connection string for your Render database.
- `-f`: Specifies the output file name.
- `--schema=public`: Specifies the schema to dump. In this case, we only want to back up tables in the `public` schema.

If the command was successful, you'll see output similar to the following:

```bash

...
pg_dump: saving encoding = UTF8
pg_dump: saving standard_conforming_strings = on
pg_dump: saving search_path =
pg_dump: saving database definition
pg_dump: dumping contents of table "public.lego_colors"
pg_dump: dumping contents of table "public.lego_inventories"
pg_dump: dumping contents of table "public.lego_inventory_parts"
pg_dump: dumping contents of table "public.lego_inventory_sets"
pg_dump: dumping contents of table "public.lego_part_categories"
pg_dump: dumping contents of table "public.lego_parts"
pg_dump: dumping contents of table "public.lego_sets"
pg_dump: dumping contents of table "public.lego_themes"
```

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

## Prepare your Neon destination database

This section describes how to prepare your destination Lakebase Postgres database to receive the imported data.

### Create the Neon database

To maintain consistency with your Render setup, you might want to create a new database in Neon with the same database name used in Render.

1. Connect to your Neon project using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a Postgres client like `psql`.

2. Create a new database. For example, if your Render database was named `lego`, run:

   ```sql
   CREATE DATABASE lego;
   ```

For more information, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).

### Retrieve Neon connection details

1. Open your project in the Neon Console.
2. Select **Connect** to open the **Connect to your branch** modal.
3. Select the user and database as needed for your connection. Make sure the **Connection pooling** toggle is disabled to get an unpooled connection string.
4. Copy the connection string. It will look similar to this:

   ```text
   postgresql://[user]:[password]@[neon_hostname]/[dbname]?sslmode=require&channel_binding=require
   ```

## Restore data to Neon with pg_restore

Now you can restore your data to the Neon database using `pg_restore`:

```bash
pg_restore -d <neon-connection-string> -v --no-owner --no-acl render_dump.bak
```

Replace `<neon-connection-string>` with your Neon connection string.

This command includes these arguments:

- `-d`: Specifies the connection string for your Neon database.
- `-v`: Runs `pg_restore` in verbose mode.
- `--no-owner`: Skips setting the ownership of objects as in the original database.
- `--no-acl`: Skips restoring access privileges for objects as in the original database.

We recommend using the `--no-owner` and `--no-acl` options to skip restoring ownership and access control settings from Render. After migrating the data, review and configure the appropriate roles and privileges for all objects, as needed. For more information, refer to the section on [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations).

If the command was successful, you'll see output similar to the following:

```bash
pg_restore: connecting to database for restore
pg_restore: creating SCHEMA "public"
pg_restore: creating TABLE "public.lego_colors"
pg_restore: creating SEQUENCE "public.lego_colors_id_seq"
pg_restore: creating SEQUENCE OWNED BY "public.lego_colors_id_seq"
pg_restore: creating TABLE "public.lego_inventories"
pg_restore: creating SEQUENCE "public.lego_inventories_id_seq"
...
```

## Verify the migration

After the restore process completes, you should verify that your data has been successfully migrated:

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or [psql](https://neon.com/docs/connect/query-with-psql-editor).

2. Run some application queries to check your data. For example, if you're using the LEGO database, you can run the following:

   ```sql
   SELECT * FROM lego_inventory_parts ORDER BY quantity DESC LIMIT 5;
   SELECT parent_id, COUNT(name) FROM lego_themes GROUP BY parent_id;
   ```

3. Compare the results with those from running the same queries on your Render database to ensure data integrity.

## Clean up

After successfully migrating and verifying your data on Neon, you can update your application's connection strings to point to your new Neon database. We recommend that you keep your Render database dump file (`render_dump.bak`) as a backup until you've verified that the migration was successful.

## Other migration options

While this guide focuses on using `pg_dump` and `pg_restore`, there are other migration options available:

- **Logical replication**

  For larger databases or scenarios where you need to minimize downtime, you might consider using logical replication. See our guide on [Logical replication](https://neon.com/docs/guides/logical-replication-guide) for more information.

- **CSV export/import**

  For smaller datasets or specific tables, you might consider exporting to CSV from Render and then importing to Neon. See [Import data from CSV](https://neon.com/docs/import/import-from-csv) for more details on this method.

## Reference

For more information on the Postgres utilities used in this guide, refer to the following documentation:

- [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html)
- [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html)
- [Migrating data to Neon](https://neon.com/docs/import/migrate-from-postgres)

--- [Document source](https://neon.com/docs/import/migrate-from-supabase.md) ---

> Summary: Step-by-step guide to moving a Supabase Postgres database to Neon using `pg_dump` and `pg_restore`, with `--no-owner` and `--no-acl` flags required because Supabase ties object ownership to its own authentication system. Use this page when you need a full offline dump-and-restore migration; for near-zero downtime, the guide points to logical replication from Supabase instead. Also covers connection string retrieval, schema selection with `--schema` for public and non-public schemas (auth, storage), and post-restore verification.

# Migrate from Supabase to Lakebase Postgres

Learn how to migrate your database from Supabase to Lakebase Postgres using pg_dump and pg_restore

Last updated: 2026-11-06

This guide describes how to migrate a database from Supabase to Lakebase Postgres.

We use the `pg_dump` and `pg_restore` utilities, which are part of the Postgres client toolset. `pg_dump` works by dumping both the schema and data in a custom format that is compressed and suitable for input into `pg_restore` to rebuild the database.

**Note:** You can also replicate data from Supabase for a near-zero downtime migration. See [Replicate data from Supabase](https://neon.com/docs/guides/logical-replication-supabase-to-neon).

## Prerequisites

- A Supabase project containing the data you want to migrate.

- A Neon project to move the data to.

  For detailed information on creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project). Make sure to create a project with the same Postgres version as your Supabase deployment.

- `pg_dump` and `pg_restore` utilities installed on your local machine. These typically come with a Postgres installation.

  We recommended that you use the `pg_dump` and `pg_restore` programs from the latest version of Postgres, to take advantage of enhancements that might have been made in these programs. To check the version of `pg_dump` or `pg_restore`, use the `-V` option. For example: `pg_dump -V`.

- Review our guide on [Migrating data from Postgres](https://neon.com/docs/import/migrate-from-postgres) for more comprehensive information on using `pg_dump` and `pg_restore`.

## Prepare your Supabase database

This section describes how to prepare your Supabase database for exporting data.

To illustrate the migration workflow, we use the [LEGO Database](https://neon.com/docs/import/import-sample-data#lego-database). This database contains information about LEGO sets, parts, and themes.

### Retrieve Supabase connection details

1. Log in to your Supabase account and navigate to your project dashboard.
2. In the left sidebar, click on **Project Settings**.
3. Select **Database**, where you will find the below settings under the **Connection Parameters** section:
   - Host
   - Database name
   - Port
   - User
   - Password [Not visible in the dashboard]

You'll need these details to construct your connection string for `pg_dump`.

## Export data with pg_dump

Now that you have your Supabase connection details, you can export your data using `pg_dump`:

```bash
pg_dump -Fc -v -d postgresql://[user]:[password]@[supabase_host]:[port]/[database] --schema=public -f supabase_dump.bak
```

Replace `[user]`, `[password]`, `[supabase_host]`, `[port]`, and `[database]` with your Supabase connection details.

This command includes these arguments:

- `-Fc`: Outputs the dump in custom format, which is compressed and suitable for input into `pg_restore`.
- `-v`: Runs `pg_dump` in verbose mode, allowing you to monitor the dump operation.
- `-d`: Specifies the connection string for your Supabase database.
- `-f`: Specifies the output file name.
- `--schema=public`: Specifies the schema to dump. In this case, we only want to back up tables in the `public` schema.

Supabase projects may also store data corresponding to authentication, storage and other services under different schemas. If necessary, you can specify additional schemas to dump by adding the `--schema` option multiple times.

If the command was successful, you'll see output similar to the following:

```bash

...
pg_dump: saving encoding = UTF8
pg_dump: saving standard_conforming_strings = on
pg_dump: saving search_path =
pg_dump: saving database definition
pg_dump: dumping contents of table "public.lego_colors"
pg_dump: dumping contents of table "public.lego_inventories"
pg_dump: dumping contents of table "public.lego_inventory_parts"
pg_dump: dumping contents of table "public.lego_inventory_sets"
pg_dump: dumping contents of table "public.lego_part_categories"
pg_dump: dumping contents of table "public.lego_parts"
pg_dump: dumping contents of table "public.lego_sets"
pg_dump: dumping contents of table "public.lego_themes"
```

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

## Prepare your Neon destination database

This section describes how to prepare your destination Lakebase Postgres database to receive the imported data.

### Create the Neon database

To maintain consistency with your Supabase setup, you can create a new database in Neon with the same database name you used in Supabase.

1. Connect to your Neon project using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or a Postgres client like [psql](https://neon.com/docs/connect/query-with-psql-editor).

2. Create a new database. For example, if your Supabase database was named `lego`, run:

   ```sql
   CREATE DATABASE lego;
   ```

For more information, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).

### Retrieve Neon connection details

1. Open your project in the Neon Console.
2. Select **Connect** to open the **Connect to your branch** modal.
3. Copy the connection string. It will look similar to this:

   ```
   postgresql://[user]:[password]@[neon_hostname]/[dbname]
   ```

## Restore data to Neon with pg_restore

Now you can restore your data to the Neon database using `pg_restore`:

```bash
pg_restore -d <neon-connection-string> -v --no-owner --no-acl supabase_dump.bak
```

Replace `[user]`, `[password]`, `[neon_hostname]`, and `[dbname]` with your Neon connection details.

This command includes these arguments:

- `-d`: Specifies the connection string for your Neon database.
- `-v`: Runs `pg_restore` in verbose mode.
- `--no-owner`: Skips setting the ownership of objects as in the original database.
- `--no-acl`: Skips restoring access privileges for objects as in the original database.

A Supabase database has ownership and access control tied to the authentication system. We recommend that you use the `--no-owner` and `--no-acl` options to skip restoring these settings. After migrating the data, review and configure the appropriate roles and privileges for all objects, as needed. For more information, refer to the section on [Database object ownership considerations](https://neon.com/docs/import/migrate-from-postgres#database-object-ownership-considerations).

If the command was successful, you'll see output similar to the following:

```bash
pg_restore: connecting to database for restore
pg_restore: creating SCHEMA "public"
pg_restore: while PROCESSING TOC:
pg_restore: from TOC entry 13; 2615 2200 SCHEMA public pg_database_owner
pg_restore: error: could not execute query: ERROR:  schema "public" already exists
Command was: CREATE SCHEMA public;


pg_restore: creating COMMENT "SCHEMA public"
pg_restore: creating TABLE "public.lego_colors"
pg_restore: creating SEQUENCE "public.lego_colors_id_seq"
pg_restore: creating SEQUENCE OWNED BY "public.lego_colors_id_seq"
pg_restore: creating TABLE "public.lego_inventories"
pg_restore: creating SEQUENCE "public.lego_inventories_id_seq"
...

```

## Verify the migration

After the restore process completes, you should verify that your data has been successfully migrated:

1. Connect to your Neon database using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or `psql`.

2. Run some application queries to check your data. For example, if you're using the LEGO database, you can run the following:

   ```sql
   SELECT COUNT(*) FROM lego_sets;
   SELECT * FROM lego_themes LIMIT 5;
   ```

3. Compare the results with those from running the same queries on your Supabase database to ensure data integrity.

## Clean up

After successfully migrating and verifying your data on Neon, you can update your application's connection strings to point to your new Neon database. We recommend that you keep your Supabase dump file (`supabase_dump.bak`) as a backup until you've verified that the migration was successful.

## Other migration options

While this guide focuses on using `pg_dump` and `pg_restore`, there are other migration options available:

- **Logical replication**

  For larger databases or scenarios where you need to minimize downtime, you might consider using logical replication. See our guide on [Logical replication](https://neon.com/docs/guides/logical-replication-guide) for more information.

- **CSV export/import**

  For smaller datasets or specific tables, you might consider exporting to CSV from Supabase and then importing to Neon. See [Import data from CSV](https://neon.com/docs/import/import-from-csv) for more details on this method.

## Reference

For more information on the Postgres utilities used in this guide, refer to the following documentation:

- [pg_dump](https://www.postgresql.org/docs/current/app-pgdump.html)
- [pg_restore](https://www.postgresql.org/docs/current/app-pgrestore.html)
- [Migrating data to Neon](https://neon.com/docs/import/migrate-from-postgres)
- [Neon vs Supabase comparison](https://neon.com/guides/neon-vs-supabase)

--- [Document source](https://neon.com/docs/import/migrate-from-turso.md) ---

> Summary: Migration guide for moving a Turso (libSQL/SQLite) database to Lakebase Postgres using pgloader. Dumps the Turso database to a local SQLite file with the Turso CLI, then loads it into Neon where pgloader converts SQLite type affinities to Postgres types. Use this guide when the source is Turso or SQLite; it also covers swapping Turso drivers for the Neon serverless driver, translating `?` placeholders to `$1` parameters, adapting dialect differences like LIKE vs ILIKE, and verifying sequences after migration. Neon's Free plan supports up to 1 GB; larger Turso databases require a paid Neon plan.

# Migrate from Turso to Lakebase Postgres

Last updated: 2026-09-29

This guide describes how to migrate your Turso database to Lakebase Postgres using [pgloader](https://pgloader.readthedocs.io/en/latest/intro.html).

`pgloader` is an open-source data loading and migration tool that efficiently transfers data from various sources (like CSV, MySQL, SQLite, MS SQL, etc.) into Postgres, handling schema and data transformations on the fly. Since Turso databases are SQLite-compatible, you can dump them to a local SQLite file and then use `pgloader` to migrate that file to Lakebase Postgres.

## Prerequisites

Before you begin, ensure you have the following:

- A Neon account and a project. If you don't have one, see [Sign up](https://neon.com/docs/get-started/signing-up).
- A database created in your Neon project. For instructions, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).
- The [Turso CLI](https://docs.turso.tech/cli/introduction) installed. You'll use it to export your database.
- The `sqlite3` command-line tool, typically pre-installed on macOS and Linux.
- Neon's Free plan supports 1 GB of data. If your data size is more than 1 GB, you'll need to upgrade to one of Neon's paid plans. See [Neon plans](https://neon.com/docs/introduction/plans) for more information.

A review of the [pgloader SQLite to Postgres Guide](https://pgloader.readthedocs.io/en/latest/ref/sqlite.html) is also recommended. It provides a comprehensive overview of `pgloader`'s capabilities and type mappings, which will be helpful for understanding the migration process.

## Understanding SQLite and Postgres data types

Before migrating from Turso to Postgres, it's helpful to understand a key difference in how they handle data types. Turso, built on SQLite, uses a flexible typing system called "type affinity". You can store any type of data in any column, regardless of its declared type. Postgres uses a strict, static typing system. Data inserted into a column must precisely match the column's declared data type.

When converting a database, SQLite's type affinities are mapped to appropriate Postgres types. Here is a summary of the common mappings:

| Data Type Category              | SQLite                                | PostgreSQL                                                                          | Key Differences & Notes                                                                                                                                                                                                                                                                                                   |
| :------------------------------ | :------------------------------------ | :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Integer**                     | `INTEGER`                             | `SMALLINT` (2 bytes)<br/>`INTEGER` (4 bytes)<br/>`BIGINT` (8 bytes)                 | SQLite's `INTEGER` is a flexible-size signed integer, storing values in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value. PostgreSQL offers fixed-size integers for more granular control over storage and performance.                                                                                  |
| **Auto-incrementing Integer**   | `INTEGER PRIMARY KEY`                 | `SMALLSERIAL` (2 bytes)<br/>`SERIAL` (4 bytes)<br/>`BIGSERIAL` (8 bytes)            | In SQLite, declaring a column as `INTEGER PRIMARY KEY` automatically makes it an alias for the `rowid` and thus auto-incrementing. PostgreSQL provides the `SERIAL` pseudo-types, which create a sequence object to generate unique identifiers.                                                                          |
| **Floating-Point**              | `REAL`                                | `REAL` (4 bytes)<br/>`DOUBLE PRECISION` (8 bytes)                                   | SQLite's `REAL` is an 8-byte IEEE floating-point number. PostgreSQL offers both single-precision (`REAL`) and double-precision (`DOUBLE PRECISION`) floating-point numbers.                                                                                                                                               |
| **Arbitrary Precision Numeric** | `NUMERIC`                             | `NUMERIC(precision, scale)`<br/>`DECIMAL(precision, scale)`                         | SQLite's `NUMERIC` affinity will attempt to store data as `INTEGER` or `REAL`, or as `TEXT` if it cannot be losslessly converted. PostgreSQL's `NUMERIC` and `DECIMAL` types are for exact decimal arithmetic, crucial for financial and scientific applications, allowing for user-defined precision and scale.          |
| **String**                      | `TEXT`<br/>`VARCHAR(n)`<br/>`CHAR(n)` | `TEXT`<br/>`VARCHAR(n)`<br/>`CHAR(n)`                                               | While both databases accept these type names, in SQLite, they all have a `TEXT` affinity. The length `(n)` is not enforced in SQLite. In PostgreSQL, `VARCHAR(n)` enforces a maximum length, and `CHAR(n)` is a fixed-length, blank-padded string. `TEXT` in PostgreSQL has no predefined length limit.                   |
| **Binary Data**                 | `BLOB`                                | `BYTEA`                                                                             | Both are used for storing raw binary data.                                                                                                                                                                                                                                                                                |
| **Date & Time**                 | `TEXT`<br/>`REAL`<br/>`INTEGER`       | `DATE`<br/>`TIME`<br/>`TIMESTAMP`<br/>`TIMESTAMPTZ` (with time zone)<br/>`INTERVAL` | SQLite has no dedicated date/time storage class; they are typically stored as `TEXT` (ISO-8601 strings), `REAL` (Julian day numbers), or `INTEGER` (Unix timestamps). PostgreSQL provides a rich set of specific date and time types with built-in functions for complex date and time arithmetic and time zone handling. |
| **Boolean**                     | `INTEGER` (0 for false, 1 for true)   | `BOOLEAN`                                                                           | SQLite does not have a native boolean type and commonly uses `INTEGER` with values 0 and 1. PostgreSQL has a dedicated `BOOLEAN` type that stores `true` or `false`.                                                                                                                                                      |
| **JSON**                        | `TEXT`                                | `JSON`<br/>`JSONB`                                                                  | In SQLite, JSON data is stored as `TEXT`. PostgreSQL offers two dedicated JSON types: `JSON` for storing the raw JSON text and `JSONB` for a decomposed binary format that is more efficient for indexing and querying.                                                                                                   |
| **Unique Identifier**           | -                                     | `UUID`                                                                              | PostgreSQL has a dedicated `UUID` data type for storing Universally Unique Identifiers, which is not present in SQLite.                                                                                                                                                                                                   |
| **Array**                       | -                                     | `data_type[]`                                                                       | PostgreSQL supports arrays of any built-in or user-defined data type, a powerful feature for storing lists of values in a single column. SQLite does not have a native array type.                                                                                                                                        |

## Authenticate Turso CLI

If you haven't authenticated the Turso CLI yet, run:

```shell
turso auth login
```

Follow the prompts to log in with your Turso account credentials. This will allow you to access your Turso databases and export them for migration.

## Export your Turso database

Dump your Turso database to a local sql file using the `turso db shell` command with the `.dump` option:

```bash
turso db shell <database-name> .dump > dump.sql
```

Replace `<database-name>` with the name of your Turso database. This command connects to your Turso database and runs the `.dump` command, which outputs the full schema and data as SQL statements.

Next, generate a local SQLite database file from the dump:

```bash
sqlite3 turso_export.db < dump.sql
```

You now have a `turso_export.db` file containing your data, ready for migration.

## Retrieve your Neon database connection string

Log in to the [Neon Console](https://console.neon.tech). Find the connection string for your database by clicking the **Connect** button in the Console nav. Make sure the **Connection pooling** toggle is disabled:

![Connection details modal with connection pooling disabled](https://neon.com/docs/connect/connection_details_without_connection_pooling.png)

Your connection string should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require
```

**Important:** You will need to remove `&channel_binding=require` from the connection string, as `pgloader` does not support channel binding and throws an error when it is present.

Now, modify this connection string to pass your **endpoint ID** (`ep-cool-darkness-123456` in this example) to Neon with your password using the `endpoint` keyword, as shown here:

```bash
postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require
```

**Note:** Passing the `endpoint ID` with your password is a required workaround for some Postgres drivers, including the one used by `pgloader`. For more information, see [Connect with an endpoint ID](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field).

Keep your modified Neon connection string handy.

## Install pgloader

Install the `pgloader` utility using your preferred method:

- For **macOS** with Homebrew: `brew install pgloader`
- For **Debian/Ubuntu**: `sudo apt-get install pgloader`
- For **Docker**: Pull the latest image with `docker pull dimitri/pgloader:latest`

For other systems, see [Installing pgloader](https://pgloader.readthedocs.io/en/latest/install.html).

## Run a basic migration

For a straightforward migration, run `pgloader` directly from the command line:

```shell
pgloader sqlite://turso_export.db "postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require"
```

> Make sure to enclose the Postgres connection string in quotes to prevent shell interpretation issues.

The command output will look similar to this:

```bash
2025-06-27T08:26:19.941000Z LOG report summary reset
             table name     errors       rows      bytes      total time
-----------------------  ---------  ---------  ---------  --------------
                  fetch          0          0                     0.000s
        fetch meta data          0          5                     0.204s
         Create Schemas          0          0                     0.108s
       Create SQL Types          0          0                     0.222s
          Create tables          0          4                     1.307s
         Set Table OIDs          0          2                     0.121s
-----------------------  ---------  ---------  ---------  --------------
                authors          0          3     0.1 kB          1.082s
                  books          0          5     0.2 kB          0.993s
-----------------------  ---------  ---------  ---------  --------------
COPY Threads Completion          0          4                     1.080s
 Index Build Completion          0          2                     2.342s
         Create Indexes          0          2                     0.662s
        Reset Sequences          0          0                     1.297s
           Primary Keys          0          2                     0.650s
    Create Foreign Keys          0          1                     0.339s
        Create Triggers          0          0                     0.211s
       Install Comments          0          0                     0.000s
-----------------------  ---------  ---------  ---------  --------------
      Total import time          ✓          8     0.3 kB          6.581s
```

pgloader will automatically create the necessary tables and indexes in your Lakebase Postgres database, and transfer all data from the `turso_export.db` file. The summary report at the end confirms that the migration completed successfully without errors.

## Advanced migration with custom casting

For better control over the destination schema, create a `pgloader` load file. This lets you cast columns to specific Postgres types.

For example, if you have an `authors` table with an `id` column that is an `INTEGER PRIMARY KEY` in Turso (SQLite), you can cast it to `SERIAL` in Postgres. Similarly, if you have a `published_date` column stored as `TEXT`, you can cast it to `DATE`

Create a file named `turso.load` with the following content, replacing the connection strings as needed:

```sql
LOAD DATABASE
    FROM sqlite://turso_export.db
    INTO postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require

WITH
    include drop,
    create tables,
    create indexes,
    reset sequences,
    downcase identifiers

CAST
    -- Cast integer primary keys to SERIAL
    column authors.id to serial,
    column books.id to serial,

    -- Cast text date columns to Postgres DATE
    column books.published_date to date;
```

Run the migration using the load file:

```shell
pgloader turso.load
```

The migration will produce a cleaner Postgres schema with `SERIAL` primary keys and proper Postgres date types.

## Post-migration verification

After migrating, always verify your data.

### Verify sequences

The `reset sequences` option in the load file ensures that auto-incrementing columns start from the correct value. Connect to your Neon database using [`psql`](https://neon.com/docs/connect/query-with-psql-editor) or the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) and check the next value for a table's sequence:

```sql
SELECT nextval(pg_get_serial_sequence('books', 'id'));
```

This should return a value one higher than the max `id` in the `books` table. If it doesn't, you can reset it manually:

```sql
SELECT setval(
    pg_get_serial_sequence('books', 'id'),
    (SELECT MAX(id) FROM books) + 1
);
```

### Verify row counts

Compare row counts between your Turso source and Neon destination:

```sql
SELECT count(*) FROM books;
SELECT count(*) FROM authors;
```

## Update your application

After migrating your database schema and data to Neon, you must update your application code to connect to Neon and execute queries using a Postgres driver instead of the Turso SQLite client.

### Connection changes

First, replace your Turso database client (such as `@tursodatabase/serverless` or `@libsql/client`) with a Postgres-compatible driver. For serverless or edge environments, Neon's [serverless driver](https://neon.com/docs/serverless/serverless-driver) is a great choice.

**@tursodatabase/serverless**

```bash
npm uninstall @tursodatabase/serverless
npm install @neondatabase/serverless # or npm install pg
```

**@libsql/client**

```bash
npm uninstall @libsql/client
npm install @neondatabase/serverless # or npm install pg
```

Next, update your environment variables with your Neon connection string retrieved from the Neon Console:

```text
DATABASE_URL="postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require"
```

Then, update your database connection initialization.

**Before (Turso):**

**@tursodatabase/serverless**

```javascript
import { connect } from "@tursodatabase/serverless";

const db = connect({
  url: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN,
});
```

**@libsql/client**

```javascript
import { createClient } from "@libsql/client";

const db = createClient({...config});
```

**After (Neon):**

**Neon serverless driver**

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

**node-postgres**

```javascript
import { Pool } from 'pg';
const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  ssl: true,
});
```

### Query translation

When converting your Turso queries to run against Postgres, you must adapt how statements are prepared and executed.

You need to transition from SQLite's parameter binding (often using `?` placeholders) and driver-specific methods (`.run()`, `.all()`, `.get()`) to standard Postgres driver syntax. For example, with the Neon serverless driver, you can use tagged template literals for queries, while with `node-postgres`, you use parameterized queries with `$1`, `$2`, etc.

**Before (Turso):**

**@tursodatabase/serverless**

```javascript
// Inserting data
const insertUser = db.prepare("INSERT INTO users (username) VALUES (?)");
await insertUser.run("alice");

// Querying data
const stmt = db.prepare("SELECT * FROM users");
const users = await stmt.all();
```

**@libsql/client**

```javascript
// Inserting data
await db.execute({
    sql: "INSERT INTO users (username) VALUES (?)",
    args: ["alice"],
});

// Querying data
const rs = await db.execute("SELECT * FROM users");
const users = rs.rows;
```

**After (Neon):**

**Neon serverless driver**

```javascript
// Inserting data
await sql`INSERT INTO users (username) VALUES (${'alice'})`;

// Querying data
const users = await sql`SELECT * FROM users`;
```

**node-postgres**

```javascript
// Inserting data
await pool.query('INSERT INTO users (username) VALUES ($1)', ['alice']);

// Querying data
const { rows: users } = await pool.query('SELECT * FROM users');
```

### SQL dialect differences

Turso (SQLite) and Postgres use different SQL dialects. Here are the key differences you'll need to address when converting your application queries.

#### Boolean handling

SQLite has no native boolean type -- it stores `true`/`false` as integers `1`/`0`. Postgres has a dedicated `BOOLEAN` type with `true`/`false` values.

**Before (Turso/SQLite):**

```sql
SELECT * FROM users WHERE active = 1;
INSERT INTO users (username, active) VALUES ('alice', 1);
```

**After (Neon/Postgres):**

```sql
SELECT * FROM users WHERE active = true;
INSERT INTO users (username, active) VALUES ('alice', true);
```

#### Case-insensitive string matching

SQLite's `LIKE` operator is case-insensitive for ASCII characters by default. Postgres's `LIKE` is case-sensitive; use `ILIKE` for case-insensitive matching, or `LOWER()` for comparisons.

**Before (Turso/SQLite):**

```sql
SELECT * FROM users WHERE username LIKE '%alice%';
```

**After (Neon/Postgres):**

```sql
SELECT * FROM users WHERE username ILIKE '%alice%';
```

Alternatively, normalize both sides:

```sql
SELECT * FROM users WHERE LOWER(username) LIKE LOWER('%alice%');
```

#### Date and time functions

SQLite and Postgres use different built-in functions for date and time operations.

**Before (Turso/SQLite):**

```sql
-- Current timestamp
INSERT INTO logs (message, created_at) VALUES ('startup', datetime('now'));

-- Formatting a timestamp
SELECT strftime('%Y-%m-%d', created_at) FROM logs;
```

**After (Neon/Postgres):**

```sql
-- Current timestamp
INSERT INTO logs (message, created_at) VALUES ('startup', NOW());

-- Formatting a timestamp
SELECT to_char(created_at, 'YYYY-MM-DD') FROM logs;
```

| Operation                     | SQLite                    | Postgres                       |
| :---------------------------- | :------------------------ | :----------------------------- |
| Current timestamp             | `datetime('now')`         | `NOW()` or `CURRENT_TIMESTAMP` |
| Current date                  | `date('now')`             | `CURRENT_DATE`                 |
| Format timestamp              | `strftime(format, ts)`    | `to_char(ts, format)`          |
| Date arithmetic (add 7 days)  | `datetime(ts, '+7 days')` | `ts + INTERVAL '7 days'`       |
| Extract part of a date (year) | `strftime('%Y', ts)`      | `EXTRACT(YEAR FROM ts)`        |

## Troubleshooting

### SSL verify error with Docker

If you run `pgloader` from a Docker container and encounter an `SSL verify error: 20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, you may need to disable SSL certificate verification.

Modify your load file to set `sslmode=allow` in the Postgres connection string.

```sql
LOAD DATABASE
    FROM sqlite:///data/turso_export.db
    INTO postgresql://.../dbname?sslmode=allow;
...
```

Then, run the Docker command with the `--no-ssl-cert-verification` flag. Mount your database and load files into the container's `/data` directory.

```shell
docker run --rm -v /path/to/your/files:/data \
  dimitri/pgloader:latest \
  pgloader --no-ssl-cert-verification /data/turso.load
```

## References

- [pgloader Documentation](https://pgloader.readthedocs.io/en/latest/)
- [pgloader Reference: SQLite to Postgres](https://pgloader.readthedocs.io/en/latest/ref/sqlite.html)
- [Migrating data to Neon](https://neon.com/docs/import/migrate-intro)

--- [Document source](https://neon.com/docs/import/migrate-intro.md) ---

> Summary: Neon migration guide selection page compares transfer methods (Import Data Assistant, pg_dump/restore, pgcopydb, Logical Replication, pgloader, AWS DMS) by database size, downtime tolerance, and skill level to help you pick the right approach. Import Data Assistant is automated and targets databases under 10 GB. Logical Replication delivers near-zero downtime for production Postgres workloads. pgloader covers non-Postgres sources including MySQL, MSSQL, and SQLite. Also indexes provider-specific migration paths for Heroku, Supabase, PlanetScale, RDS, Cloud SQL, and Azure, plus guidance for region migration and Neon-to-Neon moves.

# Neon data migration guides

Learn how to migrate data to Lakebase Postgres from different database providers and sources

Last updated: 2026-10-21

This guide helps you choose the best migration method based on your database size, downtime tolerance, source database type, and technical requirements.

## Migration methods

| Method                                                                          | Best For                               | Database Size | Downtime                | Technical Skill | Key Benefit                   |
| ------------------------------------------------------------------------------- | -------------------------------------- | ------------- | ----------------------- | --------------- | ----------------------------- |
| [Import Data Assistant](https://neon.com/docs/import/import-data-assistant)     | Quick Postgres migrations              | Under 10GB    | Minimal (minutes–hours) | Low             | Easiest - fully automated     |
| [pg\_dump/restore](https://neon.com/docs/import/migrate-from-postgres)          | Standard Postgres migrations           | Any size      | Required                | Medium          | Reliable and well-tested      |
| [pgcopydb](https://neon.com/docs/import/pgcopydb)                               | Large Postgres databases               | 10GB+         | Required                | Medium          | Parallel processing - fast    |
| [Logical Replication](https://neon.com/docs/guides/logical-replication-guide)   | Production Postgres workloads          | Any size      | Near-zero               | High            | Minimal downtime              |
| [pgloader](https://neon.com/docs/import/migrate-intro#provider-specific-guides) | Non-Postgres sources                   | Any size      | Required                | Medium          | Handles MySQL, MSSQL, SQLite  |
| [AWS DMS](https://neon.com/docs/import/migrate-aws-dms)                         | Multi-source or custom transformations | Any size      | Minimal (minutes–hours) | High            | Advanced transformation rules |

**Tip: Quick guidance**

If you can't afford downtime, use [Logical Replication](https://neon.com/docs/guides/logical-replication-guide). For Postgres databases under 10GB with some downtime flexibility, [Import Data Assistant](https://neon.com/docs/import/import-data-assistant) is the easiest option. For larger Postgres databases where downtime is acceptable, choose between [pg_dump/restore](https://neon.com/docs/import/migrate-from-postgres) (simplest) or [pgcopydb](https://neon.com/docs/import/pgcopydb) (fastest).

## Region migration

If you need your Neon **database** in a different **region**, or a **Postgres-compatible export** from Neon, start with **[Region migration](https://neon.com/docs/import/region-migration)** for paths and tradeoffs. For **Neon-to-Neon** moves, use **[Migrate to another Neon region](https://neon.com/docs/import/migrate-neon-to-another-region)**. A project stays in one region; you create a **new** Neon project in the target region and migrate your **data**, or export. For a **piped** `pg_dump | pg_restore` between Neon projects, see **[Migrate data from another Neon project](https://neon.com/docs/import/migrate-from-neon)**.

## Provider-specific guides

For step-by-step instructions tailored to specific databases or providers, see [MySQL](https://neon.com/docs/import/migrate-mysql), [MSSQL](https://neon.com/docs/import/migrate-mssql), [SQLite](https://neon.com/docs/import/migrate-sqlite), [Heroku](https://neon.com/docs/import/migrate-from-heroku), [Supabase](https://neon.com/docs/import/migrate-from-supabase), [PlanetScale](https://neon.com/docs/import/migrate-from-planetscale), [Turso](https://neon.com/docs/import/migrate-from-turso), [Render](https://neon.com/docs/import/migrate-from-render), [Azure](https://neon.com/docs/import/migrate-from-azure-postgres), [Digital Ocean](https://neon.com/docs/import/migrate-from-digital-ocean), [Railway](https://neon.com/docs/import/migrate-from-railway), [Firebase](https://neon.com/docs/import/migrate-from-firebase), or [another Neon project](https://neon.com/docs/import/migrate-from-neon).

## Logical replication guides

For near-zero downtime Postgres database migrations using logical replication, see guides for [AWS RDS](https://neon.com/docs/guides/logical-replication-rds-to-neon), [Google Cloud SQL](https://neon.com/docs/guides/logical-replication-cloud-sql), [AlloyDB](https://neon.com/docs/guides/logical-replication-alloydb), [Azure](https://neon.com/docs/import/migrate-from-azure-postgres), [Supabase](https://neon.com/docs/guides/logical-replication-supabase-to-neon), [PostgreSQL](https://neon.com/docs/guides/logical-replication-postgres-to-neon), [Lakebase Postgres on Databricks](https://neon.com/docs/guides/logical-replication-lakebase-to-neon), or [Neon to Neon](https://neon.com/docs/guides/logical-replication-neon-to-neon).

## Other imports

- [Import data from CSV](https://neon.com/docs/import/import-from-csv): Import data from CSV files using psql
- [Import sample data](https://neon.com/docs/import/import-sample-data): Try Neon with sample datasets
- [Migrate schema only](https://neon.com/docs/import/migrate-schema-only): Migrate just the schema without data

--- [Document source](https://neon.com/docs/import/migrate-mssql.md) ---

> Summary: Migrating from Microsoft SQL Server (MSSQL) or Azure SQL to Lakebase Postgres uses pgloader, which streams data through the Postgres COPY protocol and automatically detects schemas, indexes, and constraints. Use this page when you need end-to-end steps covering credentials, firewall rules, pgloader configuration, running the migration, and post-migration verification. Neon's Free plan supports up to 1 GB; larger datasets require a paid plan. Azure SQL users may need FreeTDS driver configuration to resolve pgloader connection errors.

# Migrate from Microsoft SQL Server to Lakebase Postgres

Learn how to migrate a Microsoft SQL Server database to Lakebase Postgres using pgloader

Last updated: 2026-10-28

This guide describes how to migrate your database from a Microsoft SQL Server (MSSQL) database to Lakebase Postgres using [pgloader](https://pgloader.readthedocs.io/en/latest/intro.html).

The `pgloader` utility transforms data to a Postgres-compatible format as it reads from your MSSQL database. It uses the Postgres `COPY` protocol to stream the data into your Postgres database.

## Prerequisites

- An MSSQL instance containing the data you want to migrate.

  For this guide, we use `Azure SQL`, which is a managed cloud-based offering of Microsoft SQL server. We set up an Azure SQL Database and populate it with the [Northwind sample dataset](https://github.com/microsoft/sql-server-samples/tree/master/samples/databases/northwind-pubs). This dataset contains sales data corresponding to a fictional company that imports and exports food products, organized across multiple tables.

- A Neon project to move the data to.

  For detailed information on creating a Neon project, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

- Neon's Free plan supports 1 GB of data. If your data size is more than 1 GB, you'll need to upgrade to one of Neon's paid plans. See [Neon plans](https://neon.com/docs/introduction/plans) for more information.

- Review the [Pgloader MSSQL to Postgres Guide](https://pgloader.readthedocs.io/en/latest/ref/mssql.html) guide. It will provide you with a good understanding of `pgloader` capabilities and how to configure your `pgloader` configuration file, if necessary.

- See [Pgloader configuration](https://neon.com/docs/import/migrate-mssql#pgloader-configuration) for a `pgloader` configuration file update that may be required to connect to MSSQL from `pgloader`.

## Prepare your MSSQL database

### Retrieve Your MSSQL database credentials

Before starting the migration process, collect your MSSQL database credentials. If you are using Azure SQL, you can use the following steps to retrieve them:

1. Log into the Azure portal and navigate to your Azure SQL Database resource.
2. Navigate to the **Connection strings** tab under the `Settings` section and identify the connection string for your database. Make note of the following details:
   - Server
   - Database
   - User
   - Password (Not displayed in the Azure portal)

Keep the database connection details handy for later use.

### Allow inbound traffic from Neon

If you are using Azure SQL, you need to allow inbound traffic from your local machine, so `pgloader` can connect to your database. To do this, follow these steps:

1. Log into the Azure portal and navigate to your Azure SQL Server resource.

2. Click on the **Networking** option under the `Settings` section in the sidebar. Navigate to the **Firewall Rules** section under the `Public access` tab.

3. Click on the `Add your Client IPv4 address` option, which will automatically create a new rule with the IP address of your local machine. If you are running `pgloader` elsewhere, replace both the `Start IP` and `End IP` fields with the IP address of that machine.

4. Click `Save` at the bottom to make sure all changes are saved.

## Prepare your Neon destination database

This section describes how to prepare your destination database to receive the migrated data.

### Create the Neon database

To maintain parity with the MSSQL deployment, you might want to create a new database in Neon with the same name. Refer to the [Create a database](https://neon.com/docs/manage/databases#create-a-database) guide for more information.

For this example, we will create a new database named `Northwind` in the Neon project. Use `psql` to connect to your Neon project (alternatively, you can use the `Query editor` in the Neon console) and run the following query:

```sql
CREATE DATABASE "Northwind";
```

### Retrieve your Neon database connection string

Log in to the Neon Console. Find the connection string for your database by clicking the **Connect** button in the Console nav. It should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Now, modify the connection string as follows to pass your **endpoint ID** (`ep-cool-darkness-123456` in this example) to Neon with your password using the `endpoint` keyword, as shown here:

```bash
postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

**Note:** Passing the `endpoint ID` with your password is a required workaround for some Postgres drivers, including the one used by `pgloader`. For more information about this workaround and why it's required, refer to our [connection workaround](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field) documentation.

Keep your Neon connection string handy for later use.

## Install pgloader

Here's how you can set up `pgloader` for your database migration:

1. Install the `pgloader` utility using your preferred installation method. Debian (apt), RPM package, and Docker methods are supported, as well as Homebrew for macOS (`brew install pgloader`). If your macOS has an ARM processor, use the Homebrew installation method.

   See [Installing pgloader](https://pgloader.readthedocs.io/en/latest/install.html) for Debian (apt), RPM package, and Docker installation instructions.

2. Create a `pgloader` configuration file (for example, `mssql_to_neon.load`). Use your MSSQL database credentials to define the connection string for your database source. Use the Neon database connection string as the destination.

   Example configuration in `mssql_to_neon.load`:

   ```plaintext
   LOAD DATABASE
        FROM mssql://migration_user:password@host:port/AdventureWorks
        INTO postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   ```

   Make sure to replace the connection string values with your own MSSQL and Neon credentials.

## Run the migration with pgloader

To initiate the migration process, run:

```shell
pgloader mssql_to_neon.load
```

The command output will show the progress of the migration, including any errors encountered and the total time taken. For our sample dataset, the output looks similar to this:

```plaintext
2024-09-12T10:46:54.307953Z LOG report summary reset
              table name     errors       read   imported      bytes      total time       read      write
------------------------  ---------  ---------  ---------  ---------  --------------  ---------  ---------
         fetch meta data          0         65         65                     0.280s
          Create Schemas          0          0          0                     0.116s
        Create SQL Types          0          0          0                     0.232s
           Create tables          0         26         26                     9.120s
          Set Table OIDs          0         13         13                     0.120s
------------------------  ---------  ---------  ---------  ---------  --------------  ---------  ---------
dbo.customercustomerdemo          0          0          0                     1.300s     0.124s
          dbo.categories          0          8          8    64.4 kB          1.224s     0.144s     0.004s
           dbo.customers          0         91         91    11.3 kB          2.520s     0.140s
dbo.customerdemographics          0          0          0                     2.152s     0.088s
           dbo.employees          0          9          9    76.0 kB          3.088s     0.136s     0.004s
 dbo.employeeterritories          0         49         49     0.4 kB          3.112s     0.096s
              dbo.orders          0        830        830   118.5 kB          3.656s     1.380s     0.060s
     dbo."Order Details"          0       2155       2155    44.0 kB          3.268s     1.372s     0.008s
              dbo.region          0          4          4     0.2 kB          2.832s     0.132s
            dbo.products          0         77         77     4.2 kB          2.660s     0.132s
           dbo.suppliers          0         29         29     3.9 kB          3.508s     0.120s
            dbo.shippers          0          3          3     0.1 kB          2.892s     0.104s
         dbo.territories          0         53         53     3.1 kB          3.568s     0.108s
------------------------  ---------  ---------  ---------  ---------  --------------  ---------  ---------
 COPY Threads Completion          0          4          4                     5.576s
          Create Indexes          0         39         39                    14.252s
  Index Build Completion          0         39         39                     3.072s
         Reset Sequences          0          6          6                     1.500s
            Primary Keys          0         13         13                     5.024s
     Create Foreign Keys          0         13         13                     5.016s
         Create Triggers          0          0          0                     0.256s
        Install Comments          0          0          0                     0.000s
------------------------  ---------  ---------  ---------  ---------  --------------  ---------  ---------
       Total import time          ✓       3308       3308   326.0 kB         34.696s
2024-09-12T10:46:54.339953Z INFO Stopping monitor
```

## Verify the migration

After the migration is complete, connect to your Neon database and run some queries to verify that the data has been transferred correctly. For example:

```sql
SELECT productname, unitprice, unitsinstock
FROM dbo.products
WHERE discontinued = false
ORDER BY unitprice DESC
LIMIT 5;
```

This query returns the following result:

```plaintext
      productname       | unitprice | unitsinstock
------------------------+-----------+--------------
 Côte de Blaye          |     263.5 |           17
 Sir Rodney's Marmalade |      81.0 |           40
 Carnarvon Tigers       |      62.5 |           42
 Raclette Courdavault   |      55.0 |           79
 Manjimup Dried Apples  |      53.0 |           20
(5 rows)
```

Compare the results with the same queries run on your MSSQL database to ensure data integrity.

## Clean up

After successfully migrating and verifying your data on Neon:

1. Consider backing up your MSSQL database before decommissioning it.

2. Update your application code to make SQL queries using the Postgres dialect.

3. Update your application's connection strings to point to your new Neon database.

## Other migration options

While this guide focuses on using `pgloader`, you might need more manual adjustments to ensure:

- There are no unintended changes to the application behavior. For example, all MSSQL data types don't translate one-to-one to Postgres data types.
- The application code is compatible with Lakebase Postgres.

For complex migrations or when you need more control over the migration process, you might consider developing a custom Extract, Transform, Load (ETL) process using tools like Python with SQLAlchemy.

## Pgloader configuration

- `Pgloader` automatically detects table schemas, indexes, and constraints, but depending on the input table schemas, you might need to specify manual overrides in the configuration file. Refer to the [Command clauses](https://pgloader.readthedocs.io/en/latest/command.html#common-clauses) section of the `pgloader` documentation for more information.

- With Azure SQL database, `pgloader` often runs into connection errors. To solve them, you might need to manually specify the FreeTDS driver configuration (which `pgloader` uses to connect to MSSQL). Please refer to the related issues in the [PGLoader GitHub repository](https://github.com/dimitri/pgloader/) for more information.

  Below is the section required to make `pgloader` work, at the time of writing. Replace the values with your own Azure SQL database credentials.

  ```plaintext
  # /etc/freetds/freetds.conf

  ...

  [host-name]
  tds version = 7.4
  client charset = UTF-8
  encrypt = require
  host = ...
  port = 1433
  database = ...
  ```

## Reference

For more information on `pgloader` and database migration, refer to the following resources:

- [pgloader documentation - MSSQL to Postgres](https://pgloader.readthedocs.io/en/latest/ref/mssql.html)
- [Neon documentation](https://neon.com/docs)

--- [Document source](https://neon.com/docs/import/migrate-mysql.md) ---

> Summary: MySQL to Lakebase Postgres migration uses pgloader, which reads from a MySQL source and streams data into Postgres via the COPY protocol, automatically transforming data types. Use this page when moving an existing MySQL database to Neon. It covers credentials, connection string setup including the required endpoint ID workaround, and running pgloader from the command line or Docker. Neon's Free plan supports up to 1 GB; larger databases require a paid plan.

# Migrate from MySQL to Lakebase Postgres

Last updated: 2026-09-29

This topic describes how to migrate your MySQL database to Lakebase Postgres using [pgloader](https://pgloader.readthedocs.io/en/latest/intro.html).

The `pgloader` utility transforms data to a Postgres-compatible format as it is read from your MySQL database. It uses the `COPY` Postgres protocol to stream the data into your Postgres database.

## Prerequisites

Before you begin, make sure that you have the following:

- A Neon account and a project. See [Sign up](https://neon.com/docs/get-started/signing-up).
- A properly named database. For example, if you are migrating a database named `sakila`, you might want to create a database of the same name in Neon. See [Create a database](https://neon.com/docs/manage/databases#create-a-database) for instructions.
- Neon's Free plan supports 1 GB of data. If your data size is more than 1 GB, you'll need to upgrade to one of Neon's paid plans. See [Neon plans](https://neon.com/docs/introduction/plans) for more information.

Also, a close review of the [Pgloader MySQL to Postgres Guide](https://pgloader.readthedocs.io/en/latest/ref/mysql.html) guide is recommended before you start. This guide will provide you with a good understanding of `pgloader` capabilities and how to configure your `pgloader` configuration file, if necessary.

## Retrieve Your MySQL database credentials

Before starting the migration process, collect your MySQL database credentials:

1. Log into your MySQL database provider.
2. Identify and record the following details or grab your MySQL database connection string.
   - Hostname or IP address
   - Database name
   - Username
   - Password

Keep your MySQL database connection details handy for later use.

## Retrieve your Neon database connection string

Log in to the [Neon Console](https://console.neon.tech). Find the connection string for your database by clicking the **Connect** button in the Console nav. Make sure the **Connection pooling** toggle is disabled to get a direct connection string.

Your connection string should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Now, modify the connection string as follows to pass your **endpoint ID** (`ep-cool-darkness-123456` in this example) to Neon with your password using the `endpoint` keyword, as shown here:

```bash
postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

**Note:** Passing the `endpoint ID` with your password is a required workaround for some Postgres drivers, including the one used by `pgloader`. For more information about this workaround and why it's required, refer to our [connection workaround](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field) documentation.

Keep your Neon connection string handy for later use.

### Install pgloader

Here's how you can set up `pgloader` for your database migration:

1. Install the `pgloader` utility using your preferred installation method. Debian (apt), RPM package, and Docker methods are supported, as well as Homebrew for macOS (`brew install pgloader`). If your macOS has an ARM processor, use the Homebrew installation method.

   See [Installing pgloader](https://pgloader.readthedocs.io/en/latest/install.html) for Debian (apt), RPM package, and Docker installation instructions.

2. Create a `pgloader` configuration file (for example, `config.load`). Use your MySQL database credentials to define the connection string for your database source. Use the Neon database connection string you retrieved and modified in the previous step as the destination.

   **Note:** If you need to specify an SSL mode in your connection string, the following format is recommended: `sslmode=require`. Other formats may not work.

   Example configuration in `config.load`:

   ```plaintext
   load database
    from mysql://user:password@host/source_db?sslmode=require
    into postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require;
   ```

## Run the migration with pgloader

To initiate the migration process, run:

```shell
pgloader config.load
```

The command output will look similar to this:

```bash
LOG report summary reset
             table name     errors       rows      bytes      total time
-----------------------  ---------  ---------  ---------  --------------
        fetch meta data          0          2                     0.727s
         Create Schemas          0          0                     0.346s
       Create SQL Types          0          0                     0.178s
          Create tables          0          2                     0.551s
         Set Table OIDs          0          1                     0.094s
-----------------------  ---------  ---------  ---------  --------------
    "db-test".dbname             0          1     0.0 kB          0.900s
-----------------------  ---------  ---------  ---------  --------------
COPY Threads Completion          0          4                     0.905s
 Index Build Completion          0          1                     0.960s
         Create Indexes          0          1                     0.257s
        Reset Sequences          0          0                     1.083s
           Primary Keys          0          1                     0.263s
    Create Foreign Keys          0          0                     0.000s
        Create Triggers          0          0                     0.169s
        Set Search Path          0          1                     0.427s
       Install Comments          0          0                     0.000s
-----------------------  ---------  ---------  ---------  --------------
      Total import time          ✓          1     0.0 kB          4.064s
```

## SSL verify error

If you encounter an `SSL verify error: 20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY` error while attempting the instructions described above using `pgloader` from a Docker container, try the solution identified in this [GitHub issue](https://github.com/dimitri/pgloader/issues/768#issuecomment-693390290), which involves specifying `sslmode=allow` in the Postgres connection string and using the `--no-ssl-cert-verification` option with `pgloader`.

The following configuration file and Docker command were verified to work with Docker on Windows but may apply generally when using `pgloader` in a Docker container. In your `pgloader` config file, replace the MySQL and Postgres connection string values with your own. In the Docker command, specify the path to your `pgloader` config file, and replace the container ID value (the long alphanumeric string) with your own.

`pgloader` config.load file:

```plaintext
load database
  from mysql://user:password@host/source_db?sslmode=require&channel_binding=require
  into postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=allow;
```

Docker command:

```plaintext
docker run -v C:\path\to\config.load:/config.load d183dc100d3af5e703bd867b3b7826c117fa16b7ee2cd360af591dc895b121dc pgloader --no-ssl-cert-verification /config.load
```

## References

- [Installing pgloader](https://pgloader.readthedocs.io/en/latest/install.html)
- [Pgloader Tutorial: Migrating from MySQL to PostgreSQL](https://pgloader.readthedocs.io/en/latest/tutorial/tutorial.html#migrating-from-mysql-to-postgresql)
- [Pgloader MySQL to Postgres Guide](https://pgloader.readthedocs.io/en/latest/ref/mysql.html)
- [How to Migrate from MySQL to PostgreSQL RDBMS: An Enterprise Approach](https://jfrog.com/community/data-science/how-to-migrate-from-mysql-to-postgresql-rdbms-an-enterprise-approach/)

--- [Document source](https://neon.com/docs/import/migrate-neon-to-another-region.md) ---

> Summary: Neon project regions are fixed, so moving a database to another region requires creating a new Neon project in the target region and migrating the data into it. This page helps you choose a migration method: Import Data Assistant (recommended for databases under 10 GB), pg_dump/pg_restore (for full control over dump files and restore timing), or logical replication (for minimal-downtime cutover on busy databases).

# Migrate to another Neon region

Choose a migration method for a new Neon project in another region

Last updated: 2026-08-07

You can't change the region of an existing Neon project in place. A project's region is fixed when you create it. To move your database to a different region, you **create a new Neon project** in the target region and **migrate** your data into it, then cut over and delete the old project.

## Choose a migration method

Each option below is a different way to move your database into a new Neon project in a different region. Choose the option that matches your requirements.

### Import Data Assistant

**Best for** smaller databases (roughly **under 10 GB**) and when you want a guided flow in the Neon Console.

In the Neon Console, open the **[Projects](https://console.neon.tech/app/)** page and start the **Import Data Assistant**. The assistant **creates your new Neon project** in the **target region** as part of the same flow. You begin by entering the **connection string for the database you are migrating from**. See **[Import Data Assistant](https://neon.com/docs/import/import-data-assistant)** for instructions.

### pg_dump and pg_restore

**Best for** when you want full control of dump files and restore timing. See **[Migrate data from another Neon project](https://neon.com/docs/import/migrate-from-neon)**. Use direct (unpooled) connection strings for both the source and target; avoid running `pg_dump` or `pg_restore` over a pooled connection.

### Logical replication

**Best for minimal downtime** on busy databases where a long dump or restore window is not acceptable.

You replicate from the source project to the target and cut over when caught up. See **[Replicate data from one Neon project to another](https://neon.com/docs/guides/logical-replication-neon-to-neon)**. Expect more configuration than other migration methods.

## Related docs

- [Region migration](https://neon.com/docs/import/region-migration)
- [Get started with logical replication](https://neon.com/docs/guides/logical-replication-guide)

--- [Document source](https://neon.com/docs/import/migrate-schema-only.md) ---

> Summary: Schema-only migration with `pg_dump --schema-only` and `psql` copies table definitions, indexes, and constraints to Neon without transferring row data. This is required before starting logical replication so source and destination schemas match. Use this page when copying a schema from AlloyDB, RDS, or another Postgres provider and needing to strip provider-specific settings or defer index creation. Requires an unpooled Neon connection string; pooled connections are not supported for `pg_dump`.

# Migrate a database schema

Perform a schema-only migration with pg_dump and pg_restore

Last updated: 2026-09-16

This topic shows how to perform a schema-only migration using the `pg_dump` and `pg_restore` Postgres utilities.

A schema-only migration may be necessary in certain scenarios. For example, when replicating data between two Postgres instances, the tables defined in your publication on the source database must also exist in the destination database, and they must have the same table names and columns. A schema dump and reload in this case may be faster than trying to manually create the required schema on the destination database.

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

## Dump the schema

To dump only the schema from a database, you can run a `pg_dump` command similar to the following to create an `.sql` dump file with the schema only:

```sql
pg_dump --schema-only \
	--no-privileges \
	"postgresql://role:password@hostname:5432/dbname" \
	> schema_dump.sql
```

- With the `--schema-only` option, only object definitions are dumped. Data is excluded.
- The `--no-privileges` option prevents dumping privileges. Neon may not support the privileges you've defined elsewhere, or if dumping a schema from Neon, there maybe Neon-specific privileges that cannot be restored to another database.

**Tip:**

- When you're dumping or restoring on Neon, you can input your Neon connection string in place of `postgresql://role:password@hostname:5432/dbname`. You can find the connection string for your database by clicking the **Connect** button in the Console nav.

## Review and modify the dumped schema

After dumping a schema to an `.sql` file, review it for statements that you don't want to replicate or that won't be supported on your destination database, and comment them out. For example, when dumping a schema from AlloyDB, you might see statements like the ones shown below, which you can comment out if you're loading the schema into Neon, where they won't be supported. Generally, you should remove any parameters configured on another Postgres provider and rely on Neon's default Postgres settings.

If you are replicating a large dataset, also consider removing any `CREATE INDEX` statements from the resulting dump file to avoid creating indexes when loading the schema on the destination database (the subscriber). Taking indexes out of the equation can substantially reduce the time required for initial data load performed when starting logical replication. Save the `CREATE INDEX` statements that you remove. You can add the indexes back after the initial data copy is completed.

**Note:** To comment out a single line, you can use `--` at the beginning of the line.

```sql
-- SET statement_timeout = 0;
-- SET lock_timeout = 0;
-- SET idle_in_transaction_session_timeout = 0;
-- SET client_encoding = 'UTF8';
-- SET standard_conforming_strings = on;
-- SELECT pg_catalog.set_config('search_path', '', false);
-- SET check_function_bodies = false;
-- SET xmloption = content;
-- SET client_min_messages = warning;
-- SET row_security = off;

-- ALTER SCHEMA public OWNER TO alloydbsuperuser;

-- CREATE EXTENSION IF NOT EXISTS google_columnar_engine WITH SCHEMA public;

-- CREATE EXTENSION IF NOT EXISTS google_db_advisor WITH SCHEMA public;
```

## Load the schema

After making any necessary modifications, load the dumped schema using `psql`:

```sql
psql \
	"postgresql://role:password@hostname:5432/dbname" \
	< schema_dump.sql
```

After you've loaded the schema, you can view the result with this `psql` command:

```sql
\dt
```

--- [Document source](https://neon.com/docs/import/migrate-sqlite.md) ---

> Summary: SQLite-to-Lakebase Postgres migration using pgloader transfers schemas and data while mapping SQLite type affinities to strict Postgres types. Use this page when moving an existing SQLite or Turso database to Neon and needing control over type casting via pgloader CAST clauses, as distinct from guides covering MySQL, CSV, or logical replication imports. Neon's Free plan supports up to 1 GB; the guide also covers sequence verification after import and a Docker SSL workaround.

# Migrate from SQLite to Lakebase Postgres

Last updated: 2026-09-29

This guide describes how to migrate your SQLite database to Lakebase Postgres using [pgloader](https://pgloader.readthedocs.io/en/latest/intro.html)

`pgloader` is an open-source data loading and migration tool that efficiently transfers data from various sources (like CSV, MySQL, SQLite, MS SQL, etc.) into Postgres, handling schema and data transformations on the fly. We'll use it to migrate a sample SQLite database to Lakebase Postgres

## Prerequisites

Before you begin, ensure you have the following:

- A Neon account and a project. If you don't have one, see [Sign up](https://neon.com/docs/get-started/signing-up).
- A database created in your Neon project. For instructions, see [Create a database](https://neon.com/docs/manage/databases#create-a-database).
- The file path to your source SQLite database file. If you don't have one, you can create a sample database in the next step.
- Neon's Free plan supports 1 GB of data. If your data size is more than 1 GB, you'll need to upgrade to one of Neon's paid plans. See [Neon plans](https://neon.com/docs/introduction/plans) for more information.

A review of the [pgloader SQLite to Postgres Guide](https://pgloader.readthedocs.io/en/latest/ref/sqlite.html) is also recommended. It provides a comprehensive overview of `pgloader`'s capabilities.

## Understanding SQLite and Postgres data types

Before migrating from SQLite to Postgres, it's helpful to understand a key difference in how they handle data types:

- **SQLite** uses a flexible typing system called "type affinity". You can store any type of data in any column, regardless of its declared type. For example, you can store the text "hello" in a column declared as `INTEGER`. The declared type is only a suggestion.
- **Postgres** uses a strict, static typing system. Data inserted into a column must precisely match the column's declared data type. An attempt to store "hello" in an `INTEGER` column will result in an error.

When converting a database, SQLite's type affinities are mapped to appropriate Postgres types. Here is a summary of the common mappings:

| Data Type Category              | SQLite                                | PostgreSQL                                                                          | Key Differences & Notes                                                                                                                                                                                                                                                                                                   |
| :------------------------------ | :------------------------------------ | :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Integer**                     | `INTEGER`                             | `SMALLINT` (2 bytes)<br/>`INTEGER` (4 bytes)<br/>`BIGINT` (8 bytes)                 | SQLite's `INTEGER` is a flexible-size signed integer, storing values in 1, 2, 3, 4, 6, or 8 bytes depending on the magnitude of the value. PostgreSQL offers fixed-size integers for more granular control over storage and performance.                                                                                  |
| **Auto-incrementing Integer**   | `INTEGER PRIMARY KEY`                 | `SMALLSERIAL` (2 bytes)<br/>`SERIAL` (4 bytes)<br/>`BIGSERIAL` (8 bytes)            | In SQLite, declaring a column as `INTEGER PRIMARY KEY` automatically makes it an alias for the `rowid` and thus auto-incrementing. PostgreSQL provides the `SERIAL` pseudo-types, which create a sequence object to generate unique identifiers.                                                                          |
| **Floating-Point**              | `REAL`                                | `REAL` (4 bytes)<br/>`DOUBLE PRECISION` (8 bytes)                                   | SQLite's `REAL` is an 8-byte IEEE floating-point number. PostgreSQL offers both single-precision (`REAL`) and double-precision (`DOUBLE PRECISION`) floating-point numbers.                                                                                                                                               |
| **Arbitrary Precision Numeric** | `NUMERIC`                             | `NUMERIC(precision, scale)`<br/>`DECIMAL(precision, scale)`                         | SQLite's `NUMERIC` affinity will attempt to store data as `INTEGER` or `REAL`, or as `TEXT` if it cannot be losslessly converted. PostgreSQL's `NUMERIC` and `DECIMAL` types are for exact decimal arithmetic, crucial for financial and scientific applications, allowing for user-defined precision and scale.          |
| **String**                      | `TEXT`<br/>`VARCHAR(n)`<br/>`CHAR(n)` | `TEXT`<br/>`VARCHAR(n)`<br/>`CHAR(n)`                                               | While both databases accept these type names, in SQLite, they all have a `TEXT` affinity. The length `(n)` is not enforced in SQLite. In PostgreSQL, `VARCHAR(n)` enforces a maximum length, and `CHAR(n)` is a fixed-length, blank-padded string. `TEXT` in PostgreSQL has no predefined length limit.                   |
| **Binary Data**                 | `BLOB`                                | `BYTEA`                                                                             | Both are used for storing raw binary data.                                                                                                                                                                                                                                                                                |
| **Date & Time**                 | `TEXT`<br/>`REAL`<br/>`INTEGER`       | `DATE`<br/>`TIME`<br/>`TIMESTAMP`<br/>`TIMESTAMPTZ` (with time zone)<br/>`INTERVAL` | SQLite has no dedicated date/time storage class; they are typically stored as `TEXT` (ISO-8601 strings), `REAL` (Julian day numbers), or `INTEGER` (Unix timestamps). PostgreSQL provides a rich set of specific date and time types with built-in functions for complex date and time arithmetic and time zone handling. |
| **Boolean**                     | `INTEGER` (0 for false, 1 for true)   | `BOOLEAN`                                                                           | SQLite does not have a native boolean type and commonly uses `INTEGER` with values 0 and 1. PostgreSQL has a dedicated `BOOLEAN` type that stores `true` or `false`.                                                                                                                                                      |
| **JSON**                        | `TEXT`                                | `JSON`<br/>`JSONB`                                                                  | In SQLite, JSON data is stored as `TEXT`. PostgreSQL offers two dedicated JSON types: `JSON` for storing the raw JSON text and `JSONB` for a decomposed binary format that is more efficient for indexing and querying.                                                                                                   |
| **Unique Identifier**           | -                                     | `UUID`                                                                              | PostgreSQL has a dedicated `UUID` data type for storing Universally Unique Identifiers, which is not present in SQLite.                                                                                                                                                                                                   |
| **Array**                       | -                                     | `data_type[]`                                                                       | PostgreSQL supports arrays of any built-in or user-defined data type, a powerful feature for storing lists of values in a single column. SQLite does not have a native array type.                                                                                                                                        |

## Create a sample SQLite database (Optional)

If you don't have a database to migrate, you can create a sample database for this tutorial. This requires the `sqlite3` command-line tool, typically pre-installed on macOS and Linux.

1. Create a file named `seed.sql`. This schema defines `authors` and `books` tables, including a `published_date` column stored as `TEXT` to demonstrate type casting.

   ```sql title="seed.sql"
   -- Create the authors table
   CREATE TABLE authors (
       id INTEGER PRIMARY KEY,
       name TEXT NOT NULL,
       bio TEXT
   );

   -- Create the books table
   CREATE TABLE books (
       id INTEGER PRIMARY KEY,
       author_id INTEGER NOT NULL,
       title TEXT NOT NULL,
       published_date TEXT,
       rating REAL,
       FOREIGN KEY (author_id) REFERENCES authors (id)
   );

   -- Insert sample data
   INSERT INTO authors (id, name, bio) VALUES
   (1, 'George Orwell', 'Author of dystopian classics.'),
   (2, 'J.R.R. Tolkien', 'Author of high-fantasy epics.'),
   (3, 'Jane Austen', 'Renowned for her romantic fiction.');

   INSERT INTO books (author_id, title, published_date, rating) VALUES
   (1, '1984', '1949-06-08', 4.8),
   (1, 'Animal Farm', '1945-08-17', 4.5),
   (2, 'The Hobbit', '1937-09-21', 4.9),
   (2, 'The Lord of the Rings', '1954-07-29', 5.0),
   (3, 'Pride and Prejudice', '1813-01-28', 4.7);
   ```

2. Create the SQLite database `sample_library.db` from the schema file:

   ```shell
   sqlite3 sample_library.db < seed.sql
   ```

You now have a `sample_library.db` file ready for migration.

**Note: Using Turso?**

If you're using Turso, you can dump your database to a SQL file using the [Turso CLI](https://docs.turso.tech/cli/introduction) and then follow the rest of this guide:

```shell
turso db shell <database-name> .dump > seed.sql

# Generate a SQLite database file from the SQL dump
sqlite3 sample_library.db < seed.sql
```

For more details on database dumps, see the [Turso CLI documentation](https://docs.turso.tech/cli/db/shell#database-dump).

Now that you have your Neon database and SQLite database ready, you can use `pgloader` to migrate the data. Follow these steps:

## Retrieve your Neon database connection string

Log in to the [Neon Console](https://console.neon.tech). Find the connection string for your database by clicking the **Connect** button in the Console nav. Make sure the **Connection pooling** toggle is disabled:

![Connection details modal with connection pooling disabled](https://neon.com/docs/connect/connection_details_without_connection_pooling.png)

Your connection string should look similar to this:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require
```

**Important:** You will need to remove `&channel_binding=require` from the connection string, as `pgloader` does not support channel binding and throws an error when it is present.

Now, modify this connection string to pass your **endpoint ID** (`ep-cool-darkness-123456` in this example) to Neon with your password using the `endpoint` keyword, as shown here:

```bash
postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require
```

**Note:** Passing the `endpoint ID` with your password is a required workaround for some Postgres drivers, including the one used by `pgloader`. For more information, see [Connect with an endpoint ID](https://neon.com/docs/connect/connection-errors#d-specify-the-endpoint-id-in-the-password-field).

Keep your modified Neon connection string handy.

## Install pgloader

Install the `pgloader` utility using your preferred method:

- For **macOS** with Homebrew: `brew install pgloader`
- For **Debian/Ubuntu**: `sudo apt-get install pgloader`
- For **Docker**: Pull the latest image with `docker pull dimitri/pgloader:latest`

For other systems, see [Installing pgloader](https://pgloader.readthedocs.io/en/latest/install.html).

## Run a simple migration

For a basic migration, you can run `pgloader` directly from the command line. This command uses `pgloader`'s default settings to migrate the `sample_library.db` schema and data.

```shell
pgloader sqlite://sample_library.db "postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require"
```

> Make sure to enclose the Postgres connection string in quotes to prevent shell interpretation issues.

The command output will look similar to this:

```bash
2025-06-27T08:26:19.941000Z LOG report summary reset
             table name     errors       rows      bytes      total time
-----------------------  ---------  ---------  ---------  --------------
                  fetch          0          0                     0.000s
        fetch meta data          0          5                     0.204s
         Create Schemas          0          0                     0.108s
       Create SQL Types          0          0                     0.222s
          Create tables          0          4                     1.307s
         Set Table OIDs          0          2                     0.121s
-----------------------  ---------  ---------  ---------  --------------
                authors          0          3     0.1 kB          1.082s
                  books          0          5     0.2 kB          0.993s
-----------------------  ---------  ---------  ---------  --------------
COPY Threads Completion          0          4                     1.080s
 Index Build Completion          0          2                     2.342s
         Create Indexes          0          2                     0.662s
        Reset Sequences          0          0                     1.297s
           Primary Keys          0          2                     0.650s
    Create Foreign Keys          0          1                     0.339s
        Create Triggers          0          0                     0.211s
       Install Comments          0          0                     0.000s
-----------------------  ---------  ---------  ---------  --------------
      Total import time          ✓          8     0.3 kB          6.581s
```

This is quick, but it will create primary key columns as `bigint` rather than `serial`, and the `published_date` column will remain `text`. This is expected behavior, as `pgloader` uses SQLite's type affinities directly.

## Advanced migration with custom casting

For fine-grained control, a `pgloader` load file is the best approach. Here, we'll create a load file that uses the `CAST` clause to:

1. Convert `INTEGER PRIMARY KEY` columns to `SERIAL`. This makes the Postgres schema cleaner and more idiomatic.
2. Cast the `TEXT` `published_date` column to the native `DATE` type in Postgres.

Create a file named `sqlite_advanced.load` with the following content. Replace the Neon connection string and file path if necessary.

```sql title="sqlite_advanced.load"
LOAD DATABASE
    FROM sqlite://sample_library.db
    INTO postgresql://alex:endpoint=ep-cool-darkness-123456;AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require

WITH
    include drop,
    create tables,
    create indexes,
    reset sequences,
    downcase identifiers

CAST
    -- Cast specific primary key columns to SERIAL for auto-incrementing
    column authors.id to serial,
    column books.id to serial,

    -- Cast text column to date; pgloader handles ISO 8601 format ('YYYY-MM-DD') automatically
    column books.published_date to date;
```

Now, run the migration using this advanced load file:

```shell
pgloader sqlite_advanced.load
```

The migration will now produce a more refined Postgres schema, with `SERIAL` primary keys and a proper `DATE` column.

## Post-migration verification

After migrating, always verify your data. One critical area is auto-incrementing primary keys.

### Verify sequences

The `reset sequences` option in the load file ensures that auto-incrementing columns start from the correct value. You can verify this manually.

Connect to your Neon database using [`psql`](https://neon.com/docs/connect/query-with-psql-editor) or [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) and check the next value for the `books` table's sequence:

```sql
SELECT nextval(pg_get_serial_sequence('books', 'id'));
```

This should return a value one higher than the max `id` in the `books` table (for example, `6` for our sample data). If it doesn't, you can reset it manually with this command:

```sql
SELECT setval(
    pg_get_serial_sequence('books', 'id'),
    (SELECT MAX(id) FROM books) + 1
);
```

## Troubleshooting

### SSL verify error with Docker

If you run `pgloader` from a Docker container and encounter an `SSL verify error: 20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, you may need to disable SSL certificate verification.

Modify your load file to set `sslmode=allow` in the Postgres connection string.

```sql title="sqlite_advanced.load"
LOAD DATABASE
    FROM sqlite:////data/sample_library.db
    INTO postgresql://.../dbname?sslmode=allow;
...
```

Then, run the Docker command with the `--no-ssl-cert-verification` flag. Mount your database and load files into the container's `/data` directory.

```shell
docker run --rm -v /path/to/your/files:/data
  dimitri/pgloader:latest
  pgloader --no-ssl-cert-verification /data/sqlite_advanced.load
```

## References

- [pgloader Documentation](https://pgloader.readthedocs.io/en/latest/)
- [pgloader Reference: SQLite to Postgres](https://pgloader.readthedocs.io/en/latest/ref/sqlite.html)
- [pgloader CLI Reference](https://pgloader.readthedocs.io/en/latest/pgloader.html)

--- [Document source](https://neon.com/docs/import/pgcopydb.md) ---

> Summary: pgcopydb is an open-source Postgres-to-Postgres migration tool that parallelizes table copying, index creation, and constraint application to reduce downtime for one-time migrations to Neon. Use it when migrating large databases from AWS RDS, GCP Cloud SQL, Azure, or any Postgres source where pg_dump alone is too slow. Note that `pgcopydb clone --follow` (logical replication) is not supported on Neon, and both source and target URIs must use unpooled connection strings.

# Migrate data to Lakebase Postgres using pgcopydb

Streamline your Postgres data migration to Neon using pgcopydb

Last updated: 2026-07-31

**What you will learn**

- Why use pgcopydb
- Setting up environment variables for migration
- Monitoring the migration process
- Advanced usage options

**Repo**

- [pgcopydb GitHub repository](https://github.com/dimitri/pgcopydb)

**Related docs**

- [pgcopydb documentation](https://pgcopydb.readthedocs.io/)

`pgcopydb` is an open-source tool for copying Postgres databases from one server to another. It's a practical option for migrating larger Postgres databases into Neon.

## Why use pgcopydb for data migration?

`pgcopydb` builds on standard `pg_dump` and `pg_restore` but with extra features to make migrations both faster and more reliable:

- **Parallel migration**: `pgcopydb` processes multiple migration phases concurrently:
  - **Data transfer:** Streams data in parallel from multiple tables and splits large tables into chunks. This distributes the load and reduces migration time for large datasets.
  - **Index creation:** Builds indexes concurrently after data loading
  - **Constraint application:** Applies constraints in parallel while maintaining data integrity
    This parallel processing reduces migration time and minimizes downtime.

- **Dependency handling**: `pgcopydb` manages database object dependencies and migrates them in the correct order:

  - **Schema-first approach:** Creates schema objects (tables, functions, procedures) before data transfer begins
  - **Table copying precedes indexes and constraints:** Copies table data first, then creates indexes and applies constraints

  This ordered approach maintains data integrity and avoids errors during migration.

This guide walks you through using `pgcopydb` to migrate data to Neon.

**Note:** Logical replication with `pgcopydb clone --follow` is not supported on Neon. You can still use `pgcopydb` for a one-time data migration to Neon.

**Important:** `pgcopydb` uses `pg_dump` and `pg_restore` under the hood. Avoid using a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string) for Neon in `PGCOPYDB_SOURCE_PGURI` or `PGCOPYDB_TARGET_PGURI`. Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

## Prerequisites

Before you begin, ensure you have the following:

- **Source postgres database**: You need access to the Postgres database you intend to migrate. This can be a local instance, a cloud-hosted database (AWS RDS, GCP Cloud SQL, Azure Database for Postgres, or any other Postgres provider), or even a different Neon project.
- **Neon project**: You must have an active Neon project and a database ready to receive the migrated data. If you don't have a Neon project yet, see [Create a Neon project](https://neon.com/docs/manage/projects#create-a-project) to get started. Note that storage beyond your plan's included amount will incur additional charges.
- **pgcopydb installation**: `pgcopydb` must be installed on a machine that has network connectivity to both your source Postgres database and your Neon database. Check firewall rules and network configurations to allow traffic on the Postgres port. This machine should also have sufficient resources (CPU, memory, disk space) to handle the migration workload. Install `pgcopydb` by following the instructions in the [pgcopydb documentation](https://pgcopydb.readthedocs.io/en/latest/install.html).

## Setup environment variables

Before proceeding, set the following environment variables for your source and target Postgres databases where you will run `pgcopydb` commands:

```bash
export PGCOPYDB_SOURCE_PGURI="postgresql://source_user:source_password@source_host:source_port/source_db"
export PGCOPYDB_TARGET_PGURI="postgresql://neon_user:neon_user_password@xxxx.neon.tech/neondb?sslmode=require&channel_binding=require"
```

You can replace the placeholders with your actual connection details. You can get Neon database connection details from the Neon console. `pgcopydb` will automatically use these environment variables for the migration.

## Start data migration

Run the `pgcopydb clone` command with the `--no-owner` flag to skip ownership changes:

```bash
pgcopydb clone --no-owner
```

**Tip:** When using `--no-owner` flag in `pgcopydb`, often pair it with `--no-acl`, especially if the source has custom ACLs or default privileges. This flag skips restoring permissions (`GRANT`/`REVOKE`, `ALTER DEFAULT PRIVILEGES`). This is crucial because the user connecting to the target database often lacks the high-level rights to reapply all source permissions. For example, even when migrating between Neon databases, the target user might get "permission denied" errors when trying to restore privileges involving administrative roles (like `cloud_admin`, `neon_superuser`), as they may lack permission to manage settings for those specific roles. This typically halts `pgcopydb` during the `pg_restore` phase. Using `--no-acl` avoids these specific permission errors and allows the migration to proceed smoothly. However, this means that any custom permissions set on the source database won't be replicated in the target database. You may need to manually set them up afterward.

## Monitor the migration progress

You can monitor the migration progress using the `pgcopydb list progress` command. This command provides real-time updates on the migration status, including the number of rows copied and the current phase. You can either set the `--source` flag to your source database connection string or make use of the `PGCOPYDB_SOURCE_PGURI` environment variable.

```bash
pgcopydb list progress --source "your-source-connection-string" --summary
```

After successful completion, you will see a summary of the migration steps and their durations, similar to the following:

```text
                                               Step   Connection    Duration    Transfer   Concurrency
 --------------------------------------------------   ----------  ----------  ----------  ------------
   Catalog Queries (table ordering, filtering, etc)       source       3s775                         1
                                        Dump Schema       source       432ms                         1
                                     Prepare Schema       target         26s                         1
      COPY, INDEX, CONSTRAINTS, VACUUM (wall clock)         both         31s                        12
                                  COPY (cumulative)         both         23s       73 MB             4
                          CREATE INDEX (cumulative)       target       533ms                         4
                           CONSTRAINTS (cumulative)       target       244ms                         4
                                VACUUM (cumulative)       target       3s009                         4
                                    Reset Sequences         both       2s223                         1
                         Large Objects (cumulative)       (null)         0ms                         0
                                    Finalize Schema         both         18s                         4
 --------------------------------------------------   ----------  ----------  ----------  ------------
                          Total Wall Clock Duration         both       1m17s                        20
```

## Switch over your application to Neon

Switch your application to Neon and validate the migration after `pgcopydb clone` completes.

1. **Stop writes to source database**: Halt write operations to your source database.
2. **Validate migration**: Use `pgcopydb compare schema` and `pgcopydb compare data` for validation.
3. **Update application connection string**: Point your application to your Neon database.

## Advanced usage

`pgcopydb` offers several advanced options to optimize and customize your migration. Here are some key considerations:

### Boosting migration speed with parallelism

`--table-jobs <integer>` & `--index-jobs <integer>`: These options control the number of concurrent jobs for copying tables and creating indexes, respectively. For large databases, increasing these values is crucial for reducing migration time.

### Handling large tables efficiently

`--split-tables-larger-than <bytes>`: Automatically splits tables exceeding the specified size into smaller chunks for parallel import, dramatically accelerating migration of large datasets. Start with `1GB` or `500MB` and adjust based on your table sizes.

**Example:**

```bash
pgcopydb clone --table-jobs 8 --index-jobs 12 --split-tables-larger-than 500MB
```

This command will run the migration with **8** concurrent table jobs, **12** concurrent index jobs, and split tables larger than **500** MB into smaller chunks for parallel import.

For more detail, see [Same-table Concurrency](https://pgcopydb.readthedocs.io/en/latest/concurrency.html#same-table-concurrency) in the `pgcopydb` docs.

### Filtering and selective migration

`--filters <filename>`: Sometimes you only need to migrate a subset of your database. `--filters` allows you to precisely control which tables, indexes, or schemas are included in the migration. This is useful for selective migrations or excluding unnecessary data. For filter configuration and examples, see the [pgcopydb filtering documentation](https://pgcopydb.readthedocs.io/en/latest/ref/pgcopydb_config.html#filtering).

--- [Document source](https://neon.com/docs/import/region-migration.md) ---

> Summary: A Neon project's region is fixed at creation, so moving data to a different region requires creating a new project in the target region and migrating the database into it. A decision flowchart routes you to one of three paths: migrate to another Neon region (Import Data Assistant, pg_dump/restore, or logical replication), migrate to Databricks Lakebase Postgres when Postgres must stay in Azure, or export a pg_dump archive for migration to any other provider.

# Region migration

Move your Neon database to another region

Last updated: 2026-10-21

**Can you change the region of an existing Neon project?** Not directly, but you have options. A Neon **project** is created in a single [region](https://neon.com/docs/introduction/regions), and that region is fixed after creation. All branches in a project share the project's region, so branching alone won't move your data.

To run your database in a different region, you **create a new Neon project** in that region and **migrate your database** into it.

Common reasons to migrate to a different region:

- Your app moved to a different region and you want lower latency between your app and database.
- You need to set up a new environment in another region.
- You are migrating away from a [deprecated Neon Azure](https://neon.com/docs/introduction/regions#azure-regions) region.

**Note: Databricks Lakebase**

If you must keep Postgres in Azure for residency or colocation, Databricks Lakebase Postgres supports Azure regions. See **[Migrate Neon to Lakebase](https://neon.com/docs/guides/migrate-neon-to-lakebase)**.

## Choose a path

Use the flowchart to pick a migration path that fits your requirements.

```mermaid
flowchart TD
  start["Need to move Neon data<br/>to a new region?"]
  q1{"Postgres must stay<br/>in Azure?"}
  lake["Migrate Neon to Lakebase"]
  q2{"Stay on Neon<br/>in a new region?"}
  neon["Migrate to another Neon region"]
  q3{"Lakebase and Neon<br/>both ruled out?"}
  exp["Postgres-compatible export"]

  start --> q1
  q1 -->|Yes| lake
  q1 -->|No| q2
  q2 -->|Yes| neon
  q2 -->|No| q3
  q3 -->|Yes| exp
```

## Select a migration guide

Select the guide that matches your requirements.

1. **[Migrate to another Neon region](https://neon.com/docs/import/migrate-neon-to-another-region)**. Compare the **Import Data Assistant**, dump and restore, and logical replication, then follow the guide linked from that page.
2. **[Migrate Neon to Lakebase](https://neon.com/docs/guides/migrate-neon-to-lakebase)**. Create a Lakebase project, **`pg_dump`** from Neon, **`pg_restore`** on Lakebase. For lower downtime, [replicate from Neon to Lakebase](https://neon.com/docs/guides/logical-replication-neon-to-lakebase) with logical replication instead.
3. **[Postgres-compatible export from Neon](https://neon.com/docs/guides/export-neon-postgres-compatible)**. If another Neon region and Lakebase do not meet your requirements, use `pg_dump` to export your data in a Postgres-compatible format for migration elsewhere.

--- [Document source](https://neon.com/docs/introduction/about-billing.md) ---

> Summary: Neon's pricing plans, how to manage billing, monitor usage, and strategies for cost optimization.

# Plans and billing

Learn about Neon's pricing plans and how to manage billing

Last updated: 2026-11-06

## Neon plans

- [Plans](https://neon.com/docs/introduction/plans): Learn about Neon's usage-based pricing plans and what's included

## Manage billing

- [Manage billing](https://neon.com/docs/introduction/manage-billing): View and manage your monthly bill and learn how to change your plan
- [Monitor billing and usage](https://neon.com/docs/introduction/monitor-usage): Learn how to monitor billing and usage in Neon
- [Usage and cost calculations](https://neon.com/docs/introduction/usage-calculations): Convert raw API metrics into billing units and calculate your costs
- [Cost optimization](https://neon.com/docs/introduction/cost-optimization): Strategies to manage and reduce your Neon costs
- [Network transfer costs](https://neon.com/docs/introduction/network-transfer): Monitor and reduce network transfer costs

## Neon for Enterprise

- [Lakebase on Databricks](https://www.databricks.com/product/lakebase): Run Lakebase Postgres for enterprise workloads on Databricks

--- [Document source](https://neon.com/docs/introduction/agent-plan.md) ---

> Summary: The Neon Agent Plan is a pricing tier for platforms that provision and manage Postgres databases for end users at scale. It is organized into sponsored organizations (free and paid) with unlimited projects. Platforms building multi-tenant SaaS or agentic applications choose this plan for sponsored free-tier infrastructure and up to $25,000 in paid-tier credits. Compute is billed at $0.106 per compute unit hour. Enrollment requires an active Neon Scale plan and team approval. All provisioning and fleet management runs through the Neon API, with autoscaling, scale-to-zero, branching, and point-in-time recovery included.

# Neon Agent Plan

Learn about using Neon to provision and manage databases for agentic platforms

Last updated: 2026-08-25

**What you will learn:**

- How the agent plan is organized
- How Agent differs from Scale
- How to get started

**Related topics**

- [AI agent integration guide](https://neon.com/docs/guides/ai-agent-integration)
- [Integrating with Neon](https://neon.com/docs/guides/platform-integration-overview)
- [Database versioning with snapshots](https://neon.com/docs/ai/ai-database-versioning)
- [neon-for-agent-platforms on GitHub](https://github.com/neondatabase/neon-for-agent-platforms)

## Overview

The Neon agent plan provides infrastructure for platforms that deploy Postgres databases on behalf of end users. The plan uses a two-organization structure to separate free and paid user tiers, with unlimited projects in each organization. We incrementally raise your limit to accommodate growing usage.

Agent plan pricing and limits differ from the [Scale plan](https://neon.com/docs/introduction/plans). Agent is optimized for high project volume at Launch-rate compute pricing, with some Scale features and limits adjusted for fleet-style workloads.

## Why Neon for agent platforms

The lakebase architecture aligns with how agent platforms operate:

- **Instant provisioning**: Serverless Postgres with separated compute and storage provisions databases in seconds
- **Autoscaling and scale-to-zero**: Compute scales up and down automatically based on workload, and idle databases cost nothing while remaining instantly accessible
- **API management**: Every capability, including provisioning, quotas, branching, instant restore, and snapshots, is exposed through the Neon API
- **Database versioning**: Copy-on-write storage enables instant branching, snapshots, and point-in-time recovery for checkpoints and experimentation
- **Integrated services**: Neon supports built-in Auth and a PostgREST-compatible Data API for complete, production-ready backends

This combination enables agent builders to create thousands of databases without worrying about resource exhaustion or runaway costs.

## Enrollment requirements

To join the agent plan:

- You must have an active Neon Scale plan with a credit card on file

- Your application requires approval from the Neon team

Once your application is approved, the Neon team switches your Scale account to the Agent Plan and helps you set up a second Free Account for your Free Tier if needed. After setup, you manage all projects and configurations independently via the [Neon API](https://neon.com/docs/reference/api).

> **Neon agent plan**
>
> For custom rate limits and dedicated support for your agent platform, apply now.
>
> [Apply](https://neon.com/use-cases/ai-agents)

## Organization structure

Neon creates two organizations in your account:

### Free organization

This sponsored free organization hosts databases for your free-tier users at no cost to you; Neon sponsors the infrastructure. Individual projects have resource limits similar to Neon's standard free tier.

You are not charged for usage in this organization. Use this for users who haven't upgraded to your platform's paid plans. This means your free tier is truly free, with no database infrastructure costs passed to you.

For an overview of Free plan limits, see [Neon plans](https://neon.com/docs/introduction/plans).

### Paid organization

The paid organization hosts databases for your paying users with Agent plan pricing and limits. Neon provides up to $25,000 in initial credits to cover usage charges.

Compute is billed at $0.106 per compute unit hour (Launch rate, lower than Scale). You can create your own internal tier/plan structure within this organization, configuring different resource quotas for different user segments. Use this organization for users on your paid plans that need resource flexibility.

## Agent vs Scale

Agent and Scale are different plans. Enrollment starts from Scale, but after you join Agent your organizations use Agent pricing and limits.

| Feature                        | Agent plan                                                                 | Scale plan                                 |
| ------------------------------ | -------------------------------------------------------------------------- | ------------------------------------------ |
| Projects                       | Unlimited. We incrementally raise your limit to accommodate growing usage. | 1,000 (can be increased on request)        |
| Compute                        | $0.106 per CU-hour                                                         | $0.222 per CU-hour                         |
| Max fixed compute size         | 16 CU                                                                      | 56 CU                                      |
| Autoscaling                    | Up to 16 CU                                                                | Up to 16 CU                                |
| Branches per project           | Up to 1,000                                                                | Up to 5,000                                |
| Root branches per project      | 5                                                                          | 25                                         |
| Read replicas                  | Up to 3                                                                    | Up to 6 per branch                         |
| Instant restore history window | Up to 7 days                                                               | Up to 30 days                              |
| Public network transfer        | 100 GB per project included, then $0.10/GB                                 | 500 GB per project included, then $0.10/GB |
| Automated snapshot schedules   | Available upon request                                                     | Available                                  |

Both plans include metrics/logs export, SOC 2 reporting, private networking, and configurable scale-to-zero. For the full Scale feature list, see [Neon plans](https://neon.com/docs/introduction/plans).

## Managing projects

After initial enrollment, you have full control over both organizations as admin. Project limits are unlimited; we incrementally raise your limit to accommodate growing usage. All project operations are performed through the [Neon API](https://neon.com/docs/reference/api), enabling fleet management at scale with small engineering teams. You can:

- Create and delete projects in either organization
- Set per-project resource quotas and billing limits
- Monitor compute, storage, and network usage across all projects
- Track consumption metrics for building usage-based billing

The API-first approach means you can provision and manage thousands of databases programmatically without manual intervention.

### Project transfers between organizations

With the sponsored free and paid organization structure of the agent plan, you can move user projects between organizations when they upgrade or downgrade tiers. Transferring projects between organizations requires a [personal API key](https://neon.com/docs/manage/api-keys#types-of-api-keys) with access to both organizations. You can transfer up to 400 projects per request.

See [transfer projects between organizations](https://neon.com/docs/manage/orgs-project-transfer) for details.

## Pricing

The agent plan uses usage-based pricing with dedicated support. See [Agent vs Scale](https://neon.com/docs/introduction/agent-plan#agent-vs-scale) for how limits compare to Scale.

| Resource                        | Agent plan                                                                                        |
| ------------------------------- | ------------------------------------------------------------------------------------------------- |
| Projects                        | **Unlimited** <br/> _We incrementally raise your limit to accommodate growing usage._             |
| Branches per Project            | **Up to 1,000** <br/> _Agents use branches to quickly toggle between application states._         |
| Compute                         | **$0.106 per compute unit hour** <br/> _Same rate as Launch; lower than Scale_                    |
| Storage                         | **$0.35 per GB-month** <br/> _Same as Launch and Scale_                                           |
| Instant Restore (PITR)          | **$0.2 per GB-month** <br/> _Up to 7-day history window_                                          |
| Public network transfer         | **100 GB per project included**, then $0.10/GB                                                    |
| Management API                  | **Higher Rate Limits Available** <br/> _API for instant provisioning and management of databases_ |
| Data API (PostgREST-compatible) | **Higher Rate Limits Available** <br/> _REST API for direct database access_                      |
| Support                         | **Shared Slack Channel** <br/> _Direct access to the Neon team_                                   |

> _Pricing applies to the paid organization only._

## Billing model

The paid organization receives up to $25,000 in initial credits that cover compute ($0.106 per compute unit hour), storage, and data transfer charges. Usage is tracked per project, and the API exposes consumption metrics for building usage-based billing into your platform.

The sponsored free organization has no billing charges; Neon sponsors the infrastructure for your free tier users.

### Consumption metrics

Track compute time, storage, and network I/O per project to monitor usage and build billing logic. See the [consumption metrics guide](https://neon.com/docs/guides/consumption-metrics) for details.

## Program benefits

The agent plan includes these benefits for participating platforms:

| Benefit                    | Description                                                                                                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Your Free Tier is free** | Neon sponsors projects in your free tier, covering infrastructure costs. Project limits are unlimited; we incrementally raise your limit to accommodate growing usage. |
| **General use credits**    | Up to $25,000 in credits for paid tier usage (for platforms not already enrolled in the [Neon Startup Program](https://neon.com/startups)).                            |
| **Higher rate limits**     | Custom rate limits for Management API and Data API to support high-volume operations.                                                                                  |
| **Dedicated support**      | Shared Slack channel with direct access to the Neon team for technical support.                                                                                        |
| **Co-marketing**           | Blog features, social promotions, hackathon support, and joint marketing opportunities.                                                                                |

## Getting started

Once enrolled in the agent plan:

1. You'll receive admin access to both organizations (sponsored and paid)
2. Create projects in the appropriate organization based on your user's tier
3. Configure resource quotas per project as needed
4. Monitor usage and billing using the Neon API

For step-by-step implementation instructions, see the [AI Agent integration guide](https://neon.com/docs/guides/ai-agent-integration).

**Tip: Code samples and agent skill**

The [neon-for-agent-platforms](https://github.com/neondatabase/neon-for-agent-platforms) repository provides TypeScript samples and a companion agent skill for building on the agent plan. Install the companion skill with the [Neon CLI](https://neon.com/docs/cli):

```bash
neon skills -s neon-postgres-agent-platforms -y
```

--- [Document source](https://neon.com/docs/introduction/architecture-overview.md) ---

> Summary: The lakebase architecture splits Postgres into an ephemeral compute layer and a durable storage layer connected by WAL, so compute nodes can scale, restart, or fail without data loss. The storage layer uses Paxos-based WAL quorum across safekeepers to define commit correctness, a pageserver to reconstruct page versions on demand, and object storage for immutable long-term history. None of those components sit on the hot query path. This design enables copy-on-write branching, instant point-in-time restores, and serverless autoscaling including scale-to-zero, all as metadata operations rather than data copies. Lakebase Postgres on Neon and on Databricks both run on this architecture.

# The lakebase architecture

Inside Lakebase Postgres: decoupled compute and durable storage

Last updated: 2026-08-07

## Top level overview

Instead of running Postgres as a single stateful system tied to a VM and its filesystem, Lakebase Postgres is a serverless database that splits the system into two independent layers: compute and storage. These layers communicate over the network, with a stream of write-ahead log (WAL) records connecting them.

This separation is what puts Lakebase Postgres in the [lakebase category](https://www.databricks.com/blog/what-is-a-lakebase) of OLTP databases. Compute can scale up, scale down, go idle, and be restarted instantly without risking data loss or requiring data movement.

- **Ephemeral compute layer**: optimized for latency and execution. This layer runs Postgres, executing queries and transactions using RAM and local NVMe for performance. Compute nodes do not own durable state and can be replaced freely.
- **Durable storage layer**: optimized for correctness, history, and scale. This layer defines durability by replicating WAL via quorum, materializes Postgres pages on demand, and stores long-term, immutable history in object storage.

The lakebase architecture intentionally keeps object storage off the critical path. Object storage provides durability and scale, but never sits in front of query execution. Latency-sensitive work stays close to compute, while durability and history are handled asynchronously and independently.

![Lakebase architecture overview](https://neon.com/docs/introduction/neon-architecture-overview.png)

**Note: What is the difference between Neon and Lakebase?**

Neon and Databricks run the same database, Lakebase Postgres, on the same infrastructure. What surrounds it differs: on Neon it anchors a complete backend for apps and agents, while Databricks integrates it with the rest of the Data Intelligence Platform. For a full comparison, see [Neon and Lakebase](https://neon.com/docs/introduction/neon-and-lakebase).

## Resource hierarchy

While the sections below describe the physical architecture, Lakebase Postgres on Neon organizes resources into a logical hierarchy:

| Concept          | Description                                                           | Relationship              |
| ---------------- | --------------------------------------------------------------------- | ------------------------- |
| Organization     | Highest-level container for billing, users, and projects              | Contains Projects         |
| Project          | Primary container for all database resources for an application       | Contains Branches         |
| Branch           | Lightweight, copy-on-write clone of database state                    | Contains Databases, Roles |
| Compute Endpoint | Running Postgres instance (CPU/RAM for queries)                       | Attached to a Branch      |
| Database         | Logical container for data (tables, schemas, views)                   | Exists within a Branch    |
| Role             | Postgres role for authentication and authorization                    | Belongs to a Branch       |
| Operation        | Async action by the control plane (creating branch, starting compute) | Associated with Project   |

For details on each concept, see the [glossary](https://neon.com/docs/reference/glossary).

## Compute layer

The compute layer is where Postgres actually runs. Each Lakebase Postgres compute node is a standard Postgres instance: it parses SQL, plans queries, executes transactions, enforces MVCC, and manages locks and indexes. From the perspective of the query engine, nothing about Postgres itself is rewritten or replaced.

What is different is what the compute node is responsible for. **It exists to execute work, not to preserve data.** A compute node can start, stop, scale, or fail at any time without putting durability at risk.

### Components

A compute node has access to fast, local resources:

- RAM - used for shared_buffers, session state, and hot data
- Local NVMe - used as a performance cache for data pages

Pages cached in RAM or NVMe avoid network round-trips and keep most reads at memory or microsecond-level latencies.

### How compute fits into the system

When a query runs, the compute node behaves as you would expect:

- SQL is parsed and planned
- Pages are accessed through the buffer manager
- Changes are applied in memory

The architectural difference appears when the system crosses the boundary between execution and durability. **Instead of flushing WAL to a local filesystem, the compute node streams WAL to the storage layer.** A transaction is considered committed once that WAL has been acknowledged by a quorum of safekeepers (more on this later). The compute node does not wait for data pages to be written to disk or object storage.

For reads, **the compute node always prefers local access.** It first looks in memory, then in the local NVMe cache. Only when a page is missing locally does the compute node request it from the pageserver, which reconstructs the correct page version and returns it over the network. At no point does the compute node read directly from object storage.

## Storage layer

If the compute layer is responsible for execution, the storage layer is responsible for correctness, durability, and history. **This layer exists independently of any single compute node and continues to operate even when computes come and go.**

Rather than exposing a traditional filesystem, the database storage layer is built around three distinct components, each with a well-defined role:

- Safekeepers: define correctness by replicating WAL
- The pageserver: turns WAL into queryable data pages
- Object storage: holds long-term, immutable history

### Safekeepers: defining correctness via WAL quorum

Safekeepers are responsible for one thing: **durable replication of WAL**. When a compute node generates WAL records, it streams them to multiple safekeepers. A transaction is considered committed once a quorum of safekeepers has acknowledged the WAL record [via the Paxos protocol](https://neon.com/blog/paxos).

This is a fundamental difference from how traditional Postgres works:

- Correctness is enforced through replication and consensus
- Commit latency is primarily quorum/network-bound, with safekeepers batching WAL flushes rather than relying on compute-local fsync
- No single machine defines the durable state of the database

### Pageserver: WAL ⇄ pages

The pageserver sits between WAL and data [pages](https://neon.com/docs/reference/glossary#page). Its job is to **materialize page versions** by combining previously materialized base pages and committed WAL records. It is the system's translation layer between the logical history of the database and the physical representation needed to run queries.

When a compute node needs a page at a specific [LSN (Log Sequence Number)](https://neon.com/docs/reference/glossary#lsn), it asks the pageserver. The pageserver checks whether it already has that version available. If not, it reconstructs the page by replaying WAL up to the requested LSN and returns the result. Materialized pages are later persisted into object storage asynchronously, building up the long-term history of the database.

Importantly, page materialization is not on the transaction's critical path. Commits do not wait for pages to be written or uploaded.

### Object storage: long-term, immutable history

Object storage is where Lakebase Postgres keeps the **durable history** of the database. This layer stores materialized page versions, historical snapshots of data, and immutable representations of past states. It is not a query engine, and it is never accessed directly by the compute layer. It backs the pageserver, not Postgres.

This distinction is critical for performance. Object storage is optimal for durability, scale, and cost, not latency. Reads from object storage may take hundreds of milliseconds, but those reads happen only inside the pageserver when reconstructing pages, and never on the hot query path.

## Write path: committing a transaction

![Write path in Lakebase Postgres](https://neon.com/docs/introduction/neon-write-path.png)

When a transaction executes on a compute node:

1. **Postgres applies changes in memory.** Rows are updated in shared buffers, indexes are modified, and WAL records are generated as usual.
2. **WAL is streamed to the safekeepers.** Instead of flushing WAL to a local filesystem, the compute node sends WAL records over the network to multiple safekeepers.
3. **Commit is defined by quorum.** A transaction is considered committed once a quorum of safekeepers has acknowledged the WAL record. At this point, the client receives success.
4. **Page materialization happens later.** Page reconstruction and persistence happen asynchronously in the storage layer.

## Read path: serving data without object-store latency

![Read path in Lakebase Postgres](https://neon.com/docs/introduction/neon-read-path.png)

The obvious concern with running a database on object storage is latency, but the lakebase architecture is designed specifically to avoid this. The most important thing to understand about reads is this: **queries do not read from object storage.** Object storage backs the system, but it is never on the hot query path.

### The preferred path: local first

When Postgres running on a compute node needs to read a page, it follows a preference order:

1. **RAM (shared buffers).** This is the fastest path, just like in traditional Postgres.
2. **Local NVMe cache.** If the page is not in memory, the compute node checks its local NVMe cache. Access here is still fast.

Only if the page is missing locally does the system involve the storage layer (next section).

### Cache miss: requesting a page from the pageserver

On a cache miss, the compute node requests the required page from the pageserver, specifying the page identifier and the logical point in time (LSN). The pageserver then:

1. Checks whether it already has the requested page version materialized
2. If not, loads a base page from object storage, replays WAL records up to the requested LSN and returns the reconstructed page to the compute node

Once returned, the page can be cached in RAM and NVMe, making subsequent reads fast. This reconstruction only happens if needed, and only for the pages actually accessed.

## Durability

Durability in the lakebase architecture is not a single mechanism but a composition of responsibilities. No single component is responsible for everything, and no single machine defines the state of the database.

This layering is what allows Lakebase Postgres to tolerate failures intrinsically:

- If a compute node dies → queries stop, but data is safe. A new compute attaches immediately and continues from the same history.
- If a pageserver dies → no durable state is lost. Another pageserver can be deployed and it can reconstruct pages using WAL and object storage.
- If a safekeeper dies → another can be deployed, and WAL replication continues as long as quorum remains.
- Object storage is the last line of defense → it holds immutable page history and survives failures across entire failure domains.

## What this architecture enables

**This design turns traditionally heavy-weight database operations (which usually require copying large amounts of data) into simple metadata operations.** These include creating a new branch, restoring from a snapshot, spinning up a read replica, or attaching a new compute node. In Lakebase Postgres, these operations are fast because they operate on references to existing history, not on the data itself.

- **Serverless compute provisioning.** Because durable state lives outside the compute layer, compute endpoints can [automatically scale up and down according to load](https://neon.com/docs/introduction/autoscaling), or [scale to zero](https://neon.com/docs/introduction/scale-to-zero) entirely. When compute starts, it simply attaches to existing database history rather than reconstructing local state.
- **Copy-on-write branching.** When you create a [branch](https://neon.com/docs/introduction/branching), the engine does not duplicate files or pages. Instead, the new branch points to an existing point in history and begins diverging from there using copy-on-write semantics. Only new or modified data consumes additional storage.
- **Instant restores.** Because the database's history is preserved as immutable page versions in object storage, [restoring the database](https://neon.com/docs/introduction/branch-restore) does not involve copying data back into place. Compute can reattach to a past point in history, and execution can resume from the restored state. This process is fast and predictable, even for multi-terabyte databases.
- **One foundation for OLTP and OLAP.** Once transactional data lives in object storage, it is no longer isolated from analytical or AI workloads. The same underlying history that supports an OLTP engine (Lakebase Postgres) can also support OLAP engines and AI systems. This is the principle behind the [lakebase architecture](https://www.databricks.com/product/lakebase).

## In short

Lakebase Postgres, the database product at the center of Neon's backend primitives, is a serverless engine that treats:

- compute as ephemeral and replaceable;
- storage as durable, replicated, and shared;
- WAL as the source of truth;
- and object storage as the foundation.

The result is a database architecture that scales, recovers, and evolves without being constrained by a single machine or filesystem. For developers, this means faster iteration, safer workflows, and infrastructure that adapts automatically as applications grow from early prototypes to large-scale production systems. The same lakebase architecture underpins Lakebase Postgres via Neon and via Databricks, so transactional and analytical data can share one storage foundation.

--- [Document source](https://neon.com/docs/introduction/autoscaling-architecture.md) ---

> Summary: Neon's autoscaling architecture runs each Postgres instance inside a VM on a Kubernetes node. CPU and RAM scale dynamically through an autoscaler-agent that collects metrics, a modified Kubernetes scheduler that approves upscaling requests to prevent memory overcommit, and NeonVM, a custom VM controller built on QEMU/KVM. When a node is saturated, NeonVM live-migrates VMs to another machine in roughly 100ms, preserving the VM's IP address and keeping active queries uninterrupted. Memory scaling is event-driven through Linux cgroups notifications. A compute cache dedicates a portion of each VM's allocated RAM to disk-backed caching to accelerate repeated scans and index builds.

# Autoscaling architecture

Learn how Neon automatically scales compute resources on demand

Last updated: 2026-08-07

**What you will learn:**

- How Neon's autoscaling architecture is structured
- The role of key components like the autoscaler-agent and Kubernetes scheduler

**Related topics**

- [Introduction to autoscaling](https://neon.com/docs/introduction/autoscaling)
- [Enabling autoscaling](https://neon.com/docs/guides/autoscaling-guide)
- [How the algorithm works](https://neon.com/docs/guides/autoscaling-algorithm)

A Neon project can have one or more computes, each representing an individual Postgres instance. Storage is decoupled from these computes, meaning that the Postgres servers executing queries are physically separate from the data storage location. This separation offers numerous advantages, including enablement of Neon's autoscaling feature.

![High-level architecture diagram](https://neon.com/docs/introduction/autoscale-high-level-architecture.jpg)

Looking more closely, you can see that each Postgres instance operates within its own virtual machine inside a [Kubernetes cluster](https://neon.com/docs/reference/glossary#kubernetes-cluster), with multiple VMs hosted on each node of the cluster. Autoscaling is implemented by allocating and deallocating compute resources ([RAM](https://neon.com/docs/reference/glossary#ram)) to each VM.

![Autoscaling diagram](https://neon.com/docs/introduction/autoscale-architecture.jpg)

## The autoscaler-agent

Each [Kubernetes node](https://neon.com/docs/reference/glossary#kubernetes-node) hosts a single instance of the [autoscaler-agent](https://neon.com/docs/reference/glossary#autoscaler-agent), which serves as the control mechanism for Neon's autoscaling system. The agent collects metrics from the VMs on its node, makes scaling decisions, and performs the necessary checks and requests to implement those decisions.

## The Kubernetes scheduler

A Neon-modified [Kubernetes scheduler](https://neon.com/docs/reference/glossary#kubernetes-scheduler) coordinates with the autoscaler-agent and is the single source of truth for resource allocation. The autoscaler-agent obtains approval for all upscaling from the scheduler. The scheduler maintains a global view of all resource usage changes and approves requests for additional resources from the autoscaler-agent or standard scheduling. In this way, the scheduler assumes responsibility for preventing overcommitting of memory resources. In the rare event that a node exhausts its resources, new pods are not scheduled on the node, and the autoscaler-agent is denied permission to allocate more resources.

## NeonVM

Kubernetes does not natively support the creation or management of VMs. To address this, Neon uses a tool called [NeonVM](https://neon.com/docs/reference/glossary#neonvm). This tool is a custom resource definition and controller for VMs, handling tasks such as adding or removing CPUs and memory. Internally, NeonVM uses [QEMU](https://neon.com/docs/reference/glossary#qemu) and [KVM](https://neon.com/docs/reference/glossary#kvm) (where available) to achieve near-native performance.

When an autoscaler-agent needs to modify a VM's resource allocation, it simply updates the corresponding NeonVM object in Kubernetes, and the VM controller then manages the rest of the process.

## Live migration

In cases where a Kubernetes node becomes saturated, NeonVM manages the process of [live migrating](https://neon.com/docs/reference/glossary#live-migration) a VM, transferring the VM from one machine to another with minimal interruptions (typically around 100ms). Live migration transmits the internal state of the original VM to a new one while the former continues to operate, swiftly transitioning to the new VM after most of the data is copied. From within the VM, the only indication that a migration occurred might be a temporary performance reduction. Importantly, the VM retains its IP address, ensuring that connections are preserved and queries remain uninterrupted.

The live migration process allows for the proactive reduction of node load by migrating VMs away before reaching capacity. Although it is still possible for the node to fill up in the interim, Neon's separation of storage and compute means that VMs typically use minimal disk space, resulting in fast migrations.

## Memory scaling

Postgres memory consumption can escalate rapidly in specific scenarios. Fortunately, Neon's autoscaling system is able to detect memory usage increases without constantly requesting metrics from the VM. This is accomplished by running Postgres within a [cgroups](https://neon.com/docs/reference/glossary#cgroups), which provides notifications when memory usage crosses a specified threshold. Using cgroups in this way requires running our [vm-monitor](https://neon.com/docs/reference/glossary#vm-monitor) in the VM alongside Postgres to request more resources from the autoscaler-agent when Postgres consumes too much memory. The vm-monitor also verifies that downscaling requests from an autoscaler-agent will leave sufficient memory leftover.

## Compute cache

To expedite queries, the autoscaling system places a cache in front of the storage layer. Many queries benefit from this additional memory, particularly those requiring multiple database scans (such as creating an index). The [compute cache](https://neon.com/docs/reference/glossary#compute-cache) capitalizes on the additional memory allocated to the VM by dedicating a portion to the cache to itself. The cache is backed by disk and kept at a size intended to fit in the kernel page cache. Due to the storage model, writebacks are not required, resulting in near-instant evictions. The vm-monitor adjusts the cache size when scaling occurs through the autoscaler-agent, ensuring seamless operation.

## Autoscaling source code

To further explore Neon's autoscaling implementation, visit Neon's [autoscaling](https://github.com/neondatabase/autoscaling) GitHub repository. While not primarily designed for external use, Neon welcomes exploration and contributions.

--- [Document source](https://neon.com/docs/introduction/autoscaling.md) ---

> Summary: Neon Autoscaling dynamically scales compute resources (measured in CUs) up and down in response to live database load, with no restarts or manual intervention required. Configure autoscaling by setting a min/max CU range on any primary compute or read replica; the maximum permitted autoscaling range is 8 CU. Use this page to understand how autoscaling works and to find the configuration steps before reading the full enablement guide.

# Autoscaling

An introduction to Neon's autoscaling

Last updated: 2026-06-05

Neon's _Autoscaling_ feature dynamically adjusts the amount of compute resources allocated to a Neon compute in response to the current load, eliminating the need for manual intervention or restarts.

The following visualization shows how Neon's autoscaling works throughout a typical day. The compute resources scale up or down based on demand, ensuring that your database has the necessary compute resources when it needs them, while conserving resources during off-peak times.

![visualization for autoscaling](https://neon.com/docs/introduction/autoscaling_intro.png)

To dive deeper into how Neon's autoscaling algorithm operates, visit [Understanding Neon's autoscaling algorithm](https://neon.com/docs/guides/autoscaling-algorithm).

## Autoscaling benefits

Neon's Autoscaling feature offers the following benefits:

- **On-demand scaling:** Autoscaling helps with workloads that experience variations over time, such as applications with time-based changes in demand or occasional spikes.
- **Cost-effectiveness**: Autoscaling optimizes resource utilization, ensuring that you only use required resources, rather than over-provisioning to handle peak loads.
- **Resource and cost control**: Autoscaling operates within a user-defined range, ensuring that your compute resources and associated costs do not scale indefinitely.
- **No manual intervention or restarts**: After you enable autoscaling and set scaling limits, no manual intervention or restarts are required, allowing you to focus on your applications.

## Configuring autoscaling

You can enable autoscaling for any compute instance, whether it's a primary compute or a read replica. Simply open the **Edit compute** drawer ([learn how](https://neon.com/docs/guides/autoscaling-guide)) for your compute and set the autoscaling range. This range defines the minimum and maximum compute sizes within which your compute will automatically scale. For example, you might set the minimum to 2 CU (8 GB of RAM) and the maximum to 8 CU (32 GB of RAM). Your compute resources will dynamically adjust within these limits, never dropping below the minimum or exceeding the maximum, regardless of demand.

**Note:** The maximum permitted autoscaling range is 8 CU. This means the difference between your maximum and minimum compute size cannot exceed 8 CU.

We recommend regularly [monitoring](https://neon.com/docs/introduction/monitoring-page) your usage from the **Monitoring Dashboard** to determine if adjustments to this range are needed.

![autoscaling configuration](https://neon.com/docs/introduction/autoscaling_config.png)

For full details about enabling and configuring autoscaling, see [Enabling autoscaling](https://neon.com/docs/guides/autoscaling-guide).

--- [Document source](https://neon.com/docs/introduction/billing-aws-marketplace.md) ---

> Summary: AWS Marketplace billing for Neon is deprecated; Neon self-service pricing plans can no longer be purchased through the AWS Marketplace. Users who previously paid via AWS Marketplace must now purchase plans directly through Neon.

# AWS Marketplace

Paying for Neon via your AWS Billing account

Last updated: 2026-06-05

**Important: Deprecated**

Neon no longer supports billing through the AWS Marketplace.

Neon [self-service pricing plans](https://neon.com/pricing) are no longer purchasable through the AWS Marketplace. You can only purchase these plans through Neon.

If you have any questions about billing in general or require assistance, please reach out to [Neon Support](https://neon.com/docs/introduction/support).

--- [Document source](https://neon.com/docs/introduction/branching.md) ---

> Summary: Neon branching creates copy-on-write clones of your database instantly, with writes saved as deltas so parent branches see zero load or performance impact. Use branching to spin up isolated development or test environments pre-loaded with production data, or run parallel CI/CD pipelines. You can also recover from data loss by rolling back to any point within your history window.

# Branching

Branch your data the same way you branch your code

Last updated: 2026-09-01

With Neon, you can quickly branch your data for development, testing, and various other purposes, enabling you to improve developer productivity and optimize continuous integration and delivery (CI/CD) pipelines.

You can also rewind your data or create branches from the past to recover from mistakes or analyze historical states.

This page covers branching in Lakebase Postgres. For what one branch action does across the whole backend, see [Branch your backend](https://neon.com/docs/concepts/branch-your-backend).

[Watch on YouTube](https://youtube.com/watch?v=UuHnFlg66Io)

## What is a branch?

A branch is a copy-on-write clone of your data. You can create a branch from a current or past state. For example, you can create a branch that includes all data up to the current time or an earlier time.

**Tip: working with sensitive data?**

Neon also supports schema-only branching. [Learn more](https://neon.com/docs/guides/branching-schema-only).

A branch is isolated from its originating data, so you are free to play around with it, modify it, or delete it when it's no longer needed. Changes to a branch are independent. A branch and its parent can share the same data but diverge at the point of branch creation. Writes to a branch are saved as a delta.

Creating a branch does not increase load on the parent branch or affect it in any way, which means you can create a branch without impacting the performance of your production database.

Each Neon project is created with a [root branch](https://neon.com/docs/reference/glossary#root-branch) called `main`. The first branch that you create is branched from the project's root branch. Subsequent branches can be branched from the root branch or from a previously created branch.

**Tip: Using Managed Better Auth?**

Users, sessions, and auth configuration in the `neon_auth` schema branch with your data, so preview and test environments get isolated authentication state. See [Managed Better Auth](https://neon.com/docs/auth/overview) and [Branching authentication](https://neon.com/docs/auth/branching-authentication).

**Tip: Using Neon backend services?**

Object Storage, Functions, and AI Gateway all branch with your data too: each branch gets its own storage namespace, function deployment, and gateway endpoint, isolated from its parent. See [Neon Object Storage](https://neon.com/docs/storage/overview), [Neon Functions](https://neon.com/docs/compute/functions/overview), and [Neon AI Gateway](https://neon.com/docs/ai-gateway/overview).

## Branching workflows

You can use Neon's branching feature in a variety of workflows.

### Development

You can create a branch of your production database that developers are free to play with and modify. By default, branches are created with all of the data that existed in the parent branch, eliminating the setup time required to deploy and maintain a development database.

![development environment branch](https://neon.com/docs/introduction/branching_dev_env.png)

The following video demonstrates creating a branch in the Neon Console. For step-by-step instructions, see [Create a branch](https://neon.com/docs/manage/branches#create-a-branch).

You can integrate branching into your development workflows and toolchains using the Neon CLI, API, or GitHub Actions. If you use Vercel, you can use the [Neon-managed Vercel integration](https://neon.com/docs/guides/neon-managed-vercel-integration) to create a branch for each preview deployment.

Refer to the following guides for instructions:

- [Branching with the Neon API](https://neon.com/docs/guides/branching-neon-api): Learn how to instantly create and manage branches with the Neon API
- [Branching with the Neon CLI](https://neon.com/docs/guides/branching-neon-cli): Learn how to instantly create and manage branches with the Neon CLI
- [Branching with GitHub Actions](https://neon.com/docs/guides/branching-github-actions): Automate branching with Neon's GitHub Actions for branching
- [The Neon-Managed Vercel Integration](https://neon.com/docs/guides/neon-managed-vercel-integration): Connect your Vercel project and create a branch for each preview deployment

### Testing

Testers can create branches for testing schema changes, validating new queries, or testing potentially destructive queries before deploying them to production. A branch is isolated from its parent branch but has all of the parent branch's data up to the point of branch creation, which eliminates the effort involved in hydrating a database. Tests can also run on separate branches in parallel, with each branch having dedicated compute resources.

![test environment branches](https://neon.com/docs/introduction/branching_test.png)

Refer to the following guide for instructions.

- [Branching: Testing queries](https://neon.com/docs/guides/branching-test-queries): Instantly create a branch to test queries before running them in production

### Temporary environments

Create branches with TTL by [setting an expiration date](https://neon.com/docs/guides/branch-expiration). Perfect for temporary development and testing environments that need automatic deletion.

Branches with expiration work well for:

- CI/CD pipeline testing environments
- Feature development with known lifespans
- Automated testing scenarios
- AI-driven development workflows

## Restore and recover data

If you lose data due to an unintended deletion or some other event, you can use **[instant restore](https://neon.com/docs/introduction/branch-restore)** to recover: roll the branch back to any point in time that still falls within your project's **history window** (the retention you configure under **Settings → Postgres**). You can also create a new restore branch for historical analysis or any other reason.

![Recover from data loss using restore branching](https://neon.com/docs/introduction/branching_data_loss.png)

### History window

**Instant restore** (and Time Travel, branching from the past, and snapshots) need Neon to keep a log of data changes. The **history window** is the project-wide setting—on **Settings → Postgres** in the Console—that controls how long that change history is retained, which sets how far back **instant restore** and the other features can reach.

Neon retains a history of changes for your branches, with defaults of 6 hours on Free plan and 1 day on paid plans. Increasing the history window expands recovery options but also increases storage costs, as more history is kept. You can configure it up to 7 days on Launch or 30 days on Scale plans.

For limits, billing, and how to change the setting, see [History window](https://neon.com/docs/introduction/history-window).

Learn how to use these data recovery features:

- [Instant restore](https://neon.com/docs/guides/branch-restore): Restore a branch to an earlier point in its history
- [Reset from parent](https://neon.com/docs/guides/reset-from-parent): Reset a branch to match its parent
- [Time Travel queries](https://neon.com/docs/guides/time-travel-assist): Run SQL queries against your database's past state

--- [Document source](https://neon.com/docs/introduction/compute-lifecycle.md) ---

> Summary: Neon compute runs as a stateless Postgres process with two states, Active and Idle, and automatically suspends after 5 minutes of inactivity (scale to zero), which paid plans can disable. Activation from idle takes a few hundred milliseconds under normal conditions but may be longer after 7 or more days without connections. Cold memory buffers also slow the first queries after wakeup. Session-scoped objects such as temporary tables, prepared statements, advisory locks, and NOTIFY/LISTEN subscriptions are lost when the compute suspends.

# Compute lifecycle

Last updated: 2026-09-16

A compute in Neon is a stateless Postgres process due to the separation of storage and compute. It has two main states: `Idle` and `Active`.

Generally, an idle compute has been suspended by Neon's scale to zero feature due to inactivity, while an `Active` compute has been activated by a connection or operation, indicating that Postgres is currently running.

## Scale to zero

If there are no active queries for 5 minutes, which is the scale to zero setting in Neon, your compute is automatically placed into an idle state. If you are on a paid plan, you can disable the scale to zero behavior so that a compute always remains active. This behavior is controlled by your compute's **Scale to zero** setting.

![Scale to zero configuration dialog](https://neon.com/docs/introduction/autoscaling_config.png)

For information about configuring this setting, see [Edit a compute](https://neon.com/docs/manage/computes#edit-a-compute).

**Note:** Neon's _Scale to Zero_ feature is conservative. It treats an "idle-in-transaction" connection as active to avoid breaking application logic that involves long-running transactions. Only the truly inactive connections are closed after the defined period of inactivity.

## Compute activation

When you connect to an idle compute, Neon automatically activates it. Activation generally takes a few hundred milliseconds. However, if your Neon project has been idle for more than 7 days, you may experience a slightly longer activation time.

Considering this activation time, your first connection may have a slightly higher latency than subsequent connections to an already-active compute. Also, Postgres memory buffers are cold after a compute wakes up from the idle state, which means that initial queries may take longer until the memory buffers are warmed.

After a period of time in the idle state, Neon occasionally activates your compute to check for data availability. The time between checks gradually increases if the compute does not receive any client connections over an extended period.

In the **Branches** widget in the Console nav, you can check if a compute is active or idle and watch as it transitions from one state to another.

![Compute state](https://neon.com/docs/introduction/compute_state.png)

## Session context considerations

When connections are closed due to a compute being suspended, anything that exists within a session context is forgotten and must be recreated before being used again. For example, Postgres parameters set for a specific session, in-memory statistics, temporary tables, prepared statements, advisory locks, and notifications and listeners defined using `NOTIFY/LISTEN` commands only exist for the duration of the current session and are lost when the session ends.

For more, see [Session context](https://neon.com/docs/reference/compatibility#session-context).

--- [Document source](https://neon.com/docs/introduction/cost-optimization.md) ---

> Summary: Storage is unlimited on paid plans: there's no hard per-branch size limit and storage grows with your usage. Practical strategies for cutting Neon costs across every billing metric: compute (CU-hours), storage, instant restore history, extra branches, and public data transfer. Use this page to diagnose an unexpectedly high bill or to proactively reduce spend. Key tactics include right-sizing compute, enabling scale to zero, running VACUUM FULL to reclaim storage space, and trimming the PITR history window. Instant restore storage is billed at $0.20/GB-month on paid plans for root branches only. Extra branches cost $1.50/branch-month over the plan allowance. Paid plans include 500 GB of public data transfer per project per month, then $0.10/GB.

# Cost optimization

Strategies to manage and reduce your Neon costs

Last updated: 2026-09-29

Managing your Neon costs effectively requires understanding how each billing factor works and implementing strategies to control usage. This guide provides actionable recommendations for optimizing costs across all billing metrics.

To monitor your current usage, check the **Billing** page in the [Neon Console](https://console.neon.tech), which shows your charges to date for each billing metric. For programmatic access to usage data, see [Consumption metrics](https://neon.com/docs/guides/consumption-metrics).

## Compute (CU-hours)

Compute is typically the largest component of your Neon bill. You're charged based on compute size (in CUs) multiplied by the hours your compute is running.

**Optimization strategies:**

- **Right-size your compute.** Start by determining the appropriate compute size for your workload. Your compute should be large enough to cache your frequently accessed data (your working set) in memory. A compute that's too small can lead to poor query performance, while an oversized compute wastes resources. See [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute) for guidance.

- **Use autoscaling effectively.** Configure [autoscaling](https://neon.com/docs/introduction/autoscaling) to dynamically adjust compute resources based on demand. Set your minimum size to handle your baseline workload and your maximum to accommodate peak traffic. You only pay for what you use. See [Enable autoscaling](https://neon.com/docs/guides/autoscaling-guide) for configuration steps.

- **Enable scale to zero.** For non-production environments or databases with intermittent usage, enable [scale to zero](https://neon.com/docs/introduction/scale-to-zero) to suspend your compute after 5 minutes of inactivity. This can dramatically reduce compute costs for development, testing, and preview environments. See [Configuring scale to zero](https://neon.com/docs/guides/scale-to-zero-guide).

- **Manage persistent connections and scheduled jobs.** Applications that maintain long-lived connections or scheduled jobs (like cron tasks) can prevent your compute from scaling to zero, keeping it active 24/7. If these aren't critical, consider closing idle connections or adjusting job schedules to allow scale to zero during off-peak hours.

- **Be aware of logical replication impact when replicating from Neon.** If you replicate data **from** Neon (Neon as the publisher) to an external destination, your compute stays active while subscribers are connected and will not [scale to zero](https://neon.com/docs/introduction/scale-to-zero), resulting in ongoing compute usage and higher bills. See [Important notices about logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) for details. Plan accordingly and consider whether outbound logical replication is necessary for all environments.

- **Consider read replica costs.** [Read replicas](https://neon.com/docs/introduction/read-replicas) are billed as separate compute endpoints. If you have read replicas, they add to your total compute hours. Review whether all replicas are needed, and consider scale to zero settings for replicas used infrequently.

## Storage (root and child branches)

Storage costs are based on actual data size for root branches and the minimum of accumulated changes or logical data size for child branches, billed in GB-months.

**Optimization strategies:**

- **Clean up unused data.** Delete old rows, drop unused tables, and remove test data to reduce your root branch data size. Be aware that delete operations generate WAL records that temporarily add to your [instant restore storage](https://neon.com/docs/introduction/cost-optimization#instant-restore-storage) until they age out of your history window. For bulk deletions, use `TRUNCATE TABLE` instead of `DELETE` when possible (it generates far less WAL).

- **Reclaim space from bloated tables.** Frequent updates and deletes leave dead tuples that inflate your data size. You can run `VACUUM FULL` on heavily modified tables to reclaim space. However, see the [VACUUM FAQ](https://neon.com/docs/introduction/cost-optimization#how-does-running-vacuum-or-vacuum-full-affect-my-storage-costs) first to understand the trade-offs before taking action.

- **Manage child branch storage.** Child branches are billed for the minimum of accumulated data changes or your logical data size, capped at your actual data size. While this prevents charges from exceeding your data size, managing branches effectively still helps minimize costs:
  - Set a [time to live](https://neon.com/docs/guides/branch-expiration) on development and preview branches
  - [Delete](https://neon.com/docs/manage/branches#delete-a-branch) child branches when they're no longer needed
  - For production workloads, use a [root branch](https://neon.com/docs/manage/branches#root-branch) instead (root branches are billed on actual data size)

- **Implement branch lifecycle management.** Review your branches regularly and [delete](https://neon.com/docs/manage/branches#delete-a-branch) any that are no longer needed. Keeping your branch count under control reduces both storage costs and potential [extra branch charges](https://neon.com/docs/introduction/plans#extra-branches).

### Storage FAQs

<details>

<summary>**Do branches add to storage?**</summary>

When branches are created, they initially do not add to storage since they share data with their parent through copy-on-write. However, as soon as changes are made to a branch, new data is written, adding to child branch storage. See [Manage child branch storage](https://neon.com/docs/introduction/cost-optimization#storage-root-and-child-branches) above for strategies to control branch storage costs.

</details>

<details>

<summary>**Do delete operations add to storage?**</summary>

Yes. Any data-modifying operation, including deletes, generates [WAL records](https://neon.com/docs/reference/glossary#write-ahead-logging-wal) that temporarily increase your storage size until they age out of your history window. For mass deletions, `TRUNCATE TABLE` is more storage-efficient since it logs a single operation rather than a record for each deleted row.

</details>

<details>

<summary>**What happens when I reach my storage limit?**</summary>

Storage limits depend on your Neon plan:

- **Free plan**: The Free plan includes 1 GB of storage per project. If you reach this limit, database operations that would increase storage (inserts, updates, and deletes) will fail until you reduce your storage or [upgrade to a paid plan](https://neon.com/docs/introduction/manage-billing#change-your-plan).
- **Paid plans**: Storage is unlimited on Launch and Scale: there's no hard per-branch size limit, your storage grows with your usage, and you pay only for what you use.

</details>

<details>

<summary>**I have a small database. Why is my bill higher than expected?**</summary>

If your database is small but your bill seems high, check these factors:

- **Instant restore history:** Neon charges for point-in-time restore (PITR) storage only for branches you can point-in-time restore from: **root branches**. Child branches do not add to PITR storage charges. If you perform many data modifications on your root branch(es) with a 7-day history window, you'll accumulate 7 days of that billable history at $0.20/GB-month. See [Instant restore storage](https://neon.com/docs/introduction/cost-optimization#instant-restore-storage) for optimization strategies.
- **Unused branches:** If you created branches, performed write operations, and forgot about the branches, they could be contributing to your storage costs. Review and [delete](https://neon.com/docs/manage/branches#delete-a-branch) branches you no longer need.
- **Table bloat:** Frequent updates and deletes can cause table bloat (dead tuples), which can make your data size larger than expected. See the [VACUUM FAQ](https://neon.com/docs/introduction/cost-optimization#how-does-running-vacuum-or-vacuum-full-affect-my-storage-costs) for details.

To see what's driving your costs, check the **Billing** page in the Neon Console, which shows your charges to date for each billing metric.

</details>

<details>

<summary>**How does running VACUUM or VACUUM FULL affect my storage costs?**</summary>

If you're looking to control your storage costs, you might start by deleting old data from your tables, which reduces the data size you're billed for going forward. Since, in typical Postgres operations, deleted tuples are not physically removed until a vacuum is performed, you might then run `VACUUM`, expecting to see a further reduction in the `Data size` reported in the Console. But you don't see the expected decrease.

**Why no reduction?**

In Postgres, [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html) doesn't reduce your storage size. Instead, it marks the deleted space in the table for reuse, meaning future data can fill that space without increasing data size. While, `VACUUM` by itself won't make the data size smaller, it is good practice to run it periodically, and it does not impact availability of your data.

```sql
VACUUM your_table_name;
```

**Use VACUUM FULL to reclaim space**

Running `VACUUM FULL` _does_ reclaim physical storage space by rewriting the table, removing empty spaces, and shrinking the table size. This can help lower the **Data size** part of your storage costs. It's recommended to use `VACUUM FULL` when a table has accumulated a lot of unused space, which can happen after heavy updates or deletions. For smaller tables or less frequent updates, a regular `VACUUM` is usually enough.

To reclaim space using `VACUUM FULL`, you can run the following command per table you want to vacuum:

```sql
VACUUM FULL your_table_name;
```

However, there are some trade-offs:

- **Table locking.** `VACUUM FULL` locks your table during the operation. If this is your production database, this may not be an option.
- **Temporary storage spike.** The process creates a new copy of the table, temporarily increasing your storage usage. On the Free plan, this could cause the operation to fail if you hit the 1 GB storage limit.

In short, `VACUUM FULL` can help reduce your data size and future storage costs, but be aware of the temporary storage spike and table locking during the operation.

**Recommendations**

- **Use VACUUM FULL sparingly.** Because it locks tables and can temporarily increase storage, only run `VACUUM FULL` when there is a significant amount of space to be reclaimed.
- **Manual VACUUM for scale to zero users.** In Neon, [autovacuum](https://www.postgresql.org/docs/current/routine-vacuuming.html#AUTOVACUUM) is enabled by default. However, when your compute suspends due to inactivity, the database activity statistics that autovacuum relies on are lost. If your project uses [scale to zero](https://neon.com/docs/guides/scale-to-zero-guide#considerations), consider running manual `VACUUM` operations regularly on frequently updated tables.

  To clean a single table named `playing_with_neon`, analyze it for the optimizer, and print a detailed vacuum activity report:

  ```sql
  VACUUM (VERBOSE, ANALYZE) playing_with_neon;
  ```

  See [VACUUM and ANALYZE statistic](https://neon.com/docs/postgresql/query-reference#vacuum-and-analyze-statistics) for a query that shows the last time vacuum and analyze were run.

</details>

<details>

<summary>**What is the maximum data size that Neon supports?**</summary>

Storage is unlimited on paid plans (Launch and Scale). Neon applies quota-based soft limits to help you avoid unexpected costs; if you approach your quota, writes slow down rather than stop, and you can contact [Neon Support](https://neon.com/docs/introduction/support) to raise it. The Free plan is limited to 1 GB per project.

</details>

## Instant restore storage

Instant restore storage (PITR storage) is the change history retained for point-in-time recovery. Neon only charges for PITR storage on branches you can point-in-time restore from: **root branches**. You cannot point-in-time restore from child branches, so child branches do not add to this charge. Instant restore storage is billed at $0.20/GB-month on paid plans, separate from your data storage. The Free plan includes up to 1 GB of instant restore history at no charge.

**Optimization strategies:**

- **Adjust your history window.** By default, Neon retains instant restore history for 6 hours on Free plan projects and 1 day on paid plan projects. You can increase this up to the maximum for your plan (6 hours for Free, 7 days for Launch, 30 days for Scale). If you don't need much recovery capability, reduce your history window to lower costs. See [History window](https://neon.com/docs/introduction/history-window).

- **Understand the trade-offs.** A longer history window means more recovery options for **instant restore** but higher instant restore storage costs. A shorter window reduces costs but limits how far back **instant restore** can go. Consider your actual recovery requirements when setting the window.

- **High-write workloads on root branches generate more history.** The more writes on your root branch(es), the more instant restore history accumulates. For write-heavy root branches, a shorter history window can significantly reduce costs.

## Extra branches

Extra branches beyond your plan's allowance are billed at $1.50/branch-month, prorated hourly. Plans include 10 branches for Free and Launch, 25 for Scale.

**Optimization strategies:**

- **Use branch expiration.** Set automatic deletion timestamps on temporary branches using [branch expiration](https://neon.com/docs/guides/branch-expiration) to ensure they're cleaned up when no longer needed.

- **Automate cleanup.** Consider implementing automated cleanup scripts using the [Neon API](https://neon.com/docs/manage/branches#branching-with-the-neon-api) or [Neon CLI](https://neon.com/docs/guides/branching-neon-cli) to stay within your plan's branch allowance.

- **Check Vercel retention settings.** If you use the Vercel-Managed integration, Vercel's default deployment retention policy can delay automatic branch cleanup by months. Reduce the retention period or set up a GitHub Action for immediate cleanup. See [Managing Vercel preview branch cleanup](https://neon.com/docs/guides/vercel-branch-cleanup).

## Public data transfer

Public network transfer (egress) is the data sent from your databases over the public internet. Free plans include 5 GB per project per month. On paid plans, the first 500 GB per project per month is included, then $0.10/GB. You see no data transfer cost until a project exceeds that allowance, so the charge might show up unexpectedly if you're not monitoring data transfer. For a deeper look at what causes high network transfer and how to monitor it, see [Network transfer](https://neon.com/docs/introduction/network-transfer).

**Optimization strategies:**

- **Optimize query results.** Select only the columns you need rather than using `SELECT *`. For large result sets, use pagination or streaming instead of fetching all rows at once.

- **Consider logical replication costs.** [Logical replication](https://neon.com/docs/guides/logical-replication-neon) to external destinations counts as public data transfer. If you're replicating large amounts of data, factor this into your transfer costs.

- **Reduce backup-related egress.** Frequent `pg_dump` (or similar) exports send your data over the network and count as public data transfer. To lower egress, reduce how often you run dumps and consider using [Neon's snapshots](https://neon.com/docs/guides/backup-restore) with [scheduled backups](https://neon.com/docs/guides/backup-restore#create-backup-schedules) as a backup alternative that does not transfer data off Neon.

- **Monitor with the consumption API.** Track data transfer programmatically using the [Consumption API](https://neon.com/docs/guides/consumption-metrics), or check the **Billing** page in the Console for current charges.

--- [Document source](https://neon.com/docs/introduction/feedback.md) ---

> Summary: Send feedback to the Neon team with the Neon CLI (`neon feedback`), an HTTP POST to https://feedback.neon.tech/, the Neon MCP Server (`send_feedback`), the Neon Console, or the Neon Discord server. People and coding agents use the same channels. Also served at https://neon.com/feedback.md.

# Send feedback

Share ideas, requests, and problems with the Neon team

Last updated: 2026-10-15

Tell us about a docs page that's wrong or out of date, a command or API call that doesn't behave as documented, a confusing error, a feature you'd like, or an example you'd find useful. People and coding agents can use the same channels.

Feedback isn't a support channel. If you need help with an issue, see [Support](https://neon.com/docs/introduction/support).

Don't include passwords, API keys, connection strings, or other secrets in your feedback.

## Where to send it

If you're a coding agent, use the first option your environment supports.

### Neon CLI

Run [`neon feedback`](https://neon.com/docs/cli/feedback) from your terminal. You don't need to be logged in.

```bash
neon feedback --message "I'd love a Python example for branching in the docs"
```

```text filename="Output"
Feedback received. Thank you!
```

The `feedback` command requires Neon CLI version 8.0.2 or later. Run `neon --version` to check your version, and [upgrade the CLI](https://neon.com/docs/cli/install#upgrade) if needed.

### HTTP

Send a POST request with a JSON body to `https://feedback.neon.tech/`. No authentication is required.

```bash
curl -X POST https://feedback.neon.tech/ \
  -H 'Content-Type: application/json' \
  -d '{"feedback": "describe the issue", "source": "neon_website", "path": "/docs/connect/choose-connection"}'
```

| Field      | Required | Value                                                                                       |
| ---------- | -------- | ------------------------------------------------------------------------------------------- |
| `feedback` | Yes      | Your feedback, up to 10,000 characters                                                      |
| `source`   | Yes      | `neon_website`                                                                              |
| `path`     | No       | The docs path, command, API endpoint, or tool the feedback is about, up to 2,048 characters |

A rejected request returns a 4xx status with an `error` message in the JSON body, such as `{"error": "feedback is required"}`.

### Neon MCP Server

If your coding agent is connected to the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server), ask it to send feedback. The agent uses the `send_feedback` tool. It's available on every connection, including the no-login `https://mcp.neon.tech/mcp?category=docs` endpoint. For example:

```text
Send Neon feedback that I'd love a TypeScript example for branching in the docs.
```

### Neon Console

In the [Neon Console](https://console.neon.tech), select **Feedback** at the bottom of the left sidebar. Enter your message under **Share your thoughts** and select **Send**. You can also open the form directly with this [Feedback](https://console.neon.tech/app/projects?modal=feedback) link.

### Discord

Join the [feedback channel](https://discord.com/channels/1176467419317940276/1176788564890112042) on the [Neon Discord server](https://neon.com/discord) to share ideas and see what other Neon users are building.

## What gets sent

The Neon CLI and the Neon MCP Server send only your message. No account, project, or connection details come with it.

Feedback from the Neon Console is linked to your Neon user ID, so the Neon team can see which account sent it.

## Write a useful report

- Say what you tried, what you expected, and what happened.
- Name the page URL, command, API endpoint, or tool involved.
- Quote error messages exactly.
- Send one issue per report.

--- [Document source](https://neon.com/docs/introduction/high-availability.md) ---

> Summary: Neon high availability separates storage and compute. WAL is replicated across Availability Zones by Safekeepers, and Pageservers fail over to secondaries in seconds, without idle standby compute replicas. Object storage provides 99.999999999% durability. Recovery times vary by failure type: Postgres crash and VM failure resolve in seconds, node failure in 1-2 minutes, AZ failure in 1-10 minutes, and unresponsive endpoints after 5 minutes. Neon HA does not support cross-region replication. Session data such as temporary tables and the compute cache does not persist across a failover.

# High Availability (HA) in Neon

Understanding Neon's approach to High Availability

Last updated: 2026-10-23

At Neon, our lakebase architecture takes a different approach to high availability. Instead of maintaining idle standby compute replicas, we achieve multi-AZ resilience through our separation of storage and compute.

![lakebase architecture diagram](https://neon.com/docs/introduction/neon_architecture_5.jpg)

Based on this separation, we can break our approach into two main parts:

- **Storage redundancy** — _Protecting both your long-term and active data_

  On the storage side, all data is backed by cloud object storage for long-term safety, while Pageserver and Safekeeper services are distributed across [Availability Zones](https://en.wikipedia.org/wiki/Availability_zone) to provide redundancy for the cached data used by compute.

- **Compute resiliency** — _Keeping your application running_

  Our architecture scales to handle traffic spikes and restarts or reschedules compute instances when issues occur, with recovery times typically ranging from a few seconds to a few minutes. While this means your application needs to handle brief disconnections, it provides cost efficiency by eliminating the need for continuously running standby compute instances.

## Storage redundancy

By distributing storage components across multiple Availability Zones (AZs), Neon ensures both data durability and continuous data access.

### General storage architecture

This diagram shows how Neon handles Safekeeper or Pageserver service recovery across Availability Zones:

![HA storage failover](https://neon.com/docs/introduction/HA-storage-failover.png)

In this architecture:

- **Safekeepers replicate data across AZs**

  Safekeepers are distributed across multiple Availability Zones (AZs) to handle **Write-Ahead Log (WAL) replication**. WAL is replicated across these multi-AZ Safekeepers, ensuring your data is safe if any particular Safekeeper fails.

- **Pageservers**

  Pageservers act as a disk cache, ingesting and indexing data from the WAL stored by Safekeepers and serving that data to your compute. To ensure high availability, Neon employs secondary Pageservers that maintain up-to-date copies of project data.

  In the event of a Pageserver failure, impacted projects are immediately reassigned to a secondary Pageserver, with minimal downtime. The system continuously monitors Pageserver health using a heartbeat mechanism to ensure timely detection and failover.

- **Object storage**

  Your data's primary, long-term storage is in **cloud object storage**, with **99.999999999%** durability, protecting against data loss regardless of Pageserver or Safekeeper status.

#### Recap of storage recovery times

Here's a summary of how different storage components handle and recover from failures:

| Component      | Failure impact                                 | Recovery mechanism              | Recovery time |
| -------------- | ---------------------------------------------- | ------------------------------- | ------------- |
| Safekeeper     | WAL writes continue to other Safekeepers       | Redundancy is built-in          | Immediate     |
| Pageserver     | Read requests automatically route to secondary | Automatic failover to secondary | Seconds       |
| Object storage | No impact - 99.999999999% durability           | Multi-AZ redundancy built-in    | Immediate     |

## Compute failover

Our serverless architecture manages compute failures through rapid recovery and automatic traffic redirection, without the need to maintain idle standby replicas. Because compute instances are stateless, failures don't affect your data, and your connection string remains unchanged. The system typically resolves issues within seconds to minutes, depending on the type of failure. However, your application should be configured to handle brief disconnections and reconnect automatically.

### Compute endpoints are ephemeral

Your compute endpoint exists essentially as metadata, with your connection string being the core element. This design means endpoints can be instantly reassigned to new compute resources without changing your application's configuration. When you first connect, Neon assigns your endpoint to an available VM from our ready-to-use pool, eliminating traditional provisioning delays.

### Postgres failure

Postgres runs inside the VM. If Postgres crashes, an internal Neon process detects the issue and automatically restarts Postgres. This recovery process typically completes within a few seconds.

![Postgres restarting after failure](https://neon.com/docs/introduction/postgres_fails.png)

### VM failure

In rarer cases, the VM itself may fail due to issues like a kernel panic or the host's termination. When this happens, Neon recreates the VM and reattaches your compute endpoint. This process may take a little longer than restarting Postgres, but it still typically resolves in seconds.

![VM restarting after failure](https://neon.com/docs/introduction/vm_fails.png)

### Unresponsive endpoints

If a compute endpoint becomes unhealthy or unresponsive, we will automatically detect and reattach it to a new compute after 5 minutes. Your application may experience connectivity issues until the endpoint is restored.

### Node failures

Kubernetes nodes are the underlying infrastructure hosting multiple compute instances. When a node becomes unavailable, Neon automatically reschedules compute instances to other healthy nodes, a process that typically takes 1-2 minutes. While your data remains safe during this process, compute availability will be temporarily affected until rescheduling is complete.

### Availability Zone failures

Availability Zones are physically separate data centers within a cloud region. When an AZ becomes unavailable, compute instances in that AZ will be automatically rescheduled to healthy AZs. Recovery time typically takes 1-10 minutes, depending on node availability in the destination AZs. Your connection string remains stable, and new connections will be routed to the recovered instance.

Multi-AZ support is available in all regions for recovery purposes. While compute instances run in a single AZ at any given time, storage components are continuously distributed across multiple AZs, and compute can be automatically rescheduled to other AZs if needed.

### Recap of failover times

Here's a summary of how different types of compute failures are handled and their expected recovery times:

| Failure type              | Impact                             | Recovery mechanism                      | Recovery time |
| ------------------------- | ---------------------------------- | --------------------------------------- | ------------- |
| Postgres crash            | Brief interruption                 | Automatic restart                       | Seconds       |
| VM failure                | Brief interruption                 | VM recreation and endpoint reattachment | Seconds       |
| Unresponsive endpoint     | Intermittent connectivity          | Automatic recovery initiation           | 5 minutes     |
| Node failure              | Compute unavailable                | Rescheduling to healthy nodes           | 1-2 minutes   |
| Availability Zone failure | Compute unavailable in affected AZ | Rescheduling to healthy AZs             | 1-10 minutes  |

### Impact on session data after failover?

While your application should handle reconnections automatically, session-specific data like temporary tables, prepared statements, and the [compute cache](https://neon.com/docs/reference/glossary#compute-cache), which stores frequently accessed data, will not persist across a failover. As a result, queries may initially run more slowly until the Postgres memory buffers and cache are rebuilt.

For details on uptime and performance guarantees, refer to the [Neon Service Level Agreement](https://neon.com/docs/legal/sla).

## Limitations

_No cross-region replication._ Neon's HA architecture is designed to mitigate failures within a single region by replicating data across multiple AZs. However, we currently do not support real-time replication across different cloud regions. In the event of a region-wide outage, your data is not automatically replicated to another region, and availability depends on the cloud provider restoring service to the affected region.

--- [Document source](https://neon.com/docs/introduction/ip-allow.md) ---

> Summary: IP Allow is a Neon Scale plan feature that blocks connections from any IP address not on an explicit allowlist. It supports individual addresses, ranges, and CIDR notation. Use it to enforce network-level access control beyond database credentials alone. Restrictions can be scoped to protected branches only, leaving other branches unrestricted, and are configured in project settings.

# IP Allow

Limit database access to trusted IP addresses

Last updated: 2026-10-09

Neon's IP Allow feature, available with the Neon [Scale](https://neon.com/docs/introduction/plans) plan, ensures that only trusted IP addresses can connect to the project where your database resides, preventing unauthorized access and helping maintain overall data security. You can limit access to individual IP addresses, IP ranges, or IP addresses and ranges defined with [CIDR notation](https://neon.com/docs/reference/glossary#cidr-notation).

You can configure **IP Allow** in your Neon project's settings. To get started, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

## Neon services to allowlist

If IP Allow is enabled on your project, add the following IP addresses to allow connections from Neon hosted services:

| Service                                                     | IP addresses                     |
| ----------------------------------------------------------- | -------------------------------- |
| [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server) | `34.192.103.46`, `23.22.233.166` |

## IP Allow together with Protected Branches

You can apply IP restrictions more precisely by designating specific branches in your Neon project as protected and selecting **Protected branches only** under **Restricted branches** in your project's **Settings** > **Networking**. This will apply your IP allowlist to protected branches only with no IP restrictions on other branches in your project. Typically, the protected branches feature is used with branches that contain production or sensitive data. For step-by-step instructions, refer to our [Protected Branches guide](https://neon.com/docs/guides/protected-branches).

**Tip:** If you are an AWS user, Neon also supports a **Private Networking** feature, which enables connections to your Neon databases via AWS PrivateLink, bypassing the open internet entirely. See [Private Networking](https://neon.com/docs/guides/neon-private-networking).

--- [Document source](https://neon.com/docs/introduction/live-sql-queries.md) ---

> Summary: A live SQL query is a query you subscribe to instead of running once. Realtime makes any SQL query live on standard Postgres, including joins, aggregates, functions and extensions.

# Live SQL queries

Subscribe to data in realtime with live SQL queries.

Last updated: 2026-10-15

A live SQL query is a query you subscribe to, instead of running it once. You get the current results straight away, then the changes as writes land, so your app always has the latest answer without polling.

[Realtime](https://neon.com/docs/realtime/overview) makes any SQL query live on standard Lakebase Postgres. That includes joins, aggregates, functions and extensions, at high throughput, with no second database or bespoke sync system to run.

## Seal and subscribe

Define the query in your backend and seal it. A sealed query is a short-lived capability for one exact query, so you can pass it safely to a browser or an agent:

```ts filename="your-server.ts"
import { createRealtime, rawSql } from "@neon/realtime/server"

const realtime = createRealtime({
  secret: process.env.NEON_REALTIME_SECRET!,
  db: "neondb"
})

// Any SQL query, including joins, aggregates, functions and extensions
const query = rawSql("select id, body from messages where channel_id = $1", [channelId])
const sealedQuery = await realtime.seal({ query })
```

Then subscribe to the sealed query from the client:

```ts filename="your-client.ts"
import { createRealtimeClient } from "@neon/realtime/client"

const client = createRealtimeClient({ url: "wss://realtime.neon.tech/..." })

const subscription = client.subscribe(sealedQuery)
subscription.onChange(({ data, status }) => {
  console.log(status, data)
})
```

Layer on [reactive client primitives](https://neon.com/docs/introduction/reactivity), like type-safe live queries and optimistic mutations, to build fast, reactive apps directly on Lakebase Postgres.

## Next steps

- [Realtime overview](https://neon.com/docs/realtime/overview): what Realtime is and how to get started
- [Quickstart](https://neon.com/docs/realtime/quickstart): enable Realtime and run your first live queries
- [Defining queries](https://neon.com/docs/realtime/guides/queries): define and seal live queries in your backend
- [Subscribing to queries](https://neon.com/docs/realtime/guides/subscribing): subscribe to sealed queries from your app or agent
- [Live SQL API](https://neon.com/docs/realtime/reference/api): the API that serves live queries to clients

--- [Document source](https://neon.com/docs/introduction/manage-billing.md) ---

> Summary: The Neon Billing page in the Neon Console centralizes account billing actions: viewing charges to date, updating payment methods and billing email, downloading invoices, and upgrading or downgrading plans. Use it to stop monthly charges by switching to the Free plan, fix a failed payment, or request billing support (available on paid plans only). Legacy Enterprise plan downgrades require a support ticket. Indian customers must pay invoices manually because Stripe does not support e-Mandate recurring payments in India.

# Manage billing

Invoices, payment methods, changing your plan, and other actions around managing your bill

Last updated: 2026-10-27

**What you will learn:**

- How to access the Billing page
- How to update payment method, billing email, and billing details
- How to download invoices
- How to pay an invoice manually
- How to request billing support
- How to change plans
- How to prevent further monthly charges
- How to delete your account

**Related topics**

- [Neon plans](https://neon.com/docs/introduction/plans)
- [Monitoring billing and usage](https://neon.com/docs/introduction/monitor-usage)
- [Support](https://neon.com/docs/introduction/support)

## View the Billing page

You can view and manage billing from the **Billing** page in the Neon Console.

To access your **Billing** page:

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu to view the charges to date.

The **Billing** page has a sidebar with **Billing summary** and **Payment info**. **Billing summary** shows **This month's summary**: your billing period, plan details (including **Change plan**), and **Charges to date**. **Payment info** shows how you pay, your billing email, and company or address details (see [Update your payment method](https://neon.com/docs/introduction/manage-billing#update-your-payment-method) and [Update billing details](https://neon.com/docs/introduction/manage-billing#update-billing-details-company-and-address)).

At the top of the page, **View/Pay invoices** opens your invoices, where you can download them or pay an outstanding invoice (see [Pay an invoice](https://neon.com/docs/introduction/manage-billing#pay-an-invoice)). If you are on a **paid** plan, **Request billing support** appears next to it (see [Request billing support](https://neon.com/docs/introduction/manage-billing#request-billing-support)).

## Update your payment method

The **Payment info** view explains that **charges are applied to your card on the first day of the month**.

To update your payment method:

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu.
4. In the sidebar, select **Payment info**.
5. In the **Payment method** card, select **Edit**.

If you are unable to update your payment method, please [contact support](https://neon.com/docs/introduction/support).

## Payment issues

### Missed payments

If an auto-debit payment transaction fails, Neon sends a request to update your payment method. You can also pay an outstanding invoice manually at any time from **View/Pay invoices** (see [Pay an invoice](https://neon.com/docs/introduction/manage-billing#pay-an-invoice)). Late fees and payment policies are described in the [Neon Platform Terms](https://neon.com/platform-terms).

### Failing payments for Indian customers

Neon's billing system uses **Stripe Checkout**, which does not currently support **e-Mandates** (a requirement from the Reserve Bank of India) (RBI) for automatic recurring payments. Because of this, customers in India cannot set up automatic monthly payments. In the event of a payment failure, please [contact support](https://neon.com/docs/introduction/support) to request a link to your invoice to complete the payment manually.

## Update your billing email

To update your billing email:

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu.
4. In the sidebar, select **Payment info**.
5. In the **Billing email** card, select **Edit**.

If you are unable to update your billing email, please [contact support](https://neon.com/docs/introduction/support).

## Update billing details (company and address)

To update the company name, address, postal or ZIP code, country, or VAT or tax ID shown on your account:

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu.
4. In the sidebar, select **Payment info**.
5. In the **Billing Info** card, select **Edit**.

If you are unable to update this information, please [contact support](https://neon.com/docs/introduction/support).

**Note:** Updating your billing details (company name, address, or tax or VAT ID) applies to invoices generated after the change. Invoices that were already issued keep the details they had when they were created.

## Invoices

A Neon invoice includes the charges and the amount due for the billing period. For an explanation of what you've been billed for, see [Usage metrics](https://neon.com/docs/introduction/plans#usage-metrics).

### Pay an invoice

Invoices are charged automatically to your payment method on the first day of the month. If an automatic payment didn't go through, organization admins (or the account owner on a personal account) can pay an outstanding invoice manually at any time.

To pay an invoice manually:

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu.
4. Select **View/Pay invoices**.
5. On an unpaid invoice, select **Pay invoice** to open its secure payment page and complete the payment.

**Note:** **Pay invoice** appears only on unpaid invoices, and only for organization admins (or the account owner on a personal account). Other members can view the invoice without the payment action. Paying an invoice manually settles it immediately instead of waiting for the automatic monthly charge.

### Download invoices

To download an invoice:

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu.
4. Select **View/Pay invoices**.
5. Find the invoice you want and open its actions menu, then select **Download**.

**Note:** When an invoice is paid, Neon's billing system sends a payment confirmation email to the address associated with the Neon account.

### Request billing support

If you have a question or problem with billing or an invoice, you can contact the billing team from the **Billing** page. This is available on **paid** plans.

#### From the Billing page header

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu.
4. Select **Request billing support**.
5. In the form, choose the **related invoice** (if you have invoices) and describe how we can help, then submit.

If you have no invoices yet, **Request billing support** may appear disabled with a short explanation.

#### From past invoices

1. On the **Billing** page, select **View/Pay invoices**.
2. For the invoice you care about, open the actions menu (`...`) and select **Request support**. The same form opens with that invoice pre-selected.

You can still use **Download** from the invoice menu to save a PDF. For other support paths (for example **Launch** plan limits on ticket topics), see [Support](https://neon.com/docs/introduction/support).

#### What billing support can and can't help with

Billing support can help with questions about a specific invoice or charge, refunds and credits, and questions about your plan or subscription.

Updating your billing details applies to new invoices only. Invoices that were already issued keep the company name, address, and tax or VAT ID they had when they were created, and Neon does not reissue or re-address a past invoice. Update your details on the Billing page so your future invoices reflect them.

## Change your plan

**Note: Restart required for new limits**

If you're upgrading your plan, your compute will only pick up the new plan limits (such as max compute size and project storage) after the compute restarts. See [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

To upgrade or downgrade your plan:

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu.
4. Select **Change plan**.

Changing your plan to one with lower usage allowances may affect the performance of your applications. To compare plan allowances, see [Neon plans](https://neon.com/docs/introduction/plans#plan-overview).

If you are downgrading your plan, you will be required to remove any projects, branches, or data that exceed your new plan allowances.

To downgrade from a **legacy Enterprise plan**, please open a support ticket. Cancellation of a legacy Enterprise plan is handled according to the Master Subscription Agreement (MSA) outlined in the Customer Agreement.

## How to prevent further monthly charges to your account

If you're on a Neon paid plan, you need to downgrade to the Free plan to avoid further monthly charges. You can do so from the [Billing](https://console.neon.tech/app/billing#change_plan) page in the Neon Console. Simply removing all Neon projects will **not** stop the monthly fee associated with your plan. You will continue to be invoiced until you downgrade to Free.

## Delete your account

If you would like to delete your Neon account entirely, please refer to the steps described here: [Deleting your account](https://neon.com/docs/manage/accounts#delete-account).

--- [Document source](https://neon.com/docs/introduction/monitor-active-queries.md) ---

> Summary: The Active Queries view in the Neon Console displays up to 100 currently running queries for a selected branch, compute, and database. It is backed by the `pg_stat_activity` Postgres system view. Inspect live query activity without writing SQL, or query `pg_stat_activity` directly via the Neon SQL Editor or psql for custom analysis. Completed queries do not persist in the view, and no active queries appear while a compute is scaled to zero.

# Monitor active queries

View and analyze running queries in your database

Last updated: 2026-06-05

You can monitor active queries for your Neon project from the **Monitoring** page in the Neon Console.

1. In the Neon Console, select a project.
2. Go to **Monitoring**.
3. Select the **Active queries** tab.

The **Active queries** view displays up to 100 currently running queries for the selected **Branch**, **Compute**, and **Database**. Use the **Refresh** button to update the list with the latest active queries.

![Neon active queries tab](https://neon.com/docs/introduction/active_queries.png)

The **Active queries** view is powered by the `pg_stat_activity` Postgres system view, which is available in Neon by default. To run custom queries against the data collected by `pg_stat_activity`, you can use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any SQL client, such as [psql](https://neon.com/docs/connect/query-with-psql-editor).

For details on `pg_stat_activity`, see [pg_stat_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) in the PostgreSQL documentation.

**Note: active queries retention**

In Neon, the `pg_stat_activity` system view only holds data on currently running queries. Once a query completes, it no longer appears in the **Active queries** view. If your Neon compute scales down to zero due to inactivity, there will be no active queries until a new connection is established and a query is run.

--- [Document source](https://neon.com/docs/introduction/monitor-logs.md) ---

> Summary: Logs for Functions, Object Storage, and Realtime live on the Monitoring page, split across the Functions, Storage, and Realtime tabs (one viewer per service, no combined view). Filter by level (DEBUG, INFO, NOTICE, WARN, ERROR, FATAL) or service name, search log bodies, poll for new lines with Go live, and download the current view as a .log file.

# Monitor logs

View, search, and download logs for Functions, Object Storage, and Realtime

Last updated: 2026-11-06

The Monitoring page shows service logs in three tabs: **Functions**, **Storage**, and **Realtime**. Each tab is a log viewer for that service on the current branch; there is no combined, all-services view. The tabs share the same controls, described below. The **Realtime** tab appears only on branches where [Realtime](https://neon.com/docs/realtime/overview) is available.

## View logs

1. In the Neon Console, select a project and branch.
2. Go to **Monitoring**.
3. Open the **Functions**, **Storage**, or **Realtime** tab.

Each tab shows logs from every function or bucket on the branch. Narrow to a single service with the service name field (see [Scope by service](https://neon.com/docs/introduction/monitor-logs#scope-by-service)).

You can also jump straight to a service's tab without visiting Monitoring first:

- From the **Functions** list, open a function's menu and select **View logs**.
- From the Object Storage **bucket** list, open a bucket's menu and select **View logs**.

Both land you on the matching tab.

Each row shows a timestamp, a level, and the log message. Expand a row to see its full context: `timestamp`, `severity`, `entity_type`, `scope_name`, and `service_name`. `entity_type` identifies the kind of service a line came from (`function` or `storage`); `service_name` identifies the specific one (`neon-function/<slug>` or `neon-storage/<bucket>`).

For what these fields mean for a given service, and how each service maps its own output onto the shared level set, see [Function logs](https://neon.com/docs/compute/functions/logs) or [Object Storage logs](https://neon.com/docs/storage/logs).

## Scope by service

Use the service name field to narrow the view to one function or bucket. It matches a substring by default; click the `~`/`=` toggle next to it to switch to an exact match on the full name.

## Log levels

Every service reports logs on the same shared level set: `DEBUG`, `INFO`, `NOTICE`, `WARN`, `ERROR`, `FATAL`. Not every service emits every level. See the service-specific pages linked above for what each one actually produces.

## Filter and search

Use the level chips to show only the levels you care about, and the search box to match a literal, case-insensitive substring in the log body. Use the time-range chips (`5m`, `15m`, `1h`, `6h`, `24h`, `7d`) to change the query window.

If a query matches more than 1,000 lines, the view shows only the most recent 1,000 and displays a banner telling you to narrow the time range or add a search to see the rest.

If no logs match the current filters, the empty state offers a **Widen time range** button that expands the query window in one click.

## Go live

**Go live** polls for new log lines every 5 seconds; it isn't a push-based live tail. Toggle it off to stop polling and inspect a static view.

## Download

**Download** saves the log lines currently loaded in the view, exactly as filtered, to a plain-text `.log` file, newest first. Downloading doesn't re-run the query: it's a snapshot of what's on screen, so narrow your search, levels, and time range first if you want a smaller or more targeted file.

## Query logs from the CLI

The same branch logs are available from the terminal with [`neon logs query`](https://neon.com/docs/cli/logs), so you can filter and script against them without opening the Console:

```bash
neon logs query --since 30m
```

Combine filters like `--source`, `--service-name`, and `--severity-text`, or pass a raw `--logql` expression.

To read logs with a tool that speaks the Loki HTTP API, use the branch's [Loki-compatible read API](https://neon.com/docs/cli/logs#loki-read-api). [`neon logs loki`](https://neon.com/docs/cli/logs#loki) calls it from the terminal and prints its JSON response.

--- [Document source](https://neon.com/docs/introduction/monitor-pgadmin.md) ---

> Summary: pgAdmin 4 is an open-source Postgres management tool for monitoring real-time metrics including active sessions, transactions per second, tuple operations, and block I/O. Use it when you need a GUI-based dashboard to inspect live database activity without writing queries. Note that pgAdmin polls the database continuously, which prevents Neon compute from suspending. The system_stats extension required for the System Statistics tab is not supported on Neon.

# Monitor Neon with pgAdmin

Monitor your Lakebase Postgres database with pgAdmin

Last updated: 2026-09-16

pgAdmin is a database management tool for Postgres that supports various database tasks, including monitoring performance metrics.

![PgAdmin monitoring dashboard](https://neon.com/docs/introduction/pgadmin_monitor.png)

With pgAdmin, you can monitor real-time activity for a variety of metrics including:

- Active sessions (Total, Active, and Idle)
- Transactions per second (Transactions, Commits, Rollbacks)
- Tuples in (Inserts, Updates, Deletes)
- Tuples out (Fetched, Returned)
- Block I/O for shared buffers (see [Cache your data](https://neon.com/docs/postgresql/query-performance#cache-your-data) for information about Neon's compute cache)
- Database activity (Sessions, Locks, Prepared Transactions)

**Note: Notes**

Neon currently does not support the `system_stats` extension required to use the **System Statistics** tab in pgAdmin. It's also important to note that pgAdmin, while active, polls your database for statistics, which does not allow your compute to suspend as it normally would when there is no other database activity.

## How to install pgAdmin

Pre-compiled and configured installation packages for pgAdmin 4 are available for different desktop environments. For installation instructions, refer to the [pgAdmin deployment documentation](https://www.pgadmin.org/docs/pgadmin4/latest/deployment.html). Downloads can be found on the [PgAdmin Downloads](https://www.pgadmin.org/download/) page.

## How to connect to your database from pgAdmin

Find the connection string for your database by clicking the **Connect** button in the Console nav.

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

Enter your connection details as shown [here](https://neon.com/docs/connect/connect-postgres-gui#connect-to-the-database).

Neon uses the default Postgres port: `5432`

--- [Document source](https://neon.com/docs/introduction/monitor-pghero.md) ---

> Summary: PgHero is an open-source Postgres performance dashboard that surfaces long-running queries, tables needing vacuuming, duplicate or missing indexes, and per-user connection counts through a browser UI. Connect PgHero to a Lakebase Postgres database via Docker and a Neon connection string, with pg_stat_statements enabled as a prerequisite. Agent-based monitoring tools that require host-level installation are not supported by Neon. PgHero runs externally and connects over the standard Postgres protocol.

# Monitor Neon with PgHero

Monitor your Lakebase Postgres database with PgHero

Last updated: 2026-11-04

[PgHero](https://github.com/pghero/pghero) is an open-source performance tool for Postgres that can help you find and fix data issues, using a dashboard interface.

A quick look at the interface gives you an idea of what you'll find in PgHero.

![PgHero Dashboard](https://neon.com/docs/introduction/pg_hero.png)

Among other things, you can use PgHero to:

- Identify long-running queries
- Identify tables that require vacuuming
- Identify duplicate or missing indexes
- View connections by database and user
- Explain, analyze, and visualize queries

**Note:** Neon does not currently support monitoring tools or platforms that require installing an agent on the Postgres host system, but please keep an eye on our [roadmap](https://neon.com/docs/introduction/roadmap) for future integrations that enable these monitoring options.

## How to install PgHero

PgHero supports installation with [Docker](https://github.com/ankane/pghero/blob/master/guides/Docker.md), [Linux](https://github.com/ankane/pghero/blob/master/guides/Linux.md), and [Rails](https://github.com/ankane/pghero/blob/master/guides/Rails.md). Here, we'll show how to install PgHero with Docker and connect it to a Neon database.

Before you begin:

- Ensure that you have the [pg_stat_statements](https://neon.com/docs/extensions/pg_stat_statements) extension installed. PgHero uses it for query stats.
- Ensure that you have Docker installed. See [Install Docker Engine](https://docs.docker.com/engine/install/) for instructions.

PgHero is available on [DockerHub](https://hub.docker.com/r/ankane/pghero/). To install it, run:

```
docker pull ankane/pghero
```

## How to connect to your database from PgHero

Find the connection string for your database by clicking the **Connect** button in the Console nav.

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

Finally, run this command, replacing `$NEON_DB` with your Neon database connection string.

```
docker run -ti -e DATABASE_URL="$NEON_DB" -p 8080:8080 ankane/pghero
```

Then visit [http://localhost:8080](http://localhost:8080) in your browser to open the PgHero Dashboard.

--- [Document source](https://neon.com/docs/introduction/monitor-query-performance.md) ---

> Summary: The Query performance tab in the Neon Console Monitoring page displays the top previously run queries for a branch, compute, and database, grouped by normalized form and sortable by frequency or average execution time. Use it to identify slow or high-frequency queries without installing any extensions, since the view is built on the `pg_stat_statements` extension installed on a system-managed database. Query history resets whenever the Neon compute suspends or restarts, including after scaling to zero due to inactivity.

# Monitor query performance

View and analyze query performance for your Neon database

Last updated: 2026-07-22

You can monitor query history for your Neon project from the **Monitoring** page in the Neon Console.

1. In the Neon Console, select a project.
2. Go to **Monitoring**.
3. Select the **Query performance** tab.

The **Query performance** view shows the top 100 previously run queries for the selected **Branch**, **Compute**, and **Database**. Queries are grouped by their normalized form, with identical queries shown as a single row with a **Frequency** column indicating the number of times that query has been executed. Queries can be sorted by **Frequency** or **Average time**. Use the **Refresh** button to load the latest queries.

![Neon query performance tab](https://neon.com/docs/introduction/query_performance.png)

The **Query performance** view is powered by the `pg_stat_statements` Postgres extension, installed on a system managed database in your Postgres instance. Query history includes all queries run against your database, regardless of where they were issued from (Neon SQL Editor, external clients, or applications).

**Note: Query history when compute restarts**

In Neon, data collected by the `pg_stat_statements` extension is not retained when your Neon compute (where Postgres runs) is suspended or restarted. For example, if your compute scales down to zero due to inactivity, your query history is lost. New data will be gathered once your compute restarts.

## Running your own queries

To run your own queries on `pg_stat_statements` data, you can install the `pg_stat_statements` extension to your database and run your queries from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any SQL client, such as [psql](https://neon.com/docs/connect/query-with-psql-editor). For details on `pg_stat_statements`, including how to install it, what data it collects, and queries you can run, refer to our [pg_stat_statements](https://neon.com/docs/extensions/pg_stat_statements) extension guide.

You can also get this data from the terminal with [`neon inspect db outliers`](https://neon.com/docs/cli/inspect#db-outliers) and [`neon inspect db calls`](https://neon.com/docs/cli/inspect#db-calls).

--- [Document source](https://neon.com/docs/introduction/monitor-usage.md) ---

> Summary: Neon exposes billing and usage data at three levels in the Console: the Billing page (account-level charges and plan summary), the Projects page (org-level compute, storage, history, and network transfer), and the Project dashboard (the same metrics for a single project, updated with up to one hour delay). Use this page to locate current charges or check plan usage before an invoice arrives. On usage-based plans (Launch, Scale, Agent, Enterprise), the project consumption metrics API returns the same metrics programmatically.

# Monitor billing and usage

Where to see usage and costs in the Console and via the API

Last updated: 2026-10-09

You can monitor usage and costs in the Neon Console or programmatically with the Neon API. For what each metric means and how it maps to your invoice, see [Usage metrics](https://neon.com/docs/introduction/plans#usage-metrics) and [Invoice metrics](https://neon.com/docs/introduction/plans#invoice-metrics) on the Plans page.

## View usage in the Neon Console

Neon exposes usage in three places in the Console: the **Billing** page (account-level charges and plan summary), the **Projects** page (org-level usage metrics), and the project's **Overview** page (project-level usage metrics when you are inside a project).

### Billing page

From the **Billing** page (Organization → **Billing** in the Neon Console) you see account-level information: this month's summary including current plan, included features, usage-based pricing, and **charges to date**. Invoice line items appear only when there is a charge for that metric.

To open the Billing page:

1. Navigate to the Neon Console.
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing**.

### Projects page

From the **Projects** page (Organization → **Projects**) you see an org-level summary of four metrics across all projects: **Compute**, **Storage**, **History**, and **Network transfer**.

### Project overview

When you open a project, the **Usage** panel on the **Overview** page shows the same four metrics for that project only: **Compute**, **Storage**, **History**, and **Network transfer**.

Usage is shown since the start of the current billing period. Metrics may be delayed by about an hour and are not updated for inactive projects.

**Note:** Network transfer metrics only appear on the Billing page when your usage exceeds the included allowance for your plan. To track network transfer before it results in charges, check the account usage panel on the **Projects** page, which always displays current usage. You can also monitor programmatically with the [Consumption API](https://neon.com/docs/guides/consumption-metrics). For more on network transfer, see [Network transfer](https://neon.com/docs/introduction/network-transfer).

**Note: Billing metrics for pre-2025 custom contract customers**

If you signed a contract with Neon prior to 01/01/2025, different billing metrics apply:

- **Storage** is measured in GiBs instead of [GB-month](https://neon.com/docs/reference/glossary#gb-month), and if you exceed your contract's monthly storage allowance, extra storage units are automatically allocated and billed. Extra storage charges are applied based on the number of additional storage units needed to cover peak storage usage during the current billing period, prorated from the date the extra storage was allocated. Peak usage resets at the beginning of the next billing period.
- **Written data** is the total volume of data written from compute to storage during the monthly billing period, measured in gibibytes (GiB).

If you have questions or want to change the billing metrics defined in your contract, contact your Neon sales representative.

## Retrieve usage with the API

On **usage-based plans** (Launch, Scale, Agent, and Enterprise), use the **project consumption metrics** API. It returns metrics that align with usage-based billing and match your invoice.

See [Querying consumption metrics](https://neon.com/docs/guides/consumption-metrics) for the endpoint, required and optional parameters, example requests and responses, pagination, polling behavior, and building usage dashboards. For a guide to converting the raw API values into billing units and calculating your costs, see [Usage and cost calculations](https://neon.com/docs/introduction/usage-calculations).

**Tip: Optimize your costs**

For strategies to reduce your Neon costs across compute, storage, branches, and data transfer, see [Cost optimization](https://neon.com/docs/introduction/cost-optimization).

--- [Document source](https://neon.com/docs/introduction/monitoring-page.md) ---

> Summary: The Monitoring dashboard in the Neon console shows real-time graphs for RAM, CPU, connection counts, database size, deadlocks, row changes, replication delay, and cache hit rate. Use it to interpret each metric, diagnose connection saturation, cache misses, or replication lag, and decide whether to scale up or enable pooling. Historical data retention depends on your plan.

# Monitoring dashboard

Last updated: 2026-09-25

The **Monitoring** dashboard in the Neon console provides several graphs for monitoring system and database metrics. You can access the **Monitoring** dashboard from the sidebar in the Neon Console.

The Monitoring page is organized into **Postgres**, **Storage**, **Functions**, and **Realtime** tabs. This page describes the **Postgres** tab, which holds the metrics graphs below along with the **Active queries**, **Query performance**, **Data API Advisors**, and **System operations** views. The **Storage**, **Functions**, and **Realtime** tabs show [logs](https://neon.com/docs/introduction/monitor-logs) for Object Storage, Functions, and Realtime.

Your Neon plan defines the range of data you can view.

| Neon Plan | Data Access |
| --------- | ----------- |
| Free      | 1 day       |
| Launch    | 3 days      |
| Scale     | 14 days     |

You can select different periods or a custom period within the permitted range from the menu on the dashboard.

The dashboard displays metrics for the selected branch and compute. Choose the branch from the project/branch menu at the top of the sidebar, and use the **Compute** drop-down on the page to switch computes. Use the **Refresh** button to update the displayed metrics.

If your compute was idle or there has not been much activity, graphs may display this message: `There is no data to display at the moment`. In this case, try selecting a different time period or returning later after more usage data has been collected.

All time values displayed in graphs are in [Coordinated Universal Time (UTC)](https://en.wikipedia.org/wiki/Coordinated_Universal_Time).

**Note: Endpoint Inactive: What does it mean?**

The values and plotted lines in your graphs will drop to `0` when your compute is inactive because a compute must be active to report data. These inactive periods are also shown as a diagonal line pattern in the graph, as shown here:

![monitoring graph diagonal pattern for inactive compute](https://neon.com/docs/introduction/monitor_inactive.png)

## RAM

![Monitoring page RAM graph](https://neon.com/docs/introduction/monitor_ram.png)

This graph shows allocated RAM and usage over time for the selected compute.

**ALLOCATED**: The amount of allocated RAM.

RAM is allocated according to the size of your compute or your [autoscaling](https://neon.com/docs/guides/autoscaling-guide) configuration, if applicable. For example, if your compute size is .25 CU (1 GB RAM), your allocated RAM is always 1 (GB). With autoscaling, allocated RAM increases and decreases as your compute size scales up and down in response to load. If [scale to zero](https://neon.com/docs/guides/scale-to-zero-guide) is enabled and your compute transitions to an idle state after a period of inactivity, allocated RAM drops to 0.

**Used**: The amount of RAM used.

The graph plots a line showing the amount of RAM used. If the line regularly reaches the maximum amount of allocated RAM, consider increasing your compute size to increase the amount of allocated RAM. To see the amount of RAM allocated for each Neon compute size, see [Compute size and autoscaling configuration](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration).

**Cached**: The amount of data cached in memory.

## CPU

![Monitoring page CPU graph](https://neon.com/docs/introduction/monitor_cpu.png)

This graph shows the amount of allocated CPU and usage over time for the selected compute.

**ALLOCATED**: The amount of allocated CPU.

CPU is allocated according to the size of your compute or your [autoscaling](https://neon.com/docs/guides/autoscaling-guide) configuration, if applicable. For example, if your compute size is .25 CU (1 GB RAM), your allocated CPU scales proportionally. With autoscaling, allocated CPU increases and decreases as your compute size scales up and down in response to load. If [scale to zero](https://neon.com/docs/guides/scale-to-zero-guide) is enabled and your compute transitions to an idle state after a period of inactivity, allocated CPU drops to 0.

**Used**: The amount of CPU used, in [Compute Units (CU)](https://neon.com/docs/reference/glossary#compute-unit-cu).

If the plotted line regularly reaches the maximum amount of allocated CPU, consider increasing your compute size. To see the compute sizes available with Neon, see [Compute size and autoscaling configuration](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration).

## Postgres connections count

![Monitoring page connections graph](https://neon.com/docs/introduction/monitor_connections.png)

The **Postgres connections count** graph shows the number of idle connections, active connections, and the total number of connections directly to your Postgres database over time for the selected compute. These are the actual connections on the Postgres server itself.

**ACTIVE**: The number of active connections for the selected compute.

Monitoring active connections can help you understand your database workload at any given time. If the number of active connections is consistently high, it might indicate that your database is under heavy load, which could lead to performance issues such as slow query response times. See [Connections](https://neon.com/docs/postgresql/query-reference#connections) for related SQL queries.

**IDLE**: The number of idle connections for the selected compute.

Idle connections are those that are open but not currently being used. While a few idle connections are generally harmless, a large number of idle connections can consume unnecessary resources, leaving less room for active connections and potentially affecting performance. Identifying and closing unnecessary idle connections can help free up resources. See [Find long-running or idle connections](https://neon.com/docs/postgresql/query-reference#find-long-running-or-idle-connections).

**TOTAL**: The sum of active and idle connections for the selected compute.

**MAX**: The maximum number of simultaneous connections allowed for your compute size.

The MAX line helps you visualize how close you are to reaching your connection limit. When your TOTAL connections approach the MAX line, you may want to consider:

- Increasing your compute size to allow for more connections
- Implementing [connection pooling](https://neon.com/docs/connect/connection-pooling), which supports up to 10,000 simultaneous connections
- Optimizing your application's connection management

The connection limit (defined by the Postgres `max_connections` setting) is set according to your Neon compute size configuration. For the connection limit for each Neon compute size, see [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

**Note:** If you're using [connection pooling](https://neon.com/docs/connect/connection-pooling), also monitor the [Pooler client connections](https://neon.com/docs/introduction/monitoring-page#pooler-client-connections) and [Pooler server connections](https://neon.com/docs/introduction/monitoring-page#pooler-server-connections) graphs. When using a pooled connection, the **Pooler server connections** represent the actual connections from PgBouncer to Postgres, while this **Postgres connections count** graph shows all direct connections to Postgres (including those from the pooler and any direct connections).

## Pooler client connections

![Pooler client connections graph](https://neon.com/docs/introduction/pooler_client_connections.png)

The **Pooler client connections** graph shows connections from your applications to Neon's PgBouncer connection pooler. This graph only displays data when you're using a [pooled connection string](https://neon.com/docs/connect/connection-pooling) (one that includes `-pooler` in the endpoint hostname).

PgBouncer supports up to 10,000 simultaneous client connections, which is significantly higher than the direct Postgres connection limit. The graph shows the following connection states:

**ACTIVE**: Client connections actively executing a query through the pooler.

These are connections that currently have an active query running. A high number of active connections indicates your application is actively using the database.

**WAITING**: Client connections waiting for an available server connection from the pool.

When all available server connections (connections from PgBouncer to Postgres) are in use, additional client requests must wait in a queue. If you consistently see a high number of waiting connections, it may indicate:

- Your workload requires more server connections than your current `default_pool_size` allows
- Long-running queries are holding server connections
- Your compute size may need to be increased to support more concurrent server connections

The graph also displays **Max wait**, which shows the maximum time (in seconds) that any client connection has been waiting for an available server connection. A consistently high max wait time indicates that clients are experiencing delays in getting database access, which could impact application performance

**ACTIVE CANCEL** and **WAITING CANCEL**: Connections in the process of being cancelled.

These represent client connections where a cancellation request has been issued (for example, when a user cancels a query).

**Tip:** Connection pooling works by allowing many client connections to share a smaller pool of actual Postgres connections. While you can have thousands of client connections, they share a limited number of server connections determined by PgBouncer's `default_pool_size` setting. For more details, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## Pooler server connections

![Pooler server connections graph](https://neon.com/docs/introduction/pooler_server_connections.png)

The **Pooler server connections** graph shows connections from Neon's PgBouncer pooler to your Postgres database. This graph only displays data when you're using a [pooled connection string](https://neon.com/docs/connect/connection-pooling) (one that includes `-pooler` in the endpoint hostname).

These server connections are shared by all client connections to the pooler, enabling thousands of clients to efficiently share a smaller pool of Postgres connections. The graph shows the following states:

**SERVER ACTIVE**: Server connections currently serving client queries.

These are the pooler's connections to Postgres that are actively processing queries from clients. This number represents the actual concurrent queries being executed on your Postgres database through the pooler.

**SERVER IDLE**: Server connections in the pool that are available but not currently in use.

PgBouncer maintains these idle connections in the pool so they're ready to handle new client requests without the overhead of establishing new connections. In transaction pooling mode (which Neon uses), connections are returned to the idle state as soon as a transaction completes.

The total number of server connections (active + idle) is limited by PgBouncer's `default_pool_size` setting, which is set to 0.9 × your compute's `max_connections`. For example:

- A 1 CU compute with `max_connections=450` can have up to 405 pooler server connections
- A 2 CU compute with `max_connections=901` can have up to 810 pooler server connections

**Note:**

The **Pooler server connections** count is a subset of what you see in the [Postgres connections count](https://neon.com/docs/introduction/monitoring-page#postgres-connections-count) graph. The Postgres connections count shows all connections to Postgres, including those from the pooler plus any direct (non-pooled) connections. To understand your complete connection picture when using pooling:

- **Pooler client connections**: Shows how many applications/clients are connected to the pooler
- **Pooler server connections**: Shows how many connections the pooler is using to Postgres (limited by `default_pool_size`)
- **Postgres connections count**: Shows all connections to Postgres (pooler connections + direct connections)

## Database size

![Monitoring page database size graph](https://neon.com/docs/introduction/monitor_data_size.png)

The **Database size** graph shows the logical data size (the size of your actual data) for the named database and the total size for all user-created databases (**All Databases**) on the selected branch. The **All Databases** metric is only shown when there is more than one database on the selected branch.

**Important:** Database size metrics are only displayed while your compute is active. When your compute is idle, database size values are not reported, and the **Database size** graph shows zero even though data may be present.

## Deadlocks

![Monitoring page deadlocks graph](https://neon.com/docs/introduction/monitor_deadlocks.png)

The **Deadlocks** graph shows a count of deadlocks over time for the named database on the selected branch. The named database is always the oldest database on the selected branch.

Deadlocks occur in a database when two or more transactions simultaneously block each other by holding onto resources the other transactions need, creating a cycle of dependencies that prevent any of the transactions from proceeding, potentially leading to performance issues or application errors. For lock-related queries you can use to investigate deadlocks, see [Performance tuning](https://neon.com/docs/postgresql/query-reference#performance-tuning). To learn more about deadlocks in Postgres, see [Deadlocks](https://www.postgresql.org/docs/current/explicit-locking.html).

## Rows

![Monitoring page rows graph](https://neon.com/docs/introduction/monitor_rows.png)

The **Rows** graph shows the number of rows deleted, updated, and inserted over time for the named database on the selected branch. The named database is always the oldest database on the selected branch. Row metrics are reset to zero whenever your compute restarts.

Tracking rows inserted, updated, and deleted over time provides insights into your database's activity patterns. You can use this data to identify trends or irregularities, such as insert spikes or an unusual number of deletions.

**Note:** Row metrics only capture row-level changes (`INSERT`, `UPDATE`, `DELETE`, etc.) and exclude table-level operations such as `TRUNCATE`.

## Replication delay bytes

![Replication delay bytes](https://neon.com/docs/introduction/rep_delay_bytes.png)

The **Replication delay bytes** graph shows the total size, in bytes, of the data that has been sent from the primary compute but has not yet been applied on the replica. A larger value indicates a higher backlog of data waiting to be replicated, which may suggest issues with replication throughput or resource availability on the replica. This graph is only visible when selecting a **Replica** compute from the **Compute** drop-down menu.

## Replication delay seconds

![Replication delay seconds](https://neon.com/docs/introduction/rep_delay_seconds.png)

The **Replication delay seconds** graph shows the time delay, in seconds, between the last transaction committed on the primary compute and the application of that transaction on the replica. A higher value suggests that the replica is behind the primary, potentially due to network latency, high replication load, or resource constraints on the replica. This graph is only visible when selecting a **Replica** compute from the **Compute** drop-down menu.

## Compute cache hit rate

![compute cache hit rate graph](https://neon.com/docs/introduction/compute_cache_hit_rate.png)

The **Compute cache hit rate** graph shows the percentage of read requests served from your [compute cache](https://neon.com/docs/reference/glossary#compute-cache) rather than from storage. Reads served from storage are more costly and can result in slower query performance. To learn more about how Neon caches data, see [Monitoring compute cache usage](https://neon.com/docs/extensions/neon#monitoring-compute-cache-usage).

## Working set size

![working set size graph](https://neon.com/docs/introduction/working_set_size.png)

Your working set is the size of the distinct set of Postgres pages (relation data and indexes) accessed in a given time interval - to optimize for performance and consistent latency it is recommended to size your compute so that the working set fits into your [compute cache](https://neon.com/docs/manage/computes#how-to-size-your-compute) for quick access.

The **Working set size** graph visualizes the amount of data accessed (calculated as unique pages accessed × page size) over a given interval. Here's how to interpret the graph:

- **5m** (5 minutes): This line shows the data accessed in the last 5 minutes.
- **15m** (15 minutes): Similar to the 5-minute window, this metric tracks the data accessed in the last 15 minutes.
- **1h** (1 hour): This line represents the data accessed in the last hour.
- **Compute cache size**: The size of your compute cache, determined by the size of your compute. Larger computes have larger caches. For cache sizes, see [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

For optimal performance your compute cache should be larger than your working set size for a given time interval. If your working set size is larger than the compute cache size it is recommended to increase the maximum size of the compute to improve the cache hit rate and achieve good performance.

If your workload pattern doesn't change much over time it is recommended to compare the 1h time interval working set size with the compute cache size and make sure that working set size is smaller than the compute cache size.

To read these values from the terminal, see [`neon inspect db working-set`](https://neon.com/docs/cli/inspect#db-working-set) and [`neon inspect db lfc-hit-rate`](https://neon.com/docs/cli/inspect#db-lfc-hit-rate).

--- [Document source](https://neon.com/docs/introduction/monitoring.md) ---

> Summary: Neon's monitoring hub links every observability tool for your databases: the built-in Monitoring dashboard, usage metrics, active queries, query performance, logs, and pg_stat_statements. Find the right tool for your need, from in-console visibility to external export for Datadog, Grafana Cloud, and New Relic.

# Monitoring in Neon

Learn about monitoring resources and metrics in Neon

Last updated: 2026-07-31

To find out what's going on with your Neon projects and databases, Neon offers several ways to track metrics and monitor usage.

- [Monitoring dashboard](https://neon.com/docs/introduction/monitoring-page): View system and database metrics on the Neon Monitoring dashboard
- [Monitor billing and usage](https://neon.com/docs/introduction/monitor-usage): Monitor billing and usage metrics for your Neon account and projects
- [Autoscaling](https://neon.com/docs/guides/autoscaling-guide#monitor-autoscaling): Monitor Autoscaling RAM usage
- [Neon system operations](https://neon.com/docs/manage/operations): Monitor Neon project operations from the Neon Console, API, or CLI
- [Active Queries](https://neon.com/docs/introduction/monitor-active-queries): View and analyze running queries in your database
- [Query performance](https://neon.com/docs/introduction/monitor-query-performance): View and analyze query performance for your Neon database
- [Logs](https://neon.com/docs/introduction/monitor-logs): View, search, and download logs across Functions and Object Storage
- [Data API Advisors](https://neon.com/docs/data-api/database-advisor): Detect Data API security and performance issues, in the console or via API
- [pg_stat_statements](https://neon.com/docs/extensions/pg_stat_statements): Monitor query performance and statistics in Postgres with pg_stat_statements

## Datadog integration

- [Datadog](https://neon.com/docs/guides/datadog): Export Neon Metrics to Datadog with the Neon Datadog Integration

## OpenTelemetry

- [OTel integration](https://neon.com/docs/guides/opentelemetry): Export Neon metrics to any OpenTelemetry-compatible observability platform
- [Grafana Cloud](https://neon.com/docs/guides/grafana-cloud): Export Neon metrics and logs to Grafana Cloud with native OTLP integration
- [Better Stack](https://neon.com/guides/betterstack-otel-neon): Monitor Neon with Better Stack using OpenTelemetry integration
- [New Relic](https://neon.com/guides/newrelic-otel-neon): Monitor Neon with New Relic using OpenTelemetry integration
- [Metrics and logs reference](https://neon.com/docs/reference/metrics-logs): Metrics and logs reference for monitoring

## Other monitoring tools

- [pgAdmin](https://neon.com/docs/introduction/monitor-pgadmin): Monitor your Lakebase Postgres database with pgAdmin
- [PgHero](https://neon.com/docs/introduction/monitor-pghero): Monitor your Lakebase Postgres database with PgHero

## Feedback and future improvements

At Neon, we understand that observability and monitoring are critical for running successful applications.

If you've got feature requests or feedback about what you'd like to see in Neon monitoring and observability features, let us know via the [Feedback](https://console.neon.tech/app/projects?modal=feedback) form in the Neon Console or our [feedback channel](https://discord.com/channels/1176467419317940276/1176788564890112042) on Discord.

--- [Document source](https://neon.com/docs/introduction/neon-and-lakebase.md) ---

> Summary: Lakebase Postgres is an OLTP database where storage and compute are separated and durable object storage is the source of truth. It runs in two places: on Neon, a complete backend for apps and agents built for developers, startups, and agent platforms, and on Databricks, the Data and AI platform for businesses. Same infrastructure, same technology, same core feature set. Use this page to understand the lakebase architecture and decide where to run it.

# Neon and Lakebase

How to choose where to run Lakebase Postgres

Last updated: 2026-08-03

In 2025, Neon joined Databricks. The serverless Postgres architecture that Neon pioneered is now the foundation of Lakebase Postgres, a database you can run in two places: on Neon and on Databricks. Wherever you run it, it's the same infrastructure, the same technology, and the same core feature set. What differs is what's built around the database. This page explains the [lakebase category](https://www.databricks.com/blog/what-is-a-lakebase), what's the same in both places, and how to choose between them.

## What is a lakebase?

![Standard database compared to lakebase. On the left, compute and storage live together on one machine and each replica keeps a full copy of the data. On the right, stateless Postgres compute runs in a layer separate from shared, durable object storage](https://neon.com/docs/introduction/database-vs-lakebase.svg)

At the broadest level, a lakebase is a type of OLTP database where storage and compute are separated and the source of truth for storage is cheap, durable object storage. That architectural choice has consequences that traditional Postgres deployments can't match:

- **Compute is stateless and elastic.** Because no compute node owns the data, compute can scale up under load, scale down when idle, and [scale to zero](https://neon.com/docs/introduction/scale-to-zero) entirely. Read replicas spin up without copying data.
- **History is cheap.** Object storage is inexpensive enough to retain a full history of changes, which makes [instant point-in-time restore](https://neon.com/docs/introduction/branch-restore) practical instead of a slow backup-and-restore exercise.
- **Copies are virtual.** [Branches](https://neon.com/docs/introduction/branching) are copy-on-write views over shared storage, so a full copy of your database for development, testing, or an agent workflow is created in seconds and costs nothing until it diverges.
- **Operational data is lake-native.** Data lives in the same storage layer as the lakehouse, so analytics and AI can reach it without ETL pipelines or fragile sync jobs.

## Where Lakebase Postgres runs

Lakebase Postgres is the Databricks implementation of a lakebase: Postgres, built on the architecture described above. It's available in two places:

- **On Neon**, as the database at the core of a complete backend for apps and agents: Postgres alongside [Auth](https://neon.com/docs/auth/overview), [Data API](https://neon.com/docs/data-api/overview), [Object Storage](https://neon.com/docs/storage/overview), [Functions](https://neon.com/docs/compute/functions/overview), and [AI Gateway](https://neon.com/docs/ai-gateway/overview).
- **On Databricks**, as [Lakebase](https://www.databricks.com/product/lakebase), an enterprise-grade Postgres database tightly integrated into the rest of the Databricks Data Intelligence Platform: Unity Catalog governance, lakehouse analytics, notebooks, and AI workflows.

The database itself doesn't change between them. What surrounds it differs, because Neon and Databricks serve different customers: Neon is built for developers, startups, and agent platforms; Databricks is the Data and AI platform for businesses.

|                         | Neon                                                                                                                                                                                                                          | Databricks                                                                                                                   |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **The database**        | Lakebase Postgres                                                                                                                                                                                                             | Lakebase Postgres                                                                                                            |
| **Integrated products** | [Auth](https://neon.com/docs/auth/overview), [Functions](https://neon.com/docs/compute/functions/overview), [Object Storage](https://neon.com/docs/storage/overview), [AI Gateway](https://neon.com/docs/ai-gateway/overview) | Lakehouse, Lakeflow, Unity Catalog, Unity AI Gateway, [all Databricks products](https://www.databricks.com/product/platform) |
| **What it is**          | A complete backend for apps and agents                                                                                                                                                                                        | The Data and AI platform for businesses                                                                                      |
| **Built for**           | Developers, startups, agent and codegen platforms                                                                                                                                                                             | Enterprises, data and AI teams, companies building on Databricks                                                             |
| **How teams use it**    | Build, iterate, preview, and deploy apps quickly                                                                                                                                                                              | Operate production-grade OLTP databases with tight integration to the data lake                                              |
| **Governance**          | Project-level access controls                                                                                                                                                                                                 | Lakehouse-wide governance via Unity Catalog                                                                                  |

## Core database features

Because Neon and Databricks run the same infrastructure, the core feature set is the same. The links below go to the Neon and Databricks documentation for the same underlying capability. Databricks availability is based on the [Lakebase documentation](https://docs.databricks.com/aws/en/oltp/projects/).

| Feature                             | On Neon                                                                | On Databricks                                                                                      |
| ----------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Branching**                       | [Branching](https://neon.com/docs/introduction/branching)              | [Branches](https://docs.databricks.com/aws/en/oltp/projects/branches)                              |
| **Autoscaling**                     | [Autoscaling](https://neon.com/docs/introduction/autoscaling)          | [Autoscaling](https://docs.databricks.com/aws/en/oltp/projects/autoscaling)                        |
| **Scale to zero**                   | [Scale to zero](https://neon.com/docs/introduction/scale-to-zero)      | [Scale to zero](https://docs.databricks.com/aws/en/oltp/projects/scale-to-zero)                    |
| **Read replicas**                   | [Read replicas](https://neon.com/docs/introduction/read-replicas)      | [Read replicas](https://docs.databricks.com/aws/en/oltp/projects/read-replicas)                    |
| **Instant restore (point-in-time)** | [Instant restore](https://neon.com/docs/introduction/branch-restore)   | [Point-in-time restore](https://docs.databricks.com/aws/en/oltp/projects/point-in-time-restore)    |
| **Connection pooling**              | [Connection pooling](https://neon.com/docs/connect/connection-pooling) | Built-in PgBouncer ([Connect](https://docs.databricks.com/aws/en/oltp/projects/connect))           |
| **Data API (REST)**                 | [Data API](https://neon.com/docs/data-api/overview)                    | [Lakebase Data API](https://docs.databricks.com/aws/en/oltp/projects/data-api)                     |
| **Management API**                  | [Neon API](https://neon.com/docs/reference/api)                        | [Lakebase API guide](https://docs.databricks.com/aws/en/oltp/projects/api-usage)                   |
| **CLI**                             | [Neon CLI](https://neon.com/docs/cli/install)                          | [Databricks CLI for Lakebase](https://docs.databricks.com/aws/en/oltp/projects/cli)                |
| **Terraform**                       | [Terraform provider](https://neon.com/docs/reference/terraform)        | [Terraform for Lakebase](https://docs.databricks.com/aws/en/oltp/projects/automate-with-terraform) |
| **MCP server**                      | [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server)            | [MCP on Databricks](https://docs.databricks.com/aws/en/generative-ai/mcp/managed-mcp)              |

## Features around the database

The features around the database are where Neon and Databricks diverge, because each is designed for a different customer. Neon leans into developer workflow and the backend services apps and agents need; Databricks leans into enterprise operations, governance, and integration with the rest of the Data Intelligence Platform.

| Feature                                              | On Neon                                                                                                            | On Databricks                                                                                                                              |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **High availability**                                | Coming soon ([Roadmap](https://neon.com/docs/introduction/roadmap))                                                | Yes ([High availability](https://docs.databricks.com/aws/en/oltp/projects/manage-high-availability))                                       |
| **Cross-cloud disaster recovery (DR)**               | Not available                                                                                                      | Private preview                                                                                                                            |
| **Managed user authentication**                      | Yes ([Managed Better Auth](https://neon.com/docs/auth/overview))                                                   | Not yet; database access uses Databricks identity and Postgres roles ([Connect](https://docs.databricks.com/aws/en/oltp/projects/connect)) |
| **GitHub integration**                               | Yes ([GitHub integration](https://neon.com/docs/guides/neon-github-integration))                                   | Via GitHub Actions ([GitHub Actions](https://docs.databricks.com/aws/en/dev-tools/ci-cd/github))                                           |
| **Private networking (Private Link)**                | Yes ([Private Networking](https://neon.com/docs/guides/neon-private-networking))                                   | Yes ([Data protection](https://docs.databricks.com/aws/en/oltp/projects/private-link))                                                     |
| **Metrics and logs export (Datadog, OpenTelemetry)** | Yes ([Datadog](https://neon.com/docs/guides/datadog), [OpenTelemetry](https://neon.com/docs/guides/opentelemetry)) | Via the Databricks platform                                                                                                                |
| **HIPAA compliance**                                 | Yes ([HIPAA](https://neon.com/docs/security/hipaa))                                                                | Yes, via Databricks ([HIPAA](https://docs.databricks.com/aws/en/security/privacy/hipaa))                                                   |
| **SOC 2**                                            | Yes ([Compliance](https://neon.com/docs/security/compliance))                                                      | Yes, via Databricks ([SOC](https://www.databricks.com/trust/compliance/soc))                                                               |
| **Vercel Marketplace**                               | Yes ([Vercel integration](https://neon.com/docs/guides/vercel-overview))                                           | Not yet                                                                                                                                    |
| **Vercel Integration**                               | Yes ([Vercel-Managed integration](https://neon.com/docs/guides/vercel-managed-integration))                        | Not yet                                                                                                                                    |

## How to choose

You get the same database either way, so the decision comes down to what you need around it and how your team works.

**Choose Neon if:**

- You're a developer looking for a hands-off Postgres to power side projects, experiments, or personal apps without setup friction or infrastructure management
- You're a startup focused on shipping quickly and want a complete backend, database included, that keeps up without slowing your team down
- You're a small team iterating fast, using branching and previews to accelerate the software lifecycle and deploy safely
- You're building an agent or codegen platform (like Replit, Lovable, or Bolt) and need to spin up and manage fleets of databases efficiently, with costs that stay under control through usage-based pricing and scale to zero

**Choose Databricks if:**

- You're building on the Databricks Data Intelligence Platform
- You're running data-intensive or AI-driven applications where unified governance, lineage, and access control across OLTP and analytical data are essential
- You're a data or AI team that needs operational data to be immediately available for analytics, notebooks, and ML workflows
- You're an enterprise team that highly values security, compliance, high availability, and platform-level integrations

## Provider and region availability

Neon runs on AWS. Lakebase Postgres on Databricks inherits the cloud reach of the Databricks platform, with availability that varies by provider. For the full, current region lists, follow the links below.

| Cloud provider | Neon                                                                                                             | Databricks                                                                                                              |
| -------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **AWS**        | Yes ([Neon regions](https://neon.com/docs/introduction/regions))                                                 | Yes, generally available ([AWS regions](https://docs.databricks.com/aws/en/oltp/projects/manage-projects#availability)) |
| **Azure**      | No, Azure support is being deprecated ([Neon regions](https://neon.com/docs/introduction/regions#azure-regions)) | Yes, in beta ([Azure regions](https://learn.microsoft.com/en-us/azure/databricks/oltp/projects/manage-projects))        |
| **GCP**        | Not available                                                                                                    | Yes, in beta ([GCP regions](https://docs.databricks.com/gcp/en/oltp/projects/manage-projects#availability))             |

**Tip: Keep exploring Lakebase**

See the [Lakebase docs](https://docs.databricks.com/aws/en/oltp), review the [latest updates to the Lakebase platform](https://www.databricks.com/blog/lakebase-holiday-update), explore [customer stories](https://www.databricks.com/product/lakebase#customer-stories), and [watch a demo](https://www.databricks.com/resources/demos/tours/appdev/databricks-lakebase?itm_data=demo_center).

--- [Document source](https://neon.com/docs/introduction/network-transfer.md) ---

> Summary: Network transfer (egress) in Neon counts all outbound data through the Neon proxy, with per-plan monthly allowances and overage rates. Use this page to diagnose high egress costs from large result sets, pg_dump exports, or logical replication syncs, and to monitor usage via the Console or Consumption API. Reduction strategies include scoping SELECT columns, using Neon snapshots, adding replication filters, and routing traffic over Private Link.

# Reduce network transfer costs

Monitor and reduce data egress costs

Last updated: 2026-11-02

Network transfer is one of the usage metrics that affects your Neon bill. This guide explains what network transfer is, what causes it to increase, how to monitor it, and how to reduce it. For broader cost guidance, see [Cost optimization](https://neon.com/docs/introduction/cost-optimization). For plan allowances and pricing, see [Plans](https://neon.com/docs/introduction/plans).

## What is network transfer?

Neon measures data sent from your databases through the [Neon proxy](https://neon.com/docs/introduction/architecture-overview) to clients. All PostgreSQL connections pass through the proxy, including pooled and direct connections, primary computes, and [read replicas](https://neon.com/docs/introduction/read-replicas). All outbound client traffic counts toward network transfer, also known as egress.

There are two types of network transfer:

- **Public network transfer**: Data sent over the public internet. [Logical replication](https://neon.com/docs/guides/logical-replication-neon) to any destination counts as public network transfer.
  - **Free plan**: 5 GB per project per month included. Exceeding this suspends your compute until the next billing cycle or you upgrade.
  - **Launch / Scale plans**: 500 GB per project per month included, then $0.10/GB.
- **Private network transfer**: Traffic routed over AWS PrivateLink. Available on the Scale plan only. Billed at $0.01/GB, bi-directional. Unlike public network transfer, which only counts outbound data, private network transfer counts traffic in both directions: data sent from your database to clients and data sent from clients to your database.

In the Console, these appear as **Public network transfer** and **Private network transfer**. In the Consumption API, the fields are `public_network_transfer_bytes` and `private_network_transfer_bytes`. In project and branch detail API responses, the combined field is `data_transfer_bytes`.

## What causes high network transfer?

The following are common causes of increased network transfer in Neon. See [How to monitor](https://neon.com/docs/introduction/network-transfer#how-to-monitor-network-transfer) to identify these patterns and [How to reduce](https://neon.com/docs/introduction/network-transfer#how-to-reduce-network-transfer) for solutions.

**Large query result sets.** Using `SELECT *`, fetching entire tables without `LIMIT`, missing pagination, or joins that unintentionally multiply rows sends more data than your application needs. ORM defaults can also pull more rows or columns than necessary. This includes queries against [read replicas](https://neon.com/docs/introduction/read-replicas), which pass through the same proxy and count toward network transfer.

**High-frequency repeated queries.** Querying the database on every page render or API request without caching transfers the same data repeatedly. This is common in serverless environments where each invocation starts fresh. Check the `calls` column in `pg_stat_statements` to spot these patterns (see [Diagnosing a spike](https://neon.com/docs/introduction/network-transfer#diagnosing-a-spike)).

**Database exports (pg_dump).** Full database dumps transfer the entire database over the network. Running frequent scheduled dumps multiplies the total. Compression flags like `-Fc` do not reduce the data sent from Neon because compression happens client-side after transfer.

**Logical replication.** Replicating data to external destinations produces a continuous outbound stream. Initial table syncs can create large one-time spikes.

**Log export.** Sending Postgres logs to [Datadog](https://neon.com/docs/guides/datadog), [Grafana Cloud](https://neon.com/docs/guides/grafana-cloud), or [OpenTelemetry](https://neon.com/docs/guides/opentelemetry) collectors counts toward network transfer. Logs contain metadata rather than row data, so the volume is typically small relative to other causes.

## How to monitor network transfer

**Important:** The Billing page only displays network transfer when usage exceeds the included allowance. To track usage before it results in charges, check the usage panel on the organization **Projects** page or the project **Overview** page, or use the Consumption API.

Paid plans receive a weekly usage report by email that includes network transfer usage and cost.

### Console organization page

The usage panel on the organization **Projects** page always displays current network transfer usage across all projects. Each project's **Overview** page shows network transfer for that project.

![Organization page usage panel showing network transfer](https://neon.com/docs/introduction/dashboard_org_usage.png)

### Console Billing page

Navigate to **Organization > Billing** to see **Public network transfer** and **Private network transfer**. These metrics only appear when your usage exceeds the included allowance and there is an overage charge. For more on the Billing page, see [Monitor billing and usage](https://neon.com/docs/introduction/monitor-usage).

![Billing page showing network transfer charges](https://neon.com/docs/introduction/dashboard_org_billing.png)

### Consumption API for paid plans

**Tip:** On the Free plan? Skip to [Project and branch detail APIs](https://neon.com/docs/introduction/network-transfer#project-and-branch-detail-apis) for an API option available on all plans.

The [`/consumption_history/v2/projects`](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project-v2) endpoint provides programmatic access to network transfer metrics on paid plans.

It supports three granularity levels:

| Granularity | Maximum time range |
| ----------- | ------------------ |
| `hourly`    | Last 7 days        |
| `daily`     | Last 60 days       |
| `monthly`   | Last year          |

Use `hourly` granularity to diagnose recent spikes. Data updates approximately every 15 minutes.

**Tip:** Consumption API calls do not wake suspended computes, so polling does not increase your compute usage.

The following example retrieves hourly public and private network transfer for all projects in an organization over a six-day window:

```bash
curl --request GET \
  --url 'https://console.neon.tech/api/v2/consumption_history/v2/projects?org_id=$ORG_ID&from=2026-02-01T00:00:00Z&to=2026-02-07T00:00:00Z&granularity=hourly&metrics=public_network_transfer_bytes,private_network_transfer_bytes' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $NEON_API_KEY'
```

<details>

<summary>Response body (partial)</summary>

The response returns one entry per hour for each project, with the requested metrics in each hourly bucket. Metrics with no usage are omitted from the response.

```json
{
  "projects": [
    {
      "project_id": "delicate-dawn-54854667",
      "periods": [
        {
          "period_id": "90c7f107-3fe7-4652-b1da-c61f71043128",
          "period_plan": "launch",
          "period_start": "2026-02-02T18:04:52Z",
          "consumption": [
            {
              "timeframe_start": "2026-02-04T00:00:00Z",
              "timeframe_end": "2026-02-04T01:00:00Z",
              "metrics": [
                {
                  "metric_name": "public_network_transfer_bytes",
                  "value": 8347291
                }
              ]
            },
            {
              "timeframe_start": "2026-02-04T01:00:00Z",
              "timeframe_end": "2026-02-04T02:00:00Z",
              "metrics": [
                {
                  "metric_name": "public_network_transfer_bytes",
                  "value": 1203477
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "cursor": "delicate-dawn-54854667"
  }
}
```

</details>

For full details on parameters, pagination, and polling, see [Querying consumption metrics](https://neon.com/docs/guides/consumption-metrics).

### Project and branch detail APIs

The `data_transfer_bytes` field on the [Get project details](https://neon.com/docs/reference/api/projects/get-project) and [Get branch details](https://neon.com/docs/reference/api/branches/get-project-branch) endpoints returns a running total of network transfer for the current billing period. Unlike the [Consumption API](https://neon.com/docs/introduction/network-transfer#consumption-api-for-paid-plans), which provides time-windowed breakdowns, this value resets at the start of each billing cycle and is not broken down by hour or day. These endpoints are available on all plans.

**Get project details:**

```bash
curl --request GET \
  --url https://console.neon.tech/api/v2/projects/$PROJECT_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $NEON_API_KEY'
```

The response includes `data_transfer_bytes` in the project object:

```json
{
  "project": {
    "data_transfer_bytes": 40821459,
    ...
  }
}
```

**Get branch details:**

```bash
curl --request GET \
  --url https://console.neon.tech/api/v2/projects/$PROJECT_ID/branches/$BRANCH_ID \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $NEON_API_KEY'
```

The response includes `data_transfer_bytes` in the branch object:

```json
{
  "branch": {
    "data_transfer_bytes": 40820887,
    ...
  }
}
```

### Diagnosing a spike

Neon does not provide per-query or per-connection network transfer breakdowns. To identify the source of a spike, use `hourly` granularity from the Consumption API to narrow down the time window, then correlate it with known operations: scheduled `pg_dump` jobs, logical replication initial syncs, application deployments, or changes to query patterns. If you have multiple projects, compare per-project hourly data to isolate which project is responsible. On the Free plan, compare `data_transfer_bytes` across branches using the branch detail API to identify which branch contributes the most. Once you identify the branch, connect to it and run the `pg_stat_statements` queries below to find the top queries.

To find which queries return the most rows, use the [`pg_stat_statements`](https://neon.com/docs/extensions/pg_stat_statements) extension. The `rows` column is not an exact byte count, but queries returning many rows or wide rows (TEXT, JSONB, BYTEA columns) are the most likely contributors to high network transfer.

**Total rows**

Queries that returned the most total rows across all executions:

```sql
SELECT
  query,
  calls,
  rows AS total_rows,
  rows / calls AS avg_rows_per_call
FROM pg_stat_statements
WHERE calls > 0
ORDER BY rows DESC
LIMIT 10;
```

**Rows per execution**

Queries that return the most rows per execution, indicating poorly scoped SELECTs or missing pagination:

```sql
SELECT
  query,
  calls,
  rows AS total_rows,
  rows / calls AS avg_rows_per_call
FROM pg_stat_statements
WHERE calls > 0
ORDER BY avg_rows_per_call DESC
LIMIT 10;
```

**Most frequent**

Queries called most often, which compound transfer through volume:

```sql
SELECT
  query,
  calls,
  rows AS total_rows,
  rows / calls AS avg_rows_per_call
FROM pg_stat_statements
WHERE calls > 0
ORDER BY calls DESC
LIMIT 10;
```

**Longest running**

Queries consuming the most total execution time. Not a direct measure of network transfer, but helps identify problem queries during a spike window:

```sql
SELECT
  query,
  calls,
  rows AS total_rows,
  round(total_exec_time::numeric, 2) AS total_exec_time_ms,
  round((total_exec_time / calls)::numeric, 2) AS avg_exec_time_ms
FROM pg_stat_statements
WHERE calls > 0
ORDER BY total_exec_time DESC
LIMIT 10;
```

**Tip:** In Neon, [scaling to zero](https://neon.com/docs/introduction/scale-to-zero) clears [`pg_stat_statements`](https://neon.com/docs/extensions/pg_stat_statements) data, so computes that recently woke up already have fresh statistics. For long-running computes, run `SELECT pg_stat_statements_reset();` to start a clean measurement window. This cannot be undone and resets stats for all database roles.

For wire-level analysis of exact message sizes, see [Elephantshark](https://neon.com/blog/elephantshark-monitor-postgres-network-traffic), an open-source Postgres traffic monitor from Neon.

## How to reduce network transfer

For broader cost reduction strategies across all billing metrics, see [Cost optimization](https://neon.com/docs/introduction/cost-optimization).

**Optimize query results.** Select only the columns you need. Use pagination (`LIMIT`/`OFFSET` or cursor-based) instead of fetching all rows at once. Use SQL aggregations (`SUM`, `COUNT`, `GROUP BY`) to summarize data in the database rather than returning raw rows to your application.

**Reduce pg_dump frequency.** Use [Neon snapshots](https://neon.com/docs/guides/backup-restore) with [scheduled backups](https://neon.com/docs/guides/backup-restore#create-backup-schedules) as a backup alternative that keeps data within Neon. Reserve `pg_dump` for migrations or situations that require an external copy. When you do run `pg_dump`, use `-t` to dump only specific tables, `--exclude-table` to skip large ones, or `--schema-only` if you only need the schema. Note that compression flags (`-Fc`, `-Z`) compress the output file on the client after the data has already been sent from Neon, so they do not reduce your billed network transfer.

**Manage logical replication.** Initial table syncs can produce large spikes in network transfer. Dropping and re-creating a replication slot forces a new full sync, so avoid resetting slots as a troubleshooting step unless necessary. Replicate only the tables or columns you need by using row filters (WHERE clauses) and column lists on [`CREATE PUBLICATION`](https://www.postgresql.org/docs/current/sql-createpublication.html) (PostgreSQL 15+). Monitor replication lag and throughput to understand ongoing transfer volume.

**Use Private Link for internal traffic.** If your application runs in AWS, [Private Networking](https://neon.com/docs/guides/neon-private-networking) (Scale plan) routes traffic over PrivateLink at $0.01/GB instead of $0.10/GB for public network transfer beyond the included allowance.

### Use an agent skill to find egress anti-patterns

The `neon-postgres` [agent skill](https://neon.com/docs/ai/agent-skills) includes an egress optimization workflow for your AI assistant. It's a general Postgres skill, so the workflow applies when you ask about high database bills, unexpected network transfer, egress spikes, or query overfetching.

The assistant finds the queries that transfer the most data using `pg_stat_statements` and traces them back to your code. It then fixes the anti-patterns it finds (unused columns such as `SELECT *`, missing pagination, repeated reads of static data, application-side aggregation, and JOIN duplication) and checks that your tests still pass and transfer drops.

`neon-postgres` is part of the default set that `neon skills` installs, so you may already have it. To add just this skill with the [Neon CLI](https://neon.com/docs/cli):

```bash
neon skills -s neon-postgres
```

Without the Neon CLI, run `npx skills add neondatabase/agent-skills -s neon-postgres` instead.

**Tip:** Building a platform on Neon? You can cap per-project network transfer with [consumption limits](https://neon.com/docs/guides/consumption-limits).

## References

- [Cost optimization](https://neon.com/docs/introduction/cost-optimization): Broader cost reduction strategies across all billing metrics
- [Querying consumption metrics](https://neon.com/docs/guides/consumption-metrics): Full API reference with pagination, polling, and error handling
- [Building a Usage Dashboard with Neon's Consumption API](https://neon.com/guides/usage-dashboard-consumption-api): Example app for visualizing usage metrics

--- [Document source](https://neon.com/docs/introduction/plans.md) ---

> Summary: Compare Neon's Free, Launch, and Scale plans: compute rates ($0.106/CU-hour on Launch, $0.222/CU-hour on Scale), storage ($0.35/GB-month, unlimited on paid plans), branch and project limits, autoscaling, and Free plan allowances. Paid plans have no monthly minimum. Includes billing examples for estimating costs.

# Neon plans

Last updated: 2026-11-04

Neon offers plans to support you at every stage, from your first prototype to production at scale.
Start for free, then **pay only for what you use** as your needs grow.

## Plan overview

Compare Neon's **Free**, **Launch**, and **Scale** plans.

**Tip: Building an agent platform?**

For AI agent platforms that provision thousands of databases, Neon offers an **Agent Plan** with unlimited projects, Launch-rate compute, and credits for **your** free tier. Agent limits differ from Scale. [Learn more](https://neon.com/docs/introduction/agent-plan)

| Plan feature                                                                                  | **Free**                                                           | **Launch**                                 | **Scale**                                                                                                         |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| [Price](https://neon.com/docs/introduction/plans#price)                                       | $0/month                                                           | Pay for what you use                       | Pay for what you use                                                                                              |
| [Who it's for](https://neon.com/docs/introduction/plans#who-its-for)                          | Prototypes, side projects, and small teams                         | Startups and growing teams                 | Production-grade workloads and larger companies                                                                   |
| [Organization members](https://neon.com/docs/introduction/plans#organization-members)         | Unlimited                                                          | Unlimited                                  | Unlimited                                                                                                         |
| [Projects](https://neon.com/docs/introduction/plans#projects)                                 | 100                                                                | 100                                        | 1,000 (can be increased on request)                                                                               |
| [Branches](https://neon.com/docs/introduction/plans#branches)                                 | 10/project                                                         | 10/project                                 | 25/project                                                                                                        |
| [Extra branches](https://neon.com/docs/introduction/plans#extra-branches)                     | Not available                                                      | $1.50/branch-month (prorated hourly)       | $1.50/branch-month (prorated hourly)                                                                              |
| [Compute](https://neon.com/docs/introduction/plans#compute)                                   | 100 CU-hours/project                                               | $0.106/CU-hour                             | $0.222/CU-hour                                                                                                    |
| [Autoscaling](https://neon.com/docs/introduction/plans#autoscaling)                           | Up to 2 CU (8 GB RAM)                                              | Up to 16 CU (64 GB RAM)                    | Up to 16 CU autoscaling, or fixed sizes up to 56 CU (224 GB RAM)                                                  |
| [Scale to zero](https://neon.com/docs/introduction/plans#scale-to-zero)                       | After 5 min                                                        | After 5 min, can be disabled               | Configurable (1 minute to always on)                                                                              |
| [Storage](https://neon.com/docs/introduction/plans#storage)                                   | 1 GB/project, 20 GB account total                                  | $0.35/GB-month                             | $0.35/GB-month                                                                                                    |
| [Public network transfer](https://neon.com/docs/introduction/plans#public-network-transfer)   | 5 GB per project included                                          | 500 GB per project included, then $0.10/GB | 500 GB per project included, then $0.10/GB                                                                        |
| [Monitoring](https://neon.com/docs/introduction/plans#monitoring)                             | 1 day                                                              | 3 days                                     | 14 days                                                                                                           |
| [Metrics/logs export](https://neon.com/docs/introduction/plans#metricslogs-export)            | Not available                                                      | Not available                              | ✅                                                                                                                 |
| [Spending notifications](https://neon.com/docs/introduction/plans#spending-notifications)     | Not available                                                      | ✅                                          | ✅                                                                                                                 |
| [Instant restore](https://neon.com/docs/introduction/plans#instant-restore)                   | No charge, up to 6 hours                                           | $0.20/GB-month                             | $0.20/GB-month                                                                                                    |
| [History window](https://neon.com/docs/introduction/plans#history-window)                     | 6 hours, up to 1 GB of changes                                     | Up to 7 days                               | Up to 30 days                                                                                                     |
| [Snapshots](https://neon.com/docs/introduction/plans#snapshots)                               | 1 manual snapshot                                                  | 100 manual snapshots, $0.09/GB-month       | 100 manual snapshots, $0.09/GB-month                                                                              |
| [Auth](https://neon.com/docs/introduction/plans#auth)                                         | Up to 60k MAU/project                                              | Up to 1M MAU/project                       | Up to 1M MAU/project                                                                                              |
| [Object Storage](https://neon.com/docs/introduction/plans#object-storage)                     | 5 GB/project                                                       | $0.023/GB-month                            | $0.023/GB-month                                                                                                   |
| [Functions](https://neon.com/docs/introduction/plans#functions)                               | 10 active / 400 waiting Capacity-Hours, 1M invocations per project | $0.10/$0.025/Capacity-Hour, $0.60/M        | $0.12/$0.03/Capacity-Hour, $0.60/M                                                                                |
| [AI Gateway](https://neon.com/docs/introduction/plans#ai-gateway)                             | Prepaid credits                                                    | Prepaid credits                            | Prepaid credits                                                                                                   |
| [Data API](https://neon.com/docs/introduction/plans#data-api)                                 | No separate charge                                                 | No separate charge                         | No separate charge                                                                                                |
| [Realtime](https://neon.com/docs/introduction/plans#realtime)                                 | Free during beta                                                   | Free during beta                           | Free during beta                                                                                                  |
| [Private network transfer](https://neon.com/docs/introduction/plans#private-network-transfer) | Not available                                                      | Not available                              | $0.01/GB                                                                                                          |
| [Compliance and security](https://neon.com/docs/introduction/plans#compliance-and-security)   | Not available                                                      | Protected branches                         | SOC 2, ISO, GDPR, [HIPAA](https://neon.com/docs/security/hipaa), Protected branches, IP Allow, Private Networking |
| [Uptime SLA](https://neon.com/docs/introduction/plans#uptime-sla)                             | Not available                                                      | Not available                              | ✅                                                                                                                 |
| [Support](https://neon.com/docs/introduction/plans#support)                                   | Community                                                          | Billing support                            | Standard (additional options for higher-volume customers)                                                         |

To upgrade or downgrade, go to **Billing** > **Change plan** in the [Neon Console](https://console.neon.tech/app/billing#change_plan). See [Change your plan](https://neon.com/docs/introduction/manage-billing#change-your-plan) for what happens to your resources when you switch.

## Plan features

This section describes the features listed in the [Plan overview](https://neon.com/docs/introduction/plans#plan-overview) table.

**Tip: Optimize your costs**

Learn how to manage your Neon costs effectively with our [cost optimization guide](https://neon.com/docs/introduction/cost-optimization), which covers strategies for compute, storage, branches, and data transfer.

### Price

On **Launch** and **Scale** plans, you pay only for what you use; there's no minimum monthly fee. Usage for compute, storage, extra branches, and other features is billed at the published rates (see the [Plan overview](https://neon.com/docs/introduction/plans#plan-overview) table).

Higher-volume customers may qualify for annual commits. [Contact sales](https://neon.com/contact-sales) to learn more.

**Note:** Invoices under $0.50 are not collected.

On the **Free** plan, there is no monthly cost. You get usage allowances for projects, branches, compute, storage, and more, for $0/month.

### Who it's for

- **Free**: Prototypes, side projects, and small teams. Includes 100 projects, 100 CU-hours/project, 1 GB Postgres storage per project (up to 20 GB total across all projects), and 5 GB of egress per project. Upgrade if you need more resources or features.
- **Launch**: Startups and growing teams needing more resources, features, and flexibility. Pay only for what you use.
- **Scale**: Production-grade workloads and large teams. Higher limits, advanced features, full support, compliance, additional security, and SLAs. Pay only for what you use.

### Organization members

You can invite teammates to your organization and they'll have access to all projects within it. To invite members, go to the **People** page in your organization and click **Invite member**. See [Invite members](https://neon.com/docs/manage/orgs-manage#invite-members) for details.

### Projects

A project is a container for your backend. It includes your database, branches, computes, and backend services like object storage and functions. Similar to a Git repository that contains code, artifacts, and branches, a project contains all your resources. Learn more about [Neon's object model](https://neon.com/docs/concepts/the-object-model).

> For most use cases, create a project for each app or customer to isolate data and manage resources.

Included per plan:

- **Free**: 100 projects
- **Launch**: 100 projects
- **Scale**: 1,000 projects (soft limit; request more if needed via [support](https://neon.com/docs/introduction/support))

### Branches

Each Neon project is created with a [root branch](https://neon.com/docs/reference/glossary#root-branch), like the `main` branch in Git.  
Postgres objects (databases, schemas, tables, records, indexes, roles) are created on a branch.

You can create [child branches](https://neon.com/docs/reference/glossary#child-branch) for testing, previews, or development.

Included per plan, counting the root branch:

- **Free**: 10 branches/project
- **Launch**: 10 branches/project
- **Scale**: 25 branches/project

See [Extra branches](https://neon.com/docs/introduction/plans#extra-branches) for overage costs and [Storage](https://neon.com/docs/introduction/plans#storage) for how branch storage is billed.

> Projects can have multiple root branches, with limits based on your plan. See [Branch types: Root branch](https://neon.com/docs/manage/branches#root-branch) for details.

### Extra branches

On paid plans, you can create extra child branches. Extra branches beyond your plan's branch allowance (outlined [above](https://neon.com/docs/introduction/plans#branches)) are billed in **branch-months**, metered hourly.

1 extra branch × 1 month = 1 branch-month

Cost: **$1.50/branch-month** (~$0.002/hour).

Example: The Launch plan includes 10 branches/project. You create 2 extra branches for 5 hours each → 10 extra branch-hours × $0.002/hour = ~$0.02 total.

> Extra branches are not available on the Free plan. Delete branches or upgrade if you need more.

The maximum number of branches you can have per project:

- **Launch**: 5,000 branches/project
- **Scale**: 5,000 branches/project

If you need more, [request an increase in the feedback form in console](https://console.neon.tech/app/settings?modal=feedback\&modalparams=%22Branch%20limit%20increase%22).

### Compute

Compute usage depends on compute size and runtime.

- Measured in **CU-hours** (Compute Unit hours)
- Each Compute Unit (CU) allocates approximately 4 GB of RAM, along with associated CPU and local SSD resources
- Compute sizes up to 56 CU (plan-dependent)

| Compute Unit | RAM    |
| ------------ | ------ |
| .25          | 1 GB   |
| .5           | 2 GB   |
| 1            | 4 GB   |
| 2            | 8 GB   |
| 3            | 12 GB  |
| ...          | ...    |
| 56           | 224 GB |

Formula:

```
compute size × hours running = CU-hours
```

Examples:

- 0.25 CU for 4 hours = 1 CU-hour
- 2 CU for 3 hours = 6 CU-hours
- 8 CU for 2 hours = 16 CU-hours

**Free**: 100 CU-hours/project/month (enough to run a 0.25 CU compute in a project for 400 hours/month).  
**Launch**: $0.106/CU-hour  
**Scale**: $0.222/CU-hour

> All computes in your project count toward usage. Each branch has a read-write compute by default; [read replicas](https://neon.com/docs/reference/glossary#read-replica) add read-only computes.

#### Compute with autoscaling

Autoscaling changes compute size between a defined min and max. Estimate usage as:

```
average compute size × hours running = CU-hours
```

#### Compute with scale to zero

Scale to zero suspends computes after inactivity to reduce compute usage and cost.

### Autoscaling

Adjusts compute size between defined limits based on demand.

- **Free**: Up to 2 CU (8 GB RAM)
- **Launch**: Up to 16 CU (64 GB RAM)
- **Scale**: Up to 16 CU for autoscaling; fixed sizes up to 56 CU (224 GB RAM)

> Autoscaling is capped at 16 CU. Scale supports fixed computes above 16 CU.

### Scale to zero

Suspends computes after inactivity.

- **Free**: 5 min inactivity; cannot disable
- **Launch**: 5 min inactivity; can disable
- **Scale**: Fully configurable; 1 minute to always on

### Storage

Storage is your data size, billed on actual usage in **GB-months**, measured hourly.

- **Launch**/**Scale plan storage cost**: $0.35/GB-month
- **[Root branches](https://neon.com/docs/reference/glossary#root-branch)**: billed on actual data size (_logical data size_)
- **[Child branches](https://neon.com/docs/reference/glossary#child-branch)**: billed on the minimum of the data changes since creation or the logical data size

When a child branch is created, it initially consumes no storage. As you make changes (inserts, updates, or deletes) to the child branch, a delta is recorded from the point of branch creation. This delta, a log of all write operations, grows over time and counts toward your storage usage.

Importantly, **child branch storage is capped at your actual data size**: you're billed for the minimum of accumulated changes or logical data size, whichever is lower.

**Important: Manage child branches to control storage costs**

Even though child branch storage is capped at your logical data size, it's still important to manage branches effectively to minimize storage costs:

- Set a [time to live](https://neon.com/docs/guides/branch-expiration) on development and preview branches
- Delete child branches when they're no longer needed
- For production workloads, use a [root branch](https://neon.com/docs/manage/branches#root-branch) instead; root branches are billed on your actual data size with no delta tracking overhead.

> **Free** plan users get 1 GB of Postgres storage per project, up to 20 GB total across all projects

#### Unlimited storage

**Storage is unlimited on paid plans (Launch and Scale): there's no hard per-branch size limit, and your storage grows with your usage.** The Free plan is limited to 1 GB of Postgres storage per project, and to 20 GB in total across all your projects. These two limits are enforced independently: the total Postgres storage across all your Free projects can't exceed 20 GB, even though each project is also individually capped at 1 GB. This limit applies to Postgres storage and is separate from [Object Storage](https://neon.com/docs/introduction/plans#object-storage), which has its own Free allowance.

### Public network transfer

Public network transfer (egress) is the total volume of data sent from your databases over the public internet during the monthly billing period.

> Public network transfer includes data sent via [logical replication](https://neon.com/docs/reference/glossary#logical-replication) to any destination, including other Neon databases.

Allowances per plan:

- **Free**: 5 GB per project per month
- **Launch**: 500 GB per project per month, then $0.10/GB
- **Scale**: 500 GB per project per month, then $0.10/GB

> On all plans, the network transfer allowance is per project and shared across all products in that project, including Postgres, [Object Storage](https://neon.com/docs/introduction/plans#object-storage), and [Functions](https://neon.com/docs/introduction/plans#functions).

### Monitoring

View metrics such as RAM, CPU, connections, and database size in the **Monitoring** dashboard in the Neon Console.

Retention of metrics data differs by plan:

- **Free**: 1 day
- **Launch**: 3 days
- **Scale**: 14 days

See [Monitoring dashboard](https://neon.com/docs/introduction/monitoring-page) for details.

### Metrics/logs export

Export metrics and Postgres logs to [Datadog](https://neon.com/docs/guides/datadog) or any [OTel-compatible platform](https://neon.com/docs/guides/opentelemetry).  
Available only on the **Scale** plan.

### Spending notifications

Get email alerts when your organization's monthly Neon charges reach 80% and 100% of a threshold you set, so you can act before the bill grows. Available on the **Launch** and **Scale** plans.

See [Spending notifications](https://neon.com/docs/introduction/spending-notifications) for how to set a threshold.

### Instant restore

Neon stores a change history to support point-in-time restore (instant restore). You can only point-in-time restore from **root branches**, so PITR storage is charged only for root branches. Child branches do not add to this charge.

- **Free**: No charge, up to 6 hours, limited to 1 GB of change history per project
- **Launch**: Up to 7 days, billed at $0.20/GB-month
- **Scale**: Up to 30 days, billed at $0.20/GB-month

You can change your [history window](https://neon.com/docs/introduction/plans#history-window) to control how much change history you retain for **instant restore**. See [Instant restore](https://neon.com/docs/introduction/branch-restore) for how to use the feature.

> The change history is a log of write operations in the form of Postgres [Write-Ahead Logs](https://neon.com/docs/reference/glossary#write-ahead-logging-wal).

### History window

How far back **instant restore** can reach (and how much change history is retained) for your project.

The maximum history window per plan:

- **Free**: Up to 6 hours, limited to 1 GB of change history per project
- **Launch**: Up to 7 days
- **Scale**: Up to 30 days

> The history window defaults are 6 hours for Free plan projects and 1 day for paid plan projects.

Shortening the history window can reduce [instant restore](https://neon.com/docs/introduction/plans#instant-restore) storage costs but limits how far back you can restore. See [History window](https://neon.com/docs/introduction/history-window) for configuration details and more information.

### Snapshots

Snapshots capture the state of your branch at a point in time. You can create snapshots manually or schedule automated backups.

The per-plan snapshot limit applies to **manual snapshots only**. On paid plans, snapshots created by backup schedules do not count toward this limit (scheduled backups are not available on the Free plan).

Manual snapshot limits per plan:

- **Free**: 1 manual snapshot
- **Launch**: 100 manual snapshots
- **Scale**: 100 manual snapshots

**Pricing**: Snapshot storage is billed at $0.09/GB-month.

For billing, manual snapshots are charged as full snapshots. Scheduled snapshots are charged as full snapshots for the first snapshot in a schedule, then as incremental (delta) storage for subsequent snapshots in that schedule.

Automated backup schedules are available on paid plans. On the Agent plan, they are available upon request. See [Backup & restore](https://neon.com/docs/guides/backup-restore) for details.

### Auth

Managed Better Auth is a managed authentication service built on [Better Auth](https://www.better-auth.com/), fully integrated into the Neon platform.

Monthly Active User (MAU) limits per project:

- **Free**: Up to 60,000 MAU per project
- **Launch**: Up to 1M MAU per project ([request an increase in console](https://console.neon.tech/app/settings?modal=feedback\&modalparams=%22Neon%20auth%20limit%20increase%22) if you need more)
- **Scale**: Up to 1M MAU per project ([request an increase in console](https://console.neon.tech/app/settings?modal=feedback\&modalparams=%22Neon%20auth%20limit%20increase%22) if you need more)

> An MAU (Monthly Active User) is a unique user who authenticates at least once during a monthly billing period.

See [Managed Better Auth](https://neon.com/docs/auth/overview) for more information.

### Object Storage

Neon Object Storage is S3-compatible object storage that branches with your Neon project. It's available on all plans, including Free.

On paid plans, the following rates apply ([usage limits](https://neon.com/docs/storage/overview#limits) also apply):

- **Storage**: $0.023/GB-month. Only stored volume is metered; there's no per-operation charge.
- **Egress**: Data transferred out counts toward your [public network transfer](https://neon.com/docs/introduction/plans#public-network-transfer) allowance, which is shared across all products, and is billed at the same rate once you exceed it.

On the **Free** plan, you get 5 GB of Object Storage per project.

See [Neon Object Storage](https://neon.com/docs/storage/overview) for more information.

### Functions

Neon Functions are serverless Node.js compute you deploy onto a Neon branch, so your backend code runs next to your database. They're available on all plans, including Free.

You're billed for compute only while a request is being processed. Billing starts when a request triggers the function and continues until processing finishes, either by returning a response or by completing any background [`waitUntil`](https://neon.com/docs/compute/functions/reference/runtime-limits#timeouts) work it started. You aren't billed between requests.

Compute is measured in **Capacity-Hours**. Functions run at a fixed size, so one hour of function runtime equals one Capacity-Hour. That runtime is billed at two rates, and a single request usually incurs both:

- **Active compute**: billed while your code is actively using the CPU.
- **Waiting compute**: billed at a lower rate when your code isn't using much CPU, typically while it waits on the network, a timer, or other I/O.

**Invocations** are counted separately: each time your function is called counts as one invocation, regardless of how long it runs. Billed per million.

[Usage limits](https://neon.com/docs/compute/functions/reference/runtime-limits) apply. On paid plans, Functions are billed at the following rates:

| Metric          | **Launch**           | **Scale**           |
| --------------- | -------------------- | ------------------- |
| Active compute  | $0.10/Capacity-Hour  | $0.12/Capacity-Hour |
| Waiting compute | $0.025/Capacity-Hour | $0.03/Capacity-Hour |
| Invocations     | $0.60/M              | $0.60/M             |

On the **Free** plan, you get 10 active Capacity-Hours, 400 waiting Capacity-Hours, and 1 million invocations per project per month. Each project gets its own allowance, and it isn't shared with your other projects. The [concurrency limit](https://neon.com/docs/compute/functions/reference/runtime-limits#concurrency) is separate: it caps in-flight invocations across your account to prevent abuse and isn't a usage allowance.

Egress (data a function sends out) counts toward the project's [public network transfer](https://neon.com/docs/introduction/plans#public-network-transfer) allowance, which is also per project and shared across all products in that project.

See [Neon Functions](https://neon.com/docs/compute/functions/overview) for what's included and current limitations.

### AI Gateway

Neon AI Gateway provides access to open-weight and foundation models from multiple providers through a single Neon credential. It's available on all plans, including Free. On the Free plan, you add a payment card and buy prepaid credits without upgrading. Any account with prepaid credits can use every model in the catalog; see [Model access](https://neon.com/docs/ai-gateway/models#model-access) for details.

Prices match each provider's published list prices, with no additional markup, and draw down a prepaid credit balance you buy from the **Billing** page in the Neon Console.

See [AI Gateway prepaid credits](https://neon.com/docs/ai-gateway/prepaid-credits) for pricing details, buying credits, and usage limits.

### Data API

The [Neon Data API](https://neon.com/docs/data-api/overview) lets you query your database over HTTP. It's available on all plans with no separate charge. The queries it runs use your database compute, so they count toward your [compute](https://neon.com/docs/introduction/plans#compute) usage like any other query. Responses count toward your [public network transfer](https://neon.com/docs/introduction/plans#public-network-transfer) allowance.

### Realtime

[Neon Realtime](https://neon.com/docs/realtime/overview) is free to use during the beta. Neon doesn't charge for the live query engine or the Live SQL API service. Your workload can still generate usage that's billed by your plan:

- **Database compute**: starting a live query can wake your compute, which counts toward your [compute](https://neon.com/docs/introduction/plans#compute) usage.
- **Network transfer**: data sent to clients counts toward your [public network transfer](https://neon.com/docs/introduction/plans#public-network-transfer) allowance.

### Private network transfer

Bi-directional data transfer to and from your databases over private networking.

Private networking is available on the **Scale** plan. It uses [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html) to bypass the public internet.

Billed at $0.01/GB for network transferred to and from Neon. You'll only see this on your bill if you enable this feature.

### Compliance and security

Compliance certifications available on **Scale**:

- SOC 2
- SOC 3
- ISO 27001
- ISO 27701
- GDPR
- CCPA
- HIPAA ([additional charge](https://neon.com/docs/security/hipaa))

Security features:

- [Protected branches](https://neon.com/docs/guides/protected-branches): safeguards for critical data (available on **Launch** and **Scale**)
- [IP Allow](https://neon.com/docs/introduction/ip-allow): restricts access to trusted IPs (available on **Scale**)
- [Private Networking](https://neon.com/docs/guides/neon-private-networking): secure private connections via AWS PrivateLink (available on **Scale**)

### Uptime SLA

Guaranteed service availability is offered on the **Scale** plan. For uptime commitments, Service Credits, and exclusions, see the [Neon Service Level Agreement](https://neon.com/docs/legal/sla).

### Support

Support level by plan:

- **Free**: Community support
- **Launch**: Billing support
- **Scale**: Standard support

Higher-volume customers may qualify for annual commits and additional support options aligned with [Databricks Support](https://www.databricks.com/support). [Contact sales](https://neon.com/contact-sales) to learn more.

See [Support](https://neon.com/docs/introduction/support) for details.

## Usage metrics

The Neon Console displays usage in a simplified view on the [Projects page](https://console.neon.tech/app/), while your invoice shows a detailed breakdown.

![Usage metrics on the Projects page in the Neon Console](https://neon.com/docs/introduction/usage_metrics_console.png)

Use the table below to understand how Console metrics map to invoice line items.

| Console metric       | Invoice line item(s)                                                                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Compute**          | Database compute, CU-hour                                                                                                                                 |
| **Storage**          | Database storage (root branches), GB-month <br/> Database storage (child branches), GB-month                                                              |
| **History**          | Database storage (instant restore), GB-month <br/> Database storage (snapshots), GB-month                                                                 |
| **Network transfer** | Public network transfer, GB <br/> Private network transfer, GB (if [Private Networking](https://neon.com/docs/guides/neon-private-networking) is enabled) |
| Not shown            | Database extra branches, branch-month                                                                                                                     |
| Not shown            | Function compute (active), capacity-hour <br/> Function compute (waiting), capacity-hour <br/> Function invocations, million                              |
| Not shown            | Object storage, GB-month                                                                                                                                  |

**Note:** **Extra branches**, **Neon Functions**, and **Object Storage** don't appear in the Console usage summary but can appear on your invoice. AI Gateway usage draws down your [prepaid credit balance](https://neon.com/docs/ai-gateway/prepaid-credits) rather than appearing as a usage line item.

## Invoice metrics

The following metrics may appear on your Neon invoice. Each metric represents a specific type of usage that contributes to your monthly bill.

| **Metric**                                       | **Description**                                                                                                                                                                                  |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Database compute, CU-hour**                    | Total compute usage in **CU-hours** (Compute Unit hours). [Learn more](https://neon.com/docs/introduction/plans#compute).                                                                        |
| **Database extra branches, branch-month**        | Number of extra branches beyond your plan allowance, metered hourly. [Learn more](https://neon.com/docs/introduction/plans#extra-branches).                                                      |
| **Database storage (instant restore), GB-month** | Storage used for **instant restore**, billed per GB-month. [Learn more](https://neon.com/docs/introduction/plans#instant-restore).                                                               |
| **Database storage (child branches), GB-month**  | Data storage for child branches (minimum of delta or logical size), billed per GB-month. [Learn more](https://neon.com/docs/introduction/plans#storage).                                         |
| **Database storage (root branches), GB-month**   | Data storage for root branches, billed per GB-month. [Learn more](https://neon.com/docs/introduction/plans#storage).                                                                             |
| **Database storage (snapshots), GB-month**       | Storage used for branch snapshots, billed per GB-month. [Learn more](https://neon.com/docs/introduction/plans#snapshots).                                                                        |
| **Private network transfer, GB**                 | Bi-directional data transfer to and from your databases over private networking (for example, AWS PrivateLink). [Learn more](https://neon.com/docs/introduction/plans#private-network-transfer). |
| **Public network transfer, GB**                  | Outbound data transfer (egress) from your databases to the public internet. [Learn more](https://neon.com/docs/introduction/plans#public-network-transfer).                                      |
| **Function compute (active), capacity-hour**     | Neon Functions compute for time your code is actively using the CPU. [Learn more](https://neon.com/docs/introduction/plans#functions).                                                           |
| **Function compute (waiting), capacity-hour**    | Neon Functions compute for time your code waits on I/O, billed at a lower rate. [Learn more](https://neon.com/docs/introduction/plans#functions).                                                |
| **Function invocations, million**                | Number of times your functions are called. [Learn more](https://neon.com/docs/introduction/plans#functions).                                                                                     |
| **Object storage, GB-month**                     | Stored Object Storage volume. [Learn more](https://neon.com/docs/introduction/plans#object-storage).                                                                                             |

## Usage-based cost examples

The following examples show what your monthly bill might look like on the **Launch** and **Scale** plans at different levels of usage. Each example includes compute, storage (root and child branches), and instant restore history. Your actual costs will depend on your specific workload, usage patterns, and configuration.

> **Note:** The "billable days" shown below refer to **active compute time** (the total hours your compute is actively running) in a month. Computes can scale to zero when idle, so you may accumulate these hours in shorter periods of usage throughout the month rather than running continuously.

### Launch plan

- **Example 1 (light usage)**
  - Compute: ~10 CU-hours = 1 CU × 10 hours: **$1.06**  
    _(10 CU-hours × $0.106/CU-hour)_
  - Root branch storage: 2 GB: **$0.70**  
    _(2 GB × $0.35/GB-month)_
  - Child branch storage: 1 GB: **$0.35**  
    _(1 GB × $0.35/GB-month)_
  - Instant restore history: 1 GB: **$0.20**  
    _(1 GB × $0.20/GB-month)_

    **Amount due:** **$2.31**

- **Example 2**
  - Compute: ~120 CU-hours = 1 CU × 120 hours (about 5 billable days): **$12.72**  
    _(120 CU-hours × $0.106/CU-hour)_
  - Root branch storage: 20 GB: **$7.00**  
    _(20 GB × $0.35/GB-month)_
  - Child branch storage: 5 GB: **$1.75**  
    _(5 GB × $0.35/GB-month)_
  - Instant restore history: 10 GB: **$2.00**  
    _(10 GB × $0.20/GB-month)_

    **Amount due:** **$23.47**

- **Example 3**
  - Compute: ~250 CU-hours = 2 CU × 125 hours (about 5.2 billable days): **$26.50**  
    _(250 CU-hours × $0.106/CU-hour)_
  - Root branch storage: 40 GB: **$14.00**  
    _(40 GB × $0.35/GB-month)_
  - Child branch storage: 10 GB: **$3.50**  
    _(10 GB × $0.35/GB-month)_
  - Instant restore history: 20 GB: **$4.00**  
    _(20 GB × $0.20/GB-month)_

    **Amount due:** **$48.00**

---

### Scale plan

- **Example 1**
  - Compute: ~1,700 CU-hours = 4 CU × 425 hours (about 17.7 billable days): **$377.40**  
    _(1,700 CU-hours × $0.222/CU-hour)_
  - Root branch storage: 100 GB: **$35.00**  
    _(100 GB × $0.35/GB-month)_
  - Child branch storage: 25 GB: **$8.75**  
    _(25 GB × $0.35/GB-month)_
  - Instant restore history: 50 GB: **$10.00**  
    _(50 GB × $0.20/GB-month)_

    **Amount due:** **$431.15**

- **Example 2**
  - Compute: ~2,600 CU-hours = 8 CU × 325 hours (about 13.5 billable days): **$577.20**  
    _(2,600 CU-hours × $0.222/CU-hour)_
  - Root branch storage: 150 GB: **$52.50**  
    _(150 GB × $0.35/GB-month)_
  - Child branch storage: 40 GB: **$14.00**  
    _(40 GB × $0.35/GB-month)_
  - Instant restore history: 75 GB: **$15.00**  
    _(75 GB × $0.20/GB-month)_

    **Amount due:** **$658.70**

## Frequently asked questions

### What is a CU?

A CU (Compute Unit) is Neon's measure of compute size. Each CU allocates approximately 4 GB of RAM to the database instance, along with associated CPU and local SSD resources. Scaling up increases these resources linearly. For example, a 2 CU compute has 8 GB RAM.

### How is compute usage measured in Neon?

Compute usage is measured in **CU-hours**:  
CU-hours = compute size (in CU) × hours running  
Examples:  
• 0.25 CU for 4 hours = 1 CU-hour  
• 2 CU for 3 hours = 6 CU-hours  
Your plan's compute price per CU-hour depends on whether you are on Launch or Scale. On the Free plan, each project includes 100 CU-hours per month.

### How is storage usage billed in Neon?

Storage is billed based on actual usage, measured in **GB-months**:  
1 GB-month = 1 GB stored for 1 month  
Storage usage is metered hourly and summed over the month. For child branches, you're billed for the minimum of accumulated changes or logical data size; capped at your actual data size. On the Free plan, you get 1 GB of Postgres storage per project, up to 20 GB total across all projects.

### How do branches affect storage?

Your root branch contains your main data. Child branches share data with the root until changes are made. Child branches are billed for the minimum of accumulated changes or logical data size; you never pay more than your actual data size. Delete unused branches to control storage costs.

### How is extra branch usage billed?

Paid plans include a set number of branches per project. Additional branches are billed at **$1.50/branch-month**, prorated hourly (about $0.002/hour).  
Example: If your plan includes 10 branches and you run 2 extra branches for 5 hours each, that's 10 branch-hours (~$0.02).

### How are instant restores billed?

Neon charges for PITR (point-in-time restore) storage only for branches you can point-in-time restore from: root branches. The charge is based on the amount of change history retained on those branches, not the number of restores you perform. Child branches do not add to PITR storage charges.  
• Free: Up to 6 hours of history, limited to 1 GB of changes per project, no charge.  
• Launch: Up to 7 days of history, billed at $0.20/GB-month.  
• Scale: Up to 30 days of history, billed at $0.20/GB-month.  
Change history is stored as Postgres WAL records.

### Is instant restore history accumulated at the project or branch level?

You can only point-in-time restore from root branches, so only root branches contribute to your billed PITR storage. You set a single **history window** (for example, 7 days or 30 days) for the entire project for **instant restore**. You cannot enable, disable, or configure the history window per branch.

### Can I disable scale-to-zero?

Free: No, it's always enabled (5 min idle timeout).  
Launch: Yes, you can disable it.  
Scale: Yes, fully configurable (1 minute to always-on). Learn more: [Scale to zero](https://neon.com/docs/introduction/scale-to-zero)

### What is autoscaling and how does it work?

Autoscaling adjusts compute size based on load, between your set min/max limits. All plans support it, but maximum CU differs: Free up to 2 CU, Launch and Scale up to 16 CU. Scale supports up to 56 CU for fixed-size computes. Learn more: [Autoscaling](https://neon.com/docs/introduction/autoscaling)

### How are read replicas billed?

Each read replica is its own compute and contributes to CU-hours.

### Do public network transfer limits reset each month?

Yes. Free includes 5 GB per project per month. Launch and Scale include 500 GB per project per month, then $0.10/GB.

### How is private network transfer billed?

Only available on Scale: $0.01/GB, bidirectional, between Neon and private network services.

### What are the limits and quotas for the Free plan?

The Free plan costs $0/month and includes 100 projects, 10 branches per project, 100 CU-hours of compute per project per month, autoscaling up to 2 CU (≈8 GB RAM), 1 GB of Postgres storage per project (up to 20 GB total across all projects), and 5 GB of public network transfer per project per month. It also includes a 6-hour instant restore history (up to 1 GB of changes per project), 1 manual snapshot, up to 60,000 Managed Better Auth MAU per project, 1 day of monitoring history, and community support. Scale to zero is always enabled (computes suspend after 5 minutes of inactivity) and can't be disabled. Compute (CU-hours) and network transfer reset each monthly billing period; projects, branches, and storage are continuous limits. For the full row-by-row breakdown, see the [Plan overview](https://neon.com/docs/introduction/plans#plan-overview) table.

### What happens if I exceed my Free plan limits?

On the Free plan, when you run out of CU-hours or public network transfer, your compute is suspended until the next billing period or until you upgrade. Exceeding the 1 GB per-project storage cap, or the 20 GB total cap across all your projects, causes operations that increase storage (inserts, updates, and deletes) to fail until you free space or upgrade. Branch creation fails once you reach 10 branches per project. None of these limits delete your data.

### How do I upgrade or downgrade my plan?

In the Neon Console, go to **Billing** and select **Change plan**. After an upgrade, a compute picks up the new plan limits (such as maximum compute size) the next time it restarts. Before you downgrade, remove any projects, branches, or data that exceed the new plan's allowances. See [Change your plan](https://neon.com/docs/introduction/manage-billing#change-your-plan).

### Do you charge for idle computes?

If scale-to-zero is enabled, no. Computes that are suspended do not accrue CU-hours.

### What is the difference between root and child branch storage billing?

Root branches are billed for their full logical data size. Child branches are billed for the minimum of accumulated changes since creation or logical data size; ensuring you never pay more than your actual data size.

### Can I get more than the listed project limit?

Yes, on Scale you can request increases for projects beyond the listed limit.

### Why is the compute rate higher on Scale than Launch?

Scale includes higher availability, advanced security features, compliance certifications, and SLAs. The higher CU-hour rate reflects these additional capabilities.

### How can I control my costs?

• Set a maximum autoscaling limit to cap compute size.  
• Enable scale-to-zero for idle databases.  
• Delete unused branches to reduce storage costs.  
• Shorten your **history window** to reduce **History** usage (instant restore storage).  
For more detailed strategies, see our [Cost optimization](https://neon.com/docs/introduction/cost-optimization) guide.

### Do you offer credits for startups?

Yes, venture-backed startups may apply for the Neon Startup Program. Learn more: [Startup Program](https://neon.com/startup)

### How is storage charged for snapshots?

Snapshot storage is billed at $0.09/GB-month.

### Is storage cost different for archived branches?

No. Archived branches are billed at the same rate as active branches. Neon automatically archives inactive branches to optimize storage resources and maintain a cost-efficient storage infrastructure. See [Branch archiving](https://neon.com/docs/guides/branch-archiving) for details on how archiving works.

--- [Document source](https://neon.com/docs/introduction/reactivity.md) ---

> Summary: Realtime's reactive client primitives bind live SQL queries to your app state, with type-safe useLiveQuery hooks, TanStack DB collections and optimistic mutations on standard Postgres.

# Reactivity

Build reactive apps with end-to-end, type-safe live queries and optimistic mutations.

Last updated: 2026-10-15

A reactive app updates itself when its data changes. Your components declare the data they need, and the system keeps that data in sync, so there's no fetch-and-refresh code to write.

[Realtime](https://neon.com/docs/realtime/overview) builds this on [live SQL queries](https://neon.com/docs/introduction/live-sql-queries). Its reactive client primitives bind each live query to your application state, end to end and type-safe, on standard Lakebase Postgres.

## Reactive client primitives

- **Type-safe live queries:** `useLiveQuery` binds a sealed query to your component state, with the row type carried from your backend query.
- **TanStack DB collections:** sync a live query into a [TanStack DB](https://tanstack.com/db/latest/docs/overview) collection for more advanced client-side data management.
- **Optimistic mutations:** apply writes locally first for instant feedback. The synced result replaces the optimistic state once the write lands.

## Bind a live query to a component

In a React app, `useLiveQuery` binds a sealed query to your component, optionally starting from `initialData` loaded during SSR:

```tsx filename="YourApp.tsx"
import { useLiveQuery } from "@neon/realtime-react"
import type { SealedLiveQuery } from "@neon/realtime/client"

interface Props {
  sealedQuery: SealedLiveQuery<Message>
  initialData?: Message[]
}

export function Messages({ sealedQuery, initialData }: Props) {
  const { data } = useLiveQuery(sealedQuery, { initialData })

  return (
    <ul>
      {data.map((message) => (
        <li key={message.id}>{message.body}</li>
      ))}
    </ul>
  )
}
```

The component re-renders whenever a write changes the query's results.

## Next steps

- [Client-side reactivity](https://neon.com/docs/realtime/guides/reactivity): bind live queries to your app state
- [Optimistic mutations](https://neon.com/docs/realtime/guides/mutations): apply writes locally while they sync
- [Next.js example](https://neon.com/docs/realtime/examples/nextjs): build a reactive app with Next.js and SSR
- [TanStack example](https://neon.com/docs/realtime/examples/tanstack): build a reactive app with TanStack Start and DB
- [TypeScript SDK](https://neon.com/docs/realtime/sdks/typescript): reference for the React and TanStack DB integrations

--- [Document source](https://neon.com/docs/introduction/read-replicas.md) ---

> Summary: Neon read replicas are independent read-only compute instances that serve requests from the same storage as the primary compute. No data is duplicated or replicated, and replicas spin up in seconds. Use read replicas to offload analytics queries, distribute read traffic, or grant read-only access without affecting write performance. Read replicas are asynchronous and support Autoscaling and Scale to Zero. Cross-region replicas require logical replication to a separate Neon project.

# Neon Read Replicas

Scale your app, run ad-hoc queries, and provide read-only access without duplicating data

Last updated: 2026-08-26

Neon read replicas are independent computes designed to perform read operations on the same data as your primary read-write compute. Neon's read replicas do not replicate or duplicate data. Instead, read requests are served from the same storage, as shown in the diagram below. While your read-write queries are directed through your primary compute, read queries can be offloaded to one or more read replicas.

![read replica simple](https://neon.com/docs/introduction/read_replica_simple.png)

You can instantly create read replicas for any branch in your Neon project and configure the compute size allocated to each. Read replicas also support Neon's [Autoscaling](https://neon.com/docs/introduction/autoscaling) and [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero) features, providing you with the same control over compute resources that you have with your primary compute.

## How are Neon read replicas different?

- **No additional storage is required**: With read replicas reading from the same source as your primary read-write compute, no additional storage is required to create a read replica. Data is neither duplicated nor replicated. Creating a read replica involves spinning up a read-only compute instance, which takes a few seconds.
- **You can create them almost instantly**: With no data replication required, you can create read replicas almost instantly.
- **They are cost-efficient**: With no additional storage or transfer of data, costs associated with storage and data transfer are avoided. Neon's read replicas also benefit from Neon's [Autoscaling](https://neon.com/docs/introduction/autoscaling) and [Scale to Zero](https://neon.com/docs/manage/computes#scale-to-zero-configuration) features, which allow you to manage compute usage.
- **They are instantly available**: You can allow read replicas to scale to zero when not in use without introducing lag. When a read replica starts up in response to a query, it is up to date with your primary read-write compute almost instantly.

## How do you create read replicas?

You can create read replicas using the Neon Console, [Neon CLI](https://neon.com/docs/cli), or [Neon API](https://neon.com/docs/reference/api), providing the flexibility required to integrate read replicas into your workflow or CI/CD processes.

**Note:** On paid plans, you can add up to 6 read replicas per branch. The Free plan is limited to 3 read replica computes per project. If a branch already has more than 6 read replicas, they keep running, but you can't add another until the branch is below the limit.

**Console**

From the Neon Console, it's a simple **Add Read Replica** action on a branch.

![Create a read replica](https://neon.com/docs/introduction/create_read_replica.png)

**CLI**

Add a read-only compute to a branch with [`neon branches add-compute`](https://neon.com/docs/cli/branches#add-compute):

```bash
neon branches add-compute br-young-fire-15282225 --type read_only
```

**API**

Create a read-only compute with the [Create compute](https://neon.com/docs/reference/api/endpoints/create-project-endpoint) endpoint:

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/late-bar-27572981/endpoints \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "endpoint": {
    "type": "read_only",
    "branch_id": "br-young-fire-15282225"
  }
}
' | jq
```

For more details and how to connect to a read replica, see [Create and manage Read Replicas](https://neon.com/docs/guides/read-replica-guide).

## Read Replica architecture

The following diagram shows how your primary compute and read replicas send read requests to the same Pageserver, which is the component of the [lakebase architecture](https://neon.com/docs/introduction/architecture-overview) that is responsible for serving read requests.

![read replica computes](https://neon.com/docs/introduction/read_replicas.png)

Neon read replicas are asynchronous, which means they are _eventually consistent_. As updates are made by your primary compute, Safekeepers store the data changes durably until they are processed by Pageservers. At the same time, Safekeepers keep read replica computes up to date with the most recent changes to maintain data consistency.

## Cross-region support

Neon only supports creating read replicas **in the same region** as your database. However, a cross-region replica setup can be achieved by creating a Neon project in a different region and replicating data to that project via [logical replication](https://neon.com/docs/guides/logical-replication-guide). For example, you can replicate data from a Neon project in a US region to a Neon project in a European region following our [Neon-to-Neon logical replication guide](https://neon.com/docs/guides/logical-replication-neon-to-neon). Read-only access to the replicated database can be managed at the application level.

## Use cases

Neon's read replicas have a number of applications:

- **Horizontal scaling**: Scale your application by distributing read requests across replicas to improve performance and increase throughput.
- **Analytics queries**: Offloading resource-intensive analytics and reporting workloads to reduce load on the primary compute.
- **Read-only access**: Granting read-only access to users or applications that don't require write permissions.

## Get started with read replicas

To get started with read replicas, refer to our guides:

- [Create and manage Read Replicas](https://neon.com/docs/guides/read-replica-guide): Learn how to create, connect to, configure, delete, and monitor read replicas
- [Scale your app with Read Replicas](https://neon.com/docs/guides/read-replica-integrations): Scale your app with read replicas using built-in framework support
- [Run analytics queries with Read Replicas](https://neon.com/docs/guides/read-replica-data-analysis): Leverage read replicas for running data-intensive analytics queries
- [Run ad-hoc queries with Read Replicas](https://neon.com/docs/guides/read-replica-adhoc-queries): Leverage read replicas for running ad-hoc queries
- [Provide read-only access with Read Replicas](https://neon.com/docs/guides/read-only-access-read-replicas): Leverage read replicas to provide read-only access to your data

--- [Document source](https://neon.com/docs/introduction/regions.md) ---

> Summary: Neon projects deploy to AWS regions. The region is fixed at project creation and cannot be changed afterward. Use this page to choose a region close to your application server, or to find NAT gateway IP addresses for outbound connection allowlists. To move data to a different region, create a new project there and migrate.

# Regions

Last updated: 2026-10-14

Neon offers project deployment in multiple AWS regions. To minimize latency between your Neon database and application, we recommend choosing the region closest to your application server.

Each Neon **project** exists in exactly one region. Your database runs in that region. **You cannot change the region** for an existing project. If you need your **data** in a different region, you **create a new Neon project** in that region and **migrate your database** there. You are not moving the project; region is fixed when the project is created.

## AWS regions

- 🇺🇸 AWS US East (N. Virginia) — `aws-us-east-1`
- 🇺🇸 AWS US East (Ohio) — `aws-us-east-2`
- 🇺🇸 AWS US West (Oregon) — `aws-us-west-2`
- 🇩🇪 AWS Europe (Frankfurt) — `aws-eu-central-1`
- 🇬🇧 AWS Europe (London) — `aws-eu-west-2`
- 🇸🇬 AWS Asia Pacific (Singapore) — `aws-ap-southeast-1`
- 🇦🇺 AWS Asia Pacific (Sydney) — `aws-ap-southeast-2`
- 🇧🇷 AWS South America (São Paulo) — `aws-sa-east-1`

## Azure regions

**Warning: Azure regions deprecation**

Neon Azure regions (`azure-eastus2`, `azure-westus3`, `azure-gwc`) are deprecated. You can no longer create new projects in Azure regions. Projects on the Free plan that have been inactive for 90 days or more are subject to deletion as of October 5, 2026.

If you have projects in Azure regions, see [Azure regions deprecation](https://neon.com/docs/import/azure-regions-deprecation) for what's changing and your options.

## Product availability

You can create a project in any region listed above, but not every backend product is available in every region yet. Postgres and Managed Better Auth run in all regions. Object Storage, Functions, the AI Gateway, and Realtime are rolling out region by region.

| Region                           | Postgres | Managed Better Auth | Object Storage | Functions | AI Gateway | Realtime |
| :------------------------------- | :------: | :-----------------: | :------------: | :-------: | :--------: | :------: |
| `aws-us-east-1` (N. Virginia)    |     ✅    |          ✅          |        ✅       |     ✅     |      ✅     |     ✅    |
| `aws-us-east-2` (Ohio)           |     ✅    |          ✅          |        ✅       |     ✅     |      ✅     |     ✅    |
| `aws-us-west-2` (Oregon)         |     ✅    |          ✅          |        —       |     —     |      —     |     —    |
| `aws-eu-central-1` (Frankfurt)   |     ✅    |          ✅          |        ✅       |     ✅     |      ✅     |     ✅    |
| `aws-eu-west-2` (London)         |     ✅    |          ✅          |        —       |     —     |      —     |     —    |
| `aws-ap-southeast-1` (Singapore) |     ✅    |          ✅          |        ✅       |     ✅     |      ✅     |     ✅    |
| `aws-ap-southeast-2` (Sydney)    |     ✅    |          ✅          |        —       |     —     |      —     |     —    |
| `aws-sa-east-1` (São Paulo)      |     ✅    |          ✅          |        —       |     —     |      —     |     —    |

The AI Gateway is available on any plan with [prepaid credits](https://neon.com/docs/ai-gateway/prepaid-credits).

For the latest details and usage limits, see each product's overview: [Lakebase Postgres](https://neon.com/docs/postgres/overview), [Managed Better Auth](https://neon.com/docs/auth/overview), [Object Storage](https://neon.com/docs/storage/overview), [Functions](https://neon.com/docs/compute/functions/overview), [AI Gateway](https://neon.com/docs/ai-gateway/overview).

## Request a region

> **Request a new Provider / Region**
>
> Looking for Neon in a different cloud provider or region? Submit a request through [Neon support](https://neon.com/docs/introduction/support) or let us know in the [Neon Discord](https://neon.com/discord).

## Select a region for your Neon project

You can select the region for your Neon project during project creation. See [Create a project](https://neon.com/docs/manage/projects#create-a-project).

All branches and databases created in a Neon project are created in the region selected for the project.

**Note:** After you select a region for a Neon project, it cannot be changed for that project. To run your database in a different region, create a **new** project there and migrate your data. See [Region migration](https://neon.com/docs/import/region-migration).

## Check which region your project uses

To find the region an existing project runs in, use any of these:

- **Console:** open the project and check the **Project** panel on the **Overview** page. The region is listed in the **Region** row.
- **CLI:** run `neon projects list` or `neon projects get <project_id>`. The output includes the region ID (for example, `aws-us-east-2`).
- **Connection string:** the region is the segment before `.aws.neon.tech` in the hostname. For example, `us-east-2.aws.neon.tech` is AWS US East (Ohio).
- **API:** read the `region_id` field from `GET /projects/{project_id}`.

All branches and databases in a project share the project's region, so the project region is the region for everything inside it.

## NAT Gateway IP addresses

A NAT gateway has a public IP address that external systems see when private resources initiate outbound connections. Neon uses multiple IP addresses per region for this outbound communication, with the number varying by region. To ensure proper connectivity for setups such as replicating data to Neon, you should allow access to all the NAT gateway IP addresses associated with your Neon project's region.

If you are unsure of your project's region, see [Check which region your project uses](https://neon.com/docs/introduction/regions#check-which-region-your-project-uses).

**Important: Keep your allowlist up to date**

Neon connects to external systems (for example, when replicating data into Neon from an external source) through NAT gateways, and adds NAT gateway IP addresses periodically as it expands capacity. If you allowlist Neon's outbound IPs on an external system and don't add the new addresses, those connections can fail intermittently, because Neon may route through a new IP your firewall hasn't allowed.

Allow **all** NAT gateway IP addresses listed for your project's region, not just the ones you connect through today, and add the new addresses to your allowlist after Neon expands a region. Expansions are announced in the [changelog](https://neon.com/docs/changelog).

_NAT gateway IP lists last updated: October 28, 2026._

### AWS NAT Gateway IP Addresses

| Region               | NAT Gateway IP Addresses                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aws-us-east-1`      | 100.25.69.105, 100.26.142.14, 100.30.82.73, 100.49.133.240, 100.50.65.216, 100.51.56.234, 100.56.36.16, 100.57.146.156, 100.57.146.174, 100.57.146.193, 100.57.146.194, 100.57.146.196, 100.57.146.203, 100.57.146.235, 100.57.146.29, 100.57.146.40, 100.57.146.41, 100.57.146.61, 100.57.146.71, 100.60.103.89, 100.61.221.141, 13.219.161.141, 18.211.255.174, 18.215.104.21, 18.233.124.238, 23.23.0.232, 3.213.105.99, 3.213.96.50, 3.215.46.180, 3.220.221.222, 3.220.225.247, 3.220.64.214, 3.222.32.110, 3.225.140.235, 3.91.130.130, 3.93.203.54, 32.193.167.21, 32.193.20.224, 32.199.39.215, 34.193.220.216, 34.197.57.145, 34.198.227.45, 34.199.194.48, 34.202.217.219, 34.224.137.41, 34.226.172.234, 34.233.170.231, 34.233.243.3, 34.235.208.170, 34.235.208.71, 34.235.42.99, 34.239.66.10, 35.168.244.148, 35.169.34.250, 35.170.12.67, 44.195.6.75, 44.206.116.254, 44.206.76.236, 44.207.191.162, 44.209.63.35, 44.212.153.181, 44.212.197.226, 44.214.123.25, 44.221.231.26, 50.17.232.215, 52.203.31.78, 52.205.172.123, 52.205.179.214, 52.21.78.38, 52.4.26.44, 52.55.110.148, 52.6.163.215, 52.70.189.141, 52.70.242.229, 52.72.22.6, 52.73.235.120, 54.146.178.112, 54.146.212.225, 54.156.66.192, 54.158.31.163, 54.160.39.37, 54.172.132.182, 54.173.116.247, 54.197.227.141, 54.204.55.253, 54.205.208.153, 54.210.30.243, 54.225.186.135, 54.225.190.80, 54.236.248.73, 54.237.192.160, 54.82.237.132, 54.86.178.17, 54.88.155.118, 72.44.41.126, 98.84.215.244, 98.85.96.200, 98.87.212.88, 98.88.203.121, 98.88.212.99, 98.90.4.167, 98.91.34.143 |
| `aws-us-east-2`      | 13.58.218.179, 16.58.110.124, 16.58.110.255, 16.58.110.55, 16.58.78.168, 16.59.182.226, 16.59.242.134, 16.59.254.197, 16.59.67.63, 18.116.233.216, 18.117.23.33, 18.117.39.4, 18.118.172.16, 18.118.228.124, 18.119.198.133, 18.119.21.3, 18.188.221.27, 18.190.115.7, 18.217.181.229, 18.218.224.116, 18.220.57.29, 18.224.168.68, 18.224.238.162, 18.225.188.55, 18.226.197.170, 18.227.101.127, 18.227.137.94, 18.227.138.172, 3.128.125.142, 3.128.6.252, 3.129.145.179, 3.13.114.172, 3.131.221.179, 3.132.126.158, 3.133.42.168, 3.135.156.130, 3.135.177.98, 3.139.195.115, 3.139.7.20, 3.14.39.143, 3.141.218.87, 3.143.189.83, 3.143.90.29, 3.147.34.169, 3.150.222.149, 3.150.57.42, 3.150.90.85, 3.151.136.191, 3.151.193.140, 3.151.209.139, 3.151.57.14, 3.16.227.37, 3.19.194.45, 3.21.178.250, 3.21.225.88, 3.21.57.242, 3.23.194.25, 52.14.237.223, 52.15.124.181, 52.15.165.218, 52.15.50.22, 52.15.67.98                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `aws-us-west-2`      | 184.32.127.134, 34.213.87.149, 35.155.141.113, 35.164.221.218, 35.83.202.11, 44.229.51.71, 44.235.241.217, 44.236.56.140, 44.245.132.244, 44.255.125.141, 52.13.220.49, 52.32.22.241, 52.37.48.254, 52.40.99.9, 54.186.210.201, 54.213.57.47                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `aws-eu-central-1`   | 18.156.24.144, 18.157.202.178, 18.158.27.131, 18.158.63.175, 18.159.15.226, 18.184.82.97, 18.192.200.167, 18.194.181.241, 18.198.137.195, 3.120.216.35, 3.122.126.22, 3.122.142.179, 3.123.76.138, 3.124.70.9, 3.124.82.159, 3.125.214.237, 3.125.234.79, 3.125.57.42, 3.126.104.76, 3.127.13.64, 3.66.63.165, 3.74.218.49, 3.79.165.117, 3.79.211.200, 35.158.212.127, 51.102.100.131, 52.58.17.95, 54.93.82.216, 63.176.189.25, 63.176.236.186, 63.177.148.115, 63.181.154.218, 63.181.212.169, 63.181.222.221, 63.181.53.159, 63.182.111.227, 63.182.118.232, 63.183.16.12, 63.183.171.185, 63.183.38.44, 63.183.46.134, 63.184.208.180, 63.184.214.3, 63.184.241.74, 63.184.85.228, 63.185.226.93, 63.185.233.67, 63.186.108.15, 63.186.14.220, 63.186.197.52, 63.186.94.195                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `aws-eu-west-2`      | 16.60.68.174, 18.133.205.39, 18.134.194.79, 3.10.42.8, 35.178.12.220, 52.56.191.86                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `aws-ap-southeast-1` | 13.251.199.154, 18.141.120.105, 18.142.42.169, 3.1.149.186, 3.1.239.32, 47.131.90.115, 52.221.53.167, 52.74.190.151, 52.76.51.78, 54.254.50.26, 54.254.92.70, 54.255.161.23                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `aws-ap-southeast-2` | 13.237.134.148, 13.55.152.144, 54.153.185.87                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `aws-sa-east-1`      | 18.230.1.215, 52.67.111.132, 52.67.202.176, 54.232.117.41, 54.233.189.29, 56.126.102.242                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### Azure NAT Gateway IP Addresses

| Region          | NAT Gateway IP Addresses                       |
| :-------------- | :--------------------------------------------- |
| `azure-eastus2` | 48.211.218.176, 48.211.218.194, 48.211.218.200 |
| `azure-gwc`     | 20.52.100.129, 20.52.100.208, 20.52.187.150    |
| `azure-westus3` | 20.38.38.171, 20.168.0.32, 20.168.0.77         |

## Move your database to another region

A Neon project's region does not change after creation. To use another region, create a **new** project there and migrate your data. See **[Region migration](https://neon.com/docs/import/region-migration)** for paths, prerequisites, and steps.

--- [Document source](https://neon.com/docs/introduction/roadmap.md) ---

> Summary: Neon's public product roadmap tracks what is in flight, recently shipped, and planned across compute, storage, security, and cloud regions. Planned features include higher storage and compute limits, CMK encryption, and RBAC. Recently shipped milestones include Postgres 18 GA, a major write throughput improvement, Managed Better Auth GA, and the AI agent pricing plan.

# Roadmap

Last updated: 2026-11-05

This roadmap describes what's in flight, what we delivered recently, and what's on the horizon.

## Backend primitives for apps and agents

We've expanded Neon with [a branchable stack of backend primitives](https://neon.com/blog/were-building-backends). Managed Better Auth, Functions, Object Storage, and AI Gateway are now generally available alongside Lakebase Postgres, and Realtime is in public beta. See [What we've shipped recently](https://neon.com/docs/introduction/roadmap#what-weve-shipped-recently-). Here's what we're working on next.

- **Realtime general availability**: Realtime is in public beta and moving toward general availability. [Learn more](https://neon.com/docs/realtime/overview).
- **More regions for backend services**: Functions, Object Storage, AI Gateway, and Realtime are expanding beyond their current AWS regions. [Learn more](https://neon.com/docs/introduction/regions).

## Core Postgres database features and improvements

We're also improving and scaling Lakebase Postgres on Neon. Here's what's on the roadmap.

### Backups & restore

- Externally exported backups
- Integration with external backup systems
- Cross-region branch snapshots and exported backups
- Cross-cloud branch snapshots and exported backups
- Branch recovery, so you can restore a deleted branch during a short recovery period
- Snapshots on non-root branches

### Security

- Custom key support for encryption at rest
- Customer-managed key (CMK) support for application-level encryption
- Kerberos and LDAP authentication support
- Mutual TLS connections

### Clouds & regions

- Region expansion for paid plan users. Let us know where you want to see Neon next: [Request a region](https://neon.com/docs/introduction/regions)

### Integrations

- Vercel OIDC support, so Vercel apps can connect to Neon with a short-lived Vercel OIDC token instead of a static password

### Database storage

- Increased ingestion speeds
- Continued storage scaling

### Postgres compute

- **Postgres 19 support**: We support Postgres 14 through 18 today, with Postgres 19 support on the way.
- Fixed compute sizes up to 128 CUs
- Autoscaling up to 60 CUs
- Automatic updates for large computes, with no manual restart required
- Scale to zero for computes larger than 16 CU

### Account security

- Role-based access control (RBAC) roles extended into the database
- Self-serve audit logs of all database access
- Single sign-on (SSO) and SCIM user provisioning for organizations

### High availability

- Cross-availability zone (AZ) highly available compute
- Cross-AZ, cross-region, and cross-cloud disaster recovery

## What we've shipped recently 🚢

- **AI Gateway credits for all accounts**: You no longer need a paid plan to use the AI Gateway. Free plan organization admins can buy prepaid credits from $5 under **Billing** in the Console. [Learn more](https://neon.com/docs/ai-gateway/prepaid-credits).
- **Recover deleted projects from the Console**: Recover a deleted project from the **Projects** page for 7 days after deletion, in addition to the CLI and API. [Learn more](https://neon.com/docs/manage/projects#recover-a-deleted-project).
- **Automatic updates for computes up to 16 CU**: Every compute up to 16 CU, including all autoscaling computes, now gets compute updates automatically, with no manual restart required. [Learn more](https://neon.com/docs/manage/updates).
- **Give your app its own MCP server**: Run an MCP server on Functions with the Managed Better Auth OAuth provider plugin, so your users can reach your app from AI agents with their existing accounts. [Read the blog post](https://neon.com/blog/managed-better-auth-oauth-provider-mcp).
- **More coding agents supported by `neon init`**: Factory Droid, fx, Hermes Agent, Junie, Kilo Code, Kimi Code, Kiro CLI, and Pi join more than 20 coding agents you can connect to Neon with one command. [Learn more](https://neon.com/docs/ai/connect-mcp-clients-to-neon#supported-agents-add-mcp).
- **New Functions templates**: Twenty new Function Registry templates cover AI agents and chat, APIs, workflows, email, uploads, and monitoring, including an MCP server, `openai-agents`, `mastra`, and `x402-paid-api`. They combine Functions with Postgres, AI Gateway, Object Storage, and Managed Better Auth. [Learn more](https://neon.com/functions/templates).
- **Managed Better Auth general availability**: Managed Better Auth is now generally available. Check the [Managed Better Auth roadmap](https://neon.com/docs/auth/roadmap) for upcoming plugins and features. [Learn more](https://neon.com/docs/auth/overview).
- **HIPAA support for backend services**: HIPAA compliance now extends to Managed Better Auth, the Data API, Functions, Object Storage, AI Gateway, and Realtime, so you can use them with protected health information in a HIPAA-enabled project. [Learn more](https://neon.com/docs/security/hipaa).
- **Set up your coding agent for Neon**: One prompt installs the Neon CLI, signs you in, and adds Neon's agent skills and MCP server. Each backend service overview page also has a prompt that builds a working example in your project. [Learn more](https://neon.com/docs/cli/skills).
- **Apple and Microsoft sign-in for Managed Better Auth**: Managed Better Auth now supports Apple and Microsoft Entra ID as OAuth providers, alongside Google, GitHub, and Vercel. [Learn more](https://neon.com/docs/auth/guides/setup-oauth).
- **Tune Lakebase Search indexes**: `lakebase_vector` 1.1.2 adds functions that recommend `lakebase_ann.probes` settings for your index, so you can trade off recall and latency without trial and error. [Learn more](https://neon.com/docs/extensions/lakebase-vector#get-recommended-probes-values).
- **Gemini 4 Argon on the AI Gateway**: Google's Gemini 4 Argon is now available through the chat completions or native Gemini endpoint, with a 1M-token context window and text, image, video, audio, and PDF input. [Learn more](https://neon.com/docs/ai-gateway/models/gemini-4-argon).
- **Jev decision models on the AI Gateway**: TypeSafe's Jev 1.14 and the open-weights OpenJev answer questions about your input with a choice, a score, or a probability your code can act on, billed for input tokens only. [Learn more](https://neon.com/docs/ai-gateway/decisions).
- **Automatic top-up for AI Gateway credits**: Organization admins can turn on auto-reload so Neon buys more AI Gateway credits with your card on file when your balance drops below a threshold you set. [Learn more](https://neon.com/docs/ai-gateway/prepaid-credits#automatic-top-up).
- **OAuth provider for Managed Better Auth (beta)**: Managed Better Auth can act as an OAuth 2.1 authorization server, so your users can sign in to your MCP server, API, or other apps with their existing accounts. [Learn more](https://neon.com/docs/auth/guides/plugins/oauth-provider).
- **Scaffold functions and search the docs from the Neon CLI**: `neon functions new` scaffolds a Neon Function from a template, and `neon docs search` searches neon.com from your terminal. [Learn more](https://neon.com/docs/cli/functions#new).
- **Support center in the Console**: Ask the AI assistant, open a support ticket, or reach the community from one place under **Help** > **Get help** in your organization menu. [Learn more](https://neon.com/docs/introduction/support#open-the-support-center).
- **Neon Realtime (public beta)**: Turn any SQL query into a live query that stays up to date as your data changes, running directly from Lakebase Postgres with support for scale to zero and branching. [Learn more](https://neon.com/docs/realtime/overview).
- **Sync Stripe data to Neon in real time**: Stripe Data Pipeline can now stream your Stripe data into a Neon database and keep it in sync, so you can join payments and subscriptions with your app data without webhook handlers. [Read the blog post](https://neon.com/blog/stripe-data-pipeline-realtime-sync-to-postgres).
- **CJK full-text search in Lakebase Search**: The `lakebase_tokenizer` extension now splits Chinese, Japanese, and Korean text into search terms, so you can run keyword and BM25 search over CJK content. [Learn more](https://neon.com/docs/extensions/lakebase-tokenizer#cjk-text).
- **New AI Gateway models**: Eleven new models from Anthropic, OpenAI, Google, xAI, and open-weight providers joined the AI Gateway catalog, including `claude-sonnet-5-5` and `gpt-6-sol`. [Learn more](https://neon.com/docs/ai-gateway/overview#available-models).
- **All AI Gateway models with prepaid credits**: Paid plan users with prepaid credits can now call every model in the AI Gateway catalog, including frontier models from OpenAI, Anthropic, and Google, without requesting access. [Learn more](https://neon.com/docs/ai-gateway/models#available-models).
- **Send feedback from the CLI and MCP server**: Send feedback to Neon with `neon feedback` in the Neon CLI or the `send_feedback` tool in the Neon MCP server. Only your message is sent, with no account or project details. [Learn more](https://neon.com/docs/introduction/feedback).
- **Enable backend services at project creation**: Turn on Object Storage, Functions, AI Gateway, and Auth alongside Postgres when you create a project, so it comes up with your whole stack ready. [Learn more](https://neon.com/docs/manage/projects#create-a-project).
- **More storage on the Free plan**: The Neon Free plan now includes 1 GB of database storage per project, up from 0.5 GB, applied automatically to existing projects. [Learn more](https://neon.com/docs/introduction/plans).
- **Embedding models in the AI Gateway**: Turn text into vectors through the same OpenAI-compatible endpoint and Neon credential you use for chat, with `/v1/embeddings` support for `qwen3-embedding-0-6b` and `gte-large-en`. [Learn more](https://neon.com/docs/ai-gateway/embeddings).
- **Effect bindings for the Neon SDK**: The new `@neon/effect` package wraps the Neon Management SDK in Effect v4, so API calls return typed `Effect` values and paginated lists return a `Stream`. [Learn more](https://neon.com/docs/reference/effect-sdk).
- **Reset Object Storage from parent**: Reset from parent now rolls back a branch's Object Storage along with its Postgres data, reverting uploads, overwrites, and deletes made on the branch. [Learn more](https://neon.com/docs/guides/reset-from-parent).
- **Function Triggers**: Invoke a deployed Function on a UTC cron schedule or when a file lands in an Object Storage bucket, even when the compute is scaled to zero. [Learn more](https://neon.com/docs/compute/functions/triggers/overview).
- **Custom domains for Functions**: Serve a Function's public API or webhook on a domain you own, with Neon provisioning the TLS certificate automatically. [Learn more](https://neon.com/docs/compute/functions/custom-domains).
- **Prepaid credits for the AI Gateway**: Buy prepaid credits for the AI Gateway from the Console and draw them down as you send inference requests, at provider list prices with no markup. [Learn more](https://neon.com/docs/ai-gateway/prepaid-credits).
- **Neon tools for agents with `@neon/tools`**: Hand your AI agent typed, function-calling tools for managing Neon that stay in sync with the API, with adapters for MCP, Mastra, and Eve. [Read the announcement](https://neon.com/blog/give-your-agent-neon-tools).
- **Faster queries on large computes**: On fixed-size computes of 18 CU and above, shared buffers now expand to use up to 75% of memory backed by huge pages, so cache-heavy workloads can see up to 2x throughput with no restart. [Read the blog post](https://neon.com/blog/improving-lakebase-compute-cache-part-1).
- **Neon in Grok Bot**: The Neon plugin is now available in Grok Bot, pairing Neon agent skills with the Neon MCP server so you can create projects and branches and run SQL from a Grok bot. [Learn more](https://neon.com/docs/ai/agent-setup/grok-bot).
- **Neon MCP server as a Claude connector**: The Neon MCP server is now listed in Claude's connector directory, so you can create projects and branches, run SQL, change schemas, and diagnose slow queries from Claude.ai or Claude Desktop. [Learn more](https://neon.com/docs/ai/agent-setup/claude-ai).
- **AI Gateway as a Vercel AI SDK provider**: The Neon AI Gateway is now a community provider for the Vercel AI SDK, so you can reach frontier and open-source models through one credential built into your branch and swap models without per-provider SDKs or keys. [Learn more](https://neon.com/docs/ai-gateway/overview).
- **Project-level permissions**: Grant people and agents Viewer, Editor, or Admin access on individual projects instead of across your whole organization, on top of four organization roles (Admin, Editor, Viewer, Collaborator). Now available to all organizations. [Learn more](https://neon.com/docs/manage/user-permissions).
- **API keys and profiles in the Neon CLI**: New `neon api-keys` and `neon profile` commands let you mint account, organization, or project-scoped keys and switch between multiple accounts from the terminal. [Learn more](https://neon.com/docs/cli/api-keys).
- **More models on the AI Gateway**: The AI Gateway catalog expanded with Kimi K3, GLM-5.2, Inkling, and new Gemini and GPT models, all reachable through one credential and one base URL. [Learn more](https://neon.com/docs/ai-gateway/overview#available-models).
- **New Console layout for the Neon backend**: The Console sidebar now places every branch-level backend service (Auth, Object Storage, Functions, AI Gateway) alongside your Postgres database, with a branch Overview page that shows each service's status. [Learn more](https://neon.com/docs/get-started/backend-overview).
- **Debug Postgres from the CLI with `neon inspect db`**: Run read-only Postgres diagnostics (table sizes, bloat, unused indexes, long-running queries, locks, and more) straight from the Neon CLI, safe to hand to an agent. [Learn more](https://neon.com/docs/cli/inspect).
- **Snapshots in the Neon CLI**: The new `neon snapshots` command group manages the full snapshot lifecycle (list, create, restore, and schedule) from your terminal. [Learn more](https://neon.com/docs/cli/snapshots).
- **Query Functions and Storage logs from the Neon MCP server**: New read-only `query_logs`, `list_log_fields`, and `list_log_field_values` tools let your AI assistant investigate Functions and Object Storage failures without leaving your editor. [Learn more](https://neon.com/docs/ai/neon-mcp-server).
- **Neon backend services**: Object Storage, Functions, and AI Gateway are generally available in AWS US East (Ohio), US East (N. Virginia), Europe (Frankfurt), and Asia Pacific (Singapore). Support is expanding toward all regions. Declare your whole backend in one `neon.ts` file and it branches with your data. [Read the announcement](https://neon.com/blog/neon-backend-is-ga).
- **New TypeScript SDK for the Neon API**: `@neon/sdk` is a fetch-based, zero-dependency client that covers the full Neon Platform API, including the new backend services, and replaces `@neondatabase/api-client` as the recommended client. [Learn more](https://neon.com/docs/reference/typescript-sdk).
- **Passkey support**: Sign in to Neon with a passkey using device biometrics or a security key. Passkeys satisfy organization-level 2FA requirements. [Learn more](https://neon.com/docs/manage/accounts#passkeys).
- **Git-style diffs in the Neon CLI**: The new `neon diff` command shows schema changes between your current branch and any other branch, and the config commands now report their changes as a git diff. [Learn more](https://neon.com/docs/cli).
- **New `neon api` command**: Call any Neon Platform API route from the terminal using your existing CLI login, without hand-building `curl` requests or handing agents raw API keys. [Learn more](https://neon.com/docs/cli/api).
- **Cmd+K in the Neon Console**: Press `Cmd+K` (or `Ctrl+K`) anywhere in the Console to open a searchable command bar with actions scoped to your current branch and project.
- **Neon CLI is now `neon`**: Install the CLI as `neon` (`npm i -g neon`) instead of `neonctl`, scaffold a `neon.ts` config with `neon config init`, and print your current branch with no network call using `neon status`. [Learn more](https://neon.com/docs/cli/install).
- **Lakebase Search**: Vector and BM25 full-text search are now available to all users on Postgres 16+ through the `lakebase_vector` and `lakebase_text` extensions, so you can run semantic, keyword, and hybrid search in Postgres without a separate search stack. [Learn more](https://neon.com/docs/ai/lakebase-search)
- **neon.ts**: A TypeScript config file you commit to your repo to declare branch policies, compute settings, and Neon services as code. Apply changes with `neon deploy` and preview them with `neon config plan`. [Learn more](https://neon.com/docs/reference/neon-ts)
- **Branch-first development workflow**: New CLI commands (`neon link`, `neon checkout`, `neon env pull`, `neon psql`, `neon data-api`) bring project linking and branch switching to the terminal. Your `DATABASE_URL` updates automatically when you check out a branch. [Learn more](https://neon.com/docs/cli)
- **More network transfer on paid plans**: The public network transfer allowance on all paid plans increased from 100 GB to 500 GB per project per month. [Learn more](https://neon.com/docs/introduction/network-transfer)
- **Schema Diff for larger schemas**: The schema comparison line limit has been raised from 8,000 to 20,000 lines, unblocking diffs on larger production schemas. [Learn more](https://neon.com/docs/guides/schema-diff).
- **Per-branch consumption metrics**: A new API endpoint returns compute, storage, and transfer usage broken down by branch, making it easier to attribute costs in multi-branch workflows. [Learn more](https://neon.com/docs/guides/consumption-metrics).
- **Neon MCP Server branch forking**: The `create_branch` MCP tool now accepts a `parentId` parameter so agents can fork any branch, not only the project default. [Learn more](https://neon.com/docs/ai/neon-mcp-server).
- **Higher manual snapshot limits**: Paid plans (Launch and Scale) now include 100 manual snapshots per project, up from 10. [Learn more](https://neon.com/docs/guides/backup-restore).
- **Managed Better Auth new plugins**: Magic Link sign-in, phone number (OTP) sign-in, wildcard trusted domains, and custom application name configuration are now available in Managed Better Auth. [Learn more](https://neon.com/docs/auth/guides/plugins/magic-link).
- **Managed Better Auth MCP tools**: Two new Neon MCP Server tools (`configure_neon_auth` and `get_neon_auth_config`) let you set up and inspect your Managed Better Auth configuration from your AI editor using natural language. [Learn more](https://neon.com/docs/ai/neon-mcp-server).
- **Faster writes**: Neon disabled full-page writes (FPW) across all projects, delivering up to 5x write throughput improvement with no changes required on your end. [Read the announcement](https://neon.com/blog/turning-off-fpw-for-faster-writes).
- **Require 2FA for your organization**: Org admins can now enforce two-factor authentication for all members from Organization Settings. [Learn more](https://neon.com/docs/manage/orgs-manage#require-2fa-for-organization-members).
- **One-click Neon MCP setup for Kiro**: The Neon MCP Server now supports an Add to Kiro badge for one-click MCP setup in the Kiro IDE. [Learn more](https://neon.com/docs/ai/connect-mcp-clients-to-neon).
- **Postgres 18 general availability**: Postgres 18 is now generally available on Neon. [Read the announcement](https://neon.com/blog/postgres-18).
- **Organization spending notifications**: Set a monthly spending threshold for your organization from the Billing page and receive email alerts when you reach 80% and 100% of that threshold. [Learn more](https://neon.com/docs/introduction/spending-notifications).
- **Neon plugin for OpenAI Codex**: The Neon plugin is now available in the OpenAI Codex plugin directory, adding the Neon MCP Server and Agent Skills to Codex so you can manage projects, branches, and databases from chat. [Learn more](https://neon.com/docs/ai/agent-setup/codex)
- **Lakebase Postgres in Stripe Projects**: Neon is now part of Stripe Projects, so you can provision a Neon database as part of a Stripe CLI app setup alongside other services. [Read the announcement](https://neon.com/blog/neon-works-with-stripe-projects-for-agentic-provisioning)
- **Automatic cache prewarming**: Neon now prewarms your compute's in-memory cache during scheduled compute updates, protecting query performance immediately after the update restarts Postgres. [Read the blog post](https://neon.com/blog/prewarming)
- **Unlimited org members on the Free plan**: You can now add unlimited members to each organization on the Free plan. The members API supports pagination and sorting, and the Console shows a 2FA indicator per member. [Learn more](https://neon.com/docs/manage/orgs-manage).
- **Managed Better Auth organization settings and webhooks**: Configure Managed Better Auth Organizations from the Console (**Settings** > **Better Auth**, per branch) and use webhooks to receive HTTP callbacks for auth events (OTP, magic link, user creation). [Learn more](https://neon.com/docs/auth/guides/plugins/organization) and [Webhooks](https://neon.com/docs/auth/guides/webhooks).
- **Network transfer guide and egress optimizer agent skill**: A new guide explains how to monitor and reduce network transfer costs. An agent skill helps your AI assistant diagnose and fix query patterns that cause excessive egress. [Learn more](https://neon.com/docs/introduction/network-transfer).
- **Two-factor authentication (2FA)**: Enable 2FA from Account settings for an extra layer of security at login. [Learn more](https://neon.com/docs/manage/accounts#two-factor-authentication).
- **Data API advisors**: A new Monitoring tab scans your database when you use the Data API and reports security and performance issues (such as missing RLS or unindexed foreign keys) with recommended fixes. [Learn more](https://neon.com/docs/data-api/database-advisor).
- **Cursor plugin for Neon**: The Neon plugin adds Neon Skills and MCP to Cursor so your assistant can use workflow guidance and run database operations from natural language. [Learn more](https://neon.com/docs/ai/agent-setup/cursor).
- **Neon CircleCI orb**: A community-contributed orb provisions a Neon database branch per job for isolated, production-like CI. [Learn more](https://neon.com/docs/guides/branching-circleci).
- **Add organization members by domain**: Verify email domains on the organization People page so users with matching addresses automatically join your org. [Learn more](https://neon.com/docs/manage/orgs-add-members-by-domain).
- **TimescaleDB on Postgres 18**: The timescaledb extension is now supported on Postgres 18. [Learn more](https://neon.com/docs/extensions/timescaledb).
- **Claimable Neon**: Agents can provision a temporary Neon project with no signup or credit card, then a human claims it. [Learn more](https://neon.com/docs/reference/claimable-neon).
- **Neon MCP Server documentation tools**: The MCP Server now includes `list_docs_resources` and `get_doc_resource` so your agent can fetch Neon docs on demand. [Learn more](https://neon.com/docs/ai/neon-mcp-server).
- **Compute autoscaling report**: A published report compares Neon autoscaling to provisioned compute using real production workloads, with methodology and key findings. [Learn more](https://neon.com/autoscaling-report).
- **Consumption history API**: The consumption history API is now available on all paid plans. You can use it with Neon's usage-based pricing plans to track usage programmatically: query compute, storage, and data transfer at hourly, daily, or monthly granularity for custom dashboards and alerts. [Learn more](https://neon.com/docs/guides/consumption-metrics).
- **Simpler MCP Server setup**: Configure the Neon MCP Server for all detected AI agents and editors with a single command: `npx add-mcp https://mcp.neon.tech/mcp`. OAuth opens in your browser to authorize access. For full setup (MCP plus agent skills and VS Code extension), use `npx neon@latest init`. [Learn more](https://neon.com/docs/ai/connect-mcp-clients-to-neon).
- **Claimable Neon REST API**: Claimable Neon offers an auth.md agent API for programmatic project provisioning. [Learn more](https://neon.com/docs/reference/claimable-neon).
- **Managed Better Auth SDK simplified**: The server-side Managed Better Auth SDK for Next.js now uses a unified `createNeonAuth()` API, explicit configuration, and session caching that reduces Auth Server API calls by 95–99%. [Learn more](https://neon.com/docs/auth/migrate/from-auth-v0.1).
- **Agent Skills**: Install [Agent Skills](https://github.com/neondatabase/agent-skills) to teach your AI assistant about Neon best practices. The Neon MCP Server can also provision the Data API with optional Managed Better Auth or external auth. [Learn more](https://neon.com/docs/ai/connect-mcp-clients-to-neon).
- **Managed Better Auth on Vercel previews**: Both Vercel-managed and Neon-managed integrations now automatically provision Managed Better Auth on preview branches when enabled on production, so preview deployments get the right auth environment variables. [Learn more](https://neon.com/docs/auth/overview).
- **One-command setup for MCP and VS Code extension**: `npx neon@latest init` now configures both the Neon MCP Server and the Neon VS Code Extension in one step for Cursor or VS Code. [Learn more](https://neon.com/docs/ai/agent-setup).
- **Expanded `neon init`**: [`neon init`](https://neon.com/docs/cli/init) sets up your project with agent tooling (either a plugin, or skills and the MCP server) for many more coding assistants (for example Claude Desktop, Codex, Zed, Gemini CLI, and GitHub Copilot CLI), not only Cursor, VS Code, and Claude Code. [Learn more](https://neon.com/docs/cli/init).
- **New Neon VS Code extension**: A revamped extension that replaces the previous Neon Local extension. It uses direct Neon connection strings and brings schema browsing, SQL editing, and table data into your IDE, plus automatic MCP Server configuration. Available for VS Code, Cursor, Windsurf, and other compatible editors. [Learn more](https://neon.com/docs/local/vscode-extension).
- **Connection pooling metrics**: Pooler client and server connection graphs are now available in the Neon Console and via OpenTelemetry and Datadog integrations, so you can monitor PgBouncer usage and tune pool size. [Learn more](https://neon.com/docs/introduction/monitoring-page).
- **GitHub Action support for Managed Better Auth and Data API**: The Neon Create Branch GitHub Action now supports `get_auth_url` and `get_data_api_url` outputs, so you can run integration tests against isolated branch environments with the same auth and data access patterns as production. [Learn more](https://github.com/marketplace/actions/neon-create-branch-github-action).

<details>

<summary>Shipped in 2025</summary>

- **Postgres 18**: Now the default version for all newly created projects.
- **Project recovery**: Accidentally deleted a project? You can now recover it within 7 days of deletion. This feature restores your entire project infrastructure, including all branches, endpoints, compute configurations, and project settings. [Learn more](https://neon.com/docs/manage/projects#recover-a-deleted-project).
- **100 Free plan projects**: The Neon Free plan now includes 100 projects, giving you plenty of room to experiment, prototype, and build. [Learn more](https://neon.com/docs/introduction/plans).
- **Now built on Better Auth**: Managed Better Auth now uses [Better Auth](https://www.better-auth.com/) as the foundation. All authentication data lives directly in your Neon database, so when you branch, your entire auth state branches with it. Users, sessions, organizations, and configuration are stored in a dedicated `neon_auth` schema. [Read the announcement](https://neon.com/blog/neon-auth-branchable-identity-in-your-database).
- **Purely usage-based billing**: We've removed the $5 monthly minimum from our paid plans. Neon is now purely usage-based: if you use $3 one month, that's the bill you'll receive. [Learn more](https://neon.com/docs/introduction/plans).
- **One-command MCP setup**: Connecting AI editors to the Neon MCP Server is now a single command: `npx neon@latest init`. This command authenticates via OAuth, automatically creates a Neon API key, and configures Cursor, VS Code, or Claude Code CLI to connect to Neon. [Learn more](https://neon.com/docs/ai/agent-setup/cursor).
- **Data masking with console support**: Create anonymized branches with data masking directly from the Neon Console. [Learn more](https://neon.com/docs/workflows/data-anonymization).
- **Neon is now a Kiro Power**: Manage your Postgres databases directly from the Kiro IDE. Deploy instantly, branch for safe testing, and time-travel to restore from any past state. [Read the announcement](https://neon.com/blog/just-launched-neon-is-now-a-kiro-power).
- **Custom Neon agents for GitHub Copilot**: We've built two specialized agents that bring Neon's branching workflow directly into your IDE: the Neon Migration Specialist for safe Postgres migrations and the Neon Performance Analyzer for identifying and fixing slow queries. [Learn more](https://neon.com/docs/ai/agent-setup/vscode).
- **Data API advanced settings**: Added OpenAPI mode for automatic schema generation and server timing headers for debugging slow queries and measuring performance. [Learn more](https://neon.com/docs/data-api/manage).
- **Platform integration paths**: Whether you're building an agent platform, a developer tool, or a SaaS that offers databases to users, there's a [platform integration path](https://neon.com/docs/guides/platform-integration-overview) designed for your use case, including AI Agents integration, Claimable database flow, Embedded Postgres, and OAuth integration.
- **HIPAA support for Postgres 18**: HIPAA compliance is now supported for Postgres 18 projects in AWS regions. [Learn more](https://neon.com/docs/security/hipaa).
- **Backup scheduling**: Automate snapshots with daily, weekly, or monthly backup schedules with configurable retention periods. Available on paid plans (excluding the Agent plan). [Learn more](https://neon.com/docs/guides/backup-restore).
- **Postgres 18 support**: Postgres 18 is now available on Neon. [Read the announcement](https://neon.com/blog/postgres-18).
- **AI agent plan**: An AI agent pricing plan for platforms that need to provision thousands of databases. [Learn more](https://neon.com/use-cases/ai-agents).
- **Usage-based pricing plans**: Our paid plans are fully usage-based. Pay only for what you use. See [Neon plans](https://neon.com/docs/introduction/plans).
- **Branch expiration management**: Set a time-to-live (TTL) for Neon branches to simplify branch cleanup and management, see our [branch expiration guide](https://neon.com/docs/guides/branch-expiration).
- **Neon VS Code extension**: An extension that lets you connect to Neon and manage your database directly in your IDE. Available for VS Code, Cursor, and other compatible editors. See [Neon VS Code Extension](https://neon.com/docs/local/vscode-extension).
- **TanStack integration & new open-source tools**: Neon is now the official database partner of TanStack, with new open-source tools including a Vite Plugin for Neon to streamline fullstack development with TanStack, Vite, and Postgres.
- **Data API**: Neon's Data API feature, powered by PostgREST, is open to all Neon users. [Learn more](https://neon.com/docs/data-api/get-started).
- **Monitoring platform support**: Neon supports exporting metrics and Postgres logs to any OpenTelemetry-compatible backend, like New Relic. For details, refer to our [OpenTelemetry docs](https://neon.com/docs/guides/opentelemetry).
- **Claimable Neon**: A new way for SaaS vendors to partner with Neon to offer instant Neon projects. Let your users create a project with no registration required. [Learn more about Claimable Neon](https://neon.com/docs/reference/claimable-neon), and see our [Claimable database integration guide](https://neon.com/docs/workflows/claimable-database-integration).
- **Neon on Azure GA**: We've announced our general availability release on Azure with deeper Azure integration. [Read the announcement](https://neon.com/blog/azure-native-integration-ga).
- **Import Data Assistant**: The [Import Data Assistant](https://neon.com/docs/import/import-data-assistant) makes data import easier and faster.
- **Neon serverless driver GA**: Our JavaScript/TypeScript serverless driver has reached version 1.0.0, bringing stronger SQL injection safeguards and better performance for serverless environments.
- **Neon snapshots**: Create and manage point-in-time snapshots of your database with our new unified Backup & Restore experience.
- **Inbound logical replication GA**: Neon now fully supports Postgres logical replication for inbound data (replicating data to Neon).
- **Postgres logs in Datadog (beta)**: Stream and analyze your Postgres logs directly in your Datadog dashboard for better observability.
- **GitHub Secret Scanning**: Neon joined GitHub's Secret Scanning Partner Program to automatically detect and protect against exposed database credentials in public repositories.
- **HIPAA compliance**: You can [enable HIPAA compliance](https://neon.com/docs/security/hipaa) on any Neon project. Learn more about Neon's compliance milestones on our [Compliance page](https://neon.com/docs/security/compliance).
- **Scheduled updates**: You can now check for update notices and choose preferred update windows for Postgres updates, security patches, and Neon feature enhancements.
- **AWS São Paulo region**: Create projects in São Paulo (sa-east-1) for lower latency access from the South America and data residency within Brazil.
- **Vercel preview deployment support**: We added support for preview deployments with our **Vercel-Managed Integration**. See the [Vercel-Managed Integration guide](https://neon.com/docs/guides/vercel-managed-integration).
- **Manage your database from Cursor, Claude Desktop, or Claude Code**: Manage your Neon database directly from [Cursor](https://neon.com/guides/cursor-mcp-neon), [Claude Desktop](https://neon.com/guides/neon-mcp-server), or [Claude Code](https://neon.com/guides/claude-code-mcp-neon) using natural language, made possible by the [Neon Model Context Protocol (MCP) Server](https://github.com/neondatabase/mcp-server-neon).
- **Database branching for Vercel preview environments**: We added support for **database branching for preview environments** to the **Vercel-Managed Integration**, available from the [Vercel Marketplace](https://vercel.com/marketplace).
- **AWS London region**: Create projects in London (eu-west-2) for lower latency access from the UK and data residency within the United Kingdom.
- **Datadog integration GA**: Monitor your Neon database performance, resource utilization, and system health directly from Datadog's observability platform.
- **Save your connection details to [1Password](https://1password.com/)**: See [Save your connection details to 1Password](https://neon.com/docs/connect/connect-from-any-app#save-your-connection-details-to-1password).
- **Query monitoring in the console**: Monitor your [active queries](https://neon.com/docs/introduction/monitor-active-queries) and [query performance](https://neon.com/docs/introduction/monitor-query-performance) in the Neon Console.
- **Schema-only branches**: Create branches that include only your database schema, ideal for workflows involving sensitive data. [Learn more](https://neon.com/docs/guides/branching-schema-only).
- Support for the [postgres_fdw](https://neon.com/docs/extensions/postgres_fdw), [dblink](https://neon.com/docs/extensions/dblink), and [pg_repack](https://neon.com/docs/extensions/pg_repack) Postgres extensions.
- **Claimable Neon: No signup, instant project**: Provision a temporary Neon project with no signup, then claim it. Start at [neon.com/claimable-neon](https://neon.com/claimable-neon) or [`auth.md`](https://neon.com/auth.md).
- **Neon Chat for Visual Studio Code**: This AI-powered assistant lets you chat with the latest Neon documentation without leaving your IDE. You can find it here: [Neon VS Code Extension](https://marketplace.visualstudio.com/items?itemName=buildwithlayer.neon-integration-expert-15j6N).
- **A GitHub Copilot extension**: This extension provides chat-based access to the latest Neon documentation directly from your repository. You can find it here: [Neon Copilot Extension](https://github.com/marketplace/neon-database)
- **Schema Diff API**: Neon now supports schema checks in agentic systems and deployment pipelines with the new schema diff API endpoint. Learn more about [Schema Diff](https://neon.com/docs/guides/schema-diff), which is also available via the console and CLI.
- **Managed Better Auth**: Sync user profiles from your auth provider to your database automatically. Includes OAuth provider management - enable or disable providers (Google, GitHub, Vercel, Microsoft, and Apple). Google can use shared Managed Better Auth credentials for development, and the other providers use custom client credentials. See [Managed Better Auth](https://neon.com/docs/guides/neon-auth) for details.
- **Postgres 17**: Now the default version for all newly created projects.
- **Support for [pg_cron](https://neon.com/docs/extensions/pg_cron)**: Schedule and manage periodic jobs directly in your Postgres database with this extension.
- **Neon on AgentStack**: Integrate Neon with AgentStack to enable AI agents to create ephemeral or long-lived Postgres instances for structured data storage. Explore the [Neon tool](https://github.com/AgentOps-AI/AgentStack/blob/main/agentstack/_tools/neon/__init__.py) in AgentStack's repo.
- **Neon on Composio**: Integrate Neon's API with LLMs and AI agents via Composio. Check out the [Composio integration](https://composio.dev/tools?search=neon).
- **Higher connection limits for autoscaling configurations**: Postgres `max_connections` are now much higher. [Learn more](https://neon.com/docs/connect/connection-pooling#connection-limits-without-connection-pooling).
- **PgBouncer `default_pool_size` scaling**: The `default_pool_size` is now set according to your compute's `max_connections` setting. Previously, it was fixed at `64`. [Learn more](https://neon.com/docs/connect/connection-pooling#neon-pgbouncer-configuration-settings).
- **Managed Better Auth.js adapter**: Simplify authentication with the new [Auth.js Neon Adapter](https://authjs.dev/getting-started/adapters/neon).

</details>

<details>

<summary>Shipped in 2024</summary>

- **Larger computes**: Autoscaling now supports up to 16 CU, and fixed compute sizes up to 56 CU are available.
- **A Model Context Protocol (MCP) server for Neon**: We released an open-source MCP server, enabling AI agents to interact with Neon's API using natural language for tasks like database creation, SQL queries, and migrations. Read the blog post: [Let Claude Manage Your Neon Databases: Our MCP Server is Here](https://neon.com/blog/let-claude-manage-your-neon-databases-our-mcp-server-is-here).
- **Neon in the Azure Marketplace**: Neon is now available as an [Azure Native Integration](https://azuremarketplace.microsoft.com/en-us/marketplace/apps/neon1722366567200.neon_serverless_postgres_azure_prod?tab=Overview), enabling developers to deploy Lakebase Postgres databases directly from the Azure portal. [Read the announcement](https://neon.com/blog/neon-is-now-available-as-an-azure-native-integration).
- **Archive storage**: To minimize storage costs, we now support automatic archiving of inactive branches (snapshots of your data) in cost-efficient object storage. For more about this feature, see [Branch archiving](https://neon.com/docs/guides/branch-archiving).
- **Organizations GA**: Organization Accounts are now generally available. Create a new organization, transfer over your projects, invite your team and get started collaborating. Refer to our [Organizations docs](https://neon.com/docs/manage/organizations) to learn more.
- **Private Networking**: Private and secure network access to your compute resources without traversing public networks. Support for [AWS PrivateLink](https://neon.com/docs/guides/neon-private-networking) is available.
- **Schema Diff GitHub Action**: This action uses our [Schema Diff](https://neon.com/docs/guides/schema-diff) feature to compare database schemas across branches and post the differences as a comment on your pull request, streamlining the review process. It's also supported with our [Neon GitHub integration](https://neon.com/docs/guides/neon-github-integration).
- **Import Data Assistant**: Helps you migrate data to Neon from other Postgres databases. All you need to get started is a connection string for your existing database. See [Import Data Assistant](https://neon.com/docs/import/import-data-assistant) for instructions.
- **Python SDK**: Our new [Python SDK](https://pypi.org/project/neon-api/) wraps the [Neon API](https://neon.com/docs/reference/api), allowing you to manage Neon directly from your Python applications.
- **Neon in the Vercel Marketplace**: Neon is now a first-party native integration in the Vercel Marketplace. This integration lets Vercel users add Postgres to their projects and manage billing directly through Vercel. For details, see the [Vercel-Managed Integration guide](https://neon.com/docs/guides/vercel-managed-integration).
- **Archive storage on the Free plan**: Archive storage is now available on the Free plan for automatically archiving inactive branches. This feature helps minimize storage costs, allowing us to expand the Free plan even further. Learn more in [Branch Archiving](https://neon.com/docs/guides/branch-archiving).
- **Neon RLS**: This feature integrates with third-party **authentication providers** like Auth0, Clerk, and Stack Auth to bring authorization to your code base by leveraging Postgres [Row-Level Security (RLS)](https://www.postgresql.org/docs/current/ddl-rowsecurity.html). [Read the announcement](https://neon.com/blog/introducing-neon-authorize) and check out the docs.
- **Neon on Azure**: You can deploy Neon databases on Azure, starting with the East US 2 region. This marks the first milestone on our Azure roadmap. Many more exciting updates are on the way, including deeper integrations with the Azure ecosystem. [Read the announcement](https://neon.com/blog/first-azure-region-available-in-neon).
- **End-to-end RAG pipelines in Postgres**: Shipped the open source [pgrag](https://neon.com/docs/extensions/pgrag) extension for RAG in SQL. Now deprecated; see [Lakebase Search](https://neon.com/docs/ai/lakebase-search).
- **Support for analytics with pg_mooncake**: This new extension, brought to the community by [mooncake.dev](https://mooncake.dev/), introduces native columnstore tables with DuckDB execution for _fast_ analytics directly in Postgres. [Read the announcement](https://www.mooncake.dev/blog/pgmooncake-neon).
- **Datadog integration**: Scale users can now export Neon metrics to Datadog.
- **Deletion of backup branches created by restore operations**: To help minimize storage and keep your Neon project organized, we added support for deleting obsolete backup branches created by [restore](https://neon.com/docs/guides/branch-restore) operations. Previously, these backup branches could not be removed. [Learn more](https://neon.com/docs/guides/branch-restore#deleting-backup-branches).
- **Read replicas on the Free plan**: Read Replicas are now available to all Neon users. [Read the announcement](https://neon.com/blog/create-read-replicas-in-the-free-plan)
- **ISO27110 & ISO27701 compliance**: These new certifications add to our growing list of compliance achievements. For more about Neon's compliance milestones, see [Compliance](https://neon.com/docs/security/compliance).
- **Increased limits for Neon projects**: We increased the number of projects included in all our paid plans: Launch (100 projects), Scale (1000 projects), and Business (5000 projects). More projects supports use cases such as database-per-tenant and AI agents. [Read the announcement](https://neon.com/blog/thousands-of-neon-projects-now-included-in-your-pricing-plan).
- **Postgres 17**: You can now run the very latest version of Postgres on Neon. [Read the announcement](https://neon.com/blog/postgres-17).
- **SQL Editor AI features**: We added AI features to the Neon SQL Editor, including SQL generation, AI-generated query names, and an AI assistant that will fix your queries. [Learn more](https://neon.com/docs/get-started/query-with-neon-sql-editor#ai-features).
- **Data migration support with inbound logical replication**: We've introduced inbound logical replication as the first step toward enabling seamless, low-downtime migrations from your current database provider to Neon. This feature allows you to use Neon as your development environment, taking advantage of developer-friendly tools like branching and our [GitHub integration](https://neon.com/docs/guides/neon-github-integration), even if you keep production with your existing provider. To get started, explore our guides for replicating data from AlloyDB, CloudSQL, and RDS. See [Replicate data to Neon](https://neon.com/docs/guides/logical-replication-guide#replicate-data-to-neon). Inbound logical replication also supports migrating data between Neon projects, useful for version, region, or account migrations. See [Replicate data from one Neon project to another](https://neon.com/docs/guides/logical-replication-neon-to-neon).

</details>

For more of the latest features and fixes, check our [Changelog](https://neon.com/docs/changelog), published weekly. Or watch for our Changelog email, also sent out weekly. You can also subscribe to updates using our [RSS feed](https://neon.com/docs/changelog/rss.xml).

## Share your thoughts

As always, we are listening. If you see something you like, something you disagree with, or something you'd love for us to add, let us know in our Discord feedback channel.

Share your ideas in Discord: [Leave feedback](https://discord.com/channels/1176467419317940276/1176788564890112042)

--- [Document source](https://neon.com/docs/introduction/scale-to-zero.md) ---

> Summary: Scale to Zero suspends inactive Lakebase Postgres computes after 5 minutes and reactivates them within a few hundred milliseconds on the next query, so you pay only for active compute time. Use this feature for development, test, or intermittently active production databases where always-on compute is unnecessary. Free plan users cannot disable it, but paid plan users can. Very large computes remain always active and are not eligible for scale to zero.

# Scale to Zero

Minimize costs by automatically scaling inactive databases to zero

Last updated: 2026-11-04

Neon's _Scale to Zero_ feature suspends the Neon compute that runs your Postgres database after a period of inactivity, which minimizes costs for databases that aren't always active, such as development or test environment databases, and even production databases that aren't used 24/7.

- When your database is inactive, it automatically scales to zero after 5 minutes. This means you pay only for active time instead of 24/7 compute usage. No manual intervention is required.
- Once you query the database again, it reactivates automatically within a few hundred milliseconds.

The diagram below illustrates the _Scale to Zero_ behavior alongside Neon's _Autoscaling_ feature. The compute usage line highlights an _inactive_ period, followed by a period where the compute is automatically suspended until it's accessed again.

![Compute metrics graph](https://neon.com/docs/introduction/compute-usage-graph.jpg)

Neon compute scales to zero after an _inactive_ period of 5 minutes. For Neon Free plan users, this setting is fixed. Paid plan users can disable the scale-to-zero setting to maintain an always-active compute.

**Note:** Scale to zero is only available for computes up to 16 CU in size. Computes larger than 16 CU remain always active to ensure best performance.

You can enable or disable the scale-to-zero setting by editing your compute settings. For detailed instructions, see [Configuring scale to zero for Neon computes](https://neon.com/docs/guides/scale-to-zero-guide).

[Logical replication](https://neon.com/docs/guides/logical-replication-guide) **from** Neon keeps compute active while subscribers are connected, so the database does not scale to zero. See [Logical replication in Neon](https://neon.com/docs/guides/logical-replication-neon#important-notices) for details.

--- [Document source](https://neon.com/docs/introduction/serverless.md) ---

> Summary: Neon serverless Postgres decouples storage and compute so databases provision in seconds, autoscale under load, and drop to zero when idle. No manual server sizing is required. Use this page to understand Neon's serverless model: elastic autoscaling, usage-based billing, and full PostgreSQL compatibility. Billing is compute- and storage-based; autoscaling enforces a user-set maximum to prevent unexpected costs.

# Serverless

Postgres with instant provisioning, no server management, and pay-per-usage billing

Last updated: 2026-11-07

Neon takes the world's most loved database, Postgres, and makes it serverless. As part of the Neon backend, Lakebase Postgres helps teams ship reliable and scalable applications faster.

Enabling serverless Postgres begins with Neon's [lakebase architecture](https://neon.com/docs/introduction/architecture-overview), which natively decouples storage and compute. By separating these components, Neon can dynamically scale up during periods of high activity and down to zero when idle. Developers can be hands-off instead of sizing infrastructure manually.

This serverless character also makes Neon databases highly agile and well-suited for use cases that require automatic creation, management, and deletion of a high number of Postgres databases, like [database-per-user architectures with thousands of tenants](https://neon.com/use-cases/database-per-tenant), as well as [database branching workflows](https://neon.com/branching) that accelerate development by enabling the management of dev/testing databases via CI/CD.

![Multi-tenant storage](https://neon.com/docs/introduction/neon_architecture_5.jpg)

Read our [lakebase architecture](https://neon.com/docs/introduction/architecture-overview) section for more information on how Neon is built.

## What "serverless" means to us

At Neon, we interpret "serverless" not only as the absence of servers to manage but as a set of principles and features designed to streamline your development process and optimize operational efficiency for your database.

To us, serverless means:

- **Instant provisioning**: Neon allows you to spin up Postgres databases in seconds, eliminating the long setup times traditionally associated with database provisioning.
- **No server management**: You don't have to deal with the complexities of provisioning, maintaining, and administering servers. Neon handles it all, so you can focus on your application.
- **Autoscaling**: Compute resources automatically scale up or down based on real-time demand, ensuring optimal performance without manual intervention. No restarts are required.
- **Usage-based pricing**: Your costs are directly tied to the resources your workload consumes (both compute and storage). There's no need to over-provision or pay for idle capacity.
- **Built-in availability and fault tolerance**: We've designed our architecture for high availability and resilience, ensuring your data is safe and your applications are always accessible.
- **Focus on business logic**: With the heavy lifting of infrastructure management handled by Neon, you can dedicate your time and effort to writing code and delivering value to your users.

## To us, serverless does not mean…

_That Neon only works with serverless architectures_. Neon is fully compatible with the entire PostgreSQL ecosystem. Whether you're using [Django](https://neon.com/docs/guides/django), [Rails](https://neon.com/docs/guides/ruby-on-rails), or even a bash script in your basement, if it works with Postgres, it works with Neon.

_That you have to pay per query_. Your charges are based on compute and storage usage, not the number of queries. On the [Launch plan](https://neon.com/docs/introduction/plans#launch), you pay only for the compute and storage you use, with no monthly minimum, so a low-CPU workload can run billions of queries at low cost.

_That you'll get unpredictable costs due to traffic spikes_. We provide transparency in your potential costs. You always set a maximum autoscaling limit to avoid unpredictable bills, and you can always [check your consumption](https://neon.com/docs/introduction/monitor-usage). We send you notifications if your storage usage grows quickly.

## Learn more

- [Autoscaling](https://neon.com/docs/introduction/autoscaling)
- [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero)
- [Plans and billing](https://neon.com/docs/introduction/about-billing)
- [Database-per-tenant use cases](https://neon.com/use-cases/database-per-tenant)
- [Bursty workload use cases](https://neon.com/use-cases/bursty-workloads)
- [Postgres for SaaS use cases](https://neon.com/use-cases/postgres-for-saas)

--- [Document source](https://neon.com/docs/introduction/spending-notifications.md) ---

> Summary: Spending notifications alert organization admins when monthly Neon charges on Launch and Scale plans reach 80% and 100% of a configured threshold. Projects continue running and charges accumulate until you raise the threshold or the billing cycle resets. Organization admins set, edit, or disable notifications in the Neon Console or via the Management API.

# Spending notifications

Get alerts when your organization's Neon spending approaches a threshold you set

Last updated: 2026-11-05

**What you will learn:**

- What spending notifications do
- Who can set them up
- How to enable, edit, and disable notifications in the Console
- How to manage notification thresholds with the Neon CLI or Management API
- What happens when the threshold is reached

**Related topics**

- [Manage billing](https://neon.com/docs/introduction/manage-billing)
- [Monitor billing and usage](https://neon.com/docs/introduction/monitor-usage)
- [Cost optimization](https://neon.com/docs/introduction/cost-optimization)
- [Neon API keys](https://neon.com/docs/manage/api-keys#create-an-api-key)

## About spending notifications

Spending notifications help you keep track of your organization's Neon spending. When charges approach the threshold you set, organization admins receive email alerts so they can take action before the bill grows further.

Spending notifications are available on the Launch and Scale plans. You can manage them from the **Billing** page in the Neon Console, with the [Neon CLI](https://neon.com/docs/introduction/spending-notifications#manage-spending-notifications-with-the-neon-cli), or with the [Neon Management API](https://neon.com/docs/introduction/spending-notifications#manage-spending-notifications-with-the-neon-api).

**Coming soon: Automatic project suspension**

Currently, email alerts are the only available action. Automatic project suspension is coming soon: when the threshold is reached, projects' computes will pause until you raise the threshold or the next monthly billing period begins.

## Who can set up spending notifications

Only organization admins can enable, edit, or disable spending notifications. Other members see the notification threshold in read-only form on the **Billing** page.

## Alert thresholds

When a spending notification is configured, Neon sends email alerts to organization admins at two thresholds:

- When spending reaches 80% of the threshold
- When spending reaches 100% of the threshold

Neon checks your spending every 15 minutes. Once spending crosses a threshold, an alert email goes out, and reminders continue weekly until you raise the threshold or the billing cycle resets.

## Enable spending notifications

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select your organization from the profile menu in the top-right of the console.
3. Select **Billing** from the menu.
4. On the **Spending Notifications** card, select **Enable**.
5. In the **Enable Spending Notifications** dialog, enter a whole-dollar amount.
6. Select **Enable**.

The **Spending Notifications** card now shows the current spending and a progress bar toward the threshold.

## Edit the threshold

1. Navigate to the **Billing** page.
2. On the **Spending Notifications** card, select **Edit**.
3. Update the amount and select **Save**.

You can also open the edit dialog from the over-threshold banner by selecting **Manage spending notifications**. The banner appears in the Console when spending is approaching the threshold or has reached it.

## Disable spending notifications

1. Navigate to the **Billing** page.
2. On the **Spending Notifications** card, select **Disable**.
3. Confirm in the **Disable Spending Notifications** dialog.

After you disable notifications, no further email alerts are sent and the over-threshold banner no longer appears.

## What happens when the threshold is reached

When your organization's monthly charges reach the threshold:

- Admins receive a final email alert.
- A banner appears in the Neon Console showing **Threshold reached**, with a **Manage spending notifications** link that opens the edit dialog.

Projects continue to run, and charges continue to accumulate, until you raise the threshold or the billing cycle resets at the start of the next month. Automatic project suspension is coming soon and will stop compute charges at the threshold.

Spending notifications only send alerts; they don't stop usage. If you need Neon to actively suspend computes when a limit is reached, you can set per-project consumption quotas with the Neon API. These work per project and per consumption metric (compute, storage, and data transfer) rather than on total dollar spend. See [Configure consumption limits](https://neon.com/docs/guides/consumption-limits).

**Note:** A spending notification threshold applies to the organization's total monthly Neon charges across all projects in that organization. If you belong to multiple organizations, set a separate threshold for each.

## Manage spending notifications with the Neon CLI

The [`neon orgs spending-limit`](https://neon.com/docs/cli/orgs#spending-limit) commands read, set, and remove the threshold in US dollars. The CLI converts the amount to cents for you:

```bash
neon orgs spending-limit get --org-id <org_id>
neon orgs spending-limit set 500 --org-id <org_id>
neon orgs spending-limit delete --org-id <org_id>
```

## Manage spending notifications with the Neon API

You can manage spending notifications through the Management API at:

`https://console.neon.tech/api/v2/organizations/{org_id}/billing/spending_limit`

Replace `{org_id}` with your organization ID (see [Finding your org_id](https://neon.com/docs/manage/orgs-api#finding-your-org_id)). Authenticate with a [personal API key](https://neon.com/docs/manage/api-keys#create-an-api-key) or another allowed credential for the Management API.

| Action                      | Method                                                                                                                                  | Who can use it                                               |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| Read the current threshold  | [Retrieve the organization's notification threshold](https://neon.com/docs/reference/api/organizations/get-organization-spending-limit) | Organization members with **read** access (Launch and Scale) |
| Set or change the threshold | [Set the organization's notification threshold](https://neon.com/docs/reference/api/organizations/set-organization-spending-limit)      | **Organization admins** only (Launch and Scale)              |
| Remove the threshold        | [Clear the organization's notification threshold](https://neon.com/docs/reference/api/organizations/delete-organization-spending-limit) | **Organization admins** only (Launch and Scale)              |

**Request body (`PUT`):** send `spending_limit_cents` as a positive integer (monthly threshold in **cents**; minimum **1**). For example, `$100.00` per month is `10000`. Values **`0`** and **`null`** are rejected; to clear a threshold, call **`DELETE`** on the same path (idempotent when no threshold is configured).

**Response (`GET` / `PUT` 200):** the API returns `spending_limit_cents`, or `null` when no threshold is set. Alerts at 80% and 100% of the threshold behave the same as for Console-managed notifications; computes are not suspended by this feature.

See the linked API reference pages for response codes, schemas, and **Try it** examples.

--- [Document source](https://neon.com/docs/introduction/status.md) ---

> Summary: The Neon status page (neonstatus.com) reports real-time uptime and incident status for platform components (database connectivity, project/branch operations, Console API, Console Frontend, account creation, login, and the Neon website) and backend services (Data API, Managed Better Auth, Object Storage, Functions, and AI Gateway). Check here to confirm whether an outage is regional, and subscribe to alerts via webhook, RSS, Slack, or Microsoft Teams. Routine maintenance and compute updates are not posted here.

# Neon status

Stay informed about the performance and availability of Neon

Last updated: 2026-10-30

Real-time uptime and incident status live on the Neon status page, not on this page. Open it to see current platform status and bookmark it for quick access during incidents.

> **Check live Neon status**
>
> View real-time uptime and incident status for all Neon platform components.
>
> [Open status page](https://neonstatus.com/)

To monitor the status for your specific Neon project, check the region where your project is located. You can find your project's region on the **Overview** page in the Neon Console, in the **Project** panel.

The Neon status page tracks the following components. Most are reported per region. Console API, Console Frontend, Account Creation, and Console Login also have a global entry, and the Website is reported globally only.

**Platform**

- **Database Connectivity** – Ability to connect to active Neon database projects via Postgres protocol
- **Project/Branch Operations** – Operations including project creation, auto-suspend, compute starts, and branch operations
- **Console API** – The Neon Console management API
- **Console Frontend** – The management UI at [https://console.neon.tech/](https://console.neon.tech/)
- **Account Creation** – The signup process at [https://console.neon.tech/signup](https://console.neon.tech/signup), including team invites
- **Console Login** – The login process at [https://console.neon.tech/login](https://console.neon.tech/login)
- **Website** – The Neon website at [https://neon.com/](https://neon.com/)

**Backend services**

- **Data API** – The [Neon Data API](https://neon.com/docs/data-api/overview) HTTP query interface
- **Managed Better Auth** – [Managed Better Auth](https://neon.com/docs/auth/overview) authentication
- **Object Storage** – [Neon Object Storage](https://neon.com/docs/storage/overview)
- **Functions** – [Neon Functions](https://neon.com/docs/compute/functions/overview)
- **AI Gateway** – [Neon AI Gateway](https://neon.com/docs/ai-gateway/overview)

Backend services are listed only for the regions where they're available.

**Note: Updates and maintenance notices**

Neon performs occasional platform maintenance and applies regular updates to your project's computes, but these maintenance activities and updates are not posted to the Neon status page. To stay informed about maintenance operations and updates, watch for notices in the Neon Console and your project settings. See [Maintenance & updates overview](https://neon.com/docs/manage/maintenance-updates-overview) for details.

## Subscribe to status updates

To receive status notifications, click **Subscribe** on the [Neon status page](https://neonstatus.com/) and choose your preferred method: webhook, RSS, Microsoft Teams, or Slack.

--- [Document source](https://neon.com/docs/introduction/support.md) ---

> Summary: Neon support plans map to pricing tiers. Free plan users get community (Discord) support only. Launch adds billing-only tickets. Scale unlocks Standard support. Higher-volume customers can access additional support options aligned with Databricks Support. Use this page to find which channels your plan includes and review the general support policy.

# Support

Last updated: 2026-10-28

This page covers Neon's support plans, channels, and policies. To share ideas or report a docs gap without opening a support request, see [Send feedback](https://neon.com/docs/introduction/feedback).

## Get help

The help you can get depends on your plan:

- **Free**: Ask questions on the [Neon Discord Server](https://neon.com/docs/introduction/support#neon-discord-server) or use [Neon AI chat assistance](https://neon.com/docs/introduction/support#neon-ai-chat-assistance).
- **Launch**: Open [support tickets](https://neon.com/docs/introduction/support#support-tickets) for billing questions.
- **Scale**: Open support tickets for any Neon issue.

To open a support ticket, go to the [Neon Console](https://console.neon.tech) and select **Help** > **Get help** from the organization menu in the top right corner. See [Open the support center](https://neon.com/docs/introduction/support#open-the-support-center).

Check the [Neon status page](https://neonstatus.com/) first if you think there's a service disruption.

## Support plans

Neon's support plans are mapped to [Neon Pricing Plans](https://neon.com/docs/introduction/plans), as outlined in the following table.

| Neon pricing plan | Support plan options |
| :---------------- | :------------------- |
| Free plan         | Community support    |
| Launch plan       | Billing support      |
| Scale plan        | Standard support     |

### Higher-volume customers

Higher-volume Neon customers have access to the same flexibility as other Databricks customers, including annual commits and additional support options. These options follow the [Databricks Support](https://www.databricks.com/support) plans (Business, Production, and Mission Critical), which add response-time SLAs and more support channels.

To learn whether you qualify and to discuss options, [contact our sales team](https://neon.com/contact-sales).

## Support channels

The support channels you can access differ according to your [Support Plan](https://neon.com/docs/introduction/support#support-plans).

| Support channels                                                                                                        | Community support | Billing support | Standard support |
| :---------------------------------------------------------------------------------------------------------------------- | :---------------: | :-------------: | :--------------: |
| [Neon Discord Server](https://neon.com/docs/introduction/support#neon-discord-server) (not an official channel)         |         ✓         |        ✓        |         ✓        |
| [Neon AI chat assistance](https://neon.com/docs/introduction/support#neon-ai-chat-assistance) (not an official channel) |         ✓         |        ✓        |         ✓        |
| [Support tickets](https://neon.com/docs/introduction/support#support-tickets)                                           |         -         |        \*       |         ✓        |
| [Slack channel](https://neon.com/docs/introduction/support#slack-channel)                                               |         -         |        -        |       \*\*       |
| [Dedicated Support Engineer](https://neon.com/docs/introduction/support#dedicated-support-engineer)                     |         -         |        -        |       \*\*       |

* Under **Billing support** (Launch plan), you can only use [support tickets](https://neon.com/docs/introduction/support#support-tickets) for **billing-related** issues. **Scale** plan and higher can use support tickets for **any** Neon issue. On paid plans, **Request billing support** on the [Billing](https://neon.com/docs/introduction/manage-billing#view-the-billing-page) page is the dedicated path for invoice and billing questions.

** [Slack channels](https://neon.com/docs/introduction/support#slack-channel) and [Dedicated Support Engineers](https://neon.com/docs/introduction/support#dedicated-support-engineer) are available for an additional fee, and with some Databricks support plans for [higher-volume customers](https://neon.com/docs/introduction/support#higher-volume-customers). [Contact sales](https://neon.com/contact-sales) to learn more.

### Neon Discord Server

All Neon users have access to the [Neon Discord Server](https://neon.com/discord), where you can ask questions in the **#support** channel or see what others are doing with Neon. You will find Neon users and members of the Neon team actively engaged.

**Important:** The [Neon Discord Server](https://neon.com/discord) is not an official Neon Support channel.

### Neon AI chat assistance

Neon AI chat assistance is available to all Neon users. You can access it from these locations:

- **Neon Console**: Open the [support center](https://neon.com/docs/introduction/support#open-the-support-center) and select **Ask the AI assistant**.
- **Neon documentation**: Select **Ask AI** in the header of the [Neon documentation](https://neon.com/docs) site, or open search with **⌘K** (**Ctrl+K** on Windows and Linux) and ask Neon AI from there.
- **Neon CLI**: Run [`neon ask`](https://neon.com/docs/cli/ask) to ask questions about Neon from your terminal

Neon AI chat assistants are updated regularly and built on various sources including the Neon documentation, the Neon website, the Neon API, and Neon GitHub repositories.

**Important:** Neon AI chat is not an official Neon Support channel.

### Support tickets

**Launch** plan (**Billing support**): you can open support tickets for **billing-related** issues only, such as questions about an invoice, charge, refund, or your plan. For what billing support can and can't help with, see [What billing support can and can't help with](https://neon.com/docs/introduction/manage-billing#what-billing-support-can-and-cant-help-with).

**Scale** plan (**Standard support**): you can open support tickets for **any** Neon issue.

**Vercel-managed Neon integration**: if you use Neon through the Vercel-managed Neon integration and are on Neon's Scale plan, you can also open support tickets for any Neon issue.

You open support tickets from the support center in the Neon Console.

#### Open the support center

1. In the Neon Console, open the organization menu in the top right corner.
2. Select **Help** > **Get help**.

The **Support center** drawer opens. Under **Which organization needs support?**, select the organization the request is for. The options under **How can we help?** depend on that organization's plan:

- **Ask the AI assistant**: Get answers sourced from the Neon docs. See [Neon AI chat assistance](https://neon.com/docs/introduction/support#neon-ai-chat-assistance).
- **Read the docs**: Browse Neon guides, references, and quickstarts.
- **Contact our support team**: Open a technical support ticket. Available on the **Scale** plan.
- **Ask a billing question**: Open a billing support ticket about an invoice, charge, refund, or your plan. Available on the **Launch** and **Scale** plans.
- **Get help from the community**: Join the [Neon Discord Server](https://neon.com/docs/introduction/support#neon-discord-server).

On the **Free** plan, the support center offers the AI assistant, the docs, and the community. To unlock support tickets, [upgrade to a paid plan](https://neon.com/docs/introduction/manage-billing#change-your-plan).

#### Open a technical support ticket (Scale plan)

1. In the support center, select **Contact our support team**. The **Open a support ticket** form opens for the organization you selected.
2. Fill in:
   - **Subject**: A short summary of the issue. Required.
   - **Priority**: How urgent the issue is.
   - **Problem description**: A detailed description of the issue.
   - **Attachments**: Optional. Add screenshots, logs, or other files.
3. Leave **I consent to Neon employees connecting to my database to help resolve this support case** selected if you want support to be able to connect to your database. Clear it if you don't.
4. Optionally, select the affected **Project**, **Branch**, **Compute**, and **Affected Service** to help support find the problem faster.
5. Check **Your contact email**. Responses go to this address, which defaults to the email address for your Neon account.
6. Select **Submit support ticket**.

#### Open a billing support ticket (Launch and Scale plans)

1. In the support center, select **Ask a billing question**.
2. Under **Related invoice**, select the invoice your question is about, if any.
3. Under **How can we help?**, describe your question or problem.
4. Select **Submit request**.

You can also open a billing support ticket from the **Billing** page. Select **Request billing support** in the page header, or select **View past invoices**, open an invoice's actions menu, and select **Request support** to open the form with that invoice pre-selected. See [Request billing support](https://neon.com/docs/introduction/manage-billing#request-billing-support).

**Tip:** To ensure you receive responses from our support team, allowlist the `help@databricks.com` email address in your email client. This prevents support responses from being filtered to your spam or junk folder.

### Slack channel

[Slack connect](https://slack.com/intl/en-ie/connect) channels are available for an additional fee for Standard support customers, and with some Databricks support plans for [higher-volume customers](https://neon.com/docs/introduction/support#higher-volume-customers). To learn more, [contact our sales team](https://neon.com/contact-sales).

### Dedicated Support Engineer

A dedicated engineer can develop in-depth knowledge of your systems, leading to more efficient issue resolution. This service is available for an additional fee. To learn more, [contact our sales team](https://neon.com/contact-sales).

## General support policy

Neon provides Support for eligible plans under the terms of this Support Policy as long as the Customer maintains a current subscription to one of the following Neon plans: Launch, Scale. For more information, see [plans](https://neon.com/docs/introduction/plans). "Support" means the services described in this Support Policy and does not include one-time services or other services not specified in this Support Policy, such as training, consulting, or custom development. Support for Free plan users is provided through [Discord](https://neon.com/discord). See Neon [plans](https://neon.com/docs/introduction/plans) and [pricing](https://neon.com/pricing) for more information about our plans.

Unless described otherwise, defined terms mentioned in this policy shall have the same meaning as defined in the [Neon Platform Terms](https://neon.com/platform-terms).

We provide updates regarding any disruption in our Services on our [status page](https://neonstatus.com/). Please check this source first before seeking support.

### Issue resolution

Neon will make commercially reasonable efforts to resolve any Issues submitted by customers on eligible plans. Such efforts may (at our discretion) include helping with diagnosis, suggesting workarounds, or changing the Product in a new release. An "Issue" is a material and verifiable failure of the Product to conform to its Documentation. Support will not be provided for the following: (1) use of the Products in a manner inconsistent with the applicable Documentation, (2) modifications to the Products not provided by or approved in writing by Neon, (3) use of the Products with third-party software not provided or approved by Neon. The Customer shall not submit Issues arising from any products other than the Products or otherwise use Support for unsupported products; this includes issues caused by third-party integrations.

### Billing issues

If you, the Customer, believe that your invoice or billing receipt is incorrect, we strongly encourage you to contact our Support team rather than filing a dispute with your card provider. Paid plans can use **Request billing support** on the **Billing** page in the Neon Console; see [Request billing support](https://neon.com/docs/introduction/manage-billing#request-billing-support). Should a payment dispute be filed before getting in touch with us, we are limited in terms of the action we can take to resolve the matter. Once a dispute has been made with the card provider, the account associated with it and all deployments under it may be suspended until it has been resolved.

### Etiquette

Regardless of the method or location through which Neon provides Support, communication should be professional and respectful. Any communication that is deemed objectionable by Neon staff is not tolerated. This includes but is not limited to any communication that is abusive or contains profane language. Neon reserves the right to terminate Support Services in the event of any such objectionable communication.

### Customer responsibilities

To ensure efficient resolution of issues, customers are expected to (1) provide detailed information about the issue, (2) cooperate with the Support team during troubleshooting, and (3) use available self-service resources for basic inquiries.

### Changes to the support policy

We reserve the right to modify, amend, or update this Support Policy, including the types of support offered, support hours, response times, and support plans, at any time and at our sole discretion. Any changes to the Support Policy will be effective immediately upon posting a revised version of this Support Policy. Continued use of our services after such modifications will constitute acknowledgment and acceptance of the changes.

## Legacy enterprise support

Customers on a legacy Enterprise plan can view support plan details in the following dropdown. These terms, including the target response times, apply only to legacy Enterprise contracts. They don't apply to the Free, Launch, or Scale plans.

<details>

<summary>**Enterprise support (legacy)**</summary>

### General support policy

Neon provides Support for Enterprise plans under the terms of this Support Policy as long as the Customer maintains a current subscription to an Enterprise plan. "Support" means the services described in this Support Policy and does not include one-time services or other services not specified in this Support Policy, such as training, consulting, or custom development.

Unless described otherwise, defined terms mentioned in this policy shall have the same meaning as defined in the [Neon Platform Terms](https://neon.com/platform-terms).

We provide updates regarding any disruption in our Services on our [status page](https://neonstatus.com/). Please check this source first before seeking support.

### Issue resolution

Neon will make commercially reasonable efforts to resolve any Issues submitted by Enterprise customers. Such efforts may (at our discretion) include helping with diagnosis, suggesting workarounds, or changing the Product in a new release. An "Issue" is a material and verifiable failure of the Product to conform to its Documentation. Support will not be provided for the following: (1) use of the Products in a manner inconsistent with the applicable Documentation, (2) modifications to the Products not provided by or approved in writing by Neon, (3) use of the Products with third-party software not provided or approved by Neon. The Customer shall not submit Issues arising from any products other than the Products or otherwise use Support for unsupported products; this includes issues caused by third-party integrations.

### Billing issues

If you, the Customer, believe that your invoice or billing receipt is incorrect, we strongly encourage you to contact our Support team rather than filing a dispute with your card provider. Where available in the Neon Console, paid plans can use **Request billing support** on the **Billing** page; see [Request billing support](https://neon.com/docs/introduction/manage-billing#request-billing-support). Should a payment dispute be filed before getting in touch with us, we are limited in terms of the action we can take to resolve the matter. Once a dispute has been made with the card provider, the account associated with it and all deployments under it may be suspended until it has been resolved.

### Response times

Neon aims to respond to all Enterprise subscription requests in a timely manner and as soon as practically possible. Enterprise customers are prioritized based on the Severity of their issue and their specific Enterprise support tier (Standard, Gold, or Platinum). Response times are outlined in the target response time guidelines below.

#### Enterprise target response times

The table below outlines Neon's guidelines for the various support tiers of our Enterprise support plan.

These times relate to the time it takes Neon to respond to the Customer's initial request. This guideline only applies when submitting a support ticket through the Neon Console.

| Severity Level        | Enterprise Standard                       | Enterprise Gold                          | Enterprise Platinum                      |
| --------------------- | ----------------------------------------- | ---------------------------------------- | ---------------------------------------- |
| Severity 1 (Critical) | \< 2 hours (during Normal Business Hours) | \< 1 hour                                | \< 1 hour                                |
| Severity 2 (High)     | \< 2 days (during Normal Business Hours)  | \< 1 day                                 | \< 4 hours                               |
| Severity 3 (Normal)   | \< 3 days (during Normal Business Hours)  | \< 3 days (during Normal Business Hours) | \< 3 days (during Normal Business Hours) |
| Severity 4 (Low)      | \< 3 days (during Normal Business Hours)  | \< 3 days (during Normal Business Hours) | \< 3 days (during Normal Business Hours) |

#### Severity levels

When the Customer submits an issue (with or without specifying a starting severity), Neon will reasonably assess its severity according to the appropriate severity levels defined below. Neon reserves the right to set, upgrade and downgrade severities of support tickets, on a case-by-case basis, considering any available mitigations, workarounds, and timely cooperation from Customers. Neon will explain the reasoning to the Customer and will resolve any disagreement regarding the severity as soon as is reasonably practicable. Critical and High-priority levels should not be used for low-impact issues or general questions!

A detailed explanation of each severity level, including several examples, is provided below.

##### Severity 1 (Critical)

Catastrophic problems in the Customer's production system leading to loss of service or impact on the Customer's business:

- Unavailability of the service
- Security breaches that compromise the confidentiality, integrity, or availability of the database or its data.

**Note:** If Critical is selected during the case creation, the customer will be asked to provide in-depth details on the business impact the issue has caused.

Examples:

- A complete outage of the service provided by Neon
- Security breaches
- Error impacting the project as a whole (all endpoints/db affected)
- Error impacting multiple projects
- EP/Branch/DB unreachable
- Data corruption/Data loss

##### Severity 2 (High)

Means a high-impact problem in a customer's production systems. Essential operations are seriously disrupted, but a workaround exists that allows for continued essential operations.

- Non-essential modifications to configuration, like adjusting database parameters or table schema
- Minor performance concerns that have minimal impact on database usability
- Minor issues related to application integrations, such as minor API connectivity problems
- Small-scale challenges with data import/export, data transformation, or data loading processes

Examples:

- Partial outage of the service provided by Neon: service usable, but key feature unusable, for example:
  - Cannot create a new branch
  - Cannot execute a branch restore
  - Cannot perform point-in-time recovery (PITR)
  - Etc.
- Any use case that would require a high load of manual work on the customer side to mitigate an issue on our end
- Any use case which massively and negatively affects the customer's business

##### Severity 3 (Normal)

A medium-impact problem on a production or non-production system that involves:

- Partial or limited loss of non-critical functionality
- A usage problem that involves no loss in functionality
- Customers can continue essential operations. Normal problems also include issues with non-production systems, such as test and development systems.

Examples:

- RCA for past outages or incidents (no disruption of the service at the moment)
- Sporadic connection failure/timeouts/retries
- Cannot connect with random third-party framework or tool (but can connect generally speaking)
- Any use case which has a minor impact on the customer's business
- Poor performing queries/ingestion
- Billing issues

##### Severity 4 (Low)

A general usage question; there is no impact on the product's quality, performance, or functionality in a production or non-production system:

- Any request for information, enhancement, or documentation clarification regarding the platform

Examples:

- Feature requests/feature enablement
- General questions ("active time," "how to backup a DB," "how to ingest data") and feedback
- Any use case that has no impact on the customer's business at all

</details>

--- [Document source](https://neon.com/docs/introduction/usage-calculations.md) ---

> Summary: Neon's consumption history API returns raw metrics that you convert to billing units before multiplying by plan rates to calculate cost. Use this page over the Console when you need to reconcile an invoice programmatically or build cost-tracking tooling. Plan-specific rates, transfer allowances, and granularity lookback limits are documented here.

# Usage and cost calculations

Convert raw API metrics into billing units and calculate your costs

Last updated: 2026-10-31

This guide helps you use the Neon API to fetch your consumption data, convert raw metrics into human-readable numbers, and understand how your bill is calculated. To monitor usage in the Neon Console instead, see [Monitor billing and usage](https://neon.com/docs/introduction/monitor-usage).

It applies to **Launch**, **Scale**, **Agent**, and **Enterprise** plans. Consumption history begins at the time you upgrade from the Free plan.

## Fetch your usage

The [consumption history endpoint](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project-v2) returns per-project, per-day (or per-hour, or per-month) usage for the metrics you request.

```sh
curl "https://console.neon.tech/api/v2/consumption_history/v2/projects?\
org_id=${ORG_ID}&from=2026-03-01T00:00:00Z&to=2026-04-01T00:00:00Z&\
granularity=daily&metrics=compute_unit_seconds,root_branch_bytes_month,\
child_branch_bytes_month,instant_restore_bytes_month,snapshot_storage_bytes_month,\
extra_branches_month,public_network_transfer_bytes,private_network_transfer_bytes,\
functions_active_capacity_microseconds,functions_waiting_capacity_microseconds,\
functions_invocations,functions_egress_bytes&\
limit=100" \
  -H "Authorization: Bearer ${NEON_API_KEY}"
```

Calling this endpoint does not wake suspended computes, so it is safe to poll without affecting your usage.

Required parameters: `org_id`, `from`, `to`, `granularity`, `metrics`. Optional: `project_ids`, `limit`, `cursor`. For the complete API reference including pagination, polling, rate limits, and error handling, see [Querying consumption metrics](https://neon.com/docs/guides/consumption-metrics).

**Note: Legacy endpoint**

The older `/consumption_history/projects` endpoint returns different metrics (active time, compute time, written data, and synthetic storage) that do not match your invoice on usage-based plans (Launch, Scale, Agent, or Enterprise). Use the v2 endpoint shown above unless you are on a [legacy plan](https://neon.com/docs/guides/consumption-metrics-legacy).

## Usage metrics and units

| API metric name                           | What it measures                                                                                                                                                                           | Raw unit              | Converted unit      |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | ------------------- |
| `compute_unit_seconds`                    | CPU time weighted by compute size                                                                                                                                                          | CU-seconds            | CU-hours            |
| `root_branch_bytes_month`                 | Storage on root branches                                                                                                                                                                   | byte-months           | GB-months           |
| `child_branch_bytes_month`                | Storage on child branches (delta from parent)                                                                                                                                              | byte-months           | GB-months           |
| `instant_restore_bytes_month`             | Instant restore (point-in-time recovery / PITR) history                                                                                                                                    | byte-months           | GB-months           |
| `snapshot_storage_bytes_month`            | Storage for branch snapshots. Manual snapshots are full snapshots; scheduled snapshots are full for the first snapshot, then incremental (delta) for subsequent snapshots in that schedule | byte-months           | GB-months           |
| `public_network_transfer_bytes`           | Outbound (egress) data over the public network                                                                                                                                             | bytes                 | GB                  |
| `private_network_transfer_bytes`          | Inbound (ingress) and outbound (egress) traffic over private networking (Scale+)                                                                                                           | bytes                 | GB                  |
| `extra_branches_month`                    | All child branches per hour (subtract plan allowance before billing)                                                                                                                       | branch-hours          | branch-months       |
| `functions_active_capacity_microseconds`  | Time Functions spend actively using CPU                                                                                                                                                    | capacity-microseconds | Capacity-Hours      |
| `functions_waiting_capacity_microseconds` | Time Functions spend waiting on I/O                                                                                                                                                        | capacity-microseconds | Capacity-Hours      |
| `functions_invocations`                   | Number of function calls                                                                                                                                                                   | invocations           | million invocations |
| `functions_egress_bytes`                  | Data sent by Functions                                                                                                                                                                     | bytes                 | GB                  |

A Compute Unit (CU) corresponds to 1 CPU with 4 GB RAM. A 2 CU endpoint accumulates 2 CU-seconds for every wall-clock second it runs.

## Converting raw values to readable numbers

Neon uses decimal gigabytes (1 GB = 10^9 bytes), not gibibytes, and a fixed billing period of **744 hours** (31 x 24), regardless of actual month length.

| From                  | To                              | Formula                                |
| --------------------- | ------------------------------- | -------------------------------------- |
| CU-seconds            | CU-hours                        | `value / 3600`                         |
| byte-months           | GB-months (billing unit)        | `value / 1000000000`                   |
| byte-hours            | GB-months (legacy field)        | `value / 744 / 1000000000`             |
| byte-hours            | average GB (what Console shows) | `value / hours_in_period / 1000000000` |
| bytes                 | GB                              | `value / 1000000000`                   |
| branch-hours          | branch-months                   | `value / 744`                          |
| capacity-microseconds | Capacity-Hours                  | `value / 3600000000`                   |
| invocations           | million invocations             | `value / 1000000`                      |

The v2 storage metrics (`root_branch_bytes_month`, `child_branch_bytes_month`, `instant_restore_bytes_month`, `snapshot_storage_bytes_month`) are reported in **byte-months**: the underlying byte-hours already divided by 744, so converting to GB-months divides by `1000000000` only. The byte-hours rows above apply to the legacy `GET /projects/{project_id}` field `data_storage_bytes_hour`, which is raw byte-hours.

For "average GB," `hours_in_period` is the number of hours between your `from` and `to` timestamps.

Use the capacity-microseconds conversion for both active and waiting Functions capacity. Convert `functions_egress_bytes` with the same bytes-to-GB formula used for other byte metrics.

## Calculating your cost

For priced metrics, sum each metric's cost to get the total. Rates differ by plan (see [Plans](https://neon.com/docs/introduction/plans) for current pricing):

| Metric                | Formula                          | Launch               | Scale               |
| --------------------- | -------------------------------- | -------------------- | ------------------- |
| Compute               | CU-hours x rate                  | $0.106/CU-hr         | $0.222/CU-hr        |
| Root storage          | GB-months x rate                 | $0.35/GB-mo          | $0.35/GB-mo         |
| Child storage         | GB-months x rate                 | $0.35/GB-mo          | $0.35/GB-mo         |
| Instant restore       | GB-months x rate                 | $0.20/GB-mo          | $0.20/GB-mo         |
| Snapshots             | GB-months x rate                 | $0.09/GB-mo          | $0.09/GB-mo         |
| Public transfer       | max(0, project\_GB - 500) x rate | $0.10/GB             | $0.10/GB            |
| Private transfer      | GB x rate                        | n/a                  | $0.01/GB            |
| Extra branches        | branch-months x rate             | $1.50/mo             | $1.50/mo            |
| Functions active      | Capacity-Hours x rate            | $0.10/Capacity-Hour  | $0.12/Capacity-Hour |
| Functions waiting     | Capacity-Hours x rate            | $0.025/Capacity-Hour | $0.03/Capacity-Hour |
| Functions invocations | millions of invocations x rate   | $0.60/million        | $0.60/million       |

Agent plan rates match Scale except compute, which is billed at $0.106/CU-hr (the Launch rate). Enterprise rates match Scale, and Enterprise plans may include custom negotiated pricing.

For current Functions pricing and Free plan allowances, see [Plans](https://neon.com/docs/introduction/plans#functions).

### Example: compute

If the API returns `"value": 500000` for `compute_unit_seconds` on the Scale plan:

1. Convert: 500000 / 3600 = 138.89 CU-hours
2. Cost: 138.89 x $0.222 = **$30.83**

### Example: storage

If the API returns `"value": 3360000000` for `root_branch_bytes_month`:

1. Convert: 3360000000 / 1000000000 = 3.36 GB-months
2. Cost: 3.36 x $0.35 = **$1.18**

## Billing mechanics

### The 744 constant

Neon defines a billing month as exactly 744 hours (31 x 24). This constant is used for all byte-hour and branch-hour conversions, regardless of how many days the calendar month has. Shorter months (28 or 30 days) accumulate fewer hours, so they cost slightly less.

### Byte-hours

Storage is metered in byte-hours (bytes stored multiplied by hours held). The v2 consumption metrics report this **already divided by 744**, as byte-months. For example, 2 GB stored for a full 31-day month:

1. Per-day byte-hours: 2000000000 x 24 = 48000000000
2. Full-month byte-hours: 48000000000 x 31 = 1488000000000
3. Byte-months the v2 API returns: 1488000000000 / 744 = 2000000000
4. Convert to GB-months: 2000000000 / 1000000000 = 2.0 GB-months
5. Cost: 2.0 x $0.35 = **$0.70**

### Branch-hours and the allowance

The `extra_branches_month` metric counts **all** child branches, not only the ones beyond your allowance. Each plan includes a set number of included branches per project, and the root branch is always included, so the free child allowance is `branches_per_project - 1`. That's 9 on Launch and 24 on Scale. To calculate billable branch-hours:

1. For each project and each time bucket (day or hour), compute the free allowance: `(branches_per_project - 1) x hours_in_bucket`.
2. Subtract: `billable = max(0, reported_branch_hours - free_allowance)`.
3. Sum across all projects and days, then divide by 744 for branch-months.

**Example:** A project has 12 child branches on Launch, queried with daily granularity. The API returns `"value": 288` for `extra_branches_month` for one day:

1. Free allowance for that day: (10 - 1) x 24 = 216 branch-hours
2. Billable: max(0, 288 - 216) = 72 branch-hours
3. Convert: 72 / 744 = 0.097 branch-months
4. Cost: 0.097 x $1.50 = **$0.15**

Repeat for each day in the billing period and sum the billable branch-hours across all projects before dividing by 744.

### Public transfer allowance

On paid plans, each project receives a 500 GB free allowance. Subtract the allowance from each project's public transfer, then sum the billable usage:

```text
billable GB per project = max(0, project_GB - 500)
total cost = sum(billable_GB per project) x $0.10
```

### Granularity and precision

Each granularity has a lookback limit. If your `from` timestamp falls outside it, the API returns `406 Not Acceptable`.

| Granularity | Lookback limit            | Best for                                       |
| ----------- | ------------------------- | ---------------------------------------------- |
| `hourly`    | Last 168 hours (\~7 days) | Exact billing match, branch allowance accuracy |
| `daily`     | Last 60 days              | Full-month reports, cost reconciliation        |
| `monthly`   | Last 12 months            | Trend analysis across billing periods          |

These limits are measured from the current server time, not from billing period boundaries. Using `granularity=hourly` gives the most precise match to Neon's internal billing calculations because branch allowances are evaluated per hour. Coarser granularity averages out within-bucket fluctuations, so daily or monthly queries may slightly underestimate billable branch-hours compared to the actual invoice.

## Reconciling your bill

Neon sends a weekly usage email that includes per-metric costs. You can also check charges to date on the [Billing page](https://neon.com/docs/introduction/monitor-usage#billing-page) in the Console. For the priced metrics listed above, those costs are calculated using the same formulas: raw API values converted to billing units, multiplied by the plan rate, with allowances subtracted where applicable.

To reconcile the numbers yourself:

1. Fetch consumption history for the billing month (`from` = month start, `to` = month end or current date).
2. Sum each priced metric across all projects.
3. Convert the priced metrics to billing units using the formulas above.
4. Apply the 500 GB public transfer allowance and branch allowance to each project.
5. Multiply by your plan's rates.

The result should closely match the costs in your weekly email. Small differences can occur due to:

- **Granularity**: the billing system uses hourly precision. If you query with `daily` granularity, branch allowance rounding can introduce minor variance.
- **Timing**: your query's `to` timestamp may differ slightly from the snapshot used for the email.
- **Rounding**: display rounding in the email versus full-precision calculation.

For the closest match, use `granularity=daily` and align `from`/`to` with your billing period start (visible on the [Billing page](https://neon.com/docs/introduction/monitor-usage#billing-page)), or store hourly consumption by polling periodically.

**Tip: Optimize your costs**

For strategies to reduce your costs across compute, storage, branches, and data transfer, see [Cost optimization](https://neon.com/docs/introduction/cost-optimization). For network transfer specifically, see [Reduce network transfer costs](https://neon.com/docs/introduction/network-transfer).

## Tracking usage on the Free plan

The consumption history API requires a paid plan. On the Free plan, you can track usage with the project detail and branch detail endpoints:

### Project snapshot

Use `GET /projects/{project_id}` to check compute time, data transfer, and storage for the current billing period:

```sh
curl "https://console.neon.tech/api/v2/projects/${PROJECT_ID}" \
  -H "Authorization: Bearer ${NEON_API_KEY}"
```

The response includes:

| Field                      | What it tells you                                                                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `compute_time_seconds`     | Total CU-seconds this billing period (weighted by compute size). Divide by 3600 for CU-hours.                                                      |
| `active_time_seconds`      | Wall-clock seconds endpoints were running. Divide `compute_time_seconds` by this value to get your average compute size in CUs.                    |
| `data_storage_bytes_hour`  | Byte-hours of storage (combines root, child, and instant restore). Divide by hours elapsed for average size, or by 744 x 1000000000 for GB-months. |
| `data_transfer_bytes`      | Data transfer in bytes (combines public and private). Divide by 1000000000 for GB.                                                                 |
| `consumption_period_start` | Start of the billing cycle. All consumption fields reset here.                                                                                     |

On paid plans, the [consumption history API](https://neon.com/docs/introduction/usage-calculations#fetch-your-usage) provides these as separate metrics: `compute_time_seconds` corresponds to `compute_unit_seconds`, `data_storage_bytes_hour` splits into `root_branch_bytes_month`, `child_branch_bytes_month`, and `instant_restore_bytes_month`, and `data_transfer_bytes` splits into `public_network_transfer_bytes` and `private_network_transfer_bytes`.

**Note: Not for billing**

These fields are approximate and meant for monitoring usage, not for billing or metering. On paid plans, use the [consumption history API](https://neon.com/docs/introduction/usage-calculations#fetch-your-usage) (`/consumption_history/v2/projects`) for billing.

### Branch storage

The Free plan caps storage per project based on `logical_size` across branches. Use `GET /projects/{project_id}/branches` to check each branch's size:

```sh
curl "https://console.neon.tech/api/v2/projects/${PROJECT_ID}/branches" \
  -H "Authorization: Bearer ${NEON_API_KEY}"
```

Each branch in the response includes a `logical_size` field (bytes). Sum across branches to get total project storage.

### Free plan limits

See the [Neon Free plan docs](https://neon.com/docs/introduction/plans#plan-overview) for current limits. Exceeding them suspends compute or blocks creation. There are no costs on the Free plan.

--- [Document source](https://neon.com/docs/legal/sla.md) ---

> Summary: The Neon Service Level Agreement (SLA) defines the Monthly Uptime Percentage for Compute Endpoints on the Neon Business and Scale plans, the Service Credits available when it isn't met, how to submit a claim, and exclusions.

# Neon Service Level Agreement

Last updated: 2026-10-23

**Last Modified:** February 20, 2026 

The Service Level Agreement ("**SLA"**) outlined below applies exclusively to customers who have subscribed to the Neon Business or Scale plan. This SLA is incorporated into and forms an integral part of the applicable Agreement between Neon, LLC. and the customer. Unless otherwise provided herein, capitalized terms will have the meaning specified in the Agreement. We reserve the right to change the terms of this SLA.

Neon will use commercially reasonable efforts to maximize the availability of Compute Endpoints and agrees to provide the performance standards as detailed below. This SLA applies only to the availability of Compute Endpoints, and does not apply to any other part of the Platform, APIs, product, or Services offered by Neon.

1. **SERVICE AVAILABILITY** 

If Neon does not achieve and maintain the Monthly Uptime Percentages set forth in the table below, then the Customer may be eligible for a Service Credit as described in this SLA.

| Monthly Uptime Percentage                           | Service Credit |
| --------------------------------------------------- | -------------- |
| Less than 99.95% but greater than or equal to 99.0% | 10%            |
| Less than 99.0% but greater than or equal to 98.0%  | 15%            |
| Less than 98.0% but greater than or equal to 96.0%  | 20%            |
| Less that 96.0%                                     | 80%            |

2. **SERVICE CREDITS AND PROCESS** 

2.1 If the Monthly Uptime Percentage is not met, then you may be eligible for a Service Credit. 

2.2 You must log a support ticket with the Neon support team within 21 days of first becoming aware of an event that impacts service availability and abide by the Customer Obligations set out below. 

2.3 Neon will conduct an assessment of the Service Credit claim.

2.4 A Service Credit is calculated as a percentage of the Fees paid by the Customer for the Services in the month in which the applicable SLA was not met.

2.5 Neon will process claims within 45 days of receipt of full information provided to the Neon support team. 

2.6 If Neon determines that the Customer has satisfied the Customer Obligations and that there are no applicable Exclusions, a Service Credit will be granted to the Customer.

2.7 Neon will apply any awarded Service Credit only against future payments otherwise due from the Customer. At Neon's discretion, we may issue the Service Credit to the credit card the Customer used to pay for the billing cycle in which the Downtime occurred. 

2.8 A Service Credit will not entitle the Customer to any refund or other payment from Neon.

2.9 A Service Credit may not be transferred or applied to any other account. Unless otherwise provided in the Agreement, the Customer's sole and exclusive remedy for any Downtime or non-performance or other failure by Neon to provide the Platform is the receipt of a Service Credit (if eligible) in accordance with the terms of this SLA.

3. **CUSTOMER OBLIGATIONS**

3.1 To be eligible for a Service Credit, you must conduct the following obligations (collectively "**Customer Obligations**"):

3.1.1 You must log a support ticket with Neon within 24 hours of first becoming aware of an event that impacts service availability.

3.1.2 You must submit your claim and all required information by the end of the month immediately following the month in which the Downtime occurred.

3.1.3 You must include all information necessary for Neon to validate your claim, including: (i) a detailed description of the events resulting in Downtime, including your request logs that document the errors and corroborate your claimed outage (with any confidential or sensitive information in the logs removed or replaced with asterisks); (ii) information regarding the time and duration of the Downtime; (iii) the number and location(s) of affected users (if applicable); and (iv) descriptions of your attempts to resolve the Downtime at the time of occurrence. 

3.1.4 You must reasonably assist Neon in investigating the cause of the Downtime and processing your claim. 

3.1.5 You must comply with the terms of the Agreement and any advice from our support team.

3.1.6 Your failure to provide the request and other information as required above will disqualify you from receiving a Service Credit.

4. **EXCLUSIONS** 

4.1 Downtime does not include, and you will not be eligible for a Service Credit for, any performance or availability issue that results from the following (collectively "**SLA Exclusions"**):

4.1.1 factors outside of our reasonable control, such as natural disaster, war, acts of terrorism, riots, government action, or a network or device failure at your website or premises or between your website or premises and Neon;

4.1.2 services, hardware, or software provided by a third party, such as cloud platform services on which Neon runs;

4.1.3 any voluntary actions or inactions from you or any third party not in accordance with the Documentation or guidance e.g., deleting a database, not configuring sufficient compute resources, exceeding available storage, unsharing a Project (if the project owner drops the privilege of a user to access the project), revoking API keys, or incorrectly modifying database connection parameters; overloading a database instance to the point it is inoperable, unsharing of Project, creating excessively large number of tables that significantly increase the recovery time etc.or failing to maintain indexes); 

4.1.4 underlying database engine software that leads to repeated database crashes or an inoperable database instance;

4.1.5 long recovery time due to insufficient IO capacity for your database workload;

4.1.6 that result from your equipment, software or other technology and/or third party equipment, software or other technology (other than third party equipment within our direct control); 

4.1.7 arising from our suspension and termination of your right to use Neon in accordance with the Agreement;

4.1.8 that result from any maintenance as provided for pursuant to the Agreement

4.1.8 Neon's Services being in Technical Preview.

5. **DEFINITIONS**

As used herein, "month" refers to a calendar month.

As used herein, "month" refers to a calendar month.

"**Agreement**" means the Master Service Agreement and applicable Order Form entered into between Neon and the Customer. 

"**Business Hours"** means 06:00am to 14:00pm Pacific Standard Time (UTC -8), Monday through Friday, excluding public holidays in the United States.

**"Compute Endpoints"** means compute instances that provide virtualized computing resources (CPU and memory) for running PostgreSQL. Clients and applications connect to a Neon database via a Compute Endpoint hostname.

"**Downtime**" is calculated on a monthly basis and is the total number of minutes during the month that a Compute Endpoint was unavailable. For the purposes of calculating the Monthly Uptime Percentage, Downtime does not include partial minutes of unavailability, inaccessibility or unavailability due to Unscheduled Downtime. A minute is considered unavailable if all of your continuous attempts to establish a connection to a Compute Endpoint within the minute fail. 

"**Fees"** means the total fees paid by you for the Platform during the month in which Downtime occurred.

"**Monthly Uptime Percentage"**  is calculated as:

_[(`total minutes in month` – `downtime`) / `total minutes in month`] x 100_

**"Project"** refers to the top-level object in the Neon object hierarchy, serving as a container for all associated objects, except for API keys, which have a Neon account scope. The project framework encompasses objects including branches, compute endpoints, databases, and roles. A project also defines the region where resources are hosted.

"**Service Credit**" means the percentage of the Fees to be credited to you if Neon approves your claim, as set forth in the table above.

"**Unscheduled Downtime**" means the time, in minutes, that the Compute Endpoints  are not generally accessible and available to Customers, excluding inaccessibility or unavailability due to Customer's or Authorized Users' acts or omissions, Force Majeure Events, scheduled maintenance disclosed with at least 24 hours' noticel, hacking or virus attacks or emergency maintenance. 

"**You**", "**your**" or "**Customer"** means the person or entity using the Platform or Services  identified in the applicable Order Form as the customer.

--- [Document source](https://neon.com/docs/local/neon-local.md) ---

> Summary: Neon Local is a Docker proxy that routes local Postgres connections to a Neon cloud branch. No connection string changes are needed when switching branches. Use it to connect to an existing branch via BRANCH_ID, or to auto-create ephemeral branches with PARENT_BRANCH_ID that are deleted when the container stops. Both the standard postgres driver and the Neon serverless driver are supported through the same Docker configuration.

# Neon Local

Use Docker environments to connect to Neon and manage branches automatically

Last updated: 2026-11-06

[Neon Local](https://github.com/neondatabase-labs/neon_local) is a proxy service that creates a local interface to your Neon cloud database. It supports two main use cases:

1. **Connecting to existing Neon branches** - Connect your app to any existing branch in your Neon project
2. **Connecting to ephemeral Neon branches** - Connect your app to a new ephemeral database branch that is instantly created when the Neon Local container starts and deleted when the container stops

Your application connects to a local Postgres endpoint, while Neon Local handles routing and authentication to the correct project and branch. This removes the need to update connection strings when working across database branches.

## Connect to existing Neon branch

To connect to an existing Neon branch, provide the `BRANCH_ID` environment variable to the container. This allows you to work with a specific branch without creating a new one.

### Docker run

```shell
docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<your_neon_api_key> \
  -e NEON_PROJECT_ID=<your_neon_project_id> \
  -e BRANCH_ID=<your_branch_id> \
  neondatabase/neon_local:latest
```

### Docker Compose

```yaml
db:
  image: neondatabase/neon_local:latest
  ports:
    - '5432:5432'
  environment:
    NEON_API_KEY: ${NEON_API_KEY}
    NEON_PROJECT_ID: ${NEON_PROJECT_ID}
    BRANCH_ID: ${BRANCH_ID}
```

## Ephemeral database branches for development and testing

To create ephemeral branches (default behavior), provide the `PARENT_BRANCH_ID` environment variable instead of `BRANCH_ID`. The Neon Local container automatically creates a new ephemeral branch of your database when the container starts, and deletes it when the container stops. This ensures that each time you deploy your app via Docker Compose, you have a fresh copy of your database, without needing manual cleanup or orchestration scripts. Your database branch lifecycle is tied directly to your Docker environment.

### Docker run

```shell
docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<your_neon_api_key> \
  -e NEON_PROJECT_ID=<your_neon_project_id> \
  -e PARENT_BRANCH_ID=<parent_branch_id> \
  neondatabase/neon_local:latest
```

### Docker Compose

```yaml
db:
  image: neondatabase/neon_local:latest
  ports:
    - '5432:5432'
  environment:
    NEON_API_KEY: ${NEON_API_KEY}
    NEON_PROJECT_ID: ${NEON_PROJECT_ID}
    PARENT_BRANCH_ID: ${PARENT_BRANCH_ID}
```

## Docker run instructions

Run the Neon Local container using the following `docker run` command:

```shell
docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<your_neon_api_key> \
  -e NEON_PROJECT_ID=<your_neon_project_id> \
  neondatabase/neon_local:latest
```

## Docker Compose instructions

Add Neon Local to your `docker-compose.yml`:

```yaml
db:
  image: neondatabase/neon_local:latest
  ports:
    - '5432:5432'
  environment:
    NEON_API_KEY: ${NEON_API_KEY}
    NEON_PROJECT_ID: ${NEON_PROJECT_ID}
```

## Multi-driver support

The Neon Local container now supports both the `postgres` and Neon `serverless` drivers simultaneously through a single connection string. You no longer need to specify a driver or configure different connection strings for different drivers.

## Connecting your app (Postgres driver)

Connect to Neon Local using a standard Postgres connection string.

### Docker run

```shell
postgres://neon:npg@localhost:5432/<database_name>?sslmode=require
```

### Docker compose

```shell
postgres://neon:npg@${db}$:5432/<database_name>?sslmode=require

# where {db} is the name of the Neon Local service in your compose file
```

**Note:**

For javascript applications
The Neon Local container uses an automatically generated self-signed certificate to secure communication between your app and the container. Javascript applications using the `pg`or `postgres` postgres libraries to connect to the Neon Local proxy will also need to add the following configuration to allow your app to connect using the self-signed certificate.

```shell
ssl: { rejectUnauthorized: false }
```

## Connecting your app (Neon serverless driver)

Connect using the Neon [serverless driver](https://neon.com/docs/serverless/serverless-driver).

**Note:** The Neon Local container only supports HTTP-based communication using the Neon Serverless driver, not websockets. The following configurations will enable your app to communicate using only HTTP traffic with your Neon database.

### Docker run

```javascript
import { neon, neonConfig } from '@neondatabase/serverless';

neonConfig.fetchEndpoint = 'http://localhost:5432/sql';
neonConfig.useSecureWebSocket = false;
neonConfig.poolQueryViaFetch = true;

const sql = neon('postgres://neon:npg@localhost:5432/<database_name>');
```

### Docker compose

```javascript
import { neon, neonConfig } from '@neondatabase/serverless';

neonConfig.fetchEndpoint = 'http://{db}:5432/sql';
neonConfig.useSecureWebSocket = false;
neonConfig.poolQueryViaFetch = true;

const sql = neon('postgres://neon:npg@{db}:5432/<database_name>');

// where {db} is the name of the Neon Local service in your compose file
```

No additional environment variables are needed - the same Docker configuration works for both drivers:

```shell
docker run \
  --name db \
  -p 5432:5432 \
  -e NEON_API_KEY=<your_neon_api_key> \
  -e NEON_PROJECT_ID=<your_neon_project_id> \
  neondatabase/neon_local:latest
```

## Environment variables and configuration options

| Variable           | Description                                                                       | Required | Default                       |
| ------------------ | --------------------------------------------------------------------------------- | -------- | ----------------------------- |
| `NEON_API_KEY`     | Your Neon API key. [Manage API Keys](https://neon.com/docs/manage/api-keys)       | Yes      | N/A                           |
| `NEON_PROJECT_ID`  | Your Neon project ID. Found under Project Settings → General in the Neon console. | Yes      | N/A                           |
| `BRANCH_ID`        | Connect to an existing Neon branch. Mutually exclusive with `PARENT_BRANCH_ID`.   | No       | N/A                           |
| `PARENT_BRANCH_ID` | Create ephemeral branch from parent. Mutually exclusive with `BRANCH_ID`.         | No       | your project's default branch |
| `DRIVER`           | **Deprecated** - Both drivers now supported simultaneously.                       | No       | N/A                           |
| `DELETE_BRANCH`    | Set to `false` to persist branches after container shutdown.                      | No       | `true`                        |

## Persistent Neon branch per Git branch

To persist a branch per Git branch, add the following volume mounts:

```yaml
db:
  image: neondatabase/neon_local:latest
  ports:
    - '5432:5432'
  environment:
    NEON_API_KEY: ${NEON_API_KEY}
    NEON_PROJECT_ID: ${NEON_PROJECT_ID}
    DELETE_BRANCH: false
  volumes:
    - ./.neon_local/:/tmp/.neon_local
    - ./.git/HEAD:/tmp/.git/HEAD:ro,consistent
```

**Note:** This will create a `.neon_local` directory in your project to store metadata. Be sure to add `.neon_local/` to your `.gitignore` to avoid committing database information.

## Git integration using Docker on Mac

If using Docker Desktop for Mac, ensure that your VM settings use **gRPC FUSE** instead of **VirtioFS**. There is currently a known bug with VirtioFS that prevents proper branch detection and live updates inside containers.

![Docker Desktop are set to gRPC FUSE](https://neon.com/docs/local/neon-local-docker-settings.jpg)

## Resources

- [Local development with Neon](https://neon.com/guides/local-development-with-neon)
- [How to set up Neon Local with Docker Compose and JavaScript Postgres clients](https://neon.com/guides/neon-local-docker-compose-javascript)

--- [Document source](https://neon.com/docs/local/vscode-extension.md) ---

> Summary: The Neon VS Code Extension connects to any Neon project branch from VS Code, Cursor, or other VS Code-compatible editors. It provides a database explorer, SQL editor, and spreadsheet-style table data editor without leaving the IDE. Use it to browse schemas, run queries, edit rows, manage databases, and copy connection strings. On sign-in, the extension configures the Neon MCP Server, enabling AI-assisted SQL and natural-language database queries from coding agents.

# Neon VS Code Extension

Connect to Neon and manage your database directly in VS Code, Cursor, and other editors

Last updated: 2026-09-17

The Neon extension lets you connect to any Neon branch and manage your database directly in your IDE. Available for VS Code, Cursor, and other VS Code-compatible editors, you can browse schemas, run queries, edit table data, and get connection strings, without leaving your editor.

## What you can do

With the Neon extension, you can:

- **Connect to projects and branches**  
  The extension automatically detects valid Neon connection strings in your code.
- **Browse your database**  
  Use a clean tree view showing databases, schemas, tables, views, sequences, and relationships.
- **Manage databases and tables**  
  Create and manage databases, schemas, and tables directly in your IDE.
- **Run queries with SQL Editor**  
  Write and execute queries against your selected database. View and sort results, and export data if needed.
- **Edit data with Table Data Editor**  
  View, edit, insert, and delete rows in a spreadsheet-like interface. Import and export tables in CSV, JSON, or SQL formats.
- **Enable AI-powered features**  
  Automatically configure the Neon MCP Server so you can manage projects, branches, and databases from your AI chat.

## Requirements

- [VS Code 1.85.0+](https://code.visualstudio.com/), [Cursor](https://cursor.sh/), or other VS Code-compatible editor.
- A [Neon account](https://neon.tech).

## Install the extension

Click one of the buttons below to install the extension directly, or search for **"Neon - Serverless Postgres"** in your editor's Extensions view (`Ctrl+Shift+X` or `Cmd+Shift+X` on Mac).

[vscode:extension/databricks.neon-local-connect](https://neon.com/docs/local/vscode:extension/databricks.neon-local-connect)

[cursor:extension/databricks.neon-local-connect](https://neon.com/docs/local/cursor:extension/databricks.neon-local-connect)

For other VS Code-compatible editors, install from the [Open VSX Registry](https://open-vsx.org/extension/databricks/neon-local-connect).

## Sign in to Neon

1. Open the Neon panel in the sidebar (look for the Neon logo).

2. Click **Sign in**.

3. Complete OAuth authorization in your browser.

Once signed in, the extension automatically configures the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server) for AI features.

## Connect to a branch

The extension scans your workspace for existing Neon connection strings and can automatically detect your project and branch.

You can also manually select:

1. **Organization**: your Neon organization.
2. **Project**: the project containing your database.
3. **Branch**: the branch to connect to.

Click **Connect** to establish the connection.

**Note:** If you're new to Neon, this reflects our object hierarchy: organizations contain projects, and projects contain branches. [Learn more about how Neon organizes your data.](https://neon.com/docs/concepts/the-object-model)

## Create a new branch

You can create a new branch for feature development, bug fixes, or collaborative work:

1. Select your organization and project.
2. Click **Create new branch...** in the branch dropdown.
3. Enter a descriptive branch name (for example, `feature/user-authentication`, `bugfix/login-validation`).
4. Choose the parent branch you want to branch from.

The extension creates the new branch and connects you immediately.

## Use your connection string

After connecting, copy the connection string from the extension panel and add it to your `.env` file:

```env
DATABASE_URL="postgresql://user:password@ep-example-123456.us-east-2.aws.neon.tech/neondb?sslmode=require"
```

## Start developing

Your application now connects directly to your Neon branch. See the quickstart for your language or framework for more details.

- [Framework quickstarts](https://neon.com/docs/get-started/frameworks)
- [Language quickstarts](https://neon.com/docs/get-started/languages)

## Database explorer

Once connected, the extension provides a comprehensive **Database Explorer** in the sidebar that lets you browse your database structure with an intuitive tree view:

### What you can see

- **Databases**: All available databases in your connected branch.
- **Schemas**: Database schemas organized in a tree structure.
- **Tables & Views**: All tables and views with their column definitions.
- **Sequences**: Database sequences.
- **Data Types**: Column data types, constraints, and relationships.
- **Primary Keys**: Clearly marked primary key columns.
- **Foreign Keys**: Visual indicators for foreign key relationships.

### Schema view actions

- **Right-click any table** to access quick actions:
  - **Query Table**: Opens a pre-filled `SELECT *` query in the SQL Editor.
  - **View Table Data**: Opens the table data in an editable spreadsheet view.
  - **Truncate Table**: Remove all rows from a table.
  - **Drop Table**: Delete the table entirely.
- **Right-click databases or schemas** for management operations.
- **Refresh** the schema view to see the latest structural changes.
- **Expand/collapse** database objects to focus on what you need.

The schema view automatically updates when you switch between branches, so you always see the current state of your connected database.

### Database management actions

Right-click databases, schemas, or tables to access management operations:

- **Create and drop databases and schemas**: Add new databases or remove existing ones.
- **Table designer**: Create tables with columns, indexes, and constraints.
- **Foreign key management**: Set up relationships with referential integrity.
- **View and sequence management**: Create and manage database views and sequences.
- **User and role management**: Control database access and permissions.
- **Data import/export**: Transfer data in CSV, JSON, or SQL formats.

Access these features through the context menu (right-click) in the Database Explorer.

## SQL Editor

Execute SQL queries directly in your IDE with the integrated SQL Editor:

### Features

- **Syntax Highlighting**: Full SQL syntax support.
- **Results Display**: View query results in a tabular format with sorting and filtering.
- **Export Options**: Export results to CSV, JSON, or SQL formats.
- **Query Statistics**: View execution time and performance metrics.
- **Error Highlighting**: Detailed error messages for debugging.

### How to use

1. **From Schema View**: Right-click any table and select "Query Table" for a pre-filled SELECT query.
2. **From Command Palette**: Use `Ctrl+Shift+P` and search for "Neon: Open SQL Editor".

The SQL Editor connects directly to your database connection, so you can query any database in your current branch without additional setup.

## Table data editor

View and edit your table data with a spreadsheet-like interface:

### Viewing data

- **Paginated Display**: Navigate through large datasets with page controls.
- **Column Management**: Show/hide columns, sort by any column.
- **Data Types**: Visual indicators for different data types (primary keys, foreign keys, etc.).
- **Null Handling**: Clear visualization of NULL values.

### Editing capabilities

- **Inline Editing**: Edit field values directly in the table.
- **Insert New Rows**: Add new records with the "Add Row" button.
- **Delete Rows**: Remove records with confirmation dialogs.
- **Real-time Validation**: Data validation based on column types and constraints.

**Important:** Row editing and deletion require tables to have a primary key defined. This ensures data integrity by uniquely identifying rows for safe updates.

### How to access

1. **From Schema View**: Right-click any table and select "View Table Data".
2. The data opens in a new tab with full editing capabilities.
3. Changes are immediately applied to your database.
4. Use the refresh button to see updates from other sources.

Perfect for quick data inspection, testing, and small data modifications without writing SQL.

## AI agent integration

The Neon extension includes built-in support for AI-powered database features through the [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server):

### Features

- **Automatic MCP Server configuration**: enables AI-powered database features with your coding agent.
- **Chat with your database** using natural language.
- **AI-assisted SQL generation** and schema understanding.
- **View and manage MCP server status** directly in the extension.

The MCP server is automatically configured when you sign in. You can view the status and manage the configuration from the extension panel.

### Extension settings

This extension contributes the following settings:

| Setting                            | Description                                            | Default |
| ---------------------------------- | ------------------------------------------------------ | ------- |
| `neon.mcpServer.autoConfigEnabled` | Automatically configure the Neon MCP server on sign-in | `true`  |

## Available commands

You can run any command by opening the Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`) and typing "Neon".

| Command                     | Description                                            |
| --------------------------- | ------------------------------------------------------ |
| **Neon: Sign In**           | Sign in to your Neon account                           |
| **Neon: Sign Out**          | Sign out from your Neon account                        |
| **Neon: Open SQL Editor**   | Open a new SQL editor tab                              |
| **Neon: View Databases**    | Open the database tree view                            |
| **Neon: Refresh Databases** | Refresh the database tree view                         |
| **Neon: Create Branches**   | Create Neon branches                                   |
| **Neon: Get Started**       | Automatically configure your project to work with Neon |

## Troubleshooting

### Connection errors

- Verify your Neon account is active.
- Ensure you have access to the selected project and branch.
- Check your network connection.

### MCP Server not working

- Check the MCP Server panel status in the extension.
- Try disabling and re-enabling the MCP server.
- Reload the window after configuration changes.

### Database view not updating

- Use the refresh button in the Databases view title bar.
- Disconnect and reconnect to the branch.

## Next steps & resources

- [Branching in Neon](https://neon.com/docs/concepts/branch-your-backend).
- [Neon MCP Server](https://neon.com/docs/ai/neon-mcp-server).
- [Serverless driver](https://neon.com/docs/serverless/serverless-driver).
- [Discord Community](https://neon.com/discord).

--- [Document source](https://neon.com/docs/manage/account-recovery.md) ---

> Summary: To recover a former employee's Neon account, either regain access through the original login provider, or submit a support ticket with company letterhead for manual identity verification. Use this page when ownership was not transferred and your organization needs to recover projects, billing, or admin access. Manual verification requires a government-issued ID.

# Account recovery

Learn how to recover a lost Neon account

Last updated: 2026-06-05

If a former employee owned a Neon account and didn't shut it down or transfer access before leaving, you can follow the steps outlined below to recover the account.

## Regain access through the original login method

First, determine how the account was accessed.

### A. If the account used a third-party login

If the former employee signed up with a third-party identity provider (for example, Google, GitHub, Microsoft, Hasura), you must recover access to that account through your organization's identity provider. Neon cannot bypass third-party authentication.

### B. If the account used email and password

If you have access to the former employee's company email account:

1. Go to the [Neon login page](https://console.neon.tech/login)
2. Click **Forgot Password**
3. Enter the former employee's email address
4. Access the password reset link from their inbox
5. Set a new password and sign in

Once signed in, you can:

- [Update the email address](https://neon.com/docs/manage/accounts#update-personal-information)
- [Transfer project ownership](https://neon.com/docs/manage/orgs-project-transfer)
- [Add an admin](https://neon.com/docs/manage/orgs-manage#set-permissions) to your projects or organization
- [Update billing details](https://neon.com/docs/introduction/manage-billing)

**Note:** For security reasons, we recommend immediately revoking access to company email accounts when employees leave your organization.

## If you cannot access the email or login method

If the original login method is inaccessible, we can assist through a manual identity verification process.

To begin:

1. Open a [Neon Support ticket](https://console.neon.tech/app/projects?modal=support) from your Neon account.
2. Provide:
   - A signed statement on company letterhead explaining the situation
   - Contact details for another employee at your company

Neon will:

- Notify the email address associated with the account and wait 24 business hours (Mon–Fri) for a response
- Send you a document to sign electronically
- Schedule a short video call to verify your identity (please have a government-issued ID ready)

**Info:** Neon will not store or copy your ID. It's used only to confirm that the person on the call is who they say they are.

Once all steps are complete, we'll grant access to the account or transfer project ownership as needed.

**Important:** Neon Support may request additional information during or after the verification process. Manual account recovery is a sensitive procedure designed to protect your organization's data and prevent unauthorized access.

--- [Document source](https://neon.com/docs/manage/accounts.md) ---

> Summary: Neon account settings let you update your profile, change your password, and configure two-factor authentication (2FA) or passkeys. Use this page to switch login methods, enable or remove TOTP-based 2FA, add or remove passkeys, manage personal API keys, or permanently delete your account. 2FA and passkey removal both have a 24-hour security delay. Deleted accounts can be reactivated within 30 days, after which all data is permanently removed.

# Accounts

Manage your Neon account

Last updated: 2026-10-26

Your **Neon account** is your personal identity for logging in, managing your profile, and authenticating actions across all organizations you belong to.

## Account settings

You can access your Neon account settings at [https://console.neon.tech/app/settings](https://console.neon.tech/app/settings) or from anywhere in the Console. Click your profile avatar in the top-right and select **Settings**.

Here's what you can do from **Account settings**.

## Update personal information

Change your name or email address.

![Personal information section in Account settings](https://neon.com/docs/manage/personal_profile.png)

**If you signed up with email**

By default, your email will be used as your first name. You may want to add your first and last name here to complete your profile. Your email is your login and where we'll send all account communications.

**If you signed up with Google, GitHub, or another provider**

Your name and email come from your social account. Feel free to change your name to whatever works for you. If you change your email, we'll unlink your social account and switch you to email sign-in. After that, you'll use your new email and password to log in.

**Changing your email**

If you change your email (whether you started with email or social login), you'll get a verification email to confirm. Once confirmed, your new address becomes your login. If you're using a social login and change your email, we'll unlink your social account and switch you to email sign-in.

[Change your email in the Neon Console](https://console.neon.tech/app/settings?modal=change_email)

### Need to switch your login method?

**If you signed up with Google or GitHub**, you can switch to email login by changing your email and setting a password.

**If you signed up with email,** it's not currently possible to switch to a social login. [Contact Support](https://neon.com/docs/introduction/support) and we'll help you out.

## Change password

No surprises here: just enter your current password, then your new one (twice). We'll enforce our current password rules for your security.

## Two-factor authentication

Protect your account with two-factor authentication (2FA). Once enabled, you'll enter a 6-digit code from your authenticator app each time you log in.

If your organization admin requires 2FA for the organization, you must enroll in 2FA or set up a [passkey](https://neon.com/docs/manage/accounts#passkeys) to continue accessing that organization.

### Enable 2FA

1. Go to **Account settings**, scroll to the **[Two-factor authentication](https://console.neon.tech/app/settings#two-factor)** section, and click **Set up two-factor authentication**.
2. Scan the QR code with your authenticator app (for example, Google Authenticator, Authy, or 1Password). If you can't scan it, enter the setup key shown below the QR code manually.
3. Enter the 6-digit code from your app and click **Verify and enable**.

After setup, Neon will prompt you for a code from your authenticator app every time you log in.

**Tip: iPhone users**

Scanning the QR code with an iPhone camera opens Apple's **Passwords** app, which requires a username and password alongside each authenticator setup. If you sign in with an OAuth provider like Google or GitHub and don't have a Neon password, you'll need to create a placeholder entry in Passwords. Dedicated authenticator apps handle standalone codes without this limitation.

### Remove 2FA

1. Click **Remove two-factor authentication** in your account settings.
2. Enter a 6-digit code from your authenticator app to confirm.

For security, removal is **delayed by 24 hours**. During the cooldown:

- You'll receive an email notification with a link to cancel the removal.
- You can also cancel from your account settings.
- 2FA remains active until the cooldown expires.

**Note:** Recovery codes are not currently supported. Keep your authenticator app backed up or synced across devices. If you lose access to your authenticator, [contact Support](https://neon.com/docs/introduction/support).

## Passkeys

A passkey lets you verify it's you when you sign in, using your device's built-in biometrics (like Touch ID or Windows Hello) or a security key, instead of typing a code. Passkeys are saved through your browser or operating system's passkey manager, such as Google Password Manager or iCloud Keychain.

You can set up both a passkey and two-factor authentication (2FA) on your account. At sign-in, use whichever one you have available.

### Add a passkey

1. Go to **Account settings** and scroll to the **[Passkeys](https://console.neon.tech/app/settings#passkeys)** section.
2. Click **Add passkey**.
3. Give the passkey a name, then click **Continue**.
4. Follow your browser or device's prompts to save the passkey, for example, to Google Password Manager, iCloud Keychain, or a security key.

Your new passkey appears in the list on this page. Click **Add another passkey** to register a passkey for another device.

### Sign in with a passkey

After you enter your email and password, click **Sign in with Passkey** to verify with your passkey instead of entering a code from your authenticator app. Follow your browser or device's prompts to complete verification. If you have more than one passkey saved, your browser may first ask which one to use.

### Remove a passkey

1. Go to **Account settings** and scroll to the **[Passkeys](https://console.neon.tech/app/settings#passkeys)** section.
2. Click **Remove** next to the passkey you want to remove.
3. Verify your identity with an existing passkey.

For security, removal is **delayed by 24 hours**. During the cooldown, the entry shows the time remaining and a **Cancel removal** button in place of **Remove**.

- You'll receive an email notification saying someone requested to remove the passkey, with a link to cancel the removal if it wasn't you.
- You can also cancel anytime from your account settings by clicking **Cancel removal**.
- The passkey remains active until the cooldown expires.

**Note:** If you lose access to your only passkey and have no other way to sign in, [contact Support](https://neon.com/docs/introduction/support).

## Create personal API keys

Personal API keys let you securely interact with the [Neon API](https://neon.com/docs/reference/api), including through command-line tools, scripts, or third-party integrations that use the API. Your personal API key works for any organization you belong to, so you can manage projects, automate tasks, or use integrations across all your orgs with a single key. The actions you can perform with your key depend on your role in each org (admin, member, or collaborator). You can create, view, and revoke your personal API keys here in your account settings.

[Learn more about API keys](https://neon.com/docs/manage/api-keys)

![Personal API keys section in Account settings.](https://neon.com/docs/manage/personal_api_key.png)

## Delete account

Delete your Neon account after leaving or deleting all orgs and projects.

**Important:** You are solely responsible for exporting your Projects and Content from the Neon Platform before the deactivation/deletion of your Account for any reason.

**Leaving an org**

If you're the only admin, promote another member to admin first. You can then leave the org.

**Deleting an org**

Remove all members (so you're the only one left), delete all projects, and you can then delete the org.

Once you have no orgs left, you can then click **Delete**.

### What happens after you delete your account

- You'll receive a confirmation email.
- If you change your mind, you can reactivate your account by logging in again within 30 days. Your personal info will be restored, though not your API keys.
- After 30 days, your account and all related data will be permanently deleted.

## Need to recover access to an account?

See [Account Recovery](https://neon.com/docs/manage/account-recovery) for step-by-step instructions if you need to regain access to a Neon account.

--- [Document source](https://neon.com/docs/manage/api-keys.md) ---

> Summary: Neon API keys are bearer tokens required to authenticate Neon REST API requests, available in personal, organization, and project-scoped variants. Use this page to create, list, or revoke keys via the Console or API. Each key's secret is shown only once at creation; losing it requires revoking and replacing the key, since revocation is immediate and permanent.

# Manage API Keys

Last updated: 2026-10-09

Most actions performed in the Neon Console can also be performed using the [Neon API](https://neon.com/docs/reference/api). You'll need an API key to validate your requests. Each key is a randomly-generated 64-bit token that you must include when calling Neon API methods. All keys remain valid until deliberately revoked.

## Types of API keys

Neon supports three types of API keys:

| Key Type               | Who Can Create              | Scope                                                | Validity                                                                 |
| ---------------------- | --------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------ |
| Personal API Key       | Any user                    | All organization projects where the user is a member | Valid until revoked; org project access ends if user leaves organization |
| Organization API Key   | Organization administrators | All projects within the organization                 | Valid until revoked                                                      |
| Project-scoped API Key | Organization administrators | Single specified project                             | Valid until revoked or project leaves organization                       |

Only organization **Admins** can create organization or project-scoped keys. If you're an Editor, Viewer, or Collaborator, create a personal API key instead; it's scoped to your own access. See [User permissions](https://neon.com/docs/manage/user-permissions) for what each role can do.

While there is no strict limit on the number of API keys you can create, we recommend keeping it under 10,000 per Neon account.

## Creating API keys

You create and manage API keys in the [Neon Console](https://console.neon.tech), and where you go depends on the key type:

- **Personal keys:** open the profile menu in the top-right and go to **Settings** > **API keys**.
- **Organization and project-scoped keys:** switch to your organization, then go to **Settings** > **API keys**.

Each page lists your existing keys with their name, ID, and creation details, plus a button to create a new key. You'll need to create your first API key from the Console, where you are already authenticated. You can then use that key to generate new keys from the API.

> When creating API keys from the Neon Console, the secret token will be displayed only once. Copy it immediately and store it securely in a credential manager (like AWS Key Management Service or Azure Key Vault); you won't be able to retrieve it later. If you lose an API key, you'll need to revoke it and create a new one.

**Important:** You are responsible for maintaining the records and associations of any API keys in your environment and systems.

### Create a personal API key

You can create a personal API key in the Neon Console, with the Neon CLI, or using the Neon API.

**Console**

In the Neon Console, select **Account settings** > **API keys**. You'll see a list of any existing keys, along with the button to create a new key.

![Creating a personal API key in the Neon Console](https://neon.com/docs/manage/personal_api_key.png)

**CLI**

The [`neon api-keys create`](https://neon.com/docs/cli/api-keys#create) command creates a personal key. `--name` is required, and the key is printed once:

```bash
neon api-keys create --name development
```

```text
API key
ID    3225999
Name  development

napi_examplekey1234567890abcdefghijklmnopqrstuvwxyz
WARNING: Store this key now: it is not shown again.
WARNING: This key reaches everything your account can, in every organization. Pass --org-id or --project-id to narrow it.
```

The key is the last line of stdout, so you can capture it directly:

```bash
echo "NEON_API_KEY=$(neon api-keys create --name local-dev -o json | jq -r .key)" >> .env
```

**API**

You'll need an existing personal key (create one from the Neon Console) in order to create new keys using the API. If you've got a key ready, you can use the following request to generate new keys:

```bash
curl https://console.neon.tech/api/v2/api_keys
  -H "Content-Type: application/json"
  -H "Authorization: Bearer $PERSONAL_API_KEY"
  -d '{"key_name": "my-key"}'
```

**Parameters:**

- `key_name`: A descriptive name for the API key (for example, "development", "staging", "ci-pipeline")

**Response:**

```json
{
  "id": 177630,
  "key": "neon_api_key_1234567890abcdef1234567890abcdef"
}
```

To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/api-keys/create-api-key).

### Create an organization API key

Organization API keys provide admin-level access to all organization resources. Only organization admins can create these keys. To create an organization API key, you must use your personal API key and be an administrator in the organization. Neon will verify your admin status before allowing the key creation.

For more detail about organization-related methods, see [Organization API Keys](https://neon.com/docs/manage/orgs-api#api-keys).

**Console**

Navigate to your organization's **Settings** > **API keys** to view a list of existing keys and the button to create a new key.

![creating an api key from the console](https://neon.com/docs/manage/org_api_keys.png)

**CLI**

Pass `--org-id` to [`neon api-keys create`](https://neon.com/docs/cli/api-keys#create). Find your organization ID with `neon orgs list`:

```bash
neon api-keys create --name orgkey --org-id org-example-12345678
```

```text
API key
ID    3243302
Name  orgkey

napi_examplekey1234567890abcdefghijklmnopqrstuvwxyz
WARNING: Store this key now: it is not shown again.
WARNING: This key reaches every project in org-example-12345678, including ones created later. Pass --project-id instead to restrict it to one.
```

You need admin permissions in the organization. As a member the command fails with a permissions error naming your role.

**API**

To create an organization API key via the API, you need to use your personal API key. You also need to have admin-level permissions in the specified organization. This endpoint is rate limited to 10 requests per second; if you create many keys, throttle your requests or use retries with backoff.

```bash
curl --request POST \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/api_keys' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer $PERSONAL_API_KEY' \
     --data '{"key_name": "orgkey"}'
```

**Response:**

```json
{
  "id": 165434,
  "key": "neon_org_key_1234567890abcdef1234567890abcdef",
  "name": "orgkey",
  "created_at": "2022-11-15T20:13:35Z",
  "created_by": "user_01h84bfr2npa81rn8h8jzz8mx4"
}
```

### Create project-scoped organization API keys

Project-scoped API keys have [**Editor** access](https://neon.com/docs/manage/user-permissions#per-project-permissions) on their project, meaning they can read and modify project resources but **cannot** delete the project or manage who can access it. These keys:

- Can only access and manage the specified project
- Cannot perform organization-related actions or create new projects
- Will stop working if the project is transferred out of the organization

**Console**

In your organization's **Settings** > **API keys**, click **Create new** and select **Project-scoped** to create a key for your chosen project.

![Project-scoped API keys from the Console](https://neon.com/docs/manage/project_scoped_select.png)

**CLI**

Pass `--project-id` to [`neon api-keys create`](https://neon.com/docs/cli/api-keys#create). You don't name the organization: the CLI looks it up from the project, and `--org-id` and `--project-id` are mutually exclusive.

```bash
neon api-keys create --name only-this-project --project-id some-project-123
```

```text
API key
ID       3243162
Name     only-this-project
Project  some-project-123

napi_examplekey1234567890abcdefghijklmnopqrstuvwxyz
WARNING: Store this key now: it is not shown again.
Limited to some-project-123: it cannot create projects, mint API keys, or read any other project. It can still change and delete everything inside that project.
```

A project-scoped key is owned by the project's organization, not by your account, so it does not appear in `neon api-keys list`. Use `neon api-keys list --org-id <org-id>` to see it, and pass the same `--org-id` to revoke it.

**API**

Organization administrators can create an API key for any organization-owned project using the following command:

```bash
curl --request POST \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/api_keys' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer $PERSONAL_API_KEY' \
     --data '{"key_name":"only-this-project", "project_id": "some-project-123"}'
```

**Parameters:**

- `org_id`: The ID of your organization
- `key_name`: A descriptive name for the API key
- `project_id`: The ID of the project to which the API key will be scoped

**Example Response:**

```json
{
  "id": 1904821,
  "key": "neon_project_key_1234567890abcdef1234567890abcdef",
  "name": "test-project-scope",
  "created_at": "2026-12-11T21:34:58Z",
  "created_by": "user_01h84bfr2npa81rn8h8jzz8mx4",
  "project_id": "project-id-123"
}
```

## Make an API call

The following example demonstrates how to use your API key to retrieve projects:

```bash
curl 'https://console.neon.tech/api/v2/projects' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

where:

- `"https://console.neon.tech/api/v2/projects"` is the resource URL, which includes the base URL for the Neon API and the `/projects` endpoint.
- The `"Accept: application/json"` in the header specifies the accepted response type.
- The `Authorization: Bearer $NEON_API_KEY` entry in the header specifies your API key. Replace `$NEON_API_KEY` with an actual 64-bit API key. A request without this header, or containing an invalid or revoked API key, fails and returns a `401 Unauthorized` HTTP status code.
- [`jq`](https://stedolan.github.io/jq/) is an optional third-party tool that formats the JSON response, making it easier to read.

<details>

<summary>Response body</summary>

For attribute definitions, find the [Retrieve project details](https://neon.com/docs/reference/api/projects/get-project) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "projects": [
    {
      "cpu_used_sec": 0,
      "id": "purple-shape-411361",
      "platform_id": "aws",
      "region_id": "aws-us-east-2",
      "name": "purple-shape-411361",
      "provisioner": "k8s-pod",
      "pg_version": 15,
      "locked": false,
      "created_at": "2026-01-03T18:22:56Z",
      "updated_at": "2026-01-03T18:22:56Z",
      "proxy_host": "us-east-2.aws.neon.tech",
      "branch_logical_size_limit": 3072
    }
  ]
}
```

</details>

Refer to the [Neon API Reference](https://neon.com/docs/reference/api) for other supported Neon API methods.

## List API keys

**Console**

Navigate to **Account settings** > **API keys** to view your personal API keys, or your organization's **Settings** > **API keys** to view organization API keys.

**CLI**

List your account keys with [`neon api-keys list`](https://neon.com/docs/cli/api-keys#list). It shows key metadata, never the keys themselves:

```bash
neon api-keys list
```

Organization keys aren't visible to your account, so pass `--org-id` to list them.

**API**

For personal API keys:

```bash
curl "https://console.neon.tech/api/v2/api_keys" \
 -H "Authorization: Bearer $NEON_API_KEY" \
 -H "Accept: application/json" | jq
```

For organization API keys:

```bash
curl "https://console.neon.tech/api/v2/organizations/{org_id}/api_keys" \
 -H "Authorization: Bearer $NEON_API_KEY" \
 -H "Accept: application/json" | jq
```

## Revoke API Keys

You should revoke API keys that are no longer needed or if you suspect a key may have been compromised. Key details:

- The action is immediate and permanent
- All API requests using the revoked key will fail with a 401 Unauthorized error
- The key cannot be reactivated; you'll need to create a new key if access is needed again

### Who can revoke keys

- Personal API keys can only be revoked by the account owner
- Organization API keys can be revoked by organization admins
- Project-scoped keys can be revoked by organization admins

**Console**

In the Neon Console, navigate to **Account settings** > **API keys** and click **Revoke** next to the key you want to revoke. The key will be immediately revoked. Any request that uses this key will now fail.

![Revoking an API key in the Neon Console](https://neon.com/docs/manage/revoke_api_key.png)

**CLI**

Revoke a key with [`neon api-keys revoke`](https://neon.com/docs/cli/api-keys#revoke), passing the numeric key ID (not the name). The action is immediate and permanent, so confirm the ID with `neon api-keys list` first:

```bash
neon api-keys revoke 177630
```

Organization and project-scoped keys need admin permissions and `--org-id`.

**API**

The following Neon API method revokes the specified API key. The `key_id` is a required parameter:

```bash
curl -X DELETE \
  'https://console.neon.tech/api/v2/api_keys/177630' \
  -H "Accept: application/json"  \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Revoke API key](https://neon.com/docs/reference/api/api-keys/revoke-api-key) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "id": 177630,
  "name": "mykey",
  "revoked": true,
  "last_used_at": "2022-12-23T23:38:35Z",
  "last_used_from_addr": "192.0.2.21"
}
```

</details>

## Rotate an API key

Neon API keys don't expire or rotate on a schedule, so you rotate one manually. Because revocation is immediate, create the replacement first to avoid downtime:

1. Create a new key with the same scope as the old one (see [Creating API keys](https://neon.com/docs/manage/api-keys#creating-api-keys)).
2. Update every caller that uses the old key, such as CI secrets, Terraform variables, serverless functions, the Neon CLI, and any MCP server configuration.
3. Revoke the old key once nothing depends on it.

If you're rotating because a key was exposed, revoke the compromised key first, then create and roll out its replacement. For rotating Postgres passwords alongside API keys, see [Reset a password](https://neon.com/docs/manage/roles#reset-a-password).

To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/api-keys/create-api-key).

--- [Document source](https://neon.com/docs/manage/backup-pg-dump-automate.md) ---

> Summary: Automated pg_dump backups combine GitHub Actions and AWS S3 to store nightly exports beyond Neon's built-in point-in-time restore window. Read this before following the setup steps. Suited to teams that need long-term retention, disaster recovery, or compliance-driven backup files outside of Neon's native restore feature.

# Automate pg_dump backups

Automate backups of your Neon database to S3 with pg_dump and GitHub Actions

Last updated: 2026-11-04

Keeping regular backups of your database is critical for protecting against data loss. While Neon offers an [instant restore](https://neon.com/docs/introduction/branch-restore) feature (point-in-time restore) that keeps up to 30 days of history, depending on your plan, there are scenarios (such as business continuity, disaster recovery, or regulatory compliance) where maintaining independent and longer-lived backup files may be necessary. In these cases, using the Postgres `pg_dump` tool to create backups and storing them on a reliable external service (like an AWS S3 bucket) gives you control over long-term retention and recovery of your data.

Manually performing backups can be tedious and time consuming, so automation is key to ensure you're taking backups consistently. An automated backup process also lets you enforce retention policies by automatically cleaning up old backups, saving storage, and keeping your backup repository tidy.

This two-part guide walks you through setting up an automated backup pipeline using `pg_dump` and GitHub Actions. You will configure everything needed to run nightly backups and store them in S3, ensuring your data is available to restore if needed.

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) (the hostname without the `-pooler` suffix) for the backup connection.

- [Part 1: Create an S3 bucket to store backups](https://neon.com/docs/manage/backups-aws-s3-backup-part-1): Set up an AWS S3 bucket for storing backups
- [Part 2: Automate with GitHub Actions](https://neon.com/docs/manage/backups-aws-s3-backup-part-2): Schedule nightly backups with GitHub Actions and pg_dump

--- [Document source](https://neon.com/docs/manage/backup-pg-dump.md) ---

> Summary: Use pg_dump to back up a Lakebase Postgres database to a local custom-format archive, and pg_restore to restore it to any Neon project, including across regions. Always use a direct (unpooled) connection string for both operations; avoid pooled connections.

# Backups with pg_dump

Learn how to create a backup of your Neon database using pg_dump

Last updated: 2026-11-04

This topic describes how to create a backup of your Neon database using the Postgres `pg_dump` utility and how to restore a backup using `pg_restore`.

The same **`pg_dump`** flow applies when you **export** data for a **region migration** or a **Postgres-compatible export from Neon**. For path selection (another Neon region, Lakebase, or export), see **[Region migration](https://neon.com/docs/import/region-migration)**.

**Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

## Prerequisites

- Make sure `pg_dump` and `pg_restore` are installed. You can verify by running `pg_dump -V`.
- We recommend using the latest versions of `pg_dump` and `pg_restore`, and ensuring that the client version matches your Neon project's Postgres version.

## Install `pg_dump` and `pg_restore`

If you don't have the `pg_dump` and `pg_restore` utilities installed locally, you'll need to install them on your preferred platform.

**Windows**

1. Install PostgreSQL using the official installer from [https://www.postgresql.org/download/windows/](https://www.postgresql.org/download/windows/).
2. `pg_dump` and `pg_restore` are installed by default and can be found in the PostgreSQL `bin` directory.

**Mac**

1. Install PostgreSQL using Homebrew with the command: brew install postgresql.
2. `pg_dump` and `pg_restore` come with the installation and are available in your `PATH`.

**Linux**

1. On Ubuntu/Debian, install the PostgreSQL client tools with: `sudo apt-get install postgresql-client`.
2. `pg_dump` and `pg_restore` will be available after installation.

**Docker**

1. Pull the official PostgreSQL Docker image: `docker pull postgres`.
2. Run the container with: `docker run --name postgres -e POSTGRES_PASSWORD=yourpassword -d -p 5432:5432 postgres`.
3. Verify `pg_dump` is available by running: `docker run --rm postgres pg_dump --version`.

## Creating a backup with `pg_dump`

Following this procedure will create a database backup locally, where you're running the `pg_dump` command.

1. Retrieve the connection string for your Neon database by clicking **Connect** in the Console nav to open the **Connect to your branch** modal.

2. Deselect the **Connection pooling** option. You need a direct connection string, not a pooled one.

   Your connection string should look something like this:

   ```bash
   postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require
   ```

3. Create a backup of your Neon database by running the following `pg_dump` command with your Neon database connection string.

   ```bash
   pg_dump -Fc -v -d "<neon_database_connection_string>" -f <dump_file_name>
   ```

   After adding your Neon database connection string and a dump file name, your command will look something like this:

   ```bash
   pg_dump -Fc -v -d "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require" -f mydatabase.bak
   ```

   The `pg_dump` command above includes these arguments:

   - `-Fc`: Sends the output to a custom-format archive suitable for input into `pg_restore`.
   - `-v`: Runs `pg_dump` in verbose mode, allowing you to monitor what happens during the dump operation.
   - `-d`: Specifies the [connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) for your Neon database.
   - `-f <dump_file_name>`: The dump file name. It can be any name you choose (`mydumpfile.bak`, for example).

   For more command options, see [Advanced pg_dump and pg_restore options](https://neon.com/docs/import/migrate-from-postgres#advanced-pgdump-and-pgrestore-options).

For most accidental-delete recoveries you don't need a local file. Neon keeps a change history that supports [instant restore](https://neon.com/docs/introduction/branch-restore) (point-in-time restore) within your project's [history window](https://neon.com/docs/introduction/history-window), which is usually faster. Reach for a local `pg_dump` backup when you need off-platform redundancy, archival beyond your history window, an external copy for compliance, or a copy to move into a different Postgres instance.

## Restoring a backup with `pg_restore`

This procedure shows how to restore a database using the `pg_restore` utility from a backup file created using `pg_dump`, as described above.

1. Create a new Neon project.

2. Create a database with the same name as the one you backed up. The `pg_dump` instructions above created a backup of a database named `neondb`. Your database name is likely different.

3. Retrieve the connection string for your Neon database:

   Go to your Neon project and click the **Connect** button to open the **Connect to your branch** modal.

   Deselect the **Connection pooling** option. You need a direct connection string, not a pooled one.

   Your connection string should look something like this:

   ```bash
   postgresql://alex:AbC123dEf@ep-dry-morning-a8vn5za2.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require
   ```

4. Restore your data to the target database in Neon with `pg_restore`.

   ```bash
   pg_restore -v -d "<neon_database_connection_string>" <dump_file_name>
   ```

   After adding your Neon database connection string and the dump file name, your command will look something like this:

   ```bash
   pg_restore -v -d "postgresql://alex:AbC123dEf@ep-dry-morning-a8vn5za2.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require" mydatabase.bak
   ```

   The example above includes these arguments:

   - `-v`: Runs `pg_restore` in verbose mode, allowing you to monitor what happens during the restore operation.
   - `-d`: Specifies the Neon database to connect to. The value is a Neon database connection string. See [Prerequisites](https://neon.com/docs/manage/backup-pg-dump#prerequisites).
   - `<dump_file_name>` is the name of the dump file you created with `pg_dump`.

   For more command options, see [Advanced pg_dump and pg_restore options](https://neon.com/docs/import/migrate-from-postgres#advanced-pgdump-and-pgrestore-options).

## `pg_dump` and `pg_restore` example

The following example shows how data is dumped from source database named `neondb` in one Neon project and restored to a `neondb` database in another Neon project using the commands described in the previous sections. (A database named `neondb` was created in the Neon project prior to running the restore operation.)

Before performing this procedure:

- A new Neon project was created for the destination database, and a database with the same name as the source database was created (`neondb`)
- Connection strings for the source and destination databases were collected:
  - source: `postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require`
  - destination: `postgresql://alex:AbC123dEf@ep-dry-morning-a8vn5za2.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require`

```bash
~$ cd mydump
~/mydump$ pg_dump -Fc -v -d "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require" -f mydatabase.bak

~/mydump$ ls
mydatabase.bak

~/mydump$ pg_restore -v -d "postgresql://alex:AbC123dEf@ep-dry-morning-a8vn5za2.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require" mydatabase.bak
```

--- [Document source](https://neon.com/docs/manage/backups-aws-s3-backup-part-1.md) ---

> Summary: Part 1 of a 2-part guide for backing up a Postgres database to AWS S3 using GitHub Actions. Covers creating an OIDC identity provider in IAM, an IAM role with a trusted web identity, an S3 bucket, and a bucket policy granting List, Get, Put, and Delete access. Complete this AWS-side setup before wiring up the GitHub Actions workflow in part 2. Co-locating the bucket with the database region reduces latency and transfer costs.

# Create an S3 bucket to store Postgres backups

Last updated: 2026-06-05

This guide will walk you through setting up an AWS S3 bucket to store your Postgres backups.

**Note:** This is part one of a two-part guide.
Continue to part two [here](https://neon.com/docs/manage/backups-aws-s3-backup-part-2).

## Prerequisites

To complete this guide, you'll need an AWS user with the appropriate permissions to:

- **Manage IAM resources**: Create an OpenID Connect (OIDC) identity provider and IAM roles.
- **Manage S3**: Create an S3 bucket and update its bucket policy.

These actions typically require AdministratorAccess or a custom IAM policy granting the necessary permissions. If you're not an administrator, ensure your user has IAM management privileges and S3 permissions.

## Setup AWS Providers and Roles

There are three parts to the AWS setup, they are:

1. Creating an OIDC Identity Provider
2. Creating a Role
3. Creating an S3 bucket and updating the S3 bucket policy

## Add an Identity provider

An OIDC (OpenID Connect) Identity Provider (IdP) in AWS is a third-party service that handles authentication. To allow GitHub Actions to authenticate with AWS, you must add GitHub as an identity provider.

To create a new Identity Provider, navigate to: **IAM** > **Access Management** > **Identity Providers**, and click **Add provider**.

![AWS Access Management](https://neon.com/docs/manage/1-s3-backups-github-actions-01-identity-provider-1.jpg)

On the next screen select OpenID Connect and add the following to the Provider URL and Audience fields.

1. Provider URL: `https://token.actions.githubusercontent.com`
2. Audience: `sts.amazonaws.com`

When you're done, click **Add Provider**.

![AWS Identity Provider](https://neon.com/docs/manage/1-s3-backups-github-actions-02-identity-provider-2.jpg)

You should now see this provider is visible in the list under: **IAM** > **Access Management** > **Identity Providers**.

## Create Role

A Role is an identity that you can assume to obtain temporary security credentials for specific tasks or actions within AWS. Roles are used to delegate permissions and grant access to AWS services without the need for credentials like passwords or access keys.

To create a new Role, navigate to: **IAM** > **Access Management** > **Roles**, and click **Create role**.

![AWS Identity Role](https://neon.com/docs/manage/1-s3-backups-github-actions-03-role-1.jpg)

On the next screen you can create a **Trusted Identity** for the Role.

## Select Trusted Identity

On this screen select **Web Identity**, then select `token.actions.githubusercontent.com` from the **Identity Provider** dropdown menu.

![AWS Trust Identity 1](https://neon.com/docs/manage/1-s3-backups-github-actions-04-trust-identity-1.jpg)

Once you select the **Identity Provider**, you'll be shown a number of fields to fill out.

Select `sts.amazonaws.com` from the **Audience dropdown** menu, then fill out the GitHub repository details as per your requirements.

When you're ready, click **Next**.
![AWS Trust Identity 2](https://neon.com/docs/manage/1-s3-backups-github-actions-05-trust-identity-2.jpg)

## Add Permissions: Skip

You can skip selecting anything from this screen and click **Next** to continue.

## Name, review and create

On this screen give the **Role** a name and description. You'll use the **Role** name in the code for the GitHub Action. Consider naming this role using specifics as to avoid confusion later down the line.

When you're ready click **Create role**.

![AWS Trust Identity 3](https://neon.com/docs/manage/1-s3-backups-github-actions-06-trust-identity-3.jpg)

## Setup AWS S3 bucket

There are two parts to creating an S3 bucket, they are:

1. Creating an S3 bucket
2. Updating the bucket policy

## Create S3 bucket

AWS S3 (Simple Storage Service) buckets are storage containers used to store objects in Amazon's cloud storage service. An S3 bucket can store any amount of data, from files and documents to images and videos, or in the case of a database backup, a .gz (​​[GNU zip](https://www.gnu.org/software/gzip/)) file.

To create a new bucket, navigate to: **S3** > **buckets**, and click **Create bucket**.

![AWS S3 Bucket](https://neon.com/docs/manage/1-s3-backups-github-actions-07-bucket-1.jpg)

On the next screen select **General Purpose** for the bucket Type and then give your bucket a name.

The most important thing to notice on this screen is the **region** where you're creating the bucket.

![AWS S3 Bucket](https://neon.com/docs/manage/1-s3-backups-github-actions-08-bucket-2.jpg)

It's recommended that you deploy your bucket to the same region as your database to minimize latency and reduce backup times. While having an S3 bucket in `us-east-1` and a database in `ap-southeast-1` isn't necessarily a problem, cross-region data transfers can take longer and may introduce additional costs.

## S3 bucket Policy

To ensure the **Role** being used in the GitHub Action can perform actions on the S3 bucket, you'll need to update the bucket policy.

Select your bucket then select the **Permissions** tab and click **Edit**.

![AWS S3 Bucket Policy](https://neon.com/docs/manage/1-s3-backups-github-actions-09-bucket-3.jpg)

You can now add the following policy which grants the **Role** you created earlier access to perform S3 **List**, **Get**, **Put** and **Delete** actions.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::627917386332:role/neon-s3-backup-github-actions"
      },
      "Action": ["s3:ListBucket", "s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
      "Resource": ["arn:aws:s3:::neon-s3-backup", "arn:aws:s3:::neon-s3-backup/*"]
    }
  ]
}
```

From the snippet above replace the Role name `neon-s3-backup-github-actions` with your **Role** name and replace the S3 bucket name `neon-s3-backup` with your S3 bucket name. When you're ready click **Save changes**.

## Next steps

There are a couple of things to note before moving on to the second part of this guide. You'll be creating several GitHub Secrets to hold various values that you likely won't want to expose or repeat in code. These are:

- `AWS_ACCOUNT_ID`: This can be found by clicking on your user name in the AWS console.
- `S3_BUCKET_NAME`: In this example, this value would be, `neon-s3-backup`
- `IAM_ROLE`: In this example this value would be, `neon-s3-backup-github-action`

Make a note of these values before you proceed to [part two](https://neon.com/docs/manage/backups-aws-s3-backup-part-2).

--- [Document source](https://neon.com/docs/manage/backups-aws-s3-backup-part-2.md) ---

> Summary: Part 2 of a 2-part guide: a scheduled GitHub Actions workflow that runs `pg_dump` nightly, compresses the output as a gzip file, and uploads it to S3 using IAM role-based authentication via GitHub Secrets. Complete the IAM and S3 bucket setup in part 1 before using this page. Includes a configurable retention step that auto-deletes backups older than a set number of days. Set `PG_VERSION` and `AWS_REGION` to target any Postgres version or AWS region.

# Set up a GitHub Action to perform nightly Postgres backups

Last updated: 2026-11-04

This guide shows you how to configure nightly Postgres backups using a scheduled GitHub Action and `pg_dump`.

**Note:** This is part two of a two-part guide. Make sure you've completed [part 1](https://neon.com/docs/manage/backups-aws-s3-backup-part-1) first.

## Prerequisites

Setting up a scheduled backup involves three key components:

### 1. AWS Requirements

- You'll need your **AWS Account ID** and permissions to:
  - Create **IAM Roles** and **Identity Providers**
  - Create and manage **S3 buckets**
  - Update **S3 bucket policies**

### 2. Postgres Database

- Ensure you have:
  - The **connection string** for your database
  - The **AWS region** where your database is deployed
  - The **Postgres version** your database is running

**Important:** Use a direct (unpooled) connection string for `DATABASE_URL`. Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string); use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead. Make sure the hostname does not include the `-pooler` suffix.

### 3. GitHub Action

- You'll need **repository access** with permission to manage:
  - **Actions** and **Settings** > **Secrets and variables**

## Neon project setup

Before looking at the code, first take a look at your Neon console dashboard. In our example there is only one project, with a single database named `acme-co-prod`. This database is running Postgres 17 and deployed in the `us-east-1` region.

The goal is to backup this database to it's own folder inside an S3 bucket using the same name.

![Neon Console](https://neon.com/docs/manage/2-s3-backups-github-actions-01-neon-projects.jpg)

## Scheduled GitHub Action

Using the same database naming convention as above, create a new file for the GitHub Action using the following folder structure.

```shell
.github
  |-- workflows
      |-- acme-co-prod-backup.yml
```

![Neon Console](https://neon.com/docs/manage/2-s3-backups-github-actions-02-github-workflows.jpg)

This GitHub Action will run on a recurring schedule and save the backup file to a S3 bucket as defined by the environment variables. Below the code snippet we've explained what each part of the Action does.

```yml
name: acme-co-prod-backup

on:
  schedule:
    - cron: '0 5 * * *' # Runs at midnight EST (us-east-1)
  workflow_dispatch:

jobs:
  db-backup:
    runs-on: ubuntu-latest

    permissions:
      id-token: write

    env:
      RETENTION: 7
      DATABASE_URL: ${{ secrets.ACME_CO_PROD }}
      IAM_ROLE: ${{ secrets.IAM_ROLE }}
      AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
      S3_BUCKET_NAME: ${{ secrets.S3_BUCKET_NAME }}
      AWS_REGION: 'us-east-1'
      PG_VERSION: '17'

    steps:
      - name: Install PostgreSQL
        run: |
          sudo apt update
          yes '' | sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
          sudo apt install -y postgresql-${{ env.PG_VERSION }}

      - name: Set PostgreSQL binary path
        run: echo "POSTGRES=/usr/lib/postgresql/${{ env.PG_VERSION }}/bin" >> $GITHUB_ENV

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT_ID }}:role/${{ env.IAM_ROLE }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Set file, folder and path variables
        run: |
          GZIP_NAME="$(date +'%B-%d-%Y@%H:%M:%S').sql.gz"
          FOLDER_NAME="${{ github.workflow }}"
          UPLOAD_PATH="s3://${{ env.S3_BUCKET_NAME }}/${FOLDER_NAME}/${GZIP_NAME}"

          echo "GZIP_NAME=${GZIP_NAME}" >> $GITHUB_ENV
          echo "FOLDER_NAME=${FOLDER_NAME}" >> $GITHUB_ENV
          echo "UPLOAD_PATH=${UPLOAD_PATH}" >> $GITHUB_ENV

      - name: Create folder if it doesn't exist
        run: |
          if ! aws s3api head-object --bucket ${{ env.S3_BUCKET_NAME }} --key "${{ env.FOLDER_NAME }}/" 2>/dev/null; then
            aws s3api put-object --bucket ${{ env.S3_BUCKET_NAME }} --key "${{ env.FOLDER_NAME }}/"
          fi

      - name: Run pg_dump
        run: |
          set -o pipefail
          : "${DATABASE_URL:?DATABASE_URL secret is not set}"
          "${POSTGRES}/pg_dump" "$DATABASE_URL" | gzip > "$GZIP_NAME"

      - name: Empty bucket of old files
        run: |
          THRESHOLD_DATE=$(date -d "-${{ env.RETENTION }} days" +%Y-%m-%dT%H:%M:%SZ)
          aws s3api list-objects --bucket ${{ env.S3_BUCKET_NAME }} --prefix "${{ env.FOLDER_NAME }}/" --query "Contents[?LastModified<'${THRESHOLD_DATE}'] | [?ends_with(Key, '.gz')].{Key: Key}" --output text | while read -r file; do
            aws s3 rm "s3://${{ env.S3_BUCKET_NAME }}/${file}"
          done

      - name: Upload to bucket
        run: |
          aws s3 cp "${{ env.GZIP_NAME }}" "${{ env.UPLOAD_PATH }}" --region ${{ env.AWS_REGION }}
```

## Action configuration

The first part of the GitHub Action specifies the name of the Action and sets the schedule for when it should run.

```yml
name: acme-co-prod-backup

on:
  schedule:
    - cron: '0 5 * * *' # Runs at midnight EST (us-east-1)
  workflow_dispatch:
```

- `name` : The workflow name and will also be used when creating the folder in the S3 bucket
- `cron`: This determines how often the Action will run, take a look a the GitHub docs where the [POSIX cron syntax](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule) is explained
- `workflow_dispatch`: This allows you to trigger the workflow manually from the GitHub UI

## Environment variables

The next part deals with environment variables. Some variables are set inline in the Action but others are defined using [GitHub Secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository).

```yml
env:
  RETENTION: 7
  DATABASE_URL: ${{ secrets.ACME_CO_PROD }}
  IAM_ROLE: ${{ secrets.IAM_ROLE }}
  AWS_ACCOUNT_ID: ${{ secrets.AWS_ACCOUNT_ID }}
  S3_BUCKET_NAME: ${{ secrets.S3_BUCKET_NAME }}
  AWS_REGION: 'us-east-1'
  PG_VERSION: '17'
```

- `RETENTION`: Determines how long a backup file should be retained before it's deleted
- `DATABASE_URL`: The database connection string for the database you're backing up
- `IAM_ROLE`: The name of the AWS IAM Role
- `AWS_ACCOUNT_ID`: Your AWS Account Id
- `S3_BUCKET_NAME`: The name of the S3 bucket where all backups are being stored
- `AWS_REGION`: The region where the S3 bucket is deployed
- `PG_VERSION`: The version of Postgres to install in the GitHub Action environment

## GitHub Secrets

As mentioned earlier, several of the environment variables in the Action are defined using GitHub secrets. These secrets can be added to your repository by navigating to **Settings** > **Secrets and variables** > **Actions**.

![GitHub Secrets](https://neon.com/docs/manage/2-s3-backups-github-actions-03-github-secrets.jpg)

## Install PostgreSQL

This step installs Postgres into the GitHub Action's virtual environment. The version to install is defined by the `PG_VERSION` environment variable.

```yml
- name: Install PostgreSQL
  run: |
    sudo apt update
    yes '' | sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
    sudo apt install -y postgresql-${{ env.PG_VERSION }}
```

## Set PostgreSQL binary path

This step sets the `$POSTGRES` variable, allowing easy access to the Postgres binaries in the GitHub Action's environment.

```yml
- name: Set PostgreSQL binary path
  run: echo "POSTGRES=/usr/lib/postgresql/${{ env.PG_VERSION }}/bin" >> $GITHUB_ENV
```

## Configure AWS credentials

This step configures the AWS credentials, enabling secure interaction between the GitHub Action and AWS services.

```yml
- name: Configure AWS credentials
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::${{ env.AWS_ACCOUNT_ID }}:role/${{ env.IAM_ROLE }}
    aws-region: ${{ env.AWS_REGION }}
```

## Set file, folder and path variables

This step involves setting three variables that are all output to `GITHUB_ENV`. This allows other steps in the Action to access them.

```yml
- name: Set file, folder and path variables
  run: |
    GZIP_NAME="$(date +'%B-%d-%Y@%H:%M:%S').sql.gz"
    FOLDER_NAME="${{ github.workflow }}"
    UPLOAD_PATH="s3://${{ env.S3_BUCKET_NAME }}/${FOLDER_NAME}/${GZIP_NAME}"

    echo "GZIP_NAME=${GZIP_NAME}" >> $GITHUB_ENV
    echo "FOLDER_NAME=${FOLDER_NAME}" >> $GITHUB_ENV
    echo "UPLOAD_PATH=${UPLOAD_PATH}" >> $GITHUB_ENV
```

The three variables are as follows:

1. `GZIP_NAME`: The name of the `.sql.gz` file derived from the date e.g, `February-20-2025@07:53:02.sql.gz`
2. `FOLDER_NAME`: The folder where the `.gz` files are to be uploaded
3. `UPLOAD_PATH`: This is the full path that includes the S3 bucket name, folder name and `.gz` file

## Create folder if it doesn't exist

This step creates a new folder (if one doesn't already exist) inside the S3 bucket using the `FOLDER_NAME` as defined in the previous step.

```yml
- name: Create folder if it doesn't exist
  run: |
    if ! aws s3api head-object --bucket ${{ env.S3_BUCKET_NAME }} --key "${{ env.FOLDER_NAME }}/" 2>/dev/null; then
      aws s3api put-object --bucket ${{ env.S3_BUCKET_NAME }} --key "${{ env.FOLDER_NAME }}/"
    fi
```

## Run pg_dump

This step runs `pg_dump` and saves the output in the Action's virtual memory using the `GZIP_NAME` as defined in the previous step.

```yml
- name: Run pg_dump
  run: |
    set -o pipefail
    : "${DATABASE_URL:?DATABASE_URL secret is not set}"
    "${POSTGRES}/pg_dump" "$DATABASE_URL" | gzip > "$GZIP_NAME"
```

GitHub Actions already runs `bash` steps with `pipefail` enabled, but setting it explicitly makes the intent clear and keeps the step correct even if the shell is overridden: the step fails if `pg_dump` fails, instead of masking the error behind a successful `gzip`. The `DATABASE_URL` check fails the step early with a clear message if the secret is missing.

## Empty bucket of old files

This optional step automatically removes `.gz` files older than the retention period specified by the `RETENTION` variable. It checks the `FOLDER_NAME` directory and deletes outdated backups to save storage space.

```yml
- name: Empty bucket of old files
  run: |
    THRESHOLD_DATE=$(date -d "-${{ env.RETENTION }} days" +%Y-%m-%dT%H:%M:%SZ)
    aws s3api list-objects --bucket ${{ env.S3_BUCKET_NAME }} --prefix "${{ env.FOLDER_NAME }}/" --query "Contents[?LastModified<'${THRESHOLD_DATE}'] | [?ends_with(Key, '.gz')].{Key: Key}" --output text | while read -r file; do
      aws s3 rm "s3://${{ env.S3_BUCKET_NAME }}/${file}"
    done
```

## Upload to bucket

This step uploads the `.gz` file created by the `pg_dump` step and uploads it to the correct folder within the S3 bucket.

```yml
- name: Upload to bucket
  run: |
    aws s3 cp "${{ env.GZIP_NAME }}" "${{ env.UPLOAD_PATH }}" --region ${{ env.AWS_REGION }}
```

## Finished

After committing and pushing the workflow to your GitHub repository, the Action will automatically run on the specified schedule, ensuring your Postgres backups are performed regularly.

## Restoring from a backup

The workflow saves a gzip-compressed plain SQL dump, so restore it with `psql`, not `pg_restore`. Download the file from S3, then pipe it into the target database:

```bash
aws s3 cp "s3://<bucket>/<folder>/<file>.sql.gz" .
gunzip -c <file>.sql.gz | psql "<target connection string>"
```

Restore into a new, empty database, such as one in a new Neon project. To restore with `pg_restore` instead, for example to restore a single table, change the `pg_dump` step to `pg_dump -Fc` and see [Restoring a backup with pg_restore](https://neon.com/docs/manage/backup-pg-dump#restoring-a-backup-with-pgrestore).

--- [Document source](https://neon.com/docs/manage/branches.md) ---

> Summary: Storage is unlimited on paid plans: there's no hard per-branch size limit and storage grows with your usage, so a branch can grow as large as your data requires. Neon branches are copy-on-write clones of a parent branch that isolate schema and data changes without affecting the parent. Each project starts with a root branch; you can create child branches from it or any existing branch. Use this page to create, rename, protect, restore, or delete branches via the Console, CLI, or API. Unused branches accumulate storage costs as they age past the history window.

# Manage branches

Last updated: 2026-10-09

Data resides in a branch. Each Neon project is created with a [root branch](https://neon.com/docs/manage/branches#root-branch), which is also designated as your [default branch](https://neon.com/docs/manage/branches#default-branch). Projects created in the Neon Console have a root branch named `production`, while projects created via the API or CLI have a root branch named `main`. You can create child branches from your root branch or from previously created branches. A branch can contain multiple databases and roles. Neon's [plan allowances](https://neon.com/docs/introduction/plans) define the number of branches you can create.

A child branch is a copy-on-write clone of the parent branch. You can modify the data in a branch without affecting the data in the parent branch.
For more information about branches and how you can use them in your development workflows, see [Branching](https://neon.com/docs/introduction/branching).

You can create and manage branches using the Neon Console, [Neon CLI](https://neon.com/docs/cli), or [Neon API](https://neon.com/docs/reference/api).

**Important:** When working with branches, it is important to remove old and unused branches. Branches hold a lock on the data they contain, which will add to your storage usage as they age out of your project's [history window](https://neon.com/docs/introduction/history-window).

## Branch naming requirements

Specifying a branch name is optional. If you don't provide one, the branch name defaults to the automatically generated branch ID with a `br-` prefix (for example, `br-curly-wave-123456`).

If you do specify a custom branch name when creating or renaming a branch, it must meet the following requirements:

- **Maximum length**: 256 characters (API limit). Note that the Neon Console enforces a more restrictive limit of 128 characters.
- **Uniqueness**: Branch names must be unique within a project. You cannot have two branches with the same name in the same project.
- **Non-empty**: Branch names cannot be empty or consist only of whitespace characters.
- **Character flexibility**: Unlike some other Neon resources (such as databases or roles), branch names have no special character restrictions. You can use any characters as long as they meet the requirements above.

## Create a branch

**Console**

To create a branch:

1. In the Neon Console, select a project.
2. Select **Branches** in the sidebar.
3. Click **New branch** to open the branch creation dialog.
   ![Create branch dialog](https://neon.com/docs/manage/create_branch.png)
4. Select a **Parent branch**. This determines the origin of the schema and data for your new branch. By default, your project's default branch (named `main` if the project was created with the CLI or API, or `production` if created in the Console) is selected, but you can choose any existing branch in your project.
5. Specify a branch name, or leave it blank to use the default generated name.
6. Select what to include in the new branch:
   - **Current data**: Creates a copy of the parent branch's latest data and schema, resulting in an isolated database that reflects the parent at the time of creation.
   - **Past data**: Creates a copy using data from a specific past date and time of the parent branch. The parent branch must have the relevant history.

     **Note:** You can only specify a date and time that falls within your [history window](https://neon.com/docs/introduction/history-window).
   - **Schema only**: Replicates only the database schema (tables, views, roles, etc.) from the parent branch, without copying any of the actual data. This is useful for testing migrations or building new test data without exposing sensitive real-world data. See [Schema-only branches](https://neon.com/docs/guides/branching-schema-only).
   - **Anonymized data**: Creates a branch with masked sensitive data. You can configure data anonymization rules to protect personally identifiable information while preserving realistic data sets for development. See [Data anonymization](https://neon.com/docs/workflows/data-anonymization).
7. Configure auto-deletion: By default, **Automatically delete branch after** is checked with 1 day selected to help prevent unused branches from accumulating. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable expiration entirely. This is useful for CI/CD pipelines and short-lived development environments. Note: This default only applies when creating branches through the Console; API and CLI branches have no expiration by default. Refer to our [Branch expiration guide](https://neon.com/docs/guides/branch-expiration) for details.
8. Click **Create** to create your branch.

You are presented with the connection details for your new branch and directed to the **Branch** overview page where you are shown the details for your new branch.

**Note: Postgres role passwords on branches**

When creating a new branch, the branch will have the same Postgres roles and passwords as the parent branch. If you want your branch created with new role passwords, you can enable [branch protection](https://neon.com/docs/guides/protected-branches).

**CLI**

Create a branch with [`neon branches create`](https://neon.com/docs/cli/branches#create). By default it branches from your project's default branch; pass `--name` to name it:

```bash
neon branches create --name mybranch
```

**API**

Create a branch with the [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch) endpoint. The `branch` attribute specifies the parent; the `endpoints` attribute creates a compute, which is required to connect:

```bash
curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoints": [
    {
      "type": "read_write"
    }
  ],
  "branch": {
    "parent_id": "br-wispy-dew-591433"
  }
}'
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "branch": {
    "id": "br-curly-wave-123456",
    "project_id": "dry-heart-13671059",
    "parent_id": "br-morning-meadow-123456",
    "parent_lsn": "0/1FA22C0",
    "name": "br-curly-wave-123456",
    "current_state": "init",
    "pending_state": "ready",
    "state_changed_at": "2026-08-04T07:13:09Z",
    "creation_source": "console",
    "primary": false,
    "default": false,
    "protected": false,
    "cpu_used_sec": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "written_data_bytes": 0,
    "data_transfer_bytes": 0,
    "created_at": "2026-08-04T07:13:09Z",
    "updated_at": "2026-08-04T07:13:09Z",
    "created_by": {
      "name": "your@email.com",
      "image": ""
    },
    "init_source": "parent-data"
  },
  "endpoints": [
    {
      "host": "ep-cool-darkness-123456.c-2.us-west-2.aws.neon.tech",
      "id": "ep-cool-darkness-123456",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-curly-wave-123456",
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 0.25,
      "region_id": "aws-us-west-2",
      "type": "read_write",
      "current_state": "init",
      "pending_state": "active",
      "settings": {},
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "creation_source": "console",
      "created_at": "2026-08-04T07:13:09Z",
      "updated_at": "2026-08-04T07:13:09Z",
      "proxy_host": "c-2.us-west-2.aws.neon.tech",
      "suspend_timeout_seconds": 0,
      "provisioner": "k8s-neonvm"
    }
  ],
  "operations": [
    {
      "id": "8289b00a-4341-48d2-b3f1-d0c8dbb7e806",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-curly-wave-123456",
      "action": "create_branch",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T07:13:09Z",
      "updated_at": "2026-08-04T07:13:09Z",
      "total_duration_ms": 0
    },
    {
      "id": "a3c9baa4-6732-4774-a141-9d03396babce",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-curly-wave-123456",
      "endpoint_id": "ep-cool-darkness-123456",
      "action": "start_compute",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2026-08-04T07:13:09Z",
      "updated_at": "2026-08-04T07:13:09Z",
      "total_duration_ms": 0
    }
  ],
  "roles": [
    {
      "branch_id": "br-curly-wave-123456",
      "name": "alex",
      "protected": false,
      "created_at": "2026-08-04T07:07:55Z",
      "updated_at": "2026-08-04T07:07:55Z"
    }
  ],
  "databases": [
    {
      "id": 2886327,
      "branch_id": "br-curly-wave-123456",
      "name": "dbname",
      "owner_name": "alex",
      "created_at": "2026-08-04T07:07:55Z",
      "updated_at": "2026-08-04T07:07:55Z"
    }
  ],
  "connection_uris": [
    {
      "connection_uri": "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.c-2.us-west-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require",
      "connection_parameters": {
        "database": "dbname",
        "password": "AbC123dEf",
        "role": "alex",
        "host": "ep-cool-darkness-123456.c-2.us-west-2.aws.neon.tech",
        "pooler_host": "ep-cool-darkness-123456-pooler.c-2.us-west-2.aws.neon.tech"
      }
    }
  ]
}
```

</details>

## View branches

**Console**

To view the branches in a Neon project:

1. In the Neon Console, select a project.

2. Select **Branches** in the sidebar to view all current branches in the project.

   ![all branches](https://neon.com/docs/manage/branches_all_list.png)

   Branch details in this table view include:

   - **Branch**: The branch name, which is a generated name if no name was specified when created.
   - **Parent**: Indicates the parent from which this branch was created, helping you track your branch hierarchy.
   - **Compute hours**: Number of hours the branch's compute was active so far in the current billing period.
   - **Primary compute**: Shows the current compute size and status for the branch's compute.
   - **Data size**: Indicates the logical data size of the branch, helping you monitor your plan's storage limit. Data size does not include history.
   - **Created by**: The account or integration that created the branch.
   - **Last active**: Shows when the branch's compute was last active.

3. Select a branch from the table to view details about the branch.

   Branch details shown on the branch page may include:

   - **Archive status**: This only appears if the branch was archived. For more, see [Branch archiving](https://neon.com/docs/guides/branch-archiving).
   - **ID**: The branch ID. Branch IDs have a `br-` prefix.
   - **Created on**: The date and time the branch was created.
   - **Compute hours**: The compute hours used by the default branch in the current billing period.
   - **Data size**: The logical data size of the branch. Data size does not include history.
   - **Parent branch**: The branch from which this branch was created (only applicable to child branches).

   The branch details page also includes details about the **Computes**, **Roles**, **Databases**, and **Child branches** that belong to the branch. All of these objects are associated with a particular branch. For information about these objects, see:

   - [Manage computes](https://neon.com/docs/manage/computes#view-a-compute).
   - [Manage roles](https://neon.com/docs/manage/roles)
   - [Manage databases](https://neon.com/docs/manage/databases)
   - [View branches](https://neon.com/docs/manage/branches#view-branches)

**CLI**

List the branches in a project with [`neon branches list`](https://neon.com/docs/cli/branches#list):

```bash
neon branches list --project-id dry-heart-13671059
```

```text filename="Output"
Name                  ID                        Current State  Expires At  Created At
[default] main        br-morning-meadow-123456  ready          never       2026-08-04T07:07:55Z
br-curly-wave-123456  br-curly-wave-123456      ready          never       2026-08-04T07:13:09Z
```

**API**

List the branches in a project with the [List branches](https://neon.com/docs/reference/api/branches/list-project-branches) endpoint:

```bash
curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [List branches](https://neon.com/docs/reference/api/branches/list-project-branches) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "branches": [
    {
      "id": "br-curly-wave-123456",
      "project_id": "dry-heart-13671059",
      "parent_id": "br-morning-meadow-123456",
      "parent_lsn": "0/1FA22C0",
      "parent_timestamp": "2026-08-04T07:08:48Z",
      "name": "br-curly-wave-123456",
      "current_state": "ready",
      "state_changed_at": "2026-08-04T07:13:09Z",
      "creation_source": "console",
      "primary": false,
      "default": false,
      "protected": false,
      "cpu_used_sec": 0,
      "compute_time_seconds": 0,
      "active_time_seconds": 0,
      "written_data_bytes": 0,
      "data_transfer_bytes": 0,
      "created_at": "2026-08-04T07:13:09Z",
      "updated_at": "2026-08-04T07:18:15Z",
      "created_by": {
        "name": "your@email.com",
        "image": ""
      },
      "init_source": "parent-data"
    },
    {
      "id": "br-morning-meadow-123456",
      "project_id": "dry-heart-13671059",
      "name": "main",
      "current_state": "ready",
      "state_changed_at": "2026-08-04T07:07:58Z",
      "logical_size": 30777344,
      "creation_source": "console",
      "primary": true,
      "default": true,
      "protected": false,
      "cpu_used_sec": 0,
      "compute_time_seconds": 0,
      "active_time_seconds": 0,
      "written_data_bytes": 0,
      "data_transfer_bytes": 0,
      "created_at": "2026-08-04T07:07:55Z",
      "updated_at": "2026-08-04T07:13:11Z",
      "created_by": {
        "name": "your@email.com",
        "image": ""
      },
      "init_source": "parent-data"
    }
  ],
  "annotations": {},
  "pagination": {
    "sort_by": "updated_at",
    "sort_order": "DESC"
  }
}
```

</details>

## Branch archiving

On the Free plan, Neon automatically archives inactive branches to cost-efficient archive storage after a defined threshold. For more, see [Branch archiving](https://neon.com/docs/guides/branch-archiving).

**Note:** For branches with predictable lifespans, you can set an expiration date when creating branches to automatically delete them at a specified time. This offers an alternative to archiving for temporary development and testing environments, ensuring cleanup happens exactly when needed.

## Rename a branch

Neon permits renaming a branch, including your project's default branch.

**Console**

To rename a branch:

1. In the Neon Console, select a project.
2. Select **Branches** in the sidebar to view the branches for the project.
3. Select a branch from the table.
4. On the branch overview page, open the three-dot menu (⋮) and select **Rename**.
5. Specify a new name for the branch and click **Save**.

**CLI**

Rename a branch with [`neon branches rename`](https://neon.com/docs/cli/branches#rename), passing the current name or ID and the new name:

```bash
neon branches rename br-rough-sky-123456 teambranch
```

**API**

Rename a branch with the [Update branch](https://neon.com/docs/reference/api/branches/update-project-branch) endpoint:

```bash
curl -X 'PATCH' \
  'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-rough-sky-123456' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"branch": {"name": "teambranch"}}'
```

## Set a branch as default

Each Neon project is created with a default branch (named `main` if the project was created with the CLI or API, or `production` if created in the Console), but you can designate any branch as your project's default branch. When creating a new branch without specifying the parent, a new branch is created from your project's default branch. Default branch is automatically selected in the UI when creating the new branch, and it's used in the [create branch API call](https://neon.com/docs/reference/api/branches/create-project-branch). The [Neon-Managed Vercel integration](https://neon.com/docs/guides/neon-managed-vercel-integration) also creates preview deployment branches from your project's default branch.

For more information, see [Default branch](https://neon.com/docs/manage/branches#default-branch).

**Console**

To set a branch as the default branch:

1. In the Neon Console, select a project.
2. Select **Branches** in the sidebar to view the branches for the project.
3. Select a branch from the table.
4. On the branch overview page, open the three-dot menu (⋮) and select **Set as default**.
5. In the **Set as default** confirmation dialog, click **Set as default** to confirm your selection.

**CLI**

Set the default branch with [`neon branches set-default`](https://neon.com/docs/cli/branches#set-default):

```bash
neon branches set-default br-curly-wave-123456
```

**API**

Set the default branch with the [Set default branch](https://neon.com/docs/reference/api/branches/set-default-project-branch) endpoint:

```bash
curl -X POST 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-curly-wave-123456/set_as_default' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

## Set a branch as protected

This feature is available on all Neon's paid plans, which supports up to five protected branches.

**Console**

To set a branch as protected:

1. In the Neon Console, select a project.
2. Select **Branches** in the sidebar to view the branches for the project.
3. Select a branch from the table.
4. On the branch overview page, open the three-dot menu (⋮) and select **Set as protected**.
5. In the **Set as protected** confirmation dialog, click **Set as protected** to confirm your selection.

**CLI**

No dedicated command sets protection, so use the [`neon api`](https://neon.com/docs/cli/api) passthrough, which sends the request with your CLI credentials:

```bash
neon api /projects/dry-heart-13671059/branches/br-curly-wave-123456 -X PATCH -F branch.protected=true
```

**API**

Mark a branch as protected with the [Update branch](https://neon.com/docs/reference/api/branches/update-project-branch) endpoint:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-curly-wave-123456' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"branch": {"protected": true}}'
```

For details and configuration instructions, refer to our [Protected branches guide](https://neon.com/docs/guides/protected-branches).

## Set a branch expiration

To set or update a branch's expiration (auto-deletion TTL):

**Console**

1. In the Neon Console, select a project.
2. Select **Branches** in the sidebar to view the branches for the project.
3. Select a branch from the table.
4. On the branch overview page, open the three-dot menu (⋮) and select **Set expiration**.
5. Set a new expiration date and time, or toggle off "Automatically delete branch after" to remove expiration.
6. Click **Save**.

**CLI**

Set an expiration with [`neon branches set-expiration`](https://neon.com/docs/cli/branches#set-expiration). Omit `--expires-at` to remove it:

```bash
neon branches set-expiration br-curly-wave-123456 --expires-at 2025-08-15T18:00:00Z
```

**API**

Set an expiration with the [Update branch](https://neon.com/docs/reference/api/branches/update-project-branch) endpoint:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-curly-wave-123456' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"branch": {"expires_at": "2025-08-15T18:00:00Z"}}'
```

For details and configuration instructions, refer to our [Branch expiration guide](https://neon.com/docs/guides/branch-expiration).

## Connect to a branch

You connect to a branch through a compute associated with it, using a Postgres connection string that carries your role, the compute hostname (it starts with `ep-`), and the database name. Get the string from the Console, CLI, or API, then connect with any Postgres client. To run queries without a client, use the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor).

**Console**

Click **Connect** in the Console nav, then select the branch, database, and role. Copy the connection string.

![Connection details modal](https://neon.com/docs/connect/connect_to_branch_modal.png)

**CLI**

Connect directly with [`neon psql`](https://neon.com/docs/cli/psql):

```bash
neon psql br-curly-wave-123456
```

Or print the connection string to use elsewhere with [`neon connection-string`](https://neon.com/docs/cli/connection-string) (add `--pooled` or `--prisma` as needed):

```bash
neon connection-string br-curly-wave-123456 --database-name neondb --role-name alex
```

**API**

Retrieve the connection string with the [Get connection URI](https://neon.com/docs/reference/api/projects/get-connection-uri) endpoint (`database_name` and `role_name` are required):

```bash
curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/connection_uri?branch_id=br-curly-wave-123456&database_name=neondb&role_name=alex' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

Then connect with any client, for example `psql`:

```bash
psql postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

For application connection examples, see [Frameworks](https://neon.com/docs/get-started/frameworks) and [Languages](https://neon.com/docs/get-started/languages).

## Reset a branch from parent

You can use Neon's **Reset from parent** feature to instantly update a branch with the latest schema and data from its parent. This feature can be an integral part of your CI/CD automation.

You can use the Neon Console, CLI, or API. For details, see [Reset from parent](https://neon.com/docs/guides/reset-from-parent).

## Restore a branch to its own or another branch's history

There are several restore operations available using Neon's instant restore feature:

- Restore a branch to its own history
- Restore a branch to the head of another branch
- Restore a branch to the history of another branch

You can use the Neon Console, CLI, or API. For more details, see [Instant restore](https://neon.com/docs/guides/branch-restore).

## Delete a branch

Deleting a branch is a permanent action. Deleting a branch also deletes the databases and roles that belong to the branch as well as the compute associated with the branch. You cannot delete a branch that has child branches. The child branches must be deleted first.

**Console**

To delete a branch:

1. In the Neon Console, select a project.
2. Select **Branches** in the sidebar.
3. Select a branch from the table.
4. On the branch overview page, open the three-dot menu (⋮) and select **Delete**.
5. On the confirmation dialog, click **Delete**.

**CLI**

Delete a branch with [`neon branches delete`](https://neon.com/docs/cli/branches#delete), passing the branch name or ID:

```bash
neon branches delete br-curly-wave-123456
```

**API**

Delete a branch with the [Delete branch](https://neon.com/docs/reference/api/branches/delete-project-branch) endpoint:

```bash
curl -X 'DELETE' \
  'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-curly-wave-123456' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Delete branches](https://neon.com/docs/reference/api/branches/delete-project-branch) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "branch": {
    "id": "br-curly-wave-123456",
    "project_id": "dry-heart-13671059",
    "parent_id": "br-morning-meadow-123456",
    "parent_lsn": "0/1FA22C0",
    "parent_timestamp": "2026-08-04T07:08:48Z",
    "name": "br-curly-wave-123456",
    "current_state": "ready",
    "pending_state": "storage_deleted",
    "state_changed_at": "2026-08-04T07:13:09Z",
    "logical_size": 30851072,
    "creation_source": "console",
    "primary": false,
    "default": false,
    "protected": false,
    "cpu_used_sec": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "written_data_bytes": 0,
    "data_transfer_bytes": 0,
    "created_at": "2026-08-04T07:13:09Z",
    "updated_at": "2026-08-04T07:21:55Z",
    "created_by": {
      "name": "your@email.com",
      "image": ""
    },
    "init_source": "parent-data"
  },
  "operations": [
    {
      "id": "eb85073d-53fc-4d37-a32a-ca9e9ea1eeb1",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-curly-wave-123456",
      "endpoint_id": "ep-soft-art-123456",
      "action": "suspend_compute",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T07:21:55Z",
      "updated_at": "2026-08-04T07:21:55Z",
      "total_duration_ms": 0
    },
    {
      "id": "586af342-1ffe-4e0a-9e11-326db1164ad7",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-curly-wave-123456",
      "action": "delete_timeline",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2026-08-04T07:21:55Z",
      "updated_at": "2026-08-04T07:21:55Z",
      "total_duration_ms": 0
    }
  ]
}
```

</details>

**Tip:** For temporary branches, consider setting an expiration date when creating them to automate cleanup and reduce manual deletion overhead.

## Check the data size

You can check the logical data size for the databases on a branch by viewing the **Storage** column on the **Branches** page in the Neon Console. Alternatively, you can run the following query on your branch from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any SQL client connected to your database:

```sql
SELECT pg_size_pretty(sum(pg_database_size(datname)))
FROM pg_database;
```

The query value may differ slightly from the **Data size** reported in the Neon Console.

Data size is your logical data size.

**Note: Storage is unlimited on paid plans**

**Storage is unlimited on paid plans (Launch and Scale): there's no hard per-branch size limit, and your branch storage grows with your usage.** The Free plan is limited to 1 GB per project.

## Branch types

Neon has different branch types with different characteristics.

### Root branch

A root branch is a branch without a parent branch. Each Neon project starts with a root branch (named `production` in the Console, `main` via API/CLI), which cannot be deleted and is set as the [default branch](https://neon.com/docs/manage/branches#default-branch) for the project.

Neon also supports two other types of root branches that have no parent but _can_ be deleted:

- [Backup branches](https://neon.com/docs/manage/branches#backup-branch), created by instant restore operations on other root branches.
- [Schema-only branches](https://neon.com/docs/manage/branches#schema-only-branch).

The number of root branches allowed in a project depends on your Neon plan.

| Plan   | Root branch allowance per project |
| :----- | :-------------------------------- |
| Free   | 3                                 |
| Launch | 5                                 |
| Scale  | 25                                |

### Default branch

Each Neon project has a default branch. In the Neon Console, your default branch is identified by a `DEFAULT` tag. You can designate any branch as the default branch for your project.

When creating a new branch without specifying the parent, a new branch is created from your project's default branch. The [Neon-Managed Vercel integration](https://neon.com/docs/guides/neon-managed-vercel-integration) also creates preview deployment branches from your project's default branch.

### Non-default branch

Any branch not designated as the default branch is considered a non-default branch. You can rename or delete non-default branches.

### Protected branch

Neon's protected branches feature implements a series of protections:

- Protected branches cannot be deleted.
- Protected branches cannot be [reset](https://neon.com/docs/manage/branches#reset-a-branch-from-parent).
- Projects with protected branches cannot be deleted.
- Computes associated with a protected branch cannot be deleted.
- New passwords are automatically generated for Postgres roles on branches created from protected branches. [Learn more](https://neon.com/docs/guides/protected-branches#new-passwords-generated-for-postgres-roles-on-child-branches).
- With additional configuration steps, you can apply IP Allow restrictions to protected branches only. See [How to apply IP restrictions to protected branches](https://neon.com/docs/guides/protected-branches#how-to-apply-ip-restrictions-to-protected-branches).
- Protected branches are not [archived](https://neon.com/docs/guides/branch-archiving) due to inactivity.

Typically, a protected status is given to a branch or branches that hold production data or sensitive data. The protected branch feature is only supported on Neon's paid plans. See [Set a branch as protected](https://neon.com/docs/manage/branches#set-a-branch-as-protected).

### Schema-only branch

A branch that replicates only the database schema from a source branch, without copying any of the actual data. This feature is particularly valuable when working with sensitive information. Rather than creating branches that include confidential data, you can duplicate just the database structure and then populate it with your own data.

Schema-only branches are [root branches](https://neon.com/docs/manage/branches#root-branch), meaning they have no parent. As a root branch, each schema-only branch starts an independent line of data in a Neon project.

See [Schema-only branches](https://neon.com/docs/guides/branching-schema-only).

### Backup branch

A branch created by an [instant restore](https://neon.com/docs/introduction/branch-restore) operation. When you restore a branch from a particular point in time, the current branch is saved as a backup branch. Performing a restore operation on a root branch, creates a backup branch without a parent branch (a root branch). See [Instant restore](https://neon.com/docs/guides/branch-restore).

### Branch with expiration

A branch with an expiration timestamp is automatically deleted when the expiration time is reached. Any branch can have an expiration timestamp added or removed at any time. Use it for temporary development and testing environments.

## Branching with the Neon CLI

The Neon CLI supports creating and managing branches. See [Neon CLI commands — branches](https://neon.com/docs/cli/branches).

## Branching with the Neon API

Branch actions performed in the Neon Console can also be performed using the [Neon API](https://neon.com/docs/reference/api). Each operation above includes an example in its **API** tab; see the [Neon API Reference](https://neon.com/docs/reference/api) for complete request and response schemas. A request requires an API key: see [Create an API key](https://neon.com/docs/manage/api-keys#create-an-api-key), where `$NEON_API_KEY` stands in for your key.

### Create a branch with the API

See [Create a branch](https://neon.com/docs/manage/branches#create-a-branch) for the Console, CLI, and API options.

### List branches with the API

See [View branches](https://neon.com/docs/manage/branches#view-branches) for the Console, CLI, and API options.

### Delete a branch with the API

See [Delete a branch](https://neon.com/docs/manage/branches#delete-a-branch) for the Console, CLI, and API options.

--- [Document source](https://neon.com/docs/manage/computes.md) ---

> Summary: Neon computes are virtualized Postgres instances attached to branches, available as primary read-write or read-replica types. Use this page to create, resize, or delete a compute, configure autoscaling or scale-to-zero, size your compute based on working set and connection limits, or manage compute endpoints via the Neon Console or API.

# Manage computes

Last updated: 2026-11-05

A compute is a virtualized service that runs applications. In Neon, a compute runs Postgres.

Each project has a primary read-write compute for its [default branch](https://neon.com/docs/reference/glossary#default-branch). Neon supports both read-write and [read replica](https://neon.com/docs/introduction/read-replicas) computes. A branch can have one primary (read-write) compute and multiple read replica computes. A compute is required to connect to a Neon branch (where your database resides) from a client or application.

To connect to a database in a branch, you must use a compute associated with that branch. The following diagram illustrates how an application connects to a branch via its compute:

```text
Project
    |---- default branch (main) ---- compute <--- application/client
             |    |
             |    |---- database
             |
             ---- child branch ---- compute <--- application/client
                            |
                            |---- database
```

Your Neon plan determines the resources available to a compute. The Neon Free plan supports computes with up to 2 CU (8 GB of RAM). Paid plans offer larger compute sizes. Larger computes consume more compute hours over the same period of active time than smaller computes.

## View a compute

A compute is associated with a branch.

**Console**

In the Neon Console, select your branch from the project/branch menu at the top of the sidebar, then select **Postgres database** > **Computes**. If the branch has a compute, it is shown on the **Computes** tab of the branch overview.

Compute details shown on the **Computes** tab include:

- The type of compute, which can be **Primary** (read-write) or **Read Replica** (read-only).
- The compute status, typically **Active** or **Idle**.
- **Endpoint ID**: The compute endpoints ID, which always starts with an `ep-` prefix; for example: `ep-quiet-butterfly-w2qres1h`
- **Size**: The size of the compute. Shows autoscaling minimum and maximum CU values if autoscaling is enabled.
- **Last active**: The date and time the compute was last active.

**Edit**, **Monitor**, and **Connect** actions for a compute can be accessed from the **Computes** tab.

**CLI**

List the computes in a project with [`neon postgres computes list`](https://neon.com/docs/cli/postgres#computes-list), and pass `--branch` to see one branch's computes:

```bash
neon postgres computes list --branch main
```

```text filename="Output"
Computes on main
ID                      Branch ID                  Type        Current State  Autoscaling Limit Min Cu  Autoscaling Limit Max Cu
ep-cool-king-123456     br-lively-sunset-123456    read_write  active         0.25                      2
```

For one compute's host, state, size, and scale-to-zero timeout, use [`neon postgres computes get`](https://neon.com/docs/cli/postgres#computes-get):

```bash
neon postgres computes get ep-cool-king-123456
```

**API**

List the computes for a project with the [List computes](https://neon.com/docs/reference/api/endpoints/list-project-endpoints) endpoint:

```bash
curl -X 'GET' \
  'https://console.neon.tech/api/v2/projects/autumn-lake-30024670/endpoints' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [List computes](https://neon.com/docs/reference/api/endpoints/list-project-endpoints) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "endpoints": [
    {
      "host": "ep-misty-morning-a1pfa4ez.ap-southeast-1.aws.neon.tech",
      "id": "ep-misty-morning-a1pfa4ez",
      "project_id": "autumn-lake-30024670",
      "branch_id": "br-dry-glitter-a1rh0x6q",
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 2,
      "region_id": "aws-ap-southeast-1",
      "type": "read_write",
      "current_state": "idle",
      "settings": {},
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "last_active": "2025-08-03T17:40:20Z",
      "creation_source": "console",
      "created_at": "2025-08-03T17:40:19Z",
      "updated_at": "2025-08-03T17:45:24Z",
      "suspended_at": "2025-08-03T17:45:24Z",
      "proxy_host": "ap-southeast-1.aws.neon.tech",
      "suspend_timeout_seconds": 0,
      "provisioner": "k8s-neonvm"
    },
    {
      "host": "ep-autumn-frost-a1wlmval.ap-southeast-1.aws.neon.tech",
      "id": "ep-autumn-frost-a1wlmval",
      "project_id": "autumn-lake-30024670",
      "branch_id": "br-dark-bar-a11jneqm",
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 2,
      "region_id": "aws-ap-southeast-1",
      "type": "read_write",
      "current_state": "idle",
      "settings": {},
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "last_active": "2025-08-03T17:34:40Z",
      "creation_source": "console",
      "created_at": "2025-08-03T11:27:50Z",
      "updated_at": "2025-08-03T17:41:11Z",
      "suspended_at": "2025-08-03T17:41:11Z",
      "proxy_host": "ap-southeast-1.aws.neon.tech",
      "suspend_timeout_seconds": 0,
      "provisioner": "k8s-neonvm"
    }
  ]
}
```

</details>

## Create a compute

You can only create a single primary read-write compute for a branch that does not have a compute, but a branch can have multiple read replica computes.

**Console**

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Click **Add a compute** or **Add Read Replica** if you already have a primary read-write compute.
4. On the **Add new compute** drawer or **Add read replica** drawer, specify your compute settings, and click **Add**. Selecting the **Read replica** compute type creates a [read replica](https://neon.com/docs/introduction/read-replicas).

**CLI**

Add a compute to a branch with [`neon branches add-compute`](https://neon.com/docs/cli/branches#add-compute), passing `--type read_write` for the branch's primary compute. Add `--cu` to set a fixed size or an autoscaling range:

```bash
neon branches add-compute br-dry-glitter-a1rh0x6q --type read_write
```

**API**

Create a compute with the [Create compute](https://neon.com/docs/reference/api/endpoints/create-project-endpoint) endpoint. The branch you specify cannot already have a read-write compute:

```bash
curl -X 'POST' \
  'https://console.neon.tech/api/v2/projects/autumn-lake-30024670/endpoints' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint": {
    "branch_id": "br-dry-glitter-a1rh0x6q",
    "type": "read_write"
  }
}'
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Create compute](https://neon.com/docs/reference/api/endpoints/create-project-endpoint) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "endpoint": {
    "host": "ep-misty-morning-a1pfa4ez.ap-southeast-1.aws.neon.tech",
    "id": "ep-misty-morning-a1pfa4ez",
    "project_id": "autumn-lake-30024670",
    "branch_id": "br-dry-glitter-a1rh0x6q",
    "autoscaling_limit_min_cu": 1,
    "autoscaling_limit_max_cu": 2,
    "region_id": "aws-ap-southeast-1",
    "type": "read_write",
    "current_state": "init",
    "pending_state": "active",
    "settings": {},
    "pooler_enabled": false,
    "pooler_mode": "transaction",
    "disabled": false,
    "passwordless_access": true,
    "creation_source": "console",
    "created_at": "2025-08-03T17:40:19Z",
    "updated_at": "2025-08-03T17:40:19Z",
    "proxy_host": "ap-southeast-1.aws.neon.tech",
    "suspend_timeout_seconds": 0,
    "provisioner": "k8s-neonvm"
  },
  "operations": [
    {
      "id": "d6ef3cc2-663b-440a-88e7-ea6a59ea2c6a",
      "project_id": "autumn-lake-30024670",
      "branch_id": "br-dry-glitter-a1rh0x6q",
      "endpoint_id": "ep-misty-morning-a1pfa4ez",
      "action": "start_compute",
      "status": "running",
      "failures_count": 0,
      "created_at": "2025-08-03T17:40:19Z",
      "updated_at": "2025-08-03T17:40:19Z",
      "total_duration_ms": 0
    }
  ]
}
```

</details>

## Edit a compute

You can edit a compute to change the [compute size](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration) or [scale to zero](https://neon.com/docs/manage/computes#scale-to-zero-configuration) configuration.

**Console**

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.

2. Under **Postgres database**, select **Computes**.

3. Select **Edit** for the compute you want to edit.

   The **Edit** drawer opens, letting you modify settings such as compute size, the autoscaling configuration, and your scale to zero setting.

4. Once you've made your changes, click **Save**. All changes take immediate effect.

**CLI**

Edit a compute with [`neon postgres computes update`](https://neon.com/docs/cli/postgres#computes-update). For example, set the autoscaling range to 0.5 to 3 CU:

```bash
neon postgres computes update ep-misty-morning-a1pfa4ez --cu 0.5-3
```

Pass `--suspend-timeout` to change the scale-to-zero timeout. The command waits until the change is applied, then prints the compute.

**API**

Update a compute with the [Update compute](https://neon.com/docs/reference/api/endpoints/update-project-endpoint) endpoint. For example, change the autoscaling range:

```bash
curl -X 'PATCH' \
  'https://console.neon.tech/api/v2/projects/autumn-lake-30024670/endpoints/ep-misty-morning-a1pfa4ez' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "endpoint": {
    "autoscaling_limit_min_cu": 0.5,
    "autoscaling_limit_max_cu": 3
  }
}'
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Update compute](https://neon.com/docs/reference/api/endpoints/update-project-endpoint) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "endpoint": {
    "host": "ep-misty-morning-a1pfa4ez.ap-southeast-1.aws.neon.tech",
    "id": "ep-misty-morning-a1pfa4ez",
    "project_id": "autumn-lake-30024670",
    "branch_id": "br-dry-glitter-a1rh0x6q",
    "autoscaling_limit_min_cu": 0.5,
    "autoscaling_limit_max_cu": 3,
    "region_id": "aws-ap-southeast-1",
    "type": "read_write",
    "current_state": "idle",
    "settings": {},
    "pooler_enabled": false,
    "pooler_mode": "transaction",
    "disabled": false,
    "passwordless_access": true,
    "last_active": "2025-08-03T17:40:20Z",
    "creation_source": "console",
    "created_at": "2025-08-03T17:40:19Z",
    "updated_at": "2025-08-03T17:49:01Z",
    "suspended_at": "2025-08-03T17:45:24Z",
    "proxy_host": "ap-southeast-1.aws.neon.tech",
    "suspend_timeout_seconds": 0,
    "provisioner": "k8s-neonvm"
  },
  "operations": []
}
```

</details>

For information about selecting an appropriate compute size or autoscaling configuration, see [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

### What happens to the compute when making changes

Some key points to understand about how your endpoint responds when you make changes to your compute settings:

- Changing the size of your fixed compute restarts the endpoint and _temporarily disconnects all existing connections_.

  **Note:** When your compute resizes automatically as part of the autoscaling feature, there are no restarts or disconnects; it just scales.

- Editing minimum or maximum autoscaling sizes also requires a restart; existing connections are temporarily disconnected.

- If you disable scale to zero, you may need to restart your compute manually to get the latest compute-related release updates from Neon if updates are not applied automatically by a [scheduled update](https://neon.com/docs/manage/updates). Scheduled updates are applied according to certain criteria, so not all computes receive these updates automatically. See [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

To avoid prolonged interruptions resulting from compute restarts, we recommend configuring your clients and applications to reconnect automatically in case of a dropped connection. See [Handling connection disruptions](https://neon.com/docs/manage/updates#handling-connection-disruptions).

### Compute size and autoscaling configuration

You can change compute size settings when [editing a compute](https://neon.com/docs/manage/computes#edit-a-compute).

_Compute size_ is the number of Compute Units (CUs) assigned to a Neon compute. The number of CUs determines the processing capacity of the compute. Each CU allocates approximately 4 GB of RAM to the database instance, along with associated CPU and local SSD resources. Scaling up increases these resources linearly, as shown in the table below.

| Compute Units | RAM    |
| :------------ | :----- |
| .25           | 1 GB   |
| .5            | 2 GB   |
| 1             | 4 GB   |
| 2             | 8 GB   |
| 3             | 12 GB  |
| 4             | 16 GB  |
| 5             | 20 GB  |
| 6             | 24 GB  |
| 7             | 28 GB  |
| 8             | 32 GB  |
| 9             | 36 GB  |
| 10            | 40 GB  |
| 11            | 44 GB  |
| 12            | 48 GB  |
| 13            | 52 GB  |
| 14            | 56 GB  |
| 15            | 60 GB  |
| 16            | 64 GB  |
| 18            | 72 GB  |
| 20            | 80 GB  |
| 22            | 88 GB  |
| 24            | 96 GB  |
| 26            | 104 GB |
| 28            | 112 GB |
| 30            | 120 GB |
| 32            | 128 GB |
| 34            | 136 GB |
| 36            | 144 GB |
| 38            | 152 GB |
| 40            | 160 GB |
| 42            | 168 GB |
| 44            | 176 GB |
| 46            | 184 GB |
| 48            | 192 GB |
| 50            | 200 GB |
| 52            | 208 GB |
| 54            | 216 GB |
| 56            | 224 GB |

Neon supports fixed-size and autoscaling compute configurations.

- **Fixed size:** Select a fixed compute size ranging from .25 CUs to 56 CUs. A fixed-size compute does not scale to meet workload demand. Fixed sizes larger than 16 CU are in beta.
- **Autoscaling:** Specify a minimum and maximum compute size. Neon scales the compute size up and down within the selected compute size boundaries in response to the current load. Currently, the _Autoscaling_ feature supports a range of .25 CU to 16 CU. The maximum permitted autoscaling range is 8 CU, meaning the difference between your maximum and minimum cannot exceed 8 CU. The .25 CU and .5 CU settings are _shared compute_. For information about how Neon implements the _Autoscaling_ feature, see [Autoscaling](https://neon.com/docs/introduction/autoscaling).

**Info: monitoring autoscaling**

For information about monitoring your compute as it scales up and down, see [Monitor autoscaling](https://neon.com/docs/guides/autoscaling-guide#monitor-autoscaling).

### How to size your compute

The size of your compute determines the amount of frequently accessed data you can cache in memory and the maximum number of simultaneous connections you can support. As a result, if your compute size is too small, this can lead to suboptimal query performance and connection limit issues.

In Postgres, the `shared_buffers` setting defines the amount of data that can be held in memory. In Neon, up to 75% of your compute's RAM is used for data caching.

The Postgres `max_connections` setting defines your compute's maximum simultaneous connection limit and is set according to your compute size configuration.

The following table outlines the RAM, compute cache size (75% of RAM), and the `max_connections` limit for each compute size that Neon supports. To understand how `max_connections` is determined for an autoscaling configuration, see [Parameter settings that differ by compute size](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size).

**Note:** Compute size support differs by [Neon plan](https://neon.com/docs/introduction/plans). Autoscaling is supported up to 16 CU. Neon supports fixed compute sizes (no autoscaling) for compute sizes larger than 16 CU. These larger fixed sizes are in beta.

**Note: Caching on large fixed-size computes**

On fixed-size computes of 18 CU and above, Neon delivers this cache as Postgres `shared_buffers` set to 75% of RAM and backed by huge pages, and disables the secondary file cache that smaller and autoscaling computes rely on. This keeps hot data in memory rather than on the compute's local disk. Confirm the configuration with `SHOW shared_buffers` and `SHOW huge_pages`, and measure cache efficiency with the [Compute cache hit rate](https://neon.com/docs/introduction/monitoring-page#compute-cache-hit-rate) graph. See [What is the compute cache?](https://neon.com/docs/extensions/neon#what-is-the-compute-cache) for details.

| Compute Size (CU) | RAM (GB) | Compute cache size (GB) | max\_connections |
| :---------------- | :------- | :---------------------- | :--------------- |
| 0.25              | 1        | 0.75                    | 104              |
| 0.50              | 2        | 1.5                     | 209              |
| 1                 | 4        | 3                       | 419              |
| 2                 | 8        | 6                       | 839              |
| 3                 | 12       | 9                       | 1258             |
| 4                 | 16       | 12                      | 1678             |
| 5                 | 20       | 15                      | 2098             |
| 6                 | 24       | 18                      | 2517             |
| 7                 | 28       | 21                      | 2937             |
| 8                 | 32       | 24                      | 3357             |
| 9                 | 36       | 27                      | 4000             |
| 10                | 40       | 30                      | 4000             |
| 11                | 44       | 33                      | 4000             |
| 12                | 48       | 36                      | 4000             |
| 13                | 52       | 39                      | 4000             |
| 14                | 56       | 42                      | 4000             |
| 15                | 60       | 45                      | 4000             |
| 16                | 64       | 48                      | 4000             |
| 18                | 72       | 54                      | 4000             |
| 20                | 80       | 60                      | 4000             |
| 22                | 88       | 66                      | 4000             |
| 24                | 96       | 72                      | 4000             |
| 26                | 104      | 78                      | 4000             |
| 28                | 112      | 84                      | 4000             |
| 30                | 120      | 90                      | 4000             |
| 32                | 128      | 96                      | 4000             |
| 34                | 136      | 102                     | 4000             |
| 36                | 144      | 108                     | 4000             |
| 38                | 152      | 114                     | 4000             |

When selecting a compute size, ideally, you want to keep as much of your dataset in memory as possible. This improves performance by reducing the amount of reads from storage. If your dataset is not too large, select a compute size that will hold the entire dataset in memory. For larger datasets that cannot be fully held in memory, select a compute size that can hold your [working set](https://neon.com/docs/reference/glossary#working-set). Selecting a compute size for a working set involves advanced steps, which are outlined below. See [Sizing your compute based on the working set](https://neon.com/docs/manage/computes#sizing-your-compute-based-on-the-working-set).

Regarding connection limits, you'll want a compute size that can support your anticipated maximum number of concurrent connections. If you are using **Autoscaling**, it is important to remember that your `max_connections` setting is based on both your minimum and the maximum compute size. See [Parameter settings that differ by compute size](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size) for details. To avoid any `max_connections` constraints, you can use a pooled connection with your application, which supports up to 10,000 concurrent user connections. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

#### Sizing your compute based on the working set

If it's not possible to hold your entire dataset in memory, the next best option is to ensure that your working set is in memory. A working set is your frequently accessed or recently used data and indexes. To determine whether your working set is fully in memory, you can query the cache hit ratio for your Neon compute. The cache hit ratio tells you how many queries are served from memory. Queries not served from memory bypass the cache to retrieve data from database storage (the [Pageserver](https://neon.com/docs/manage/computes#docs/reference/glossary#pageserver)), which can affect query performance.

You can monitor your compute cache hit rate and your working set size from Neon's **Monitoring** page, where you'll find the following charts:

- [Compute cache hit rate](https://neon.com/docs/introduction/monitoring-page#compute-cache-hit-rate)
- [Working set size](https://neon.com/docs/introduction/monitoring-page#working-set-size)

Neon also provides a [neon](https://neon.com/docs/extensions/neon) extension with a `neon_stat_file_cache` view that you can use to query the cache hit ratio for your compute. For more information, see [The neon extension](https://neon.com/docs/extensions/neon).

#### Autoscaling considerations

Autoscaling is most effective when your data (either your full dataset or your working set) can be fully cached in memory on the minimum compute size in your autoscaling configuration.

Consider this scenario: If your data size is approximately 6 GB, starting with a compute size of .25 CU can lead to suboptimal performance because your data cannot be adequately cached. While your compute _will_ scale up from .25 CU on demand, you may experience poor query performance until your compute scales up and fully caches your working set. You can avoid this issue if your minimum compute size can hold your working set in memory.

As mentioned above, your `max_connections` setting is based on both your minimum and maximum compute size settings. To avoid any `max_connections` constraints, you can use a pooled connection for your application. See [Connection pooling](https://neon.com/docs/connect/connection-pooling).

### Scale to zero configuration

Neon's _Scale to Zero_ feature automatically transitions a compute into an idle state after 5 minutes of inactivity. You can disable scale to zero to maintain an "always-active" compute. An "always-active" configuration eliminates the few hundred milliseconds seconds of latency required to reactivate a compute but is likely to increase your compute time usage on systems where the database is not always active.

**Note:** Scale to zero is only available for computes up to 16 CU in size. Computes larger than 16 CU remain always active to ensure best performance.

For more information, refer to [Configuring scale to zero for Neon computes](https://neon.com/docs/guides/scale-to-zero-guide).

**Important:** If you disable scale to zero, you may need to restart your compute manually to get the latest compute-related release updates from Neon if updates are not applied automatically by a [scheduled update](https://neon.com/docs/manage/updates). Scheduled updates are applied according to certain criteria, so not all computes receive these updates automatically. See [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

## Restart a compute

It is sometimes necessary to restart a compute. Reasons for restarting a compute might include:

- Activating new limits after upgrading to a paid plan
- Getting the latest compute-related updates, which Neon typically releases weekly
- Accessing a recently released Postgres extension or extension version
- Resolving performance issues or unexpected behavior

Restarting ensures your compute is running with the latest configurations and improvements.

**Important:** Restarting a compute interrupts any connections currently using the compute. To avoid prolonged interruptions resulting from compute restarts, we recommend configuring your clients and applications to reconnect automatically in case of a dropped connection.

**Console**

Use the **Restart compute** option in the Neon Console. Select your branch from the project/branch menu at the top of the sidebar, then select **Postgres database** > **Computes** and choose **Restart compute** from the compute's menu.

![Restart a compute in the console](https://neon.com/docs/manage/restart_compute.png)

You can also restart a compute by letting it suspend: stop activity (stop running queries) and wait for the compute to suspend due to inactivity, which happens after 5 minutes by default. Watch the compute's **Status** field on the **Branches** page until it reports `Idle`. The compute restarts the next time it's accessed, and the status changes to `Active`.

**CLI**

Restart the compute with [`neon postgres computes restart`](https://neon.com/docs/cli/postgres#computes-restart):

```bash
neon postgres computes restart ep-misty-morning-a1pfa4ez
```

**API**

Issue a [Restart compute endpoint](https://neon.com/docs/reference/api/endpoints/restart-project-endpoint) call. You'll need your [project ID](https://neon.com/docs/reference/glossary#project-id), compute [endpoint ID](https://neon.com/docs/reference/glossary#endpoint-id), and an [API key](https://neon.com/docs/manage/api-keys#create-an-api-key):

```bash
curl --request POST \
   --url https://console.neon.tech/api/v2/projects/autumn-lake-30024670/endpoints/ep-misty-morning-a1pfa4ez/restart \
   --header 'accept: application/json' \
   --header 'authorization: Bearer $NEON_API_KEY'
```

**Note:** The [Restart compute endpoint](https://neon.com/docs/reference/api/endpoints/restart-project-endpoint) API only works on an active compute. If your compute is idle, you can wake it up with a query or the [Start compute endpoint](https://neon.com/docs/reference/api/endpoints/start-project-endpoint) API.

## Delete a compute

A branch can have a single read-write compute and multiple read replica computes. You can delete any of these computes from a branch. However, be aware that a compute is required to connect to a branch and access its data. If you delete a compute and add it back later, the new compute will have different connection details.

**Console**

1. In the Neon Console, select your branch from the project/branch menu at the top of the sidebar.
2. Under **Postgres database**, select **Computes**.
3. Click **Edit** for the compute you want to delete.
4. At the bottom of the **Edit compute** drawer, click **Delete compute**.

**CLI**

Delete the compute with [`neon postgres computes delete`](https://neon.com/docs/cli/postgres#computes-delete):

```bash
neon postgres computes delete ep-misty-morning-a1pfa4ez
```

**API**

Delete a compute with the [Delete compute](https://neon.com/docs/reference/api/endpoints/delete-project-endpoint) endpoint:

```bash
curl -X 'DELETE' \
  'https://console.neon.tech/api/v2/projects/autumn-lake-30024670/endpoints/ep-misty-morning-a1pfa4ez' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Delete compute](https://neon.com/docs/reference/api/endpoints/delete-project-endpoint) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "endpoint": {
    "host": "ep-misty-morning-a1pfa4ez.ap-southeast-1.aws.neon.tech",
    "id": "ep-misty-morning-a1pfa4ez",
    "project_id": "autumn-lake-30024670",
    "branch_id": "br-dry-glitter-a1rh0x6q",
    "autoscaling_limit_min_cu": 0.5,
    "autoscaling_limit_max_cu": 3,
    "region_id": "aws-ap-southeast-1",
    "type": "read_write",
    "current_state": "idle",
    "settings": {},
    "pooler_enabled": false,
    "pooler_mode": "transaction",
    "disabled": false,
    "passwordless_access": true,
    "last_active": "2025-08-03T17:40:20Z",
    "creation_source": "console",
    "created_at": "2025-08-03T17:40:19Z",
    "updated_at": "2025-08-03T17:52:39Z",
    "suspended_at": "2025-08-03T17:45:24Z",
    "proxy_host": "ap-southeast-1.aws.neon.tech",
    "suspend_timeout_seconds": 0,
    "provisioner": "k8s-neonvm"
  },
  "operations": []
}
```

</details>

## Compute-related issues

This section outlines compute-related issues you may encounter and possible resolutions.

### No space left on device

You may encounter an error similar to the following when your compute's local disk storage is full:

```bash
ERROR: could not write to file "base/pgsql_tmp/pgsql_tmp1234.56.fileset/o12of34.p1.0": No space left on device (SQLSTATE 53100)
```

Neon computes allocate 20 GiB of local disk space or 15 GiB x the maximum compute size (whichever is highest) for temporary files used by Postgres. Data-intensive operations can sometimes consume all of this space, resulting in `No space left on device` errors.

To resolve this issue, you can try the following strategies:

- **Identify and terminate resource-intensive processes**: These could be long-running queries, operations, or possibly sync or replication activities. You can start your investigation by [listing running queries by duration](https://neon.com/docs/postgresql/query-reference#list-running-queries-by-duration).
- **Optimize queries to reduce temporary file usage**.
- **Adjust pipeline settings for third-party sync or replication**: If you're syncing or replicating data with an external service, modify the pipeline settings to control disk space usage.

If the issue persists, refer to our [Neon Support channels](https://neon.com/docs/introduction/support#support-channels).

### Compute is not suspending

In some cases, you may observe that your compute remains constantly active for no apparent reason. Possible causes for a constantly active compute when not expected include:

- **Connection requests**: Frequent connection requests from clients, applications, or integrations can prevent a compute from suspending automatically. Each connection resets the scale to zero timer.
- **Background processes**: Some applications or background jobs may run periodic tasks that keep the connection active.

Possible steps you can take to identify the issues include:

1. **Checking for active processes**

   You can run the following query to identify active sessions and their states:

   ```sql
   SELECT
     pid,
     usename,
     query,
     state,
     query_start
   FROM
     pg_stat_activity
   WHERE
     query_start >= now() - interval '24 hours'
   ORDER BY
     query_start DESC;
   ```

   Look for processes initiated by your users, applications, or integrations that may be keeping your compute active.

2. **Review connection patterns**
   - Ensure that no applications are sending frequent, unnecessary connection requests.
   - Consider batching connections if possible, or use [connection pooling](https://neon.com/docs/connect/connection-pooling) to limit persistent connections.

3. **Optimize any background jobs**

   If background jobs are needed, reduce their frequency or adjust their timing to allow Neon's scale to zero feature to activate after the defined period of inactivity (the default is 5 minutes). For more information, refer to our [Scale to zero guide](https://neon.com/docs/guides/scale-to-zero-guide).

--- [Document source](https://neon.com/docs/manage/database-access.md) ---

> Summary: Database access control in Neon uses Postgres roles to separate administrative neon_superuser privileges from least-privilege read-only, read-write, and developer roles scoped to specific databases and schemas. Use this page for SQL statements covering CREATE ROLE, GRANT, ALTER DEFAULT PRIVILEGES, and REVOKE. Includes guidance on revoking public schema defaults, which differ between Postgres 14 and Postgres 15+.

# Manage database access

Learn how to manage user access to databases in your Neon project

Last updated: 2026-11-05

Each Neon project is created with a Postgres role that is named for your database. For example, if your database is named `neondb`, the project is created with a role named `neondb_owner`.

This Postgres role is automatically assigned the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which allows creating databases, roles, and reading and writing data in all tables, views, and sequences. Any user created with the Neon Console, Neon API, or Neon CLI is also assigned the `neon_superuser` role.

It is good practice to reserve `neon_superuser` roles for database administration tasks like creating roles and databases. For other users, we recommend creating roles with specific sets of permissions based on application and access requirements. Then, assign the appropriate roles to your users. The roles you create should adhere to a _least privilege_ model, granting only the permissions required to accomplish their tasks.

But how do you create roles with limited access? The following sections describe how to create read-only and read-write roles and assign those roles to users. We'll also look at how to create a "developer" role and grant that role full access to a database on a development branch in a Neon project.

## A word about users, groups, and roles in Postgres

In Postgres, users, groups, and roles are the same thing. From the PostgreSQL [Database Roles](https://www.postgresql.org/docs/current/user-manag.html) documentation:

_PostgreSQL manages database access permissions using the concept of roles. A role can be thought of as either a database user, or a group of database users, depending on how the role is set up._

Neon recommends granting privileges to roles, and then assigning those roles to your database users.

## Creating roles with limited access

You can create roles with limited access via SQL. Roles created with SQL are created with the same basic [public schema privileges](https://neon.com/docs/manage/database-access#public-schema-privileges) granted to newly created roles in a standalone Postgres installation. These users are not assigned the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role. They must be selectively granted permissions for each database object.

The recommended approach to creating roles with limited access is as follows:

1. Use your Neon role to create roles for each application or use case via SQL. For example, create `readonly` and `readwrite` roles.
2. Grant privileges to those roles to allow access to database objects. For example, grant the `SELECT` privilege to a `readonly` role, or grant `SELECT`, `INSERT`, `UPDATE`, and `DELETE` privileges to a `readwrite` role.
3. Create your database users. For example, create users named `readonly_user1` and `readwrite_user1`.
4. Assign the `readonly` or `readwrite` role to those users to grant them the privileges associated with those roles. For example, assign the `readonly` role to `readonly_user1`, and the `readwrite` role to `readwrite_user1`.

**Note:** You can remove a role from a user at any time to revoke privileges. See [Revoke privileges](https://neon.com/docs/manage/database-access#revoke-privileges).

## Create a read-only role

This section describes how to create a read-only role with access to a specific database and schema. An SQL statement summary is provided at the end.

To skip the SQL, create the role with the Neon CLI instead. [`neon roles create --access read_only`](https://neon.com/docs/cli/roles#create) grants `SELECT` on the tables the database owner owns, now and later, in the `public` schema or the schemas you pass with `--schema`:

```bash
neon roles create --name readonly_user1 --access read_only --database neondb
```

**Info:** In Postgres, access must be granted at the database, schema, and object level. For example, to grant access to a table, you must also grant access to the database and schema in which the table resides. If these access permissions are not defined, the role will not be able access the table.

To create a read-only role:

1. Connect to your database from an SQL client such as [psql](https://neon.com/docs/connect/query-with-psql-editor), [pgAdmin](https://www.pgadmin.org/), or the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). If you need help connecting, see [Connect from any client](https://neon.com/docs/connect/connect-from-any-app).

2. Create a `readonly` role using the following statement.

   ```sql
   CREATE ROLE readonly PASSWORD '<password>';
   ```

   The password should have at least 12 characters with a mix of lowercase, uppercase, number, and symbol characters. For detailed password guidelines, see [Manage roles with SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql).

   **Note:** Neon also supports the `NOLOGIN` option: `CREATE ROLE role_name NOLOGIN;` This allows you to define roles that cannot authenticate but can be granted privileges.

3. Grant the `readonly` role read-only privileges on the schema. Replace `<database>` and `<schema>` with actual database and schema names, respectively.

   ```sql
   -- Grant permission to connect to the database
   GRANT CONNECT ON DATABASE <database> TO readonly;

   -- Grant USAGE on the schema
   GRANT USAGE ON SCHEMA <schema> TO readonly;

   -- Grant SELECT on all existing tables in the schema
   GRANT SELECT ON ALL TABLES IN SCHEMA <schema> TO readonly;

   -- Grant SELECT on all tables added in the future
   ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT SELECT ON TABLES TO readonly;
   ```

4. Create a database user. The password requirements mentioned above apply here as well.

   ```sql
   CREATE ROLE readonly_user1 WITH LOGIN PASSWORD '<password>';
   ```

5. Assign the `readonly` role to `readonly_user1`:

   ```sql
   GRANT readonly TO readonly_user1;
   ```

   The `readonly_user1` user now has read-only access to tables in the specified schema and database and should be able to connect and run `SELECT` queries.

   ```bash
   psql postgresql://readonly_user1:AbC123dEf@ep-cool-darkness-123456.us-west-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   psql (15.2 (Ubuntu 15.2-1.pgdg22.04+1), server 15.3)
   SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
   Type "help" for help.

   dbname=> SELECT * FROM <schema>.<table_name>;
   ```

   If the user attempts to perform an `INSERT`, `UPDATE`, or `DELETE` operation, a `permission denied` error is returned.

### SQL statement summary

To create the read-only role and user described above, run the following statements from an SQL client:

```sql
-- readonly role
CREATE ROLE readonly PASSWORD '<password>';
GRANT CONNECT ON DATABASE <database> TO readonly;
GRANT USAGE ON SCHEMA <schema> TO readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA <schema> TO readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT SELECT ON TABLES TO readonly;

-- User creation
CREATE USER readonly_user1 WITH PASSWORD '<password>';

-- Grant privileges to user
GRANT readonly TO readonly_user1;
```

## Create a read-write role

This section describes how to create a read-write role with access to a specific database and schema. An SQL statement summary is provided at the end.

To create a read-write role:

1. Connect to your database from an SQL client such as [psql](https://neon.com/docs/connect/query-with-psql-editor), [pgAdmin](https://www.pgadmin.org/), or the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). If you need help connecting, see [Connect from any client](https://neon.com/docs/connect/connect-from-any-app).

2. Create a `readwrite` role using the following statement.

   ```sql
   CREATE ROLE readwrite PASSWORD '<password>';
   ```

   The password should have at least 12 characters with a mix of lowercase, uppercase, number, and symbol characters. For detailed password guidelines, see [Manage roles with SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql).

3. Grant the `readwrite` role read-write privileges on the schema. Replace `<database>` and `<schema>` with actual database and schema names, respectively.

   ```sql
   -- Grant permission to connect to the database
   GRANT CONNECT ON DATABASE <database> TO readwrite;

   -- Grant USAGE and CREATE on the schema
   GRANT USAGE, CREATE ON SCHEMA <schema> TO readwrite;

   -- Grant SELECT, INSERT, UPDATE, DELETE on all existing tables in the schema
   GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA <schema> TO readwrite;

   -- grant SELECT on all tables added in the future
   ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO readwrite;

   -- Grant USAGE on all sequences in the schema
   GRANT USAGE ON ALL SEQUENCES IN SCHEMA <schema> TO readwrite;

   -- Grant USAGE on all sequences added in the future
   ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT USAGE ON SEQUENCES TO readwrite;
   ```

4. Create a database user. The password requirements mentioned above apply here as well.

   ```sql
   CREATE ROLE readwrite_user1 WITH LOGIN PASSWORD '<password>';
   ```

5. Assign the `readwrite` role to `readwrite_user1`:

   ```sql
   GRANT readwrite TO readwrite_user1;
   ```

   The `readwrite_user1` user now has read-write access to tables in the specified schema and database and should able to connect and run `SELECT`, `INSERT`, `UPDATE`, `DELETE` queries.

   ```bash
   psql postgresql://readwrite_user1:AbC123dEf@ep-cool-darkness-123456.us-west-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   psql (15.2 (Ubuntu 15.2-1.pgdg22.04+1), server 15.3)
   SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
   Type "help" for help.

   dbname=> INSERT INTO <table_name> (col1, col2) VALUES (1, 2);
   ```

### SQL statement summary

To create the read-write role and user described above, run the following statements from an SQL client:

```sql
-- readwrite role
CREATE ROLE readwrite PASSWORD '<password>';
GRANT CONNECT ON DATABASE <database> TO readwrite;
GRANT USAGE, CREATE ON SCHEMA <schema> TO readwrite;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA <schema> TO readwrite;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO readwrite;
GRANT USAGE ON ALL SEQUENCES IN SCHEMA <schema> TO readwrite;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT USAGE ON SEQUENCES TO readwrite;

-- User creation
CREATE USER readwrite_user1 WITH PASSWORD '<password>';

-- Grant privileges to user
GRANT readwrite TO readwrite_user1;
```

## Create a developer role

This section describes how to create a "development branch" and grant developers full access to a database on the development branch. To accomplish this, we create a developer role on the "parent" branch, create a development branch, and then assign users to the developer role on the development branch.

As you work through the steps in this scenario, remember that when you create a branch in Neon, you are creating a clone of the parent branch, which includes the roles and databases on the parent branch.

To get started:

1. Connect to the database **on the parent branch** from an SQL client such as [psql](https://neon.com/docs/connect/query-with-psql-editor), [pgAdmin](https://www.pgadmin.org/), or the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor). If you need help connecting, see [Connect from any client](https://neon.com/docs/connect/connect-from-any-app).

2. Use your default Neon role or another role with `neon_superuser` privileges to create a developer role **on the parent branch**. For example, create a role named `dev_users`.

   ```sql
   CREATE ROLE dev_users PASSWORD '<password>';
   ```

   The password should have at least 12 characters with a mix of lowercase, uppercase, number, and symbol characters. For detailed password guidelines, see [Manage roles with SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql).

3. Grant the `dev_users` role privileges on the database:

   ```sql
   GRANT ALL PRIVILEGES ON DATABASE <database> TO dev_users;
   ```

   You now have a `dev_users` role on your parent branch, and the role is not assigned to any users. This role will now be included in all future branches created from this branch.

   **Note:**

   The `GRANT` statement above does not grant privileges on existing schemas, tables, sequences, etc., within the database. If you want the `dev_users` role to access specific schemas, tables, etc., you need to grant those permissions explicitly.

   For example, to grant all privileges on all tables in a schema:

   ```sql
   GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA <schema_name> TO dev_users;
   ```

   Similarly, you'd grant privileges for sequences and other objects as needed.

   That said, the `GRANT` command above allows users with the `dev_users` role to create new schemas within the database. But for pre-existing schemas and their objects, you need to grant permissions explicitly.

4. Create a development branch. Name it something like `dev1`. See [Create a branch](https://neon.com/docs/manage/branches#create-a-branch) for instructions.

5. Connect to the database **on the development branch** with an SQL client. Be mindful that a child branch connection string differs from a parent branch connection string. The branches reside on different hosts. If you need help connecting to your branch, see [Connect from any client](https://neon.com/docs/connect/connect-from-any-app).

6. After connecting the database on your new branch, create a developer user (for example, `dev_user1`). The password requirements described above apply here as well.

   ```sql
   CREATE ROLE dev_user1 WITH LOGIN PASSWORD '<password>';
   ```

7. Assign the `dev_users` role to the `dev_user1` user:

   ```sql
   GRANT dev_users TO dev_user1;
   ```

   The `dev_user1` user can now connect to the database on your development branch and start using the database with full privileges.

   ```bash
   psql postgresql://dev_user1:AbC123dEf@ep-cool-darkness-123456.us-west-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
   psql (15.2 (Ubuntu 15.2-1.pgdg22.04+1), server 15.3)
   SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
   Type "help" for help.

   dbname=>
   ```

### SQL statement summary

```sql
-- dev_users role
CREATE ROLE dev_users PASSWORD `password`;
GRANT ALL PRIVILEGES ON DATABASE <database> TO dev_users;

-- optionally, grant access to an existing schema
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA <schema_name> TO dev_users;

-- User creation
CREATE ROLE dev_user1 WITH LOGIN PASSWORD '<password>';

-- Grant privileges to user
GRANT dev_users TO dev_user1;
```

## Revoke privileges

If you set up privilege-holding roles as describe above, you can revoke privileges by removing assigned roles. For example, to remove the `readwrite` role from `readwrite_user1`, run the following SQL statement:

```sql
REVOKE readwrite FROM readwrite_user1;
```

## Public schema privileges

When creating a new database, Postgres creates a schema named `public` in the database and permits access to the schema to a predefined Postgres role named `public`. Newly created roles in Postgres are automatically assigned the `public` role. In Postgres 14, the public role has `CREATE` and `USAGE` privileges on the `public` schema. In Postgres 15 and higher, the `public` role has only `USAGE` privileges on the `public` schema.

Why does this matter? If you create a new role and want to limit access for that role, you should be aware of the default `public` schema access automatically assigned to newly created roles.

If you want to limit access to the `public` schema for your users, you have to revoke privileges on the `public` schema explicitly.

For users of Postgres 14, the SQL statement to revoke the default `CREATE` permission on the `public` schema from the `public` role is as follows:

```sql
REVOKE CREATE ON SCHEMA public FROM PUBLIC;
```

You must be the owner of the `public` schema or a member of a role that authorizes you to execute this SQL statement.

To restrict the `public` role's capability to connect to a database, use this statement:

```sql
REVOKE ALL ON DATABASE <database> FROM PUBLIC;
```

This ensures users are unable to connect to a database by default unless this permission is explicitly granted.

## More information

For more information about granting privileges in Postgres, please see the [GRANT](https://www.postgresql.org/docs/current/sql-grant.html) command in the _PostgreSQL documentation_.

--- [Document source](https://neon.com/docs/manage/databases.md) ---

> Summary: Neon databases are Postgres containers for schemas, tables, and indexes that exist within a project branch. Use this page to create, rename, or delete databases via the Neon Console, CLI, API, or SQL. Note that the TABLESPACE parameter is not supported. Because Neon roles are not full Postgres superusers, ownership transfers require a group-role workaround using ALTER TABLE ... OWNER TO or REASSIGN OWNED.

# Manage databases

Last updated: 2026-10-03

A database is a container for SQL objects such as schemas, tables, views, functions, and indexes. In the [Neon object model](https://neon.com/docs/concepts/the-object-model), a database exists within a branch of a project. There is a limit of 500 databases per branch.

If you do not specify your own database name when creating a project, your project's default branch is created with a database called `neondb`, which is owned by your project's default role (see [Manage roles](https://neon.com/docs/manage/roles) for more information). You can create your own databases in a project's default branch or in a child branch.

All databases in Neon are created with a `public` schema. SQL objects are created in the `public` schema, by default. For more information about the `public` schema, refer to [The Public schema](https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-PUBLIC), in the _PostgreSQL documentation_.

**Note:** As of Postgres 15, only a database owner has the `CREATE` privilege on a database's `public` schema. For other users, the `CREATE` privilege must be granted manually via a `GRANT CREATE ON SCHEMA public TO <username>;` statement. For more information, see [Public schema privileges](https://neon.com/docs/manage/database-access#public-schema-privileges).

Databases belong to a branch. If you create a child branch, databases from the parent branch are copied to the child branch. For example, if database `mydb` exists in the parent branch, it will be copied to the child branch. The only time this does not occur is when you create a branch that includes data up to a particular point in time. If a database was created in the parent branch after that point in time, it is not duplicated in the child branch.

Neon supports creating and managing databases from the Neon Console, CLI, and API, and directly with [SQL](https://neon.com/docs/manage/databases#manage-databases-with-sql).

The role that creates a database is automatically made the owner of that database. The `neon_superuser` role is also granted all privileges on databases created in the Neon Console, CLI, or API. Databases created with SQL don't receive this grant. For information about this role, see [The neon_superuser role](https://neon.com/docs/manage/roles#the-neonsuperuser-role).

## Create a database

**Console**

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Databases**.
5. Click **Add database**.
6. Enter a database name, and select a database owner.
7. Click **Create**.

**CLI**

Create a database with [`neon databases create`](https://neon.com/docs/cli/databases#create). If you omit `--branch`, the CLI uses the project's default branch:

```bash
neon databases create --name mydb --owner-name casey
```

**API**

Create a database with the [Create database](https://neon.com/docs/reference/api/branches/create-project-branch-database) endpoint. A database `name` and `owner_name` are required:

```bash
curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/databases' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "database": {
    "name": "mydb",
    "owner_name": "casey"
  }
}'
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Create database](https://neon.com/docs/reference/api/branches/create-project-branch-database) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "database": {
    "id": 2889509,
    "branch_id": "br-morning-meadow-123456",
    "name": "mydb",
    "owner_name": "casey",
    "created_at": "2026-08-04T08:14:14Z",
    "updated_at": "2026-08-04T08:14:14Z"
  },
  "operations": [
    {
      "id": "b51c8ece-b78e-49f7-8ec1-78b37cbae3c4",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-morning-meadow-123456",
      "endpoint_id": "ep-holy-heart-123456",
      "action": "apply_config",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T08:14:14Z",
      "updated_at": "2026-08-04T08:14:14Z",
      "total_duration_ms": 0
    }
  ]
}
```

</details>

**Note:** Database names can't exceed 63 bytes, and some names aren't permitted. See [Reserved database names](https://neon.com/docs/manage/databases#reserved-database-names).

## View databases

**Console**

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Databases**.

**CLI**

List databases with [`neon databases list`](https://neon.com/docs/cli/databases#list). If you omit `--branch`, the CLI uses the project's default branch:

```bash
neon databases list
```

```text filename="Output"
Databases on main
Name    Owner Name  Created At
neondb  casey       2026-06-19T18:27:19Z
mydb    casey       2026-06-19T18:27:19Z
```

**API**

List databases for a branch with the [List databases](https://neon.com/docs/reference/api/branches/list-project-branch-databases) endpoint:

```bash
curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/databases' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [List databases](https://neon.com/docs/reference/api/branches/list-project-branch-databases) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "databases": [
    {
      "id": 1139149,
      "branch_id": "br-morning-meadow-123456",
      "name": "neondb",
      "owner_name": "casey",
      "created_at": "2026-01-04T18:38:23Z",
      "updated_at": "2026-01-04T18:38:23Z"
    },
    {
      "id": 1140822,
      "branch_id": "br-morning-meadow-123456",
      "name": "mydb",
      "owner_name": "casey",
      "created_at": "2026-01-04T21:17:17Z",
      "updated_at": "2026-01-04T21:17:17Z"
    }
  ]
}
```

</details>

## Update a database

You can rename a database or change its owner with the [Update database](https://neon.com/docs/reference/api/branches/update-project-branch-database) endpoint. You can also rename a database with [SQL](https://neon.com/docs/manage/databases#rename-a-database-with-sql). The Neon CLI doesn't support updating a database.

This example renames `mydb` to `database1`:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/databases/mydb' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "database": {
    "name": "database1"
  }
}'
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Update database](https://neon.com/docs/reference/api/branches/update-project-branch-database) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "database": {
    "id": 2889509,
    "branch_id": "br-morning-meadow-123456",
    "name": "database1",
    "owner_name": "casey",
    "created_at": "2026-08-04T08:14:14Z",
    "updated_at": "2026-08-04T08:14:14Z"
  },
  "operations": [
    {
      "id": "2f8c0a6a-33b5-4d56-964b-739614b699c0",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-morning-meadow-123456",
      "endpoint_id": "ep-holy-heart-123456",
      "action": "apply_config",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T08:17:22Z",
      "updated_at": "2026-08-04T08:17:22Z",
      "total_duration_ms": 0
    }
  ]
}
```

</details>

To change a database's owner, pass `owner_name`. This example makes `alex` the owner of `database1`:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/databases/database1' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "database": {
    "owner_name": "alex"
  }
}'
```

## Delete a database

Deleting a database is a permanent action. All objects in the database, such as schemas, tables, and indexes, are also deleted. Roles aren't deleted, because roles belong to the branch, not the database.

**Console**

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Databases**.
5. For the database you want to delete, click the delete icon.
6. In the confirmation dialog, click **Delete**.

**CLI**

Delete a database with [`neon databases delete`](https://neon.com/docs/cli/databases#delete):

```bash
neon databases delete database1
```

**API**

Delete a database with the [Delete database](https://neon.com/docs/reference/api/branches/delete-project-branch-database) endpoint:

```bash
curl -X 'DELETE' \
  'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/databases/database1' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Delete database](https://neon.com/docs/reference/api/branches/delete-project-branch-database) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "database": {
    "id": 2889509,
    "branch_id": "br-morning-meadow-123456",
    "name": "database1",
    "owner_name": "casey",
    "created_at": "2026-08-04T08:14:14Z",
    "updated_at": "2026-08-04T08:14:14Z"
  },
  "operations": [
    {
      "id": "4cd4881b-2807-4377-a76d-8e7d39bc5448",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-morning-meadow-123456",
      "endpoint_id": "ep-holy-heart-123456",
      "action": "apply_config",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T08:19:39Z",
      "updated_at": "2026-08-04T08:19:39Z",
      "total_duration_ms": 0
    }
  ]
}
```

</details>

## Manage databases with SQL

You can create and manage databases in Neon with SQL, as you can with any standalone Postgres installation. To create a database, issue a `CREATE DATABASE` statement from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor) or from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor).

```sql
CREATE DATABASE testdb;
```

Most standard [Postgres CREATE DATABASE parameters](https://www.postgresql.org/docs/current/sql-createdatabase.html) are supported with the exception of `TABLESPACE`. This parameter requires access to the local file system, which is not permitted in Neon.

The role that creates a database is the owner of the database. As noted at the top of this page, only the database owner can create objects in the `public` schema on Postgres 15 and later unless you grant `CREATE` to other roles.

For more information about database object privileges in Postgres, see [Privileges](https://www.postgresql.org/docs/current/ddl-priv.html).

### Rename a database with SQL

To rename a database, use `ALTER DATABASE`. Postgres won't let you rename a database while you're connected to it, so connect to a different database on the same branch first (for example, the default `neondb`), then run:

```sql
ALTER DATABASE old_db_name RENAME TO new_db_name;
```

If open connections to the database block the rename, terminate them first:

```sql
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE datname = 'old_db_name'
  AND pid <> pg_backend_pid();
```

The rename is instant, and data, schemas, tables, roles, and grants are unaffected. The database name is part of every connection string for the database, so update any application, script, or stored secret that references the old name. You can also rename a database with the [Neon API](https://neon.com/docs/manage/databases#update-a-database).

### Delete a database with SQL

To delete a database, use `DROP DATABASE`. As with renaming, connect to a different database on the same branch first, since Postgres won't drop the database you're connected to:

```sql
DROP DATABASE old_db_name;
```

Deletion is permanent. All schemas, tables, indexes, and other objects in the database are dropped along with it. You can also delete a database from the [Neon Console, CLI, or API](https://neon.com/docs/manage/databases#delete-a-database).

## Transfer database table ownership between roles

In Neon, roles created via the Console, CLI, or API are members of `neon_superuser` but are not full Postgres superusers. This means you can't directly transfer ownership of a database table from one role to another using `ALTER TABLE ... OWNER TO`.

The workaround is to introduce a shared group role that both roles belong to. You transfer ownership to the group, then the destination role can claim ownership for itself.

**Note:** In the example below, `current_owner`, `new_owner`, and `table_owners` are placeholder role and group names. Replace them with names from your own environment.

1. Connect as the owner of the database (or another role that can create roles) and run:

   ```sql
   -- Create a group role with no login
   CREATE ROLE table_owners NOLOGIN;

   -- Grant schema access to the group
   GRANT USAGE, CREATE ON SCHEMA public TO table_owners;

   -- Add both roles to the group
   GRANT table_owners TO current_owner;
   GRANT table_owners TO new_owner;
   ```

   Replace `current_owner` and `new_owner` with the actual role names.

2. Connect as `current_owner` and transfer the table to the group:

   ```sql
   ALTER TABLE your_table OWNER TO table_owners;
   ```

3. Connect as `new_owner`. Transfer ownership from the group to yourself:

   ```sql
   ALTER TABLE your_table OWNER TO new_owner;
   ```

4. Verify ownership:

   ```sql
   \dt your_table
   ```

   The **Owner** column should now show `new_owner`.

5. Leave the `table_owners` group role in place if you need to transfer other tables later, or drop it when you're done. Revoke its schema privileges first, or `DROP ROLE` fails:

   ```sql
   REVOKE ALL ON SCHEMA public FROM table_owners;
   DROP ROLE table_owners;
   ```

   `DROP ROLE` also fails if the role still owns objects.

### Transfer ownership for multiple objects

The numbered steps above show how to transfer one table with `ALTER TABLE ... OWNER TO`.

If you need to transfer ownership for everything a role owns in a database, use `REASSIGN OWNED` instead of running `ALTER ... OWNER TO` for each table.

`REASSIGN OWNED` includes tables and other object types owned by the role, such as views, materialized views, sequences, functions, schemas, and types.

Connect as `current_owner` and move all owned objects to the shared group:

```sql
REASSIGN OWNED BY current_owner TO table_owners;
```

Then connect as `new_owner` and move those objects from the group to the destination role:

```sql
REASSIGN OWNED BY table_owners TO new_owner;
```

**Note:**

- `REASSIGN OWNED` runs in the current database context, so run it in each database where you need to transfer ownership.
- `REASSIGN OWNED` reassigns ownership only. It does not change existing `GRANT` permissions or default privileges.

## Reserved database names

The following names are reserved and cannot be given to a database:

- `postgres`
- `template0`
- `template1`

--- [Document source](https://neon.com/docs/manage/integrations.md) ---

> Summary: The Integrations page in the Neon Console is the central hub for adding, configuring, and removing third-party integrations with a Neon project. Automated and manual setup flows are both supported. Use this page to connect a new service, update an existing integration, or request one that is not yet available. Unavailable integrations offer a Request button to register interest and inform the Neon team's rollout priorities.

# Manage integrations

Last updated: 2026-06-05

The **Integrations** page in the Neon Console provides a hub for managing third-party integrations with your Neon project. You can use these supported integrations to optimize and extend Neon's functionality and streamline your workflow.

When visiting the **Integrations** page, you'll notice different categories of integrations, which you can browse to find the one you need.

## Manage integrations

For integrations listed as **Added**, you can click **Manage** on the integration card to configure or remove the integration.

## Add integrations

For integrations that are not added, you can click **Add** and follow the instructions to get started. Some integrations support an automated integration setup. Others are documented integrations, which involve a manual setup procedure.

## Manual integrations

Integrations currently requiring a manual setup have a **Read** button, which opens a modal where you can read about how to integrate the selected platform or service with Neon.

## Express interest in future integrations

Integrations that are not yet available have a **Request** button, which opens a modal where you can express your interest and share your use case. This information helps the Neon team prioritize integration rollouts and build exactly what you need.

## Suggest an integration

If you can't find the integration you're looking for:

1. Click the **Suggest an integration** button on the **Integrations** page.
2. Fill out the necessary details for the integration you'd like to see added.
3. Click **Suggest integration**.

The Neon team will review your request.

--- [Document source](https://neon.com/docs/manage/maintenance-updates-overview.md) ---

> Summary: Neon performs two distinct update types: platform maintenance and compute updates. Platform maintenance covers infrastructure, resource management, and critical security patches; track it via the Neon Status page by region. Compute updates cover Postgres version upgrades, OS patches, and new Neon features; view them in the Console under Settings > Postgres. Paid plans can select a preferred update window.

# Maintenance & updates overview

Last updated: 2026-10-09

Neon performs two types of updates: **platform maintenance** and **updates** to your Neon [computes](https://neon.com/docs/reference/glossary#compute). While both are essential for maintaining a stable, secure, and optimized environment, they serve different purposes.

- **Platform maintenance** includes updates to Neon's infrastructure, resource management operations, and critical security patches. These changes ensure platform stability and security. To learn more, see [Platform maintenance](https://neon.com/docs/manage/platform-maintenance).

- **Updates** apply improvements and updates to individual Neon computes, including Postgres updates, operating system patches, and new Neon features. These updates keep your Neon compute environment and Postgres instances current and optimized. To learn more, see [Updates](https://neon.com/docs/manage/updates).

For both types of updates, we strive to minimize disruption to database operations and provide advanced notification. The table below outlines where you can check for upcoming maintenance and updates.

### Where to check for maintenance and updates

| Type                     | Where to check                                         | Details                                                                                                                                                                                                                                                |
| ------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Platform maintenance** | [Neon Status](https://neonstatus.com/)                 | Check the regional status page where your Neon project resides for upcoming platform maintenance. Optionally, subscribe to a regional status page to receive status updates. See [Neon Status](https://neon.com/docs/introduction/status) for details. |
| **Updates**              | [Neon Console](https://console.neon.tech/app/projects) | In your Neon project, go to **Settings** > **Postgres** to view your update window and check for update notices. Paid plans allow you to select a preferred update window.                                                                             |

--- [Document source](https://neon.com/docs/manage/operations.md) ---

> Summary: Neon Control Plane system operations are discrete, trackable actions that the control plane records for every user-initiated or system-initiated change to a project. Use this page to view operation history via the Console, CLI, or API; poll operation status before issuing the next API call to prevent race conditions; and recover from 423 Locked responses using exponential backoff. Terminal statuses are finished and skipped for successful completion, and failed, error, and cancelled for unsuccessful completion.

# System operations

Last updated: 2026-11-05

An operation is an action performed by the Neon Control Plane on a Neon object or resource. Operations are typically initiated by user actions, such as creating a branch or deleting a database. Other operations may be initiated by the Neon Control Plane, such as suspending a [compute](https://neon.com/docs/reference/glossary#compute) after a period of inactivity or checking its availability. You can monitor operations to keep an eye on the overall health of your Neon project or to check the status of specific operations. When working with the Neon API, you can poll the status of operations to ensure that an API request is completed before issuing the next API request. For more information, see [Poll operation status](https://neon.com/docs/manage/operations#poll-operation-status).

| Operation              | Description                                                                                                                                                                                                                                                                                                                                                      |
| :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Apply config`         | Applies a new configuration to a Neon object or resource. For example, changing compute settings or creating, deleting, or updating Postgres users and databases initiates this operation.                                                                                                                                                                       |
| `Apply storage config` | Applies a new configuration to a database storage object or resource. For example, updating the [history window](https://neon.com/docs/introduction/history-window) for a project initiates this operation.                                                                                                                                                      |
| `Check availability`   | Checks the availability of data in a branch and that a [compute](https://neon.com/docs/reference/glossary#compute) can start on a branch. Branches without a compute are not checked. This operation, performed by the [availability checker](https://neon.com/docs/reference/glossary#availability-checker), is a periodic load generated by the Control Plane. |
| `Create branch`        | Creates a [branch](https://neon.com/docs/reference/glossary#branch) in a Neon project. For related information, see [Manage branches](https://neon.com/docs/manage/branches).                                                                                                                                                                                    |
| `Create timeline`      | Sets up storage and creates the default branch when a Neon [project](https://neon.com/docs/reference/glossary#project) is created.                                                                                                                                                                                                                               |
| `Delete tenant`        | Deletes stored data when a Neon project is deleted.                                                                                                                                                                                                                                                                                                              |
| `Start compute`        | Starts a compute when there is an event or action that requires compute resources. For example, connecting to a suspended compute initiates this operation.                                                                                                                                                                                                      |
| `Suspend compute`      | Suspends a compute after a period of inactivity. For information about how Neon manages compute resources, see [Compute lifecycle](https://neon.com/docs/introduction/compute-lifecycle/).                                                                                                                                                                       |
| `Tenant attach`        | Attaches a Neon project to storage.                                                                                                                                                                                                                                                                                                                              |
| `Tenant detach`        | Detaches a Neon project from storage after the project as been idle for an extended period.                                                                                                                                                                                                                                                                      |
| `Tenant reattach`      | Reattaches a detached Neon project to storage when a detached project receives a request.                                                                                                                                                                                                                                                                        |
| `Timeline archive`     | The time when a branch archive operation was initiated.                                                                                                                                                                                                                                                                                                          |
| `Timeline unarchive`   | The time when the branch unarchive operation was initiated.                                                                                                                                                                                                                                                                                                      |

## View operations

You can view system operations via the Neon Console, [Neon CLI](https://neon.com/docs/cli), or [Neon API](https://neon.com/docs/reference/api).

**Neon Console**

You can view system operations via the **Monitoring** page in the Neon Console.

![System operations](https://neon.com/docs/changelog/operations_monitoring.png)

Operation details include:

- **Operation**: The action performed by the operation.
- **Branch**: The branch on which the operation was performed.
- **Compute**: The compute on which the operation occurred.
- **Operation status**: The status of the operation.
- **Duration**: The duration of the operation.
- **Date**: The date and time the operation occurred.

Possible **Status** values are `OK`, `Scheduling`, `In progress`, and `Error`.

**CLI**

To view operation using the Neon CLI:

```bash
neon operations list --project-id <project_id>
```

To check the status of one operation, pass its ID to `neon operations get`:

```bash
neon operations get <operation_id> --project-id <project_id>
```

See [Neon CLI commands — operations](https://neon.com/docs/cli/operations).

**API**

To list operations with the Neon API:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

See [Get a list of operations](https://neon.com/docs/reference/api/operations/list-project-operations).

## Operations and the Neon API

This section describes how to work with operations using the [Neon API](https://neon.com/docs/reference/api). The following topics are covered:

- [List operations](https://neon.com/docs/manage/operations#list-operations): Describes how to list all operations for a Neon project.
- [List operations with pagination](https://neon.com/docs/manage/operations#list-operations-with-pagination): Describes how to list all operations for a Neon project and paginate the response.
- [Get operation](https://neon.com/docs/manage/operations#get-operation): Describes how to retrieve the details for a specific operation by the operation ID.
- [Poll operation status](https://neon.com/docs/manage/operations#poll-operation-status): Describes how to poll an operation for its status, which may be necessary to avoid failed requests due to in-progress operations when using the Neon API programmatically.

**Note:** Operation names have underscores when view using the API; for example:

### List operations

Lists operations for the specified project. This method supports response pagination. For more information, see [List operations with pagination](https://neon.com/docs/manage/operations#list-operations-with-pagination).

```text
/projects/{project_id}/operations
```

cURL command:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [List operations](https://neon.com/docs/reference/api/operations/list-project-operations) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "operations": [
    {
      "id": "97c7a650-e4ff-43d7-8c58-4c67f5050167",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T08:47:52Z",
      "updated_at": "2022-12-09T08:47:56Z"
    },
    {
      "id": "0f3daf10-2544-425c-86d3-9a9932ab25b9",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T04:47:39Z",
      "updated_at": "2022-12-09T04:47:44Z"
    },
    {
      "id": "fb8484df-51b4-4a40-b0fc-97b73998892b",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T02:47:05Z",
      "updated_at": "2022-12-09T02:47:09Z"
    }
  ],
  "pagination": {
    "cursor": "2022-12-07T00:45:05.262011Z"
  }
}
```

</details>

### List operations with pagination

Pagination allows you to limit the number of operations displayed, as the number of operations for a project can be large. To paginate responses, issue an initial request with a `limit` value. For brevity, the limit is set to 1 in the following example.

cURL command:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations?limit=1' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [List operations](https://neon.com/docs/reference/api/operations/list-project-operations) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "operations": [
    {
      "id": "97c7a650-e4ff-43d7-8c58-4c67f5050167",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T08:47:52Z",
      "updated_at": "2022-12-09T08:47:56Z"
    }
  ],
  "pagination": {
    "cursor": "2022-12-09T08:47:52.20417Z"
  }
}
```

</details>

To list the next page of operations, add the `cursor` value returned in the response body of the previous request and a `limit` value for the next page.

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations?cursor=2022-12-09T08%3A47%3A52.20417Z&limit=1' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [List operations](https://neon.com/docs/reference/api/operations/list-project-operations) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "operations": [
    {
      "id": "0f3daf10-2544-425c-86d3-9a9932ab25b9",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-wispy-dew-591433",
      "endpoint_id": "ep-orange-art-714542",
      "action": "check_availability",
      "status": "finished",
      "failures_count": 0,
      "created_at": "2022-12-09T04:47:39Z",
      "updated_at": "2022-12-09T04:47:44Z"
    }
  ],
  "pagination": {
    "cursor": "2022-12-09T04:47:39.797163Z"
  }
}
```

</details>

### Get operation

This method shows only the details for the specified operation ID.

```text
/projects/{project_id}/operations/{operation_id}
```

cURL command:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations/97c7a650-e4ff-43d7-8c58-4c67f5050167' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Retrieve operation details](https://neon.com/docs/reference/api/operations/get-project-operation) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "operation": {
    "id": "97c7a650-e4ff-43d7-8c58-4c67f5050167",
    "project_id": "autumn-disk-484331",
    "branch_id": "br-wispy-dew-591433",
    "endpoint_id": "ep-orange-art-714542",
    "action": "check_availability",
    "status": "finished",
    "failures_count": 0,
    "created_at": "2022-12-09T08:47:52Z",
    "updated_at": "2022-12-09T08:47:56Z"
  }
}
```

</details>

## Poll operation status

Some Neon API requests may take a few moments to complete. When using the Neon API programmatically, you can check the `status` of an operation before proceeding with the next API request. For example, you may want to check the operation status of a create branch request before issuing a create database request for that branch.

The response to a Neon API request includes information about the operations that were initiated. For example, a create branch request initiates `create_branch` and `start_compute` operations.

```json
"operations": [
    {
      "id": "22acbb37-209b-4b90-a39c-8460090e1329",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "action": "create_branch",
      "status": "running",
      "failures_count": 0,
      "created_at": "2022-12-08T19:55:43Z",
      "updated_at": "2022-12-08T19:55:43Z"
    },
    {
      "id": "055b17e6-ffe3-47ab-b545-cfd7db6fd8b8",
      "project_id": "autumn-disk-484331",
      "branch_id": "br-dawn-scene-747675",
      "endpoint_id": "ep-small-bush-675287",
      "action": "start_compute",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2022-12-08T19:55:43Z",
      "updated_at": "2022-12-08T19:55:43Z"
    }
  ]
```

You can use the [Get operation details](https://neon.com/docs/reference/api/operations/get-project-operation) method to poll the status of an operation by the operation ID. You might do this at intervals of 5 seconds until the `status` of the operation changes to `finished` before issuing the next request. For example, this request polls the `start_compute` operation shown above:

```bash
curl 'https://console.neon.tech/api/v2/projects/autumn-disk-484331/operations/055b17e6-ffe3-47ab-b545-cfd7db6fd8b8' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Get operation details](https://neon.com/docs/reference/api/operations/get-project-operation) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "operation": {
    "id": "055b17e6-ffe3-47ab-b545-cfd7db6fd8b8",
    "project_id": "autumn-disk-484331",
    "branch_id": "br-dawn-scene-747675",
    "endpoint_id": "ep-small-bush-675287",
    "action": "start_compute",
    "status": "finished",
    "failures_count": 0,
    "created_at": "2022-12-08T19:55:43Z",
    "updated_at": "2022-12-08T19:55:43Z"
  }
}
```

</details>

Possible operation `status` values include: `scheduling`, `running`, `finished`, `failed`, `error`, `cancelling`, `cancelled`, and `skipped`. The successful terminal statuses are `finished` and `skipped`; the unsuccessful terminal statuses are `failed`, `error`, and `cancelled`. The remaining statuses are nonterminal. A failed operation can include retry history in `failures_count` and `retry_at`.

## Handle concurrent operation errors

Neon limits overlapping operations on a project. One API response can still list several operations (for example `create_branch` and `start_compute`) when they are part of the same request. If you try to start more work while the project is already busy with conflicting operations, the API returns **`423 Locked`**.

This can happen when:

- Your own API requests overlap. For example, creating a branch before a previous branch creation has finished.
- A system-initiated operation is running, such as a [platform maintenance](https://neon.com/docs/manage/platform-maintenance) task or a periodic [availability check](https://neon.com/docs/manage/operations#view-operations).

Following [Poll operation status](https://neon.com/docs/manage/operations#poll-operation-status) limits conflicts from your own overlapping requests. You can still get `423` if a system-initiated operation starts between your poll and your next call, so keep [retry handling](https://neon.com/docs/manage/operations#retry-with-exponential-backoff) as a fallback.

### Retry with exponential backoff

If the API returns **`423 Locked`**, retry the same request after a short wait, increasing the delay between attempts (exponential backoff), and stop after a maximum number of tries. The example below starts at 0.1 seconds and doubles the wait on each attempt, up to five attempts.

```bash
#!/usr/bin/env bash
# Retries a create-branch request when the response is 423 Locked.
# Set PROJECT_ID and NEON_API_KEY. Replace br-main-abc123 with a parent branch id from your project.

MAX_RETRIES=5
DELAY=0.1  # 100 msec

for ATTEMPT in $(seq 1 "$MAX_RETRIES"); do
  response=$(curl -s -w "\n%{http_code}" \
    "https://console.neon.tech/api/v2/projects/${PROJECT_ID}/branches" \
    -H 'Accept: application/json' \
    -H "Authorization: Bearer ${NEON_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{"endpoints":[{"type":"read_write"}],"branch":{"parent_id":"br-main-abc123"}}')

  http_code=$(echo "$response" | tail -n1)
  body=$(echo "$response" | sed '$d')

  if [ "$http_code" != "423" ]; then
    echo "$body"
    exit 0
  fi

  echo "Project locked, retrying in ${DELAY}s (attempt ${ATTEMPT}/${MAX_RETRIES})..." >&2
  sleep "$DELAY"
  DELAY=$(awk -v d="$DELAY" 'BEGIN { printf "%.10g", d * 2 }')
done

echo "Max retries reached" >&2
exit 1
```

Replace `br-main-abc123` with a branch id from your project. See [Create a branch with the API](https://neon.com/docs/manage/branches#create-a-branch-with-the-api) for the full request shape.

--- [Document source](https://neon.com/docs/manage/organizations.md) ---

> Summary: Neon Organizations are the top-level containers for all projects, providing centralized billing, member management, and access controls for teams on free and paid plans. Teams use organizations to collaborate across projects, assign organization roles, grant per-project permissions, and auto-provision users by verified email domain. Current limitations include all users being able to manage protected branches regardless of role, and per-project permissions that can raise a member's access but not restrict it.

# Organizations

Manage your projects and collaborate with team members

Last updated: 2026-08-04

In Neon, all projects live within organizations. When you sign up, you automatically get a free organization for your first project. Organizations provide a central place to manage your projects and collaborate with team members. You can start inviting teammates as soon as your organization is created. Paid plans also include billing management for your organization.

## About Neon Organizations

In the Neon Console, the Organizations page gives you a centralized view of all your projects. From there, you can create new projects, manage existing ones, and oversee your members and billing information.

## User roles and permissions

Access works in two layers. An organization role sets a member's baseline access across every project, and per-project permissions grant extra access on individual projects. The two are additive, so a per-project permission can only raise someone's access, never lower it.

There are four organization roles:

- **Admin**: Full control over the organization and all its projects, including billing, members, and settings.
- **Editor**: Access to all organization projects, but cannot modify org settings, delete projects, or transfer them out of the organization.
- **Viewer**: Read-only access to organization and project metadata. Cannot see connection strings or run SQL.
- **Collaborator**: No access by default. Sees only the projects they're explicitly granted.

For a full breakdown of what each role and per-project permission allows, see the [User permissions](https://neon.com/docs/manage/user-permissions) page. That page also explains [which roles receive certain organization emails](https://neon.com/docs/manage/user-permissions#email-notifications) (for example, alerts when a project is close to its storage limit).

You can also [auto-provision members by email domain](https://neon.com/docs/manage/orgs-add-members-by-domain) so that users whose email matches a verified domain are added to the organization automatically when they sign up or log in.

## Creating a new organization

You can create additional organizations at any time. [See how to create an organization.](https://neon.com/docs/manage/orgs-manage#create-an-organization)

## Switching between organizations

If you belong to more than one organization, use the org switcher in the profile menu (click your name in the top-right corner of the Console) to change the active organization. [See how to switch organizations.](https://neon.com/docs/manage/orgs-manage#switch-organizations)

## Limitations

As we continue to refine our organization features, here are some temporary limitations you should be aware of:

- **Branch management**: All users are currently able to manage [protected branches](https://neon.com/docs/guides/protected-branches), regardless of their role or permission level. Granular permissions for this feature are not yet implemented.
- **Access can only be added, not restricted**: Per-project permissions raise a member's access above their organization-role baseline; they can't reduce it. There's no way to block an Editor from a single project. To limit someone to specific projects, give them the **Collaborator** role and grant permissions on just those projects. See [Notes and limitations](https://neon.com/docs/manage/user-permissions#notes-and-limitations).

## Feedback

If you've got feature requests or feedback about what you'd like to see from Organizations in Neon, let us know via the [Feedback](https://console.neon.tech/app/projects?modal=feedback) form in the Neon Console or our [feedback channel](https://discord.com/channels/1176467419317940276/1176788564890112042) on Discord.

--- [Document source](https://neon.com/docs/manage/orgs-add-members-by-domain.md) ---

> Summary: Auto-join by domain lets admins verify email domains via DNS TXT record. Users who sign up or log in with a matching address are automatically added as Editors, with no manual invite required. Use this page to auto-provision org membership for your company domain instead of sending individual invites. An org can have multiple verified domains, and the same domain can be shared across multiple Neon organizations.

# Add organization members by domain

Last updated: 2026-08-07

Organization admins can add verified email domains so that users whose email matches one of those domains are automatically added as members when they sign up or log in. No manual invite is required for those users.

Only organization admins can add, verify, or remove domains. The **Auto-join by domain** section appears on your organization's **People** page when this feature is available for your org.

## How it works

- You add a domain (for example, `example.com`) on the organization **People** page under **Auto-join by domain**. The domain is added in a "Pending verification" state and Neon generates a verification code.
- You add a TXT record at your domain with that exact code. After DNS propagates, you click **Verify** in the Console to confirm you own the domain.
- When a user signs up or logs in to Neon with an email whose domain matches one of your verified domains (for example, `alex@example.com`), they are automatically added to your organization as an Editor. They do not receive an invite email; they simply see the organization in their [org switcher](https://neon.com/docs/manage/orgs-manage#switch-organizations).

An organization can have multiple verified domains. The same domain can also be added to multiple organizations. If a user's email domain matches verified domains in more than one org, they are added to all of those organizations.

## Add and verify a domain

## Open the People page

In the Neon Console, switch to the organization you want to manage, then open the **People** page. Scroll to the **Auto-join by domain** section (below **Pending invites**). The section shows a short description and a **Domain** field with an **Add domain** button.

![Auto-join by domain section before adding a domain: Domain input field and Add domain button](https://neon.com/docs/manage/Auto_join_by_domain.png)

## Add the domain

In the **Domain** field, enter your domain (for example, `example.com`) and click **Add domain**. The domain appears in a card above the input with status **Pending verification**. The card shows a **Verification TXT record** value (a string starting with `neon-domain-verification=`) and instructs you to add a TXT record at your domain with that exact value, then click **Verify** after DNS propagates. Below the card, an **Add another domain** field lets you add additional domains.

![Domain added with Pending verification status, Verification TXT record value, and Verify button](https://neon.com/docs/manage/auto_join_by_domain_verify.png)

## Add the TXT record at your DNS provider

In your DNS provider's console, add a TXT record at your domain with the exact value shown in the Neon Console (copy it using the icon next to the value). Use the root or host you manage for the domain. Do not add a subdomain prefix to the value itself; paste the single string as the TXT record content.

**Tip: DNS propagation**

TXT records can take from a few minutes to 48 hours to propagate. If verification fails, wait a bit and try again, or check that the TXT record is published (for example, with `dig TXT yourdomain.com` or your provider's DNS checker).

## Verify the domain

After the TXT record has propagated, click **Verify** in the Neon Console (in the verification section for that domain). If the record matches, the domain status changes to **Verified**. Users who sign up or log in with an email at that domain will then be automatically added to the organization as members.

**Tip: After verification**

You can delete the TXT record from your domain after verification. Neon only uses it to confirm ownership; the record does not need to remain in place.

## Remove a domain

Only organization admins can remove a domain. In the **Auto-join by domain** section on the **People** page, open the actions menu (⋮) for the domain and choose **Remove**. Confirm in the dialog. After removal, new users with that email domain will no longer be automatically added to the organization. Existing members are not affected.

## Behavior details

- **Role:** Users who are automatically added receive the **Editor** role, which gives them access to every project in the organization. Admins can change their role later from the **People** page if needed. See [Organization roles](https://neon.com/docs/manage/user-permissions#organization-roles).
- **Existing members:** If the user is already a member of the organization, no duplicate is created; they are simply signed in as usual.
- **Sign up and log in:** Users are automatically added both when they create a new Neon account and when an existing user logs in. So if you add and verify a domain after some colleagues already have Neon accounts, those colleagues will be added to the org the next time they log in (as long as their email domain matches).

## Related

- [Manage organizations](https://neon.com/docs/manage/orgs-manage) for inviting members manually and managing roles.
- [User permissions](https://neon.com/docs/manage/user-permissions) for a breakdown of what each organization role and per-project permission allows.

--- [Document source](https://neon.com/docs/manage/orgs-api-consumption.md) ---

> Summary: The Neon API provides an organization-scoped consumption endpoint on the Scale plan: `/consumption_history/projects` for per-project breakdowns. It returns usage metrics at hourly, daily, or monthly granularity. Use this page to audit cross-project usage, build chargeback reports, or monitor billing trends. To find your org_id before querying, use GET `/users/me/organizations` with a personal API key.

# Query organization usage metrics with the Neon API

Last updated: 2026-07-15

You can use the Neon API to retrieve project-level consumption metrics for your organization:

| Metric                                                                                                          | Description                                                                       | Plan Availability |
| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------- |
| [Project-level](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project) (granular) | Project-level metrics available at hourly, daily, or monthly level of granularity | Scale             |

## Finding organizations for consumption queries

Before querying consumption metrics, you'll need the `org_id` values for organizations you want to query. Use your personal API key to list all organizations you have access to:

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/users/me/organizations' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $PERSONAL_API_KEY' | jq
```

The response includes details about each organization, including the `org_id` you'll need for consumption queries:

```json
{
  "organizations": [
    {
      "id": "org-morning-bread-81040908",
      "name": "Morning Bread Organization",
      "handle": "morning-bread-organization-org-morning-bread-81040908",
      "plan": "free_v2",
      "created_at": "2025-04-30T14:43:00Z",
      "managed_by": "console",
      "updated_at": "2025-04-30T14:46:22Z"
    },
    {
      "id": "org-super-grass-41324851",
      "name": "Super Org Inc",
      "handle": "super-org-inc-org-super-grass-41324851",
      "plan": "scale_v2",
      "created_at": "2025-06-02T16:56:18Z",
      "managed_by": "console",
      "updated_at": "2025-06-02T16:56:18Z"
    }
  ]
}
```

### Project-level metrics (granular)

You can also get similar daily, hourly, or monthly metrics across a selected time period, but broken out for each individual project that belongs to your organization.

Using the endpoint `GET /consumption_history/projects`, let's use the same start date, end date, and level of granularity as our account-level request: hourly metrics between June 30th and July 2nd, 2024.

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/consumption_history/projects?limit=10&from=2024-06-30T00%3A00%3A00Z&to=2024-07-02T00%3A00%3A00Z&granularity=hourly&org_id=org-ocean-art-12345678' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY'
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Retrieve project consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "projects": [
    {
      "project_id": "random-project-123456",
      "periods": [
        {
          "period_id": "random-period-abcdef",
          "period_plan": "scale",
          "period_start": "2024-06-30T00:00:00Z",
          "consumption": [
            {
              "timeframe_start": "2024-06-30T00:00:00Z",
              "timeframe_end": "2024-06-30T01:00:00Z",
              "active_time_seconds": 147472,
              "compute_time_seconds": 43222,
              "written_data_bytes": 112730864,
              "synthetic_storage_size_bytes": 37000959232
            },
            {
              "timeframe_start": "2024-07-01T00:00:00Z",
              "timeframe_end": "2024-07-01T01:00:00Z",
              "active_time_seconds": 1792,
              "compute_time_seconds": 533,
              "written_data_bytes": 0,
              "synthetic_storage_size_bytes": 0
            }
            // ... More consumption data
          ]
        },
        {
          "period_id": "random-period-ghijkl",
          "period_plan": "scale",
          "period_start": "2024-07-01T09:00:00Z",
          "consumption": [
            {
              "timeframe_start": "2024-07-01T09:00:00Z",
              "timeframe_end": "2024-07-01T10:00:00Z",
              "active_time_seconds": 150924,
              "compute_time_seconds": 44108,
              "written_data_bytes": 114912552,
              "synthetic_storage_size_bytes": 36593552376
            }
            // ... More consumption data
          ]
        }
        // ... More periods
      ]
    }
    // ... More projects
  ]
}
```

</details>

### Invoice-aligned metrics

For metrics that match your invoice on usage-based plans (Launch, Scale, Agent, and Enterprise), use `/consumption_history/v2/projects`. See [Query consumption metrics](https://neon.com/docs/guides/consumption-metrics).

## Metric definitions

- **active_time_seconds**: The number of seconds the project's computes have been active during the period.
- **compute_time_seconds**: The number of CPU seconds used by the project's computes, including computes that have been deleted; for example:
  - A compute that uses 1 CPU for 1 second is equal to `compute_time=1`.
  - A compute that uses 2 CPUs simultaneously for 1 second is equal to `compute_time=2`.
- **written_data_bytes**: The total amount of data written to all of a project's branches.
- **synthetic_storage_size_bytes**: The total space occupied in storage. Synthetic storage size combines the logical data size and Write-Ahead Log (WAL) size for all branches.

--- [Document source](https://neon.com/docs/manage/orgs-api.md) ---

> Summary: Neon Organization API endpoints for managing org API keys, members, invitations, and project transfers. Organization API keys are auto-scoped to the org; personal API keys require an explicit org_id parameter. Some operations, including creating invitations, removing members, and transferring projects, require a personal admin key and reject organization API keys. A permission matrix maps each endpoint to its supported key type.

# Manage organizations using the Neon API

Last updated: 2026-08-04

Learn how to manage Neon Organizations using the Neon API, including managing organization API keys, working with organization members, and handling member invitations.

## Personal vs organization API keys

You can authorize your API requests using either of these methods:

- **Organization API key**: Automatically scopes all requests to your organization
- **Personal API key**: Requires including an `org_id` parameter to specify which organization you're working with

The key difference is in how you structure your API requests. Here's an example of listing projects using both methods:

Using an organization API key:

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects' \
     --header 'authorization: Bearer $ORG_API_KEY'
```

Using a personal API key:

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects?org_id=org-example-12345678' \
     --header 'authorization: Bearer $PERSONAL_API_KEY'
```

Both examples retrieve a list of projects, but notice how the personal API key request includes `org_id=org-example-12345678` to specify which organization's projects to list. With an organization API key, this parameter isn't needed because the key itself is already tied to a specific organization.

### Matrix of operations and key types

Some operations require a personal API key from an organization admin and cannot be performed using organization API keys. These operations are marked with ❌ in the matrix below.

| Action                                                                                                                   | Personal API Key | Organization API Key |
| ------------------------------------------------------------------------------------------------------------------------ | ---------------- | -------------------- |
| [Create an organization API key](https://neon.com/docs/manage/orgs-api#create-api-keys)                                  | ✅                | ❌                    |
| [Get a list of organization API keys](https://neon.com/docs/manage/orgs-api#list-api-keys)                               | ✅                | ✅                    |
| [Revoke an organization API key](https://neon.com/docs/manage/orgs-api#revoke-an-api-key)                                | ✅                | ✅                    |
| [Get organization details](https://neon.com/docs/manage/orgs-api#get-organization-details)                               | ✅                | ✅                    |
| [Get organization members details](https://neon.com/docs/manage/orgs-api#list-members)                                   | ✅                | ✅                    |
| [Get organization member details](https://neon.com/docs/manage/orgs-api#get-member-details)                              | ✅                | ✅                    |
| [Update the role for an organization member](https://neon.com/docs/manage/orgs-api#update-member-role)                   | ✅                | ✅                    |
| [Remove member from the organization](https://neon.com/docs/manage/orgs-api#remove-member)                               | ✅                | ❌                    |
| [Get organization invitation details](https://neon.com/docs/manage/orgs-api#list-invitations)                            | ✅                | ✅                    |
| [Create organization invitations](https://neon.com/docs/manage/orgs-api#create-invitations)                              | ✅                | ❌                    |
| [Transfer projects between organizations](https://neon.com/docs/manage/orgs-api#transfer-projects-between-organizations) | ✅                | ❌                    |

## Finding your org_id

To find your organization's `org_id`, navigate to your Organization's **Settings** page, where you'll find it under the **General information** section. Copy and use this ID in your API requests.

![finding your organization ID from the settings page](https://neon.com/docs/manage/orgs_id.png)

## Create API keys

There are two types of organization API keys:

- **Organization API keys**: Provide admin-level access to all organization resources, including projects, members, and settings. Only organization Admins can create these keys.
- **Project-scoped organization API keys**: Provide [**Editor** access](https://neon.com/docs/manage/user-permissions#per-project-permissions) to a single project within the organization, so they can read and modify project resources but can't delete the project or manage who can access it. Only organization Admins can create these keys.

If you're an Editor, Viewer, or Collaborator, create a personal API key instead; it's scoped to your own access.

The key token is only displayed once at creation time. Copy it immediately and store it securely. If lost, you'll need to revoke the key and create a new one. For detailed instructions, see [Manage API Keys](https://neon.com/docs/manage/api-keys#create-an-organization-api-key).

Organization API key creation (`POST /organizations/{org_id}/api_keys`) is rate limited to 10 requests per second. If you create keys in bulk, throttle your requests or use retries with backoff.

[Try in API Reference](https://neon.com/docs/reference/api/organizations/create-org-api-key)

## List API keys

Lists all API keys for your organization. The response does not include the actual key tokens, as these are only provided when creating a new key.

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/api_keys' \
     --header 'authorization: Bearer $PERSONAL_API_KEY' | jq
```

Example response:

```json
[
  {
    "id": 123456,
    "name": "my-key-name",
    "created_at": "2024-01-01T12:00:00Z",
    "created_by": {
      "id": "user-abc123de-4567-8fab-9012-3cdef4567890",
      "name": "John Smith",
      "image": "https://avatar.example.com/user.jpg"
    },
    "last_used_at": "2024-01-01T12:30:00Z",
    "last_used_from_addr": "192.0.2.1,192.0.2.2"
  }
]
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/list-org-api-keys)

## Revoke an API key

Revokes the specified organization API key. This action cannot be reversed. You can obtain the `key_id` by listing the API keys for your organization.

```bash
curl --request DELETE \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/api_keys/{key_id}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $PERSONAL_API_KEY' | jq
```

Example response:

```json
{
  "id": 123456,
  "name": "my-key-name",
  "created_at": "2024-01-01T12:00:00Z",
  "created_by": "user-abc123de-4567-8fab-9012-3cdef4567890",
  "last_used_at": "2024-01-01T12:30:00Z",
  "last_used_from_addr": "192.0.2.1,192.0.2.2",
  "revoked": true
}
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/revoke-org-api-key)

## Get organization details

Retrieves information about your organization, including its name, plan, and creation date.

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}' \
     --header 'authorization: Bearer $PERSONAL_API_KEY' | jq
```

Example response:

```json
{
  "id": "org-example-12345678",
  "name": "Example Organization",
  "handle": "example-organization-org-example-12345678",
  "plan": "business",
  "created_at": "2024-01-01T12:00:00Z",
  "managed_by": "console",
  "updated_at": "2024-01-01T12:00:00Z"
}
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/get-organization)

## List members

Retrieves a paginated list of members for the specified organization. Each entry includes the member ID, user ID, organization role, join date, and the user's email. Member objects may include optional `has_mfa` and `deactivated_at` fields.

- `has_mfa`: Whether the member has TOTP (2FA) enabled.
- `deactivated_at`: Timestamp indicating the member account is deactivated.

You can sort by `email`, `role`, or `joined_at` (default), set `sort_order` to `asc` or `desc`, and use `limit` (1–500) to control page size. Use the `cursor` from the response `pagination.next` to fetch the next page.

**Example: list members with sorting and pagination**

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/members?limit=20&sort_by=joined_at&sort_order=desc' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY' | jq
```

**Example: next page (using cursor from previous response)**

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/members?limit=20&sort_by=joined_at&sort_order=desc&cursor=eyJtZW1iZXJfaWQiOi...' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY' | jq
```

Example response:

```json
{
  "members": [
    {
      "member": {
        "id": "abc123de-4567-8fab-9012-3cdef4567890",
        "user_id": "def456gh-7890-1abc-2def-3ghi4567890j",
        "org_id": "org-example-12345678",
        "role": "admin",
        "joined_at": "2024-01-01T12:00:00Z"
      },
      "user": {
        "email": "user@example.com",
        "has_mfa": true,
        "deactivated_at": "2026-05-01T12:00:00Z"
      }
    }
  ],
  "pagination": {
    "next": "eyJtZW1iZXJfaWQiOiI1ZmVlMTNhYy05NTdiLTQwY2QtOGRlMC00ZDQ5NGNjMjhlMjgiLCJzb3J0X2J5Ijoiam9pbmVkX2F0In0=",
    "sort_by": "joined_at",
    "sort_order": "desc"
  }
}
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/get-organization-members)

**Note:** The member ID (`id`) from this response is needed for operations like updating roles or removing members.

## Get member details

Retrieves information about a specific member using their member ID (obtained from the [List members](https://neon.com/docs/manage/orgs-api#list-members) endpoint).

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/members/{member_id}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY'
```

Example response:

```json
{
  "id": "abc123de-4567-8fab-9012-3cdef4567890",
  "user_id": "def456gh-7890-1abc-2def-3ghi4567890j",
  "org_id": "org-example-12345678",
  "role": "admin",
  "joined_at": "2024-01-01T12:00:00Z"
}
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/get-organization-member)

## Update member role

Changes a member's current role in the organization. If using your personal API key, you need to be an admin in the organization to perform this action. Note: you cannot downgrade the role of the organization's only admin.

Valid roles are `admin`, `editor`, `viewer`, and `collaborator`. The value `member` is still accepted as a legacy alias for `editor`. A member's organization role sets their baseline access on every project; to change their access on a single project, see [Manage project access](https://neon.com/docs/manage/orgs-api#manage-project-access).

```bash
curl --request PATCH \
     --url 'https://console.neon.tech/api/v2/organizations/members/{member_id}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY' \
     --header 'content-type: application/json' \
     --data '{"role": "editor"}' | jq
```

Example response:

```json
{
  "id": "abc123de-4567-8fab-9012-3cdef4567890",
  "user_id": "def456gh-7890-1abc-2def-3ghi4567890j",
  "org_id": "org-example-12345678",
  "role": "editor",
  "joined_at": "2024-01-01T12:00:00Z"
}
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/update-organization-member)

## Remove member

You must use your personal API key and have admin-level permissions in the organization to use this endpoint. Organization API keys are not supported.

```bash
curl --request DELETE \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/members/{member_id}' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $PERSONAL_API_KEY'
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/remove-organization-member)

## List invitations

Retrieves a list of all pending invitations for the organization.

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/organizations/invitations' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY' | jq
```

Example response:

```json
{
  "invitations": [
    {
      "id": "abc123de-4567-8fab-9012-3cdef4567890",
      "email": "user@example.com",
      "org_id": "org-example-12345678",
      "invited_by": "def456gh-7890-1abc-2def-3ghi4567890j",
      "invited_at": "2024-01-01T12:00:00Z",
      "role": "editor"
    }
  ]
}
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/get-organization-invitations)

## Create invitations

Creates invitations for new organization members. Specify the organization role each invited user should get (`admin`, `editor`, `viewer`, or `collaborator`). Each invited user:

- Receives an email notification about the invitation
- If they have an existing Neon account, they automatically join with the role you specified
- If they don't have an account yet, the email invites them to create one

You must use your personal API key and have admin-level permissions in the organization to use this endpoint. Organization API keys are not supported.

```bash
curl --request POST \
     --url 'https://console.neon.tech/api/v2/organizations/{org_id}/invitations' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $PERSONAL_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "invitations": [
         {
           "email": "user@example.com",
           "role": "editor"
         }
       ]
     }' | jq
```

[Try in API Reference](https://neon.com/docs/reference/api/organizations/create-organization-invitations)

## Transfer projects between organizations

The API supports transferring projects between organizations. For detailed instructions and examples, see [Transfer projects to an organization](https://neon.com/docs/manage/orgs-project-transfer).

Key requirements:

- Must use a personal API key
- Requires Admin in the source organization, and a role that can create projects in the target (Admin, Editor, or Viewer)

[Try in API Reference](https://neon.com/docs/reference/api/organizations/transfer-projects-from-org-to-org)

## Manage project access

For organizations on the [new permissions model](https://neon.com/docs/manage/user-permissions), you can list project members and set or remove a member's project role through the API. See [Manage project access with the API](https://neon.com/docs/manage/user-permissions#manage-project-access-with-the-api) for endpoints and examples.

--- [Document source](https://neon.com/docs/manage/orgs-cli.md) ---

> Summary: The Neon CLI supports organization-scoped commands using the `--org-id` flag or a saved context file. Run `neon orgs list` to look up an org ID, and use `neon projects list` or `neon projects create` scoped to an org. To avoid repeating `--org-id` on every command, set a persistent org context with `set-context`.

# Manage Organizations using the Neon CLI

Last updated: 2026-11-05

Neon's CLI provides an expanding set of commands to manage your organizations.

## Authorization

Use the `login` command to authenticate your Neon account from the CLI. This command opens a browser where you will be asked to grant the necessary permissions to manage your Neon resources across all organizations you belong to. Your OAuth token is stored in `~/.config/neon/credentials.json`.

Authentication is tied to your Neon user account. Once authenticated, you can access and manage any organization you belong to. When running commands, you'll need to specify which organization to use via `--org-id`, a [context file](https://neon.com/docs/cli/set-context), or by responding to the interactive prompt.

See [Login - CLI](https://neon.com/docs/cli/login) to learn more.

## List Organizations

The `neon orgs list` command outputs a list of all organizations that the CLI user currently belongs to. This command is useful for quickly identifying the `org_id` associated with each organization, which can be used in other CLI operations.

Example:

```bash
neon orgs list
Organizations
ID                      Name         Plan
org-ocean-art-12345678  Example Org  Launch
```

See [Orgs - CLI](https://neon.com/docs/cli/orgs) to learn more.

## Manage members and invitations

The `neon orgs members` commands list, inspect, update, and remove the members of an organization, and `neon orgs invitations` lists and sends invitations. Changing a role or removing a member requires an organization Admin. Organization API keys can't send invitations, so use a personal API key.

```bash
neon orgs members list --org-id org-xxxx-xxxx
neon orgs invitations create --email dana@example.com --role editor --org-id org-xxxx-xxxx
```

See [Orgs - CLI](https://neon.com/docs/cli/orgs#members) to learn more.

## Manage spending notifications

The `neon orgs spending-limit` commands get, set, and remove the organization's monthly [spending notification](https://neon.com/docs/introduction/spending-notifications) threshold, in US dollars:

```bash
neon orgs spending-limit set 500 --org-id org-xxxx-xxxx
```

See [Orgs - CLI](https://neon.com/docs/cli/orgs#spending-limit) to learn more.

## Manage projects within an Organization

The Neon CLI `projects` command supports an `--org-id` option. This allows you to list or create projects within a specified organization.

Example: Listing all projects in an organization:

```bash
neon projects list --org-id org-xxxx-xxxx
Projects
ID                       Name                      Region ID         Created At
bright-moon-12345678     dev-backend-api           aws-us-east-2     2026-07-26T11:43:37Z
silent-forest-87654321   test-integration-service  aws-eu-central-1  2026-05-30T22:14:49Z
crystal-stream-23456789  staging-web-app           aws-us-east-2     2026-05-17T13:47:35Z
```

You can include the `org-id` to apply the following subcommands specifically to your organization:

- [List projects](https://neon.com/docs/cli/projects#list)
- [Create projects](https://neon.com/docs/cli/projects#create)

See [Projects - CLI](https://neon.com/docs/cli/projects) to learn more.

## Manage project access

The CLI doesn't have a dedicated command for [per-project permissions](https://neon.com/docs/manage/user-permissions) yet. To manage who can access a project from the CLI, use the [`neon api`](https://neon.com/docs/cli/api) command, which sends an authenticated request to any Neon API route.

For example, to set an organization member's role on a project, call the member-role endpoint with the role you want to grant (`viewer`, `editor`, or `admin`). You send the role in lowercase; the response reports it as an uppercase permission level (`VIEWER`, `EDITOR`, or `ADMIN`):

```bash
neon api /projects/{project_id}/members/{member_id}/role -X PUT -F role=editor
```

To remove a member's explicit role on a project (they keep whatever their organization role grants by default):

```bash
neon api /projects/{project_id}/members/{member_id}/role -X DELETE
```

The [API key's permissions](https://neon.com/docs/manage/api-keys#types-of-api-keys) determine what these requests can do: only organization Admins can manage project access. For the full list of project-access routes and their fields, see the [Neon API reference](https://neon.com/docs/reference/api).

## Setting Organization Context

To simplify your workflow, the Neon CLI `set-context` command supports setting an organization context. This means you don't have to specify an organization ID every time you run a CLI command.

Sees [set-context - CLI](https://neon.com/docs/cli/set-context) to learn more.

--- [Document source](https://neon.com/docs/manage/orgs-manage.md) ---

> Summary: Neon organization management covers Console workflows for creating organizations, inviting members, assigning organization roles, granting per-project permissions, requiring 2FA, and managing per-organization billing. Use this page to add or remove members, change someone's role, or delete an organization from the UI. Admins control deletions, billing changes, and 2FA enforcement.

# Manage Neon Organizations

Last updated: 2026-11-05

Learn how to manage your organization's projects, invite members, set their access, and oversee billing details. For a breakdown of what each organization role and per-project permission allows, see [User permissions](https://neon.com/docs/manage/user-permissions).

**Note:** Organizations managed through the [Vercel-managed integration](https://neon.com/docs/guides/vercel-managed-integration) still use the legacy roles (Admin, Member, Collaborator). See [Legacy permissions](https://neon.com/docs/manage/user-permissions#legacy-permissions).

## Create an organization

To create a new org, use the **Create organization** button in the profile menu in the top-right of the console.

Select a plan for your new organization. Organizations can be free or paid; if you choose a paid plan, you'll enter billing details.

![create organization with billing](https://neon.com/docs/manage/orgs_create_with_billing.png)

After confirming, you'll be directed to your new organization's **Projects** page, where you can get started creating projects and inviting [members](https://neon.com/docs/manage/orgs-manage#invite-members).

## Switch organizations

If you belong to more than one organization, use the org switcher in the profile menu to change which one you're working in.

1. Click your name in the top-right corner of the Console to open the profile menu.
2. Under **Organization**, click the name of your current organization. A list of every organization you belong to opens, with a check mark next to the active one.
3. Select the organization you want to work in. If you belong to many organizations, type in **Search organizations** to filter the list.

The Console opens that organization's projects, and the rest of the Console now applies to the organization you selected.

![org switcher in the Neon Console profile menu](https://neon.com/docs/manage/orgs_switch.png)

If someone has shared a project with you through [project sharing](https://neon.com/docs/manage/orgs-manage#project-sharing), select **Projects shared with me** in the switcher to see those projects.

## Invite members

Only Admins can invite new members to the organization. Invitations are issued via email. If a recipient does not have a Neon account, they will receive instructions to create one. Alternatively, you can [auto-provision members by domain](https://neon.com/docs/manage/orgs-add-members-by-domain) so that users with a matching email domain are added automatically when they sign up or log in.

![organizations people tab](https://neon.com/docs/manage/orgs_people.png)

To invite members:

- Navigate to the **People** page in your Organization.
- Click **Invite member** and enter the email addresses in a comma-separated list.
- Choose the organization role each person should get. The role sets their baseline access across every project in the organization. See [Organization roles](https://neon.com/docs/manage/user-permissions#organization-roles).
- Monitor the status of sent invites on the **Pending Invites** section; from here, you can resend or cancel invitations as needed.

**Note: Invites not received?**

If invite emails aren't received, they may be in spam or quarantined. Recipients should check these folders and mark Neon emails as safe.

To list members, update roles, or send invitations from the terminal, use [`neon orgs members`](https://neon.com/docs/cli/orgs#members) and [`neon orgs invitations`](https://neon.com/docs/cli/orgs#invitations). To do it programmatically, see [Manage organizations using the Neon API](https://neon.com/docs/manage/orgs-api) (including [List members](https://neon.com/docs/manage/orgs-api#list-members)).

The **People** page also shows deactivated organization members with a **Deactivated** badge, so admins can review access without opening each member profile.

## Set permissions

Access works in two layers: an organization role sets a member's baseline across every project, and per-project permissions add to it on individual projects. Only Admins can change either one. For the full breakdown of what each level allows, see [User permissions](https://neon.com/docs/manage/user-permissions).

There are four organization roles: **Admin**, **Editor**, **Viewer**, and **Collaborator**. To change someone's role, open the more options menu (⋮) next to their name on the **People** page and choose **Edit member**.

![organization members](https://neon.com/docs/manage/orgs_members_kebab.png)

A few things to keep in mind:

- Changing a role changes a person's baseline on every project at once. To give someone more access on just one project, leave their role alone and [grant a per-project permission](https://neon.com/docs/manage/user-permissions#assign-project-access) instead.
- Per-project permissions are additive, so they can only raise someone's access above their organization role, never lower it.
- You cannot leave the organization if you are the only Admin. Promote another member to Admin before you try to leave the org.

## Require 2FA for organization members

Admins can require two-factor authentication (2FA) for everyone in the organization from **Organization → Settings**. A passkey satisfies this requirement too, so members can enroll in either 2FA or a passkey to comply.

- You can only enable this if your own account already has 2FA or a passkey set up.
- When required 2FA is on, members who don't have 2FA or a passkey enrolled are prompted to set one up when they access the organization.

See [Manage your Neon account](https://neon.com/docs/manage/accounts#two-factor-authentication) for personal 2FA setup steps, or [Passkeys](https://neon.com/docs/manage/accounts#passkeys) for passkey setup steps.

## Give someone access to specific projects only

To give a person access to a few projects instead of the whole organization, add them to the organization with the **Collaborator** role, then grant them a permission on each project they need. A Collaborator starts with no access at all: projects don't appear in their list until you grant one. This is the recommended way to work with contractors and anyone else who should see only part of the organization.

For the steps, see [Assign project access](https://neon.com/docs/manage/user-permissions#assign-project-access).

**Note:** The **Collaborator** organization role is not the same as a legacy project-sharing collaborator, even though the names match. A Collaborator is a member of your organization who you grant per-project permissions to. A project-sharing collaborator is an external Neon account invited to a single project. See [Legacy permissions](https://neon.com/docs/manage/user-permissions#legacy-permissions).

### Project sharing

Project sharing invites an external Neon account by email to a single project, without adding them to your organization. It's still available from a project's **Settings** → **Sharing** page, and if any project in your organization has collaborators, you'll also see them on the organization's **People** page.

Project-sharing collaborators _do not_ have access to the organization itself. They reach their shared projects by selecting **Projects shared with me** in the org switcher. When a project is transferred into an organization, sharing-based access is automatically removed for anyone who is already a member of that organization.

![organization collaborators](https://neon.com/docs/manage/org_collaborators.png)

**Note: Invites not received?**

If invite emails aren't received, they may be in spam or quarantined. Recipients should check these folders and mark Neon emails as safe.

To manage an existing project-sharing collaborator, open the more options menu (⋮) next to their row in the **Collaborators** table:

- **Convert to member**: Admins can turn an external collaborator into a full organization member. Their sharing-based access is removed, and their organization role then determines what they can reach. Set that role on the **People** page.
- **Remove from project**: Revoke the collaborator's access to the shared project.

![collaborators more options menu](https://neon.com/docs/manage/orgs_collaborators_kebab.png)

Project sharing is being deprecated and will be removed in a future release. For new access, use the **Collaborator** role plus per-project permissions instead. For details on sharing itself, see the [Project collaboration guide](https://neon.com/docs/guides/project-collaboration-guide).

## Create and delete projects

Any member except a Collaborator can create projects from the organization's **Projects** page, including Viewers. The organization retains ownership of these projects, not the individual user. Whoever creates a project becomes **Admin** on it.

Deleting a project takes **Admin** access on that project, which any organization Admin also has. It isn't limited to organization Admins: a member granted Admin on a single project can delete that project.

## Manage billing

When you create a new organization, you'll choose a plan for that organization. Each organization manages its own billing and plan.

Billing is Admin-only, and no per-project permission grants it. As the Admin for the organization account:

- You have full access to edit all billing information.
- Promote another member to Admin if you want to delegate billing management; however, all Admins will have the capability to edit billing details.
- Other members can view the **Billing** page, but only Admins can make changes.

For detailed information on pricing and plans, refer to [Neon plans](https://neon.com/docs/introduction/plans).

### Downgrade to Free plan

If downgrading to the Free plan isn't available for your organization, you'll see an error when you try.

To downgrade, your org must:

- Stay within Free plan limits (storage, projects, branches, etc.)

If you need help or think you should be able to downgrade, use the **Request support** option during the downgrade process.

[See Neon plans for details.](https://neon.com/docs/introduction/plans)

## Delete an organization

Only Admins can delete an Organization. Before doing so, make sure all projects within the Organization are removed.

In your Organization's **Settings** page, you'll find the **Delete** section. It will list any actions you need to take before deletion is allowed. For example, if you still have outstanding projects that need to be removed, you'll see:

![delete organization](https://neon.com/docs/manage/orgs_delete.png)

Complete any necessary steps. Once cleared, you can go ahead and delete. This action will permanently remove the organization and cancel its associated billing. _It can't be reversed._

## Rename an organization

Only Admins can rename an organization. Go to the **Settings** page under **General information**. Changing the organization name applies globally; the new name will appear for everyone in the organization.

![organization settings](https://neon.com/docs/manage/orgs_id.png)

--- [Document source](https://neon.com/docs/manage/orgs-project-transfer.md) ---

> Summary: Move Neon projects between organizations without changing credentials or connection strings, via the Console or API. The destination organization's plan must be the same tier or higher than the source.

# Transfer projects

Last updated: 2026-10-09

Move projects between organizations you belong to in the Neon Console or via the Neon API. You can also hand a project to a different Neon account with a claim link.

Transferring a project does not change its credentials or connection string, so connected applications keep working. Billing and usage move to the destination organization, and project limits follow the destination organization's [plan](https://neon.com/docs/introduction/plans).

Before you transfer, review [Limits and requirements](https://neon.com/docs/manage/orgs-project-transfer#limits-and-requirements). In particular, disconnect any project integrations first, and make sure the destination organization's plan is the same tier or higher than the source organization's. Projects can't be transferred into or out of [Vercel-managed organizations](https://neon.com/docs/guides/vercel-managed-integration).

## Ways to transfer

**Console (single)**

1. Open the project's **Settings** page.
2. On the **General** tab, under **Transfer project**, select **Transfer project**.
3. Choose the destination organization.

![transfer single project to another org](https://neon.com/docs/manage/transfer_project.png)

**Alternative: create a claim link**

The steps above transfer a project to one of your own organizations. As an alternative, you can hand a project to a **different Neon account**. On the same **Transfer** page, select **Create claim link** and share the generated link with the recipient. When they sign in and open it, they choose which of their organizations to transfer the project into. The link expires after 24 hours by default.

To automate this flow, see [Claimable database integration](https://neon.com/docs/workflows/claimable-database-integration).

**Console (multiple)**

1. Use the profile menu in the top-right of the console to select the source organization.

2. Open **Settings** > **Transfer projects**.

3. Select the projects to transfer, then click **Next**.

4. Choose the destination organization, then click **Transfer**.

**API**

Transfer projects with a [personal API key](https://neon.com/docs/manage/api-keys#create-a-personal-api-key) that has access to both organizations. Organization API keys are not supported.

`POST /organizations/{source_org_id}/projects/transfer`

```bash
curl --request POST \
     --url 'https://console.neon.tech/api/v2/organizations/{source_org_id}/projects/transfer' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $PERSONAL_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
  "project_ids": [
    "project-id-1",
    "project-id-2"
  ],
  "destination_org_id": "destination-org-id"
}'
```

Where:

- `source_org_id` (in URL path) is the organization where projects currently reside
- `destination_org_id` is the organization receiving the projects
- `project_ids` is an array of up to 400 project IDs to transfer

A `200` response with an empty object (`{}`) means the transfer succeeded. A `406` (plan or capacity) or `422` (active integrations) means it failed; see [Limits and requirements](https://neon.com/docs/manage/orgs-project-transfer#limits-and-requirements) to resolve.

For the full request and response schema, see the [API reference](https://neon.com/docs/reference/api/organizations/transfer-projects-from-org-to-org).

As an alternative, to hand a project to a different Neon account, create a claim link. See [Claimable database integration](https://neon.com/docs/workflows/claimable-database-integration).

## Limits and requirements

- Transfer up to **200** projects at a time in the Console, or **400** via the API.
- Destination organization must have capacity for the projects under its [plan](https://neon.com/docs/introduction/plans) (for example, project count limits).
- Destination organization plan must be the **same tier or higher** than the source organization plan (for example, Launch to Scale works; Scale to Launch does not). This is a plan-level check, independent of the project's settings.
- Requires **Admin** in the source organization, since transferring a project out of an organization is Admin-only. In the destination organization you need any role that can create projects: **Admin**, **Editor**, or **Viewer**. Collaborators can't receive transfers. See [User permissions](https://neon.com/docs/manage/user-permissions).
- Disconnect project integrations before you transfer. Open the project's **Integrations** page and remove any added integrations (for example, GitHub or Vercel). See [Manage integrations](https://neon.com/docs/manage/integrations).
- [Vercel-managed organizations](https://neon.com/docs/guides/vercel-managed-integration) can't be the source or destination of a transfer. This restriction applies to the whole organization, not to individual projects. Removing a project's integrations on its [Integrations](https://neon.com/docs/guides/integrations) page, or disconnecting its database from Vercel, doesn't make the project transferable.
- HIPAA projects can only move to a HIPAA-enabled organization.

If a transfer fails:

- **Plan or capacity** (API `406`): the destination organization has a lower plan than the source, no free project slots, or doesn't allow a project's region. Upgrade the destination organization, free up slots, or choose a different organization.
- **Integrations** (API `422`): one or more projects still have active integrations (for example, GitHub or Vercel). Remove them and retry.

--- [Document source](https://neon.com/docs/manage/platform-maintenance.md) ---

> Summary: Neon platform maintenance covers unscheduled infrastructure updates, resource rebalancing, and critical security patches. These may cause brief compute restarts or temporary latency on queries, API requests, and compute starts. Use this page to monitor upcoming maintenance via the Neon Status page or the Console maintenance indicator. Includes guidance on connection retry logic, timeouts, and pooling strategies for strict SLOs.

# Platform maintenance

Last updated: 2026-07-15

Neon occasionally performs essential **platform maintenance** outside of [scheduled updates](https://neon.com/docs/manage/updates) performed on Neon computes. This means that you may experience brief disruptions from time to time for these important updates.

Platform maintenance may include any of the following:

- Neon infrastructure updates and upgrades (for example, updates to Neon Kubernetes clusters or compute nodes)
- Resource management updates (for example, rebalancing of compute nodes)
- Critical security patches (for example, addressing a zero-day vulnerability)

We strive to avoid disruptions as much as possible, but certain updates may require compute restarts or result in temporary latency for operations like compute starts, queries, or API requests.

**Note:** Whenever possible, we perform platform maintenance outside of normal business hours in affected regions to minimize disruption.

## Where to check for maintenance

For notification of planned platform maintenance, you can monitor or subscribe to the [Neon Status page](https://neonstatus.com/) for your region. To learn more, see [Neon Status](https://neon.com/docs/introduction/status).

If there is ongoing maintenance, you'll see a **Maintenance** indicator at the top of the Neon Console. Clicking on the indicator takes you to the Neon Status page where you can read the maintenance notification.

![Maintenance indicator](https://neon.com/docs/manage/maintenance_indicator.png)

## Handling disruptions and latency during platform maintenance

Most Postgres connection drivers include built-in retry mechanisms that automatically handle short-lived interruptions, so most applications reconnect to a Neon database automatically after a brief disruption.

If your application has strict SLOs (Service Level Objectives) or availability requirements, verify that retries are enabled and that you have tuned connection timeouts, retry intervals, and pooling strategies to tolerate occasional disruptions. For detailed guidance, see:

- [Building resilient applications with Postgres](https://neon.com/guides/building-resilient-applications-with-postgres)
- [Build connection timeout handling into your application](https://neon.com/docs/connect/connection-latency#build-connection-timeout-handling-into-your-application)

If you use the [Neon API](https://neon.com/docs/reference/api) or [SDKs](https://neon.com/docs/reference/sdk) that wrap it, apply the same retry logic to those calls.

--- [Document source](https://neon.com/docs/manage/platform.md) ---

> Summary: The Neon platform overview organizes all database management topics by area: access and collaboration, projects and resources, monitoring and observability, security and compliance, and operations and maintenance. Use this page to find the right sub-topic when you know the management area but not the specific doc.

# Platform overview

Find information about managing all aspects of your database using the Neon platform

Last updated: 2026-10-28

## The Neon platform, in brief

Neon is a full backend platform for apps and agents, not just a database. For an overview of every product, start at the [Neon documentation home](https://neon.com/docs).

- [Postgres](https://neon.com/docs/postgres/overview): Serverless Postgres with branching, autoscaling, scale to zero, and instant restore.
- [Auth](https://neon.com/docs/auth/overview): Managed Better Auth with sign-up, OAuth, and sessions. Users live in your Postgres and branch with it.
- [Data API](https://neon.com/docs/data-api/overview): HTTPS queries with no backend code. Drop-in compatible with Supabase.
- [Object Storage](https://neon.com/docs/storage/overview): S3-compatible object storage that branches with your database.
- [Functions](https://neon.com/docs/compute/functions/overview): Long-running serverless functions on Node.js, deployed alongside your database.
- [AI Gateway](https://neon.com/docs/ai-gateway/overview): One API for frontier and open-source models, built into your Neon project.
- [Realtime](https://neon.com/docs/realtime/overview): Realtime live SQL and reactive DX for building apps and agents.

This page covers the platform's management and operations side: the account, project, and infrastructure tasks you use to run your Neon projects day to day.

## Access & collaboration

Manage your account, your team, and who can access your project's databases.

- [Accounts](https://neon.com/docs/manage/accounts): About Neon account types
- [User permissions](https://neon.com/docs/manage/user-permissions): Manage user permissions and access levels
- [Organizations](https://neon.com/docs/manage/organizations): Build your team in Neon
- [Project collaboration](https://neon.com/docs/guides/project-collaboration-guide): Collaborate on your projects with other users
- [Database access](https://neon.com/docs/manage/database-access): Learn how to manage user access to your databases using roles
- [API keys](https://neon.com/docs/manage/api-keys): Generate and manage API keys
- [Account recovery](https://neon.com/docs/manage/account-recovery): Recover your account and reset your password

## Projects & resources

Learn how to manage all aspects of your Neon projects. These topics cover the basics of setting up your projects through the UI (create, edit, delete) as well as practical guidance and best practices around managing project resources.

- [The object model](https://neon.com/docs/concepts/the-object-model): Learn about the Neon project and all its resources
- [Projects](https://neon.com/docs/manage/projects): Create and manage projects in Neon
- [Branches](https://neon.com/docs/manage/branches): Learn about database branching in Neon
- [Computes](https://neon.com/docs/manage/computes): Configure and optimimze compute resources for your Neon projects
- [Roles](https://neon.com/docs/manage/roles): Manage roles within projects and assign permissions
- [Databases](https://neon.com/docs/manage/databases): Manage your database from the Console, CLI, or API
- [Tables](https://neon.com/docs/guides/tables): Use the Tables page to easily view, edit, and manage your database entries
- [Integrations](https://neon.com/docs/manage/integrations): Manage third-party integrations with your Neon project

## Monitoring & observability

Monitor your Neon projects to track system health and performance.

- [Overview](https://neon.com/docs/introduction/monitoring): Learn about monitoring resources and metrics in Neon
- [Monitoring dashboard](https://neon.com/docs/introduction/monitoring-page): Dashboard graphs for monitoring system and database metrics
- [System operations](https://neon.com/docs/manage/operations): Track actions taken by the control plane on project resources
- [Active queries](https://neon.com/docs/introduction/monitor-active-queries): View and analyze running queries in your database
- [Query performance](https://neon.com/docs/introduction/monitor-query-performance): View and analyze query performance for your Neon database
- [Datadog](https://neon.com/docs/guides/datadog): Monitor your database with Datadog
- [Grafana Cloud](https://neon.com/docs/guides/grafana-cloud): Monitor your database with Grafana Cloud
- [OpenTelemetry](https://neon.com/docs/guides/opentelemetry): Monitor your database with OpenTelemetry
- [Metrics and logs reference](https://neon.com/docs/reference/metrics-logs): Metrics and logs reference for monitoring
- [Better Stack](https://neon.com/guides/betterstack-otel-neon): Monitor Neon with Better Stack using OpenTelemetry integration
- [New Relic](https://neon.com/guides/newrelic-otel-neon): Monitor Neon with New Relic using OpenTelemetry integration
- [pgAdmin](https://neon.com/docs/introduction/monitor-pgadmin): Monitor your database with pgAdmin
- [PgHero](https://neon.com/docs/introduction/monitor-pghero): Monitor your database with PgHero

## Security & compliance

Learn how Neon secures your projects and data, and explore the security features available for you to use.

- [Overview](https://neon.com/docs/security/security-overview): Overview of Neon's security features
- [Security reporting](https://neon.com/docs/security/security-reporting): Report security vulnerabilities and incidents
- [Compliance](https://neon.com/docs/security/compliance): Learn how Neon complies with various standards
- [HIPAA](https://neon.com/docs/security/hipaa): HIPAA compliance with Neon
- [Acceptable Use Policy](https://neon.com/docs/security/acceptable-use-policy): Read about Neon's acceptable use policies
- [AI use in Neon](https://neon.com/docs/security/ai-use-in-neon): Learn about how AI is used in Neon

## Operations & maintenance

- [Production checklist](https://neon.com/docs/get-started/production-checklist): Guidelines to optimize price, performance, and reliability
- [Backups](https://neon.com/docs/manage/backups): An overview of backup strategies for Lakebase Postgres
- [Backup with pg_dump](https://neon.com/docs/manage/backup-pg-dump): Learn how to create a backup of your Neon database using pg_dump
- [Automate pg_dump backups](https://neon.com/docs/manage/backup-pg-dump-automate): Automate backups of your Neon database to S3 with pg_dump and GitHub Actions
- [Updates overview](https://neon.com/docs/manage/maintenance-updates-overview): Overview of Neon platform maintenance and compute updates
- [Platform maintenance](https://neon.com/docs/manage/platform-maintenance): Find out how Neon manages essential platform maintenance and critical security updates
- [Updates](https://neon.com/docs/manage/updates): Learn about updates for Neon computes and Postgres
- [Regions](https://neon.com/docs/introduction/regions): Learn about Neon regions and availability

--- [Document source](https://neon.com/docs/manage/project-permissions-get-started.md) ---

> Summary: A worked example that takes a four-person team from everyone-sees-everything to a proper access structure. Set each person's organization role, grant per-project permissions where someone needs more than their baseline, and verify the result on the Project permissions page. Includes the same setup through the Neon API for orchestrators and agents.

# Get started with project permissions

Scope each person and agent to the projects they need, in about five minutes

Last updated: 2026-11-01

By default, everyone you invite to your Neon organization can reach every project in it. That's fine until it isn't: a contractor you brought in for one reporting project can open your production database, and an agent you gave a credential to can modify any project instead of the one you meant. Project permissions fix that, so a mistake or a leaked credential affects one project rather than everything you have.

This guide sets that up for a small team. It takes about five minutes, and you finish with each person and agent holding exactly the access their work needs.

**What you will learn:**

- How organization roles and per-project permissions combine
- Which role to give a teammate, a contractor, and an agent
- How to grant access on a single project
- How to verify who can reach what

**Related topics**

- [User permissions reference](https://neon.com/docs/manage/user-permissions)
- [Organizations](https://neon.com/docs/manage/organizations)
- [Manage API keys](https://neon.com/docs/manage/api-keys)

The example uses a four-person team and three projects, but the same approach scales to any size.

## Before you start

You need less than you might expect:

- **An organization.** You already have one. Neon creates a free organization for your first project when you sign up, and all projects live inside an organization.
- **The Admin role.** You're an Admin of the organization you signed up with, so you can invite people and grant permissions right away.
- **The email addresses** your teammates use, or will use, for their Neon accounts.

**Note: Already sharing projects?**

If you currently use [project collaboration](https://neon.com/docs/guides/project-collaboration-guide) to share a project, your collaborators became **Editors** on the projects shared with them. That works, but it gives them edit access to those projects and nothing more granular. Follow this guide to move them onto organization roles plus per-project permissions, which is the model project sharing is being replaced by.

## The scenario

A four-person team runs three Neon projects:

| Project           | What it's for                             |
| ----------------- | ----------------------------------------- |
| `acme-production` | The live customer-facing database         |
| `acme-staging`    | Pre-release testing                       |
| `acme-analytics`  | Reporting, built by an outside contractor |

The team:

- **You** run the organization and own billing.
- **Alex** is a backend engineer who works across production and staging every day.
- **Dana** is a designer who needs to look things up but shouldn't be changing databases.
- **Sam** is a contractor building the analytics project, and shouldn't see the customer data in production or staging.

Without per-project permissions, everyone you invite gets the same access on all three projects, so Sam would be able to open `acme-production`. Here's how to avoid that.

## Decide the access each person needs

Work out the baseline first, then the exceptions. The baseline is the organization role: pick the **lowest** role that covers most of a person's work, because per-project permissions can only add to it.

| Person | Organization role | Per-project grant          | What they end up with                                       |
| ------ | ----------------- | -------------------------- | ----------------------------------------------------------- |
| You    | Admin             | None needed                | Full control of the organization and all three projects     |
| Alex   | Editor            | None needed                | Edit all three projects, but can't delete or transfer       |
| Dana   | Viewer            | Editor on `acme-staging`   | Read-only everywhere, plus full edit on staging             |
| Sam    | Collaborator      | Editor on `acme-analytics` | Only `acme-analytics`. Production and staging are invisible |

Two things make this work:

- **Collaborator is closed by default.** Sam sees nothing until you grant it. `acme-production` doesn't appear in their project list, and Neon responds as though it doesn't exist. That's what makes Collaborator the right role for contractors, external developers, and agents.
- **Grants only add.** Dana is a Viewer across the organization, and the Editor grant raises that to full edit on `acme-staging` alone.

**Important: You can't subtract access**

A per-project permission can only raise someone above their organization-role baseline. There's no way to give Alex Editor everywhere but block them from one project. If someone should reach only specific projects, make them a **Collaborator** and grant each project explicitly, the way Sam is set up above. See [Notes and limitations](https://neon.com/docs/manage/user-permissions#notes-and-limitations).

## Set it up

## Invite each person with their baseline role

In the Neon Console, open your organization's **People** page and select **Invite member**. Enter the email address and choose the organization role from the table above: **Editor** for Alex, **Viewer** for Dana, **Collaborator** for Sam.

To change someone already in the organization, open the more options menu (⋮) next to their name and choose **Edit member**.

Invited people get an email, and the organization appears in their [org switcher](https://neon.com/docs/manage/orgs-manage#switch-organizations) once they accept. For what each role allows, see [Organization roles](https://neon.com/docs/manage/user-permissions#organization-roles).

![Invite members dialog with a role dropdown for each invitee](https://neon.com/docs/manage/project-permissions-get-started/invite-members.png)

**Tip: Adding a whole team at once**

If your teammates all use email addresses at a domain you control, [auto-join by domain](https://neon.com/docs/manage/orgs-add-members-by-domain) adds them automatically when they sign up or log in. They join as **Editors**, so change the role afterwards for anyone who needs less.

## Grant edit access on staging

Dana is a Viewer, which is right for most of the organization but too restrictive on `acme-staging`.

Open `acme-staging`, go to **Settings** → **Project permissions**, and select **Grant permission**. Choose **Editor**, pick Dana, and confirm.

![Grant project permission dialog with Editor selected and Dana chosen, showing her inherited Viewer access](https://neon.com/docs/manage/project-permissions-get-started/grant-permission.png)

Dana can now get connection strings and run SQL on staging, while staying read-only on production and analytics.

## Grant access to the analytics project

Sam is a Collaborator, so right now they can't see any project at all. Open `acme-analytics`, go to **Settings** → **Project permissions**, select **Grant permission**, choose **Editor**, and pick Sam.

That single grant is their entire access to your organization. Nothing else needs locking down, because Collaborators start with nothing.

## Verify what everyone can reach

On each project's **Project permissions** page, review the list of people who can reach it. Each person is tagged **Inherited** or **Explicit**:

- **Inherited** means the access comes from their organization role. You'll always appear here as Admin.
- **Explicit** means you granted it on this project. Dana on staging and Sam on analytics show up this way.

Check `acme-production` in particular: you and Alex have access, and neither Dana nor Sam can edit it. Dana appears as an inherited Viewer, and Sam has no access at all.

To change or revoke an explicit grant, use the more options menu (⋮) next to the person's name. Removing a grant drops them back to their organization role's baseline.

For a definitive answer rather than a visual check, ask the API who can reach a project. It returns each person's `effective_project_permission`, which is the access that actually applies after both layers combine:

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/$PROJECT_ID/members' \
     --header 'authorization: Bearer $ORG_API_KEY' | jq '.project_members[] | {email, org_role, effective_project_permission, grant_source}'
```

Run it against `acme-production` and you should see Alex with `EDITOR` from `org_role_default`. Sam still appears in the list as an organization member, but with `effective_project_permission` of `null` and `grant_source` of `unassigned`, which is how the API reports someone who has no access to the project. `grant_source` tells you whether the access came from someone's organization role or an explicit grant.

## The result

Your team now has an access structure rather than a single shared level:

- You keep full control, including billing.
- Alex works across every project without being able to delete or transfer one.
- Dana can look at anything and change only staging.
- Sam works on analytics and cannot see customer data.

When the contract ends, remove Sam from the organization on the **People** page, or revoke the grant on `acme-analytics` to leave them in the organization with no project access.

## Scoping access for agents

An agent is the case this model is built for. Give it the **Collaborator** role and grant it one project, and a misbehaving or compromised agent can reach only that project.

Pair the grant with a [project-scoped API key](https://neon.com/docs/cli/api-keys), so the credential itself is bounded too. A project-scoped key can't create projects, can't mint more keys, and can't see any other project:

```bash
neon api-keys create --name analytics-agent --project-id $PROJECT_ID
```

<details>

<summary>**Do the whole setup through the API**</summary>

If you provision projects programmatically, the same two layers are available through the [Neon API](https://neon.com/docs/reference/api). These calls need an [organization API key](https://neon.com/docs/manage/api-keys) with the Admin role. Roles are sent lowercase and returned uppercase.

Grant a member Editor on one project:

```bash
curl --request PUT \
     --url 'https://console.neon.tech/api/v2/projects/$PROJECT_ID/members/$MEMBER_ID/role' \
     --header 'authorization: Bearer $ORG_API_KEY' \
     --header 'content-type: application/json' \
     --data '{"role": "editor"}'
```

Get each `member_id` from the [List project members](https://neon.com/docs/manage/user-permissions#list-project-members) response. To remove an explicit grant and drop someone back to their organization-role baseline, send `DELETE` to the same route. See [Manage project access with the API](https://neon.com/docs/manage/user-permissions#manage-project-access-with-the-api) for full request and response details.

The CLI doesn't have a dedicated command for this yet, but you can call the same routes through the [`neon api`](https://neon.com/docs/cli/api) passthrough:

```bash
neon api /projects/$PROJECT_ID/members/$MEMBER_ID/role -X PUT -F role=editor
```

</details>

## Next steps

- [User permissions](https://neon.com/docs/manage/user-permissions) for the complete role and permission matrices, including exactly which actions each level allows.
- [Manage organizations](https://neon.com/docs/manage/orgs-manage) for inviting members, changing roles, and organization settings.
- [Add members by domain](https://neon.com/docs/manage/orgs-add-members-by-domain) to auto-provision teammates by verified email domain.
- [Manage API keys](https://neon.com/docs/manage/api-keys) for account, organization, and project-scoped keys.

--- [Document source](https://neon.com/docs/manage/projects.md) ---

> Summary: Postgres storage is unlimited on paid plans: there's no hard per-branch size limit and project storage grows with your usage. A Neon project is the top-level workspace that groups branches, databases, roles, and computes. This page covers the full project lifecycle: create, configure, and delete, via the Console or API. Use it when you need to set project-level defaults such as compute autoscaling, history window for instant restore and Time Travel, IP Allow rules, logical replication, or project access. Deleted projects can be recovered within a 7-day window using the Console, CLI, or API.

# Manage projects

Learn how to manage Neon projects from the Neon Console or the Neon API.

Last updated: 2026-10-23

In Neon, the project is your main workspace. Within a project, you create branches for different workflows, like environments, features, or previews. Each branch contains its own databases, roles, computes, and replicas. Your [Neon Plan](https://neon.com/docs/introduction/plans) determines how many projects you can create and the resource limits within those projects.

## Default resources

When you add a new project, Neon creates the following resources by default:

- A root branch is created as your project's default branch. In the Console, this branch is named `production`; via API/CLI, it's named `main`. You can create child branches for development, testing, staging, and other purposes. For more information, see [Manage branches](https://neon.com/docs/manage/branches).
- A single primary read-write compute. This is the compute associated with the branch. For more information, see [Manage computes](https://neon.com/docs/manage/computes).
- A Postgres database that resides on the project's default branch. If you did not specify your own database name when creating the project, the database created is named `neondb`.
- A Postgres role that is named for your database. For example, if your database is named `neondb`, the project is created with a default role named `neondb_owner`.
- Postgres storage depends on your [Neon plan](https://neon.com/docs/introduction/plans). **On paid plans (Launch and Scale), there's no hard per-branch size limit**; your storage grows with your usage, and you pay only for the storage you use. The Free plan includes 1 GB of Postgres storage per project, shared across all branches. This is separate from [Object Storage](https://neon.com/docs/storage/overview), which has its own allowance.

## Create a project

The following instructions describe how to create additional Neon projects. If you are creating your very first Neon project, refer to the instructions in [Playing with Neon](https://neon.com/docs/get-started/signing-up).

You can create a project from the Console or the Neon CLI. To create one with the API, see [Create a project with the API](https://neon.com/docs/manage/projects#create-a-project-with-the-api).

**Console**

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Click **New Project**.
3. Enter a **Project name** and choose a **Region** (the cloud provider is part of the region). Project names are limited to 64 characters.
4. Under **Services**, choose what to enable. **Postgres database** is on by default (expand it to set the **Postgres version**). Where the selected region supports them, you can also enable **Object storage**, **Functions**, **AI gateway**, and **Neon Auth**. Services that aren't available in the selected region aren't shown.
5. Click **Create project**.

After creating a project, you are directed to the project's **Overview** page.

**CLI**

Install the CLI with `npm i -g neon` and run `neon login` to log in. Then create a project with `neon projects create`:

```bash
neon projects create --name myproject --region-id aws-us-east-2
```

The output includes the new project ID and the default connection string. For all options, see [Neon CLI — projects](https://neon.com/docs/cli/projects).

## View projects

To view your projects:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. From the profile menu in the top-right of the console, select your organization.
3. The **Projects** page lists your projects, including any projects that have been shared with you.

## Project settings

Once you open a project, you use the **Settings** page to manage the project and configure its defaults. Settings are grouped into tabs, and project-wide settings are labeled **Applies to all branches** to distinguish them from branch-level settings.

The **Settings** page includes these tabs:

- **General**: View the project and branch IDs, rename the project or branch, protect a branch, set branch expiration, change the project's default branch, and transfer or delete the project.
- **Postgres**: Configure project-wide database defaults (all labeled **Applies to all branches**): compute defaults (size and scale to zero) for new computes, the history window for [instant restore](https://neon.com/docs/introduction/branch-restore) and [Time Travel](https://neon.com/docs/guides/time-travel-assist), your [update schedule](https://neon.com/docs/manage/updates), [logical replication](https://neon.com/docs/guides/logical-replication-guide), and the [Data API](https://neon.com/docs/data-api/overview).
- **Networking**: Control **Public internet access** (allow any IP address or restrict to an [IP allowlist](https://neon.com/docs/introduction/ip-allow)) and **VPC access** ([Private Networking](https://neon.com/docs/guides/neon-private-networking)).
- **Credentials**: Manage branch-scoped, per-service credentials, used as S3 access keys for [Object Storage](https://neon.com/docs/storage/overview) and as Bearer API tokens for the [AI Gateway](https://neon.com/docs/ai-gateway/overview).
- **Auth**: Configure [Managed Better Auth](https://neon.com/docs/auth/overview): application info and URLs, trusted redirect domains, email sign-up and sign-in, OAuth providers, the email provider, and webhooks.
- **Functions**: Manage [custom domains](https://neon.com/docs/compute/functions/custom-domains) for your [Neon Functions](https://neon.com/docs/compute/functions/overview).
- **HIPAA compliance**: Enable [HIPAA compliance](https://neon.com/docs/security/hipaa) for the project.
- **Sharing** and **Project permissions**: Invite external collaborators and grant organization members per-project access. See [User permissions](https://neon.com/docs/manage/user-permissions).

### General project settings

On the **General** page, you are permitted to change the name of your project or copy the project ID. The project ID is permanent and cannot be changed.

### Change your project's default compute settings

You can change your project's default compute settings on the **Postgres** tab, under **Compute defaults**. These settings determine the compute resources allocated to any new branches or read replicas you create.

**Important:** Changes to default compute settings only affect **newly created computes**. Existing computes, including those on your primary branch and read replicas, will not be automatically updated. To change settings for existing computes, you need to update them individually through the **Branches** page.

A Compute Unit (CU) represents approximately 4 GB of RAM, along with associated CPU and local SSD resources. New branches inherit compute settings from your first branch, but you can change these defaults to:

- Set smaller compute sizes for preview deployments and development branches
- Standardize settings across read replicas
- Optimize resource usage and costs for non-production workloads

Neon supports two compute configurations:

- **Fixed size:** Select a fixed compute size ranging from .25 CUs to 56 CUs
- **Autoscaling:** Specify minimum and maximum compute sizes (from .25 CU to 16 CUs) to automatically scale based on workload. Note: The maximum permitted autoscaling range is 8 CU, meaning the difference between max and min cannot exceed 8 CU (for example, if min = 1 CU, max can be at most 9 CU). For more information, see [Autoscaling](https://neon.com/docs/introduction/autoscaling)

### Configure the history window for instant restore

By default, Neon retains a history of changes for all branches in your project, enabling features like:

- [Instant restore](https://neon.com/docs/introduction/branch-restore) for recovering lost data
- [Time Travel](https://neon.com/docs/guides/time-travel-assist) queries for investigating data issues

For plan limits, billing, and how retention works, see [History window](https://neon.com/docs/introduction/history-window).

If you extend the history window, you expand how far back **instant restore** and Time Travel can go, but you also increase **History** usage (change history billed for instant restore) on your project.

Also note that adjusting the history window affects _all_ branches in your project.

To configure the history window:

1. Select a project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**.
4. Under **History window**, use the slider to choose how long to keep change history.
5. Click **Save**.

### Schedule updates for your project

To keep your Neon computes and Postgres instances up to date, Neon automatically applies scheduled updates that include Postgres minor version upgrades, security patches, and new features. Updates are applied to the computes within your project. They require a quick compute restart, take only a few seconds, and typically occur weekly.

On the Free plan, updates are automatically scheduled. On paid plans, you can set a preferred day and time for updates. Restarts occur within your selected time window and take only a few seconds.

To set your project's update schedule or view currently scheduled updates:

1. Go to **Settings** > **Postgres** and find **Updates**.
2. Choose a day of the week and an hour. Updates will occur within this time window and take only a few seconds.

For more information, see [Updates](https://neon.com/docs/manage/updates).

### Give someone access to a project

How you grant access depends on whether the person is already in your organization:

- **Organization members**: Grant them a per-project permission (**Viewer**, **Editor**, or **Admin**) from the project's **Settings** → **Project permissions** page. This is also how you give a member more access on one project than their organization role provides. See [Assign project access](https://neon.com/docs/manage/user-permissions#assign-project-access).
- **People outside your organization**: Invite them as a collaborator, as described below.

#### Invite collaborators to a project

Neon's project collaboration feature allows you to invite external Neon accounts to collaborate on a Neon project.

**Note:** Project sharing is being deprecated and will be removed in a future release. To give a contractor or other limited-access user access to specific projects, add them to the organization as a **Collaborator** and grant per-project permissions instead. See [User permissions](https://neon.com/docs/manage/user-permissions).

Organization members can't be added as collaborators on organization-owned projects. Grant them a per-project permission instead.

To invite collaborators to a Neon project:

1. In the Neon Console, select a project.
2. Select **Settings**.
3. Select **Sharing**.
4. Select **Invite** and enter the email address of the account you want to collaborate with.
5. Click **Invite**.

The email you specify is added to the list of **Collaborators**. The Neon account associated with that email address is granted full access to the project, with the exception of privileges required to delete the project. This account can also invite other Neon users to the project. When that user logs in to Neon, the project they were invited to is listed on their **Projects** page under **Shared with you**.

The costs associated with projects being collaborated on are charged to the Neon account that owns the project. For example, if you invite another Neon user account to a project you own, any usage incurred by that user within your project is billed to your Neon account, not theirs.

For additional information, refer to our [Project collaboration guide](https://neon.com/docs/guides/project-collaboration-guide).

### Configure IP Allow

The IP Allow feature provides an added layer of security for your data, restricting access to the branch where your database resides to only those IP addresses that you specify. In Neon, the IP allowlist is applied to all branches by default.

Optionally, you can allow unrestricted access to your project's non-protected branches. For instance, you might want to restrict access to protected branches to a handful of trusted IPs while allowing unrestricted access to your development branches.

By default, Neon allows IP addresses from `0.0.0.0`, which means that Neon accepts connections from any IP address. Once you configure IP Allow by adding IP addresses or ranges, only those IP addresses will be allowed to access Neon.

**Note:** Neon projects provisioned on AWS support both [IPv4](https://en.wikipedia.org/wiki/Internet_Protocol_version_4) and [IPv6](https://en.wikipedia.org/wiki/IPv6) addresses. Neon project provisioned on Azure currently on support IPv4.

**Neon Console**

To configure an allowlist:

1. Select a project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Networking**.
4. Under **Public internet access**, select **Only addresses on the allowlist**, then specify the IP addresses you want to permit. Separate multiple entries with commas.
5. Optionally, under **Restricted branches**, select **Protected branches only** to enforce the allowlist only on branches you've designated as protected. Every other branch keeps accepting any address.
6. Click **Save changes**.

**CLI**

The [Neon CLI ip-allow command](https://neon.com/docs/cli/ip-allow) supports IP Allow configuration. For example, the following `add` command adds IP addresses to the allowlist for an existing Neon project. Multiple entries are separated by a space. No delimiter is required.

```bash
neon ip-allow add 203.0.113.0 203.0.113.1
ID              wispy-haze-123456
Name            wispy-haze-123456
IP Addresses    203.0.113.0, 203.0.113.1
Protected Only  false
```

To apply an IP allowlist to protected branches only, you can use the `--protected-only` option:

```bash
neon ip-allow add 203.0.113.1 --protected-only
```

To reverse that setting, use `--protected-only false`.

```bash
neon ip-allow add 203.0.113.1 --protected-only false
```

**API**

The [Create project](https://neon.com/docs/reference/api/projects/create-project) and [Update project](https://neon.com/docs/reference/api/projects/update-project) methods support **IP Allow** configuration. For example, the following API call configures **IP Allow** for an existing Neon project. Separate multiple entries with commas. Each entry must be quoted. You can set the `"protected_branches_only` option to `true` to apply the allowlist to protected branches only, or `false` to apply it to all branches in your Neon project.

```bash
curl -X PATCH \
     https://console.neon.tech/api/v2/projects/falling-salad-31638542 \
     -H 'accept: application/json' \
     -H 'authorization: Bearer $NEON_API_KEY' \
     -H 'content-type: application/json' \
     -d '
{
  "project": {
    "settings": {
      "allowed_ips": {
        "protected_branches_only": true,
        "ips": [
          "203.0.113.0", "203.0.113.1"
        ]
      }
    }
  }
}
' | jq
```

#### How to specify IP addresses

You can define an allowlist with individual IP addresses, IP ranges, or [CIDR notation](https://neon.com/docs/reference/glossary#cidr-notation). A combination of these options is also permitted. Multiple entries, whether they are the same or of different types, must be separated by a comma. Whitespace is ignored.

- **Add individual IP addresses**: You can add individual IP addresses that you want to allow. This is useful for granting access to specific users or devices. This example represents a single IP address:

  ```text
  192.0.2.1
  ```

- **Define IP ranges**: For broader access control, you can define IP ranges. This is useful for allowing access from a company network or a range of known IPs. This example range includes all IP addresses from `198.51.100.20` to `198.51.100.50`:

  ```text
  198.51.100.20-198.51.100.50
  ```

- **Use CIDR notation**: For more advanced control, you can use [CIDR (Classless Inter-Domain Routing) notation](https://neon.com/docs/reference/glossary#cidr-notation). This is a compact way of defining a range of IPs and is useful for larger networks or subnets. Using CIDR notation can be advantageous when managing access to branches with numerous potential users, such as in a large development team or a company-wide network.

  This CIDR notation example represents all 256 IP addresses from `203.0.113.0` to `203.0.113.255`.

  ```text
  203.0.113.0/24
  ```

- **Use IPv6 addresses**: Neon projects provisioned on AWS also support specifying IPv6 addresses. For example:

  **Note:** IPv6 is not yet supported for projects provisioned on Azure.

  ```text
  2001:DB8:5432::/48
  ```

A combined example using all three options above, specified as a comma-separated list, would appear similar to the following:

```text
192.0.2.1, 198.51.100.20-198.51.100.50, 203.0.113.0/24, 2001:DB8:5432::/48
```

This list combines individual IP addresses, a range of IP addresses, a CIDR block, and an IPv6 address. It illustrates how different types of IP specifications can be used together in a single allowlist configuration, offering a flexible approach to access control.

#### Update an IP Allow configuration

You can update your IP Allow configuration via the Neon Console or API as described in [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow). Replace the current configuration with the new configuration. For example, if your IP Allow configuration currently allows access from IP address `192.0.2.1`, and you want to extend access to IP address `192.0.2.2`, specify both addresses in your new configuration: `192.0.2.1, 192.0.2.2`. You cannot append values to an existing configuration. You can only replace an existing configuration with a new one.

The Neon CLI provides an `ip-allow` command with `add`, `reset`, and `remove` options that you can use to update your IP Allow configuration. For instructions, refer to [Neon CLI commands — ip-allow](https://neon.com/docs/cli/ip-allow).

#### Remove an IP Allow configuration

To remove an IP configuration entirely to go back to the default "no IP restrictions" (`0.0.0.0`) configuration:

**Neon Console**

1. Select a project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Networking**.
4. Under **Public internet access**, select **Any IP address**.
5. Click **Save changes**.

**CLI**

The [Neon CLI ip-allow command](https://neon.com/docs/cli/ip-allow) supports removing an IP Allow configuration. To do so, specify `--ip-allow reset` without specifying any IP address values:

```bash
neon ip-allow reset
```

**API**

Specify the `ips` option with an empty string. If applicable, also include `"protected_branches_only": false`.

```bash
curl -X PATCH \
     https://console.neon.tech/api/v2/projects/falling-salad-31638542 \
     -H 'accept: application/json' \
     -H 'authorization: Bearer $NEON_API_KEY' \
     -H 'content-type: application/json' \
     -d '
{
  "project": {
    "settings": {
      "allowed_ips": {
        "protected_branches_only": false,
        "ips": []
      }
    }
  }
}
'
```

### Enable the Data API

The Data API turns your database tables into a REST API, making it easy to query your data from client applications. When you enable the Data API, it automatically creates `authenticated` and `anonymous` roles and sets up the necessary permissions for secure client-side access.

For setup instructions and examples, see the [Data API documentation](https://neon.com/docs/data-api/get-started).

### Enable logical replication

Logical replication lets you replicate data changes from Neon to external data services and platforms, including data warehouses, analytical database services, messaging platforms, event-streaming platforms, and external Postgres databases.

**Important:** Enabling logical replication changes the PostgreSQL `wal_level` setting from `replica` to `logical` for all databases in your Neon project. This allows Postgres to record the row-level WAL detail required for logical decoding. Once changed, it cannot be reverted. Enabling logical replication also restarts all computes, so active connections will be dropped and have to reconnect.

**Console**

1. Select your project in the Neon Console.
2. Select **Settings** in the sidebar.
3. Select **Postgres**, then find **Logical replication**.
4. Click **Enable** to enable logical replication.

**CLI**

Use [`neon projects update`](https://neon.com/docs/cli/projects#update) with the `--enable-logical-replication` flag. Because this can't be undone, add `--yes` to skip the confirmation prompt. Replace `$PROJECT_ID` with your project ID.

```bash
neon projects update $PROJECT_ID --enable-logical-replication --yes
```

**API**

Use the [Update project](https://neon.com/docs/reference/api/projects/update-project) endpoint to enable logical replication programmatically. Replace `$PROJECT_ID` with your project ID.

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/$PROJECT_ID' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "project": {
    "settings": {
      "enable_logical_replication": true
    }
  }
}'
```

You can verify that logical replication is enabled by running the following query:

```sql
SHOW wal_level;
wal_level
-----------
logical
```

After enabling logical replication, the next steps involve creating publications on your replication source database in Neon and configuring subscriptions on the destination system or service. To get started, refer to our [logical replication guides](https://neon.com/docs/guides/logical-replication-guide).

### Delete a project

Deleting a project also deletes any computes, branches, databases, and roles that belong to the project. You can recover the project within seven days. After the recovery period ends, deletion is permanent.

Deleting a project requires **Admin** access on that project, which every organization Admin has. A member granted Admin on a single project can delete that project. See [Per-project permissions](https://neon.com/docs/manage/user-permissions#per-project-permissions).

To delete a project:

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select the project that you want to delete.
3. Select **Settings**.
4. On the **General** tab, under **Delete project**, select **Delete project**.

**Note:** Deleting a project doesn't release its [custom domains](https://neon.com/docs/compute/functions/custom-domains#delete-a-custom-domain). Delete any domains you want to reuse before you delete the project.

**Note:** For HIPAA-compliant projects, see [HIPAA Compliance](https://neon.com/docs/security/hipaa#delete-a-hipaa-compliant-project) before deleting a project—for example, to export audit logs you may need.

**Important:** If you are any of Neon's paid plans, deleting all your Neon projects won't stop monthly billing. To avoid charges, you also need to downgrade to the Free plan. You can do so from the [Billing](https://console.neon.tech/app/billing#change_plan) page in the Neon Console.

**Note:** Deleted projects can be recovered within the deletion recovery period (7 days) from the Console, CLI, or API. For details, see [Recover a deleted project](https://neon.com/docs/manage/projects#recover-a-deleted-project).

## Manage projects with the Neon API

Project actions performed in the Neon Console can also be performed using the Neon API. The following examples demonstrate how to create, view, and delete projects using the Neon API. For other project-related API methods, refer to the [Neon API Reference](https://neon.com/docs/reference/api).

**Note:** The API examples that follow may not show all of the user-configurable request body attributes that are available to you. To view all attributes for a particular method, refer to method's request body schema in the [Neon API Reference](https://neon.com/docs/reference/api).

The `jq` option specified in each example is an optional third-party tool that formats the `JSON` response, making it easier to read. For information about this utility, see [jq](https://stedolan.github.io/jq/).

### Prerequisites

A Neon API request requires an API key. For information about obtaining an API key, see [Create an API key](https://neon.com/docs/manage/api-keys#create-an-api-key). In the cURL examples shown below, `$NEON_API_KEY` is specified in place of an actual API key, which you must provide when making a Neon API request.

**Note:** To learn more about the types of API keys you can create — personal, organization, or project-scoped — see [Manage API Keys](https://neon.com/docs/manage/api-keys).

### Create a project with the API

The following Neon API method creates a project. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/projects/create-project).

```http
POST /projects
```

The API method appears as follows when specified in a cURL command. The `myproject` name value is a user-specified name for the project.

```bash
curl 'https://console.neon.tech/api/v2/projects' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "project": {
    "name": "myproject"
  }
}' | jq
```

The response includes information about the role, the database, the default branch, and the primary read-write compute that is created with the project.

<details>

<summary>Response body</summary>

For attribute definitions, find the [Create project](https://neon.com/docs/reference/api/projects/create-project) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "project": {
    "data_storage_bytes_hour": 0,
    "data_transfer_bytes": 0,
    "written_data_bytes": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "cpu_used_sec": 0,
    "id": "ep-cool-darkness-123456",
    "platform_id": "aws",
    "region_id": "aws-us-east-1",
    "name": "myproject",
    "provisioner": "k8s-neonvm",
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 0.25,
      "suspend_timeout_seconds": 0
    },
    "settings": {
      "allowed_ips": {
        "ips": [],
        "protected_branches_only": false
      },
      "enable_logical_replication": false,
      "maintenance_window": {
        "weekdays": [7],
        "start_time": "06:00",
        "end_time": "07:00"
      },
      "block_public_connections": false,
      "block_vpc_connections": false,
      "hipaa": false
    },
    "pg_version": 17,
    "proxy_host": "c-2.us-east-1.aws.neon.tech",
    "branch_logical_size_limit": 512,
    "branch_logical_size_limit_bytes": 536870912,
    "store_passwords": true,
    "creation_source": "console",
    "history_retention_seconds": 86400,
    "created_at": "2026-08-04T05:15:41Z",
    "updated_at": "2026-08-04T05:15:41Z",
    "consumption_period_start": "0001-01-01T00:00:00Z",
    "consumption_period_end": "0001-01-01T00:00:00Z",
    "owner_id": "91cbdacd-06c2-49f5-bacf-78b9463c81ca"
  },
  "connection_uris": [
    {
      "connection_uri": "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.c-2.us-east-1.aws.neon.tech/dbname?sslmode=require&channel_binding=require",
      "connection_parameters": {
        "database": "dbname",
        "password": "AbC123dEf",
        "role": "alex",
        "host": "ep-cool-darkness-123456.c-2.us-east-1.aws.neon.tech",
        "pooler_host": "ep-cool-darkness-123456-pooler.c-2.us-east-1.aws.neon.tech"
      }
    }
  ],
  "roles": [
    {
      "branch_id": "br-gentle-salad-123456",
      "name": "neondb_owner",
      "password": "npg_Se0ECYqaJ5jA",
      "protected": false,
      "created_at": "2026-08-04T05:15:41Z",
      "updated_at": "2026-08-04T05:15:41Z"
    }
  ],
  "databases": [
    {
      "id": 5140981,
      "branch_id": "br-gentle-salad-123456",
      "name": "neondb",
      "owner_name": "neondb_owner",
      "created_at": "2026-08-04T05:15:41Z",
      "updated_at": "2026-08-04T05:15:41Z"
    }
  ],
  "operations": [
    {
      "id": "cacca1d4-ad0e-46dc-ae82-886ffb96889d",
      "project_id": "ep-cool-darkness-123456",
      "branch_id": "br-gentle-salad-123456",
      "action": "create_timeline",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T05:15:41Z",
      "updated_at": "2026-08-04T05:15:41Z",
      "total_duration_ms": 0
    },
    {
      "id": "1df43d11-5c07-4de1-9440-ac09d305fdf3",
      "project_id": "ep-cool-darkness-123456",
      "branch_id": "br-gentle-salad-123456",
      "endpoint_id": "ep-cool-darkness-123456",
      "action": "start_compute",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2026-08-04T05:15:41Z",
      "updated_at": "2026-08-04T05:15:41Z",
      "total_duration_ms": 0
    }
  ],
  "branch": {
    "id": "br-gentle-salad-123456",
    "project_id": "ep-cool-darkness-123456",
    "name": "main",
    "current_state": "init",
    "pending_state": "ready",
    "state_changed_at": "2026-08-04T05:15:41Z",
    "creation_source": "console",
    "primary": true,
    "default": true,
    "protected": false,
    "cpu_used_sec": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "written_data_bytes": 0,
    "data_transfer_bytes": 0,
    "created_at": "2026-08-04T05:15:41Z",
    "updated_at": "2026-08-04T05:15:41Z",
    "init_source": "parent-data"
  },
  "endpoints": [
    {
      "host": "ep-cool-darkness-123456.c-2.us-east-1.aws.neon.tech",
      "id": "ep-cool-darkness-123456",
      "project_id": "ep-cool-darkness-123456",
      "branch_id": "br-gentle-salad-123456",
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 0.25,
      "region_id": "aws-us-east-1",
      "type": "read_write",
      "current_state": "init",
      "pending_state": "active",
      "settings": {},
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "creation_source": "console",
      "created_at": "2026-08-04T05:15:41Z",
      "updated_at": "2026-08-04T05:15:41Z",
      "proxy_host": "c-2.us-east-1.aws.neon.tech",
      "suspend_timeout_seconds": 0,
      "provisioner": "k8s-neonvm"
    }
  ]
}
```

</details>

### List projects with the API

The following Neon API method lists projects for your Neon account. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/projects/list-projects).

```http
GET /projects
```

The API method appears as follows when specified in a cURL command:

```bash
curl 'https://console.neon.tech/api/v2/projects' \
 -H 'Accept: application/json' \
 -H "Authorization: Bearer $NEON_API_KEY" | jq
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [List projects](https://neon.com/docs/reference/api/projects/list-projects) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "projects": [
    {
      "id": "frosty-tree-10754091",
      "platform_id": "aws",
      "region_id": "aws-ap-southeast-1",
      "name": "personal_projects",
      "provisioner": "k8s-neonvm",
      "default_endpoint_settings": {
        "autoscaling_limit_min_cu": 0.25,
        "autoscaling_limit_max_cu": 2,
        "suspend_timeout_seconds": 0
      },
      "settings": {
        "allowed_ips": {
          "ips": [],
          "protected_branches_only": false
        },
        "enable_logical_replication": false,
        "maintenance_window": {
          "weekdays": [4],
          "start_time": "15:00",
          "end_time": "16:00"
        },
        "block_public_connections": false,
        "block_vpc_connections": false,
        "hipaa": false
      },
      "pg_version": 17,
      "proxy_host": "ap-southeast-1.aws.neon.tech",
      "branch_logical_size_limit": 512,
      "branch_logical_size_limit_bytes": 536870912,
      "store_passwords": true,
      "active_time": 1260,
      "cpu_used_sec": 319,
      "creation_source": "console",
      "created_at": "2026-11-08T17:20:01Z",
      "updated_at": "2026-08-03T01:16:18Z",
      "synthetic_storage_size": 96929448,
      "quota_reset_at": "2026-09-01T00:00:00Z",
      "owner_id": "91cbdacd-06c2-49f5-bacf-78b9463c81ca",
      "compute_last_active_at": "2026-08-03T01:16:18Z",
      "history_retention_seconds": 86400
    },
    {
      "id": "lingering-grass-54827563",
      "platform_id": "aws",
      "region_id": "aws-ap-southeast-1",
      "name": "brizai",
      "provisioner": "k8s-neonvm",
      "default_endpoint_settings": {
        "autoscaling_limit_min_cu": 0.25,
        "autoscaling_limit_max_cu": 2,
        "suspend_timeout_seconds": 0
      },
      "settings": {
        "allowed_ips": {
          "ips": [],
          "protected_branches_only": false
        },
        "enable_logical_replication": false,
        "maintenance_window": {
          "weekdays": [1],
          "start_time": "16:00",
          "end_time": "17:00"
        },
        "block_public_connections": false,
        "block_vpc_connections": false,
        "hipaa": false
      },
      "pg_version": 17,
      "proxy_host": "ap-southeast-1.aws.neon.tech",
      "branch_logical_size_limit": 512,
      "branch_logical_size_limit_bytes": 536870912,
      "store_passwords": true,
      "active_time": 0,
      "cpu_used_sec": 0,
      "creation_source": "console",
      "created_at": "2026-10-28T16:26:49Z",
      "updated_at": "2026-08-01T00:34:48Z",
      "synthetic_storage_size": 31082816,
      "quota_reset_at": "2026-09-01T00:00:00Z",
      "owner_id": "91cbdacd-06c2-49f5-bacf-78b9463c81ca",
      "compute_last_active_at": "2026-02-14T09:51:30Z",
      "history_retention_seconds": 86400
    }
  ],
  "unavailable_project_ids": [],
  "pagination": {
    "cursor": "lingering-grass-54827563"
  },
  "applications": {
    "frosty-tree-10754091": ["vercel"]
  },
  "integrations": {
    "frosty-tree-10754091": ["vercel"]
  }
}
```

</details>

### Count projects with the API

To get the number of projects without paging through the list, use the following Neon API method. It counts active projects only. Projects that are being created, or that were deleted and are still within the recovery window, aren't included. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/projects/count-projects).

```http
GET /projects/count
```

If you use a personal API key, include the `org_id` parameter to specify the organization. With an org API key, the organization is inferred from the key.

```bash
curl 'https://console.neon.tech/api/v2/projects/count?org_id=org-example-12345678' \
 -H 'Accept: application/json' \
 -H "Authorization: Bearer $NEON_API_KEY"
```

The response contains the count:

```json
{
  "count": 12
}
```

### Update a project with the API

The following Neon API method updates the specified project. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/projects/update-project).

```http
PATCH /projects/{project_id}
```

The API method appears as follows when specified in a cURL command. The `project_id` is a required parameter. The example changes the project `name` to `project1`.

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/ep-cool-darkness-123456' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "project": {
    "name": "project1"
  }
}'
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Update project](https://neon.com/docs/reference/api/projects/update-project) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "project": {
    "data_storage_bytes_hour": 35697544,
    "data_transfer_bytes": 13444,
    "written_data_bytes": 34595496,
    "compute_time_seconds": 89,
    "active_time_seconds": 348,
    "cpu_used_sec": 89,
    "id": "ep-cool-darkness-123456",
    "platform_id": "aws",
    "region_id": "aws-us-east-1",
    "name": "project1",
    "provisioner": "k8s-neonvm",
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 0.25,
      "suspend_timeout_seconds": 0
    },
    "settings": {
      "allowed_ips": {
        "ips": [],
        "protected_branches_only": false
      },
      "enable_logical_replication": false,
      "maintenance_window": {
        "weekdays": [7],
        "start_time": "06:00",
        "end_time": "07:00"
      },
      "block_public_connections": false,
      "block_vpc_connections": false,
      "hipaa": false
    },
    "pg_version": 17,
    "proxy_host": "c-2.us-east-1.aws.neon.tech",
    "branch_logical_size_limit": 512,
    "branch_logical_size_limit_bytes": 536870912,
    "store_passwords": true,
    "creation_source": "console",
    "history_retention_seconds": 86400,
    "created_at": "2026-08-04T05:15:41Z",
    "updated_at": "2026-08-04T05:55:58Z",
    "synthetic_storage_size": 35697544,
    "consumption_period_start": "0001-01-01T00:00:00Z",
    "consumption_period_end": "0001-01-01T00:00:00Z",
    "owner_id": "91cbdacd-06c2-49f5-bacf-78b9463c81ca",
    "compute_last_active_at": "2026-08-04T05:15:47Z"
  },
  "operations": []
}
```

</details>

### Delete a project with the API

The following Neon API method deletes the specified project. To view the API documentation for this method, refer to the [Neon API Reference](https://neon.com/docs/reference/api/projects/delete-project).

```http
DELETE /projects/{project_id}
```

The API method appears as follows when specified in a cURL command. The `project_id` is a required parameter.

```bash
curl -X 'DELETE' \
  'https://console.neon.tech/api/v2/projects/ep-cool-darkness-123456' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Delete project](https://neon.com/docs/reference/api/projects/delete-project) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "project": {
    "data_storage_bytes_hour": 35697544,
    "data_transfer_bytes": 13444,
    "written_data_bytes": 34595496,
    "compute_time_seconds": 89,
    "active_time_seconds": 348,
    "cpu_used_sec": 89,
    "id": "ep-cool-darkness-123456",
    "platform_id": "aws",
    "region_id": "aws-us-east-1",
    "name": "project2",
    "provisioner": "k8s-neonvm",
    "default_endpoint_settings": {
      "autoscaling_limit_min_cu": 0.25,
      "autoscaling_limit_max_cu": 0.25,
      "suspend_timeout_seconds": 0
    },
    "settings": {
      "allowed_ips": {
        "ips": [],
        "protected_branches_only": false
      },
      "enable_logical_replication": false,
      "maintenance_window": {
        "weekdays": [7],
        "start_time": "06:00",
        "end_time": "07:00"
      },
      "block_public_connections": false,
      "block_vpc_connections": false,
      "hipaa": false
    },
    "pg_version": 17,
    "proxy_host": "c-2.us-east-1.aws.neon.tech",
    "branch_logical_size_limit": 512,
    "branch_logical_size_limit_bytes": 536870912,
    "store_passwords": true,
    "creation_source": "console",
    "history_retention_seconds": 86400,
    "created_at": "2026-08-04T05:15:41Z",
    "updated_at": "2026-08-04T06:10:55Z",
    "synthetic_storage_size": 35697544,
    "consumption_period_start": "0001-01-01T00:00:00Z",
    "consumption_period_end": "0001-01-01T00:00:00Z",
    "owner_id": "91cbdacd-06c2-49f5-bacf-78b9463c81ca",
    "compute_last_active_at": "2026-08-04T05:15:47Z"
  }
}
```

</details>

## Recover a deleted project

If you accidentally delete a project, you can recover it within 7 days. This **deletion recovery period** restores the resources and settings listed below. Some integrations and Data API configuration require setup again after recovery.

**Note:** The deletion recovery period is different from the [history window](https://neon.com/docs/introduction/history-window) used for **instant restore** on branch data. The history window enables point-in-time recovery (PITR) for branch data, while the deletion recovery period allows you to recover (undelete) an entire deleted project.

### What's recovered

When you recover a deleted project, the following are restored:

- All branches, endpoints, snapshots, and compute configurations that existed when you deleted the project
- Project settings (IP Allow, logical replication, protected branches, scheduled updates)
- Project collaborators
- Connection strings
- Vercel-Managed Neon integration projects are re-imported into Vercel for management and billing

Branches with an [expiration time](https://neon.com/docs/guides/branch-expiration) that passes during the deletion recovery period are permanently deleted and aren't restored.

### What requires reconfiguration

The following features are **not** recovered and must be manually re-enabled after recovery:

- **Data API** (including `authenticated` and `anonymous` roles)
- **GitHub integration**
- **Neon-Managed Vercel integration** (Vercel Connected Accounts)
- **Vercel-Managed Neon integration** (project reconnection via Storage)
- **Monitoring integrations** (Datadog, OpenTelemetry, etc.)
- **Scoped credentials** for Object Storage and the AI Gateway. Deleting a project revokes them, and they stay revoked after recovery. [Create new credentials](https://neon.com/docs/cli/credentials) and update your apps. Neon Functions get a new credential automatically.

### While a project is deleted

You can't connect to a deleted project's databases. Access returns when you recover the project.

### Costs

There are no storage costs or recovery fees during the 7-day deletion recovery period.

### Requirements and limitations

- **Permissions:** Recovering a project requires the same access as deleting one: organization Admin, or **Admin** on that project. See [Per-project permissions](https://neon.com/docs/manage/user-permissions#per-project-permissions).
- **HIPAA projects:** Projects with [HIPAA compliance](https://neon.com/docs/security/hipaa) enabled can't be recovered. Deleting a HIPAA-compliant project is permanent.
- **Vercel-Managed Neon projects:** Recovery re-imports the project into Vercel, so the Vercel integration for the organization must still exist. If the Neon organization was also deleted (for example, when you remove the database from Vercel Storage), [contact Support](https://neon.com/docs/introduction/support).

### Recover a project

**Console**

When an organization has projects that can be recovered, its **Projects** page shows a banner stating how many projects are set to be permanently deleted. The banner doesn't appear when there's nothing to recover.

To recover a deleted project:

1. Navigate to the [Neon Console](https://console.neon.tech) and open the **Projects** page for the organization the project belonged to.
2. On the banner that says projects are set to be permanently deleted, select **Manage**.
3. In the **Recently deleted projects** dialog, find the project. The **Delete forever in** column shows how much time is left to recover it.
4. Select **Recover**.

The Console opens the recovered project. A **Project recovered** notice on the project dashboard reminds you to review the project's integrations and reconnect any that stopped working. See [What requires reconfiguration](https://neon.com/docs/manage/projects#what-requires-reconfiguration).

If recovery fails, the Console shows an error and you can try again.

**CLI**

To list projects that can be recovered:

```bash
neon projects list --recoverable-only
```

To recover a deleted project:

```bash
neon projects recover <project_id>
```

The command returns details about the recovered project.

**Example:**

```bash
neon projects recover crimson-voice-12345678
ID          crimson-voice-12345678
Name        myproject
Region ID   aws-us-east-2
Created At  2026-04-15T11:17:30Z
```

For more information about the Neon CLI, see [Neon CLI — projects](https://neon.com/docs/cli/projects).

**API**

To list projects that can be recovered, use the following Neon API method with the `recoverable` query parameter:

```http
GET /projects?recoverable=true
```

**Example:**

```bash
curl 'https://console.neon.tech/api/v2/projects?recoverable=true' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

To recover a deleted project, use the following Neon API method:

```http
POST /projects/{project_id}/recover
```

**Example:**

```bash
curl -X POST \
  'https://console.neon.tech/api/v2/projects/crimson-voice-12345678/recover' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

The API returns a `200` status code with the restored project object.

--- [Document source](https://neon.com/docs/manage/roles.md) ---

> Summary: Postgres roles in Neon are branch-scoped, with a limit of 500 roles per branch. Roles created via the Console, CLI, or API automatically receive neon_superuser membership (CREATEDB, CREATEROLE, BYPASSRLS, REPLICATION). Roles created with SQL receive only basic public schema privileges and must be granted permissions explicitly. Use this page to create, delete, list, and reset passwords for roles using the Console, CLI, API, or SQL.

# Manage roles

Last updated: 2026-11-05

In Neon, roles are Postgres roles. Each Neon project is created with a Postgres role that is named for your database. For example, if your database is named `neondb`, the project is created with a role named `neondb_owner`. This role owns the database that is created in your Neon project's default branch.

Your Postgres role and roles created in the Neon Console or API are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, and so are roles created with `neon roles create` unless you pass `--access`. Roles created with SQL from clients like [psql](https://neon.com/docs/connect/query-with-psql-editor), [pgAdmin](https://www.pgadmin.org/), or the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) are only granted the basic [public schema privileges](https://neon.com/docs/manage/database-access#public-schema-privileges) granted to newly created roles in a standalone Postgres installation. These users must be selectively granted permissions for each database object. For more information, see [Manage database access](https://neon.com/docs/manage/database-access).

**Note:** Neon is a managed Postgres service, so you cannot access the host operating system, and you can't connect using the Postgres `superuser` account like you can in a standalone Postgres installation.

**Which method should I use?:**

Roles you create in the Neon Console or API are administrator roles with [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) privileges, and so are roles from `neon roles create` by default. For a read-only or read-write role on one database, pass `--access read_only` or `--access read_write` to [`neon roles create`](https://neon.com/docs/cli/roles#create). For any other set of privileges, [use SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql) and grant only the privileges the role needs.

You can create roles in a project's default branch or child branches. Neon enforces a limit of 500 roles per branch. Internal roles that Neon manages, such as `neon_service`, don't count toward this limit.

In Neon, roles belong to a branch, which could be your production branch or a child branch. When you create a child branch, roles in the parent branch are duplicated in the child branch. For example, if role `alex` exists in the parent branch, role `alex` is copied to the child branch when the child branch is created. The only time this does not occur is when you create a branch that only includes data up to a particular point in time. If the role was created in the parent branch after that point in time, it is not duplicated in the child branch.

Neon supports creating and managing roles from the following interfaces:

- [Manage roles](https://neon.com/docs/manage/roles#manage-roles) using the Neon Console, CLI, or API
- [Manage roles with SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql)

## The neon_superuser role

Roles created in the Neon Console or API, roles created with `neon roles create` unless you pass `--access`, and the role created with a Neon project are granted membership in the `neon_superuser` role. Users can't log in as `neon_superuser`, but they inherit the privileges assigned to this role. The privileges and predefined role memberships granted to `neon_superuser` include:

- `CREATEDB`: Provides the ability to create databases.
- `CREATEROLE`: Provides the ability to create new roles (which also means it can alter and drop roles).
- `BYPASSRLS`: Provides the ability to bypass row-level security (RLS) policies. This attribute is only included in `neon_superuser` roles in projects created after the [August 15, 2023 release](https://neon.com/docs/changelog/2023-08-15-storage-and-compute).
- `NOLOGIN`: The role cannot be used to log in to the Postgres server. Neon is a managed Postgres service, so you cannot access the host operating system directly.
- `pg_read_all_data`: A predefined Postgres role provides the ability to read all data (tables, views, sequences), as if having `SELECT` rights on those objects, and `USAGE` rights on all schemas.
- `pg_write_all_data`: A predefined Postgres role that provides the ability to write all data (tables, views, sequences), as if having `INSERT`, `UPDATE`, and `DELETE` rights on those objects, and `USAGE` rights on all schemas.
- `REPLICATION`: Provides the ability to connect to a Postgres server in replication mode and create or drop replication slots.
- `pg_create_subscription`: A predefined Postgres role that lets users with `CREATE` permission on the database issue `CREATE SUBSCRIPTION`. The `pg_create_subscription` role is only available as of Postgres 16. The `neon_superuser` role in Postgres 14 and 15 can issue `CREATE SUBSCRIPTION` with only `CREATE` permission on the database.
- `pg_monitor`: A predefined Postgres role that provides read/execute privileges on various Postgres monitoring views and functions. The `neon_superuser` role also has `WITH ADMIN` on the `pg_monitor` role, which enables granting the `pg_monitor` to other Postgres roles.
- `EXECUTE` privilege on the `pg_stat_statements_reset()` function that is part of the `pg_stat_statements` extension. This privilege was introduced with the January 12, 2024 release. If you installed the `pg_stat_statements` extension before this release, drop and recreate the `pg_stat_statements` extension to enable this privilege. See [Install an extension](https://neon.com/docs/extensions/pg-extensions#install-an-extension).
- `pg_signal_backend`: The `neon_superuser` role is granted the `pg_signal_backend` privilege, which allows it to cancel (terminate) backend sessions belonging to roles that are not members of `neon_superuser`. The `WITH ADMIN OPTION` allows `neon_superuser` to grant the `pg_signal_backend` role to other users/roles.
- `pg_maintain`: A predefined Postgres role that provides the ability to run maintenance commands (`VACUUM`, `ANALYZE`, `CLUSTER`, `REFRESH MATERIALIZED VIEW`, `REINDEX`, and `LOCK TABLE`) on all relations, as if having `MAINTAIN` rights on those objects. Available as of Postgres 17.
- `pg_signal_autovacuum_worker`: A predefined Postgres role that allows signaling autovacuum workers to cancel the current table's vacuum or terminate the worker's session. Available as of Postgres 18.
- `GRANT ALL ON TABLES` and `WITH GRANT OPTION` on the `public` schema.
- `GRANT ALL ON SEQUENCES` and `WITH GRANT OPTION` on the `public` schema.
- `CREATE EVENT TRIGGER`, `ALTER EVENT TRIGGER`, `DROP EVENT TRIGGER`. The `ALTER EVENT TRIGGER` command does not allow changing the function associated with the event trigger.

You can think of roles with `neon_superuser` privileges as administrator roles. If you require roles with limited privileges, such as a read-only role, you can create those roles from an SQL client, or create a read-only or read-write role with [`neon roles create --access`](https://neon.com/docs/cli/roles#create). For more information, see [Manage database access](https://neon.com/docs/manage/database-access).

**Note:** Creating a database with the `neon_superuser` role, altering a database to have owner `neon_superuser`, and altering the `neon_superuser` role itself are _not_ permitted. This `NOLOGIN` role is not intended to be used directly or modified.

You may also see internal roles Neon uses to operate your project, such as `neon_service`. They act on your behalf (which is why they can appear with `neon_superuser` membership); their credentials are managed by Neon, and they are not intended for you to use or modify.

## Manage roles

You can create, list, delete, and reset passwords for roles using the Neon Console, CLI, or API. Roles created through any of these interfaces are granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role. To create roles with limited privileges, use [SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql).

### Create a role

**Console**

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Click **Add role**.
6. In the role creation modal, specify a role name. The branch is pre-selected.
7. Click **Create**. The role is created and you are provided with the password for the role.

**CLI**

Create a role with [`neon roles create`](https://neon.com/docs/cli/roles#create). Pass `--no-login` to create a `NOLOGIN` role:

```bash
neon roles create --name alex
```

By default, the role joins `neon_superuser`. Pass `--access read_only` or `--access read_write` to create a role scoped to one database's tables instead:

```bash
neon roles create --name reporting --access read_only
```

**API**

Create a role with the [Create role](https://neon.com/docs/reference/api/branches/create-project-branch-role) endpoint. The role `name` is required and limited to 63 bytes:

```bash
curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "role": {
    "name": "alex"
  }
}' | jq
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Create role](https://neon.com/docs/reference/api/branches/create-project-branch-role) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "role": {
    "branch_id": "br-morning-meadow-123456",
    "name": "alex",
    "password": "npg_A9xYoejTz6iQ",
    "protected": false,
    "created_at": "2026-08-04T07:47:05Z",
    "updated_at": "2026-08-04T07:47:05Z"
  },
  "operations": [
    {
      "id": "9c61fc28-c89e-4b25-ad5c-8777742e66a3",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-morning-meadow-123456",
      "endpoint_id": "ep-holy-heart-123456",
      "action": "apply_config",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T07:47:05Z",
      "updated_at": "2026-08-04T07:47:05Z",
      "total_duration_ms": 0
    }
  ]
}
```

</details>

**Note:** Role names can't exceed 63 bytes, and some names aren't permitted. See [Reserved role names](https://neon.com/docs/manage/roles#reserved-role-names).

### List roles

**Console**

In the Neon Console, select your branch from the project/branch menu at the top of the sidebar, then under **Postgres database** select **Roles** to see the roles on the branch.

**CLI**

List the roles on a branch with [`neon roles list`](https://neon.com/docs/cli/roles#list):

```bash
neon roles list
```

```text filename="Output"
Roles on main
Name          Created At
neondb_owner  2026-06-19T18:27:19Z
alex          2026-07-13T06:42:55Z
```

**API**

List roles with the [List roles](https://neon.com/docs/reference/api/branches/list-project-branch-roles) endpoint:

```bash
curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/roles' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [List roles](https://neon.com/docs/reference/api/branches/list-project-branch-roles) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "roles": [
    {
      "branch_id": "br-morning-meadow-123456",
      "name": "neondb_owner",
      "protected": false,
      "created_at": "2026-07-09T17:01:34Z",
      "updated_at": "2026-07-09T17:01:34Z"
    },
    {
      "branch_id": "br-morning-meadow-123456",
      "name": "alex",
      "protected": false,
      "created_at": "2026-07-13T06:42:55Z",
      "updated_at": "2026-07-13T14:48:29Z"
    }
  ]
}
```

</details>

### Delete a role

Deleting a role is a permanent action that cannot be undone, and you cannot delete a role that owns a database. The database must be deleted before deleting the role that owns the database.

**Console**

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Select **Delete role** from the role menu.
6. On the confirmation modal, click **Delete**.

**CLI**

Delete a role with [`neon roles delete`](https://neon.com/docs/cli/roles#delete), passing the role name:

```bash
neon roles delete alex
```

**API**

Delete a role with the [Delete role](https://neon.com/docs/reference/api/branches/delete-project-branch-role) endpoint:

```bash
curl -X 'DELETE' \
  'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/roles/alex' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Delete role](https://neon.com/docs/reference/api/branches/delete-project-branch-role) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "role": {
    "branch_id": "br-morning-meadow-123456",
    "name": "alex",
    "protected": false,
    "created_at": "2026-08-04T07:47:05Z",
    "updated_at": "2026-08-04T07:51:10Z"
  },
  "operations": [
    {
      "id": "722b9f9b-c50e-424c-845e-78b38151b82f",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-morning-meadow-123456",
      "endpoint_id": "ep-holy-heart-123456",
      "action": "apply_config",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T07:53:22Z",
      "updated_at": "2026-08-04T07:53:22Z",
      "total_duration_ms": 0
    }
  ]
}
```

</details>

### Get a role's password

To see the password for an existing role, use the Console, CLI, or API.

**Console**

Click **Connect** on your project dashboard, select the branch, database, and role, and copy the connection string. The password is included in the connection string.

**CLI**

Get a connection string that includes the role's password with [`neon connection-string`](https://neon.com/docs/cli/connection-string):

```bash
neon connection-string --role-name alex
```

**API**

Get a role's password with the [Reveal role password](https://neon.com/docs/reference/api/branches/get-project-branch-role-password) endpoint:

```bash
curl 'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/roles/alex/reveal_password' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

### Reset a password

You can reset a role's password from the Neon Console, CLI, or API. Resetting sets a generated password; to set your own value, use [SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql).

**Console**

1. Navigate to the [Neon Console](https://console.neon.tech).
2. Select a project.
3. Select your branch from the project/branch menu at the top of the sidebar.
4. Under **Postgres database**, select **Roles**.
5. Select **Reset password** from the role menu.
6. On the **Reset password** modal, click **Reset**. A reset password modal is displayed with your new password.

**CLI**

Reset a role's password with [`neon roles reset-password`](https://neon.com/docs/cli/roles#reset-password). It prints the new password and waits until the compute applies it:

```bash
neon roles reset-password alex
```

**API**

Reset a role's password with the [Reset role password](https://neon.com/docs/reference/api/branches/reset-project-branch-role-password) endpoint:

```bash
curl -X 'POST' \
  'https://console.neon.tech/api/v2/projects/dry-heart-13671059/branches/br-morning-meadow-afu2s1jl/roles/alex/reset_password' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

<details>

<summary>Response body</summary>

For attribute definitions, find the [Reset role password](https://neon.com/docs/reference/api/branches/reset-project-branch-role-password) endpoint in the [Neon API Reference](https://neon.com/docs/reference/api). Definitions are provided in the **Responses** section.

```json
{
  "role": {
    "branch_id": "br-morning-meadow-123456",
    "name": "alex",
    "password": "npg_iDKnwMW7bUg5",
    "protected": false,
    "created_at": "2026-08-04T07:47:05Z",
    "updated_at": "2026-08-04T07:51:10Z"
  },
  "operations": [
    {
      "id": "23b3db33-d36a-45bf-9fda-0e73b5b272e5",
      "project_id": "dry-heart-13671059",
      "branch_id": "br-morning-meadow-123456",
      "endpoint_id": "ep-holy-heart-123456",
      "action": "apply_config",
      "status": "running",
      "failures_count": 0,
      "created_at": "2026-08-04T07:51:10Z",
      "updated_at": "2026-08-04T07:51:10Z",
      "total_duration_ms": 0
    }
  ]
}
```

</details>

**Note:**

Resetting a password in the Neon Console resets the password to a generated value. To set your own password value, you can reset the password using the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or an SQL client like [psql](https://neon.com/docs/connect/query-with-psql-editor) with the following syntax:

```sql
ALTER ROLE role_name WITH PASSWORD 'new_password';
```

For password requirements, see [Manage roles with SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql).

A password reset takes effect immediately. The old password stops working on the next connection, so copy the new connection string from the **Connect** modal and update it wherever it is stored (deployment environment variables, secret managers, and `.env` files). Resets are branch-scoped, so reset the role on each branch where it is used.

Resetting a password is also how you rotate the credential behind a connection string. To rotate after a leak or as routine security practice, see [Rotate credentials](https://neon.com/docs/security/security-overview#rotate-credentials).

## Manage roles with SQL

Roles created with SQL have the same basic `public` schema privileges as newly created roles in a standalone Postgres installation. These roles are not granted membership in the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role like roles created with the Neon Console, CLI, or API. You must grant these roles the privileges you want them to have.

To create a role with SQL, issue a `CREATE ROLE` statement from a client such as [psql](https://neon.com/docs/connect/query-with-psql-editor), [pgAdmin](https://www.pgadmin.org/), or the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor).

```sql
CREATE ROLE <name> WITH LOGIN PASSWORD 'password';
```

- `WITH LOGIN` means that the role will have a login privilege, required for the role to log in to your database. If the role is used only for privilege management, the `WITH LOGIN` privilege is unnecessary.
- A password must have a minimum entropy of 60 bits.

  **Info:**

  To create a password with 60 bits of entropy, you can follow these password composition guidelines:

  - **Length**: The password should consist of at least 12 characters.
  - **Character diversity**: To enhance complexity, passwords should include a variety of character types, specifically:
    - Lowercase letters (a-z)
    - Uppercase letters (A-Z)
    - Numbers (0-9)
    - Special symbols (for example, !@#$%^&*)
  - **Avoid predictability**: To maintain a high level of unpredictability, do not use:
    - Sequential patterns (such as `1234`, `abcd`, `qwerty`)
    - Common words or phrases
    - Any words found in a dictionary
  - **Avoid character repetition**: To maximize randomness, do not use the same character more than twice consecutively.

  Example password: `T3sting!23Ab` (DO NOT USE THIS EXAMPLE PASSWORD)

  Passwords must be supplied in plain text but are encrypted when stored. Hashed passwords are not supported.

  The guidelines should help you create a password with approximately 60 bits of entropy. However, depending on the exact characters used, the actual entropy might vary slightly. Always aim for a longer and more complex password if you're uncertain. It's also recommended to use a trusted password manager to create and store your complex passwords safely.

For example, to create a read-only role for one schema:

```sql
CREATE ROLE readonly_user WITH LOGIN PASSWORD '<password>';
GRANT CONNECT ON DATABASE <database> TO readonly_user;
GRANT USAGE ON SCHEMA <schema> TO readonly_user;
GRANT SELECT ON ALL TABLES IN SCHEMA <schema> TO readonly_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema> GRANT SELECT ON TABLES TO readonly_user;
```

`ALTER DEFAULT PRIVILEGES` applies to tables created later by the role that runs it. For read-write and developer roles, and for using group roles to manage many users, see [Manage database access](https://neon.com/docs/manage/database-access).

## Creating NOLOGIN roles

Neon supports creating Postgres roles with the `NOLOGIN` attribute. This allows you to define roles that cannot authenticate but can be granted privileges.

```sql
CREATE ROLE my_role NOLOGIN;
```

Roles with `NOLOGIN` are commonly used for permission management. For an example, see [Transfer database table ownership between roles](https://neon.com/docs/manage/databases#transfer-database-table-ownership-between-roles).

The Neon API and CLI also support creating `NOLOGIN` roles:

- The Neon API [Create role](https://neon.com/docs/reference/api/branches/create-project-branch-role) endpoint supports a `no_login` attribute.
- The Neon CLI [`neon roles create`](https://neon.com/docs/cli/roles#create) command supports a `--no-login` option.

## Reserved role names

The following names are reserved and cannot be given to a role:

- Any name starting with `pg_`
- `neon_superuser`
- `cloud_admin`
- `zenith_admin`
- `public`
- `none`
- `web_access`
- `token_roles`

--- [Document source](https://neon.com/docs/manage/updates.md) ---

> Summary: Neon compute updates deliver Postgres minor version upgrades, security patches, and OS changes by restarting the compute, typically in seconds, with automatic cache prewarming to avoid cold-cache performance loss after restart. Paid plan users can schedule a preferred update window via the console or API. Free plan updates are scheduled by Neon with advance notice. Computes larger than 16 CU are excluded from automatic updates and must be restarted manually. Configure connection retry logic to handle the brief disruption.

# Updates

Last updated: 2026-11-04

To keep your Neon [computes](https://neon.com/docs/reference/glossary#compute) and Postgres instances up to date with the latest patches and features, Neon applies updates to your project's computes. We notify you of updates in advance so that you can plan for them if necessary. On Neon's paid plans, you can select an update window (a specific day and hour for updates).

## How Neon applies updates

To apply updates to your compute (Postgres upgrades, security patches, and similar changes), Neon restarts the compute where Postgres runs. On paid plans, this happens within the [update window](https://neon.com/docs/manage/updates#updates-on-paid-plans) you choose. On the Free plan, Neon schedules updates for you. The restart itself typically takes only a few seconds.

To protect performance, Neon **prewarms** your compute's cache during the update process, without adding time to the restart. Prewarming means repopulating Postgres's in-memory buffer cache from storage before your workload continues, so frequently used data is already in memory instead of being read cold from storage after the restart. Prewarming runs automatically. You do not configure it. There are no additional compute or storage costs associated with this behavior.

For technical details, see [Zero-Downtime Patching Part 1: Prewarming](https://neon.com/blog/prewarming).

**Important:** Brief connection drops are expected during compute updates. Verify that your application has a retry policy configured to handle these brief interruptions. For guidance on implementing retry logic, see [Building resilient applications with Postgres](https://neon.com/guides/building-resilient-applications-with-postgres).

## What updates are included?

Updates to Neon computes may include some or all of the following:

- Postgres minor version upgrades, typically released quarterly
- Security patches and updates
- Operating system updates
- Neon features and enhancements
- Updates to other tools and components included in Neon compute images

Neon compute updates do not include [Neon platform maintenance](https://neon.com/docs/manage/platform-maintenance).

## How often are updates applied?

Updates are typically released weekly but may occur more or less frequently, as needed.

Neon applies updates to computes based on the following rules:

- Computes that have been active for 30 days or more receive updates.
- Computes that are restarted receive available updates immediately.
- Computes in a transition state (for example, shutting down or restarting) at the time of an update are not updated.
- Computes **larger than 16 CU** are not updated automatically. Autoscaling computes, which have a maximum of 16 CU, and fixed-size computes up to 16 CU receive scheduled updates. See [Updating large computes](https://neon.com/docs/manage/updates#updating-large-computes).

If a compute is excluded from an update, Neon will apply the missed update with the next update, assuming the compute meets the update criteria mentioned above.

**Important: updates outside of scheduled update windows**

Please be aware that Neon must occasionally perform essential **platform maintenance** outside the scheduled updates performed on Neon computes. This means that you may experience brief disruptions from time to time. To learn more, see [Platform maintenance](https://neon.com/docs/manage/platform-maintenance).

## Updates on the Free plan

On the **Free plan**, updates are scheduled and applied automatically. You can check your project's settings for updates. We'll post a notice there at least **1 day** ahead of a planned update, letting you know when it's coming.

To view planned updates:

1. Open your project in the Neon Console.
2. Select **Settings** > **Postgres**.

   ![Free plan updates UI](https://neon.com/docs/manage/free_plan_updates.png)

If you want to apply an update ahead of the scheduled date, see [Applying updates ahead of schedule](https://neon.com/docs/manage/updates#applying-updates-ahead-of-schedule).

## Updates on paid plans

On Neon's paid plans, you can set a preferred update window by specifying the day and hour. Updates will be applied within this window, letting you plan for the required compute restart.

You can specify an update window in your Neon project's settings or using the Neon API.

**Neon Console**

In the Neon Console:

1. Open your project in the Neon Console.
2. Select **Settings** > **Postgres**.
3. Choose a day of the week and an hour. Updates will occur within this time window and take only a few seconds.

   ![Paid plan updates UI](https://neon.com/docs/manage/paid_plan_updates.png)

You can check your project's settings for upcoming updates. On all paid plans, we post a notice there at least **3 days** ahead of a planned update, letting you know when it's coming.

> On the **Scale** and **Enterprise** plans, you also receive an **email notification** 3 days in advance of a planned update, in addition to the in-console notice. On the **Launch** plan, advance notice is provided in the console only, with no email.

**API**

On Neon paid plans, the [Create project](https://neon.com/docs/reference/api/projects/create-project) and [Update project](https://neon.com/docs/reference/api/projects/update-project) APIs let you define an update window using the `maintenance_window` object, as shown in the `Update project` example below.

- The `weekdays` parameter accepts an integer (`1` for Monday, `2` for Tuesday, and so on) or an array of integers to specify multiple weekdays.
- The `start_time` and `end_time` values must be in UTC (`HH:MM` format) and at least one hour apart. Shorter intervals are not supported. Both times must fall on the same day. For example, (`22:00`, `23:00`) and (`23:00`, `00:00`) are valid settings, but (`22:00`, `03:00`) is not, as it would span multiple days.

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/fragrant-mode-99795914 \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API' \
     --header 'content-type: application/json' \
     --data '
{
  "project": {
    "settings": {
      "maintenance_window": {
        "weekdays": [
          7
        ],
        "start_time": "01:00",
        "end_time": "02:00"
      }
    }
  }
}
'
```

## Check for updates using the Neon API

You can retrieve your update window and check for planned updates using the [Retrieve project details](https://neon.com/docs/reference/api/projects/get-project) endpoint.

To get your project details, send the following request, replacing `<your_project_id>` with your Neon project ID, and `$NEON_API_KEY` with your [Neon API key](https://neon.com/docs/manage/api-keys):

```bash
curl --request GET \
     --url https://console.neon.tech/api/v2/projects/<your_project_id> \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY'
```

In the response, locate the `maintenance_window` field. It specifies the selected weekday and hour for updates. For Free plan accounts, the update window is set by Neon. Paid plan accounts can [choose a preferred update window](https://neon.com/docs/manage/updates#updates-on-paid-plans). The `weekdays` value is a number from 1 to 7, representing the day of the week.

```json
{
...
  "settings": {
      "maintenance_window": {
         "weekdays": [5],
         "start_time": "07:00",
         "end_time": "08:00"
      },
   }
  "maintenance_scheduled_for": "2025-02-07T07:00"
...
}
```

If there's a planned update, you'll also find a `maintenance_scheduled_for` field in the response body. This value matches the `start_time` in your `maintenance_window` but is formatted as a timestamp. If the `maintenance_scheduled_for` field in not present in the response, this means there is no planned update at this time.

## Applying updates ahead of schedule

Computes receive available updates immediately upon restart. For example, if Neon notifies you about an upcoming update, you can apply it right away by restarting the compute. However, the notification won't be cleared in this case. When the planned update time arrives, no further action will be taken since the compute is already updated.

If a compute regularly scales to zero, it will receive updates when it starts up again. In such cases, you may not need to pay much attention to update notifications, as updates will be applied naturally through your compute's stop/start cycles.

For compute restart instructions, see [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

## Updating large computes

**Note: Threshold raised to 16 CU**

As of early November 2026, computes up to 16 CU receive scheduled updates. Previously, computes configured to scale beyond 8 CU were not updated automatically and needed a manual restart.

Fixed-size computes **larger than 16 CU** are not updated automatically (_scheduled updates do not apply_). Computes up to 16 CU, including all autoscaling computes, follow the usual [automatic update rules](https://neon.com/docs/manage/updates#how-often-are-updates-applied) above. To apply updates on a large compute, you'll need to restart it manually. Computes larger than 16 CU don't [scale to zero](https://neon.com/docs/introduction/scale-to-zero), so they won't pick up updates through a stop/start cycle. Plan for manual restarts.

Neon typically releases compute updates weekly, so we recommend scheduling weekly compute restarts.

For restart instructions, see [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

## Handling connection disruptions during compute updates

Prewarming helps keep the cache warm through the update, so query performance is not affected by a cold cache, but you may still experience a brief connection drop due to the compute restart.

Most Postgres connection drivers include built-in retry mechanisms that automatically handle short-lived connection interruptions. This means that for most applications, a brief restart should result in minimal disruption, as the driver will reconnect automatically.

However, if your application has strict availability requirements, you may want to ensure that your connection settings are configured to allow for retries. Check your driver's documentation for options like connection timeouts, retry intervals, and connection pooling strategies. Your configuration should account for the few seconds it takes to apply updates to your Neon compute. For related information, see [Build connection timeout handling into your application](https://neon.com/docs/connect/connection-latency#build-connection-timeout-handling-into-your-application).

If your application or integration uses the [Neon API](https://neon.com/docs/reference/api) or [SDKs](https://neon.com/docs/reference/sdk) that wrap the Neon API, we recommend building in the same type of retry logic.

## See also

- [Building resilient applications with Postgres](https://neon.com/guides/building-resilient-applications-with-postgres): Best practices for handling connection drops with retry logic, connection pooling, and idempotency
- [Connection latency and timeouts](https://neon.com/docs/connect/connection-latency): Strategies for managing connection latencies and timeouts

--- [Document source](https://neon.com/docs/manage/user-permissions.md) ---

> Summary: Neon access has two layers. Organization roles (Admin, Editor, Viewer, Collaborator) set a baseline across every project, and per-project permissions (Viewer, Editor, Admin) grant extra access on individual projects. The two layers are additive, so a permission can only raise a user's access on a project, never lower it.

# User permissions

How organization roles and per-project permissions work in Neon

Last updated: 2026-07-29

In Neon, access works in two layers. Your **organization role** sets a baseline level of access across every project in the org, and **per-project permissions** grant additional access on individual projects. This page explains how the two layers combine and what each role and permission lets you do.

This page is mainly for organization Admins, who decide who can see and change projects.

For an overview of organizations, see the [Organizations](https://neon.com/docs/manage/organizations) page.

**Note: Availability**

New organizations use the permissions model described here. Existing organizations continue to use the [legacy permissions](https://neon.com/docs/manage/user-permissions#legacy-permissions) model until they're migrated, and their access is preserved when that happens. Organizations managed through the [Vercel-managed integration](https://neon.com/docs/guides/vercel-managed-integration) also continue to use the legacy model.

## How permissions work

Your organization role and any per-project permissions combine, and they're **additive**: your effective access on a project is the higher of the two. A per-project permission can only raise your access, never lower it. (Restricting access on a single project isn't supported yet. See [Notes and limitations](https://neon.com/docs/manage/user-permissions#notes-and-limitations).)

Access is **closed by default** for Collaborators. Without an explicit per-project grant, a project doesn't appear in a Collaborator's list at all, and Neon responds as though it doesn't exist.

### Common setups

These examples show how an organization role and per-project grants combine:

| Person         | Organization role | Per-project grant        | Effective access                                          |
| -------------- | ----------------- | ------------------------ | --------------------------------------------------------- |
| Team lead      | Admin             | None                     | Full control of the organization and every project        |
| Staff engineer | Editor            | None                     | Edit every project, but can't delete or transfer them out |
| Designer       | Viewer            | Editor on one project    | Read-only across the org, plus full edit on that project  |
| Contractor     | Collaborator      | Editor on their projects | Access to only the granted projects, nothing else         |
| Support        | Collaborator      | Viewer (temporary)       | Read-only on a single project, removed when done          |

A couple of behaviors are worth calling out:

- **Viewers can still create their own projects.** The read-only limit applies to projects a Viewer didn't create. Any organization member except a Collaborator can create a project, and whoever creates a project becomes **Admin** on it. They keep that access if their organization role changes later, so to reduce it, grant them a lower permission on the project explicitly.
- **Deleting a project takes Admin access on that project**, not the Admin organization role. Anyone granted **Admin** on a project, along with any organization Admin, can delete it after typing the project name to confirm.

## Assign project access

Access comes down to two things: a person's organization role sets their baseline everywhere, and per-project permissions add to it where they need more.

## Set the organization role

Start with the organization role, which sets a person's baseline access across every project. On the organization's **People** page, select **Invite member** to add someone with a role, or open the more options menu (⋮) next to an existing member and choose **Edit member** to change it. Match the role to how much of the organization they should see; for what each role grants, see [Organization roles](https://neon.com/docs/manage/user-permissions#organization-roles).

## Grant per-project permissions

To give someone more than their baseline on a specific project, open that project's **Settings** → **Project permissions**, select **Grant permission**, choose a level (**Viewer**, **Editor**, or **Admin**), and pick one or more members. A grant only ever raises access: a person's effective permission is the higher of their organization role and the grant. For what each level allows, see [Per-project permissions](https://neon.com/docs/manage/user-permissions#per-project-permissions).

![Granting a per-project permission in the Neon Console](https://neon.com/docs/manage/user-permissions/grant-permission.png)

## Review who has access

The same **Project permissions** page lists everyone who can reach the project, with an [Inherited or explicit](https://neon.com/docs/manage/user-permissions#inherited-and-explicit-access) tag on each. Change or revoke an explicit grant from the more options menu (⋮) next to a person's name.

## Organization roles

Every member of an organization has one of four roles. Each role sets a baseline level of access on every project in the organization:

| Role         | What it can do                                                                                 | Default project access |
| ------------ | ---------------------------------------------------------------------------------------------- | ---------------------- |
| Admin        | Full control of the organization and all projects, including billing, members, and settings    | Admin                  |
| Editor       | Everything except deleting projects or transferring them out of the organization               | Editor                 |
| Viewer       | Read-only access to organization and project metadata. Can't see connection strings or run SQL | Viewer                 |
| Collaborator | No default access. Sees only projects they're explicitly granted                               | None                   |

The following table shows what each role can do at the organization level:

| Action                                         | Admin | Editor | Viewer | Collaborator |
| ---------------------------------------------- | :---: | :----: | :----: | :----------: |
| Manage organization members and roles          |   ✅   |    ❌   |    ❌   |       ❌      |
| Manage organization billing                    |   ✅   |    ❌   |    ❌   |       ❌      |
| Rename or delete the organization              |   ✅   |    ❌   |    ❌   |       ❌      |
| Transfer a project into the org                |   ✅   |    ✅   |    ✅   |       ❌      |
| Transfer a project out of the org              |   ✅   |    ❌   |    ❌   |       ❌      |
| Create organization or project-scoped API keys |   ✅   |    ❌   |    ❌   |       ❌      |
| See all organization projects                  |   ✅   |    ✅   |    ✅   |       ❌      |
| Create projects                                |   ✅   |    ✅   |    ✅   |       ❌      |

Personal API keys are available to any member and are scoped to that member's own access. Only Admins can create organization or project-scoped API keys. See [Manage API keys](https://neon.com/docs/manage/api-keys).

## Per-project permissions

A per-project permission grants access on a single project, on top of a person's organization role. There are three levels, the same **Viewer**, **Editor**, and **Admin** levels an organization role grants by default:

- **Viewer**: Read-only project access.
- **Editor**: Connect, query, and edit project resources.
- **Admin**: Manage access, settings, and the project lifecycle.

To grant one, see [Assign project access](https://neon.com/docs/manage/user-permissions#assign-project-access). The following table shows what each level allows:

| Action                                                                                    | Viewer | Editor | Admin |
| ----------------------------------------------------------------------------------------- | :----: | :----: | :---: |
| See the project and read its metadata, branches, endpoints, databases, and Postgres roles |    ✅   |    ✅   |   ✅   |
| List snapshots and view the snapshot schedule                                             |    ✅   |    ✅   |   ✅   |
| Get connection strings and run SQL in the SQL Editor                                      |    ❌   |    ✅   |   ✅   |
| Create, edit, or delete branches, endpoints, databases, and Postgres roles                |    ❌   |    ✅   |   ✅   |
| Create, restore, delete, or reschedule snapshots                                          |    ❌   |    ✅   |   ✅   |
| Configure integrations (GitHub, Vercel)                                                   |    ❌   |    ✅   |   ✅   |
| Change project settings                                                                   |    ❌   |    ✅   |   ✅   |
| Manage who can access the project                                                         |    ❌   |    ❌   |   ✅   |
| Delete the project                                                                        |    ❌   |    ❌   |   ✅   |

As a rule, Viewers can see a project's resources, Editors can change them, and Admins manage access and the project itself.

Newer Neon products, including Managed Better Auth, Storage, Functions, and the AI Gateway, don't fully enforce per-project permissions yet. Per-project permission support for these products is being added over time.

### Inherited and explicit access

On a project's **Project permissions** page, access shows up in one of two ways:

- **Inherited**: Access comes from the user's organization role, not from a grant on this project. Organization Admins always appear as **Admin** with an **Inherited** tag, because they can manage every project.
- **Explicit**: The user was granted a permission directly on this project.

When a user has both an organization-role default and an explicit grant, the higher of the two applies.

## Manage project access with the API

You can manage project access programmatically with the [Neon API](https://neon.com/docs/reference/api). These calls require an [organization API key](https://neon.com/docs/manage/api-keys) with the Admin role. Roles are sent in the request as lowercase values (`viewer`, `editor`, `admin`) and returned in responses as uppercase permission levels (`VIEWER`, `EDITOR`, `ADMIN`). Response fields vary by endpoint; get a member's `member_id` from the [List project members](https://neon.com/docs/manage/user-permissions#list-project-members) response.

The Neon CLI doesn't have a dedicated command for these operations yet. You can call the same routes with the [`neon api`](https://neon.com/docs/cli/api) passthrough command, for example `neon api /projects/{project_id}/members/{member_id}/role -X PUT -F role=editor`.

### List project members

Lists the organization members who have access to a project, with each member's organization role, their explicit project role (if any), and their effective permission.

```bash
curl --request GET \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/members' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY' | jq
```

Example response:

```json
{
  "project_members": [
    {
      "member_id": "abc123de-4567-8fab-9012-3cdef4567890",
      "user_id": "def456gh-7890-1abc-2def-3ghi4567890j",
      "email": "alex@example.com",
      "org_role": "admin",
      "project_role": "admin",
      "org_default_project_permission": "ADMIN",
      "effective_project_permission": "ADMIN",
      "grant_source": "org_role_default"
    }
  ]
}
```

### Set a member's project role

Grants or updates an organization member's role on a project. Send `viewer`, `editor`, or `admin` in the request body.

```bash
curl --request PUT \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/members/{member_id}/role' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY' \
     --header 'content-type: application/json' \
     --data '{"role": "editor"}' | jq
```

Example response:

```json
{
  "project_id": "example-project-12345678",
  "member_id": "abc123de-4567-8fab-9012-3cdef4567890",
  "user_id": "def456gh-7890-1abc-2def-3ghi4567890j",
  "email": "sam@example.com",
  "org_role": "collaborator",
  "project_role": "editor",
  "explicit_project_permission": "EDITOR",
  "effective_project_permission": "EDITOR"
}
```

### Remove a member's project role

Removes a member's explicit role on a project. Their organization role's default access still applies. On success, returns the member's updated access.

```bash
curl --request DELETE \
     --url 'https://console.neon.tech/api/v2/projects/{project_id}/members/{member_id}/role' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $ORG_API_KEY'
```

## Legacy permissions

The model on this page is rolling out to organizations gradually. Until it reaches your organization, you'll see the legacy model: three roles (**Admin**, **Member**, and **Collaborator**), where Members share one access level across every project and access is granted per project through project sharing.

When the new model reaches your organization, everyone keeps the access they have today. No action is required. The legacy roles map as follows:

| Legacy                | New                                                                 |
| --------------------- | ------------------------------------------------------------------- |
| **Admin**             | **Admin** (unchanged)                                               |
| **Member**            | **Editor**, with the same access under a new name                   |
| Project creator       | **Admin** on the projects they created                              |
| Shared-project access | **Editor** on the projects they were shared, so access is preserved |

The new **Collaborator** organization role is not the same as the legacy project-sharing collaborator, even though they share a name:

|                  | Legacy model                                                            | New model                                                                              |
| ---------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Collaborator** | An external user invited to individual projects through project sharing | An organization role that starts with no access, then receives per-project permissions |

Project sharing is being deprecated and will be removed in a future release. For new access, use the **Collaborator** role plus per-project permissions instead.

## Notes and limitations

- **Access can only be added, not restricted**: Per-project permissions raise a user's access above their organization-role baseline; they can't reduce it. There's currently no way to block an Editor from a single project; they keep their baseline access on all projects in the organization.
- **Feedback**: The permissions system may not meet every need for granular control. Share your feedback via the [Feedback](https://console.neon.tech/app/projects?modal=feedback) form or our [Discord feedback channel](https://discord.com/channels/1176467419317940276/1176788564890112042).
- **Email notifications**: For **organization-owned** projects, Neon sends **approaching maximum storage** notification emails to **organization Admins** only, not to other members. Admins are responsible for billing and plan limits at the organization level, which aligns with who can [manage organization billing](https://neon.com/docs/manage/user-permissions#organization-roles).

--- [Document source](https://neon.com/docs/postgres/backup-restore/backups.md) ---

> Summary: Neon supports built-in point-in-time restore (PITR), manual backups using `pg_dump` and `pg_restore`, and automated nightly `pg_dump` exports to AWS S3 via GitHub Actions. Choose PITR for instant recovery without additional tooling; choose `pg_dump` workflows for business continuity, disaster recovery, or compliance. Each strategy links to a dedicated setup guide.

# Backups

An overview of backup strategies for Lakebase Postgres

Last updated: 2026-11-04

**What you will learn:**

- About backup strategies
- About built-in backups with instant restore
- Creating and automating backups using pg_dump

**Related resources**

- [Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore)

Neon supports different backup strategies, which you can use separately or in combination, depending on your requirements.

## Instant restore

With Neon's instant restore capability, also known as point-in-time restore or PITR, you can automatically retain a "history" of changes: up to 6 hours on the Free plan, 7 days on Launch, or 30 days on Scale ([history window limits](https://neon.com/docs/postgres/backup-restore/history-window#defaults-and-plan-limits)). This feature lets you restore your Postgres database and Managed Better Auth data to any specific moment without the need for traditional database backups or separate backup automation. It's ideal if your primary concern is fast recovery after an unexpected event.

With this strategy, the only required action is setting your desired [history window](https://neon.com/docs/postgres/backup-restore/history-window). Please keep in mind that increasing your history window also increases storage, as changes to your data are retained for a longer period.

![History window](https://neon.com/docs/manage/history_retention.png)

To get started, see [Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore).

## Backups with `pg_dump`

For business continuity, disaster recovery, or compliance, you can use standard Postgres tools to back up and restore your database. Neon supports traditional backup workflows using `pg_dump` and `pg_restore`.

To learn how, see [Backups with pg_dump](https://neon.com/docs/manage/backup-pg-dump).

## Automated backups with `pg_dump`

If you need to automate `pg_dump` backups to remote storage, we provide a two-part guide that walks you through setting up an S3 bucket and a GitHub Action to automate `pg_dump` backups on a recurring schedule. You'll also learn how to configure retention settings to manage how long `pg_dump` backups are stored before being deleted.

1. [Create an S3 bucket to store Postgres backups](https://neon.com/docs/manage/backups-aws-s3-backup-part-1)
2. [Set up a GitHub Action to perform nightly Postgres backups](https://neon.com/docs/manage/backups-aws-s3-backup-part-2)

**Note: Backup & Restore Questions?**

If you have questions about backups, please reach out to [Neon Support](https://console.neon.tech/app/projects?modal=support).

--- [Document source](https://neon.com/docs/postgres/backup-restore/branch-restore.md) ---

> Summary: Instant restore (point-in-time restore, PITR) lets you revert a Neon root branch to any earlier state within your plan's history window using a timestamp or Log Sequence Number (LSN). It overwrites all data and schema on all databases in that branch. Use it to recover from accidental data loss or schema changes on production or main branches; child branches do not support PITR. Before restoring, Time Travel Assist lets you run read-only queries against any historical point to confirm the exact restore target. After restoring, a backup branch is automatically created so you can roll back if needed.

# Instant restore

Learn how to revert changes or recover lost data using Neon's instant restore with Time Travel Assist

Last updated: 2026-09-25

**What You'll Learn**

- Restore data to any point in time
- Querying historical data

**Related docs**

- [History window for instant restore](https://neon.com/docs/postgres/backup-restore/history-window)

With Neon's instant restore capability, also known as point-in-time restore or PITR, you can restore a root branch to an earlier state in its own or another root branch's history. You can only point-in-time restore from root branches; child branches do not support instant restore. You can use Time Travel Assist to connect to a specific point in time still covered by your **history window** setting. See [History window](https://neon.com/docs/postgres/backup-restore/history-window), where you can run read-only queries to pinpoint the exact moment you need to restore to. You can also use Schema Diff to get a side-by-side, GitHub-style visual comparison of your selected branches before restoring.

## How instant restore works

### Restore from history

In the Neon Console, select your branch, then open **Postgres database** > **Backup & Restore** and use **Restore from history** to start this flow.

Instant restore is only supported for root branches. You can revert a root branch to an earlier point in time in its own or another root branch's history, using time and date or Log Sequence Number (LSN). For example, you can revert to a state just before a data loss occurred.

![branch restore to timestamp](https://neon.com/docs/guides/branch-restore_feature.png)

The default **history window** for a Neon project differs by plan. You can revert a root branch to any time within that window using **instant restore**, down to the millisecond. See [History window](https://neon.com/docs/postgres/backup-restore/history-window).

A few key points to keep in mind about the restore operation:

- [Restore backups are created automatically in case you make a mistake](https://neon.com/docs/postgres/backup-restore/branch-restore#automatic-backups)
- [Current data is overwritten](https://neon.com/docs/postgres/backup-restore/branch-restore#overwrite-not-a-merge)
- [All databases on a branch are restored](https://neon.com/docs/postgres/backup-restore/branch-restore#changes-apply-to-all-databases)
- [Connections to the selected branch are temporarily interrupted](https://neon.com/docs/postgres/backup-restore/branch-restore#connections-temporarily-interrupted)

#### Automatic backups

In case you need to rollback a restore, Neon preserves the branch's final state before the restore operation in an automatically created backup branch, which takes the following format:

```
{branch_name}_old_{head_timestamp}
```

You can use this backup to rollback the restore operation if necessary. The backup branches are listed on the **Branches** page in the Neon Console among your other branches.

When you restore a root branch (like `production`), both the restored branch and the backup branch become separate root branches with no parent-child relationship.

**Note:** Backup branches created when restoring root branch from another branch cannot be deleted. See [Deleting backup branches](https://neon.com/docs/postgres/backup-restore/branch-restore#deleting-backup-branches) for details.

![Backup branch created after restore](https://neon.com/docs/guides/branch_restore_backup.png)

#### Overwrite, not a merge

It is important to understand that whenever you restore a branch, you are performing a _complete_ overwrite of the database timeline, not a merge or refresh. All Postgres data and schema on your branch, along with Managed Better Auth data stored in the `neon_auth` schema, are replaced with the contents from the historical source. There is no way to exclude `neon_auth` from a restore, though the backup branch created by the restore still holds your earlier auth state. All data changes from the selected restore point onwards are excluded from the branch.

Object Storage is not part of the database timeline, so a database restore does not revert its contents. The same is true of Functions. This differs from [Reset from parent](https://neon.com/docs/guides/reset-from-parent), which does reset a branch's Object Storage to the parent's current state.

#### Changes apply to all databases

A reminder that in Neon's [object hierarchy](https://neon.com/docs/manage/overview), a branch can include any number of databases. Keep this in mind when restoring branches. For example, let's say you want to restore lost data in a given database. If you restore your branch to an earlier point in time before the data loss occurred, the operation applies to _all_ databases on the branch, not just the one you are troubleshooting. You can expect the restore operation to last a few seconds.

In general, Neon recommends that you avoid creating too many databases in a single Neon project. If you have multiple, distinct applications, each one deserves its own Neon project. A good rule of thumb: use one Neon project per source code repository.

#### Connections temporarily interrupted

Existing connections to the selected branch are temporarily interrupted during the restore operation. However, your connection details do not change. Applications can automatically re-establish their database connections as soon as the restore operation is finished.

#### Technical details

Neon is open source and built in public, so if you are interested in understanding the technical implementation behind instant restore, see the details below.

<details>

<summary>View technical details</summary>

Similar to the manual restore operation using the Neon Console and API described [here](https://neon.com/docs/guides/branching-pitr), the Restore operation performs a similar set of actions, but automatically:

1. On initiating a restore action, Neon builds a new point-in-time branch by matching your selected timestamp to the corresponding LSN of the relevant entries in the shared WAL record.
2. The compute for your initial branch is moved to this new branch so that your connection string remains stable.
3. We rename your new branch to the exact name as your initial branch, so the effect is seamless; it looks and acts like the same branch.
4. Your initial branch, which now has no compute attached to it, is renamed to _branch_name_old_head_timestamp_ to keep the pre-restore branch available should you need to roll back. When restoring a root branch, both the new branch and the backup branch become root branches with no parent.

</details>

### Time Travel Assist

Use Time Travel Assist to make sure you've targeted the correct restore point before you restore your branch.

See [Time Travel Assist](https://neon.com/docs/postgres/backup-restore/time-travel-assist) to learn more.

## How to use instant restore

You can use the Neon Console, CLI, or API to restore root branches. The source branch for a point-in-time restore (the branch whose history you restore from) must also be a root branch.

**Console**

### Restoring from history

Use the **Restore** page to restore a root branch to an earlier timestamp in its own or another root branch's history.

First, select the **Branch to restore**. This is the target branch for the restore operation (must be a root branch).

![branch restore to timestamp](https://neon.com/docs/guides/branch_restore_timestamp.png)

#### To restore a branch from its own history:

1. Make sure the **From history** tab is selected.

2. Choose your timestamp or switch to LSN.

3. Click **Next**.

   A confirmation window opens giving you details about the pending restore operation. Review these details to make sure you've made the correct selections.

4. Click **Restore** to complete the operation.

#### To restore from another branch:

1. Switch to the **From another branch** tab.

2. Select the root branch that you want to restore data from (only root branches support point-in-time restore).

3. By default, the operation pulls the latest data from the source branch. If you want to pull from an earlier point in time, disable **Restore from latest data (head)**.

   The timestamp selector will appear.

4. Choose your timestamp or switch to the LSN input.

5. Click **Next**, confirm the details of the operation, then click **Restore** to complete.

All databases on the selected branch are instantly updated with the data and schema from the chosen point in time. From the **Branches** page, you can now see a backup branch was created with the state of the branch at the restore point in time.

**Note:** Backup branches created when restoring a root branch from another branch cannot be deleted. See [Deleting backup branches](https://neon.com/docs/postgres/backup-restore/branch-restore#deleting-backup-branches) for details.

![branch restore backup branch](https://neon.com/docs/guides/branch_restore_backup_file.png)

**CLI**

Using the CLI, you can restore a root branch to an earlier point in its own history or another root branch's history using the following command:

```bash
neon branches restore <target id|name> <source id|name @ timestamp|lsn>
```

In the `target id|name` field, specify the ID or name of the branch you want to restore. In the `source id|name timestamp|lsn` field, specify the source branch you want to restore from (mandatory), along with the point-in-time identifier (optional), which can be either an RFC 3339-formatted timestamp or the LSN. If you omit the point-in-time identifier, the operation defaults to the latest data (HEAD) for the source branch. Concatenate the source identifier and time identifier with `@`: for example, `development@2023-12-12T12:00:00Z`.

#### Restore a root branch to its own history

If you want to restore a root branch to an earlier point in time, use the syntax `^self` in the `<source id|name>` field. For example:

```bash
neon branches restore development ^self@2024-01-01T00:00:00Z --preserve-under-name development_old
```

This command resets the target branch `development` to its state at the start of 2024. The command also preserves the original state of the branch in a backup file called `development_old` using the `preserve-under-name` parameter (mandatory when resetting to self).

#### Restore from parent

If you want to restore a target branch from its parent, you can use the special syntax `^parent` in the `<source id|name>` field. For example:

```bash
neon branches restore development ^parent
```

This command will restore the target branch `development` to the latest data (HEAD) of its parent branch.

#### Restore to another root branch's history

Here is an example of a command that restores a root branch to an earlier point in time of another root branch's history:

```bash
neon branches restore development production@0/12345
```

This command will restore the target branch `development` to an earlier point in time from the source branch `main`, using the LSN `0/12345` to specify the point in time. If you left out the point-in-time identifier, the command would default to the latest data (HEAD) for the source branch `main`.

For full CLI documentation for `branches restore`, see [branches restore](https://neon.com/docs/cli/branches#restore).

**API**

To restore a branch using the API, use the endpoint below. For point-in-time restore (when you specify a timestamp or LSN), the source branch must be a root branch.

```bash
POST /projects/{project_id}/branches/{branch_id_to_restore}/restore
```

This endpoint lets you restore a branch using the following request parameters:

| Parameter                 | Type     | Required | Description                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **source\_branch\_id**    | `string` | Yes      | The ID of the branch you want to restore from.<br/><br/>To restore to the latest data (head), omit `source_timestamp` and `source_lsn`.<br/><br/>To restore a branch to its own history (`source_branch_id` equals branch's own Id), you must include:<br/>- A time period: `source_timestamp` or `source_lsn`<br/>- A backup branch: `preserve_under_name`                           |
| **source\_lsn**           | `string` | No       | A Log Sequence Number (LSN) on the source branch. The branch will be restored with data up to this LSN.                                                                                                                                                                                                                                                                               |
| **source\_timestamp**     | `string` | No       | A timestamp indicating the point in time on the source branch to restore from. Use RFC 3339 format for the date-time string.                                                                                                                                                                                                                                                          |
| **preserve\_under\_name** | `string` | No       | If specified, a backup is created: the latest version of the branch's state is preserved under a new branch using the specified name.<br/><br/>**Note:** This field is required if:<br/>- The branch has children. All child branches will be moved to the newly created branch.<br/>- You are restoring a branch to its own history (`source_branch_id` equals the branch's own ID). |

#### Restoring a branch to its own history

In the following example, we are restoring branch `br-twilight-river-31791249` to an earlier point in time, `2024-02-27T00:00:00Z`, with a new backup branch named `backup-before-restore`. Note that the branch id in the `url` matches the value for `source_branch_id`.

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/floral-disk-86322740/branches/br-twilight-river-31791249/restore \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "source_branch_id": "br-twilight-river-31791249",
  "source_timestamp": "2024-02-27T00:00:00Z",
  "preserve_under_name": "backup-before-restore"
}
' | jq
```

### Restoring to the latest data from another branch

In this example, we are restoring a development branch `dev/alex` (branch ID `br-twilight-river-31791249`) to the latest data (head) of its parent branch `br-jolly-star-07007859`. Note that we don't include any time identifier or backup branch name; this is a straight reset of the branch to the head of its parent.

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/floral-disk-86322740/branches/br-twilight-river-31791249/restore \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "source_branch_id": "br-jolly-star-07007859"}
' | jq
```

### Restoring to the earlier state of another branch

In this example, we are restoring branch `dev/jordan` (branch ID `br-damp-smoke-91135977`) to branch `dev/alex` (branch ID `br-twilight-river-31791249`) at the point in time of `Feb 26, 2024 12:00:00.000 AM`.

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects/floral-disk-86322740/branches/br-damp-smoke-91135977/restore \
     --header 'Accept: application/json' \
     --header "Authorization: Bearer $NEON_API_KEY" \
     --header 'Content-Type: application/json' \
     --data '
{
  "source_branch_id": "br-jolly-star-07007859",
  "source_timestamp": "2024-02-26T12:00:00Z"
}
' | jq
```

To make sure you choose the right restore point, we encourage you to use [Time Travel Assist](https://neon.com/docs/postgres/backup-restore/time-travel-assist) before running a restore job, but the backup branch is there if you need it.

If you need to revert your changes, use [Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore) again and select the backup branch as the source, since the backup is not a parent branch.

## Deleting backup branches

Backup branches are deletable except in two cases:

- When a root branch is restored from another branch, the backup branch, which is the original root, cannot be deleted.
- A backup branch cannot be deleted if it has child branches.

To delete a backup branch:

1. Navigate to the **Branches** page.

2. Find the backup branch you want to delete. It will have a name with the following format:

   ```
   {branch_name}_old_{head_timestamp}
   ```

3. Select **Delete** from the menu.

If you cannot delete a backup branch, you can still free up its storage space. If you're certain you no longer need the data in a backup branch, connect to the branch and drop its databases or tables. **Be sure to connect to the correct branch when doing this**. You can connect to a backup branch just like any other branch via the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or an SQL client like [psql](https://neon.com/docs/connect/query-with-psql-editor).

To keep your **Branches** page organized, consider renaming backup branches that you plan to keep. For example, you can prefix their names with a `z` to move them to the bottom of the list. See [Rename a branch](https://neon.com/docs/manage/branches#rename-a-branch) for details.

## Billing considerations

There are minimal impacts to billing from the instant restore and Time Travel Assist features:

- **Instant restore:** The backup branches created when you restore a branch do add to your total number of branches and incur storage costs, but since they do not have a compute attached, they do not add to compute costs.
- **Time Travel Assist:** Costs related to Time Travel queries are minimal. See [Billing considerations](https://neon.com/docs/postgres/backup-restore/time-travel-assist#billing-considerations).

## Limitations

- **Instant restore is only supported for root branches.** You can only point-in-time restore from root branches (like `production` or `main`). Child branches do not support instant restore. When you restore a root branch, both the restored branch and backup branch become separate root branches with no parent-child relationship.
- Deleting backup branches is only supported in certain cases. See [Deleting backup branches](https://neon.com/docs/postgres/backup-restore/branch-restore#deleting-backup-branches) for details.
- Instant restore (PITR) is currently not supported on branches created from a snapshot restore. If you restore a snapshot to create a new branch, you cannot perform point-in-time restore on that branch at this time. Attempting to do so will return an error: `restore from snapshot on target branch is still ongoing`.

--- [Document source](https://neon.com/docs/postgres/backup-restore/history-window.md) ---

> Summary: The history window is a per-project setting (Console: Settings → Instant restore) that controls how far back Neon retains WAL records for instant restore, Time Travel queries, and branching from past states. Free plans cap retention at 6 hours (1 GB), Launch plans allow up to 7 days, and Scale plans allow up to 30 days. Retained WAL is billed as History storage at $0.20/GB-month. Set the window with the Console slider or the history_retention_seconds API property. Setting it to zero disables instant restore and Time Travel entirely.

# History window

Control how long Neon keeps change history for instant restore, Time Travel, and branching from past states

Last updated: 2026-08-24

**Instant restore** is Neon's point-in-time recovery feature: you can roll a root branch's database timeline back to an earlier state without copying the whole database. Instant restore (and Time Travel queries, branching from past states, and snapshots) rely on Neon retaining a **history** of changes. The **history window** is the Console control—on **Settings → Postgres**—that sets how long that change history is kept, which defines how far back instant restore and the other features can reach.

## Defaults and plan limits

| Plan   | Default | Maximum                             |
| ------ | ------- | ----------------------------------- |
| Free   | 6 hours | 6 hours (capped at 1 GB of history) |
| Launch | 1 day   | 7 days                              |
| Scale  | 1 day   | 30 days                             |

A longer history window means:

- Instant restore can reach further back in time
- Time Travel queries can reach further back
- You can create branches from older historical states
- More WAL records are stored, increasing **History** usage (the change history metered for instant restore on your bill)

## How it works

Neon stores a continuous record of all changes to your data in the form of Write-Ahead Log (WAL) records. The history window setting determines the retention period for this history, which instant restore and related features use.

WAL records that fall outside the configured history window are automatically removed and stop contributing to your project's storage costs.

## Storage and billing

The history window directly affects **History** on your usage dashboard (billed as instant restore storage on invoices). Neon retains WAL records for that duration. The more history you retain, the more storage you use, and the higher those charges.

| Plan   | Cost                       |
| ------ | -------------------------- |
| Free   | No charge (capped at 1 GB) |
| Launch | $0.20/GB-month             |
| Scale  | $0.20/GB-month             |

This is separate from your regular storage charges for branch data. You're billed for:

- **Storage**: Your actual data size (root branches) or the minimum of accumulated changes or logical data size (child branches)
- **History**: The WAL history retained within your history window for instant restore

**Understand the trade-offs:** Shortening the history window decreases History usage and cost but limits how far back **instant restore** (and Time Travel) can go. Set the window to match your recovery needs.

See [Cost optimization](https://neon.com/docs/introduction/cost-optimization#instant-restore-storage).

## Configure the history window for instant restore

Changing the history window affects **all branches** in your project.

**Console**

1. Select your project.

2. Go to **Settings** > **Postgres**.

3. Under **History window**, use the slider to choose how long to keep change history (used for instant restore, Time Travel, and branching from past states). You can open **history storage** from the description on that page for details.

4. Click **Save**.

**API**

Use the `history_retention_seconds` property in the project settings:

```bash
curl -X PATCH 'https://console.neon.tech/api/v2/projects/{project_id}' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "project": {
      "history_retention_seconds": 604800
    }
  }'
```

The value is specified in seconds:

- 6 hours = 21600
- 1 day = 86400
- 7 days = 604800
- 30 days = 2592000

**Note:** Reducing the history window to zero minimizes History usage and cost but disables **instant restore** and Time Travel queries.

## Production recommendations

For production workloads, consider extending the history window to 7 days so **instant restore** can reach further back. This provides:

- Protection against data loss from human or application errors that may go unnoticed for several days
- Compliance with retention requirements that may apply to your industry

See [Getting ready for production](https://neon.com/docs/get-started/production-checklist#size-the-history-window-for-instant-restore).

## Related features

The history window setting bounds how far back these capabilities can go:

- [Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore): Restore a root branch to an earlier point in time
- [Time Travel](https://neon.com/docs/postgres/backup-restore/time-travel-assist): Query historical data
- [Branching](https://neon.com/docs/introduction/branching): Create branches from past states
- [Snapshots](https://neon.com/docs/guides/backup-restore): Capture and restore from specific points

**Note:** Instant restore and the history window apply to branch data (point-in-time recovery). That is different from the **deletion recovery period**, which allows you to recover (undelete) an entire deleted project. For information about recovering deleted projects, see [Project recovery](https://neon.com/docs/manage/projects#recover-a-deleted-project).

--- [Document source](https://neon.com/docs/postgres/backup-restore/time-travel-assist.md) ---

> Summary: Time Travel in Neon lets you run read-only queries against any point in time within your project's instant restore history window. A temporary branch is created for the query and automatically deleted 30 seconds after you stop querying. Use it to investigate data anomalies, verify a restore point before committing a branch restore, or retrieve historical row states without altering production data. Access Time Travel from the SQL Editor, the Backup & Restore page, or the Neon CLI using RFC 3339 timestamps or Log Sequence Numbers (LSN).

# Time Travel

Learn how to query point-in-time connections against your data's history

Last updated: 2026-08-24

To help review your data's history, Time Travel lets you connect to any selected point in time still covered by your project's **history window** (the retention configured for **instant restore**) and then run queries against that connection. Time Travel is part of Neon's **instant restore** feature, which maintains a history of changes through Write-Ahead Log (WAL) records.

**Note:** Time Travel queries access historical Postgres database state, including Managed Better Auth data (stored in the `neon_auth` schema). Object Storage buckets, Functions, and AI Gateway configuration are not part of the database timeline and cannot be queried historically.

You can use Time Travel from two places in the Neon Console, and from the Neon CLI:

- **SQL Editor** — Time Travel is built into the SQL editor letting you switch between queries of your current data and previous iterations of your data in the same view.
- **Backup & Restore** — Time Travel Assist is built into **Restore from history** (part of **instant restore**) so you can verify the restore point before you restore a branch.
- **Neon CLI** — Use the Neon CLI to quickly establish point-in-time connections for automated scripts or command-line-based data analysis.

## How Time Travel works

Time Travel uses Neon's instant branching capability to create a temporary branch and compute at the selected point in time, which are automatically removed once you are done querying against this point-in-time connection. The computes are ephemeral: they are not listed on the **Branches** page or in a CLI or API list branches request.

However, you can see the history of operations related to the creation and deletion of branches and ephemeral computes on the **Operations** page:

- start_compute
- create_branch
- delete_timeline
- suspend_compute

### How long do ephemeral endpoints remain active

The ephemeral endpoints are created with a .50 CU compute size (2 GB of RAM). An ephemeral compute remains active for as long as you keep running queries against it. After 30 seconds of inactivity, the timeline is deleted and the endpoint is removed.

### History window

Time Travel queries are limited to the same span of time as **instant restore**: you cannot select a time outside your project's **history window**.

To learn how to configure the history window and see plan limits, see [History window](https://neon.com/docs/postgres/backup-restore/history-window).

### Data integrity

Time Travel only allows non-destructive read-only queries. You cannot alter historical data in any way. If you try to run any query that could alter historical data, you will get an error message like the following:

![time travel error message](https://neon.com/docs/guides/time_travel_error.png)

### Time Travel with the SQL Editor

Time Travel in the SQL Editor offers a non-destructive way to explore your database's historical data through read-only queries. By toggling Time Travel in the editor, you switch from querying your current data to querying against a selected point within your **history window**.

You can use this feature to help with scenarios like:

- Investigating anomalies
- Assessing the impact of new features
- Troubleshooting
- Compliance auditing

Here's an example of a completed Time Travel query.

![time travel from sql editor](https://neon.com/docs/guides/time_travel_sql.png)

### Time Travel Assist with instant restore

Time Travel Assist is also available from **Backup & Restore** under **Restore from history**, as part of [Instant restore](https://neon.com/docs/postgres/backup-restore/branch-restore). Before completing a restore operation, it's a good idea to use Time Travel Assist to verify that you've targeted the correct restore point.

An SQL editor is built into the **Restore** page for this purpose. When you make your branch and timestamp selection to restore a branch, this selection can also be used as the point-in-time connection to query against.

Here is an example of a completed query:

![Time travel assist](https://neon.com/docs/guides/time_travel_assist.png)

## How to use Time Travel

Here is how to use Time Travel from the **SQL Editor**, from **Backup & Restore** (**Restore from history**), or from the **CLI**:

**SQL Editor**

1. In the Neon Console, select your branch, then open **Postgres database** > **SQL Editor**.

2. Use the **Time Travel** (🕣) icon to enable querying against an earlier point in time.

   ![Time Travel toggle](https://neon.com/docs/get-started/time_travel_sql_editor.png)

3. Use the Date & Time selector to choose a point within your **history window**.

4. Write your read-only query in the editor, then click **Run**. You don't have to include time parameters in the query; the query is automatically targeted to your selected timestamp.

**Instant restore**

1. In the Neon Console, select your branch, then open **Postgres database** > **Backup & Restore** and go to **Restore from history**.

2. Select the branch you want to query against, then select a timestamp, the same as you would to [Restore a branch](https://neon.com/docs/postgres/backup-restore/time-travel-assist#restore-a-branch-to-an-earlier-state).

   ![time travel selection](https://neon.com/docs/guides/time_travel_restore_select.png)

   This makes the selection for Time Travel Assist. Notice the updated fields above the SQL Editor show the **branch** and **timestamp** you just selected.

   ![Time travel assist](https://neon.com/docs/guides/time_travel_show_selected.png)

3. Check that you have the right database selected to run your query against. Use the database selector under the SQL Editor to switch to a different database for querying against.

   ![time travel select db](https://neon.com/docs/guides/time_travel_db_select.png)

4. Write your read-only query in the editor, then click **Query at timestamp** to run the query. You don't have to include time parameters in the query; the query is automatically targeted to your selected timestamp.

   If your query is successful, you will see a table of results under the editor.

   ![time travel results](https://neon.com/docs/guides/time_travel_results.png)

**CLI**

Using the Neon CLI, you can establish a connection to a specific point in your branch's history. To get the connection string, use the following command:

```bash
neon connection-string <branch>@<timestamp|LSN>
```

In the `branch` field, specify the name of the branch you want to connect to. Omit the `branch` field to connect to your default branch. Replace the `timestamp|LSN` field with the specific timestamp (in RFC 3339 format) or Log Sequence Number for the point in time you want to access.

Example:

```bash
neon connection-string main@2024-04-21T00:00:00Z
postgresql://alex:AbC123dEf@br-broad-mouse-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require&options=neon_timestamp%3A2024-04-21T00%3A00%3A00Z
```

### Connect directly with psql

Appending `--psql` to the command for a one-step psql connection. For example, to connect to `main` at its state on Jan 1st, 2024:

```bash
neon connection-string main@2024-01-01T00:00:00Z --psql
```

Here is the same command using aliases:

```bash
neon cs main@2024-01-01T00:00:00Z --psql
```

### Query at Specific LSNs

For more granular control, you can also establish the connection using a specific LSN.

Example:

```bash
neon cs main@0/234235
```

This retrieves the connection string for querying the 'main' branch at a specific Log Sequence Number, providing access to the exact state of the database at that point in the transaction log.

### Include project ID for multiple projects

If you are working with multiple Neon projects, specify the project ID to target the correct project:

```bash
neon connection-string <branch>@<timestamp|LSN> --project-id <project id>
```

Example:

```bash
neon cs main@2024-01-01T00:00:00Z --project-id noisy-pond-12345678
```

Alternatively, you can set a durable project context that remains active until you remove or change the context:

```bash
neon set-context --project-id <project id>
```

Read more about getting connection strings from the CLI in [Neon CLI commands — connection-string](https://neon.com/docs/cli/connection-string), and more about setting contexts in [CLI - set-context](https://neon.com/docs/cli/set-context).

## Billing considerations

The ephemeral endpoints used to run your Time Travel queries do contribute to your consumption usage totals for the billing period, like any other active endpoint that consumes resources.

A couple of details to note:

- The endpoints are shortlived. They are suspended 30 seconds after you stop querying.
- Ephemeral endpoints are created with a .50 CU compute size (2 GB of RAM). This is Neon's second smallest compute size. For more about compute sizes in Neon, see [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

--- [Document source](https://neon.com/docs/postgres/overview.md) ---

> Summary: Lakebase Postgres is a fully managed, serverless PostgreSQL database compatible with any Postgres driver, ORM, or framework. Key features include autoscaling, scale to zero, database branching, instant point-in-time restore, and read replicas. Use this page as a starting point to create a project, connect an application, or explore Neon-specific features.

# Lakebase Postgres

The serverless database in the Neon backend

Last updated: 2026-10-15

Serverless Postgres with storage and compute separated, so your database branches instantly, scales up with demand, and down to zero when idle.

[View prompt](https://neon.com/prompts/postgres-landing.md)

## Get started

- [Create a project](https://neon.com/docs/get-started/signing-up): Sign up for Neon and create your first project in minutes.
- [Connect to your database](https://neon.com/docs/get-started/connect-neon): Get your connection string and connect from any Postgres-compatible app.
- [Connect your framework](https://neon.com/docs/get-started/frameworks): Step-by-step guides for Next.js, Django, Rails, and more.
- [Query with the SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor): Run SQL queries directly in the Neon Console, no client required.

## Explore features

- [Autoscaling](https://neon.com/docs/introduction/autoscaling): Automatically scale compute up and down with your workload.
- [Branching](https://neon.com/docs/introduction/branching): Create isolated copies of your database for every branch, preview, and test run.
- [Realtime](https://neon.com/docs/introduction/live-sql-queries): Subscribe to data in realtime with live SQL queries and end-to-end, type-safe reactivity.
- [Read replicas](https://neon.com/docs/introduction/read-replicas): Offload reads to replicas and scale read traffic independently.
- [Instant restore](https://neon.com/docs/introduction/branch-restore): Restore your database to any point in time within your history window.
- [Connection pooling](https://neon.com/docs/connect/connection-pooling): Handle thousands of concurrent connections without exhausting your database.
- [Serverless driver](https://neon.com/docs/serverless/serverless-driver): Optimized driver for serverless and edge runtimes using HTTP or WebSockets.

## About Lakebase Postgres

Lakebase Postgres is fully managed and compatible with any Postgres driver, ORM, or framework. Key capabilities include:

- **Autoscaling.** Compute scales up and down automatically with your workload.
- **Scale to zero.** Idle databases suspend, so you only pay for what you use.
- **Branching.** Create isolated, instant copies of your database for agents, development, testing, and CI.
- **Realtime.** Subscribe to data in realtime with live SQL queries.
- **Instant restore.** Restore to any point in time within your history window.
- **Read replicas.** Scale your app by offloading read traffic to read replicas.

--- [Document source](https://neon.com/docs/postgresql/index-types.md) ---

> Summary: Postgres supports several index types, each targeting different query patterns: B-tree for equality and range queries, Hash for exact-match lookups, GiST for spatial and full-text data, GIN for arrays and inverted indexes, and BRIN for ordered large tables. Use this page to choose the right index type and learn CREATE INDEX syntax, trade-offs for write overhead and storage, and advanced strategies such as multicolumn, partial, and expression indexes.

# Postgres indexes

Optimize query performance with indexes in Postgres

Last updated: 2026-07-31

Indexes speed up query performance in relational databases like Postgres by allowing the database engine to quickly locate and retrieve specific rows. In the absence of an index, Postgres must scan the entire table to find the rows that satisfy the query conditions.

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

This guide explores the most common index types in Postgres, including B-tree, Hash, GiST, GIN, and BRIN indexes. You'll learn how to create these indexes, understand the trade-offs involved with each, and how to use them effectively.

**Note:** While indexes can dramatically improve query performance, they consume additional storage and also add overhead to write operations (since Postgres needs to keep them synchronized with the table). It's important to use indexes judiciously and monitor their impact on your database's overall performance.

## B-tree Indexes

B-tree (Balanced Tree) is the default index type in Postgres and is suitable for most common scenarios. B-tree indexes organize data in a tree structure, allowing for efficient searching, insertion, and deletion. The tree is kept balanced, so all reads need to traverse a similar number of rows, providing consistent performance.

### Create a B-tree Index in Postgres

Consider a simple example using a `users` table, which includes a `username` column that is unique and sortable. We'll create a B-tree index on this column.

```sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(100) UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO users (username, email) VALUES
    ('john_doe', 'john@example.com'),
    ('jane_smith', 'jane@example.com'),
    ('bob_johnson', 'bob@example.com');

CREATE INDEX idx_users_username ON users USING btree (username);
```

Note that the `USING btree` clause is optional. If you omit it, Postgres will use the default index type, which is B-tree. For example, the following query creates a B-tree index on the `created_at` column:

```sql
CREATE INDEX idx_users_timestamp ON users (created_at);
```

### Use B-tree Indexes in Postgres

B-tree indexes are efficient for both equality and range queries on sortable data. Use them for columns frequently appearing in `WHERE` clauses, `JOIN` conditions, and `ORDER BY` clauses.

```sql
-- Equality search
SELECT * FROM users WHERE username = 'john_doe';

-- Range query
SELECT * FROM users WHERE username > 'j' AND username < 'k';

-- Prefix search
SELECT * FROM users WHERE username LIKE 'john%';

-- Sorting
SELECT * FROM users ORDER BY username;
```

For columns with a large number of distinct values, and where queries typically filter for a small set of values, hash indexes can be more efficient than B-tree indexes. Additionally, for tables with a small number of rows, the Postgres query planner may choose to do a sequential scan instead of using the index.

## Hash Indexes

Hash indexes compute a hash value for each row value in the indexed column, and store the hash along with the value in a hash table. This provides constant-time lookup for equality comparisons.

### Create a Hash Index in Postgres

We can create a hash index on the `email` column of our `users` table by running the following query:

```sql
CREATE INDEX idx_users_email_hash ON users USING hash (email);
```

### Use Hash Indexes in Postgres

Hash indexes are most effective for exact match queries on columns with a large number of distinct values:

```sql
SELECT * FROM users WHERE email = 'john@example.com';
```

This is specifically useful for columns that store attributes like a username or email address. However, hash indexes don't support range queries or sorting like B-tree indexes.

## GiST Indexes

GiST (Generalized Search Tree) indexes provide a flexible framework for implementing various indexing strategies. They work by recursively dividing data into nested subsets. While a B-tree index divides data based on comparison semantics (equal-to, less-than, greater-than), the nodes of a GiST tree each define a general boolean predicate, that all entries in its subtree must satisfy.

This makes it useful for complex data types and queries, such as geometric data or full-text search where the regular comparison operators might not make sense. For example, a GiST index can be used to find all locations within a certain distance of a point, or to do a word proximity search over full-text documents.

### Create a GiST Index in Postgres

The following query creates a table for storing geographical locations and indexes it using GiST:

```sql
CREATE EXTENSION IF NOT EXISTS postgis;

CREATE TABLE locations (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    location GEOGRAPHY(POINT, 4326)
);

INSERT INTO locations (name, location) VALUES
    ('Eiffel Tower', ST_MakePoint(2.2945, 48.8584)),
    ('Statue of Liberty', ST_MakePoint(-74.0445, 40.6892)),
    ('Sydney Opera House', ST_MakePoint(151.2153, -33.8568));

CREATE INDEX idx_locations_gist ON locations USING gist (location);
```

### Use GiST Indexes in Postgres

GiST indexes can significantly speed up spatial queries. For example, the following query finds all locations within 5000 meters of a point:

```sql
-- Find locations within 5000 meters of a point
SELECT name, ST_AsText(location)
FROM locations
WHERE ST_DWithin(location, ST_MakePoint(2.3522, 48.8566)::geography, 5000);
```

While highly versatile, especially for spatial and full-text search data, GiST indexes can be slower to build and update compared to more specialized index types.

## GIN Indexes

Generalized Inverted Indexes (GIN) are useful for indexing composite values, such as arrays or full-text search documents. GIN indexes store a separate entry for each component value (for example, each array element or each word in a text document). This is similar to an `inverted index` typically used in text search engines, except that it can be extended to handle data types other than text.

### Create a GIN Index in Postgres

The following query creates a table with an array column and indexes it using GIN:

```sql
CREATE TABLE products (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    tags TEXT[]
);

INSERT INTO products (name, tags) VALUES
    ('Smartphone', ARRAY['electronics', 'mobile', 'communication']),
    ('Laptop', ARRAY['electronics', 'computer', 'portable']),
    ('Headphones', ARRAY['electronics', 'audio', 'accessories']);

CREATE INDEX idx_products_tags ON products USING gin (tags);
```

### Use GIN Indexes in Postgres

GIN indexes are particularly effective for `contains` queries on array and full-text data:

```sql
-- Find products with specific tags
SELECT * FROM products WHERE tags @> ARRAY['electronics', 'portable'];

-- Find products with any of the given tags
SELECT * FROM products WHERE tags && ARRAY['audio', 'mobile'];
```

However, GIN indexes can be slower to build/update and require more storage space compared to more specialized index types.

## BRIN Indexes

Block Range Indexes (BRIN) are designed for very large tables where values in a column has some natural ordering. These indexes store summaries for ranges of data blocks, making them extremely compact. At query time, BRIN indexes can be used to quickly locate the blocks containing the values you are looking for.

### Create a BRIN Index in Postgres

The following query creates a table for storing temperature readings and indexes it using BRIN:

```sql
CREATE TABLE temperature_readings (
    id SERIAL PRIMARY KEY,
    sensor_id INT NOT NULL,
    temperature DECIMAL(5,2) NOT NULL,
    timestamp TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO temperature_readings (sensor_id, temperature, timestamp)
SELECT
    (random() * 100)::int,
    (random() * 50 - 10)::decimal(5,2),
    timestamp '2024-01-01 00:00:00' + (random() * (interval '365 days'))
FROM generate_series(1, 100000);

CREATE INDEX idx_temperature_brin ON temperature_readings USING brin (timestamp);
```

### Use BRIN Indexes in Postgres

BRIN indexes are especially effective for range queries on large datasets, such as the following example:

```sql
-- Find temperature readings within a specific date range
SELECT *
FROM temperature_readings
WHERE timestamp BETWEEN '2024-03-01' AND '2024-03-31';
```

While a BRIN index offers significant space savings and fast index creation, it provides less precise results and may require more disk access during queries compared to other index types.

## Advanced Indexing Strategies

We covered the most common index types in Postgres above, where each index was created on a specific column. Postgres also supports some advanced indexing techniques that can be applied to most of the fundamental index types (primarily B-tree) to further optimize query performance, for specific data access patterns.

### Multicolumn Indexes

Multicolumn indexes can be useful when queries frequently filter or sort by multiple columns together. For example, the following query creates a multicolumn index on the `temperature_readings` table:

```sql
CREATE INDEX idx_temp_sensor_timestamp ON temperature_readings (sensor_id, timestamp);
```

Multicolumn indexes can improve performance for queries that filter on multiple columns:

```sql
-- Find temperature readings from sensor 42 within a specific date range
SELECT *
FROM temperature_readings
WHERE sensor_id = 42
  AND timestamp BETWEEN '2024-03-01' AND '2024-03-31'
ORDER BY timestamp;
```

Note that a multicolumn index is also helpful for queries that filter on a subset of the indexed columns, as long as it is in the same order as the index. For example, the multicolumn index we created above accelerates both queries that filter on `sensor_id` alone, and those that filter on `sensor_id` and `timestamp` together:

```sql
-- Find maximum temperature readings from sensor 42
SELECT MAX(temperature)
FROM temperature_readings
WHERE sensor_id = 42;
```

However, a query that only filters on the `timestamp` column will not benefit from the index. Separate indexes on each column might be more efficient, depending on which queries are more frequent.

### Partial Indexes

Partial indexes cover only a subset of a table's data, which can be useful for frequently queried subsets of data. For example, the following query creates a partial index on the `temperature_readings` table for high temperatures:

```sql
CREATE INDEX idx_high_temp ON temperature_readings (temperature)
WHERE temperature > 30;
```

Partial indexes can significantly speed up queries on the indexed subset:

```sql
SELECT *
FROM temperature_readings
WHERE temperature > 35;
```

This can be useful when creating an index on the full column is too expensive due to the size of the data, and most queries only need to access a subset of it.

### Indexes on Expressions

Postgres also supports creating indexes on expressions, not just raw column values. For example, the following query creates an index on the lowercase version of the `username` in our `users` table:

```sql
CREATE INDEX idx_lower_username ON users (LOWER(username));
```

This index can improve performance for case-insensitive searches:

```sql
SELECT * FROM users WHERE LOWER(username) = 'john_doe';
```

This is useful when you frequently query based on some computation or function of a column. It saves the database engine from having to perform the computation for each row in the table at query time, which can be expensive for large tables.

## Conclusion

Understanding the different index types and their use cases can significantly improve the efficiency of your database queries. However, remember to monitor the impact of indexes on your overall database performance, as they do introduce some overhead for write operations and storage.

## Resources

- [Postgres Documentation: Index Types](https://www.postgresql.org/docs/current/indexes-types.html)
- [Postgres: Examining Index Usage](https://www.postgresql.org/docs/current/indexes-examine.html)

--- [Document source](https://neon.com/docs/postgresql/introduction.md) ---

> Summary: Postgres guides index for Neon, linking to reference and tutorial content on data types, extensions, functions, indexes, query performance, and version upgrades. Choose this page when looking for a Postgres topic within Neon's managed environment rather than a specific Neon platform feature.

# Postgres guides

Last updated: 2026-09-16

Explore Postgres features with Neon's Postgres guides. Learn about data types, extensions, functions, and optimizing query performance. Remember, **Neon is Postgres**, so you're encouraged to reference both the Neon documentation and the [official PostgreSQL documentation](https://www.postgresql.org/docs/current/).

- [Data types](https://neon.com/docs/data-types/introduction): Learn about commonly-used Postgres data types
- [Extensions](https://neon.com/docs/extensions/pg-extensions): Level up your database with our many supported Postgres extensions
- [Functions](https://neon.com/docs/functions/introduction): Learn about commonly-used Postgres functions
- [Indexes](https://neon.com/docs/postgresql/index-types): Optimize query performance with indexes in Postgres
- [Query performance](https://neon.com/docs/postgresql/query-performance): Strategies for optimizing Postgres query performance
- [Query reference](https://neon.com/docs/postgresql/query-reference): Find examples of commonly-used Postgres queries for basic to advanced operations
- [Compatibility](https://neon.com/docs/reference/compatibility): Learn about Neon as a managed Postgres service
- [Lakebase Postgres Version Support](https://neon.com/docs/postgresql/postgres-version-support): Read about Lakebase Postgres version support and maintenance policy
- [Upgrade Postgres](https://neon.com/docs/postgresql/postgres-upgrade): Learn how to upgrade your Postgres version in Neon

--- [Document source](https://neon.com/docs/postgresql/postgres-upgrade.md) ---

> Summary: Upgrading to a new major Postgres version in Neon requires creating a new project at the target version and migrating data. Each Neon project is locked to the major version selected at creation. Use the Import Data Assistant for smaller databases, pg_dump/pg_restore for larger ones, or logical replication for near-zero downtime on active databases. Note that pg_upgrade is not supported, minor version upgrades are automatic, and pg_dump must use an unpooled connection string.

# Upgrading your Postgres version

Learn how upgrade to a new major Postgres version in Neon

Last updated: 2026-10-09

This topic describes how to upgrade your Neon project from one **major** Postgres version to a newer one.

Postgres version numbers consist of a **major** and a **minor** version number. For example, in the version number 16.1, 16 is the major version number and the 1 is the minor version number.

Neon manages **minor** Postgres version upgrades for you, as per the [Lakebase Postgres Version Support Policy](https://neon.com/docs/postgresql/postgres-version-support). Typically, no user action is required for **minor** version upgrades. Neon deploys minor versions soon after they become available. However, upgrading to a new major Postgres version is a manual task that must be performed by you.

Each Neon project is tied to a specific Postgres major version, which you selected when creating your Neon project.

You can check your Neon project's Postgres version in the **Postgres** panel on the **Overview** page or by running the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any SQL client connection to your database:

```sql
SELECT version();
```

## Before you begin

- Review the [PostgreSQL Release Notes](https://www.postgresql.org/docs/current/release.html) for the new Postgres version. Major Postgres versions often introduce user-visible incompatibilities, so review the release notes for these changes. While you can upgrade directly to a new major Postgres version without going through each intermediate version, make sure you review the release notes for any skipped versions, as they may contain changes relevant to your upgrade.
- Optionally, you may want to run some performance tests of your current database to set a benchmark for post-upgrade comparison.

## Performing the upgrade

### 1. Create a Neon project with the new Postgres version

Start by creating a new Neon project with the desired Postgres version. For instructions, see [creating a new Neon project](https://neon.com/docs/manage/projects#create-a-project).

At this time, you may also want to apply any specific configurations to your new Neon project that exist in your current Neon project. For example, you may have configured settings for the following Neon features that you want to implement in your new Neon project:

- [Compute size](https://neon.com/docs/manage/computes#edit-a-compute)
- [Autoscaling](https://neon.com/docs/guides/autoscaling-guide)
- [Scale to Zero](https://neon.com/docs/guides/scale-to-zero-guide)
- [Protected branches](https://neon.com/docs/guides/protected-branches)
- [IP Allow](https://neon.com/docs/introduction/ip-allow)

Alternatively, you can apply these configurations after migrating your data.

### 2. Migrate your data using one of the following methods

- **Import Data Assistant**

  For databases under 10GB, Neon's [Import Data Assistant](https://neon.com/docs/import/import-data-assistant) provides the simplest way to migrate between Neon projects with different Postgres versions. Just create a new project with your desired Postgres version, then use the database connection string from your existing Neon project to import the data.

- **Dump and restore**

  Neon supports the following dump and restore options:

  - [Migrate data with pg_dump and pg_restore](https://neon.com/docs/import/migrate-from-postgres)

    This method requires dumping data from your current Neon project with `pg_dump` and loading the data into the new Neon project using `pg_restore`. Some downtime will be required between the dump and restore operations.

  - [Migrate data from one Neon project to another by piping data from pg_dump to pg_restore](https://neon.com/docs/import/migrate-from-neon)

    If your database is small, you can use this method to pipe `pg_dump` output directly to `pg_restore` to save time. While this method is a bit simpler, we recommend it only for small databases, as it is susceptible to failures during lengthy data migrations.

  **Important:** Avoid using `pg_dump` over a [pooled connection string](https://neon.com/docs/reference/glossary#pooled-connection-string). Use an [unpooled connection string](https://neon.com/docs/reference/glossary#unpooled-connection-string) instead.

- **Logical replication**

  The logical replication method can be used to achieve a near-zero downtime migration. Once the data in the new Neon project is synced with the data in the Neon project running the older version of Postgres, you can quickly switch your applications to the database. This method is recommended for active databases that cannot afford much downtime. For instructions, see [Logical Replication](https://neon.com/docs/guides/logical-replication-neon-to-neon).

  **Note: Notes**

  - Neon does not support the `pg_dumpall` utility. If upgrading via dump and restore, dumps must be performed one database at a time using `pg_dump`.
  - Neon does not yet support upgrading using `pg_upgrade`. Support for this utility is being considered for a future release.
  - If you choose a dump and restore method, it is recommended that you use `pg_dump` and `pg_restore` programs from the newer version of Postgres, to take advantage of any enhancements introduced in the newer version. Current releases of these programs can read data from all previous Postgres versions supported by Neon.

### 3. Switch over your applications

After the migration is complete and you have verified that your new database is working as expected, you can switch your application over to the database in your new Neon project by swapping out your current database connection details for your new database connection details.

You can find the connection details for your database by clicking the **Connect** button in the Console nav. This opens the **Connect to your branch** modal. See [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

--- [Document source](https://neon.com/docs/postgresql/postgres-version-support.md) ---

> Summary: Postgres version support tracks the latest major versions, applies minor releases automatically at the next compute restart, and aligns end-of-life with the official PostgreSQL five-year support window. Minor release downgrades and version skipping are not supported. Upgrading to a new major version requires creating a new project and migrating data.

# Postgres version support

Last updated: 2026-10-09

This topic outlines [PostgreSQL version support on Neon](https://neon.com/docs/postgresql/postgres-version-support#postgresql-version-support-on-neon).

## The official PostgreSQL versioning policy

To better understand [PostgreSQL version support on Neon](https://neon.com/docs/postgresql/postgres-version-support#postgresql-version-support-on-neon), it's helpful to first familiarize yourself with the official PostgreSQL versioning policy and numbering system. You can refer to the official [PostgreSQL Versioning Policy](https://www.postgresql.org/support/versioning/) documentation for details, but here's a condensed summary:

### Major versions

- The PostgreSQL Global Development Group releases a new major version approximately once per year.
- Each major version is supported for five years from its initial release.
- After five years, a final minor version is released, and the major version reaches end-of-life (EOL) and is no longer supported.

### Minor releases

- Minor releases include only bug fixes and security patches, and are issued _at least_ once every three months. Minor releases do not introduce new features.
- The minor release schedule is available in the [official PostgreSQL roadmap](https://www.postgresql.org/developer/roadmap/).
- Critical bugs or security issues may result in an unscheduled release outside the regular minor release roadmap if the issue is deemed too urgent to delay.
- A minor release is issued for all supported major versions simultaneously.
- Occasionally, manual actions are necessary after a minor version upgrade. The PostgreSQL Global Development Group strives to minimize these situations, but they do occur. Any exceptions, required manual steps, or incompatibilities introduced in minor releases are detailed in the [PostgreSQL release notes](https://www.postgresql.org/docs/release/).

### PostgreSQL version numbering

- The major version is indicated by the first part of the version number, such as the "18" in "18.1".
- The minor release is indicated by the second part of the version number, such as the "1" in "18.1".

## PostgreSQL version support on Neon

Neon is committed to providing stability and hassle-free maintenance. You select the major version of Postgres when [creating a Neon project](https://neon.com/docs/manage/projects#create-a-project), and Neon automatically updates your chosen Postgres version to the latest minor release soon after it becomes available. Typically, no user action is required for minor release updates.

Minor release updates are announced in the [Neon Changelog](https://neon.com/docs/changelog).

### How to check which Postgres version you're running

To check your current Postgres major and minor version, run the following query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any SQL client connection to your database:

```sql
SELECT version();
```

The first number is the major version. The second is the minor version, which Neon updates automatically.

Your Postgres major version is also displayed in the **Postgres** panel on your project's **Overview** page. With the [Neon CLI](https://neon.com/docs/cli) installed and authenticated, `neon projects get <project_id> --output json` returns the same value in its `pg_version` field.

### Minor releases

In Neon, an instance of Postgres runs on each compute in your Neon project. When the PostgreSQL Global Development Group releases a new minor version, Neon automatically updates your computes to the new minor version. Typically, no user action is required for minor version updates. While we aim to make the new minor version available at the same time as the official PostgreSQL release, these updates may occur a few days later than the official release date.

Once a new minor version is available on Neon, it is applied the next time your compute restarts (for any reason). For example, if your compute suspends due to inactivity, the compute will be updated to the new minor version the next time it restarts due to a user-initiated or control-plane initiated action that wakes the compute. If your compute is always active (i.e., it never stops due to regular database activity or because you disabled [scale to zero](https://neon.com/docs/introduction/scale-to-zero)), and you want to force a restart to pick up the latest update, see [Restart a compute](https://neon.com/docs/manage/computes#restart-a-compute).

Neon only supports the latest minor release for each major Postgres version. For example, when 18.4 is the latest minor release of Postgres version 18, you cannot choose to run a Neon compute on version 18.3.

Neon does not support skipping minor releases or downgrading to a previous minor release.

#### Recent minor version rollouts

The table below shows when recent Postgres releases became available on Neon. Each version links to its PostgreSQL release notes, which list the bug fixes and CVE patches included in that minor release.

| Postgres release date | Versions in the release                                                                                                                                                                                                                                                                   | First available on Neon | Time to availability |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -------------------- |
| 2026-08-13            | [18.6](https://www.postgresql.org/docs/release/18.6/), [17.11](https://www.postgresql.org/docs/release/17.11/), [16.15](https://www.postgresql.org/docs/release/16.15/), [15.19](https://www.postgresql.org/docs/release/15.19/), [14.24](https://www.postgresql.org/docs/release/14.24/) | 2026-08-18              | 5 days               |
| 2026-05-14            | [18.4](https://www.postgresql.org/docs/release/18.4/), [17.10](https://www.postgresql.org/docs/release/17.10/), [16.14](https://www.postgresql.org/docs/release/16.14/), [15.18](https://www.postgresql.org/docs/release/15.18/), [14.23](https://www.postgresql.org/docs/release/14.23/) | 2026-05-19              | 5 days               |
| 2026-02-12            | [18.2](https://www.postgresql.org/docs/release/18.2/), [17.8](https://www.postgresql.org/docs/release/17.8/), [16.12](https://www.postgresql.org/docs/release/16.12/), [15.16](https://www.postgresql.org/docs/release/15.16/), [14.21](https://www.postgresql.org/docs/release/14.21/)   | 2026-02-13              | 1 day                |
| 2025-11-13            | [18.1](https://www.postgresql.org/docs/release/18.1/), [17.7](https://www.postgresql.org/docs/release/17.7/), [16.11](https://www.postgresql.org/docs/release/16.11/), [15.15](https://www.postgresql.org/docs/release/15.15/), [14.20](https://www.postgresql.org/docs/release/14.20/)   | 2025-12-03              | 20 days              |

The **First available on Neon** date marks when a release first became available to run, not the point at which every compute is running it; each compute picks it up on the next restart, as described above.

As of August 2026, Neon runs the latest community minor release for every supported major version: 18.6, 17.11, 16.15, 15.19, and 14.24. For the current version list, see [Compatibility](https://neon.com/docs/reference/compatibility).

#### Manual actions after minor release upgrades

As a managed service, Neon strives to manage all minor version updates automatically, minimizing the need for user intervention. However, certain updates, such as security fixes, may require decisions that depend on your application and cannot be fully automated.

In such cases, your action may occasionally be required. When this occurs, which is infrequent, we will notify you through appropriate communication channels to ensure you are aware of any necessary steps.

### Supported major versions

Neon currently supports Postgres 14, 15, 16, 17, and 18. Neon supports the five latest major Postgres versions, in alignment with the official PostgreSQL version support policy.

### Major version upgrades

Each Neon project is created with a specific Postgres major version. Upgrading to a newer major version requires [creating a new Neon project](https://neon.com/docs/manage/projects#create-a-project) with the desired Postgres version and migrating your data to the new Neon project. For more information, see [Upgrading your Postgres version](https://neon.com/docs/postgresql/postgres-upgrade).

--- [Document source](https://neon.com/docs/postgresql/query-performance.md) ---

> Summary: Postgres query performance optimization guide covering query analysis with pg_stat_statements and EXPLAIN, database design with indexes, efficient data types, and prepared statements, and resource tuning via compute sizing, cache hit ratio, connection pooling, and bloat reduction. Reach for this page when slow queries, high sequential scan counts, index or table bloat, or low cache hit ratios call for systematic diagnosis rather than a single targeted fix. Neon-specific coverage includes the neon_stat_file_cache view and enabling PgBouncer connection pooling by appending -pooler to the connection string hostname.

# Optimize Postgres query performance

Learn about strategies for optimizing Postgres query performance

Last updated: 2026-09-16

Many factors can impact query performance in Postgres, ranging from insufficient indexing and database maintenance to poorly optimized queries or inadequate system resources. With such a wide range of factors, it can be difficult to know where to start. In this topic, we'll look at several strategies you can use to optimize query performance in Postgres.

Strategies are organized under the following categories:

- [Query analysis and optimization](https://neon.com/docs/postgresql/query-performance#query-analysis-and-optimization)
- [Query and database design](https://neon.com/docs/postgresql/query-performance#query-and-database-design)
- [Resource and configuration optimization](https://neon.com/docs/postgresql/query-performance#resource-and-configuration-optimization)

## Query analysis and optimization

Strategies in this category include:

- [Gather statistics](https://neon.com/docs/postgresql/query-performance#gather-statistics)
- [Use EXPLAIN](https://neon.com/docs/postgresql/query-performance#use-explain)

### Gather statistics

Gathering query statistics can aid in identifying performance issues and opportunities for optimization. Neon supports the [pg_stat_statements](https://neon.com/docs/extensions/pg_stat_statements) extension for monitoring and analyzing SQL query performance.

The [pg_stat_statements](https://neon.com/docs/extensions/pg_stat_statements) extension provides aggregated query statistics for executed SQL statements. The data collected includes the number of query executions, total execution time, rows returned by the query, and more.

As an alternative to writing SQL, run [`neon inspect db outliers`](https://neon.com/docs/cli/inspect#db-outliers) and [`neon inspect db calls`](https://neon.com/docs/cli/inspect#db-calls) from the terminal to see the slowest and most-frequent queries.

This extension isn't installed by default, so your first step is to install it and then allow some time for statistics collection. To install the extension, run the following `CREATE EXTENSION` statement.

```sql
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```

Once installed, you can run the following query to view the types of data that `pg_stat_statements` collects:

```shell
neondb=> \d pg_stat_statements

                      View "public.pg_stat_statements"

         Column         |       Type       | Collation | Nullable | Default
------------------------+------------------+-----------+----------+---------
 userid                 | oid              |           |          |
 dbid                   | oid              |           |          |
 toplevel               | boolean          |           |          |
 queryid                | bigint           |           |          |
 query                  | text             |           |          |
 plans                  | bigint           |           |          |
 total_plan_time        | double precision |           |          |
 min_plan_time          | double precision |           |          |
 max_plan_time          | double precision |           |          |
 mean_plan_time         | double precision |           |          |
 stddev_plan_time       | double precision |           |          |
 calls                  | bigint           |           |          |
 total_exec_time        | double precision |           |          |
 min_exec_time          | double precision |           |          |
 max_exec_time          | double precision |           |          |
 mean_exec_time         | double precision |           |          |
 stddev_exec_time       | double precision |           |          |
 rows                   | bigint           |           |          |
 ...
```

For a description of each metric, refer to the official Postgres documentation: [The pg_stat_statements View](https://www.postgresql.org/docs/current/pgstatstatements.html#PGSTATSTATEMENTS-PG-STAT-STATEMENTS).

**Note: WHAT'S THE PERFORMANCE IMPACT OF PG_STAT_STATEMENTS?**

Generally, `pg_stat_statements` is found to have a very small performance impact. Many users keep it installed so that it's available when needed. For a discussion on this topic, please see this [Database Administrators Stack Exchange article](https://dba.stackexchange.com/questions/303503/what-is-the-performance-impact-of-pg-stat-statements).

After allowing time for statistics collection, you can run queries like these to identify opportunities for query optimization:

#### Most frequently executed queries

This query lists the top 100 most frequently executed queries with the executing user and total and average execution time.

```sql
SELECT
  userid,
  query,
  calls,
  total_exec_time / 1000 AS total_seconds,
  mean_exec_time AS avg_ms
FROM pg_stat_statements
ORDER BY calls DESC
LIMIT 100;
```

#### Long-running queries

This query identifies the top 100 queries with the longest average execution time across all users, including execution frequency and the executing user's ID.

```sql
SELECT
    userid,
    query,
    calls,
    mean_exec_time
FROM
    pg_stat_statements
ORDER BY
    mean_exec_time DESC
LIMIT 100;
```

#### Queries that return the most rows

This query showcases the top 100 queries that return the most rows, ordered by the number of rows returned. It includes the average execution time for each query.

```sql
SELECT
    query,
    rows,
    mean_exec_time
FROM
    pg_stat_statements
ORDER BY
    rows DESC
LIMIT
    100;
```

### Use EXPLAIN

`EXPLAIN` provides a detailed report on how a query was executed, including how tables are scanned, execution times, join algorithms, and so on. This information can be used to optimize queries.

`EXPLAIN` has the following syntax:

```sql
EXPLAIN [ ( option [, ...] ) ] statement
```

where `option` can be one of:

```sql
ANALYZE
VERBOSE
COSTS
SETTINGS
GENERIC_PLAN
BUFFERS
WAL
TIMING
SUMMARY
FORMAT { TEXT | XML | JSON | YAML }
```

The `ANALYZE` option executes the SQL statement first and includes actual run times and other statistics in your query plans, so it's helpful to include this option when explaining `SELECT` queries. For other types of statements such as `INSERT`, `UPDATE`, or `DELETE`, you can enclose an `EXPLAIN ANALYZE` statement in a transaction, as shown below, to prevent the `EXPLAIN ANALYZE` statement from altering your data.

```sql
BEGIN;
    EXPLAIN ANALYZE sql_statement;
ROLLBACK;
```

For a description of the other `EXPLAIN` options listed above, refer to the [official PostgreSQL EXPLAIN documentation](https://www.postgresql.org/docs/current/sql-explain.html).

The following example demonstrates running `EXPLAIN ANALYZE` on a simple `SELECT` query:

```sql
EXPLAIN ANALYZE SELECT * FROM users WHERE id = '1';
                                                       QUERY PLAN
------------------------------------------------------------------------------------------------------------------------
 Gather  (cost=1000.00..59375.93 rows=1 width=9) (actual time=0.404..6479.494 rows=1 loops=1)
   Workers Planned: 2
   Workers Launched: 2
   ->  Parallel Seq Scan on users  (cost=0.00..58375.83 rows=1 width=9) (actual time=4313.317..6472.025 rows=0 loops=3)
         Filter: (id = 1)
         Rows Removed by Filter: 1833333
 Planning Time: 0.102 ms
 Execution Time: 6479.526 ms
```

In this case, the query plan shows that two parallel workers were launched to run a sequential scan on the `users` table. The presence of a sequential scan and a lengthy execution time indicates an opportunity for optimization, such as adding an index to the `id` column of the `users` table to replace the costly sequential scan with an index scan.

#### Interpreting EXPLAIN output

Interpreting `EXPLAIN` output can be a little daunting at first, but you can learn the basics here: [EXPLAIN Basics](https://www.postgresql.org/docs/current/using-explain.html#USING-EXPLAIN-BASICS).

There are numerous other resources you can draw upon to learn more about leveraging `EXPLAIN` to optimize queries. Here are a few to get you started:

- [Using EXPLAIN: official PostgreSQL documentation](https://www.postgresql.org/docs/current/using-explain.html)
- [Using EXPLAIN: PostgreSQL wiki](https://wiki.postgresql.org/wiki/Using_EXPLAIN).
- [PostgreSQL EXPLAIN tutorial](https://neon.com/postgresql/postgresql-tutorial/postgresql-explain)

**Tip: Tips**

- The Neon SQL Editor provides a visual `EXPLAIN` and `ANALYZE` capability, providing query plans in a visual form. See [Query with Neon's SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor).
- You can run the `ANALYZE` command on your database to updates statistics. This helps Postgres produce better query plans. The Postgres `autovacuum` process, which is enabled in Neon, automatically issues the `ANALYZE` command whenever the content of a table has changed sufficiently, but if you're working with large tables, this may not happen as often as expected. For a query that shows when vacuum or autovacuum
  was last run, see [VACUUM and ANALYZE statistics](https://neon.com/docs/postgresql/query-reference#vacuum-and-analyze-statistics).

## Query and database design

Strategies in this category include:

- [Use indexes](https://neon.com/docs/postgresql/query-performance#use-indexes)
- [Use efficient data types](https://neon.com/docs/postgresql/query-performance#use-efficient-data-types)
- [Limit your result sets](https://neon.com/docs/postgresql/query-performance#limit-your-result-sets)

### Use indexes

Indexes are crucial for query performance, especially in applications with large tables. They significantly reduce the time required to access data, which can be the difference between a slow application and a fast one.

To find indexes that are rarely scanned, run [`neon inspect db unused-indexes`](https://neon.com/docs/cli/inspect#db-unused-indexes); to find tables Postgres scans end to end, run [`neon inspect db seq-scans`](https://neon.com/docs/cli/inspect#db-seq-scans).

Suppose that you have a large `users` table like this with millions of rows:

```sql
CREATE TABLE users (
    user_id SERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL,
    email VARCHAR(100) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
    last_login TIMESTAMP WITH TIME ZONE
);
```

If you frequently search for users by their username or email, you can create indexes on those columns to improve search performance. For example:

```sql
CREATE INDEX idx_users_username ON users(username);
CREATE INDEX idx_users_email ON users(email);
```

To see if an index was used or to compare execution times with and without an index, you can use `EXPLAIN ANALYZE`. See [Use EXPLAIN](https://neon.com/docs/postgresql/query-performance#use-explain).

#### View table indexes

You can use the following query to view the indexes defined on a table. You should at least have an index defined on your primary key, and if you know the columns used in your queries, consider adding indexes to those too. However, note that indexes are best suited for columns with high cardinality (a high number of unique values). Postgres might ignore indexes defined on low-cardinality columns, in which case you would be consuming storage space unnecessarily.

```sql
SELECT
    tablename AS table_name,
    indexname AS index_name,
    indexdef AS index_definition
FROM
    pg_indexes
WHERE
    tablename = 'your_table_name' -- replace 'your_table_name' with the actual table name
    AND schemaname = 'public'; -- adjust the schema name as necessary
```

#### Check for missing indexes

This query checks for potential indexing opportunities in a given schema by comparing sequential scans and index scans. The query suggests to "Check indexes" based on whether the number of sequential scans exceeds the number of index scans.

```sql
SELECT
  relname AS table_name,
  CASE
    WHEN seq_scan > COALESCE(idx_scan, 0) THEN 'Check indexes'
    ELSE 'OK'
  END AS recommendation
FROM
  pg_stat_user_tables
WHERE
  schemaname = 'public' -- Adjust as necessary for your schema
ORDER BY
  (seq_scan - COALESCE(idx_scan, 0)) DESC
LIMIT 10; -- Adjust as necessary for the number of results
```

A "Check indexes" recommendation appears similar to the following:

```sql
 table_name | recommendation
------------+----------------
 users      | Check indexes
```

**Note:** The number of index scans has to exceed the number of sequential scans before the missing index check will report "OK" instead of "Check indexes". So, if you add a missing index and rerun a query, don't expect the recommendation to change immediately.

The `PgHero` utility also supports identifying missing indexes. See [PgHero](https://neon.com/docs/introduction/monitoring#pghero).

### Use efficient data types

Generally, you should avoid using a data type that is larger than necessary.

Postgres offers a range of numeric types, including `INTEGER`, `NUMERIC`, `REAL`, and `DOUBLE PRECISION`. Each has its use case, but `INTEGER` types are often sufficient for counts and identifiers and use less space than floating-point types.

If you're storing small integers, you can use the `SMALLINT` type instead of `INTEGER` or `BIGINT`, as it uses less space.

For example, imagine a scenario where your `users` table includes an `age` column. If operations such as computing the average age of users are common, you can optimize database efficiency by switching to a more compact data type, such as `SMALLINT` instead of the standard `INTEGER`:

```sql
ALTER TABLE users ALTER COLUMN age TYPE SMALLINT;
```

This change decreases the memory footprint for storing `age` data, potentially improving the performance of queries that operate on that data.

For an overview of common Postgres data types, refer to our [data types](https://neon.com/docs/data-types/introduction) guide.

### Use prepared statements

Prepared statements are another way you can optimize query performance. They let you prepare a query plan once and use it multiple times, which minimizes processing time for repetitive query execution.

For example, imagine you need to fetch all users from a database with a given name:

```sql
SELECT * FROM users WHERE name = 'alex';
```

To enhance performance when running this type of, you can use a prepared statement, as shown here:

```sql
PREPARE user_fetch_plan (text) AS SELECT * FROM users WHERE name = $1;
EXECUTE user_fetch_plan('alex');
EXECUTE user_fetch_plan('dana');
```

**Note:** If you are using a pooled connection for your Neon database, only protocol-level prepared statements are supported. See [Optimize queries with PgBouncer and prepared statements](https://neon.com/docs/connect/connection-pooling#optimize-queries-with-pgbouncer-and-prepared-statements).

### Limit your result sets

Consider a scenario where you're fetching all entries from an `orders` table with the query:

```sql
SELECT * FROM orders;
```

This approach might become inefficient and consume considerable resources when working with a large table. To optimize this query, you can add the `LIMIT` clause to restrict the output to a specific number of rows. For example:

```sql
SELECT * FROM orders LIMIT 100;
```

By doing so, you ensure that the database retrieves only a manageable subset of records, improving the query's performance and reducing the load on the database.

## Resource and configuration optimization

Strategies in this category include:

- [Right-size your compute](https://neon.com/docs/postgresql/query-performance#right-size-your-compute)
- [Cache your data](https://neon.com/docs/postgresql/query-performance#cache-your-data)
- [Use connection pooling](https://neon.com/docs/postgresql/query-performance#use-connection-pooling)
- [Check for table or index bloat](https://neon.com/docs/postgresql/query-performance#check-for-table-or-index-bloat)

### Right-size your compute

The size of your compute determines the amount of memory available to cache your frequently accessed data and the maximum number of simultaneous connections you can support. As a result, if your compute size is too small, this can lead to suboptimal query performance and connection limit issues.

For information about right-sizing your compute in Neon, see [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

### Cache your data

A cache hit ratio tells you the percentage of queries served from memory. Queries not served from memory retrieve data from disk, which is more costly and can result in slower query performance.

In a standalone Postgres instance, you can query the cache hit ratio with an SQL statement that looks for `shared buffers` block hits. In Neon, it's a little different. Neon caches data on your compute (up to 75% of your compute's RAM). To query your cache hit ratio in Neon, you need to look at compute cache hits instead of shared buffer hits.

**Note:** This applies to autoscaling computes and fixed-size computes below 18 CU. On fixed-size computes of 18 CU and above, Neon caches data in Postgres `shared_buffers` rather than the file cache, so the `neon_stat_file_cache` view below does not reflect the working cache there. On those computes, check the [Compute cache hit rate](https://neon.com/docs/introduction/monitoring-page#compute-cache-hit-rate) graph or `SHOW shared_buffers` instead. See [What is the compute cache?](https://neon.com/docs/extensions/neon#what-is-the-compute-cache) for details.

To enable querying compute cache statistics, Neon provides a [neon_stat_file_cache](https://neon.com/docs/extensions/neon#the-neonstatfilecache-view) view. To access this view, you need to install the [neon](https://neon.com/docs/extensions/neon) extension:

```sql
CREATE EXTENSION neon;
```

After allowing enough time for your workload to run fully and generate the necessary statistics, you can issue the following query to view your cache hit ratio:

```sql
\x
Expanded display is on.
SELECT * FROM neon_stat_file_cache;
file_cache_misses:                 2133643
file_cache_hits:                   108999742
file_cache_used:                   607
file_cache_writes:                 10767410
file_cache_hit_ratio:              98.08
```

The ratio is calculated according to the following formula:

```plaintext
file_cache_hit_ratio = (file_cache_hits / (file_cache_hits + file_cache_misses)) * 100
```

If the `file_cache_hit_ratio` is below 99%, your working set (your most frequently accessed data) may not be adequately in memory. This could be due to your Postgres instance not having sufficient memory.

To increase available memory for a Postgres instance in Neon, you can increase the size of your compute. Larger computes have larger caches. For information about selecting an appropriate compute size in Neon, refer to [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

Remember that the compute cache statistics are for the entire compute, not specific databases or tables. A Neon compute runs an instance of Postgres, which can have multiple databases and tables.

**Note:** The cache hit ratio query is based on statistics that represent the lifetime of your Postgres instance, from the last time you started it until the time you ran the query. Statistics are lost when your instance stops and gathered again from scratch when your instance restarts. In Neon, your compute runs Postgres, so starting and stopping a compute also starts and stops Postgres. Additionally, you'll only want to run the cache hit ratio query after a representative workload has been run. For example, say that you restart Postgres. In this case, you should run a representative workload before you try the cache hit ratio query again to see if your cache hit ratio improved.

For the same numbers from the terminal, run [`neon inspect db lfc-hit-rate`](https://neon.com/docs/cli/inspect#db-lfc-hit-rate) and [`neon inspect db working-set`](https://neon.com/docs/cli/inspect#db-working-set).

### Use connection pooling

Connection pooling improves performance by minimizing the overhead associated with creating and tearing down database connections. Neon uses PgBouncer to provide connection pooling support, enabling up to 10,000 concurrent connections.

Enabling connection pooling in Neon requires adding a `-pooler` option to your Neon connection string (to the Neon hostname), as shown here:

```plaintext
postgresql://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

Alternatively, you can obtain a pooled connection string for your database by clicking the **Connect** button in the Console nav.

For more information about connection pooling in Neon, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

### Check for table or index bloat

If there is some issue with Postgres [autovacuum](https://www.postgresql.org/docs/current/routine-vacuuming.html#AUTOVACUUM), this can lead to table and index bloat.

Bloat refers to the condition where tables and indexes occupy more space on disk than is necessary for storing the data. Bloat can occur over time due to the way Postgres handles updates and deletes.

#### Table bloat

When a row is updated, the database doesn't overwrite the existing row. Instead, it just marks the old row version as obsolete and creates a new version of the row elsewhere in the table. Similarly, when a row is deleted, it is not immediately removed; it's just marked as deleted. The space occupied by these obsolete or deleted rows contributes to table bloat.

This mechanism supports Postgres MVCC (Multi-Version Concurrency Control), allowing for more efficient query processing without locking rows for reading. However, the downside is that it can lead to wasted space and decreased performance over time as the table grows larger than necessary.

#### Index bloat

Indexes can also experience bloat. As rows are updated and deleted, the indexes that point to those rows can become inefficient. Index bloat happens because, similar to tables, indexes also retain pointers to obsolete row versions. Over time, the index can grow larger, consuming more space than necessary.

Index bloat can degrade the performance of read operations. Since indexes are used to speed up data retrieval, a bloated index can have the opposite effect, making queries slower.

#### Checking for bloat

There are SQL queries you can run to check for table and index bloat. There are several good sources for bloat check queries, including these:

- [Show database bloat – PostgreSQL wiki](https://wiki.postgresql.org/wiki/Show_database_bloat)
- [Index and table bloat check scripts from PostgreSQL Experts](https://github.com/pgexperts/pgx_scripts/tree/master/bloat)

As an alternative to these queries, run [`neon inspect db bloat`](https://neon.com/docs/cli/inspect#db-bloat) from the Neon CLI for a quick estimate.

#### Reducing bloat

To reduce table bloat, you can run the [VACUUM](https://www.postgresql.org/docs/current/sql-vacuum.html) command. `VACUUM` cleans up these obsolete records and makes space available for reuse within the table.

```sql
VACUUM your_table_name;
```

For more aggressive space reclamation, you can use `VACUUM FULL`, but this command locks the table, which can be disruptive and can affect database performance significantly.

To remove index bloat, you can use the [REINDEX](https://www.postgresql.org/docs/current/sql-reindex.html) command, which rebuilds the index from scratch. Be aware that this can be an intensive operation, especially for large indexes, as it requires an exclusive lock on the index.

This command rebuilds all indexes on the specified table:

```sql
REINDEX TABLE your_table_name;
```

Generally, you'll want to perform vacuum and reindex operations when they will have the least impact, or you'll want to plan some maintenance downtime to run them.

--- [Document source](https://neon.com/docs/postgresql/query-reference.md) ---

> Summary: A ready-to-copy Postgres SQL reference covering DDL, DML, SELECT, JOINs, transactions, indexes, views, stored procedures, functions, and performance analysis. Use this page when you need a working SQL snippet without reading full reference docs. Includes performance diagnostics using pg_stat_statements, EXPLAIN, EXPLAIN ANALYZE, pg_stat_user_tables, pg_locks, and connection management with pg_cancel_backend and pg_terminate_backend, plus Neon-specific notes on max_connections and data size.

# Postgres query reference

Find examples of commonly-used Postgres queries for basic to advanced operations

Last updated: 2026-07-22

> **Try it on Neon!**
>
> Neon is Serverless Postgres built for the cloud. Explore Postgres features and functions in our user-friendly SQL editor. Sign up for a free account to get started.
>
> [Sign Up](https://console.neon.tech/signup)

## Create a table

```sql
CREATE TABLE users (
    user_id SERIAL PRIMARY KEY,
    username VARCHAR(50) UNIQUE NOT NULL,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
```

See [CREATE TABLE](https://www.postgresql.org/docs/current/sql-createtable.html) for more information.

## Add, rename, drop a column

```sql
-- Add a column to the table
ALTER TABLE users ADD COLUMN date_of_birth DATE;

-- Rename a column in the table
ALTER TABLE users RENAME COLUMN email TO user_email;

-- Drop a column from the table
ALTER TABLE users DROP COLUMN date_of_birth;
```

See [ALTER TABLE](https://www.postgresql.org/docs/current/sql-altertable.html) for more information.

## Insert, update, delete data

```sql
-- Insert data into the users table
INSERT INTO users (username, email) VALUES ('alex', 'alex@domain.com');

-- Update data in the users table
UPDATE users SET email = 'new.alex@domain.com' WHERE user_id = 1;

-- Delete data from the users table
DELETE FROM users WHERE user_id = 1;
```

See [INSERT](https://www.postgresql.org/docs/current/sql-insert.html), [UPDATE](https://www.postgresql.org/docs/current/sql-update.html), and [DELETE](https://www.postgresql.org/docs/current/sql-delete.html) for more information.

## SELECT queries

These Postgres `SELECT` query examples cover a number of common use cases.

```sql
-- Basic SELECT to retrieve all columns from a table
SELECT * FROM users;

-- SELECT specific columns from a table
SELECT username, email FROM users;

-- SELECT with filtering using WHERE clause
SELECT * FROM users WHERE user_id > 10;

-- SELECT with ordering and limiting the results
SELECT username, email FROM users ORDER BY created_at DESC LIMIT 5;

-- SELECT with aggregation and grouping
SELECT COUNT(*) AS total_users, EXTRACT(YEAR FROM created_at) AS year FROM users GROUP BY year ORDER BY year;
```

See [SELECT](https://www.postgresql.org/docs/current/sql-select.html) for more information.

## Filter data

These Postgres `WHERE` clause examples showcase various filtering scenarios.

{/*

  CREATE TABLE orders (
  order_id SERIAL PRIMARY KEY,
  customer_id INT NOT NULL,
  order_date DATE NOT NULL,
  total_amount DECIMAL NOT NULL
  );

  INSERT INTO orders (customer_id, order_date, total_amount) VALUES
  (1, '2023-01-10', 100.00),
  (2, '2023-01-20', 150.50),
  (3, '2023-02-05', 200.75);

  CREATE TABLE products (
  product_id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  category_id INT NOT NULL,
  price DECIMAL NOT NULL
  );

  INSERT INTO products (name, category_id, price) VALUES
  ('Laptop', 1, 1200.00),
  ('Smartphone', 2, 800.00),
  ('Headphones', 5, 150.00);

  CREATE TABLE employees (
  employee_id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  department_id INT NOT NULL
  );

  INSERT INTO employees (name, department_id) VALUES
  ('John Doe', 1),
  ('Jane Smith', 2),
  ('Alice Johnson', 3);

  CREATE TABLE customers (
  customer_id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL,
  country VARCHAR(50) NOT NULL
  );

  INSERT INTO customers (name, email, country) VALUES
  ('Customer One', 'one@domain.com', 'Spain'),
  ('Customer Two', 'two@otherdomain.com', 'France'),
  ('Customer Three', 'three@domain.com', 'Spain');

  CREATE TABLE sales (
  sale_id SERIAL PRIMARY KEY,
  amount DECIMAL NOT NULL,
  sales_date DATE NOT NULL
  );

  INSERT INTO sales (amount, sales_date) VALUES
  (550.00, '2023-01-15'),
  (450.00, '2023-02-10'),
  (600.00, '2023-01-25');

  CREATE TABLE users (
  user_id SERIAL PRIMARY KEY,
  username VARCHAR(50) NOT NULL,
  last_login DATE
  );

  INSERT INTO users (username, last_login) VALUES
  ('alex', NULL),
  ('dana', '2023-01-01'),
  ('pat', NULL);

  */}

```sql
-- Filter by an exact match
SELECT * FROM users WHERE username = 'alex';

-- Filter by a range
SELECT * FROM orders WHERE order_date BETWEEN '2023-01-01' AND '2023-01-31';

-- Filter using a list of values (IN operator)
SELECT * FROM products WHERE category_id IN (1, 2, 5);

-- Filter excluding a set of values (NOT IN operator)
SELECT * FROM employees WHERE department_id NOT IN (3, 4);

-- Filter using pattern matching (LIKE operator)
SELECT * FROM customers WHERE email LIKE '%@domain.com';

-- Combine multiple conditions (AND, OR)
SELECT * FROM sales WHERE amount > 500 AND (sales_date >= '2023-01-01' AND sales_date <= '2023-01-31');

-- Filter using NULL values
SELECT * FROM users WHERE last_login IS NULL;

-- Filter using subqueries
SELECT * FROM orders WHERE customer_id IN (SELECT customer_id FROM customers WHERE country = 'Spain');
```

See [WHERE clause](https://www.postgresql.org/docs/7.1/queries.html#QUERIES-WHERE) for more information and examples.

## Sort data

These sorting examples demonstrate various ways to order your query results.

{/*

  CREATE TABLE orders (
  order_id SERIAL PRIMARY KEY,
  customer_id INT,
  status VARCHAR(50),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
  );

  INSERT INTO orders (customer_id, status, created_at) VALUES
  (1, 'shipped', '2023-03-20 10:00:00'),
  (2, 'pending', '2023-03-21 08:30:00'),
  (3, 'completed', '2023-03-19 09:45:00');

  CREATE TABLE users (
  user_id SERIAL PRIMARY KEY,
  username VARCHAR(50) NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
  );

  INSERT INTO users (username, created_at) VALUES
  ('john_doe', '2022-01-15 07:00:00'),
  ('jane_smith', '2021-05-20 13:00:00'),
  ('alice_jones', '2023-02-11 16:30:00');

  CREATE TABLE tasks (
  task_id SERIAL PRIMARY KEY,
  description TEXT,
  due_date DATE NULL
  );

  INSERT INTO tasks (description, due_date) VALUES
  ('Finish project report', '2023-04-20'),
  ('Prepare for presentation', NULL),
  ('Update website', '2023-03-25');

  */}

```sql
-- Sort results in ascending order by a single column
SELECT * FROM users ORDER BY username ASC;

-- Sort results in descending order by a single column
SELECT * FROM users ORDER BY created_at DESC;

-- Sort results by multiple columns
-- First by status in ascending order, then by created_at in descending order
SELECT * FROM orders ORDER BY status ASC, created_at DESC;

-- Sort using a column alias
SELECT username, created_at, EXTRACT(YEAR FROM created_at) AS year FROM users ORDER BY year DESC;

-- Sort by an expression
SELECT username, LENGTH(username) AS username_length FROM users ORDER BY username_length ASC;

-- Sort NULL values to the end (using NULLS LAST)
SELECT * FROM tasks ORDER BY due_date ASC NULLS LAST;

-- Sort NULL values to the start (using NULLS FIRST)
SELECT * FROM tasks ORDER BY due_date DESC NULLS FIRST;
```

For additional information, see [Sorting Rows](https://www.postgresql.org/docs/current/queries-order.html).

## Join tables

These examples illustrate different ways to join tables in Postgres for queries involving data that spans multiple tables.

{/*

  CREATE TABLE employees (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  department_id INT,
  manager_id INT REFERENCES employees(id)
  );

  -- Sample inserts
  INSERT INTO employees (name, department_id, manager_id) VALUES
  ('John Doe', 1, NULL), -- Assuming John Doe is a manager
  ('Jane Smith', 1, 1),
  ('Alice Johnson', 2, NULL); -- Assuming Alice Johnson is a manager

  CREATE TABLE departments (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  office_id INT -- This will reference `offices` table
  );

  -- Sample inserts
  INSERT INTO departments (name, office_id) VALUES
  ('Engineering', 1),
  ('Marketing', 2);

  CREATE TABLE projects (
  id SERIAL PRIMARY KEY,
  title VARCHAR(255) NOT NULL
  );

  -- Sample inserts (Optional for CROSS JOIN, but provides context)
  INSERT INTO projects (title) VALUES
  ('Project Alpha'),
  ('Project Beta');

  CREATE TABLE offices (
  id SERIAL PRIMARY KEY,
  location VARCHAR(255) NOT NULL
  );

  -- Sample inserts
  INSERT INTO offices (location) VALUES
  ('New York'),
  ('San Francisco');

  -- Last join

  CREATE TABLE departments (
  department_id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL
  );

  CREATE TABLE employees (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  department_id INT,
  FOREIGN KEY (department_id) REFERENCES departments(department_id)
  );

  -- Insert into departments
  INSERT INTO departments (name) VALUES ('Engineering'), ('Marketing');

  -- Assuming 'Engineering' has department_id = 1, 'Marketing' = 2
  -- Insert into employees
  INSERT INTO employees (name, department_id) VALUES ('John Doe', 1), ('Jane Smith', 2);

  SELECT employees.name, departments.name AS department_name
  FROM employees
  JOIN departments USING(department_id);

  */}

```sql
-- INNER JOIN to select rows that have matching values in both tables
SELECT employees.name, departments.name AS department_name
FROM employees
INNER JOIN departments ON employees.department_id = departments.id;

-- LEFT JOIN (or LEFT OUTER JOIN) to include all rows from the left table and matched rows from the right table
SELECT employees.name, departments.name AS department_name
FROM employees
LEFT JOIN departments ON employees.department_id = departments.id;

-- RIGHT JOIN (or RIGHT OUTER JOIN) to include all rows from the right table and matched rows from the left table
SELECT employees.name, departments.name AS department_name
FROM employees
RIGHT JOIN departments ON employees.department_id = departments.id;

-- FULL OUTER JOIN to select rows when there is a match in one of the tables
SELECT employees.name, departments.name AS department_name
FROM employees
FULL OUTER JOIN departments ON employees.department_id = departments.id;

-- CROSS JOIN to produce a Cartesian product of the two tables
SELECT employees.name, projects.title
FROM employees
CROSS JOIN projects;

-- SELF JOIN to join a table to itself, as if the table were two tables, temporarily renaming at least one table in the SQL statement
SELECT a.name AS employee_name, b.name AS manager_name
FROM employees a, employees b
WHERE a.manager_id = b.id;

-- Joining Multiple Tables
SELECT employees.name, departments.name AS department_name, offices.location
FROM employees
INNER JOIN departments ON employees.department_id = departments.id
INNER JOIN offices ON departments.office_id = offices.id;

-- Using USING() to specify join condition when both tables have the same column name
SELECT employees.name, departments.name AS department_name
FROM employees
JOIN departments USING(department_id);
```

For additional examples and information, see [Joins between tables](https://www.postgresql.org/docs/current/tutorial-join.html).

## Transactions

Transactions in Postgres ensure that a sequence of operations is executed as a single unit of work, either completely succeeding or failing together. Here are basic examples demonstrating how to use transactions in Postgres:

{/*

  CREATE TABLE accounts (
  account_id SERIAL PRIMARY KEY,
  user_id INT NOT NULL,
  balance DECIMAL NOT NULL
  );

  INSERT INTO accounts (user_id, balance) VALUES
  (1, 1000), -- Initial balance for user 1
  (2, 500), -- Initial balance for user 2
  (3, 200); -- Initial balance for user 3

  */}

```sql
-- Start a transaction
BEGIN;

-- Perform several operations within the transaction
INSERT INTO accounts (user_id, balance) VALUES (1, 1000);
UPDATE accounts SET balance = balance - 100 WHERE user_id = 1;
UPDATE accounts SET balance = balance + 100 WHERE user_id = 2;

-- Commit the transaction to make changes permanent
COMMIT;

-- Start another transaction
BEGIN;

-- Perform operations
UPDATE accounts SET balance = balance - 50 WHERE user_id = 1;
UPDATE accounts SET balance = balance + 50 WHERE user_id = 3;

-- Rollback the transaction in case of an error or if operations should not be finalized
ROLLBACK;

-- Demonstrating transaction with SAVEPOINT
BEGIN;
INSERT INTO accounts (user_id, balance) VALUES (3, 500);

-- Create a savepoint
SAVEPOINT my_savepoint;

UPDATE accounts SET balance = balance - 100 WHERE user_id = 3;
-- Assume an error or a need to revert to the savepoint
ROLLBACK TO SAVEPOINT my_savepoint;

-- Proceed with other operations or end transaction
COMMIT;
```

For additional information, see [Transactions](https://www.postgresql.org/docs/current/tutorial-transactions.html).

## Indexes

Creating and managing indexes is crucial for improving query performance in Postgres. Here are some basic examples of how to work with indexes:

{/*

  CREATE TABLE users (
  user_id SERIAL PRIMARY KEY,
  email VARCHAR(255) NOT NULL,
  username VARCHAR(50) NOT NULL UNIQUE,
  active BOOLEAN NOT NULL,
  preferences JSONB
  );

  -- Sample inserts
  INSERT INTO users (email, username, active, preferences) VALUES
  ('john.doe@example.com', 'johndoe', TRUE, '{"theme": "dark", "notifications": "enabled"}'),
  ('jane.doe@example.com', 'janedoe', FALSE, '{"theme": "light", "notifications": "disabled"}');

  CREATE TABLE events (
  event_id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  event_date DATE NOT NULL
  );

  -- Sample inserts
  INSERT INTO events (name, event_date) VALUES
  ('Product Launch', '2023-05-15'),
  ('Annual Meeting', '2023-12-20');

  */}

```sql
-- Create a basic index on a single column
CREATE INDEX idx_user_email ON users(email);

-- Create a unique index to enforce uniqueness and improve lookup performance
CREATE UNIQUE INDEX idx_unique_username ON users(username);

-- Create a composite index on multiple columns
CREATE INDEX idx_name_date ON events(name, event_date);

-- Create a partial index for a subset of rows that meet a certain condition
CREATE INDEX idx_active_users ON users(email) WHERE active = TRUE;

-- Create an index on an expression (function-based index)
CREATE INDEX idx_lower_email ON users(LOWER(email));

-- Drop an index
DROP INDEX idx_user_email;

-- Create a GIN index on a jsonb column to improve search performance on keys or values within the JSON document
CREATE INDEX idx_user_preferences ON users USING GIN (preferences);

-- Reindex an existing index to rebuild it, useful for improving index performance or reducing physical size
REINDEX INDEX idx_user_email;

-- Create a CONCURRENTLY index, which allows the database to be accessed normally during the indexing operation
CREATE INDEX CONCURRENTLY idx_concurrent_email ON users(email);
```

For more information about indexes in Postgres, see [Indexes](https://www.postgresql.org/docs/current/indexes.html).

## Views

These examples demonstrate how to work with views in Postgres, which can help simplify complex queries, provide a level of abstraction, or secure data access.

{/*

  CREATE TABLE employees (
  employee_id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  department VARCHAR(100) NOT NULL,
  position VARCHAR(100) NOT NULL,
  active BOOLEAN NOT NULL,
  hire_date DATE NOT NULL,
  salary DECIMAL(10, 2) NOT NULL
  );

  -- Inserting sample data into the employees table
  INSERT INTO employees (name, department, position, active, hire_date, salary) VALUES
  ('John Doe', 'Engineering', 'Software Engineer', true, '2018-06-12', 90000.00),
  ('Jane Smith', 'Marketing', 'Marketing Manager', true, '2019-07-16', 85000.00),
  ('Jim Brown', 'Engineering', 'DevOps Specialist', false, '2020-08-20', 95000.00),
  ('Emily White', 'Sales', 'Sales Representative', true, '2021-09-23', 65000.00);

  */}

```sql
-- Creating a view
CREATE VIEW employee_info AS
SELECT employee_id, name, department, position
FROM employees
WHERE active = true;

-- Querying a view
-- Just like querying a table, you can perform SELECT operations on views.
SELECT * FROM employee_info;

-- Updating a view
-- This requires the view to be updatable, which generally means it must directly map to a single underlying table.
CREATE OR REPLACE VIEW employee_info AS
SELECT employee_id, name, department, position, hire_date
FROM employees
WHERE active = true;

-- Dropping a view
DROP VIEW IF EXISTS employee_info;

-- Creating a materialized view
-- Materialized views store the result of the query physically, and hence, can improve performance but require refreshes.
CREATE MATERIALIZED VIEW department_summary AS
SELECT department, COUNT(*) AS total_employees, AVG(salary) AS average_salary
FROM employees
GROUP BY department;

-- Refreshing a materialized view
REFRESH MATERIALIZED VIEW department_summary;

-- Querying a materialized view
SELECT * FROM department_summary;

-- Dropping a materialized view
DROP MATERIALIZED VIEW IF EXISTS department_summary;
```

Standard views are virtual tables that do not store the data directly but represent the results of a query. Materialized views, on the other hand, store the result of the query on disk, acting like a snapshot that can boost performance for costly operations, at the expense of needing periodic refreshes to stay up-to-date.

For more information about views in Postgres, see [Views](https://www.postgresql.org/docs/current/tutorial-views.html).

## Stored procedures

Stored procedures in Postgres are used for performing actions that do not necessarily return a result set, such as modifying data or working with transaction control statements like `COMMIT` and `ROLLBACK`.

{/*

  CREATE TABLE accounts (
  account_id SERIAL PRIMARY KEY,
  balance DECIMAL(10, 2) NOT NULL
  );

  INSERT INTO accounts (account_id, balance) VALUES
  (1, 1000.00),
  (2, 500.00);

  */}

```sql
-- Creating a stored procedure
CREATE OR REPLACE PROCEDURE transfer_funds(source_acc INT, dest_acc INT, transfer_amount DECIMAL)
LANGUAGE plpgsql AS $$
BEGIN
  -- Subtracting amount from source account
  UPDATE accounts SET balance = balance - transfer_amount WHERE account_id = source_acc;

  -- Adding amount to destination account
  UPDATE accounts SET balance = balance + transfer_amount WHERE account_id = dest_acc;

  COMMIT;
END;
$$;

-- Calling the stored procedure
CALL transfer_funds(1, 2, 100.00);

-- See result
SELECT * FROM accounts;
```

For additional information and syntax, see [CREATE PROCEDURE](https://www.postgresql.org/docs/current/sql-createprocedure.html).

## Functions

Functions in Postgres can return a single value, a record, or a set of records.

{/*

  CREATE TABLE employees (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255),
  department VARCHAR(100)
  );

  INSERT INTO employees (name, department) VALUES
  ('John Doe', 'Engineering'),
  ('Jane Smith', 'Marketing'),
  ('Alice Johnson', 'Human Resources'),
  ('Bob Brown', 'Engineering');

  */}

```sql
-- Creating a simple function
CREATE OR REPLACE FUNCTION get_employee_count()
RETURNS integer AS $$
BEGIN
  RETURN (SELECT COUNT(*) FROM employees);
END;
$$ LANGUAGE plpgsql;

-- Calling the function
SELECT get_employee_count();

-- Creating a function that takes parameters
CREATE OR REPLACE FUNCTION get_employee_department(emp_id integer)
RETURNS text AS $$
DECLARE
  department_name text;
BEGIN
  SELECT INTO department_name department FROM employees WHERE id = emp_id;
  RETURN department_name;
END;
$$ LANGUAGE plpgsql;

-- Calling the function with a parameter
SELECT get_employee_department(1);
```

Functions are typically used to perform computations. For additional information and syntax, see [CREATE FUNCTION](https://www.postgresql.org/docs/current/sql-createfunction.html).

## Performance tuning

To analyze query performance in Postgres, you can use a combination of built-in views, extensions, and commands that help identify performance bottlenecks and optimize query execution. Here are some examples:

Many of the checks below are also available as one-line commands under [`neon inspect db`](https://neon.com/docs/cli/inspect) in the Neon CLI.

### Use pg_stat_statements

`pg_stat_statements` is an extension that provides a means to track execution statistics of all executed SQL statements.

First, ensure the extension is enabled in your Postgres database:

```sql
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
```

Then, you can query the `pg_stat_statements` view to analyze query performance. For example, this query lists the top 100 most frequently executed queries in the database:

```sql
SELECT
  userid,
  query,
  calls,
  total_exec_time / 1000 AS total_seconds,
  mean_exec_time AS avg_ms
FROM pg_stat_statements
ORDER BY calls DESC
LIMIT 100;
```

For more information and examples, refer to our [pg_stat_statements extension guide](https://neon.com/docs/extensions/pg_stat_statements), or [Gathering statistics](https://neon.com/docs/postgresql/query-performance#gather-statistics) in our query optimization guide.

### Use EXPLAIN

The `EXPLAIN` command shows the execution plan of a query, detailing how tables are scanned, joined, and which indexes are used.

```sql
EXPLAIN SELECT * FROM employees WHERE department_id = 1;
```

Using `EXPLAIN ANALYZE` is a step further than `EXPLAIN`, as it executes the query, providing actual execution times and row counts instead of estimated values.

```sql
EXPLAIN ANALYZE SELECT * FROM employees WHERE department_id = 1;
```

For more information, refer to the [EXPLAIN](https://neon.com/docs/postgresql/query-performance#use-explain) section in our query optimization guide.

### Index metrics

This query lists the number of index scans performed for all user-defined indexes.

```sql
SELECT indexrelname, relname, idx_scan FROM pg_stat_user_indexes;
```

The query returns the number of sequential scans for all user-defined tables, indicating missing indexes.

```sql
SELECT relname, seq_scan FROM pg_stat_user_tables;
```

For related information and more queries, see [Use indexes](https://neon.com/docs/postgresql/query-performance#use-indexes) in our query optimization guide.

### Read metrics

This query returns the number of rows fetched per database from storage or memory. It includes rows that are accessed to fulfill queries, which may involve filtering, joining, or processing of data. Not all fetched rows are necessarily sent back to the client, as some may be intermediate results used for query processing.

```sql
SELECT datname, tup_fetched FROM pg_stat_database;
```

This query returns the number of rows returned per database to the client after a query. This is the final set of rows after applying any filters, aggregates, or transformations specified by the query. These are typically the number of rows the client application or user sees as the query result.

```sql
SELECT datname, tup_returned FROM pg_stat_database;
```

### Write metrics

This query returns the number of rows inserted, updated, or deleted _per database_.

```sql
SELECT datname, tup_inserted, tup_updated, tup_deleted FROM pg_stat_database;
```

This query returns the number of rows inserted, updated, or deleted _per table_.

```sql
SELECT relname, n_tup_ins, n_tup_upd, n_tup_del FROM pg_stat_user_tables;
```

### List running queries by duration

To see currently running queries and their execution time, which can help identify long-running queries.

```sql
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE state = 'active'
ORDER BY duration DESC;
```

### Check for locks waiting to be granted

This query checks for locks that are currently waiting to be granted, which can be a sign of potential performance issues or deadlocks.

```sql
SELECT pg_locks.pid, relation::regclass, mode, query
FROM pg_locks
JOIN pg_stat_activity ON pg_locks.pid = pg_stat_activity.pid
WHERE NOT granted;
```

### Check for deadlocks by database

This query checks for deadlocks that have occurred, summarized by database.

```sql
SELECT datname, deadlocks FROM pg_stat_database;
```

### Count locks by table and lock mode

This query counts the number of locks per lock mode and table in a Postgres database, excluding system tables prefixed with `pg_`.

```sql
SELECT
    mode,
    pg_class.relname,
    COUNT(*)
FROM
    pg_locks
    JOIN pg_class ON pg_locks.relation = pg_class.oid
WHERE
    pg_locks.mode IS NOT NULL
    AND pg_class.relname NOT LIKE 'pg_%' ESCAPE '\'
GROUP BY
    pg_class.relname,
    mode;
```

### Index usage

Run this query to assess how effectively your queries are using indexes.

```sql
SELECT relname, seq_scan, idx_scan, n_tup_ins, n_tup_upd, n_tup_del
FROM pg_stat_user_tables
WHERE idx_scan < seq_scan AND idx_scan > 0
ORDER BY seq_scan DESC;
```

This `pg_stat_user_tables` query helps identify tables where sequential scans are more common than index scans, indicating potential areas for performance improvement through better indexing. The `pg_stat_user_tables` view is part of the Postgres [Cumulative Statistics System](https://www.postgresql.org/docs/current/monitoring-stats.html).

Also, see the [Use indexes](https://neon.com/docs/postgresql/query-performance#use-indexes) section in our query optimization guide.

### Table access statistics

This query shows how frequently tables are accessed, which can help in identifying which tables are hot for reads or writes.

```sql
SELECT relname, seq_scan, idx_scan, n_tup_ins, n_tup_upd, n_tup_del
FROM pg_stat_user_tables
ORDER BY n_tup_ins + n_tup_upd + n_tup_del DESC;
```

### VACUUM and ANALYZE statistics

This query checks the last time vacuum and analyze were run on each table, which helps ensure that your database is being maintained properly for query optimization.

```sql
SELECT schemaname, relname, last_vacuum, last_autovacuum, last_analyze, last_autoanalyze
FROM pg_stat_user_tables;
```

### Check for dead rows

This query fetches the names of user tables and the number of dead tuples (rows) in each.

```sql
SELECT relname, n_dead_tup FROM pg_stat_user_tables;
```

### Dead row percentage

This query calculates the percentage of dead rows compared to the total number of rows (alive and dead) in each user table within a Postgres database, helping identify potential table bloat and optimization opportunities. For related information, see [Check for table or index bloat](https://neon.com/docs/postgresql/query-performance#check-for-table-or-index-bloat).

```sql
SELECT
    relname,
    n_dead_tup,
    (CASE WHEN (n_live_tup + n_dead_tup) > 0 THEN
        ROUND((n_dead_tup::FLOAT / (n_live_tup + n_dead_tup))::numeric, 2)
    ELSE
        0
    END) AS dead_rows_percentage
FROM
    pg_stat_user_tables;
```

## Connections

The queries in this section use the [pg_stat_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) view, which is part of the Postgres [Cumulative Statistics System](https://www.postgresql.org/docs/current/monitoring-stats.html).

### Get the number of active connections

```sql
SELECT COUNT(*) FROM pg_stat_activity WHERE state='active';
```

### Get the maximum number of connections

Get the maximum number of connections for your Postgres instance.

```sql
SHOW max_connections;
```

The `max_connections` setting is configured by Neon according to your compute size configuration. See [Connection limits without connection pooling](https://neon.com/docs/connect/connection-pooling#connection-limits-without-connection-pooling).

**Tip:** You can use [connection pooling](https://neon.com/docs/connect/connection-pooling#connection-pooling) to increase your concurrent connection limit.

### Get the percentage of maximum connections in use

```sql
SELECT (SELECT SUM(numbackends) FROM pg_stat_database) / (SELECT
setting::float FROM pg_settings WHERE name = 'max_connections');
```

This query only considers your `max_connections` setting. It does not account for [connection pooling](https://neon.com/docs/connect/connection-pooling#connection-pooling).

### Get the current number of connections for a database

```sql
SELECT COUNT(*) FROM pg_stat_activity WHERE datname = 'your_database_name';
```

### Check for connections by user

```sql
SELECT usename, count(*)
FROM pg_stat_activity
GROUP BY usename;
```

### Find long-running or idle connections

```sql
SELECT
  pid,
  now() - pg_stat_activity.query_start AS duration,
  query,
  state
FROM
  pg_stat_activity
WHERE
  (now() - pg_stat_activity.query_start) > INTERVAL '1 minute'
  OR state = '<idle>';
```

### Cancel or terminate queries and sessions

To cancel or terminate a process:

- **Cancel a running query** (without ending the session):  
  Use `pg_cancel_backend(pid)`.

- **Terminate a session** (including all running queries):  
  Use `pg_terminate_backend(pid)`.

Examples:

Cancel a query:

```sql
SELECT pg_cancel_backend(pid)
FROM pg_stat_activity
WHERE datname = 'databasename'
  AND pid <> pg_backend_pid();
```

Terminate a session:

```sql
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE datname = 'databasename'
  AND pid <> pg_backend_pid()
  AND state = 'idle';
```

**Note:**

To identify long-running queries and the users executing them, run:

```sql
SELECT pid, usename, client_addr, application_name, state, query, now() - query_start AS duration
FROM pg_stat_activity
WHERE state <> 'idle'
ORDER BY duration DESC;
```

## Postgres version

Run this query to view your Postgres version.

```sql
SELECT version();
```

## Postgres settings

Run this query to view parameter settings for your Postgres instance.

```sql
SHOW ALL;
```

## Data size

Run this query to check the logical data size for a branch in Neon.

```sql
SELECT pg_size_pretty(sum(pg_database_size(datname)))
FROM pg_database;
```

Alternatively, you can check the **Data size** value on the **Branches** page in the Neon Console, which gives you the data size for the databases on that branch.

**Note:** Data size does not include the [history](https://neon.com/docs/reference/glossary#history) that is maintained in Neon to support features like instant restore.

--- [Document source](https://neon.com/docs/realtime/examples/drizzle.md) ---

> Summary: Use Drizzle ORM with Neon Realtime: add the Drizzle adapter, seal Drizzle selects with parameters and aliases, decode rows with drizzleParsers and return the txid from Drizzle writes.

# Drizzle example

Using Realtime with your Drizzle schema and queries.

Last updated: 2026-10-20

This page shows how to build a Realtime app with [Drizzle ORM](https://orm.drizzle.team), using your existing schema, queries, types and writes. You'll learn which Drizzle queries seal unchanged, when a field needs an SQL alias, how live rows keep Drizzle's types in the browser, and how a Drizzle write returns its transaction ID.

**Tip: Full examples on GitHub**

These apps in the `neondatabase/examples` repository use Drizzle:

- [`realtime/guides-chat-app`](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app): the chat app the guides build, with a snake_case schema
- [`realtime/with-react`](https://github.com/neondatabase/examples/tree/main/realtime/with-react): Hono and React, with a minimal Drizzle setup
- [`realtime/with-tanstack`](https://github.com/neondatabase/examples/tree/main/realtime/with-tanstack): TanStack Start, with a camelCase schema and an aliased column
- [`realtime/with-nextjs`](https://github.com/neondatabase/examples/tree/main/realtime/with-nextjs): Next.js and Managed Better Auth, with a per-user snake_case schema

## Setup

### Install the packages

Install the Realtime SDK, its Drizzle adapter, Drizzle and a Postgres driver:

```bash filename="Terminal"
npm install @neon/realtime @neon/realtime-drizzle drizzle-orm pg
npm install -D @types/pg
```

`@neon/realtime-drizzle` has two entry points. The main one exports `drizzleAdapter()` for your server. `@neon/realtime-drizzle/client` exports `drizzleParsers` for the browser and doesn't import Drizzle, so the ORM stays out of your browser bundle.

The queries guide's [setup](../guides/queries#setup) covers the rest: Neon's [Managed Better Auth](https://neon.com/docs/auth/overview), `neon.ts` and the environment variables. For Drizzle on Neon in general, see [Connect from Drizzle to Neon](https://neon.com/docs/guides/drizzle).

### Create the Realtime server

Pass `drizzleAdapter()` to [`createRealtime`](../sdks/typescript#backend-createrealtime), so the Realtime server accepts Drizzle queries:

```ts filename="backend/realtime.ts" {2,7}
import { createRealtime } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

export const realtime = createRealtime({
  secret: process.env.NEON_REALTIME_SECRET!,
  db: "neondb",
  adapter: drizzleAdapter()
})
```

- [`drizzleAdapter()`](../sdks/typescript#drizzle-drizzleadapter) takes no options. When you seal a Drizzle select, it compiles it to SQL and bind parameters
- `db` is the database name, such as `"neondb"`, not a Drizzle client. Use the database in your `DATABASE_URL`, and keep `NEON_REALTIME_SECRET` [on the server](../guides/queries#sealing-queries)
- the same server still seals [`rawSql`](../guides/queries#using-raw-sql) queries, so you can mix the two. Add `url` and it can [subscribe in trusted backend code](../guides/subscribing#subscribe-in-trusted-backend-code), where `subscribe()` takes a Drizzle query directly

## Defining queries

Define live queries with your usual Drizzle schema, client and select builder, in server code.

### Define the schema

Your schema stays plain Drizzle, with no Realtime imports or options. The choice that matters is how you name the keys. Snake_case keys, the same as the column names, are the simplest:

```ts filename="backend/schema.ts"
import { integer, pgTable, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core"

export const messages = pgTable("messages", {
  // No default: the client generates the ID, so an optimistic row already has its key
  id: uuid("id").primaryKey(),
  channel_id: integer("channel_id").notNull(),
  author_id: text("author_id").notNull(),
  body: text("body").notNull(),
  created_at: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
})

export const channelMembers = pgTable(
  "channel_members",
  {
    channel_id: integer("channel_id").notNull(),
    user_id: text("user_id").notNull()
  },
  (table) => [primaryKey({ columns: [table.channel_id, table.user_id] })]
)

export type Message = typeof messages.$inferSelect
```

- the adapter needs every selected key to match the name Postgres returns for it. With snake_case keys, no query needs an alias. For camelCase keys, see [Alias renamed and computed fields](https://neon.com/docs/realtime/examples/drizzle#alias-renamed-and-computed-fields)
- give each table a primary key. That's all Realtime needs from it. See the [table requirements](../guides/queries#table-requirements)
- `Message` is the row type of a select of every `messages` column. You'll use it when you [type rows in the browser](https://neon.com/docs/realtime/examples/drizzle#type-rows-in-the-browser)

Create the tables with your usual Drizzle workflow. Realtime needs nothing extra from your migrations: no publications, triggers or grants. See [Schema migration with Neon Postgres and Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations).

### Create the Drizzle client

You build live queries with your usual Drizzle `db`, but Realtime never runs them through it: the adapter only compiles them to SQL. `db` still runs your writes and any reads on the server, such as server-rendered rows:

```ts filename="backend/db.ts"
import { drizzle } from "drizzle-orm/node-postgres"
import { Pool } from "pg"
import * as schema from "./schema"

const pool = new Pool({
  // Neon URLs say sslmode=require. Asking pg for verify-full keeps today's checks and skips its warning
  connectionString: process.env.DATABASE_URL!.replace("sslmode=require", "sslmode=verify-full")
})
export const db = drizzle(pool, { schema })

// So an idle connection error, for example when the compute scales to zero, doesn't crash the API
pool.on("error", (error: Error) => console.error(error))
```

- any Drizzle Postgres driver works, `neon-http` included, because each [write](https://neon.com/docs/realtime/examples/drizzle#return-the-txid-from-drizzle-writes) returns its transaction ID in one statement. This page uses `drizzle-orm/node-postgres` with a `pg` pool
- `{ schema }` is only for Drizzle's relational `db.query` API, which [can't be sealed](https://neon.com/docs/realtime/examples/drizzle#common-pitfalls). Live queries use the select builder

### Define the live query

A live query is a Drizzle select that you build but don't await. Wrap it in a function, so each call builds a fresh query for its values:

```ts filename="backend/queries.ts"
import { and, desc, eq, getTableColumns } from "drizzle-orm"

import { db } from "./db"
import { channelMembers, messages } from "./schema"

export function messagesQuery(userId: string, channelId: number) {
  return db
    .select(getTableColumns(messages))
    .from(messages)
    .innerJoin(channelMembers, eq(channelMembers.channel_id, messages.channel_id))
    .where(and(eq(channelMembers.user_id, userId), eq(messages.channel_id, channelId)))
    .orderBy(desc(messages.created_at))
    .limit(50)
}
```

- `select(getTableColumns(messages))` keeps each row flat, with only the `messages` columns. A bare `select()` over a join [doesn't seal](https://neon.com/docs/realtime/examples/drizzle#common-pitfalls)
- the join is the authorization: a user only sees messages in channels they belong to, even as memberships change. See [live authorization](../guides/queries#live-authorization)
- `orderBy` and `limit` work as in any Drizzle query, so the live result is the 50 newest messages
- await the same function to read the rows on the server, for example to server-render the first results. See [return the sealed query and initial results](../guides/ssr#return-the-sealed-query-and-initial-results)

The adapter checks the query's shape when you seal it. The SQL is only checked when a client subscribes, so a query that writes or calls a non-deterministic function such as `now()` seals and then fails to subscribe. See the rules for [defining live queries](../guides/queries#defining-live-queries).

### Alias renamed and computed fields

Realtime returns rows with the names Postgres gives each result column, not the keys Drizzle maps them to. So `seal()` throws if a selected key doesn't match its result name. Snake_case keys always match. With camelCase keys over snake_case columns, a renamed field needs an SQL alias. Here's `messages` with camelCase keys:

```ts filename="backend/schema.ts"
import { integer, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core"

export const messages = pgTable("messages", {
  id: uuid("id").primaryKey(),
  channelId: integer("channel_id").notNull(),
  authorId: text("author_id").notNull(),
  body: text("body").notNull(),
  createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
})
```

A query over it aliases `createdAt`, the one selected key that differs from its column:

```ts filename="backend/queries.ts" {11}
import { eq, sql } from "drizzle-orm"

import { db } from "./db"
import { messages } from "./schema"

export function userMessagesQuery(userId: string) {
  return db
    .select({
      id: messages.id,
      body: messages.body,
      createdAt: sql<Date>`${messages.createdAt}`.mapWith(messages.createdAt).as("createdAt")
    })
    .from(messages)
    .where(eq(messages.authorId, userId))
}
```

- `id` and `body` match their columns, so they need nothing
- on its own, `createdAt: messages.createdAt` comes back as `created_at`, and `seal()` throws. ``sql<Date>`${messages.createdAt}`.as("createdAt")`` selects `"created_at" as "createdAt"`, and `sql<Date>` keeps the row type a `Date`
- `.mapWith(messages.createdAt)` only matters when Drizzle runs the query, for example when you await it to server-render. It decodes with the column's decoder, so you get a `Date` there too. Live rows don't need it: the Realtime client decodes by Postgres type. See [keep row shapes identical](../guides/ssr#keep-row-shapes-identical)
- only selected keys need to match, so filtering on `authorId` needs no alias

Computed fields, such as aggregates, follow the same rule: alias each one to its key, as in ``messageCount: sql<number>`count(*)::int`.as("messageCount")``. Cast with `::int` because Postgres returns `count(*)` as `int8`, which [arrives as a string](../guides/subscribing#subscribe-to-the-sealed-query).

## Sealing queries

Seal each query on the server. The browser can subscribe to a sealed query, but it can't read or change it, as the queries guide explains in [sealing queries](../guides/queries#sealing-queries).

### Pass query parameters

Drizzle has no special syntax for live query parameters: they're the values you pass to the query function. Fill them in on the server from context you trust. Take the user ID from the verified session, validate anything from the request, then seal with `realtime.seal({ query: messagesQuery(user.id, channelId) })`. The queries guide shows this in an [API endpoint](../guides/queries#exposing-an-endpoint) and a [server function](../guides/queries#using-server-functions).

- Drizzle compiles each value to a bind parameter. The sealed query carries the values alongside the SQL, never spliced into it
- each sealed query is for one set of values. To show another channel, the browser fetches a new sealed query. See [changing query parameters](../guides/reactivity#changing-query-parameters) and [renewing sealed queries](../guides/queries#renewing-sealed-queries)

### Parameter types

Values you compare with a column go through that column's Drizzle encoder. So unlike [raw SQL parameters](../guides/queries#parameter-types), a `Date` or JSON value needs no `pgParam` wrapper. This Drizzle version of the queries guide's [`messagesSinceQuery`](../guides/queries#parameter-types) passes `since` straight to `gt()`:

```ts filename="backend/recent-messages.ts" {15}
import { and, desc, eq, getTableColumns, gt } from "drizzle-orm"

import { db } from "./db"
import { channelMembers, messages } from "./schema"

export function messagesSinceQuery(userId: string, channelId: number, since: Date) {
  return db
    .select(getTableColumns(messages))
    .from(messages)
    .innerJoin(channelMembers, eq(channelMembers.channel_id, messages.channel_id))
    .where(
      and(
        eq(channelMembers.user_id, userId),
        eq(messages.channel_id, channelId),
        gt(messages.created_at, since)
      )
    )
    .orderBy(desc(messages.created_at))
    .limit(50)
}
```

The `timestamptz` column encodes `since` as an ISO string, and Postgres infers the parameter's type from the SQL.

## Subscribing to queries

Subscribe in the browser as the [subscribing guide](../guides/subscribing) shows. `@neon/realtime-drizzle/client` adds parsers that decode live rows like Drizzle results, and `seal()` gives the rows their type.

### Decode rows with `drizzleParsers`

Spread [`drizzleParsers`](../sdks/typescript#drizzle-client-drizzleparsers) into the Realtime client's parsers, so live rows decode the way Drizzle decodes the same columns:

```ts filename="frontend/client.ts"
import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"

export const client = createRealtimeClient({
  url: import.meta.env.VITE_NEON_REALTIME_URL,
  parsers: { ...drizzleParsers }
})
```

The parsers work by Postgres type, so for common column types a live row matches Drizzle's type. The exception is `bigint`, in either mode, which arrives as a string:

| Drizzle column                      | Drizzle's type | Live value with `drizzleParsers` |
| ----------------------------------- | -------------- | -------------------------------- |
| `timestamp({ withTimezone: true })` | `Date`         | `Date`                           |
| `timestamp()`                       | `Date`         | `Date`, read as UTC              |
| `date()`                            | `string`       | `string`                         |
| `integer()`                         | `number`       | `number`                         |
| `boolean()`                         | `boolean`      | `boolean`                        |
| `jsonb()`                           | `unknown`      | the parsed JSON value            |
| `numeric()`                         | `string`       | `string`                         |
| `bigint({ mode: "number" })`        | `number`       | `string`                         |
| `bigint({ mode: "bigint" })`        | `bigint`       | `string`                         |

Per-column modes, such as `date({ mode: "date" })` or `timestamp({ mode: "string" })`, aren't carried over. Nor are custom types or columns that Drizzle maps to tuples or arrays, such as `point()`, `line()` and `vector()`. For those, and for `bigint`, register a parser for the Postgres type with [`defineParsers`](../sdks/typescript#client-defineparsers), and decode server-rendered rows the same way. The subscribing guide lists [every default parser](../guides/subscribing#subscribe-to-the-sealed-query).

### Type rows in the browser

You don't write the row type yourself. [`seal()`](../sdks/typescript#backend-realtimeserverseal) infers it from the select: `realtime.seal({ query: messagesQuery(userId, channelId) })` returns a `SealedLiveQuery<Message>`. A typed API client, such as Hono's `hc`, carries that type to the browser. Hono types the response as JSON, though, so it types a `Date` column such as `created_at` as a `string`, while live rows decode it to a `Date`. See [fetch from an API endpoint](../guides/subscribing#fetch-from-an-api-endpoint).

- to name the row type in the browser, use `import type { Message } from "../backend/schema"`. TypeScript erases the import, so the schema stays out of the browser bundle
- `$inferSelect` fits `messagesQuery` because it selects every column. For a narrower or aliased selection, derive the type from the query: `type UserMessage = Awaited<ReturnType<typeof userMessagesQuery>>[number]`
- for the rest, see [subscribing to the sealed query](../guides/subscribing#subscribe-to-the-sealed-query) and the [React and TanStack DB bindings](../guides/reactivity)

## Optimistic mutations

The client holds each optimistic change until the write's transaction ID comes back on the subscription, so every write returns its txid. The mutations guide explains [how optimistic mutations work](../guides/mutations#how-optimistic-mutations-work).

### Return the txid from Drizzle writes

Return the [transaction ID](../guides/mutations#returning-the-txid-from-your-backend) from the write itself, by adding `pg_current_xact_id()` to its `RETURNING`. For example, a function that edits a message:

```ts filename="backend/server.ts"
import { and, eq, ne, sql } from "drizzle-orm"

import { db } from "./db"
import { messages } from "./schema"

export type MutationResponse =
  | { readonly kind: "committed"; readonly txid: string }
  | { readonly kind: "unchanged" }

// The id of the transaction that made the change, read in the write's own RETURNING
const txid = sql<string>`pg_current_xact_id()::text`

const mutationResponse = (row?: { txid: string }): MutationResponse =>
  row ? { kind: "committed", txid: row.txid } : { kind: "unchanged" }

export async function editMessage(userId: string, id: string, body: string): Promise<MutationResponse> {
  const [row] = await db
    .update(messages)
    .set({ body })
    .where(and(eq(messages.id, id), eq(messages.author_id, userId), ne(messages.body, body)))
    .returning({ txid })

  return mutationResponse(row)
}
```

- a single statement runs in its own transaction, so `RETURNING` gives you the ID of the transaction that made the change, in one round trip. Don't wrap the write in `db.transaction()` just to read the ID: that adds three more round trips and holds a connection
- the `text` cast keeps the 64-bit ID exact, as the decimal string the client waits for
- with no changed row, nothing comes over Realtime, so `mutationResponse()` returns `unchanged` and the client has nothing to wait for. `ne(messages.body, body)` skips edits that change nothing
- see how to [call these writes from the frontend](../guides/mutations#calling-the-routes-from-the-frontend)

## Common pitfalls

These Drizzle query shapes don't work as live queries. All but the last fail on the server: TypeScript rejects `.prepare()`, and the rest make `seal()` throw:

- **a bare `select()` over a join.** Drizzle nests each row by table, and the adapter can't name the nested fields. Select a flat object, such as `getTableColumns(messages)` or `{ id: messages.id, body: messages.body }`. A column from another table under a different key needs a matching alias
- **renamed keys and unaliased computed fields.** `{ authorId: messages.author_id }` and `{ total: count() }` throw until you [add an SQL alias](https://neon.com/docs/realtime/examples/drizzle#alias-renamed-and-computed-fields)
- **relational queries, prepared statements and placeholders.** `db.query.messages.findMany()`, `.prepare()` and `sql.placeholder()` don't give a select builder with bound values. Build a new select for each set of values, as [the query functions](https://neon.com/docs/realtime/examples/drizzle#pass-query-parameters) do
- **a `Date` or object straight inside a `sql` template.** `` sql`${messages.created_at} > ${since}` `` throws, because no column encodes `since`. Use a column operator such as `gt(messages.created_at, since)`, or pass `since.toISOString()`
- **Drizzle's `casing: "snake_case"` option.** With camelCase keys that don't name their columns, Drizzle writes `created_at` into the SQL, but the adapter checks the Drizzle name, `createdAt`. The query seals, and live rows have `created_at` while the type says `createdAt`. Name each column, as in `timestamp("created_at")`, and alias the renamed keys

## Next steps

- read the [queries guide](../guides/queries)
- see how the client applies writes optimistically in the [mutations guide](../guides/mutations)
- look up `drizzleAdapter()` and `drizzleParsers` in the [Drizzle section of the SDK reference](../sdks/typescript#drizzle)
- see Drizzle in a full-stack app in the [Next.js](./nextjs) and [TanStack](./tanstack) examples
- browse the full source of the [chat app](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app), [`with-react`](https://github.com/neondatabase/examples/tree/main/realtime/with-react), [`with-tanstack`](https://github.com/neondatabase/examples/tree/main/realtime/with-tanstack) and [`with-nextjs`](https://github.com/neondatabase/examples/tree/main/realtime/with-nextjs) on GitHub

--- [Document source](https://neon.com/docs/realtime/examples/kysely.md) ---

> Summary: Use Kysely with Neon Realtime: add the Kysely adapter, seal a Kysely select, keep live rows typed and return the txid from Kysely writes.

# Kysely example

Using Realtime with your Kysely schema and queries.

Last updated: 2026-10-20

This page shows how to build a Realtime app with [Kysely](https://kysely.dev), using your existing schema, queries, types and writes.

You'll learn how to [add the Kysely adapter](https://neon.com/docs/realtime/examples/kysely#create-the-realtime-server), [define your schema, migrations and live queries](https://neon.com/docs/realtime/examples/kysely#defining-queries), [pass query parameters](https://neon.com/docs/realtime/examples/kysely#passing-query-parameters), [keep end-to-end type-safety](https://neon.com/docs/realtime/examples/kysely#subscribing-to-queries) and [return the transaction ID from Kysely writes](https://neon.com/docs/realtime/examples/kysely#return-the-txid-from-kysely-writes).

**Tip: Full example on GitHub**

The [`realtime/with-kysely`](https://github.com/neondatabase/examples/tree/main/realtime/with-kysely) app in the `neondatabase/examples` repository is a framework-free TypeScript app built with Kysely and Realtime.

## Setup

### Install the packages

Install the Realtime SDK, its Kysely adapter, Kysely and the `pg` driver:

```bash filename="Terminal"
npm install @neon/realtime @neon/realtime-kysely kysely pg
npm install -D @types/pg
```

`@neon/realtime-kysely` exports `kyselyAdapter()` to use in your backend. There are no client imports. The queries guide's [setup](../guides/queries#setup) covers `neon.ts` and the environment variables. For Kysely on Neon in general, see [Connect from Kysely to Neon](https://neon.com/docs/guides/kysely).

### Create the Realtime server

Pass `kyselyAdapter()` to [`createRealtime`](../sdks/typescript#backend-createrealtime), so the Realtime server accepts Kysely queries:

```ts filename="src/server.ts" {2,7}
import { createRealtime } from "@neon/realtime/server"
import { kyselyAdapter } from "@neon/realtime-kysely"

const realtime = createRealtime({
  secret: env.realtime.secret,
  db: postgresDatabaseName,
  adapter: kyselyAdapter() // seals Kysely query builders, not raw SQL
})
```

- [`kyselyAdapter()`](../sdks/typescript#kysely-kyselyadapter) takes no options. When you seal a Kysely select, it compiles it to SQL and bind parameters
- `db` is the database name, not a Kysely instance. The example derives it from `DATABASE_URL` with `@neon/env` (as `postgresDatabaseName` in `src/env.ts`), reads the secret from the same parsed env, and keeps `NEON_REALTIME_SECRET` [on the server](../guides/queries#sealing-queries)
- the same server still seals [`rawSql`](../guides/queries#using-raw-sql) queries, so you can mix the two

## Defining queries

Define live queries with your usual Kysely schema, instance and select builder, in server code.

### Define the schema

Your `Database` interface stays plain Kysely. Use the column names as its keys:

```ts filename="src/schema.ts"
import type { Generated, Selectable } from "kysely"

// Kysely's types for the table. src/setup.ts creates it.
// Keys equal the column names: Realtime builds live rows from PostgreSQL's result names, so the
// live rows and the rows the server reads share the same keys.
export interface TodosTable {
  id: Generated<number> // SERIAL PRIMARY KEY
  title: string
  completed: Generated<boolean> // defaults to false
}

export interface Database {
  realtime_todos: TodosTable
}

// The row the live query returns. Kysely infers it from the table instead of a handwritten
// interface, keeping the `{ id, title, completed }` shape that api-types.ts and the client import.
export type Todo = Selectable<Database["realtime_todos"]>
```

Realtime names each field in a live row after the column name Postgres returns, so keys that match the columns keep live rows and Kysely's types in step. That's why [`CamelCasePlugin` doesn't work](https://neon.com/docs/realtime/examples/kysely#common-pitfalls).

The example creates the table once with Kysely's schema builder in `src/setup.ts`, run with `npm run db:setup`. You could also use a [Kysely migration](https://kysely.dev/docs/migrations) or your usual migration tool:

```ts filename="src/setup.ts"
await db.schema
  .createTable("realtime_todos")
  .ifNotExists()
  .addColumn("id", "serial", (column) => column.primaryKey())
  .addColumn("title", "text", (column) => column.notNull())
  .addColumn("completed", "boolean", (column) =>
    column.notNull().defaultTo(false)
  )
  .execute()

// Seed one row only when the table is empty, so re-running stays idempotent.
const existing = await db
  .selectFrom("realtime_todos")
  .select("id")
  .limit(1)
  .executeTakeFirst()
if (!existing) {
  await db
    .insertInto("realtime_todos")
    .values({ title: "Open this app in another tab" })
    .execute()
}
```

The primary key is all Realtime needs to work. See the [table requirements](../guides/queries#table-requirements) for more details.

### Create the Kysely instance

The example keeps the `pg` pool in `src/db.ts`:

```ts filename="src/db.ts"
import { Pool } from "pg"

import { env } from "./env.js"

export const pool = new Pool({
  connectionString: env.postgres.databaseUrl,
  max: 5,
  min: 1
})

pool.on("error", (error) => {
  console.error("Unexpected error on idle PostgreSQL client", error)
})
```

`src/server.ts` and `src/setup.ts` build a Kysely instance over that pool. The adapter compiles your queries using Kysely's PostgreSQL compiler, whatever your dialect. `db` still runs your writes and any reads on the server, such as server-rendered rows:

```ts filename="src/server.ts"
import { Kysely, PostgresDialect } from "kysely"

import { pool } from "./db.js"
import type { Database } from "./schema.js"

const db = new Kysely<Database>({
  dialect: new PostgresDialect({ pool })
})
```

### Define the live query

A live query is a Kysely select that you build but don't execute. Wrap it in a function, so each call builds a fresh query:

```ts filename="src/server.ts"
// The only place the live query is built, so the sealed query matches the rows the server reads.
const selectTodos = () =>
  db
    .selectFrom("realtime_todos")
    .select(["id", "title", "completed"])
    .orderBy("id")
```

- this example's list is shared, so the query has no `where` clause. To scope a live query so each user only sees their own rows, add a `where` on context you trust; that clause is the authorization. See [sealing authorized queries](../guides/queries#sealing-authorized-queries)
- call `.execute()` on the same builder to read the rows on the server, for example to server-render the first results. See [return the sealed query and initial results](../guides/ssr#return-the-sealed-query-and-initial-results)
- rename a field with an alias, as in `"id as todoId"`, and name a computed field with `.as()`
- `Todo` is the row type, which `src/schema.ts` infers from the table. You'll use it [in the browser](https://neon.com/docs/realtime/examples/kysely#subscribing-to-queries)

The adapter doesn't check the SQL. That happens when a client subscribes, so a query that calls a non-deterministic function such as `now()` seals and then fails to subscribe. See the rules for [defining live queries](../guides/queries#defining-live-queries).

## Sealing queries

### Passing query parameters

This example seals a single query with no parameters. When a query does need a parameter (like a user ID or search term) Kysely compiles each value to a bind parameter. The adapter encodes values the way node-postgres does, and Postgres infers each parameter's type from the SQL.

Where Postgres can't infer a parameter's type from the SQL, wrap the value in a [`pgParam`](../sdks/typescript#backend-pgparam) helper for a built-in type, inside a `sql` template.

## Subscribing to queries

Subscribe in the browser as the [subscribing guide](../guides/subscribing) shows. The client needs no Kysely-specific parsers: its defaults decode like node-postgres, which `PostgresDialect` uses, so each live row is the same `{ id, title, completed }` — a number, a string and a boolean — that Kysely reads on the server.

[`seal()`](../sdks/typescript#backend-realtimeserverseal) infers the row type from the select: `realtime.seal({ query: selectTodos() })` resolves to a [`SealedLiveQuery<Todo>`](../sdks/typescript#backend-sealedlivequery).

- to name the row type in the browser, use `import type { Todo } from "../../src/schema.js"`. TypeScript erases the import, so Kysely and your server code stay out of the browser bundle
- if your dialect runs on another driver, pass its parsers, such as [`postgresJsParsers`](../sdks/typescript#client-postgresjsparsers). For custom types, register a parser with [`defineParsers`](../sdks/typescript#client-defineparsers)
- for the rest, see [subscribing to the sealed query](../guides/subscribing#subscribe-to-the-sealed-query) and the [React and TanStack DB bindings](../guides/reactivity)

## Optimistic mutations

The client holds each optimistic change until the write's transaction ID comes back on the subscription, so every write returns its txid. The mutations guide explains [how optimistic mutations work](../guides/mutations#how-optimistic-mutations-work).

### Return the txid from Kysely writes

Return the [transaction ID](../guides/mutations#returning-the-txid-from-your-backend) from the write's own statement, with `.returning()`. Every mutation in the example — insert, toggle and delete — returns it. The example is a plain Node HTTP server; here is its toggle handler:

```ts filename="src/server.ts" {5,12}
import { sql } from "kysely"

// Same statement on every mutation: the client waits for this txid over Realtime before dropping
// its optimistic state, so the write must keep returning it.
const txid = sql<string>`pg_current_xact_id()::text`.as("txid")

// ...inside the request handler, for PATCH /api/todos/:id
const result = await db
  .updateTable("realtime_todos")
  .set({ completed: sql<boolean>`NOT completed` })
  .where("id", "=", Number(match[1]))
  .returning(txid)
  .executeTakeFirst()
return result
  ? json(response, 200, result satisfies MutationResponse)
  : json(response, 404, { error: "Todo not found" })
```

- `pg_current_xact_id()` runs in the write's statement, so it returns the ID of the transaction that made the change, with any driver. The `text` cast keeps the 64-bit ID exact, as the decimal string the client waits for
- `executeTakeFirst()` returns `undefined` when no row matched. Nothing comes over Realtime, so the handler responds `404` and the client has nothing to wait for
- the insert returns the new `id` too, with `.returning(["id", txid])`, so the client can swap its optimistic row for the real one. This demo doesn't authenticate its routes — add authorization before adapting it for production
- for writes that span several statements, run them all on `trx` in `db.transaction().execute(async (trx) => ...)`, and read the txid there with `trx.selectNoFrom(txid).executeTakeFirstOrThrow()`
- call it from a route or server function, and see how the frontend [calls these writes](../guides/mutations#calling-the-routes-from-the-frontend)

## Common pitfalls

These don't work as live queries:

- **`CamelCasePlugin`.** Its result transform doesn't apply to live rows, so they keep the snake_case column names while Kysely types camelCase keys. Aliases don't help, because the plugin snake-cases them too. Remove the plugin and use the column names as keys. For a camelCase field, alias the column, as in `"created_at as createdAt"`
- **anything but a select builder.** TypeScript rejects an executed result, a compiled query, an insert, update or delete builder, and a bare `` sql`...` `` template. Pass the builder from `selectFrom()`, and seal raw SQL with [`rawSql`](../sdks/typescript#backend-rawsql)

## Next steps

- read the [queries guide](../guides/queries)
- see how the client applies writes optimistically in the [mutations guide](../guides/mutations)
- look up `kyselyAdapter()` in the [Kysely section of the SDK reference](../sdks/typescript#kysely)
- browse the full [`realtime/with-kysely`](https://github.com/neondatabase/examples/tree/main/realtime/with-kysely) example on GitHub

--- [Document source](https://neon.com/docs/realtime/examples/mastra.md) ---

> Summary: Use Mastra with Neon Realtime: start agents from your writes, store their memory and traces in Postgres, sync them to the browser and restart them when users edit.

# Mastra example

Using Realtime with Mastra to keep users and agents in sync.

Last updated: 2026-10-15

To Realtime, a [Mastra](https://mastra.ai) agent is one more writer on your data. This example [triggers agents when users write data](https://neon.com/docs/realtime/examples/mastra#start-agents-from-your-writes) and [syncs agent activity](https://neon.com/docs/realtime/examples/mastra#sync-agent-activity-to-the-browser) and [agent sessions](https://neon.com/docs/realtime/examples/mastra#store-mastras-data-in-your-database) through the database.

**Tip: Full example on GitHub**

The complete app is in the [`thruflo/livebase`](https://github.com/thruflo/livebase) repository.

## Store Mastra's data in your database

Point Mastra's storage at your database, so Realtime can sync agent sessions, memory and traces:

```ts filename="src/server/mastra/mastra.server.ts" {8,13}
import { Agent } from "@mastra/core/agent"
import { Mastra } from "@mastra/core/mastra"
import { Memory } from "@mastra/memory"
import { MastraStorageExporter, Observability } from "@mastra/observability"
import { PostgresStore } from "@mastra/pg"
import { pool } from "~/server/db.server"

const storage = new PostgresStore({ id: "app-storage", pool, schemaName: "public" })
const memory = new Memory({ storage, options: { lastMessages: false } })
const enrichmentAgent = new Agent({
  id: "enrichment-agent", name: "Enrichment agent", instructions: "...", model: "...", memory
})
const exporter = new MastraStorageExporter({ strategy: "batch-with-updates", maxBatchWaitMs: 250 })

export const mastra = new Mastra({
  agents: { enrichmentAgent },
  storage,
  observability: new Observability({ configs: { default: { serviceName: "app", exporters: [exporter] } } })
})
```

`PostgresStore` on your `pg` pool and `public` schema puts `mastra_threads`, `mastra_messages` and `mastra_ai_spans` next to your tables. Use it rather than `PostgresStoreVNext`, because that only stores finished spans. Whereas here, `batch-with-updates` inserts each span when it starts and updates it when it ends, so the browser sees all the agent steps in progress.

## Start agents from your writes

This server function creates a record, then starts its agent:

```ts filename="src/functions/leads.ts" {18-19,21}
import { createServerFn } from "@tanstack/react-start"
import { z } from "zod"
import { leadInputs, leads } from "~/db/schema"
import { db } from "~/server/db.server"
import { startLead } from "~/server/runner.server"
import { txid } from "~/server/txid.server"
import { requireWorkspace } from "~/server/workspace.server"

export const createLead = createServerFn({ method: "POST" })
  .validator(z.object({ leadId: z.uuid(), inputId: z.uuid(), rawText: z.string().min(1) }))
  .handler(async ({ data: { leadId, inputId, rawText } }) => {
    const { workspaceId } = await requireWorkspace()
    const result = await db.transaction(async (tx) => {
      await tx.insert(leads).values({ id: leadId, workspaceId })
      const [input] = await tx
        .insert(leadInputs)
        .values({ id: inputId, workspaceId, leadId, rawText })
        .returning({ txid })
      return { txid: input!.txid }
    })
    startLead({ leadId, workspaceId })
    return result
  })
```

- `requireWorkspace()` stands in for your auth check
- `txid` is `pg_current_xact_id()::text`. Both inserts share one transaction, and the second returns its ID, so there's no extra select. The client waits for that txid to [confirm its optimistic insert](../guides/mutations#returning-the-txid-from-your-backend)
- `startLead()` runs after the commit, so the agent reads committed rows, and returns without holding up the response

## Run the agent on a thread

Each run is one `generate()` call on the record's thread:

```ts filename="src/server/pipeline.server.ts" {12,17}
import type { LeadRef } from "~/lib/types"
import { enrichmentPrompt } from "~/server/enrichment/prompt"
import { recordTools } from "~/server/enrichment/record-tools.server"
import { mastra } from "~/server/mastra/mastra.server"

import { loadEnrichmentSnapshot, setLeadStatus } from "./persist.server"

export async function runEnrichment({ leadId, workspaceId, signal }: LeadRef & { signal: AbortSignal }) {
  const snapshot = await loadEnrichmentSnapshot({ leadId, workspaceId })
  await setLeadStatus({ leadId, workspaceId, status: "enriching" })
  await mastra.getAgent("enrichmentAgent").generate(enrichmentPrompt(snapshot), {
    memory: { thread: leadId, resource: workspaceId },
    toolsets: { enrichment: recordTools({ leadId, workspaceId, signal }) },
    savePerStep: true,
    abortSignal: signal
  })
  signal.throwIfAborted()
  await setLeadStatus({ leadId, workspaceId, status: "ready" })
}
```

- Mastra stores `thread` and `resource` on every thread, message and span row, and live queries filter on them. Here the thread is the record and the resource is the workspace
- `savePerStep: true` saves messages after each step, so they reach the browser while the agent works
- `generate()` can resolve after an abort, so `throwIfAborted()` keeps an aborted run from marking the record `ready`
- `recordTools()` returns Mastra `createTool()` tools that write domain rows with `updatedBy: "agent"`

## Sync agent activity to the browser

Seal Mastra's tables the way you [seal your own](../guides/queries#sealing-queries).

### Seal the spans on the server

This server function seals the workspace's spans. Records, threads and messages seal the same way:

```ts filename="src/functions/seal.ts" {14-15,19}
import { createServerFn } from "@tanstack/react-start"
import { eq, getTableColumns, sql } from "drizzle-orm"

import { mastraAiSpans } from "~/db/mastra-schema"
import { db } from "~/server/db.server"
import { realtime } from "~/server/realtime.server"
import { requireWorkspace } from "~/server/workspace.server"

export const sealSpans = createServerFn({ method: "POST" }).handler(async () => {
  const { workspaceId } = await requireWorkspace()
  const query = db
    .select({
      ...getTableColumns(mastraAiSpans),
      startedAt: sql<Date | null>`${mastraAiSpans.startedAt}`.as("startedAt"),
      endedAt: sql<Date | null>`${mastraAiSpans.endedAt}`.as("endedAt")
    })
    .from(mastraAiSpans)
    .where(eq(mastraAiSpans.resourceId, workspaceId))
  return realtime.seal({ query })
})
```

- `mastraAiSpans` declares only the columns you sync. Mastra creates and migrates the table, so keep it out of your Drizzle migrations
- Mastra's timestamp column names differ from their Drizzle field names, so `startedAt` and `endedAt` need an [SQL alias](./drizzle#alias-renamed-and-computed-fields)
- [`realtime.seal()`](../sdks/typescript#backend-realtimeserverseal) seals the server's `workspaceId`, so a browser only gets its own workspace's spans

### Filter the spans in the browser

A TanStack DB collection holds the sealed spans, and `useLiveQuery` narrows them to one record's thread:

```ts filename="src/realtime/activity.ts" {11-12}
import { eq, useLiveQuery } from "@tanstack/react-db"

import { useRealtime } from "~/realtime/RealtimeProvider"

export function useLeadActivity(leadId: string) {
  const { descriptors } = useRealtime()
  const { data: spans } = useLiveQuery({
    query: (q) =>
      q
        .from({ span: descriptors.spans })
        .where(({ span }) => eq(span.threadId, leadId))
        .orderBy(({ span }) => span.startedAt, "asc")
  })
  return spans
}
```

- `descriptors.spans` comes from [`realtimeCollectionOptions()`](../sdks/typescript#tanstack-db-realtimecollectionoptions) with `refreshQuery: () => sealSpans()`. Its `getKey` returns `` `${span.traceId}:${span.spanId}` ``, for the table's composite primary key
- the sealed query has no `ORDER BY`, so order the spans in `useLiveQuery`

See the [TanStack example](./tanstack) for collections, SSR and optimistic writes.

## Restart agents when users edit

When a user edits a record, commit the update, then call `restartEnrichment()`. The runner keeps one `AbortController` per record:

```ts filename="src/server/runner.server.ts" {11,17}
import type { LeadRef } from "~/lib/types"
import { markLeadFailed, runEnrichment } from "./pipeline.server"

const jobs = new Map<string, { controller: AbortController }>()
const restartTimers = new Map<string, ReturnType<typeof setTimeout>>()
export function startLead(ref: LeadRef) {
  const job = { controller: new AbortController() }
  jobs.set(ref.leadId, job)
  runEnrichment({ ...ref, signal: job.controller.signal })
    .catch((error) => job.controller.signal.aborted || markLeadFailed(ref, String(error)))
    .finally(() => jobs.get(ref.leadId) === job && jobs.delete(ref.leadId))
}

export function restartEnrichment(ref: LeadRef) {
  clearTimeout(restartTimers.get(ref.leadId))
  jobs.get(ref.leadId)?.controller.abort()
  restartTimers.set(ref.leadId, setTimeout(() => startLead(ref), 1_500))
}
```

- `restartEnrichment()` aborts the running job and starts a new one after 1.5 seconds. Each edit resets the timer, so a burst of edits restarts once
- the `jobs.get(ref.leadId) === job` check keeps an aborted run that settles late from removing its replacement

The abort reaches `generate()` through its `abortSignal` and the tools check the same signal before each write. Agents only write fields that are empty or still hold the agent's own earlier value, so a user's edit always wins. Each run starts with a fresh read, so the restarted run works from the user's values.

## Next steps

- read the guides on [queries](../guides/queries), [subscribing](../guides/subscribing) and [optimistic mutations](../guides/mutations)
- look up `realtime.seal()` and `realtimeCollectionOptions()` in the [SDK reference](../sdks/typescript)
- see the [Drizzle](./drizzle) and [TanStack](./tanstack) examples
- read Mastra's docs on [storage](https://mastra.ai/docs/storage), [memory](https://mastra.ai/docs/memory/overview) and [tracing](https://mastra.ai/docs/observability/tracing/overview)
- browse the [full source on GitHub](https://github.com/thruflo/livebase)

--- [Document source](https://neon.com/docs/realtime/examples/nextjs.md) ---

> Summary: Build a per-user todo app with Next.js, Drizzle and Managed Better Auth on Neon Realtime: read and seal live queries in a Server Component, renew them through a Route Handler, and settle optimistic server action writes by txid.

# Next.js example

Full-stack example app using Realtime with Next.js.

Last updated: 2026-10-30

This example shows how to use Neon Realtime with [Next.js](https://nextjs.org), [Drizzle ORM](https://orm.drizzle.team) and Neon's [Managed Better Auth](https://neon.com/docs/auth/overview), with support for [auth](https://neon.com/docs/realtime/examples/nextjs#authorize-with-the-session), [SSR](https://neon.com/docs/realtime/examples/nextjs#server-side-rendering), [client-side reactivity](https://neon.com/docs/realtime/examples/nextjs#client-side-reactivity) and [optimistic mutations](https://neon.com/docs/realtime/examples/nextjs#optimistic-mutations).

The sections follow the same order as the guides, from [defining](https://neon.com/docs/realtime/examples/nextjs#defining-queries) and [sealing](https://neon.com/docs/realtime/examples/nextjs#sealing-queries) queries to writing to them, and show the Next.js code for each step.

**Tip: Full example on GitHub**

The complete app is in the [`realtime/with-nextjs`](https://github.com/neondatabase/examples/tree/main/realtime/with-nextjs) folder of the `neondatabase/examples` repository.

## Setup

Install the Realtime SDK with its Drizzle adapter and React bindings, Drizzle ORM and `drizzle-kit` for migrations:

```bash filename="Terminal"
npm install @neon/realtime @neon/realtime-drizzle @neon/realtime-react drizzle-orm
npm install -D drizzle-kit dotenv
```

Add a `neon.ts` that enables Managed Better Auth and Realtime on your branch:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1"

export default defineConfig({
  auth: true,
  preview: {
    realtime: {
      allowedOrigins: ["http://localhost:3000"]
    }
  }
})
```

`allowedOrigins` lists the browser origins that can connect to Realtime. A missing origin doesn't raise an error: the subscription stays `connecting`, so add your app's origin when you deploy it. The [`neon.ts` reference](https://neon.com/docs/reference/neon-ts) covers the options.

Link the directory and run `neon deploy`, as in the [queries guide's setup](../guides/queries#setup). It writes `DATABASE_URL`, `NEON_REALTIME_URL`, `NEON_REALTIME_SECRET` and `NEON_AUTH_BASE_URL` to `.env.local`. If Realtime isn't ready before the deploy stops waiting, run `neon env pull` once it is.

The Managed Better Auth server SDK also needs a cookie secret of at least 32 characters, which comes from you:

```bash filename="Terminal"
printf '\nNEON_AUTH_COOKIE_SECRET=%s\n' "$(openssl rand -base64 32)" >> .env.local
```

The browser needs the Realtime URL too. You can pass it from the server as a prop when you [render the page](https://neon.com/docs/realtime/examples/nextjs#render-in-a-server-component), instead of adding a `NEXT_PUBLIC_` copy as the [SSR guide](../guides/ssr#open-the-connection-in-the-browser) does.

Create anything that needs a secret on first use, not at module scope, because `next build` imports your modules without the runtime secrets. The `get*()` helpers on this page all do this, starting with `getEnv()` in `src/lib/env.ts`, which reads and checks these variables.

Note that `NEON_REALTIME_SECRET` never gets a `NEXT_PUBLIC_` prefix. The browser should only ever see the URL and sealed queries.

### Define the schema

Define your database schema. In this example, we're using Drizzle and defining a single table:

```ts filename="src/lib/schema.ts"
import { boolean, index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core"

// The single schema source: the app and `drizzle-kit push` both read it. Columns are declared snake_case
// on purpose. Realtime builds live rows from PostgreSQL's result names, so a camelCase JS property that
// mapped to a different column would give live rows different keys from server rows.
export const todos = pgTable(
  "realtime_next_todos",
  {
    // uuid, created in the browser, so the optimistic row and the live row share it. This primary key is
    // the replica identity Realtime needs.
    id: uuid("id").primaryKey(),
    // uuid, the Managed Better Auth user id; only ever set from the session. No foreign key to
    // neon_auth."user": this app doesn't manage the neon_auth schema.
    user_id: uuid("user_id").notNull(),
    title: text("title").notNull(),
    completed: boolean("completed").notNull().default(false),
    // timestamptz: pg and the Realtime client both parse it to a Date.
    created_at: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
  },
  // Supports the `WHERE user_id = … ORDER BY created_at DESC` live query.
  (t) => [index("realtime_next_todos_user_id_created_at_idx").on(t.user_id, t.created_at)]
)

export type Todo = typeof todos.$inferSelect
```

Give the table a primary key, here `id`, and create it with [`drizzle-kit push`](https://neon.com/docs/guides/drizzle-migrations) or your usual migration tool. A primary key is all Realtime needs from the table, as [table requirements](../guides/queries#table-requirements) explains.

## Defining queries

Define, run and seal your live queries on the server, both to provide `initialData` for SSR and to pass to the client to subscribe to.

### Define the live query

We then [define a query](../guides/queries#using-a-query-builder-or-orm) with Drizzle. `getDb()` returns a Drizzle client over a node-postgres (`pg`) pool, in `src/lib/db.ts`:

```ts filename="src/lib/todos.ts"
import "server-only"

import { desc, eq } from "drizzle-orm"

import { getDb } from "./db"
import { todos } from "./schema"

// The only place the live query is built. The server read, the seal and every renewal use it, so their
// fingerprints match. `userId` must come from getUser(), never from the client.
function todosQuery(userId: string) {
  return getDb()
    .select({
      id: todos.id,
      title: todos.title,
      completed: todos.completed,
      created_at: todos.created_at
    })
    .from(todos)
    .where(eq(todos.user_id, userId))
    .orderBy(desc(todos.created_at), desc(todos.id))
}

export type TodoRow = Awaited<ReturnType<typeof todosQuery>>[number]
```

`TodoRow` is the row type Drizzle infers from the select. The browser imports it as a type only, so no server code reaches it. `userId` always comes from the [server session](https://neon.com/docs/realtime/examples/nextjs#authorize-with-the-session), never from the browser, and this `WHERE` keeps each user's todos separate.

Live rows keep the query's `ORDER BY` order. The browser still [sorts them](https://neon.com/docs/realtime/examples/nextjs#apply-writes-optimistically) so optimistic rows, which aren't in the live result yet, land in the right place.

## Sealing queries

Seal the query on the server, for the user in the session. The browser can subscribe to a sealed query, but it can't read or change it, as the queries guide explains in [sealing queries](../guides/queries#sealing-queries).

### Create the Realtime server

The Realtime server, from [`createRealtime()`](../sdks/typescript#backend-createrealtime), holds the secret and seals queries. It should be created and then used in your trusted server code. Pass it [`drizzleAdapter()`](../sdks/typescript#drizzle-drizzleadapter), so it can seal Drizzle queries:

```ts filename="src/lib/realtime.ts"
import "server-only"

import { createRealtime } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

import { getEnv } from "./env"

let realtime: ReturnType<typeof create> | undefined
function create() {
  const env = getEnv()
  return createRealtime({
    secret: env.realtimeSecret,
    db: env.database,
    adapter: drizzleAdapter(),
    debugMode: process.env.NODE_ENV === "development" // full database errors in dev only
  })
}
export const getRealtime = () => (realtime ??= create())
```

`import "server-only"` makes the build fail if a Client Component imports the file, as [the SSR guide explains](../guides/ssr#keep-secrets-on-the-server). `getRealtime()` creates the Realtime server once, on first use, and every request seals its own query with it. `debugMode` [shows full database errors](../guides/subscribing#show-full-database-errors) in development.

### Authorize with the session

Get the user from the [Managed Better Auth](https://neon.com/docs/auth/overview) session before you read, seal or write anything:

```ts filename="src/auth/server.ts"
import "server-only"

import { createNeonAuth } from "@neon/auth/next/server"

import { getEnv } from "../lib/env"

let auth: ReturnType<typeof createNeonAuth> | undefined
/** Lazy: createNeonAuth checks the cookie secret when constructed, and throws without it. */
export function getAuth() {
  return (auth ??= createNeonAuth({
    baseUrl: getEnv().authBaseUrl,
    cookies: { secret: getEnv().authCookieSecret }
  }))
}

/**
 * The signed-in user, or null. Call it first in every Server Component data path, Server Action and
 * Route Handler: proxy.ts is not the security boundary. Pass the user id the page was loaded for, and a
 * different signed-in user counts as signed out. That id is only compared, never used to scope a query.
 */
export async function getUser(pageUserId?: string) {
  const { data, error } = await getAuth().getSession() // returns { data, error }; doesn't throw on HTTP errors
  // If Managed Better Auth can't be reached, treat the request as signed out.
  if (error) console.warn("[auth] getSession failed", error.code)
  const user = data?.user ?? null
  return pageUserId === undefined || user?.id === pageUserId ? user : null
}
```

`getUser()` wraps [`auth.getSession()`](https://neon.com/docs/auth/reference/nextjs-server#auth-getsession). The rest of `src/auth/` is Managed Better Auth setup: the auth route, the client and the [prebuilt sign-in UI](https://neon.com/docs/auth/reference/ui-components#nextjs-app-router), as in the [Managed Better Auth Next.js quick start](https://neon.com/docs/auth/quick-start/nextjs-api-only).

Make every session change a full page load to `/`, which drops the Realtime client and the previous user's rows. In `AuthProvider`, `navigate` calls `window.location.assign("/")` when the target is `/`. After Sign out, or a renewal or write the server refuses, `leaveSession()` in `src/auth/session-lost.ts` does the same. The SSR guide explains why in [when the session changes](../guides/ssr#when-the-session-changes).

### Seal in a Route Handler

Expose the sealed query from a POST [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers), as in [exposing an endpoint](../guides/queries#exposing-an-endpoint).

The browser calls it to [renew the sealed query](../guides/queries#renewing-sealed-queries) before it expires, so it has to seal exactly the same query. Add a helper to `src/lib/todos.ts`, and put its import at the top of the file:

```ts filename="src/lib/todos.ts"
import { getRealtime } from "./realtime"

export const sealTodos = (userId: string) => getRealtime().seal({ query: todosQuery(userId) })
```

Then call it from the Route Handler, for the user in the session:

```ts filename="src/app/api/todos/live-query/route.ts"
import { getUser } from "../../../../auth/server"
import { sealTodos } from "../../../../lib/todos"

const noStore = { "Cache-Control": "private, no-store" }

// Renewal is a read, so it's a Route Handler. A Server Action would queue behind pending writes.
export async function POST(request: Request) {
  const { userId } = await request.json() // the user the page was loaded for
  const user = await getUser(userId)
  if (!user) return Response.json({ error: "UNAUTHENTICATED" }, { status: 401, headers: noStore })
  return Response.json(await sealTodos(user.id), { headers: noStore })
}
```

Next.js runs server actions one at a time, so renew through a Route Handler rather than a server action, as the [subscribing guide](../guides/subscribing#fetch-from-a-server-function) recommends. The browser sends the user id the page was loaded for, and the handler answers 401 if the session has no user or a different one. `Cache-Control: private, no-store` keeps the sealed query, a [bearer token](../guides/queries#sealing-queries), out of caches.

## Server-side rendering

Next.js renders the first request on the server. To put the user's rows in that HTML and keep them live in the browser:

1. read and seal the query in one function
2. call it from a Server Component at request time, and pass the initial query results and the sealed query to a Client Component as props
3. create the Realtime client in the browser, where the Client Component subscribes after hydration

The SSR guide covers the pattern in [send both to the browser](../guides/ssr#send-both-to-the-browser).

### Read and seal together

Run the query and seal it in the same function, so the rows and the sealed query match, as in [return the sealed query and initial results](../guides/ssr#return-the-sealed-query-and-initial-results). Add it to `src/lib/todos.ts`, which already imports everything it uses:

```ts filename="src/lib/todos.ts"
// Read and seal the same query. The stream's first full result replaces these rows, so nothing is missed
// or doubled. It sends every row again rather than resuming from these.
export async function loadTodos(userId: string) {
  const query = todosQuery(userId)
  const [rows, sealedQuery] = await Promise.all([
    query, // awaiting the builder runs it
    getRealtime().seal({ query }) // compiles the builder to SQL; never runs it
  ])
  return { rows, sealedQuery }
}
```

[`seal()`](../sdks/typescript#backend-realtimeserverseal) returns a typed [`SealedLiveQuery<TodoRow>`](../sdks/typescript#backend-sealedlivequery), so the row type flows through to the Client Component.

### Render in a Server Component

Call `loadTodos()` from an async Server Component, for the user in the session, and pass the results to the Client Component as props:

```tsx filename="src/app/todos.tsx"
import { redirect } from "next/navigation"
import { connection } from "next/server"

import { getUser } from "../auth/server"
import { UserMenu } from "../auth/user-menu"
import { getEnv } from "../lib/env"
import { loadTodos } from "../lib/todos"

import { RealtimeRoot } from "./realtime-root"
import { TodoList } from "./todo-list"

export async function Todos() {
  // Request time only. During `next build` connection() never resolves, so nothing below runs at build.
  // The sealed query is a bearer token for this user's data: never prerender or cache it.
  await connection()
  const user = await getUser()
  // Backstop: proxy.ts already redirected signed-out page loads over HTTP.
  if (!user) redirect("/auth/sign-in")
  const { rows, sealedQuery } = await loadTodos(user.id)
  return (
    <>
      {/* Here rather than in page.tsx, which has no data access. */}
      <UserMenu email={user.email} />
      {/* Keyed on the query's identity. A re-render for the same query (router.refresh(), a cookie refresh)
          keeps the subscription. A deploy that changed the SQL remounts the list. */}
      <RealtimeRoot key={sealedQuery.queryFingerprint} url={getEnv().realtimeUrl}>
        <TodoList initialTodos={rows} sealedQuery={sealedQuery} userId={user.id} />
      </RealtimeRoot>
    </>
  )
}
```

[`connection()`](https://nextjs.org/docs/app/api-reference/functions/connection) waits for an incoming request, so the component never prerenders and its output, which belongs to one user and one request, is never cached. The SSR guide uses `force-dynamic` for the same reason. `connection()` also works when your app enables `cacheComponents`, inside a `<Suspense>` boundary.

The key on `queryFingerprint` keeps the subscription across re-renders for the same query, and remounts the list when a deploy changes the SQL. `TodoList` gets the user id to send with each renewal and write.

Render the component inside a `<Suspense>` boundary, so the rest of the page renders at once and the list streams in:

```tsx filename="src/app/page.tsx"
import { Suspense } from "react"

import { Todos } from "./todos"

// No data access here: the static shell renders at once and <Todos /> streams in at request time.
export default function Page() {
  return (
    <main>
      <Suspense fallback={<p>Loading todos</p>}>
        <Todos />
      </Suspense>
    </main>
  )
}
```

### Keep signed-in pages private

Inside `<Suspense>`, `redirect()` only takes effect in the browser, after the page has started streaming. To send signed-out page loads a real HTTP redirect, check the session in the [proxy](https://nextjs.org/docs/app/api-reference/file-conventions/proxy) too:

```ts filename="src/proxy.ts"
import type { NextRequest } from "next/server"

import { getAuth } from "./auth/server"

let middleware: ReturnType<ReturnType<typeof getAuth>["middleware"]> | undefined

export default function proxy(request: NextRequest) {
  // Signed-out page loads get an HTTP redirect. Server Actions skip it and return UNAUTHENTICATED themselves.
  if (request.headers.has("next-action")) return
  middleware ??= getAuth().middleware({ loginUrl: "/auth/sign-in" })
  return middleware(request)
}

// Only the app page. /auth/* is public, and /api/* routes answer 401 themselves. Add new app pages here.
export const config = { matcher: ["/"] }
```

[`auth.middleware()`](https://neon.com/docs/auth/reference/nextjs-server#auth-middleware) does the redirect and refreshes the session cookies. The redirect is for the user experience only: every Server Component, Route Handler and server action checks the session again with `getUser()`.

### Create the Realtime client in the browser

Create the Realtime client once, inside the React tree, in a `useState` initializer, and provide it with [`RealtimeProvider`](../sdks/typescript#react-realtimeprovider). This is [open the connection in the browser](../guides/ssr#open-the-connection-in-the-browser) as a Client Component:

```tsx filename="src/app/realtime-root.tsx"
"use client"

import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"
// @neon/realtime-react's build has no "use client" directive: import it only from client modules.
import { RealtimeProvider } from "@neon/realtime-react"
import { type ReactNode, useState } from "react"

export function RealtimeRoot({ url, children }: { url: string; children: ReactNode }) {
  // drizzleParsers make the browser parse live rows the way Drizzle parses server rows, so created_at
  // stays a Date and completed a boolean (todo-list.tsx reads both).
  const [client] = useState(() => createRealtimeClient({ url, parsers: { ...drizzleParsers } }))
  return <RealtimeProvider client={client}>{children}</RealtimeProvider>
}
```

Creating the client doesn't connect, so it's safe during the server render. It connects on the first subscribe and disconnects after the last one ends, so you don't need an effect that closes it. With `drizzleParsers`, live rows have the same types as the rows Drizzle reads on the server, and Server Component props keep `created_at` a `Date`, as [keep row shapes identical](../guides/ssr#keep-row-shapes-identical) explains.

Render `RealtimeRoot` around the components that subscribe. With one live query on the page, it can wrap that component and share its key, as `Todos` does. With several, render it higher up, for example in your root layout, and key each subscribing component on its own `queryFingerprint`.

## Client-side reactivity

In the browser, [`useLiveQuery()`](../sdks/typescript#react-uselivequery) subscribes to the sealed query and re-renders with each result. It's standard React, so the reactivity guide covers the hook in [React](../guides/reactivity#react). With Next.js, the Client Component also has to survive server re-renders and renew through the Route Handler.

### Subscribe with `useLiveQuery()`

Render the server's rows straight away, and keep them live. This is the start of the `TodoList` Client Component:

```tsx filename="src/app/todo-list.tsx"
"use client"

import type { SealedLiveQuery } from "@neon/realtime/client"
// @neon/realtime-react's build has no "use client" directive: import it only from client modules.
import { useLiveQuery } from "@neon/realtime-react"
import { useCallback, useState } from "react"

import { renewOrLeave } from "../auth/session-lost"
import type { TodoRow } from "../lib/todos" // type-only: erased at build, so no server code reaches the browser

export function TodoList({
  initialTodos,
  sealedQuery,
  userId
}: {
  initialTodos: TodoRow[]
  sealedQuery: SealedLiveQuery<TodoRow>
  userId: string
}) {
  // Keep the first sealed query. useLiveQuery restarts its subscription whenever it gets a new object, and
  // every server re-render (router.refresh(), a Server Action that sets a cookie) sends one for the same
  // query. Renewals go through refreshQuery. A different query remounts this list through the key in todos.tsx.
  const [query] = useState(sealedQuery)

  // Sends the page's user id: a 401 means signed out or signed in as someone else, and the page leaves.
  const refreshQuery = useCallback(
    () =>
      renewOrLeave<SealedLiveQuery<TodoRow>>(() =>
        fetch("/api/todos/live-query", { method: "POST", cache: "no-store", body: JSON.stringify({ userId }) })
      ),
    [userId]
  )

  const { data, status, utils } = useLiveQuery(query, { initialData: initialTodos, refreshQuery })
```

Server re-renders are routine in Next.js: `router.refresh()` and server actions that set cookies both cause them. Each one sends a new sealed-query object for the same query, so keep the first one in state, as [send both to the browser](../guides/ssr#send-both-to-the-browser) explains, and renew through [`refreshQuery`](../guides/reactivity#refreshquery), which posts to the [Route Handler](https://neon.com/docs/realtime/examples/nextjs#seal-in-a-route-handler).

After a 401, `renewOrLeave()` stops renewing and leaves the page, which unmounts the list, as [handling errors](../guides/reactivity#handling-errors) recommends. The `error` status is final for a subscription, and there's no client API to restart one, so while the status is `error`, offer a button that calls `window.location.reload()`.

On the first request, the rows go from the server's query to the live subscription in four steps:

1. on the server, the Server Component reads and seals the query, and the Client Component renders the rows with the status `connecting`. Nothing subscribes on the server
2. in the browser, React hydrates the same rows from the props, so the markup matches with no loading flash
3. after hydration, `useLiveQuery()` opens the connection and subscribes with the sealed query
4. the first result replaces the initial rows in one step, and the status becomes `live`. Any change committed since the server read the rows is in that result

## Optimistic mutations

Apply each change to local, optimistic state at once, and send it to a server action. The action writes it in Postgres and returns the transaction ID, and the component holds the optimistic change until that ID comes back on the subscription. The mutations guide explains [how optimistic mutations work](../guides/mutations#how-optimistic-mutations-work) and covers [React's `useOptimistic` hook](../guides/mutations#with-reacts-useoptimistic-hook).

### Apply writes optimistically

Run each write in a transition with `startTransition`, apply it with `useOptimistic`, and keep the transition open until [`utils.awaitTxId()`](../sdks/typescript#react-uselivequeryutils) sees the write's txid. At the top level of `src/app/todo-list.tsx`, add `FormEvent`, `startTransition`, `useMemo` and `useOptimistic` to the `react` import and `leaveSession` to the `session-lost` import, then add:

```tsx filename="src/app/todo-list.tsx"
import { addTodo, deleteTodo, setTodoCompleted, type WriteResult } from "./actions"

type OptimisticTodo = TodoRow & { pending?: true }
type OptimisticAction =
  | { type: "add"; todo: TodoRow }
  | { type: "toggle"; id: string; completed: boolean }
  | { type: "delete"; id: string }
type Notice = { tone: "error" | "info"; text: string }

// React re-applies pending actions to every new live snapshot, including one that already contains the
// change. So each case must be safe to re-run, and must set absolute values.
function applyOptimisticAction(todos: readonly OptimisticTodo[], action: OptimisticAction): readonly OptimisticTodo[] {
  switch (action.type) {
    case "add":
      return todos.some((t) => t.id === action.todo.id) ? todos : [{ ...action.todo, pending: true }, ...todos]
    case "toggle":
      // Only dim rows the stream hasn't confirmed yet.
      return todos.map((t) =>
        t.id === action.id && t.completed !== action.completed ? { ...t, completed: action.completed, pending: true } : t
      )
    case "delete":
      return todos.filter((t) => t.id !== action.id)
  }
}

// The live rows already follow the query's ORDER BY. Sort here so optimistic rows land in the right place.
// The server render and hydration run the same sort, so the markup matches.
// Newest first, optimistic rows included (they carry the browser's created_at until the live row replaces them).
const newestFirst = (a: OptimisticTodo, b: OptimisticTodo) =>
  b.created_at.getTime() - a.created_at.getTime() || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0)

// How long a write stays pending while it waits for its transaction to arrive on the stream. Keep it short:
// React holds every transition started meanwhile (router.refresh(), navigations) until it settles.
const SYNC_TIMEOUT_MS = 10_000
```

Inside `TodoList`, after the `useLiveQuery()` call, layer the optimistic state over `data` and send every write through `mutate()`:

```tsx filename="src/app/todo-list.tsx"
  const [optimisticTodos, updateOptimistically] = useOptimistic<readonly OptimisticTodo[], OptimisticAction>(
    data ?? initialTodos,
    applyOptimisticAction
  )
  const todos = useMemo(() => [...optimisticTodos].sort(newestFirst), [optimisticTodos])
  const [notice, setNotice] = useState<Notice | null>(null)

  function mutate(action: OptimisticAction, write: () => Promise<WriteResult>, failure: string) {
    setNotice(null)
    startTransition(async () => {
      // The optimistic change lasts exactly as long as this transition.
      updateOptimistically(action)
      let result: WriteResult
      try {
        result = await write()
      } catch {
        // Network failure, a deploy that removed the action, or a server error. The change rolls back.
        setNotice({ tone: "error", text: failure })
        return
      }
      if (result.kind === "rejected") {
        if (result.reason === "UNAUTHENTICATED")
          leaveSession() // signed out or another user, like a renewal 401
        else setNotice({ tone: "error", text: failure })
        return
      }
      if (result.kind === "unchanged") return // nothing to wait for
      try {
        // Hold the transition until the stream has applied this transaction. The rows are published before
        // the wait resolves, so the live data already contains the write: no flicker and no duplicate.
        await utils.awaitTxId(result.txid, SYNC_TIMEOUT_MS)
      } catch {
        // Committed but not seen yet (the stream is reconnecting or has stopped, or the list unmounted).
        setNotice({ tone: "info", text: "Saved. It will appear when live updates reconnect." })
      }
    })
  }

  function addTodoFromForm(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const form = event.currentTarget
    const title = String(new FormData(form).get("title") ?? "").trim()
    if (!title) return
    // Reset now. <form action>'s automatic reset waits for the whole transition, which stays open until the
    // stream confirms the write, so it would erase whatever was typed in the meantime.
    form.reset()
    const todo: TodoRow = {
      id: crypto.randomUUID(),
      title,
      completed: false,
      created_at: new Date()
    }
    mutate({ type: "add", todo }, () => addTodo(userId, { id: todo.id, title }), `Couldn't add "${title}".`)
  }
```

Toggles and deletes call `mutate()` the same way, with `setTodoCompleted()` and `deleteTodo()`. Render `todos`, `status` and `notice`, with a form that calls `addTodoFromForm`. The [full component](https://github.com/neondatabase/examples/blob/main/realtime/with-nextjs/src/app/todo-list.tsx) is on GitHub.

The browser generates each new todo's `id`, so the optimistic row and the live row share a key, and the `add` case doesn't add a row that's already there. `SYNC_TIMEOUT_MS` is 10 seconds, as in the guides.

### Return the txid from a server action

On the server, each write is a server action that returns the transaction ID:

```ts filename="src/app/actions.ts"
"use server"

import { and, eq, sql } from "drizzle-orm"
import { z } from "zod"

import { getUser } from "../auth/server"
import { getDb } from "../lib/db"
import { todos } from "../lib/schema"

// Typed results rather than throws: in production Next.js hides a thrown error's message.
export type WriteResult =
  | { kind: "committed"; txid: string }
  | { kind: "unchanged" } // nothing matched: deleted elsewhere, someone else's id, or a replayed add
  | { kind: "rejected"; reason: "UNAUTHENTICATED" | "INVALID_INPUT" }

const addInput = z.object({ id: z.uuid(), title: z.string().trim().min(1).max(200) })
const setCompletedInput = z.object({ id: z.uuid(), completed: z.boolean() })
const deleteInput = z.object({ id: z.uuid() })

// Same statement, same transaction; works on any driver.
const txid = sql<string>`pg_current_xact_id()::text`
const toResult = (row?: { txid: string }): WriteResult =>
  row ? { kind: "committed", txid: row.txid } : { kind: "unchanged" }

export async function addTodo(pageUserId: string, raw: z.input<typeof addInput>): Promise<WriteResult> {
  const user = await getUser(pageUserId) // every action checks the session itself: proxy.ts skips actions
  if (!user) return { kind: "rejected", reason: "UNAUTHENTICATED" }
  const input = addInput.safeParse(raw)
  if (!input.success) return { kind: "rejected", reason: "INVALID_INPUT" }
  const [row] = await getDb()
    .insert(todos)
    .values({ id: input.data.id, user_id: user.id, title: input.data.title }) // user_id from the session only
    .onConflictDoNothing({ target: todos.id }) // replayed id: no write, nothing to wait for
    .returning({ txid })
  return toResult(row)
}

export async function setTodoCompleted(pageUserId: string, raw: z.input<typeof setCompletedInput>): Promise<WriteResult> {
  const user = await getUser(pageUserId)
  if (!user) return { kind: "rejected", reason: "UNAUTHENTICATED" }
  const input = setCompletedInput.safeParse(raw)
  if (!input.success) return { kind: "rejected", reason: "INVALID_INPUT" }
  const [row] = await getDb()
    .update(todos)
    .set({ completed: input.data.completed })
    .where(and(eq(todos.id, input.data.id), eq(todos.user_id, user.id))) // only the user's own row
    .returning({ txid })
  return toResult(row)
}

export async function deleteTodo(pageUserId: string, raw: z.input<typeof deleteInput>): Promise<WriteResult> {
  const user = await getUser(pageUserId)
  if (!user) return { kind: "rejected", reason: "UNAUTHENTICATED" }
  const input = deleteInput.safeParse(raw)
  if (!input.success) return { kind: "rejected", reason: "INVALID_INPUT" }
  const [row] = await getDb()
    .delete(todos)
    .where(and(eq(todos.id, input.data.id), eq(todos.user_id, user.id))) // only the user's own row
    .returning({ txid })
  return toResult(row)
}
```

`RETURNING pg_current_xact_id()::text` runs in the same statement as the write, so it returns the ID of the transaction that made the change, with no explicit transaction. It's cast to `text`, because `awaitTxId()` waits for a decimal string. See [returning the txid from your backend](../guides/mutations#returning-the-txid-from-your-backend).

Each action takes the user from the session. The page's user id is only compared with it, so a write from a page loaded for someone else gets `UNAUTHENTICATED`, and zod validates everything else the browser sends. The `user_id` in each `WHERE` means one user can't change another's rows. Next.js runs server actions one at a time, so writes reach the server in the order you make them, each with its own optimistic change.

Don't revalidate after a write. The live query already delivers it, and a revalidation only re-renders the page to read and seal the same query again.

## Next steps

- read the guides on [reactivity](../guides/reactivity), [optimistic mutations](../guides/mutations) and [server-side rendering](../guides/ssr) for the concepts behind each step
- look up `useLiveQuery()` and `RealtimeProvider` in the [React section of the SDK reference](../sdks/typescript#react)
- see how Realtime works with your own Drizzle schema, selects and writes in the [Drizzle example](./drizzle)
- see the [TanStack example](./tanstack), which seeds a TanStack DB collection in a route loader and writes through collection handlers
- browse the [full source on GitHub](https://github.com/neondatabase/examples/tree/main/realtime/with-nextjs)

--- [Document source](https://neon.com/docs/realtime/examples/overview.md) ---

> Summary: Examples of building realtime, reactive apps and agents with Neon Realtime: walkthroughs for Next.js, TanStack, Mastra, Drizzle and Kysely, plus demo apps that combine Realtime with the rest of the Neon platform.

# Realtime examples

Code examples and demo apps for building with Realtime.

Last updated: 2026-10-15

The [code examples](https://neon.com/docs/realtime/examples/overview#code-examples) teach you how to use Realtime with a specific framework or library. The [demo apps](https://neon.com/docs/realtime/examples/overview#demo-apps) show what you can build with Realtime and the wider Neon platform.

## Code examples

Build full-stack, reactive apps with your framework, or drive live agent workflows from your database:

- [Next.js](https://neon.com/docs/realtime/examples/nextjs): Build a realtime, reactive app using Next.js with SSR support.
- [TanStack](https://neon.com/docs/realtime/examples/tanstack): Build a realtime, reactive app using TanStack Start and DB.
- [Mastra](https://neon.com/docs/realtime/examples/mastra): Drive agent workflows directly from Lakebase Postgres.

Use Realtime with your existing ORM or query builder schema, queries and writes:

- [Drizzle](https://neon.com/docs/realtime/examples/drizzle): Seal Drizzle queries and keep live rows typed.
- [Kysely](https://neon.com/docs/realtime/examples/kysely): Seal Kysely queries and keep live rows typed.

## Demo apps

These apps use Realtime alongside other parts of the Neon platform, such as Auth, Functions, Object Storage and the AI Gateway. Try the live demos, or read the source on GitHub.

- **1 Million Boxes**: The world's largest game of dots and boxes. Players join a team and draw lines to claim boxes, with every move synced to everyone playing. Uses Postgres, Realtime, Vercel. [Live demo](https://one-million-boxes.vercel.app) · [GitHub](https://github.com/samwillis/one-million-boxes)
- **Hacker News Realtime**: A live Hacker News viewer. It ingests the Hacker News feed into Postgres, so you can watch scores, comment counts and rankings change as they happen. Uses Postgres, Realtime, Functions, Vercel. [Live demo](https://hackernews-realtime.vercel.app) · [GitHub](https://github.com/samwillis/hackernews-realtime)
- **Neonbricks**: A collaborative brick-building app. Share a workspace and build a model together, or ask the AI to build one for you. The model and the AI chat both live in Postgres. Uses Postgres, Realtime, Functions, AI Gateway, Vercel. [Live demo](https://neonbricks-app.vercel.app) · [GitHub](https://github.com/samwillis/neonbricks)
- **Carriage**: A collaborative markdown editor built on Yjs. Edits are saved to Postgres and synced to everyone viewing the doc. Agents can read and edit docs through an MCP server, and show up as present alongside people. Uses Postgres, Realtime, Auth, Functions, Vercel. [Live demo](https://carriage-neon.vercel.app) · [GitHub](https://github.com/samwillis/carriage)

## Other examples

Other community maintained examples:

- [Livebase](https://github.com/thruflo/livebase) agentic CRM app using Realtime with Mastra
- [Realtime image jobs](https://github.com/msfstef/neon-realtime-image-jobs) upload an image and watch it move through AI processing

--- [Document source](https://neon.com/docs/realtime/examples/tanstack.md) ---

> Summary: Build a per-user todo app with TanStack Start, TanStack DB, Drizzle and Managed Better Auth on Neon Realtime: seal live queries in server functions, seed a Realtime collection in a route loader, and settle optimistic writes by txid.

# TanStack example

Full-stack example app using Realtime with TanStack.

Last updated: 2026-10-15

This example shows how to use Neon Realtime with [TanStack Start](https://tanstack.com/start), [TanStack DB](https://tanstack.com/db), Drizzle and Neon's [Managed Better Auth](https://neon.com/docs/auth/overview), with support for [auth](https://neon.com/docs/realtime/examples/tanstack#authorize-with-the-session), [SSR](https://neon.com/docs/realtime/examples/tanstack#server-side-rendering), [client-side reactivity](https://neon.com/docs/realtime/examples/tanstack#client-side-reactivity) and [optimistic mutations](https://neon.com/docs/realtime/examples/tanstack#optimistic-mutations).

The sections follow the same order as the guides, from [defining](https://neon.com/docs/realtime/examples/tanstack#defining-queries) and [sealing](https://neon.com/docs/realtime/examples/tanstack#sealing-queries) queries to writing to them, and show the TanStack code for each step.

**Tip: Full example on GitHub**

The complete app is in the [`realtime/with-tanstack`](https://github.com/neondatabase/examples/tree/main/realtime/with-tanstack) folder of the `neondatabase/examples` repository.

## Setup

Install the Realtime SDK with its Drizzle and TanStack DB bindings, plus TanStack DB's React package and its router integration:

```bash filename="Terminal"
npm install @neon/realtime @neon/realtime-drizzle @neon/realtime-tanstack
npm install @tanstack/react-db @tanstack/react-router-with-db
```

Add a `neon.ts` that enables Managed Better Auth and Realtime on your branch:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1"

export default defineConfig({
  // Managed Better Auth signs users in. Each user's todos are scoped by their user id.
  auth: true,
  preview: {
    realtime: {
      allowedOrigins: ["http://localhost:3000"]
    }
  }
})
```

`allowedOrigins` lists the browser origins that can connect to Realtime, so add your app's origin when you deploy it. The [`neon.ts` reference](https://neon.com/docs/reference/neon-ts) covers the options.

Link the directory and run `neon deploy`, as in the [queries guide's setup](../guides/queries#setup). It writes `DATABASE_URL`, `NEON_REALTIME_URL`, `NEON_REALTIME_SECRET` and `NEON_AUTH_BASE_URL` to `.env.local`. If Realtime isn't ready before the deploy stops waiting, run `neon env pull` once it is.

Two more variables come from you. The browser needs the Realtime URL, and Vite only exposes variables that start with `VITE_`. The Managed Better Auth server SDK needs a cookie secret of at least 32 characters:

```bash filename="Terminal"
echo 'VITE_NEON_REALTIME_URL=$NEON_REALTIME_URL' >> .env.local
printf '\nNEON_AUTH_COOKIE_SECRET=%s\n' "$(openssl rand -base64 32)" >> .env.local
```

Vite expands `$NEON_REALTIME_URL` when it loads the file, so the browser URL follows the server variable after each `neon env pull`. It also inlines the value into the server build, so server rendering and the browser create the client with the same URL. `NEON_REALTIME_SECRET` never gets a `VITE_` prefix. The browser only ever sees the URL and sealed queries.

## Defining queries

Define each live query once, in server code. You run it to render the page on the server and seal it for the browser to subscribe to, so both get the same rows.

### Define the schema

Define your database schema. In this example, we're using Drizzle and defining a single table:

```ts filename="src/schema.ts"
import { boolean, index, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core"

export const todos = pgTable(
  "realtime_todos",
  {
    // Generated in the browser, so an optimistic insert already has its key.
    id: uuid("id").primaryKey(),
    // The Managed Better Auth user id. Set on the server only; never sent to the browser.
    userId: text("user_id").notNull(),
    title: text("title").notNull(),
    completed: boolean("completed").notNull().default(false),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
  },
  (t) => [index("realtime_todos_user_id_idx").on(t.userId)]
)
```

### Define the live query

We then [define a query](../guides/queries). `db` is a Drizzle client over a node-postgres pool, in `src/db.server.ts`:

```ts filename="src/todos.server.ts"
import { eq, sql } from "drizzle-orm"

import { db } from "./db.server"
import { todos } from "./schema"

// One query for both the SSR rows and the sealed live query, so they match.
// Realtime matches each result column to its key by name, so `createdAt` gets
// an SQL alias (the column is `created_at`). `mapWith` keeps it a `Date`.
export const selectTodos = (userId: string) =>
  db
    .select({
      id: todos.id,
      title: todos.title,
      completed: todos.completed,
      createdAt: sql<Date>`${todos.createdAt}`.mapWith(todos.createdAt).as("createdAt")
    })
    .from(todos)
    .where(eq(todos.userId, userId))

// The row shape the browser sees, inferred from the query.
export type Todo = Awaited<ReturnType<typeof selectTodos>>[number]
```

The query has no `ORDER BY`, because the collection stores rows by key and doesn't keep their order. The page sorts them when it [queries the collection](https://neon.com/docs/realtime/examples/tanstack#render-the-collection). `userId` always comes from the server session, never from the browser. This `WHERE` is what keeps each user's todos separate.

## Sealing queries

Seal the query on the server, for the user in the session. The browser can subscribe to a sealed query, but it can't read or change it, as the queries guide explains in [sealing queries](../guides/queries#sealing-queries).

### Create the Realtime server

The Realtime server, from [`createRealtime()`](../sdks/typescript#backend-createrealtime), holds the secret and seals queries. It should be created and then used in your trusted server code:

```ts filename="src/realtime.server.ts"
import { createRealtime } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

import { env, postgresDatabaseName } from "./env.server"

export const realtime = createRealtime({
  secret: env.realtime.secret,
  db: postgresDatabaseName,
  adapter: drizzleAdapter()
})
```

The `.server.ts` suffix keeps the file out of the browser bundle, as [the SSR guide explains](../guides/ssr#keep-secrets-on-the-server).

### Authorize with the session

TanStack Start mounts [Managed Better Auth](https://neon.com/docs/auth/overview) on your app's own origin, so server code reads the session from its cookie and the browser holds no token. Check the session in middleware, on the server, before you read, seal or write anything:

```ts filename="src/auth/auth.functions.ts"
import { createMiddleware } from "@tanstack/react-start"
import { setResponseStatus } from "@tanstack/react-start/server"
import { z } from "zod"

// The data boundary: every todo server function uses this, whatever the
// route guards do. The page sends the user id it was loaded for, so a session
// for another user (signed in from another tab) counts as signed out. The
// schema is loose, so the function's own fields reach its validator.
export const requireUser = createMiddleware({ type: "function" })
  .middleware([sessionMiddleware])
  .validator(z.looseObject({ userId: z.string() }))
  .server(({ next, context, data }) => {
    if (context.user?.id !== data.userId) {
      setResponseStatus(401)
      throw new Error("UNAUTHENTICATED")
    }
    return next({ context: { user: context.user } })
  })
```

Every server function that reads, seals or writes todos uses `requireUser`. Signed out or signed in as someone else, it responds with a 401 and throws `UNAUTHENTICATED`, which the collection [handles in the browser](https://neon.com/docs/realtime/examples/tanstack#define-the-collection). `sessionMiddleware`, in the same file, reads the session from the request's cookies, and `getSessionUser` gives the [route guards](https://neon.com/docs/realtime/examples/tanstack#keep-signed-in-pages-private) the user or `null`.

The rest of `src/auth/` is Managed Better Auth setup: the server, the `/api/auth` proxy, the browser client and the prebuilt sign-in UI, as in the [Managed Better Auth TanStack Router quick start](https://neon.com/docs/auth/quick-start/tanstack-router). `auth.server.ts` stands in for the Managed Better Auth adapter for TanStack Start, which isn't out yet. The SSR guide [builds the same server](../guides/ssr#send-both-to-the-browser) in `src/backend/auth.ts`.

### Seal in a server function

Expose the sealed query from a server function, as in [using server functions](../guides/queries#using-server-functions). `refreshTodosQuery` requires a signed-in user and seals `selectTodos()` for them. The browser calls it to [renew the sealed query](../guides/queries#renewing-sealed-queries) before it expires, so it has to seal exactly the same query:

```ts filename="src/todos.functions.ts"
import { createServerFn } from "@tanstack/react-start"

import { requireUser } from "./auth/auth.functions"
import { realtime } from "./realtime.server"
import { selectTodos } from "./todos.server"

// Every function requires a signed-in user and only touches that user's rows.
// Anything that returns rows or a sealed query is POST, so it's never cached.

// Re-seals the live query before it expires.
export const refreshTodosQuery = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .handler(({ context }) => realtime.seal({ query: selectTodos(context.user.id) }))
```

## Server-side rendering

TanStack Start renders the first request on the server. To put the user's rows in that HTML and keep them live in the browser:

1. read and seal the query in one server function
2. call it from a route loader, and seed a TanStack DB collection with the rows
3. let `routerWithDbClient()` carry the collection to the browser in the HTML

The SSR guide covers the pattern in [with TanStack DB](../guides/ssr#with-tanstack-db).

### Read and seal in one server function

Run the query and seal it in the same server function, so the rows and the sealed query match. This is [return the sealed query and initial results](../guides/ssr#return-the-sealed-query-and-initial-results) as a TanStack Start server function. Add it to `src/todos.functions.ts`, which already imports everything it uses:

```ts filename="src/todos.functions.ts"
// The page's rows, plus a sealed live query for exactly the same rows.
export const loadTodos = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .handler(async ({ context }) => {
    const [rows, query] = await Promise.all([
      selectTodos(context.user.id),
      realtime.seal({ query: selectTodos(context.user.id) })
    ])
    return { rows, query }
  })
```

[`realtime.seal()`](../sdks/typescript#backend-realtimeserverseal) returns a typed [`SealedLiveQuery<Todo>`](../sdks/typescript#backend-sealedlivequery), so the row type flows through to the collection and the page.

### Keep signed-in pages private

A server-rendered page carries the user's rows and a sealed query, which is a [bearer token](../guides/queries#sealing-queries). So load the session in the root route, and stop shared caches from storing the page:

```tsx filename="src/routes/__root.tsx"
import { createRootRouteWithContext } from "@tanstack/react-router"

import { getSessionUser } from "../auth/auth.functions"
import type { RouterContext } from "../router"

export const Route = createRootRouteWithContext<RouterContext>()({
  // Runs on every navigation, so the signed-in user is always current. During
  // SSR it runs in-process with the request's cookies.
  beforeLoad: async () => ({ user: await getSessionUser() }),
  // Pages carry the user's rows, so no shared cache may store them.
  headers: () => ({ "Cache-Control": "private, no-store", Vary: "Cookie" })
})
```

Then put the signed-in pages under a layout route that sends signed-out visitors to sign-in:

```tsx filename="src/routes/_authed.tsx"
import { createFileRoute, redirect } from "@tanstack/react-router"

// Signed-in pages. UX only: every server function checks `requireUser` too.
export const Route = createFileRoute("/_authed")({
  beforeLoad: ({ context }) => {
    if (!context.user) {
      throw redirect({
        to: "/auth/$path",
        params: { path: "sign-in" },
        // An SSR redirect skips the root route's `headers`.
        headers: { "Cache-Control": "private, no-store", Vary: "Cookie" }
      })
    }
    return { user: context.user }
  }
})
```

`beforeLoad` returns the signed-in `user`, so the routes below it get a user that's never `null`.

### Create a `DbClient` per router

A TanStack DB `DbClient` holds the collections, so on the server it has to belong to one request. Create it in `getRouter()`, which TanStack Start calls once per server request and once per page load in the browser. Create the Realtime client next to it and pass it to the `DbClient` as a dependency, so collections can read it:

```tsx filename="src/router.tsx"
import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"
import { DbClient } from "@tanstack/react-db"
import { createRouter } from "@tanstack/react-router"
import { routerWithDbClient } from "@tanstack/react-router-with-db"

import { routeTree } from "./routeTree.gen"

export interface RouterContext {
  readonly dbClient: DbClient;
}

// Runs once per SSR request and once per page load in the browser.
export function getRouter() {
  // Vite inlines this into the server build too, so SSR and the browser agree.
  const url = import.meta.env.VITE_NEON_REALTIME_URL
  if (!url) {
    throw new Error("VITE_NEON_REALTIME_URL is not set. See the README setup.")
  }
  // Collections read this with `db.requireDependency("realtime")`. On the
  // server it never connects: sync only starts in the browser.
  const realtime = createRealtimeClient({
    url,
    // Decode `date` and zone-less `timestamp` columns as Drizzle does.
    // This app has neither, but most Drizzle apps do
    parsers: { ...drizzleParsers }
  })
  const dbClient = new DbClient({ realtime })
  const router = createRouter({
    routeTree,
    context: { dbClient },
    scrollRestoration: true
  })
  // Snapshots the collections loaders filled on the server, and restores them
  // in the browser before the first render.
  return routerWithDbClient(router, dbClient)
}
```

- no collection is shared between users, because each request and each page load gets its own `DbClient`, as in [create a `DbClient` per router](../guides/ssr#create-a-dbclient-per-router). Sign-in and sign-out are full page loads, which drop the browser's `DbClient` and the previous user's rows with it. See [when the session changes](../guides/ssr#when-the-session-changes)
- [`drizzleParsers`](../sdks/typescript#drizzle-client-drizzleparsers) parses live values the way Drizzle does, so live rows have the same types as the rows the server rendered. See [keep row shapes identical](../guides/ssr#keep-row-shapes-identical)
- `routerWithDbClient()` wraps the app in TanStack DB's provider, so components get this `DbClient` from `useDbClient()`. It also snapshots the collections that loaders seeded on the server into the HTML, and restores them in the browser before the first render
- `RouterContext` puts `dbClient` on route context, where the route loader reads it

### Seed the collection in a loader

In the route loader, call the server function and seed the user's collection with its rows. Loaders also run in the browser on client-side navigation, so they call a server function rather than importing server modules:

```tsx filename="src/routes/_authed/index.tsx"
import { createFileRoute } from "@tanstack/react-router"

import { todosCollection } from "../../todos.collection"
import { loadTodos } from "../../todos.functions"

export const Route = createFileRoute("/_authed/")({
  // Don't refetch on a navigation back here while the collection is live.
  // No visible effect until the app has a second page.
  staleTime: Infinity,
  // Fills the router's DbClient. On the server, routerWithDbClient snapshots
  // these rows into the HTML and restores them in the browser before render.
  loader: async ({ context }) => {
    const { rows, query } = await loadTodos({ data: { userId: context.user.id } })
    // A no-op if this user's collection already exists.
    context.dbClient.collection(todosCollection(context.user.id, query), { initialData: rows })
    return { query }
  },
  component: TodosPage
})
```

- `todosCollection()` returns the collection's descriptor, which you [define](https://neon.com/docs/realtime/examples/tanstack#define-the-collection) for client-side reactivity
- `context.dbClient.collection(descriptor, { initialData: rows })` creates the collection with the rows, without starting sync. If the collection already exists, the call reuses it and ignores `initialData`, so the live rows stay
- the loader returns only `{ query }`. The rows travel to the browser in the collection

## Client-side reactivity

In the browser, a TanStack DB collection syncs the live query's rows, and components query the collection locally. The reactivity guide explains [why a collection](../guides/reactivity#tanstack-db) suits live data.

### Define the collection

Define the collection as a descriptor, with the two-argument `collectionOptions(id, factory)` around [`realtimeCollectionOptions()`](../sdks/typescript#tanstack-db-realtimecollectionoptions). The descriptor is cheap to build, so the loader and the page both build it, and the shared `id` resolves both to the collection the loader seeded. The factory runs once per `DbClient`, and reads that `DbClient`'s Realtime client:

```ts filename="src/todos.collection.ts"
import type { RealtimeClient, SealedLiveQuery } from "@neon/realtime/client"
import { realtimeCollectionOptions } from "@neon/realtime-tanstack"
import { collectionOptions } from "@tanstack/react-db"

import { leaveIfSignedOut } from "./auth/session-lost"
import { refreshTodosQuery } from "./todos.functions"
import type { Todo } from "./todos.server"

// A cheap descriptor, built by the loader and the page alike. The factory runs
// once per DbClient, with the Realtime client `getRouter` gave that DbClient.
export function todosCollection(userId: string, query: SealedLiveQuery<Todo>) {
  const id = `todos:${userId}`
  return collectionOptions(id, (db) =>
    realtimeCollectionOptions({
      id,
      query,
      client: db.requireDependency<RealtimeClient>("realtime"),
      getKey: (todo) => todo.id,
      // Never garbage-collect while the page is open. A collection rebuilt
      // later would start empty, from this long-expired sealed query, and stay
      // `stale` until a refresh replaced it.
      gcTime: 0,
      refreshQuery: () => refreshTodosQuery({ data: { userId } }).catch(leaveIfSignedOut)
    })
  )
}
```

- `realtimeCollectionOptions()` takes the sealed `query`, the Realtime `client` and `getKey`, and syncs the collection from the subscription. Other TanStack DB options, like `gcTime`, pass through. The [config reference](../sdks/typescript#tanstack-db-realtimecollectionconfig) lists them all
- `refreshQuery` returns a fresh sealed query for the same query. The collection calls it before the current one expires and renews the subscription in place, keeping its rows. See [`refreshQuery`](../guides/reactivity#refreshquery)
- `gcTime: 0` turns off garbage collection in TanStack DB, which differs from TanStack Query, where `0` collects at once

If the session is gone or belongs to another user, the server function fails with `UNAUTHENTICATED`, and `leaveIfSignedOut`, from `src/auth/session-lost.ts`, does a full page load of `/`. The SSR guide explains [when the session changes](../guides/ssr#when-the-session-changes).

### Render the collection

Query the collection with TanStack DB's `useLiveQuery()`, and render its rows straight away, without waiting for `isReady`. The seeded rows are there for the first render, on the server and in the browser. Add the page component to `src/routes/_authed/index.tsx`, with one more import:

```tsx filename="src/routes/_authed/index.tsx"
import { useLiveQuery } from "@tanstack/react-db"

function TodosPage() {
  const { query } = Route.useLoaderData()
  const { user } = Route.useRouteContext()
  // Same id as the loader's, so this resolves to the collection it filled.
  const descriptor = todosCollection(user.id, query)
  // `isReady` turns true when Realtime sends its first complete result, and
  // stays true while it reconnects or renews the query. The SSR rows are on
  // screen before that.
  const { data: todos, isReady } = useLiveQuery({
    query: (q) =>
      q
        .from({ todo: descriptor })
        .orderBy(({ todo }) => todo.createdAt, "desc")
        .orderBy(({ todo }) => todo.id, "desc")
  })

  return (
    <main>
      <output>{isReady ? "live" : "connecting"}</output>

      <ul aria-live="polite">
        {todos.map((todo) => (
          <li key={todo.id}>
            <span>{todo.title}</span>
          </li>
        ))}
      </ul>
    </main>
  )
}
```

On the first request, the rows go from the server's query to the live subscription in four steps:

1. on the server, the loader seeds the collection and `useLiveQuery()` reads it, so the HTML has the user's rows. Nothing subscribes on the server
2. `routerWithDbClient()` snapshots the collection into the HTML. In the browser, it restores the rows before the first render, so hydration matches the server's markup with no loading flash
3. after hydration, `useLiveQuery()` starts the collection's sync, which subscribes with the sealed query from the loader
4. the first result replaces the seeded rows in one step, and `isReady` turns true. Any change committed since the server read the rows is in that result

`useLiveQuery()` sorts the rows in the browser, newest first, because the live query has no `ORDER BY`. See [query the collection](../guides/reactivity#query-the-collection) for more local queries.

## Optimistic mutations

Write to the collection, and TanStack DB applies each change at once and calls your mutation handler. The handler sends the change to a server function, which writes it in one SQL statement and returns the transaction ID from that same statement. The handler then waits for that ID to come back on the subscription, so the optimistic row hands over to the synced one in one step. The mutations guide explains [how optimistic mutations work](../guides/mutations#how-optimistic-mutations-work).

### Write to the collection

Call `insert()`, `update()` and `delete()` on the collection. Each applies at once and returns a TanStack DB transaction, which rejects if the write rolls back. Here's the page component with writes. It replaces the component, and the `@tanstack/react-db` and `../../todos.collection` imports, from [render the collection](https://neon.com/docs/realtime/examples/tanstack#render-the-collection):

```tsx filename="src/routes/_authed/index.tsx"
import { useDbClient, useLiveQuery, type Transaction } from "@tanstack/react-db"
import { useState, type FormEvent } from "react"

import { NotSyncedYetError, todosCollection } from "../../todos.collection"

type Notice = { tone: "error" | "info"; text: string }

function TodosPage() {
  const { query } = Route.useLoaderData()
  const { user } = Route.useRouteContext()
  // Same id as the loader's, so this resolves to the collection it filled.
  const descriptor = todosCollection(user.id, query)
  const collection = useDbClient().collection(descriptor)
  // `isReady` turns true when Realtime sends its first complete result, and
  // stays true while it reconnects or renews the query. The SSR rows are on
  // screen before that.
  const { data: todos, isReady } = useLiveQuery({
    query: (q) =>
      q
        .from({ todo: descriptor })
        .orderBy(({ todo }) => todo.createdAt, "desc")
        .orderBy(({ todo }) => todo.id, "desc")
  })
  const [notice, setNotice] = useState<Notice | null>(null)

  // Changes apply optimistically. If one fails, TanStack DB rolls it back and
  // the reason shows here.
  function track(tx: Transaction) {
    setNotice(null)
    tx.when("settled").catch((cause: unknown) =>
      setNotice(
        cause instanceof NotSyncedYetError
          ? { tone: "info", text: "Saved. It will appear when live updates reconnect." }
          : { tone: "error", text: `Couldn't save that change: ${cause instanceof Error ? cause.message : String(cause)}` }
      )
    )
  }

  function addTodo(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    const form = event.currentTarget
    const title = String(new FormData(form).get("title") ?? "").trim()
    if (!title) return
    form.reset()
    track(
      collection.insert({
        id: crypto.randomUUID(),
        title,
        completed: false,
        createdAt: new Date()
      })
    )
  }

  return (
    <main>
      <output>{isReady ? "live" : "connecting"}</output>

      <form onSubmit={addTodo}>
        <input aria-label="Todo title" maxLength={200} name="title" placeholder="What needs doing?" required />
        <button type="submit">Add item</button>
      </form>

      {notice ? <p role={notice.tone === "error" ? "alert" : "status"}>{notice.text}</p> : null}

      <ul aria-live="polite">
        {todos.map((todo) => (
          <li key={todo.id}>
            <label>
              <input
                aria-label={`Mark ${todo.title} as ${todo.completed ? "incomplete" : "complete"}`}
                checked={todo.completed}
                disabled={todo.$hasPendingWrites}
                onChange={() =>
                  track(
                    collection.update(todo.id, (draft) => {
                      draft.completed = !draft.completed
                    })
                  )
                }
                type="checkbox"
              />
              <span>{todo.title}</span>
            </label>
            <button
              aria-label={`Delete ${todo.title}`}
              disabled={todo.$hasPendingWrites}
              onClick={() => track(collection.delete(todo.id))}
              type="button"
            >
              Delete
            </button>
          </li>
        ))}
      </ul>
    </main>
  )
}
```

- `useDbClient().collection(descriptor)` returns the collection the loader seeded, to write to
- the insert sets `id` and a provisional `createdAt` in the browser, so the new row has its final key and sorts to the top straight away. The synced row brings the server's timestamp
- `track` waits for each transaction's `when("settled")` promise, and shows a notice if the change rolls back. A [`NotSyncedYetError`](https://neon.com/docs/realtime/examples/tanstack#send-writes-to-the-server) means the write committed but its change didn't come back in time, so the notice says it's saved
- `$hasPendingWrites` is `true` while a row has a pending optimistic change, which disables its checkbox and Delete button, so you don't start a new change on a todo whose last change isn't confirmed yet. TanStack DB runs handlers concurrently, so a toggle or delete sent straight after an insert could reach the database before the insert commits, match no rows and be lost

### Send writes to the server

Add `onInsert`, `onUpdate` and `onDelete` handlers to `realtimeCollectionOptions()` in `src/todos.collection.ts`, after `refreshQuery`. TanStack DB calls each one once per transaction, with all of its mutations, so each handler sends one batch to its server function. If the write changed rows, the handler waits for its transaction ID:

```ts filename="src/todos.collection.ts"
refreshQuery: () => refreshTodosQuery({ data: { userId } }).catch(leaveIfSignedOut),
// One server call per transaction, with all of its mutations. Each also
// sends `userId`, so the server refuses writes from a page loaded for
// another user.
onInsert: async ({ transaction, collection }) => {
  const { txid } = await createTodos({
    data: {
      userId,
      batch: transaction.mutations.map(({ modified: { id, title, completed } }) => ({ id, title, completed }))
    }
  }).catch(leaveIfSignedOut)
  if (txid) await collection.utils.awaitTxId(txid, ECHO_TIMEOUT_MS).catch(notSyncedYet)
},
onUpdate: async ({ transaction, collection }) => {
  const { txid } = await updateTodos({
    data: {
      userId,
      // The server keeps only `title` and `completed` from `changes`.
      batch: transaction.mutations.map(({ key, changes }) => ({ id: key, changes }))
    }
  }).catch(leaveIfSignedOut)
  if (txid) await collection.utils.awaitTxId(txid, ECHO_TIMEOUT_MS).catch(notSyncedYet)
},
onDelete: async ({ transaction, collection }) => {
  const { txid } = await deleteTodos({
    data: { userId, batch: transaction.mutations.map(({ key }) => key) }
  }).catch(leaveIfSignedOut)
  if (txid) await collection.utils.awaitTxId(txid, ECHO_TIMEOUT_MS).catch(notSyncedYet)
}
```

Then add what the handlers use at the top level of the file, and import the three write server functions next to `refreshTodosQuery`:

```ts filename="src/todos.collection.ts"
import { createTodos, deleteTodos, refreshTodosQuery, updateTodos } from "./todos.functions"

// How long a write waits for its own change to come back over Realtime. Keep it
// short: while a handler waits, TanStack DB holds back the collection's synced
// changes, including other tabs' writes.
const ECHO_TIMEOUT_MS = 10_000

// The write committed, but its change didn't come back over Realtime in time,
// for example while live updates reconnect. TanStack DB still rolls the change
// back, and it shows again once Realtime catches up.
export class NotSyncedYetError extends Error {}

function notSyncedYet(cause: unknown): never {
  throw new NotSyncedYetError("Saved, but not synced yet", { cause })
}
```

- [`collection.utils.awaitTxId(txid, timeout)`](../sdks/typescript#tanstack-db-realtimecollectionutilsawaittxid) waits until the subscription has delivered that transaction's changes. While a handler runs, TanStack DB holds back synced changes, so the optimistic row hands over to the synced one in one step
- TanStack DB rolls the change back if the server function throws, the wait times out, or the subscription errors or closes. The mutations guide covers [handlers with TanStack DB collections](../guides/mutations#with-tanstack-db-collections)
- `awaitTxId()` keeps waiting while the subscription reconnects or waits for a renewed sealed query, and the collection holds back synced changes while it waits. Keep the timeout short: `ECHO_TIMEOUT_MS` is 10 seconds, as in the guides
- once a handler has a txid, the write has committed, so `notSyncedYet` turns any failed wait into a `NotSyncedYetError`. The change still rolls back, but the page says it's saved rather than showing an error, and the change shows again when Realtime catches up

### Return the txid from the server

Add one server function per mutation type to `src/todos.functions.ts`, with the imports they add. Each function writes its whole batch in one SQL statement, and the statement's `RETURNING` clause includes `pg_current_xact_id()`, so it returns the transaction ID without another database round trip:

```ts filename="src/todos.functions.ts"
import { and, eq, inArray, sql } from "drizzle-orm"

import { db } from "./db.server"
import { todos } from "./schema"
import { newTodosInput, todoIdsInput, todoUpdatesInput } from "./todos.schemas"

type WriteResult = { readonly txid: string | null }

const txid = sql<string>`pg_current_xact_id()::text`

const writeResult = (row?: { txid: string }): WriteResult => ({
  txid: row?.txid ?? null
})

// Each write sends a whole TanStack DB batch in one SQL statement and returns
// its Postgres transaction id, or `null` if no row changed (for example, an id
// that's already gone).
export const createTodos = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator(newTodosInput)
  .handler(async ({ data: { batch }, context }) => {
    const [created] = await db
      .insert(todos)
      .values(batch.map((todo) => ({ ...todo, userId: context.user.id })))
      .returning({ txid })
    return writeResult(created)
  })

export const updateTodos = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator(todoUpdatesInput)
  .handler(async ({ data: { batch }, context }) => {
    const changed = batch.filter(({ changes }) =>
      Object.values(changes).some((value) => value !== undefined)
    )
    if (changed.length === 0) return writeResult()

    const titleCases = changed.flatMap(({ id, changes }) =>
      changes.title === undefined ? [] : [sql`WHEN ${todos.id} = ${id} THEN ${changes.title}`]
    )
    const completedCases = changed.flatMap(({ id, changes }) =>
      changes.completed === undefined ? [] : [sql`WHEN ${todos.id} = ${id} THEN ${changes.completed}`]
    )

    const [updated] = await db
      .update(todos)
      .set({
        ...(titleCases.length > 0
          ? { title: sql<string>`CASE ${sql.join(titleCases, sql.raw(" "))} ELSE ${todos.title} END` }
          : {}),
        ...(completedCases.length > 0
          ? { completed: sql<boolean>`CASE ${sql.join(completedCases, sql.raw(" "))} ELSE ${todos.completed} END` }
          : {})
      })
      .where(
        and(
          inArray(
            todos.id,
            changed.map(({ id }) => id)
          ),
          eq(todos.userId, context.user.id)
        )
      )
      .returning({ txid })
    return writeResult(updated)
  })

export const deleteTodos = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator(todoIdsInput)
  .handler(async ({ data: { batch }, context }) => {
    const [deleted] = await db
      .delete(todos)
      .where(and(inArray(todos.id, batch), eq(todos.userId, context.user.id)))
      .returning({ txid })
    return writeResult(deleted)
  })
```

- each call writes one TanStack DB transaction's batch in one SQL statement, so there's one txid to wait for. A single statement is its own Postgres transaction, so `pg_current_xact_id()` returns the ID of the transaction that made the change. See [returning the txid from your backend](../guides/mutations#returning-the-txid-from-your-backend)
- the query casts `txid` to `text`, because the collection waits for a decimal string. Every row a statement returns carries the same txid, so `writeResult` reads the first one. If no row changed, there's nothing to wait for and nothing to roll back, so it returns `{ txid: null }`
- `updateTodos` sets each column with a `CASE` on the row's `id`, so a batch of different changes is still one `UPDATE`. It leaves out a column no change touches, and skips the query when nothing changed, because Drizzle rejects an empty `set`
- the server functions take the user from the session, never from the browser. `requireUser` only compares the browser's `userId` with the session's, and the zod input schemas in `src/todos.schemas.ts` strip unknown keys, so a row's `userId` can't come from the browser
- `updateTodos` and `deleteTodos` scope their `WHERE` to the session's user, so one user can't change another's rows

## Next steps

- read the guides on [reactivity](../guides/reactivity), [optimistic mutations](../guides/mutations) and [server-side rendering](../guides/ssr) for the concepts behind each step
- look up every `realtimeCollectionOptions()` option in the [TanStack DB section of the SDK reference](../sdks/typescript#tanstack-db)
- see the [Next.js example](./nextjs), which reads and seals in a Server Component and subscribes in a Client Component
- browse the [full source on GitHub](https://github.com/neondatabase/examples/tree/main/realtime/with-tanstack)

--- [Document source](https://neon.com/docs/realtime/guides/mutations.md) ---

> Summary: Write through your own backend, return the transaction id, apply the change optimistically and drop the optimistic state once the change arrives on the live query. Without a framework, with React useOptimistic or with TanStack DB.

# Optimistic mutations

Make apps and agents super fast, with instant local writes.

Last updated: 2026-11-05

Apply instant local writes using [optimistic mutations](https://neon.com/docs/realtime/guides/mutations#how-optimistic-mutations-work) that [automatically discard their optimistic state](https://neon.com/docs/realtime/guides/mutations#automatic-management-of-optimistic-state) when the changes [sync in through your live query subscriptions](./subscribing#listen-for-changes).

## How optimistic mutations work

Normally, with online systems, you first send writes to the server and then display them to the user once the server has written to the database and responded successfully. Depending on network connectivity and system uptime, this can be slow or broken.

With optimistic mutations, you first display the write to the user and only then send to the server in the background. This makes apps feel super-fast and responsive, as well as resilient to connectivity or downtime issues.

### Automatic management of optimistic state

Realtime allows you to automate the management and lifecycle of your optimistic state, by monitoring the transactions coming through your live query subscriptions. For each write:

1. apply the change to local, optimistic state, so the UI updates straight away
2. send the write through your backend, with your normal validation, authorization and backend logic, which returns the [ID of the transaction](https://www.postgresql.org/docs/current/transaction-id.html) that made it
3. wait until the subscription has synced that transaction, using [`awaitTxId()`](../sdks/typescript#client-materializedlivequerysubscriptionawaittxid)
4. drop the optimistic state
5. if the write fails, or the transaction doesn't sync before the timeout, drop the optimistic state and show an error

`awaitTxId()` remembers recently seen transaction IDs, so it resolves even when the change arrives before your backend's HTTP response. It also resolves after the subscription's `onChange`, so the synced rows already include the change when the optimistic state drops, which means nothing flickers.

## Running example

Let's return to our running example, flesh out the backend server, call its new routes from the frontend and add some shared frontend helpers.

### Returning the `txid` from your backend

Each write route takes a batch of changes and writes the whole batch in one SQL statement, which returns the ID of its transaction. So there's one txid to wait for however many rows change, and you get it without another database round trip.

Add the three write routes to `backend/server.ts`, chained onto the same app so `AppType` carries them to the frontend. They follow the `/api/v1/messages/live` route from the [queries guide](./queries#exposing-an-endpoint) and the `/api/v1/inbox/live` route from the [reactivity guide](./reactivity#seal-a-broader-query):

```ts filename="backend/server.ts"
import { and, eq, inArray, ne, sql } from "drizzle-orm"
import { Hono } from "hono"
import { HTTPException } from "hono/http-exception"
import { validator } from "hono/validator"

import { requireUser } from "./auth"
import { db } from "./db"
import { channelMembers, messages } from "./schema"

export type MutationResponse =
  | { readonly kind: "committed"; readonly txid: string }
  | { readonly kind: "unchanged" }

// The id of the transaction that made the change, read in the write's own RETURNING
const txid = sql<string>`pg_current_xact_id()::text`

const mutationResponse = (row?: { txid: string }): MutationResponse =>
  row ? { kind: "committed", txid: row.txid } : { kind: "unchanged" }

const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i

function isUuid(value: unknown): value is string {
  return typeof value === "string" && UUID.test(value)
}

function isBody(value: unknown): value is string {
  return typeof value === "string" && value.trim() !== ""
}

const app = new Hono()
  // ...the sealing routes: /api/v1/messages/live and /api/v1/inbox/live
  .post(
    "/api/v1/messages",
    validator("json", (value, c) => {
      const batch: unknown = value?.batch

      if (
        !Array.isArray(batch) ||
        batch.length === 0 ||
        !batch.every(
          (item): item is { id: string; channelId: number; body: string } =>
            isUuid(item?.id) && Number.isInteger(item?.channelId) && isBody(item?.body)
        )
      ) {
        return c.json({ error: "batch must be a non-empty array of { id, channelId, body }" }, 400)
      }

      return { batch }
    }),
    async (c) => {
      const user = await requireUser(c)
      const { batch } = c.req.valid("json")
      const channelIds = [...new Set(batch.map((message) => message.channelId))]
      const rows = batch.map(({ id, channelId, body }) => ({ id, channel_id: channelId, body }))

      // One statement: the batch is written only if the user is a member of every channel in it
      const [sent] = await db
        .insert(messages)
        .select(
          db
            .select({
              id: sql`batch.id`.as("id"),
              channel_id: sql`batch.channel_id`.as("channel_id"),
              author_id: sql`${user.id}`.as("author_id"),
              body: sql`batch.body`.as("body"),
              created_at: sql`now()`.as("created_at"),
            })
            .from(sql`jsonb_to_recordset(${JSON.stringify(rows)}::jsonb) as batch(id uuid, channel_id integer, body text)`)
            .where(
              eq(
                db.$count(
                  channelMembers,
                  and(eq(channelMembers.user_id, user.id), inArray(channelMembers.channel_id, channelIds))
                ),
                channelIds.length
              )
            )
        )
        .returning({ txid })

      if (!sent) {
        throw new HTTPException(403, { message: "Not a member of this channel" })
      }

      return c.json(mutationResponse(sent))
    }
  )
  .patch(
    "/api/v1/messages",
    validator("json", (value, c) => {
      const batch: unknown = value?.batch

      if (
        !Array.isArray(batch) ||
        batch.length === 0 ||
        !batch.every((item): item is { id: string; body: string } => isUuid(item?.id) && isBody(item?.body))
      ) {
        return c.json({ error: "batch must be a non-empty array of { id, body }" }, 400)
      }

      return { batch }
    }),
    async (c) => {
      const user = await requireUser(c)
      const { batch } = c.req.valid("json")

      const [edited] = await db
        .update(messages)
        .set({ body: sql`edit.body` })
        .from(sql`jsonb_to_recordset(${JSON.stringify(batch)}::jsonb) as edit(id uuid, body text)`)
        .where(and(eq(messages.id, sql`edit.id`), eq(messages.author_id, user.id), ne(messages.body, sql`edit.body`)))
        .returning({ txid })

      return c.json(mutationResponse(edited))
    }
  )
  .delete(
    "/api/v1/messages",
    validator("json", (value, c) => {
      const batch: unknown = value?.batch

      if (!Array.isArray(batch) || batch.length === 0 || !batch.every(isUuid)) {
        return c.json({ error: "batch must be a non-empty array of uuids" }, 400)
      }

      return { batch }
    }),
    async (c) => {
      const user = await requireUser(c)
      const { batch } = c.req.valid("json")

      const [deleted] = await db
        .delete(messages)
        .where(and(inArray(messages.id, batch), eq(messages.author_id, user.id)))
        .returning({ txid })

      return c.json(mutationResponse(deleted))
    }
  )

export type AppType = typeof app

export default app
```

Return the txid from the write itself. Each route puts a `txid` field in its write's `RETURNING`, and that field reads [`pg_current_xact_id()`](https://www.postgresql.org/docs/current/functions-info.html#FUNCTIONS-INFO-SNAPSHOT). A single statement runs in its own transaction, so that's the ID of the transaction that made the change. It comes back with the write, in one round trip, and it works with any Postgres driver. The `::text` cast returns the txid as a decimal string, so its 64-bit value stays exact in JavaScript. Every row a statement returns carries the same txid, so each route takes the first.

Write each batch in one statement, so there's one txid:

- **Send** passes the whole batch as one JSON parameter, and `jsonb_to_recordset()` turns it into typed rows (`id uuid, channel_id integer, body text`) that the insert selects from. The `WHERE` counts the user's `channel_members` rows for the batch's channels and compares the count with the number of distinct channels. If the user isn't a member of every channel, nothing's written and no row comes back, so the route throws a 403. It's all or nothing.
- **Edit** runs `UPDATE … FROM jsonb_to_recordset(…)`, which joins each message to its new body. It only changes messages the user wrote, so only the author can edit a message, and the `<>` check skips edits that leave the text as it was.
- **Delete** runs `DELETE … WHERE id IN (…)`, restricted to messages the user wrote, so only the author can delete a message.

In Drizzle, the send's `insert().select()` needs every column in table order (so it selects `created_at` as `now()`), and each `sql` field needs an `.as()` alias.

**Warning: Don't open a transaction just to read the txid**

Wrapping a write in `db.transaction()` and then running `select pg_current_xact_id()` costs four round trips (`BEGIN`, the write, the select and `COMMIT`) and holds a pooled connection for all of them. When a write genuinely needs several statements, keep the transaction and put the txid in the `RETURNING` of a write that always changes a row. Every statement in a transaction shares its txid, but a write that matches nothing returns no row, and so no txid. The [Mastra example](../examples/mastra#start-agents-from-your-writes) shows this with two inserts.

When an edit or a delete batch matches no rows, the statement returns no row, so `mutationResponse()` returns `{ kind: "unchanged" }` instead of a txid. That happens when every edit leaves the text as it was, or when every message is already gone or someone else wrote it. Nothing changed, so there's nothing to wait for.

**Important: Always pass a timeout**

`awaitTxId()` keeps waiting while the subscription reconnects or waits for a renewed sealed query, so always pass a timeout. When the timeout passes, it rejects, the optimistic change drops and the UI shows that the change couldn't be confirmed. The write may still have committed. It also rejects if the subscription errors or closes.

### Calling the routes from the frontend

Add a helper for each route to `frontend/api.ts`, next to `fetchSealedMessages()` from the [subscribing guide](./subscribing#fetch-from-an-api-endpoint). Add `MutationResponse` to the file's type import from `../backend/server`, so each helper returns the route's own response type:

```ts filename="frontend/api.ts"
import type { AppType, MutationResponse } from "../backend/server"

export async function sendMessages(
  batch: Pick<Message, "id" | "channel_id" | "body">[]
): Promise<MutationResponse> {
  const res = await server.api.v1.messages.$post({
    json: { batch: batch.map(({ id, channel_id, body }) => ({ id, channelId: channel_id, body })) }
  })

  if (!res.ok) {
    throw new Error(`Could not send the messages (${res.status})`)
  }

  return res.json()
}

export async function editMessages(batch: { id: string; body: string }[]): Promise<MutationResponse> {
  const res = await server.api.v1.messages.$patch({ json: { batch } })

  if (!res.ok) {
    throw new Error(`Could not edit the messages (${res.status})`)
  }

  return res.json()
}

export async function deleteMessages(ids: string[]): Promise<MutationResponse> {
  const res = await server.api.v1.messages.$delete({ json: { batch: ids } })

  if (!res.ok) {
    throw new Error(`Could not delete the messages (${res.status})`)
  }

  return res.json()
}
```

Each helper takes an array, so one call can send any number of changes. The `hc` client types each call from its route's validators, so a wrong field is a compile error.

### Shared mutation helpers

All three approaches below share the helpers in `frontend/mutations.ts`: the mutation and message types, `newMessage()`, the `applyMutation()` reducer and `writeMutation()`, which sends one mutation through the route helpers you just added to `frontend/api.ts`, as a batch of one:

```ts filename="frontend/mutations.ts"
import type { Message } from "../backend/schema"
import type { MutationResponse } from "../backend/server"
import { deleteMessages, editMessages, sendMessages } from "./api"

export type MessageMutation =
  | { readonly type: "send"; readonly message: Message }
  | { readonly type: "edit"; readonly id: string; readonly body: string }
  | { readonly type: "delete"; readonly id: string }

export type OptimisticMessage = Message & {
  readonly pending?: boolean;
}

// The server sets its own author and timestamp, but keeps the client's id
export function newMessage(channelId: number, authorId: string, body: string): Message {
  return { id: crypto.randomUUID(), channel_id: channelId, author_id: authorId, body, created_at: new Date() }
}

export function applyMutation(
  messages: readonly OptimisticMessage[],
  mutation: MessageMutation
): readonly OptimisticMessage[] {
  switch (mutation.type) {
    case "send":
      // Once the sent message has synced, show the synced row only
      if (messages.some((message) => message.id === mutation.message.id)) {
        return messages
      }

      // Newest first, to match the query's order
      return [{ ...mutation.message, pending: true }, ...messages]
    case "edit":
      return messages.map((message) =>
        message.id === mutation.id ? { ...message, body: mutation.body, pending: true } : message
      )
    case "delete":
      return messages.filter((message) => message.id !== mutation.id)
  }
}

export function writeMutation(mutation: MessageMutation): Promise<MutationResponse> {
  switch (mutation.type) {
    case "send":
      return sendMessages([mutation.message])
    case "edit":
      return editMessages([{ id: mutation.id, body: mutation.body }])
    case "delete":
      return deleteMessages([mutation.id])
  }
}
```

A send carries the whole new row, with an id the client picks with `crypto.randomUUID()`. The synced row has the same id, so the optimistic row never needs swapping for a real one, and `applyMutation()` skips a pending send once the synced rows include it. That way, a sent message never shows twice.

## Using optimistic mutations

Pick [without a framework](https://neon.com/docs/realtime/guides/mutations#without-a-framework) to see the mechanism or for apps that don't use React, [React's `useOptimistic` hook](https://neon.com/docs/realtime/guides/mutations#with-reacts-useoptimistic-hook) for React apps that keep optimistic state locally in a component, or [TanStack DB collections](https://neon.com/docs/realtime/guides/mutations#with-tanstack-db-collections) for apps that sync into a normalized client store.

### Without a framework

Without a framework, you keep the optimistic state yourself. `frontend/optimistic-messages.ts` keeps an overlay of pending mutations on top of the subscription's synced rows, and merges the two every time either side changes:

```ts filename="frontend/optimistic-messages.ts"
import type { LiveQueryState, MaterializedLiveQuerySubscription } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { applyMutation, type MessageMutation, type OptimisticMessage, writeMutation } from "./mutations"

export function optimisticMessages(
  subscription: MaterializedLiveQuerySubscription<Message>,
  render: (messages: readonly OptimisticMessage[], state: LiveQueryState, error: string | undefined) => void
) {
  // A Map keeps insertion order, so mutations apply in the order they were made
  const pending = new Map<number, MessageMutation>()
  let nextKey = 0
  let error: string | undefined
  let stopped = false

  function update() {
    if (stopped) {
      return
    }

    const snapshot = subscription.getSnapshot()
    const synced: readonly OptimisticMessage[] = snapshot.data ?? []

    render([...pending.values()].reduce(applyMutation, synced), snapshot, error)
  }

  async function mutate(mutation: MessageMutation) {
    const key = nextKey++

    error = undefined
    pending.set(key, mutation)
    update()

    try {
      const result = await writeMutation(mutation)

      if (result.kind === "committed") {
        await subscription.awaitTxId(result.txid, 10_000)
      }
    } catch {
      error = "Couldn't confirm the change"
    } finally {
      pending.delete(key)
      update()
    }
  }

  const unsubscribe = subscription.onChange(update)

  update()

  return {
    mutate,
    stop: () => {
      stopped = true
      unsubscribe()
    }
  }
}
```

Each mutation leaves the overlay once its txid arrives, or once it fails. Either way, the list falls back to the synced rows, which by then either include the change or show that it didn't happen.

Call `optimisticMessages()` with the subscription you created in the [subscribing guide](./subscribing#subscribe-to-the-sealed-query) and a function that draws the list. It replaces `subscription.onChange(render)` from that guide, and passes the subscription's state through, so the page can show its status line as before. Call `mutate()` from your UI, with `newMessage()` for a send. It needs the signed-in user's id, which you read from the [Managed Better Auth](https://neon.com/docs/auth/overview) session, as `frontend/main.tsx` does in [render the app](https://neon.com/docs/realtime/guides/mutations#render-the-app). Show Edit and Delete only on the user's own messages, and disable them on pending messages, so you don't start a new change on a message whose last change isn't confirmed yet. The routes still enforce authorship. Call `stop()` before you unsubscribe.

### With React's `useOptimistic` hook

In React, `useOptimistic` holds the overlay for you and each write runs in its own transition. This is the optimistic version of `frontend/Messages.tsx` from the [reactivity guide](./reactivity#uselivequery). It runs the same live query and takes the same props, plus `channelId` and the signed-in user's `userId`, which `Channel` passes in (shown after the component). It reuses the types and helpers from `frontend/mutations.ts`, and `LocalTime` from the same guide:

```tsx filename="frontend/Messages.tsx"
import { type FormEvent, startTransition, useEffect, useOptimistic, useState } from "react"
import { useLiveQuery } from "@neon/realtime-react"
import type { SealedLiveQuery } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { LocalTime } from "./LocalTime"
import {
  applyMutation,
  type MessageMutation,
  newMessage,
  type OptimisticMessage,
  writeMutation
} from "./mutations"

const NO_MESSAGES: readonly OptimisticMessage[] = []

interface Props {
  sealedQuery: SealedLiveQuery<Message>;
  refreshQuery: () => Promise<SealedLiveQuery<Message>>;
  initialData?: readonly Message[];
  channelId: number;
  userId: string;
}

export function Messages({ sealedQuery, refreshQuery, initialData, channelId, userId }: Props) {
  const { data, status, error, utils } = useLiveQuery(sealedQuery, { refreshQuery, initialData })

  const [messages, addOptimistic] = useOptimistic<readonly OptimisticMessage[], MessageMutation>(
    data ?? NO_MESSAGES,
    applyMutation
  )

  const [mutationError, setMutationError] = useState<string>()

  useEffect(() => {
    return utils.onUpdate((update) => {
      if (update.type === "changes") {
        console.debug(`Applied ${update.changes.length} changes from transactions ${update.batch.txids.join(", ")}`)
      }
    })
  }, [utils])

  function mutate(mutation: MessageMutation) {
    setMutationError(undefined)

    startTransition(async () => {
      addOptimistic(mutation)

      try {
        const result = await writeMutation(mutation)

        if (result.kind === "committed") {
          await utils.awaitTxId(result.txid, 10_000)
        }
      } catch {
        setMutationError("Couldn't confirm the change")
      }
    })
  }

  function send(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()

    const form = event.currentTarget
    const body = String(new FormData(form).get("body") ?? "").trim()

    if (body) {
      form.reset()
      mutate({ type: "send", message: newMessage(channelId, userId, body) })
    }
  }

  function edit(message: OptimisticMessage) {
    const body = window.prompt("Edit message", message.body)?.trim()

    if (body) {
      mutate({ type: "edit", id: message.id, body })
    }
  }

  if (status === "error") {
    return <p role="alert">Live updates stopped: {error.message}</p>
  }

  if (data === undefined) {
    return <p>Loading messages</p>
  }

  return (
    <section>
      <form onSubmit={send}>
        <input name="body" placeholder="Message" required />
        <button type="submit">Send</button>
      </form>

      {status === "stale" && <p role="status">Updating</p>}
      {mutationError && <p role="alert">{mutationError}</p>}

      <ul>
        {messages.map((message) => (
          <li key={message.id} aria-busy={message.pending}>
            <LocalTime date={message.created_at} />
            <p>{message.body}</p>
            {message.author_id === userId && (
              <>
                <button disabled={message.pending} onClick={() => edit(message)} type="button">
                  Edit
                </button>
                <button
                  disabled={message.pending}
                  onClick={() => mutate({ type: "delete", id: message.id })}
                  type="button"
                >
                  Delete
                </button>
              </>
            )}
          </li>
        ))}
      </ul>
    </section>
  )
}
```

`mutate()` runs each mutation in its own transition, so independent writes run concurrently. The transition applies the mutation optimistically, writes through your backend and, if the write committed, waits for its txid with [`utils.awaitTxId()`](../sdks/typescript#react-uselivequeryutils). When the transition ends, React drops its optimistic change. By then the change is in `data`, with the same id for a sent message, so the list doesn't flicker. If the write fails or isn't confirmed in time, the optimistic change drops the same way, the message reverts and the error line shows.

Edit and Delete show only on the user's own messages, and the routes still enforce authorship. They're disabled on pending messages, so you don't start a new change on a message whose last change isn't confirmed yet.

In `frontend/Channel.tsx` from the [reactivity guide](./reactivity#changing-query-parameters), give `Channel` a `userId` prop and pass it to `Messages` with `channelId`. Read `userId` from the [Managed Better Auth](https://neon.com/docs/auth/overview) session where you render `Channel`, as `frontend/main.tsx` does in [render the app](https://neon.com/docs/realtime/guides/mutations#render-the-app):

```tsx filename="frontend/Channel.tsx"
// ...imports and useSealedQuery() as in the reactivity guide

export function Channel({ channelId, userId }: { channelId: number; userId: string }) {
  const sealed = useSealedQuery(channelId)
  // Renewals must be for the same query, so refresh with the same channel
  const refreshQuery = useCallback(() => fetchSealedMessages(channelId), [channelId])

  if (sealed?.sealedQuery) {
    return (
      <Messages
        sealedQuery={sealed.sealedQuery}
        refreshQuery={refreshQuery}
        channelId={channelId}
        userId={userId}
      />
    )
  }

  if (sealed?.error) {
    return <p role="alert">Couldn't open this channel</p>
  }

  return <p>Loading messages</p>
}
```

### With TanStack DB collections

For more control, keep optimistic state in a [TanStack DB](https://tanstack.com/db/latest/docs/overview) collection. Every query and component that reads the collection then sees the same optimistic changes, and they stay consistent across client-side joins. Failed writes roll back automatically, and one transaction can span several collections.

Add mutation handlers to `createMessagesCollection()` in `frontend/collections.ts`, from the [reactivity guide](./reactivity#create-the-collection). TanStack DB calls each handler once per transaction, with all of its mutations, so each handler sends them to your backend in one request. If the write committed, the handler waits for its txid before it returns, so TanStack DB keeps the optimistic state until the change has synced:

```ts filename="frontend/collections.ts"
import { createCollection } from "@tanstack/react-db"
import { realtimeCollectionOptions } from "@neon/realtime-tanstack"
import type { SealedLiveQuery } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { deleteMessages, editMessages, fetchSealedInbox, sendMessages } from "./api"
import { client } from "./client"

export function createMessagesCollection(sealedQuery: SealedLiveQuery<Message>) {
  return createCollection(
    realtimeCollectionOptions({
      id: "messages",
      client,
      query: sealedQuery,
      refreshQuery: fetchSealedInbox,
      getKey: (message) => message.id,
      onInsert: async ({ transaction, collection }) => {
        const result = await sendMessages(transaction.mutations.map(({ modified }) => modified))

        if (result.kind === "committed") {
          await collection.utils.awaitTxId(result.txid, 10_000)
        }
      },
      onUpdate: async ({ transaction, collection }) => {
        const result = await editMessages(transaction.mutations.map(({ modified: { id, body } }) => ({ id, body })))

        if (result.kind === "committed") {
          await collection.utils.awaitTxId(result.txid, 10_000)
        }
      },
      onDelete: async ({ transaction, collection }) => {
        const result = await deleteMessages(transaction.mutations.map(({ original }) => original.id))

        if (result.kind === "committed") {
          await collection.utils.awaitTxId(result.txid, 10_000)
        }
      }
    })
  )
}

export type MessagesCollection = ReturnType<typeof createMessagesCollection>
```

While a handler runs, TanStack DB holds back synced changes. When the handler returns, it drops the optimistic state and applies the synced rows together, so a sent message's optimistic row gives way to its synced row, which has the same id, in a single step. If a handler throws, the optimistic change rolls back. [`collection.utils.awaitTxId()`](../sdks/typescript#tanstack-db-realtimecollectionutilsawaittxid) resolves once the transaction has entered TanStack DB's sync queue, and it takes the same explicit timeout.

Then write through the collection. This is the optimistic version of `frontend/Inbox.tsx` from the [reactivity guide](./reactivity#query-the-collection). It runs the same local query, and its `insert()`, `update()` and `delete()` calls apply each change locally at once and call the matching handler:

```tsx filename="frontend/Inbox.tsx"
import type { FormEvent } from "react"
import { eq, useLiveQuery as useCollectionQuery } from "@tanstack/react-db"

import type { Message } from "../backend/schema"
import type { MessagesCollection } from "./collections"
import { newMessage } from "./mutations"

interface Props {
  messagesCollection: MessagesCollection;
  channelId: number;
  userId: string;
}

export function Inbox({ messagesCollection, channelId, userId }: Props) {
  const { data, isReady, isError } = useCollectionQuery({
    query: (q) =>
      q
        .from({ message: messagesCollection })
        .where(({ message }) => eq(message.channel_id, channelId))
        .orderBy(({ message }) => message.created_at, "desc")
  })

  function send(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()

    const form = event.currentTarget
    const body = String(new FormData(form).get("body") ?? "").trim()

    if (body) {
      form.reset()
      messagesCollection.insert(newMessage(channelId, userId, body))
    }
  }

  function edit(message: Message) {
    const body = window.prompt("Edit message", message.body)?.trim()

    if (body) {
      messagesCollection.update(message.id, (draft) => {
        draft.body = body
      })
    }
  }

  if (isError) {
    return <p role="alert">Couldn't sync messages</p>
  }

  if (!isReady) {
    return <p>Loading messages</p>
  }

  return (
    <section>
      <form onSubmit={send}>
        <input name="body" placeholder="Message" required />
        <button type="submit">Send</button>
      </form>

      <ul>
        {data.map((message) => (
          <li key={message.id} aria-busy={message.$hasPendingWrites}>
            {message.body}
            {message.author_id === userId && (
              <>
                <button disabled={message.$hasPendingWrites} onClick={() => edit(message)} type="button">
                  Edit
                </button>
                <button
                  disabled={message.$hasPendingWrites}
                  onClick={() => messagesCollection.delete(message.id)}
                  type="button"
                >
                  Delete
                </button>
              </>
            )}
          </li>
        ))}
      </ul>
    </section>
  )
}
```

`$hasPendingWrites` is `true` while a row has a pending optimistic change, which disables its buttons, so you don't start a new change on a message whose last change isn't confirmed yet. Edit and Delete show only on the user's own messages, and the routes still enforce authorship. Each call returns a TanStack DB transaction, and its `when("settled")` promise rejects with the handler's error if the write fails and the change rolls back, so you can await it to show an error.

An optimistic insert needs a whole `Message`, so the component also takes the signed-in user's id. It only fills in the optimistic row, because the server takes the author from the verified token. Read it from the [Managed Better Auth](https://neon.com/docs/auth/overview) session where the app creates the collection, as `frontend/main.tsx` does in [render the app](https://neon.com/docs/realtime/guides/mutations#render-the-app).

The [TanStack example](../examples/tanstack) puts these handlers into a full app with server-side rendering, and the [Next.js example](../examples/nextjs) shows the React binding in a server-rendered app.

## Render the app

`frontend/main.tsx` from the [reactivity guide](./reactivity#query-the-collection) renders both views inside `RealtimeProvider`. Read the signed-in user's id from the session and pass it to `Channel` and `Inbox`:

```tsx filename="frontend/main.tsx"
import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import { RealtimeProvider } from "@neon/realtime-react"

import { fetchSealedInbox } from "./api"
import { authClient } from "./auth"
import { Channel } from "./Channel"
import { client } from "./client"
import { createMessagesCollection } from "./collections"
import { Inbox } from "./Inbox"

const root = createRoot(document.getElementById("root")!)
const { data: session } = await authClient.getSession()

if (!session) {
  root.render(<p>Sign in to see the messages.</p>)
} else {
  const userId = session.user.id
  const messagesCollection = createMessagesCollection(await fetchSealedInbox())

  root.render(
    <StrictMode>
      <RealtimeProvider client={client}>
        <Channel channelId={2} userId={userId} />
        <Inbox messagesCollection={messagesCollection} channelId={2} userId={userId} />
      </RealtimeProvider>
    </StrictMode>
  )
}
```

Signed out, it renders a message instead of the views. Sign-in isn't part of these guides: the [running example](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app) shows one way to add it.

--- [Document source](https://neon.com/docs/realtime/guides/queries.md) ---

> Summary: Define live queries in your backend with raw SQL or Drizzle, fill in their parameters from the authenticated request, and seal them so clients can subscribe without being able to read or change them.

# Defining queries

Define live SQL queries that you can subscribe to.

Last updated: 2026-10-30

Realtime works by defining and [subscribing](./subscribing) to live SQL queries. Queries are designed to be [defined securely](https://neon.com/docs/realtime/guides/queries#defining-live-queries) in your backend code and [subscribed‑to safely](https://neon.com/docs/realtime/guides/queries#exposing-queries) in your frontend.

Define live queries using [raw SQL](https://neon.com/docs/realtime/guides/queries#using-raw-sql) or a [query builder or ORM](https://neon.com/docs/realtime/guides/queries#using-a-query-builder-or-orm). [Seal the queries](https://neon.com/docs/realtime/guides/queries#sealing-queries) and [expose](https://neon.com/docs/realtime/guides/queries#exposing-queries) them to your frontend via an [API endpoint](https://neon.com/docs/realtime/guides/queries#exposing-an-endpoint) or a [server function](https://neon.com/docs/realtime/guides/queries#using-server-functions), using your normal [authorization](https://neon.com/docs/realtime/guides/queries#authorization) context.

## Setup

The guides all share one running example: a chat app where users read the messages in the channels they belong to. You can see the [source code in the examples repo](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app) or expand the steps below.

<details>

<summary>Setup steps</summary>

Install [Drizzle](https://orm.drizzle.team) with the [node-postgres](https://node-postgres.com) driver (`pg`), [Hono](https://hono.dev), `ws`, and `jose`, which validates [Better Auth](https://neon.com/docs/auth/overview) tokens:

```bash filename="Terminal"
npm install drizzle-orm pg hono jose ws
npm install -D @types/pg @types/ws
```

Install the Realtime [TypeScript SDK](../sdks/typescript) and its [Drizzle adapter](../sdks/typescript#drizzle):

```bash filename="Terminal"
npm install @neon/realtime @neon/realtime-drizzle
```

Install the [Managed Better Auth](https://neon.com/docs/auth/overview) client for the frontend:

```bash filename="Terminal"
npm install @neon/auth
```

Add a `neon.ts` file that enables Managed Better Auth and [Realtime](../quickstart#enable-realtime) on your branch:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1"

export default defineConfig({
  auth: true,
  preview: { realtime: { allowedOrigins: ["http://localhost:5173"] } }
})
```

List every origin your browser app runs on in `allowedOrigins`, for example `http://localhost:3000` for the SSR frameworks.

Install the config package, link the directory to your Neon project and deploy the config:

```bash filename="Terminal"
npm install -D @neon/config
neon link
neon deploy
```

`neon deploy` enables Managed Better Auth and Realtime, waits until they're ready, and writes the four server variables below to `.env.local`. If Realtime isn't ready before the deploy stops waiting, run `neon env pull` once it is.

These are the environment variables on the server:

- `DATABASE_URL`: your Lakebase Postgres [connection string](https://neon.com/docs/connect/connect-intro)
- `NEON_REALTIME_SECRET`: the secret from the [Realtime page](../quickstart#enable-realtime) in the Neon Console
- `NEON_AUTH_BASE_URL`: your [Managed Better Auth](https://neon.com/docs/auth/overview) URL
- `NEON_REALTIME_URL`: the URL from the same Realtime page

And these in the frontend, with the same values as `NEON_AUTH_BASE_URL` and `NEON_REALTIME_URL`:

- `VITE_NEON_AUTH_URL`
- `VITE_NEON_REALTIME_URL`

Vite expands `$VAR` in env files, and `neon env pull` keeps lines it doesn't manage, so point them at the server variables:

```bash filename="Terminal"
echo 'VITE_NEON_AUTH_URL=$NEON_AUTH_BASE_URL' >> .env.local
echo 'VITE_NEON_REALTIME_URL=$NEON_REALTIME_URL' >> .env.local
```

Define the example schema and apply your usual [Drizzle migrations](https://neon.com/docs/guides/drizzle-migrations):

```ts filename="backend/schema.ts"
import { integer, pgTable, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core"

export const messages = pgTable(
  "messages", {
    id: uuid("id").primaryKey(),
    channel_id: integer("channel_id").notNull(),
    author_id: text("author_id").notNull(),
    body: text("body").notNull(),
    created_at: timestamp("created_at", { withTimezone: true }).notNull().defaultNow()
  }
)

export const channelMembers = pgTable(
  "channel_members", {
    channel_id: integer("channel_id").notNull(),
    user_id: text("user_id").notNull()
  },
  (table) => [primaryKey({ columns: [table.channel_id, table.user_id] })]
)

export type Message = typeof messages.$inferSelect
```

Configure your Drizzle client (`db`):

```ts filename="backend/db.ts"
import { drizzle } from "drizzle-orm/node-postgres"
import { Pool } from "pg"
import * as schema from "./schema"

const pool = new Pool({
  // Neon URLs say sslmode=require. Asking pg for verify-full keeps today's checks and skips its warning
  connectionString: process.env.DATABASE_URL!.replace("sslmode=require", "sslmode=verify-full")
})
export const db = drizzle(pool, { schema })

// So an idle connection error, for example when the compute scales to zero, doesn't crash the API
pool.on("error", (error: Error) => console.error(error))
```

Great, that's the main setup to follow along with the guides. Or for the full boilerplate, see the [example source code](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app) on GitHub.

</details>

## Defining live queries

Neon Realtime supports any **deterministic SQL query** that is [supported by Postgres](https://neon.com/postgresql/tutorial/select).

This includes [where clauses](https://neon.com/postgresql/tutorial/where), [order by](https://neon.com/postgresql/tutorial/order-by) and [limit](https://neon.com/postgresql/tutorial/limit), [joins](https://neon.com/postgresql/tutorial/joins), aggregates, [group by](https://neon.com/postgresql/tutorial/group-by) and distinct, functions (built-in and user-defined), extensions, window functions, [sub-queries](https://neon.com/postgresql/tutorial/subquery), etc.

The only limitations are that:

1. queries must be **read-only**, i.e.: must not have side effects
2. any functions used in your queries must be **deterministic**

So, for example, you can't `SELECT` over updated rows and you can't use functions like `now()` or `gen_random_uuid()`.

### Table requirements

Tables need a [stable replica identity](https://www.postgresql.org/docs/current/sql-altertable.html#SQL-ALTERTABLE-REPLICA-IDENTITY). If your tables have a primary key, they're fine.

**Optional: REPLICA IDENTITY FULL:**

Setting `REPLICA IDENTITY FULL` can make live queries marginally faster, at the cost of writing the whole old row to the Postgres WAL on every update and delete. That may save Realtime a lookup when it processes those changes. If latency matters for a write-heavy table, benchmark both settings with your own workload before you switch.

```sql
ALTER TABLE messages REPLICA IDENTITY FULL;
```

### Using raw SQL

Create a `RealtimeServer` instance (`secret` is the `NEON_REALTIME_SECRET` generated when [enabling Realtime](../quickstart#enable-realtime) and `db` should be the `dbname` in your [Postgres connection string](https://neon.com/docs/connect/connect-from-any-app#get-a-connection-string-from-the-neon-console)):

```ts filename="backend/realtime-raw.ts"
import { createRealtime } from "@neon/realtime/server"

export const realtime = createRealtime({
  secret: process.env.NEON_REALTIME_SECRET!,
  db: "neondb"
})
```

`createRealtime()` also takes a [`debugMode`](./subscribing#show-full-database-errors) option.

Then define queries using [`rawSql`](../sdks/typescript#backend-rawsql). For example:

```ts filename="backend/queries-raw.ts"
import { rawSql } from "@neon/realtime/server"

import type { Message } from "./schema"

export const allMessages = rawSql<Message>(
  `SELECT author_id, body, channel_id, created_at, id FROM messages`
)
```

A raw SQL query has to be a single `SELECT` statement with no `;`. With at most 32 KiB of SQL and at most 256 parameters of up to 16 KiB each.

#### Query parameters

When your query has parameters, wrap it in a function so they can be provided when using it. Put placeholders (like `$1`, `$2`, etc.) in the SQL and pass the values in the array.

For example:

```ts filename="backend/queries-raw.ts"
import { rawSql } from "@neon/realtime/server"

import type { Message } from "./schema"

export function messagesQuery(userId: string, channelId: number) {
  return rawSql<Message>(
    `SELECT messages.author_id, messages.body, messages.channel_id,
       messages.created_at, messages.id FROM messages
     INNER JOIN channel_members ON channel_members.channel_id = messages.channel_id
     WHERE channel_members.user_id = $1 AND messages.channel_id = $2
     ORDER BY messages.created_at DESC
     LIMIT 50`,
    [userId, channelId]
  )
}
```

**Warning: SQL injection**

Never use literal interpolation for user input like `` `WHERE user_id = '${userId}'` ``. Always use placeholders like `` `WHERE user_id = $1` `` instead.

#### Parameter types

You can pass strings, numbers, booleans, bigints and `null` as they are. Other value types need a [`pgParam`](../sdks/typescript#backend-pgparam) helper to specify the Postgres type. A `Date` could be a `date`, a `timestamp` or a `timestamptz`, so wrap it in `pgParam.date()`, `pgParam.timestamp()` or `pgParam.timestamptz()`.

For example, this filters messages `since` a [timestamp with timezone](https://neon.com/postgresql/tutorial/timestamp#introduction-to-postgresql-timestamp):

```ts filename="backend/recent-messages.ts" {5,10,13}
import { pgParam, rawSql } from "@neon/realtime/server"

import type { Message } from "./schema"

export function messagesSinceQuery(userId: string, channelId: number, since: Date) {
  return rawSql<Message>(
    `SELECT messages.author_id, messages.body, messages.channel_id,
       messages.created_at, messages.id FROM messages
     INNER JOIN channel_members ON channel_members.channel_id = messages.channel_id
     WHERE channel_members.user_id = $1 AND messages.channel_id = $2 AND messages.created_at > $3
     ORDER BY messages.created_at DESC
     LIMIT 50`,
    [userId, channelId, pgParam.timestamptz(since)]
  )
}
```

There are helpers for dates, JSON, `bytea` and arrays, such as `pgParam.array("text", ["a"])`. `pgParam.text()` covers any other named type, for example `pgParam.text("uuid", id)`.

### Using a query builder or ORM

Realtime supports an adapter pattern to convert any typed query object to raw SQL. This works by passing an adapter to [`createRealtime`](../sdks/typescript#backend-createrealtime).

The rest of these guides use the Drizzle versions of `backend/realtime.ts` and `backend/queries.ts` below in place of the raw SQL files above.

For example, configure Realtime to use the [`drizzleAdapter`](../sdks/typescript#drizzle-drizzleadapter):

```ts filename="backend/realtime.ts" {2,7}
import { createRealtime } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

export const realtime = createRealtime({
  secret: process.env.NEON_REALTIME_SECRET!,
  db: "neondb",
  adapter: drizzleAdapter()
})
```

You can now define queries using Drizzle:

```ts filename="backend/queries.ts"
import { and, desc, eq, getTableColumns } from "drizzle-orm"

import { db } from "./db"
import { channelMembers, messages } from "./schema"

export function messagesQuery(userId: string, channelId: number) {
  return db
    .select(getTableColumns(messages))
    .from(messages)
    .innerJoin(channelMembers, eq(channelMembers.channel_id, messages.channel_id))
    .where(and(eq(channelMembers.user_id, userId), eq(messages.channel_id, channelId)))
    .orderBy(desc(messages.created_at))
    .limit(50)
}
```

See the [Drizzle](../examples/drizzle) and [Kysely](../examples/kysely) examples for more details.

**Tip: Column name casing**

The Drizzle adapter needs each selected key to match its column name. That's why the schema uses snake_case keys and the join selects `getTableColumns(messages)`.

The [Drizzle example](../examples/drizzle) shows how to alias fields to match the column key.

## Sealing queries

Once you've defined a query, if you're using it in trusted backend code, you can just [subscribe to it right away](./subscribing#subscribe-in-trusted-backend-code). However, most of the time, you'll want to subscribe to live queries in an untrusted environment, such as a frontend app or agent runtime.

This is where **sealing** comes in. Sealing signs and encrypts the exact query, its parameters and the target database into a short-lived capability (similar to a JWT), so it can be used safely in an untrusted environment.

**Warning: Keep your Realtime secret on the server**

Anyone with `NEON_REALTIME_SECRET` can seal any query. Treat it like your `DATABASE_URL`, and never ship it in a browser bundle. In a Vite app, that means never giving it a `VITE_` prefix. To replace it, run [`neon realtime rotate-secret`](https://neon.com/docs/cli/realtime#rotate-secret).

To seal a query you pass your query instance, e.g.:

```ts filename="backend/server.ts"
const query = messagesQuery(userId, channelId)
```

To the [`seal`](../sdks/typescript#backend-realtimeserverseal) method of the `RealtimeServer` instance you created above:

```ts filename="backend/server.ts"
const sealedQuery = await realtime.seal({ query })
```

It's local [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API) work with no network call, so it's cheap to run on every request. It returns a [`SealedLiveQuery<Row>`](../sdks/typescript#backend-sealedlivequery), which has three fields:

- `capability`: the encrypted query
- `expiresAt`: when it expires, in Unix milliseconds
- `queryFingerprint`: a stable identity for the exact query

The client can subscribe to a sealed query, but it can't read or change it. Your secret, your SQL and the parameter values bound to it are not readable anywhere in it. The [Live SQL API](../how-it-works#live-sql-api) verifies the capability itself, so subscribing doesn't need a call back to your server.

**Important: Sealed queries are bearer tokens**

Sealed queries are typically user-specific and sealed per request, where they can bake in parameters like the authenticated user ID.

Anyone holding a sealed query can subscribe to it until it expires. Send it over HTTPS, and keep it out of URLs, logs and persistent browser storage.

### Renewing sealed queries

Sealed queries are short-lived (currently 60 seconds). To keep a subscription running, renew its sealed query before `expiresAt`, or the subscription goes `stale` when it expires. The [reactivity bindings](./reactivity) renew for you when you pass them a `refreshQuery` function. The [subscribing guide](./subscribing#renew-the-sealed-query) shows how to renew manually.

A renewal has to be for the **same** query. Different parameter values make a different query, with a different fingerprint. So, for example, to switch channels in the chat app, you would seal the new query and subscribe again.

## Authorization

Once you've sealed a query, you'll want to get it to your frontend to subscribe to.

You do this by [exposing the query](https://neon.com/docs/realtime/guides/queries#exposing-queries) from a **request handler** in your backend. So that's where you authenticate the user and decide what they can see.

### Sealing authorized queries

The flow is as follows:

1. read the auth context from the request
2. authorize access using arbitrary business logic (e.g.: your auth middleware)
3. construct the query, passing in any relevant parameters from the auth context (e.g.: filtering or joining on the authenticated `userId`)
4. seal the query so these can't be changed

This allows you to authorize live query subscriptions using existing web auth logic, middleware and frameworks, such as [Neon Auth](https://neon.com/docs/auth/overview).

### Live authorization

In our running example, [`messagesQuery()`](https://neon.com/docs/realtime/guides/queries#using-a-query-builder-or-orm) joins through `channel_members` and filters on the `userId`, so it only returns messages from channels the user belongs to:

```ts
.where(and(eq(channelMembers.user_id, userId), eq(messages.channel_id, channelId)))
```

The join is **part of the live query**, so it stays live. If you remove someone from a channel, they'll immediately lose access to its messages.

That's why Realtime authorizes the **query**, not the connection. Your request handler checks who's asking and seals a query that only matches the rows that the user is allowed to see. The authorization is **defined** at request time but it **dynamically adapts** to your data in realtime.

**Warning: Never trust user input from the client**

Take authorization context from a verified session or token and validate everything else (like `channelId`) that the client sends in the request data.

### Why not row-level security

Postgres [row-level security](https://neon.com/docs/guides/row-level-security) (RLS) is often slow and becomes a bottleneck. It's also awkward to develop with, because your access rules live in migrations, rather than your application code.

It's simpler and more efficient to reuse the auth logic you already have in your backend.

Many existing apps do use RLS, though. So, while it isn't our recommended approach to auth, we have designed Neon Realtime's architecture to be able to support it and we aim to implement support before GA.

## Exposing queries

There are two main ways to expose a [sealed](https://neon.com/docs/realtime/guides/queries#sealing-queries), [authorized](https://neon.com/docs/realtime/guides/queries#authorization) query to your frontend:

1. [exposing an endpoint](https://neon.com/docs/realtime/guides/queries#exposing-an-endpoint) from your backend API
2. [using server functions](https://neon.com/docs/realtime/guides/queries#using-server-functions) (often with [SSR](./ssr))

These are both **request handlers**. They run in a trusted environment in your backend with [auth context available](https://neon.com/docs/realtime/guides/queries#sealing-authorized-queries) from the request.

With Vite and Hono, the browser's auth client talks to Managed Better Auth directly, so its session cookie never reaches your API. The browser sends the session's JWT as a bearer token, and the API verifies it. Next.js and TanStack Start mount Managed Better Auth on your app's own origin, so server code reads the session from its cookie and the browser holds no token. Either way, the Realtime connection carries no user credential: the sealed query is the authorization.

### Exposing an endpoint

Expose the `sealedQuery` from an API endpoint, using any web framework.

Our running example uses [Hono](https://hono.dev) and [Managed Better Auth](https://neon.com/docs/auth/overview). The client [sends its auth token](./subscribing#fetch-from-an-api-endpoint) in an `Authorization: Bearer` header. The JWT is verified against your [Managed Better Auth JWKS](https://neon.com/docs/auth/guides/plugins/jwt#verify-a-token) in a `requireUser` helper:

```ts filename="backend/auth.ts"
import type { Context } from "hono"
import { HTTPException } from "hono/http-exception"
import { createRemoteJWKSet, jwtVerify } from "jose"

const authUrl = process.env.NEON_AUTH_BASE_URL!
const origin = new URL(authUrl).origin
const jwks = createRemoteJWKSet(new URL(`${authUrl}/.well-known/jwks.json`))

async function verifyUserId(token: string): Promise<string | undefined> {
  try {
    const { payload } = await jwtVerify(token, jwks, { issuer: origin, audience: origin })

    return payload.sub
  } catch {
    return undefined
  }
}

export async function getUser(headers: Headers): Promise<{ id: string } | undefined> {
  const header = headers.get("Authorization")
  const token = header?.startsWith("Bearer ") ? header.slice("Bearer ".length) : undefined
  const userId = token ? await verifyUserId(token) : undefined

  return userId ? { id: userId } : undefined
}

export async function requireUser(c: Context): Promise<{ id: string }> {
  const user = await getUser(c.req.raw.headers)

  if (!user) {
    throw new HTTPException(401, { message: "Unauthorized" })
  }

  return user
}
```

We then use this auth helper in a route to securely build and expose the `sealedQuery`:

```ts filename="backend/server.ts" {20,23}
import { Hono } from "hono"
import { validator } from "hono/validator"

import { requireUser } from "./auth"
import { messagesQuery } from "./queries"
import { realtime } from "./realtime"

const app = new Hono().post(
  "/api/v1/messages/live",
  validator("json", (value, c) => {
    const channelId: unknown = value?.channelId

    if (typeof channelId !== "number" || !Number.isInteger(channelId)) {
      return c.json({ error: "channelId must be an integer" }, 400)
    }

    return { channelId }
  }),
  async (c) => {
    const user = await requireUser(c)
    const { channelId } = c.req.valid("json")

    const query = messagesQuery(user.id, channelId)
    const sealedQuery = await realtime.seal({ query })

    return c.json(sealedQuery)
  }
)

export type AppType = typeof app

export default app
```

The `validator()` middleware checks the JSON body before the handler runs and types it, so the frontend's [`hc` client](./subscribing#fetch-from-an-api-endpoint) knows this endpoint takes `{ channelId: number }`. The handler takes the user's ID from `requireUser()` and the `channelId` from the validated body, builds the query, seals it and returns it as JSON. Chain every route onto `new Hono()` in one expression, because `AppType` only carries the routes chained into it.

`seal()` doesn't depend on request or response types and a sealed query is plain JSON. The [subscribing guide](./subscribing#fetch-from-an-api-endpoint) shows how to fetch it from the client and subscribe to it.

### Using server functions

If you're using a framework that supports [server functions](https://react.dev/reference/rsc/server-functions), you can return the `sealedQuery` from one. For example, with [TanStack Start](../examples/tanstack) you can [create a server function](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions).

The server function reads the session from the Managed Better Auth cookie with `requireUser`, a server-only middleware. The [SSR guide](./ssr#send-both-to-the-browser) sets it up. The server function then seals the query for `context.user.id`:

```ts filename="src/server-functions.ts"
import { createServerFn } from "@tanstack/react-start"

import { messagesQuery } from "./backend/queries"
import { realtime } from "./backend/realtime"
import { requireUser } from "./session-middleware"

export const sealMessages = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator((data: { channelId: number }) => {
    if (!Number.isInteger(data.channelId)) {
      throw new Error("channelId must be an integer")
    }

    return data
  })
  .handler(({ data, context }) =>
    realtime.seal({ query: messagesQuery(context.user.id, data.channelId) })
  )
```

The browser calls `sealMessages` to get the sealed query, and calls it again to [renew it](https://neon.com/docs/realtime/guides/queries#renewing-sealed-queries).

To seal the query while the page renders on the server, see the [Server-side rendering](./ssr) guide and the [Next.js](../examples/nextjs) and [TanStack](../examples/tanstack) examples.

--- [Document source](https://neon.com/docs/realtime/guides/reactivity.md) ---

> Summary: Bind live queries to React component state with useLiveQuery, change their parameters and handle errors, or sync a broader live query into a TanStack DB collection and derive instant, local queries from it.

# Client-side reactivity

Bind live queries to component and agent state.

Last updated: 2026-11-05

Build reactive apps and agents using higher-level reactivity primitives that manage live query [subscriptions](./subscribing) for you.

**Important: Framework support**

Realtime [currently](https://neon.com/docs/realtime/guides/reactivity#other-frameworks) has integrations for [React](https://neon.com/docs/realtime/guides/reactivity#react) and [TanStack DB](https://neon.com/docs/realtime/guides/reactivity#tanstack-db).

The [React binding](https://neon.com/docs/realtime/guides/reactivity#react) keeps a component's state in step with a live query, and the [TanStack DB binding](https://neon.com/docs/realtime/guides/reactivity#tanstack-db) syncs live queries into a [reactive client-side store](https://tanstack.com/db).

This page continues the [running example](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app) from the [queries](./queries) and [subscribing](./subscribing) guides. It uses the `client` from `frontend/client.ts` and `fetchSealedMessages()` from `frontend/api.ts`.

## React

The `@neon/realtime-react` binding exports a [`RealtimeProvider`](../sdks/typescript#react-realtimeprovider), a [`useLiveQuery()` hook](../sdks/typescript#react-uselivequery) and a [`useRealtimeClient()` hook](../sdks/typescript#react-userealtimeclient) that returns the provider's client. It works with React 18 and 19.

Install it alongside the client SDK:

```bash filename="Terminal"
npm install @neon/realtime-react
```

### RealtimeProvider

Wrap your app in `<RealtimeProvider>`. This allows all of your `useLiveQuery()` subscriptions to use the same [`RealtimeClient`](../sdks/typescript#client-realtimeclient) and WebSocket connection.

```tsx filename="frontend/main.tsx"
import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import { RealtimeProvider } from "@neon/realtime-react"

import { client } from "./client"

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <RealtimeProvider client={client}>
      {/* Your app here */}
    </RealtimeProvider>
  </StrictMode>
)
```

`client` is the module singleton from `frontend/client.ts`, created once for the whole app. If you render on the server, create the client in the browser instead, as the [server-side rendering guide](./ssr#open-the-connection-in-the-browser) explains.

### useLiveQuery

[`useLiveQuery()`](../sdks/typescript#react-uselivequery) takes a `sealedQuery` and a `refreshQuery` (and, optionally, [`initialData` from SSR](./ssr)) and returns the query's current rows and state.

For example, here we define a `Messages` component with `useLiveQuery`:

```tsx filename="frontend/Messages.tsx"
import { useEffect } from "react"
import { useLiveQuery } from "@neon/realtime-react"
import type { SealedLiveQuery } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { LocalTime } from "./LocalTime"

interface Props {
  sealedQuery: SealedLiveQuery<Message>;
  refreshQuery: () => Promise<SealedLiveQuery<Message>>;
  initialData?: readonly Message[];
}

export function Messages({ sealedQuery, refreshQuery, initialData }: Props) {
  const { data, status, error, utils } = useLiveQuery(sealedQuery, { refreshQuery, initialData })

  useEffect(() => {
    return utils.onUpdate((update) => {
      if (update.type === "changes") {
        console.debug(`Applied ${update.changes.length} changes from transactions ${update.batch.txids.join(", ")}`)
      }
    })
  }, [utils])

  if (status === "error") {
    return <p role="alert">Live updates stopped: {error.message}</p>
  }

  if (data === undefined) {
    return <p>Loading messages</p>
  }

  return (
    <section>
      {status === "stale" && <p role="status">Updating</p>}
      <ul>
        {data.map((message) => (
          <li key={message.id}>
            <LocalTime date={message.created_at} />
            <p>{message.body}</p>
          </li>
        ))}
      </ul>
    </section>
  )
}
```

Which uses this `LocalTime` component to format the time [after hydration](./ssr#keep-row-shapes-identical):

```tsx filename="frontend/LocalTime.tsx"
import { useEffect, useState } from "react"

export function LocalTime({ date }: { date: Date }) {
  const [formatted, setFormatted] = useState<string>()
  useEffect(() => setFormatted(date.toLocaleTimeString()), [date])

  return <time dateTime={date.toISOString()}>{formatted}</time>
}
```

`useLiveQuery` subscribes when the component mounts, re-renders it whenever the results change and unsubscribes when it unmounts.

In this example, the sealed query is a `SealedLiveQuery<Message>`, so `data` is a `readonly Message[]`, with `created_at` decoded to a `Date`. It's `undefined` until the first result arrives. `status` is the subscription's [state](./subscribing#listen-for-changes): the component shows a loading line until the first result and a small indicator while it's `stale`.

#### refreshQuery

`refreshQuery` is how the `useLiveQuery` hook [renews the sealed query](./subscribing#renew-the-sealed-query).

Sealed queries are [short-lived](./queries#renewing-sealed-queries), so the hook calls it 10 seconds before `expiresAt`. If a call fails, the hook retries every second until one succeeds. The callback has to return a sealed query for the same exact query, so `Channel` builds it from the same `channelId` the sealed query was sealed with, as [changing query parameters](https://neon.com/docs/realtime/guides/reactivity#changing-query-parameters) shows. Changing only the callback doesn't restart the subscription, and `useCallback` keeps it stable across renders. Without `refreshQuery`, nothing renews the sealed query, and the rows go `stale` when it expires.

#### initialData

The hook also accepts an optional `initialData` parameter, for example from a server render. See the [server-side rendering guide](./ssr#render-the-initial-rows-straight-away) for more details.

#### utils

The `utils` in the return value give you access to the hook's underlying [materialized subscription](../sdks/typescript#react-uselivequeryutils).

This provides `getSnapshot()`, `getState()`, `awaitRows()`, the `onChange`, `onUpdate` and `onStateChange` listeners, `renew()` and `awaitTxId()`. It's stable for the life of the subscription, so register listeners in an effect and return the remover, as the `onUpdate` listener does.

Note that a `changes` update has already been applied by the time its listener runs, and it [carries the txids](../sdks/typescript#client-livequerybatchinfo) of the transactions in it, which the [mutations guide](./mutations#how-optimistic-mutations-work) uses to confirm optimistic writes.

`utils` omits `unsubscribe()`, because React owns cleanup. The hook unsubscribes when the component unmounts or its sealed query changes. `getState()` and the listeners report the state of the underlying subscription, so they can differ from the hook's `status`.

### Changing query parameters

The hook takes a sealed query, not parameters. Parameters are sealed into the query on the server, where the client can't change them. To show a different channel, fetch a new sealed query for it and pass that in. A new `sealedQuery` is a new logical subscription: the hook cleans up the old one and subscribes to the new one.

Fetch the sealed query in the component that owns the parameter. `useSealedQuery()` fetches one whenever `channelId` changes, and `Channel` renders `Messages` once it has one:

```tsx filename="frontend/Channel.tsx"
import { useCallback, useEffect, useState } from "react"
import type { SealedLiveQuery } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { fetchSealedMessages } from "./api"
import { Messages } from "./Messages"

interface SealedChannel {
  channelId: number;
  sealedQuery?: SealedLiveQuery<Message>;
  error?: unknown;
}

function useSealedQuery(channelId: number): SealedChannel | undefined {
  const [sealed, setSealed] = useState<SealedChannel>()

  useEffect(() => {
    let cancelled = false

    fetchSealedMessages(channelId).then(
      (sealedQuery) => {
        if (!cancelled) setSealed({ channelId, sealedQuery })
      },
      (error: unknown) => {
        if (!cancelled) setSealed({ channelId, error })
      }
    )

    return () => {
      cancelled = true
    }
  }, [channelId])

  // Never hand the previous channel's sealed query to the new channel
  return sealed?.channelId === channelId ? sealed : undefined
}

export function Channel({ channelId }: { channelId: number }) {
  const sealed = useSealedQuery(channelId)
  // Renewals must be for the same query, so refresh with the same channel
  const refreshQuery = useCallback(() => fetchSealedMessages(channelId), [channelId])

  if (sealed?.sealedQuery) {
    return <Messages sealedQuery={sealed.sealedQuery} refreshQuery={refreshQuery} />
  }

  if (sealed?.error) {
    return <p role="alert">Couldn't open this channel</p>
  }

  return <p>Loading messages</p>
}
```

When the channel changes, `sealed` still holds the previous channel's sealed query until the new one arrives. Without the `channelId` check, `Messages` would get the old channel's sealed query with a `refreshQuery` for the new channel. That `refreshQuery` would then fetch the new channel's query to renew the old subscription, and the renewal would be rejected with status `error`. The `cancelled` flag covers a second race. It drops a response that arrives after the channel has changed, or after Strict Mode's extra effect run in development.

### Handling errors

`useLiveQuery()` doesn't throw for subscription errors, and it doesn't suspend. It reports everything through `status`. Render loading and error states from it, as `Messages` does. The hook throws only when it's used outside a `<RealtimeProvider>`, when the sealed query is malformed or when the client is closed. Those errors reach the nearest error boundary, not `status`.

A failed renewal doesn't end in `error`. If your endpoint can't return a sealed query, for example because the user has signed out and it answers 401, the hook keeps retrying, and once the sealed query expires the status is `stale` until a renewal succeeds. So drive sign-out from your auth state: when the user signs out, unmount the components that subscribe. The status becomes `error` only when a renewal returns a malformed response or a sealed query for a different query. To recover, fetch a new sealed query and pass it in.

As with a parameter change, the new sealed query restarts the subscription. The [subscribing guide](./subscribing#handle-errors) covers recovery at the subscription level.

## TanStack DB

Each `useLiveQuery()` above subscribes to one sealed query, so each view of the data needs its own sealed query and its own round trip to your server.

With [TanStack DB](https://tanstack.com/db/latest/docs/overview), you can oversync a broader live query into a client-side collection, such as every message in every channel the user belongs to, and then derive as many local live queries from it as you need: [filters, sorts and joins across collections](https://tanstack.com/db/latest/docs/guides/live-queries).

Install the TanStack binding and TanStack DB's React package:

```bash filename="Terminal"
npm install @neon/realtime-tanstack @tanstack/react-db
```

### Seal a broader query

Add `inboxQuery()` to `backend/queries.ts`. It's `messagesQuery()`, with the same membership join but no channel filter. So it returns the newest 500 messages across every channel that the user belongs to:

```ts filename="backend/queries.ts"
export function inboxQuery(userId: string) {
  return db
    .select(getTableColumns(messages))
    .from(messages)
    .innerJoin(channelMembers, eq(channelMembers.channel_id, messages.channel_id))
    .where(eq(channelMembers.user_id, userId))
    .orderBy(desc(messages.created_at))
    .limit(500)
}
```

Then expose it. In `backend/server.ts`, import `inboxQuery` alongside `messagesQuery` and chain one more route onto the app. It takes no body, because its only parameter comes from the verified token:

```ts filename="backend/server.ts"
  .post("/api/v1/inbox/live", async (c) => {
    const user = await requireUser(c)

    const sealedQuery = await realtime.seal({ query: inboxQuery(user.id) })

    return c.json(sealedQuery)
  })
```

### Create the collection

On the frontend, add `fetchSealedInbox()` to `frontend/api.ts`, next to `fetchSealedMessages()`. As before, the `as` restores the row type:

```ts filename="frontend/api.ts"
export async function fetchSealedInbox(): Promise<SealedLiveQuery<Message>> {
  const res = await server.api.v1.inbox.live.$post()

  if (!res.ok) {
    throw new Error(`Could not fetch the inbox query (${res.status})`)
  }

  return (await res.json()) as SealedLiveQuery<Message>
}
```

Then create the collection. `realtimeCollectionOptions()` takes the standard TanStack DB collection options plus the Realtime client and a sealed query, and returns options for `createCollection()`:

```ts filename="frontend/collections.ts"
import { createCollection } from "@tanstack/react-db"
import { realtimeCollectionOptions } from "@neon/realtime-tanstack"
import type { SealedLiveQuery } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { fetchSealedInbox } from "./api"
import { client } from "./client"

export function createMessagesCollection(sealedQuery: SealedLiveQuery<Message>) {
  return createCollection(
    realtimeCollectionOptions({
      id: "messages",
      client,
      query: sealedQuery,
      refreshQuery: fetchSealedInbox,
      getKey: (message) => message.id
    })
  )
}

export type MessagesCollection = ReturnType<typeof createMessagesCollection>
```

`getKey` returns each message's primary key. TanStack DB keys rows by it, so use a stable, unique column, never a subscription's `rowId`. `refreshQuery` renews the sealed query the same way [the React hook does](https://neon.com/docs/realtime/guides/reactivity#refreshquery). While renewals fail, the collection stays `ready` with its last rows. See the [`realtimeCollectionOptions()` reference](../sdks/typescript#tanstack-db-realtimecollectionoptions) for the rest of the options.

The collection starts syncing as soon as a live query using it is mounted. It's in the `loading` state until the first result arrives, and `ready` from then on, with each committed transaction applied atomically. A `ready` collection stays ready while the subscription is `connecting` or `stale`, so there's no separate recovery flag to render. If the subscription ends in `error`, so does the collection.

### Query the collection

Create the collection once, when the app starts. The collection takes the client directly, so an app that only uses collections doesn't need `RealtimeProvider`. `Channel` still calls `useLiveQuery()`, though, so keep both views inside `RealtimeProvider`:

```tsx filename="frontend/main.tsx"
import { StrictMode } from "react"
import { createRoot } from "react-dom/client"
import { RealtimeProvider } from "@neon/realtime-react"

import { fetchSealedInbox } from "./api"
import { authClient } from "./auth"
import { Channel } from "./Channel"
import { client } from "./client"
import { createMessagesCollection } from "./collections"
import { Inbox } from "./Inbox"

const root = createRoot(document.getElementById("root")!)
const { data: session } = await authClient.getSession()

if (!session) {
  root.render(<p>Sign in to see the messages.</p>)
} else {
  const messagesCollection = createMessagesCollection(await fetchSealedInbox())

  root.render(
    <StrictMode>
      <RealtimeProvider client={client}>
        <Channel channelId={2} />
        <Inbox messagesCollection={messagesCollection} channelId={2} />
      </RealtimeProvider>
    </StrictMode>
  )
}
```

Sign-in isn't part of these guides: build the page with [Better Auth UI](https://neon.com/docs/auth/reference/ui-components), as the [running example](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app) does by rendering `<Auth>` on `/auth/*` before it checks the session.

Then read from the collection with TanStack's own `useLiveQuery()`. It shares a name with the Realtime hook, so import it under an alias that won't clash in an app that uses both. This view shows one channel, newest first:

```tsx filename="frontend/Inbox.tsx"
import { eq, useLiveQuery as useCollectionQuery } from "@tanstack/react-db"

import type { MessagesCollection } from "./collections"

interface Props {
  messagesCollection: MessagesCollection;
  channelId: number;
}

export function Inbox({ messagesCollection, channelId }: Props) {
  const { data, isReady, isError } = useCollectionQuery({
    query: (q) =>
      q
        .from({ message: messagesCollection })
        .where(({ message }) => eq(message.channel_id, channelId))
        .orderBy(({ message }) => message.created_at, "desc")
  })

  if (isError) {
    return <p role="alert">Couldn't sync messages</p>
  }

  if (!isReady) {
    return <p>Loading messages</p>
  }

  return (
    <ul>
      {data.map((message) => (
        <li key={message.id}>{message.body}</li>
      ))}
    </ul>
  )
}
```

Pass a different `channelId` and the query re-runs in the browser, against the rows the collection already holds. Local queries only see what the collection holds, so a channel whose messages fall outside the newest 500 shows fewer rows, or none. There's no new sealed query and no round trip to your server, unlike [changing the parameters](https://neon.com/docs/realtime/guides/reactivity#changing-query-parameters) of a `useLiveQuery()` hook. Every view you add, like an unread count or a search across channels, is another local query over the same synced rows.

For server rendering, the [server-side rendering guide](./ssr#with-tanstack-db) seeds a collection on the server and hydrates it in the browser, and the [TanStack example](../examples/tanstack) builds a full app with TanStack Start.

### Manage optimistic state

Once you have a TanStack DB collection defined, you can also use it for local optimistic writes. It's often easier in a complex app to normalize data loading into a collection which can have optimistic state applied to it once, than to have to remember to apply optimistic state to a range of different live query subscriptions.

For writes through the collection, with optimistic state, see the [mutations guide](./mutations#with-tanstack-db-collections).

## Other frameworks

Bindings for other frameworks are coming. Until then, you can use the current implementations as a reference to write your own.

The React binding is a thin layer over the client subscription: `useSyncExternalStore` plus the [`QueryRefreshController`](../sdks/typescript#client-queryrefreshcontroller). Point a coding agent at [its source](https://github.com/neondatabase/neon-pkgs/tree/main/packages/realtime-react) and it can reproduce the binding for other frameworks, such as Solid, Svelte or Vue.

You can also see the [source code for the TanStack DB collection here](https://github.com/neondatabase/neon-pkgs/blob/main/packages/realtime-tanstack/src/collection-options.ts).

--- [Document source](https://neon.com/docs/realtime/guides/ssr.md) ---

> Summary: Server-render pages that use live queries. Read and seal the same query for each request, send both to the browser, render the initial rows straight away and let the first result bring the page live.

# Server-side rendering

Render sealed queries and initial query results on the server.

Last updated: 2026-10-30

[Server-side rendering (SSR)](https://developer.mozilla.org/en-US/docs/Glossary/SSR) lets a page arrive with its rows already in the HTML, then subscribe to ongoing changes as soon as it hydrates.

Realtime supports SSR, including with [Next.js](../examples/nextjs) and [TanStack Start](../examples/tanstack).

## Return the sealed query and initial results

The pattern is to [build the live query](./queries#defining-live-queries) once and then use it twice in the same request:

1. run the query to get the initial results
2. [seal the query](./queries#sealing-queries) so it can be subscribed to safely on the frontend

Running and sealing the query are both `async`, so do them in parallel using `Promise.all`:

```ts filename="backend/messages-page.ts"
import type { SealedLiveQuery } from "@neon/realtime/server"

import { messagesQuery } from "./queries"
import { realtime } from "./realtime"
import type { Message } from "./schema"

export interface MessagesPageData {
  initialData: Message[];
  sealedQuery: SealedLiveQuery<Message>;
}

// Call this per request. The result belongs to one user and is short-lived.
export async function loadMessagesPage(userId: string, channelId: number): Promise<MessagesPageData> {
  const query = messagesQuery(userId, channelId)

  const [initialData, sealedQuery] = await Promise.all([query, realtime.seal({ query })])

  return { initialData, sealedQuery }
}
```

`messagesQuery()` and `realtime` are the ones from [defining queries](./queries#using-a-query-builder-or-orm). Your Server Component or server function calls `loadMessagesPage()` with the user's id from the [verified auth session](./queries#authorization).

## Send both to the browser

Both values are serializable, so they go into the hydration payload with the rest of the page's props or loader data. The framework serializes them into the HTML it sends, and the browser picks them up when it hydrates.

For example with [Next.js](../examples/nextjs), call `loadMessagesPage()` from a Server Component and pass the results to a Client Component as props. `auth` is the Managed Better Auth server instance in `lib/auth/server.ts`, set up as in the [Managed Better Auth Next.js quick start](https://neon.com/docs/auth/quick-start/nextjs-api-only). The page must render per request, because `auth.getSession()` [reads cookies](https://neon.com/docs/auth/troubleshooting#missing-force-dynamic-on-server-components), so it sets `force-dynamic`. If your app enables `cacheComponents`, remove the `dynamic` export and read the session inside a `<Suspense>` boundary instead.

```tsx filename="app/channels/[channelId]/page.tsx"
import { notFound, redirect } from "next/navigation"

import { loadMessagesPage } from "../../../backend/messages-page"
import { auth } from "../../../lib/auth/server"
import { ChannelMessages } from "./ChannelMessages"

export const dynamic = "force-dynamic"

type Props = {
  params: Promise<{ channelId: string }>
}

export default async function MessagesPage({ params }: Props) {
  const { data: session } = await auth.getSession()

  if (!session?.user) {
    redirect("/auth/sign-in")
  }

  const channelId = Number((await params).channelId)

  if (!Number.isInteger(channelId)) {
    notFound()
  }

  const { initialData, sealedQuery } = await loadMessagesPage(session.user.id, channelId)

  return (
    <ChannelMessages
      key={sealedQuery.queryFingerprint}
      channelId={channelId}
      initialData={initialData}
      sealedQuery={sealedQuery}
    />
  )
}
```

`ChannelMessages` is a Client Component. It builds `refreshQuery`, which [renews the sealed query](https://neon.com/docs/realtime/guides/ssr#renew-from-the-server) through a Route Handler, and renders [`HydratedMessages`](https://neon.com/docs/realtime/guides/ssr#render-the-initial-rows-straight-away):

```tsx filename="app/channels/[channelId]/ChannelMessages.tsx"
"use client"

import { useCallback } from "react"
import type { SealedLiveQuery } from "@neon/realtime/client"

import type { Message } from "../../../backend/schema"
import { HydratedMessages } from "../../../frontend/HydratedMessages"

interface Props {
  channelId: number;
  initialData: Message[];
  sealedQuery: SealedLiveQuery<Message>;
}

export function ChannelMessages({ channelId, initialData, sealedQuery }: Props) {
  // Renewals must be for the same query, so renew with the same channel
  const refreshQuery = useCallback(async () => {
    const res = await fetch(`/api/messages/${channelId}/live`, { method: "POST" })

    if (!res.ok) {
      throw new Error(`Could not fetch the sealed query (${res.status})`)
    }

    return (await res.json()) as SealedLiveQuery<Message>
  }, [channelId])

  return <HydratedMessages sealedQuery={sealedQuery} refreshQuery={refreshQuery} initialData={initialData} />
}
```

The Route Handler takes the user from the session cookie, not from the request, and validates `channelId`, because the browser controls the URL. Then it seals the same `messagesQuery()` as the page:

```ts filename="app/api/messages/[channelId]/live/route.ts"
import { messagesQuery } from "../../../../../backend/queries"
import { realtime } from "../../../../../backend/realtime"
import { auth } from "../../../../../lib/auth/server"

type Context = {
  params: Promise<{ channelId: string }>
}

export async function POST(_request: Request, { params }: Context) {
  const { data: session } = await auth.getSession()

  if (!session?.user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 })
  }

  const channelId = Number((await params).channelId)

  if (!Number.isInteger(channelId)) {
    return Response.json({ error: "channelId must be an integer" }, { status: 400 })
  }

  const sealedQuery = await realtime.seal({ query: messagesQuery(session.user.id, channelId) })

  return Response.json(sealedQuery, { headers: { "Cache-Control": "no-store" } })
}
```

A server re-render, for example from `router.refresh()` or `revalidatePath()`, sends a new object for the same query. `useLiveQuery()` restarts on each new object, which rejects pending `awaitTxId()` calls. So `HydratedMessages` keeps the first sealed query, and renewals go through `refreshQuery`. Callers key it on `queryFingerprint`, so another channel or user remounts it.

Or with [TanStack Start](../examples/tanstack), [create server functions](https://tanstack.com/start/latest/docs/framework/react/guide/server-functions) for the loader and the renewal. During SSR, a route loader needs the session from the request's cookies on the server. The official Managed Better Auth adapter for TanStack Start isn't out yet, so set up the session yourself. `requireUser` reads the cookie during SSR and for calls from the browser:

<details>

<summary>Read the Managed Better Auth session in TanStack Start</summary>

This setup is built on the beta Managed Better Auth server toolkit, `@neon/auth/server`. Swap in the official adapter when it ships.

Create the auth server. It reads and sets the session cookies through TanStack Start's request helpers:

```ts filename="src/backend/auth.ts"
import { createAuthServer, extractNeonAuthCookies } from "@neon/auth/server"
import { getRequest, setCookie } from "@tanstack/react-start/server"

export const authConfig = {
  baseUrl: process.env.NEON_AUTH_BASE_URL!,
  cookieSecret: process.env.NEON_AUTH_COOKIE_SECRET! // 32+ characters
}

export const auth = createAuthServer({
  ...authConfig,
  context: () => {
    const request = getRequest()

    return {
      getCookies: () => extractNeonAuthCookies(request.headers),
      setCookie,
      getHeader: (name) => request.headers.get(name),
      getOrigin: () => request.headers.get("origin") ?? new URL(request.url).origin,
      getFramework: () => "tanstack-start"
    }
  }
})
```

`NEON_AUTH_COOKIE_SECRET` signs the session cookie and must be at least 32 characters. Generate it once:

```bash filename="Terminal"
printf '\nNEON_AUTH_COOKIE_SECRET=%s\n' "$(openssl rand -base64 32)" >> .env.local
```

Mount the Managed Better Auth proxy at `/api/auth`, so the session cookie lives on your app's origin:

```ts filename="src/routes/api/auth/$.ts"
import { handleAuthProxyRequest } from "@neon/auth/server"
import { createFileRoute } from "@tanstack/react-router"

import { authConfig } from "../../../backend/auth"

export const Route = createFileRoute("/api/auth/$")({
  server: {
    handlers: {
      ANY: ({ request, params }) =>
        handleAuthProxyRequest({ request, path: params._splat ?? "", ...authConfig })
    }
  }
})
```

`requireUser` only has a server half. It puts the user's id on `context`, and throws without a session, so it guards your data. `getSessionUser` reads the session without throwing, for route guards:

```ts filename="src/session-middleware.ts"
import { createMiddleware, createServerFn } from "@tanstack/react-start"
import { setResponseHeader } from "@tanstack/react-start/server"

import { auth } from "./backend/auth"

export const requireUser = createMiddleware({ type: "function" }).server(async ({ next }) => {
  const { data } = await auth.getSession()

  if (!data?.user) {
    throw new Error("Unauthorized")
  }

  return next({ context: { user: { id: data.user.id } } })
})

export const getSessionUser = createServerFn({ method: "GET" }).handler(async () => {
  setResponseHeader("Cache-Control", "private, no-store")
  const { data } = await auth.getSession()

  return data?.user ? { id: data.user.id } : null
})
```

Point the auth client at the proxy. An empty URL makes it use `/api/auth` on the page's origin:

```ts filename="src/frontend/auth.ts"
import { createAuthClient } from "@neon/auth"

export const authClient = createAuthClient("") // same origin: /api/auth
```

</details>

The root route puts the user on the router context for every navigation. During SSR, `getSessionUser` runs in the same process, with the request's cookies. The route's `headers` keep every page out of shared caches:

```tsx filename="src/routes/__root.tsx"
import { createRootRoute } from "@tanstack/react-router"

import { getSessionUser } from "../session-middleware"

export const Route = createRootRoute({
  beforeLoad: async () => ({ user: await getSessionUser() }),
  // Pages carry one user's rows and sealed query, so no shared cache may store them
  headers: () => ({ "Cache-Control": "private, no-store", Vary: "Cookie" })
  // … shell unchanged
})
```

The redirects below go to the sign-in route from the [Managed Better Auth TanStack Router quick start](https://neon.com/docs/auth/quick-start/tanstack-router), `src/routes/auth.$pathname.tsx`.

Both server functions use `requireUser`, so they take the user from the session and only `channelId` from the request. The route's `beforeLoad` sends signed-out visitors to sign-in before the loader runs. The router reuses the component when only `$channelId` changes, so the route keys `HydratedMessages` on the query's fingerprint:

```tsx filename="src/routes/channels.$channelId.tsx"
import { useCallback } from "react"
import { createFileRoute, redirect } from "@tanstack/react-router"
import { createServerFn } from "@tanstack/react-start"

import { loadMessagesPage } from "../backend/messages-page"
import { messagesQuery } from "../backend/queries"
import { realtime } from "../backend/realtime"
import { HydratedMessages } from "../frontend/HydratedMessages"
import { requireUser } from "../session-middleware"

function validateChannel(data: { channelId: number }) {
  if (!Number.isInteger(data.channelId)) {
    throw new Error("channelId must be an integer")
  }

  return data
}

const loadMessages = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator(validateChannel)
  .handler(({ data, context }) => loadMessagesPage(context.user.id, data.channelId))

const sealMessages = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .validator(validateChannel)
  .handler(({ data, context }) =>
    realtime.seal({ query: messagesQuery(context.user.id, data.channelId) })
  )

export const Route = createFileRoute("/channels/$channelId")({
  beforeLoad: ({ context }) => {
    if (!context.user) {
      throw redirect({ to: "/auth/$pathname", params: { pathname: "sign-in" } })
    }
  },
  loader: ({ params }) => loadMessages({ data: { channelId: Number(params.channelId) } }),
  component: MessagesRoute
})

function MessagesRoute() {
  const { channelId } = Route.useParams()
  const { initialData, sealedQuery } = Route.useLoaderData()

  // Renewals must be for the same query, so renew with the same channel
  const refreshQuery = useCallback(
    () => sealMessages({ data: { channelId: Number(channelId) } }),
    [channelId]
  )

  return (
    <HydratedMessages
      key={sealedQuery.queryFingerprint}
      initialData={initialData}
      sealedQuery={sealedQuery}
      refreshQuery={refreshQuery}
    />
  )
}
```

**Important: The sealed query is in your HTML**

Anyone with the page source holds the sealed query until it expires, because [sealed queries are bearer tokens](./queries#sealing-queries). Serve the page over HTTPS, keep it out of shared caches, and keep the sealed query out of URLs and logs.

## Render the initial rows straight away

Pass the initial rows to [`useLiveQuery()`](./reactivity) as `initialData`. The hook renders them immediately with the status `connecting`. When the subscription's first result arrives, it replaces them atomically and the status becomes `live`. Any change committed between the server read and the subscription is in that result, so nothing falls into the gap.

The initial rows are real rows. Render them as you would live ones, without a spinner or a loading state, while the status is `connecting`. `HydratedMessages` shows the server's rows straight away and swaps in the live rows when the first result arrives:

```tsx filename="frontend/HydratedMessages.tsx"
"use client"

import { useState } from "react"
import { useLiveQuery } from "@neon/realtime-react"
import type { SealedLiveQuery } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { LocalTime } from "./LocalTime"

interface HydratedMessagesProps {
  sealedQuery: SealedLiveQuery<Message>;
  refreshQuery: () => Promise<SealedLiveQuery<Message>>;
  initialData: Message[];
}

export function HydratedMessages({ sealedQuery, refreshQuery, initialData }: HydratedMessagesProps) {
  const [query] = useState(sealedQuery) // renewals go through refreshQuery
  const { data, error } = useLiveQuery(query, { refreshQuery, initialData })

  return (
    <>
      {error && <p role="alert">{error.message}</p>}
      <ul>
        {(data ?? initialData).map((message) => (
          <li key={message.id}>
            <LocalTime date={message.created_at} />
            <p>{message.body}</p>
          </li>
        ))}
      </ul>
    </>
  )
}
```

The component takes `refreshQuery` as a prop, so it works with whichever renewal path your framework uses. [Renew from the server](https://neon.com/docs/realtime/guides/ssr#renew-from-the-server) covers the options. The [reactivity guide](./reactivity#uselivequery) covers the hook itself and defines `LocalTime`.

## Open the connection in the browser

The server render doesn't open a WebSocket. On the server, the hook renders from its initial rows and never subscribes. In the browser, it renders the same rows while React hydrates, so the HTML matches, and subscribes once hydration is done.

So create the client once, inside the React tree, in a `useState` initializer. It runs once per mounted app, and the client it creates during the server render never connects, because nothing subscribes there:

**Next.js**

```tsx filename="frontend/RealtimeRoot.tsx"
"use client"

import { useState, type ReactNode } from "react"
import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"
import { RealtimeProvider } from "@neon/realtime-react"

export function RealtimeRoot({ children }: { children: ReactNode }) {
  const [client] = useState(() =>
    createRealtimeClient({
      url: process.env.NEXT_PUBLIC_NEON_REALTIME_URL!,
      parsers: { ...drizzleParsers }
    })
  )

  return <RealtimeProvider client={client}>{children}</RealtimeProvider>
}
```

**TanStack Start**

```tsx filename="frontend/RealtimeRoot.tsx"
"use client"

import { useState, type ReactNode } from "react"
import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"
import { RealtimeProvider } from "@neon/realtime-react"

export function RealtimeRoot({ children }: { children: ReactNode }) {
  const [client] = useState(() =>
    createRealtimeClient({
      url: import.meta.env.VITE_NEON_REALTIME_URL,
      parsers: { ...drizzleParsers }
    })
  )

  return <RealtimeProvider client={client}>{children}</RealtimeProvider>
}
```

With Next.js, add the browser's copy of the Realtime URL. Next.js expands `$VAR` in env files, so it follows `neon env pull`:

```bash filename="Terminal"
echo 'NEXT_PUBLIC_NEON_REALTIME_URL=$NEON_REALTIME_URL' >> .env.local
```

With TanStack Start, use the `VITE_NEON_REALTIME_URL` line from the [setup](./queries#setup).

The [subscribing guide](./subscribing#subscribe-to-the-sealed-query) creates the client at module level in `frontend/client.ts`, which suits a single-page app. In a server-rendered app, create it inside the React tree instead, which keeps browser-only setup out of module scope. Keep the client stable, too. `useLiveQuery()` subscribes per client and sealed query, so a new client on every render means a new subscription on every render.

Render `RealtimeRoot` around everything that calls `useLiveQuery()`, for example in your root layout. `RealtimeRoot`, `ChannelMessages` and `HydratedMessages` start with `"use client"` so that Next.js renders them as Client Components. TanStack Start ignores the directive.

## Keep row shapes identical

The initial rows and the live rows have to have the same shape. If they don't, the page renders one shape until the first result and another after it.

In the running example, `created_at` is a `Date` on both sides: Drizzle reads `timestamptz` columns as `Date` objects, and so does the Realtime client. The Realtime clients on this page spread `drizzleParsers`, so the live rows match Drizzle's types for other columns too. The [subscribing guide](./subscribing#subscribe-to-the-sealed-query) explains what the parsers change. The hydration payload has to keep it that way. React Server Component props and TanStack Start's serializer both preserve `Date` values. Plain `JSON.stringify` turns them into strings, so if your payload goes through it, revive the dates in the browser or keep your row types JSON-safe.

Watch numeric types too: `int8` and `numeric` columns [arrive as strings](./subscribing#subscribe-to-the-sealed-query) on the live side, so read them as strings on the server.

Formatted output has to match too, so format dates and numbers for the user's locale after hydration, as `LocalTime` in the reactivity guide does.

## Renew from the server

The sealed query in the payload expires, so pass `refreshQuery`, and the hook renews the sealed query with the same timing as in the [reactivity guide](./reactivity#refreshquery). If the page hydrates late, for example in a tab restored after a few minutes, the sealed query may already have expired, and the hook renews it straight away.

The renewal runs in the browser, so it goes through something that authenticates the user, like the Route Handler or server function above. It has to seal the same query with the same parameters, because a different fingerprint is rejected. Building both from `messagesQuery()` keeps them in step.

## When the session changes

A page can outlive its session. The user signs out in another tab, or another tab signs in as someone else, and the page still holds the first user's sealed query and rows.

Stop renewing once a renewal fails as signed out, and leave the page. The hook retries a failed renewal every second without limit, and once the sealed query expires the status stays `stale`.

Check on every renewal and write that the session's user is the one the page was loaded for. Have the page send its user id, and treat a mismatch as signed out, with the same 401 as no session. Otherwise a write from the old page lands in the new user's account.

Leave with a full page load. It drops the previous user's Realtime client, collections and optimistic rows. Then the page's redirect sends a signed-out visitor to sign-in, and a different user gets their own rows. With Next.js, pass `session.user.id` to `ChannelMessages` as `userId`, and have the Route Handler return its 401 when the body's `userId` isn't `session.user.id`:

```tsx filename="app/channels/[channelId]/ChannelMessages.tsx"
// A full page load resets this
let signedOut = false

export function ChannelMessages({ channelId, userId, initialData, sealedQuery }: Props) {
  const refreshQuery = useCallback(async () => {
    if (signedOut) {
      throw new Error("Signed out")
    }

    // The page's user, so the Route Handler can refuse anyone else's session
    const res = await fetch(`/api/messages/${channelId}/live`, {
      method: "POST",
      body: JSON.stringify({ userId })
    })

    if (res.status === 401) {
      signedOut = true // the hook retries every second, so stop calling the server
      window.location.reload()
      throw new Error("Signed out")
    }

    // … check res.ok and return the sealed query, as above
  }, [channelId, userId])

  // … render HydratedMessages, as above
}
```

With TanStack Start, have the server functions also take a `userId`, and make `requireUser` throw when it isn't the session's user. Leave the same way when a write fails as signed out.

Make sign-in and sign-out full page loads too. With the Managed Better Auth UI components, have the provider's `onSessionChange` call `window.location.assign("/")` and return a promise that never settles, so the components don't also navigate in the client.

## With TanStack DB

With [TanStack DB](./reactivity#tanstack-db), the collection carries the initial rows instead of the hook's `initialData`:

1. a route loader reads and seals the inbox and seeds the collection in the router's `DbClient`
2. `routerWithDbClient()` carries the seeded rows to the browser
3. the collection subscribes in the browser, and the first result takes over from the seeded rows

The code below does this with TanStack Start. It syncs the inbox from the [reactivity guide](./reactivity#seal-a-broader-query) into one collection and shows one channel from it. As well as the packages from that guide, it uses TanStack's router integration:

```bash filename="Terminal"
npm install @tanstack/react-router-with-db
```

### Create a `DbClient` per router

TanStack Start calls `getRouter()` once per request on the server and once per page load in the browser, so a `DbClient` created with the router belongs to one request or one page load. Create the Realtime client next to it and pass it to the `DbClient` as a dependency, so collections can read it. The server-side Realtime client never connects, because nothing subscribes there. `routerWithDbClient()` wraps the app in `DbProvider`, snapshots the collections that loaders seeded on the server into the HTML, and restores them in the browser before the first render:

```tsx filename="src/router.tsx"
import { DbClient } from "@tanstack/react-db"
import { createRouter } from "@tanstack/react-router"
import { routerWithDbClient } from "@tanstack/react-router-with-db"
import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"

import { routeTree } from "./routeTree.gen"

export function getRouter() {
  // Collections read it with db.requireDependency("realtime"). Nothing subscribes on the server, so it never connects there
  const realtime = createRealtimeClient({
    url: import.meta.env.VITE_NEON_REALTIME_URL,
    parsers: { ...drizzleParsers }
  })
  const dbClient = new DbClient({ realtime })
  const router = createRouter({ routeTree, context: { dbClient } })

  return routerWithDbClient(router, dbClient)
}
```

`routerWithDbClient()` requires `dbClient` in the router's context type, so create the root route from [Send both to the browser](https://neon.com/docs/realtime/guides/ssr#send-both-to-the-browser) with `createRootRouteWithContext<{ dbClient: DbClient }>()` instead of `createRootRoute()`, and keep its `beforeLoad` and `headers`. If the app also uses `useLiveQuery()` from `@neon/realtime-react`, pass the same Realtime client to `RealtimeProvider`. Get it with `useDbClient().requireDependency<RealtimeClient>("realtime")`.

### Define the collection

Define the collection as a descriptor with the two-argument `collectionOptions(id, factory)` around [`realtimeCollectionOptions()`](../sdks/typescript#tanstack-db-realtimecollectionoptions), and give it a stable id. Each `DbClient` runs the factory once, to create its own instance of the collection. Unlike `createMessagesCollection()` in the reactivity guide, it doesn't take a Realtime client: the factory reads the one from its `DbClient`. The descriptor is cheap to build, so the loader and the channel page each build it, and the id resolves both to the same collection:

```ts filename="src/collections.ts"
import { collectionOptions } from "@tanstack/react-db"
import { realtimeCollectionOptions } from "@neon/realtime-tanstack"
import type { RealtimeClient, SealedLiveQuery } from "@neon/realtime/client"

import type { Message } from "./backend/schema"
import { sealInbox } from "./server-functions"

export function messagesCollection(sealedQuery: SealedLiveQuery<Message>) {
  return collectionOptions("messages", (db) =>
    realtimeCollectionOptions({
      id: "messages",
      client: db.requireDependency<RealtimeClient>("realtime"),
      query: sealedQuery,
      refreshQuery: () => sealInbox(),
      getKey: (message) => message.id,
      gcTime: 0 // never collect it while the page is open: a rebuilt collection would reuse an expired sealed query
    })
  )
}
```

`refreshQuery` calls a server function that seals the same `inboxQuery()` for the user in the session:

```ts filename="src/server-functions.ts"
import { createServerFn } from "@tanstack/react-start"

import { inboxQuery } from "./backend/queries"
import { realtime } from "./backend/realtime"
import { requireUser } from "./session-middleware"

export const sealInbox = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .handler(({ context }) => realtime.seal({ query: inboxQuery(context.user.id) }))
```

### Seed the collection in a loader

A layout route, `src/routes/channels.tsx`, loads the inbox for every channel page. Its loader calls a server function that reads and seals the inbox. Then it seeds the collection in the router's `DbClient`, passing the rows to `dbClient.collection()` as `initialData`, which is TanStack DB's option for seeding a collection in one `DbClient`. It returns only the sealed query. Its `beforeLoad` sends signed-out visitors to sign-in, so the channel pages, which render in its outlet, don't need to:

```tsx filename="src/routes/channels.tsx"
import { createFileRoute, redirect } from "@tanstack/react-router"
import { createServerFn } from "@tanstack/react-start"

import { inboxQuery } from "../backend/queries"
import { realtime } from "../backend/realtime"
import { messagesCollection } from "../collections"
import { requireUser } from "../session-middleware"

const loadInbox = createServerFn({ method: "POST" })
  .middleware([requireUser])
  .handler(async ({ context }) => {
    const query = inboxQuery(context.user.id)
    const [initialData, sealedQuery] = await Promise.all([query, realtime.seal({ query })])

    return { initialData, sealedQuery }
  })

export const Route = createFileRoute("/channels")({
  staleTime: Infinity,
  beforeLoad: ({ context }) => {
    if (!context.user) {
      throw redirect({ to: "/auth/$pathname", params: { pathname: "sign-in" } })
    }
  },
  loader: async ({ context }) => {
    const { initialData, sealedQuery } = await loadInbox()
    context.dbClient.collection(messagesCollection(sealedQuery), { initialData }) // a no-op if it already exists

    return { sealedQuery }
  }
})
```

The layout's loader runs once, because `staleTime: Infinity` keeps its data fresh, so switching channels makes no server round trip. On the first load, the loader and the channel page both run on the server, so the HTML has the rows. If the loader runs again in the browser, the collection already exists, so seeding it again does nothing and the live rows stay.

One collection id is enough, because each `DbClient` belongs to one request or one page load, and the [full page load when the session changes](https://neon.com/docs/realtime/guides/ssr#when-the-session-changes) drops it.

The channel route builds the same descriptor from the layout's sealed query, so it gets the collection the loader seeded. It queries the collection with TanStack's `useLiveQuery()`, under the same alias as in the reactivity guide:

```tsx filename="src/routes/channels.$channelId.tsx"
import { eq, useLiveQuery as useCollectionQuery } from "@tanstack/react-db"
import { createFileRoute, getRouteApi } from "@tanstack/react-router"

import { messagesCollection } from "../collections"

const channels = getRouteApi("/channels")

export const Route = createFileRoute("/channels/$channelId")({
  component: ChannelRoute
})

function ChannelRoute() {
  const { channelId } = Route.useParams()
  const messages = messagesCollection(channels.useLoaderData().sealedQuery) // same id, so the seeded collection

  const { data, isError } = useCollectionQuery({
    query: (q) =>
      q
        .from({ message: messages })
        .where(({ message }) => eq(message.channel_id, Number(channelId)))
        .orderBy(({ message }) => message.created_at, "desc")
  })

  if (isError) {
    return <p role="alert">Couldn't sync messages</p>
  }

  return (
    <ul>
      {data.map((message) => (
        <li key={message.id}>{message.body}</li>
      ))}
    </ul>
  )
}
```

Render `data` straight away, without waiting for `isReady`. The seeded rows are there for the first render, but the collection only becomes ready when the first result arrives.

## Keep secrets on the server

In a server-rendered app, server and browser code live side by side, so it's easy to import a module on the wrong side. Import `backend/realtime.ts` and `backend/db.ts` only from server code: Server Components, server functions and TanStack Start server function handlers. A TanStack Start route loader also runs in the browser on client-side navigation, so it has to call a server function rather than import `backend/` modules.

Mark those modules as server-only, so a client import fails the build. In Next.js, add `import "server-only"` to `backend/realtime.ts` and `backend/db.ts`. In TanStack Start, add `import "@tanstack/react-start/server-only"` to them, or name the files `*.server.ts`. The queries guide explains why you [keep your Realtime secret on the server](./queries#sealing-queries).

## Examples

The examples put these principles into framework code. The Next.js example splits the page into a Server Component that reads and seals and a Client Component that subscribes. Instead of `force-dynamic`, it calls `connection()` in that Server Component and renders it inside `<Suspense>`, so the rest of the page renders at once and the list streams in. The TanStack example seeds the router's TanStack DB client in a route loader.

- [Next.js](https://neon.com/docs/realtime/examples/nextjs): Read and seal in a Server Component, then subscribe in a Client Component.
- [TanStack](https://neon.com/docs/realtime/examples/tanstack): Seed the router's TanStack DB client in a route loader.

--- [Document source](https://neon.com/docs/realtime/guides/subscribing.md) ---

> Summary: Subscribe to live queries from trusted backend code or the browser. Fetch sealed queries from your API, handle every callback and renew sealed queries before they expire.

# Subscribing to queries

Subscribe to live queries using the Realtime client.

Last updated: 2026-10-30

Once you've [defined](./queries) and [sealed](./queries#sealing-queries) a query, you can [subscribe to it](https://neon.com/docs/realtime/guides/subscribing#subscribe-to-the-sealed-query) using the [low‑level Realtime client](../sdks/typescript#client-createrealtimeclient).

**Important: Client-side reactivity**

Manual subscriptions are a relatively low-level API. Most apps and agents can use the [higher‑level reactivity primitives](./reactivity) that manage the subscription for you.

## Getting the query to subscribe to

Workers, trusted agents and other backend processes can [subscribe to a query directly](https://neon.com/docs/realtime/guides/subscribing#subscribe-in-trusted-backend-code).

However, to subscribe to a live query in an untrusted environment, you'll need to [expose a sealed query from your backend](./queries#exposing-queries), either a [standard API endpoint](https://neon.com/docs/realtime/guides/subscribing#fetch-from-an-api-endpoint) or [using a server function](https://neon.com/docs/realtime/guides/subscribing#fetch-from-a-server-function) (where [SSR](./ssr) can embed the sealed query and the initial results).

**Tip: Running example**

The guide continues the [running example](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app) introduced in the [Defining queries](./queries#setup) guide.

### Subscribe in trusted backend code

Add a `url` to [`createRealtime()`](../sdks/typescript#backend-createrealtime) and it returns a direct server, which seals queries with your secret and subscribes to them itself.

```ts filename="backend/worker.ts" {11,19,20,22}
import { createRealtime } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

import { messagesQuery } from "./queries"

// The worker acts for one known user, so its parameters are trusted constants
const SUPPORT_BOT_ID = "support-bot"
const SUPPORT_CHANNEL_ID = 2

const realtime = createRealtime({
  url: process.env.NEON_REALTIME_URL!,
  secret: process.env.NEON_REALTIME_SECRET!,
  db: "neondb",
  adapter: drizzleAdapter()
})

const query = messagesQuery(SUPPORT_BOT_ID, SUPPORT_CHANNEL_ID)

const subscription = await realtime.subscribe(query)
subscription.onChange(console.log)

process.once("SIGTERM", () => realtime.close())
```

**Warning: Untrusted parameters**

Never fill a direct subscription's parameters from untrusted input.

`NEON_REALTIME_URL` is written by `neon env pull --service realtime`, or shown on the [Realtime page](../quickstart#enable-realtime) in the Neon Console. Note the `await`: the direct server's `subscribe()` is async, because it seals the query locally before it subscribes. The browser client's `subscribe()` is synchronous. Otherwise it's the same subscription, with the same options and [callbacks](https://neon.com/docs/realtime/guides/subscribing#listen-for-changes) as the client's.

The direct server renews its own sealed queries and recovers from outages until you close the subscription or it moves to `error`. An error is final, so a long-running worker should watch for it with `onStateChange` and subscribe again. `realtime.close()` closes every subscription and the shared WebSocket. The direct server opens its WebSocket with the `ws` package, which you installed in [setup](./queries#setup), even on Node.js 22 and later.

Use direct subscriptions for workers, trusted agents and server-side fan-out.

### Fetch from an API endpoint

Most queries depend on who's asking and what they're asking for.

If you've [exposed your sealed query via an API endpoint](./queries#exposing-an-endpoint), you can provide this context via the request data using your standard auth machinery, such as Neon's [Managed Better Auth](https://neon.com/docs/auth/overview):

```ts filename="frontend/auth.ts"
import { createAuthClient } from "@neon/auth"

export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL)
```

In our [running example](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app), we create a typed client for the API with Hono's `hc`. It takes its routes from `AppType`, so every call is checked against the backend:

```ts filename="frontend/api.ts"
import type { SealedLiveQuery } from "@neon/realtime/client"
import { hc } from "hono/client"

import type { Message } from "../backend/schema"
import type { AppType } from "../backend/server"
import { authClient } from "./auth"

export const server = hc<AppType>(window.location.origin, {
  headers: async (): Promise<Record<string, string>> => {
    const { data } = await authClient.getSession()
    const token = data?.session.token

    return token ? { Authorization: `Bearer ${token}` } : {}
  }
})

export async function fetchSealedMessages(channelId: number): Promise<SealedLiveQuery<Message>> {
  const res = await server.api.v1.messages.live.$post({ json: { channelId } })

  if (!res.ok) {
    throw new Error(`Could not fetch the sealed query (${res.status})`)
  }

  return (await res.json()) as SealedLiveQuery<Message>
}
```

Hono's client types the response body as JSON, so the `Date` in `created_at` shows up as a `string`. The `as` restores the row type that the Realtime client decodes at runtime.

`getSession()` returns the cached session until its JWT is about to expire, then fetches a new one, so each request carries a valid token. Managed Better Auth tokens only last about 15 minutes. Without a session there's no token, so the API answers 401.

`window.location.origin` assumes your dev server proxies `/api` to the API, as the [example's Vite config](https://github.com/neondatabase/examples/tree/main/realtime/guides-chat-app/vite.config.ts) does.

### Fetch from a server function

If your framework supports [server functions](https://react.dev/reference/rsc/server-functions), you can expose the sealed query from one instead of an API endpoint. Client code calls a server function like a local async function, so it can take the place of `fetchSealedMessages()` [above](https://neon.com/docs/realtime/guides/subscribing#fetch-from-an-api-endpoint). With [SSR](./ssr), the page can also embed the sealed query and the initial query results on the server.

Server functions run on your app's origin, so they read the session from its cookie. See [Exposing queries](./queries#exposing-queries), [Using server functions](./queries#using-server-functions), the [Server-side rendering](./ssr) guide and the [TanStack](../examples/tanstack) example for more details.

**Important: Next.js uses Route Handlers**

In Next.js, server functions are server actions, which run one at a time, so renew through a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) instead, as the [Next.js](../examples/nextjs) example shows.

## Subscribe to the sealed query

Create one client for the whole app, because every subscription shares its connection:

```ts filename="frontend/client.ts"
import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"

export const client = createRealtimeClient({
  url: import.meta.env.VITE_NEON_REALTIME_URL,
  parsers: { ...drizzleParsers }
})
```

The client opens its WebSocket lazily, on the first subscription, and multiplexes every subscription over that one connection. The first sealed query binds the connection to its database, so every subscription on a client must target the same `db`. The connection carries no user identity. Each subscription brings its own sealed query.

Now fetch the sealed query, subscribe to it and render every change:

```ts filename="frontend/app.ts"
import type { LiveQuerySnapshot, LiveQueryState } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { fetchSealedMessages } from "./api"
import { client } from "./client"

const list = document.querySelector<HTMLUListElement>("#messages")!
const statusLine = document.querySelector<HTMLParagraphElement>("#status")!

// A real app takes the channel from its router
const channelId = 2

const sealedQuery = await fetchSealedMessages(channelId)
const subscription = client.subscribe(sealedQuery)

subscription.onChange(render)

window.addEventListener("beforeunload", () => {
  subscription.unsubscribe()
  client.close()
})

function render(snapshot: LiveQuerySnapshot<Message>) {
  statusLine.textContent = describe(snapshot)
  list.replaceChildren(...(snapshot.data ?? []).map(renderMessage))
}

function describe(state: LiveQueryState): string {
  switch (state.status) {
    case "connecting":
      return "Loading messages"
    case "live":
      return "Up to date"
    case "stale":
      return "Updating. Messages may be out of date."
    case "error":
      return `Stopped: ${state.error.message}`
    case "closed":
      return "Closed"
  }
}

function renderMessage(message: Message): HTMLLIElement {
  const item = document.createElement("li")

  item.textContent = `${message.created_at.toLocaleTimeString()} ${message.body}`

  return item
}
```

`subscribe()` returns a materialized subscription, which keeps the current rows for you. `onChange` gets a snapshot of the rows and the subscription's state whenever either changes, so the render reads `data`, `status` and `error` from one consistent value. `data` is `undefined` until the first result arrives.

Rows arrive decoded, so `created_at` is a `Date`, as Drizzle's `Message` type says. The client's default parsers decode these Postgres types:

| Postgres type                              | Arrives as                           |
| ------------------------------------------ | ------------------------------------ |
| `bool`                                     | `boolean`                            |
| `int2`, `int4`, `oid`, `float4`, `float8`  | `number`                             |
| `json`, `jsonb`                            | The parsed JSON value                |
| `timestamptz`                              | `Date`                               |
| `timestamp`                                | `Date` in local time                 |
| `date`                                     | `Date` at local midnight             |
| `bytea`                                    | `Uint8Array`                         |
| `int8`, `numeric`                          | `string`, so their values stay exact |
| Everything else, such as `text` and `uuid` | `string`, as Postgres formats it     |

`NULL` arrives as `null`, and arrays of built-in types decode element by element.

The client above spreads `drizzleParsers`, so rows match Drizzle's types: `date` stays a string and `timestamp` is read as UTC.

When you're done with a subscription, call `unsubscribe()`. It moves the subscription to `closed`, so any listeners get a final `closed` update, and then stops all further callbacks. `client.close()` does the same for every subscription on the client, and closes the WebSocket.

## Listen for changes

A subscription has three callbacks. Each one takes a listener and returns a function that removes it:

| Callback        | Listener arguments                 | Fires                                                                                                                                                                                                                                                                                                                            |
| --------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onChange`      | `snapshot: LiveQuerySnapshot<Row>` | After each state change, after each `changes` update while `live`, and when a new result is complete. Materialized subscriptions only.                                                                                                                                                                                           |
| `onStateChange` | `state: LiveQueryState`            | When the status changes.                                                                                                                                                                                                                                                                                                         |
| `onUpdate`      | `update: RawLiveQueryUpdate<Row>`  | With `type: "rows"` and `rows`, each `{ rowId, row }`, when a complete, authoritative result replaces the previous one. With `type: "changes"`, `changes` and `batch: LiveQueryBatchInfo` when committed transactions change the result. Each change is an `upsert` with a `rowId` and `row`, or a `remove` with only a `rowId`. |

Listeners run in the order you add them, and one that throws doesn't stop the others. Each initial result and each committed transaction becomes visible atomically. Outside a listener, `getSnapshot()` and `getState()` return the current values.

The status tells you how far to trust the rows:

| Status       | Meaning                                                                                                                                                                                      |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connecting` | Waiting for a result: when it starts, including with `initialData` from a [server render](./ssr), after a reconnect, and after renewing an expired sealed query. Rows you already have stay. |
| `live`       | The rows are authoritative and changes are streaming. It stays `live` while the server replaces the whole result.                                                                            |
| `stale`      | The sealed query expired and the subscription is waiting for a renewed one. The rows are usable but may be out of date. Render them normally.                                                |
| `error`      | Automatic recovery has stopped. See [handle errors](https://neon.com/docs/realtime/guides/subscribing#handle-errors).                                                                        |
| `closed`     | Closed by `unsubscribe()` or `client.close()`. It doesn't reopen.                                                                                                                            |

By default, subscriptions are materialized. The client keeps the rows and applies each update before `onUpdate` fires, so `getSnapshot()` in an update listener already includes it. If your code keeps its own rows, as TanStack DB does, pass `{ materialize: false }` for a raw subscription. It has the same callbacks except `onChange`, and no `getSnapshot()`. Keep the rows in a map keyed by `rowId`, replace them on each `rows` update and apply each `changes` update's upserts and removes:

```ts filename="frontend/raw-messages.ts"
import type { LiveQueryState, RawLiveQueryUpdate } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { fetchSealedMessages } from "./api"
import { client } from "./client"

const channelId = 2

// Keyed by rowId, which is only valid until the next `rows` update
const rows = new Map<string, Message>()

const subscription = client.subscribe(await fetchSealedMessages(channelId), { materialize: false })

subscription.onUpdate((update: RawLiveQueryUpdate<Message>) => {
  if (update.type === "rows") {
    rows.clear()
    for (const { rowId, row } of update.rows) {
      rows.set(rowId, row)
    }
    return
  }

  for (const change of update.changes) {
    if (change.type === "upsert") {
      rows.set(change.rowId, change.row)
    } else {
      rows.delete(change.rowId)
    }
  }

  console.log(`${rows.size} messages after transactions ${update.batch.txids.join(", ")}`)
})

subscription.onStateChange((state: LiveQueryState) => {
  console.log(state.status, state.error?.message ?? "")
})
```

A `rowId` is opaque and scoped to its subscription, and each `rows` update invalidates every earlier one. It isn't a primary key, so don't store it or match it against your own ids. A `rows` update can arrive at any time, for example after a reconnect, and it always replaces the whole result.

Each `changes` update also carries the ids of the Postgres transactions it covers, in `update.batch.txids`. The [mutations guide](./mutations) uses them to confirm optimistic mutations.

## Renew the sealed query

Sealed queries are [short-lived](./queries#renewing-sealed-queries), so a subscription that outlives its sealed query needs a fresh one. Fetch a replacement before `expiresAt` and pass it to `renew()`. This scheduler renews 10 seconds before expiry, retries a failed fetch after 1 second, reschedules from each new `expiresAt` and stops if `renew()` fails:

```ts filename="frontend/renewal.ts"
import type { RawLiveQuerySubscription, SealedLiveQuery } from "@neon/realtime/client"

// The same timing the React and TanStack DB bindings use
const RENEW_EARLY_MS = 10_000
const RETRY_MS = 1_000

export function renewBeforeExpiry<Row>(
  subscription: RawLiveQuerySubscription<Row>,
  sealedQuery: SealedLiveQuery<Row>,
  fetchSealedQuery: () => Promise<SealedLiveQuery<Row>>
): () => void {
  let timer: ReturnType<typeof setTimeout> | undefined
  let stopped = false

  function schedule(delay: number) {
    clearTimeout(timer)

    if (!stopped) {
      timer = setTimeout(renew, delay)
    }
  }

  function scheduleBeforeExpiry(expiresAt: number) {
    schedule(Math.max(0, expiresAt - Date.now() - RENEW_EARLY_MS))
  }

  async function renew() {
    let next: SealedLiveQuery<Row>

    try {
      next = await fetchSealedQuery()
    } catch {
      schedule(RETRY_MS)
      return
    }

    scheduleBeforeExpiry(next.expiresAt)

    // A rejected renewal means the subscription is in `error` or the query changed
    subscription.renew(next).catch(stop)
  }

  function stop() {
    stopped = true
    clearTimeout(timer)
  }

  scheduleBeforeExpiry(sealedQuery.expiresAt)

  return stop
}
```

Start it after subscribing, with a function that fetches the same query again, and stop it when you unsubscribe:

```ts filename="frontend/app.ts" {6,16,21}
import type { LiveQuerySnapshot, LiveQueryState } from "@neon/realtime/client"

import type { Message } from "../backend/schema"
import { fetchSealedMessages } from "./api"
import { client } from "./client"
import { renewBeforeExpiry } from "./renewal"

const list = document.querySelector<HTMLUListElement>("#messages")!
const statusLine = document.querySelector<HTMLParagraphElement>("#status")!

// A real app takes the channel from its router
const channelId = 2

const sealedQuery = await fetchSealedMessages(channelId)
const subscription = client.subscribe(sealedQuery)
const stopRenewing = renewBeforeExpiry(subscription, sealedQuery, () => fetchSealedMessages(channelId))

subscription.onChange(render)

window.addEventListener("beforeunload", () => {
  stopRenewing()
  subscription.unsubscribe()
  client.close()
})

function render(snapshot: LiveQuerySnapshot<Message>) {
  statusLine.textContent = describe(snapshot)
  list.replaceChildren(...(snapshot.data ?? []).map(renderMessage))
}

function describe(state: LiveQueryState): string {
  switch (state.status) {
    case "connecting":
      return "Loading messages"
    case "live":
      return "Up to date"
    case "stale":
      return "Updating. Messages may be out of date."
    case "error":
      return `Stopped: ${state.error.message}`
    case "closed":
      return "Closed"
  }
}

function renderMessage(message: Message): HTMLLIElement {
  const item = document.createElement("li")

  item.textContent = `${message.created_at.toLocaleTimeString()} ${message.body}`

  return item
}
```

`renew()` replaces the sealed query for the same exact query, and it keeps the subscription object, its listeners and its rows:

- Before expiry, the subscription stays `live`, with no new `rows` update.
- After expiry, for example when a laptop wakes from sleep, the subscription is `stale`. `renew()` moves it to `connecting` while the client subscribes again behind the same object, and to `live` when the new result arrives.

If the replacement's `queryFingerprint` doesn't match, the promise that `renew()` returns rejects. A changed parameter, like a different channel, makes a different query, so subscribe to the new one and unsubscribe from the old.

You don't write this yourself when you use the bindings. The [React and TanStack DB bindings](./reactivity) take a `refreshQuery` function and renew with the same timing, 10 seconds before expiry with a 1-second retry. They're built on [`QueryRefreshController`](../sdks/typescript#client-queryrefreshcontroller), which you can use if you're writing a binding for another framework.

## Handle errors

When automatic recovery stops, the subscription moves to `error`, and its `error` is a [`LiveQueryError`](../sdks/typescript#client-livequeryerror) with:

- `code`: a stable, machine-readable error code
- `message`: a description of the failure
- `retryable`: whether reconnecting or a fresh sealed query may recover it
- `sqlState`: the Postgres SQLSTATE code, when [debug mode](https://neon.com/docs/realtime/guides/subscribing#debug-subscriptions) is on and the database supplied one
- `cause`: the underlying error, when there is one

A subscription never leaves `error` by itself, and `renew()` can't bring it back. Unsubscribe, show the error, and subscribe again with a fresh sealed query, for example when the user retries.

Errors stay with their own subscription. A row that fails to decode, for example, puts only its own subscription into `error`, and the others on the client carry on.

If the connection itself fails, for example because of a fatal protocol error, every subscription on the client moves to `error` at once and the client can't reconnect. Create a new client with `createRealtimeClient()` before you subscribe again.

## Debug subscriptions

### Log client diagnostics

The client is silent by default. To see what it's doing, pass a `logLevel` to [`createRealtimeClient()`](../sdks/typescript#client-createrealtimeclient): `"error"`, `"warn"`, `"info"` or `"debug"`. Each level includes the ones before it.

```ts filename="frontend/client.ts" {7}
import { createRealtimeClient } from "@neon/realtime/client"
import { drizzleParsers } from "@neon/realtime-drizzle/client"

export const client = createRealtimeClient({
  url: import.meta.env.VITE_NEON_REALTIME_URL,
  parsers: { ...drizzleParsers },
  logLevel: import.meta.env.DEV ? "debug" : "warn"
})
```

Entries go to the console unless you pass a [`logger`](../sdks/typescript#client-realtimelogger), which receives each [entry](../sdks/typescript#client-realtimelogentry) instead. An entry has a `level`, a `message`, a `timestamp` and a stable `event` name, like `connection_lost` or `subscription_failed`. Match on `event`, not on `message`:

```ts
logger: (entry) => {
  if (entry.event === "subscription_failed") reportError(entry.error)
}
```

Entries never include sealed queries, SQL, parameters or rows. An entry's `error` can hold an error from the server or from your own code, so handle it like any other error you log.

The React and TanStack DB bindings log through the client you give them. A direct server takes the same `logLevel` and `logger` options in `createRealtime({ url })`.

### Show full database errors

By default, subscription errors carry safe, generic messages. To see the database's own error while you develop, set `debugMode` on the server that seals your queries:

```ts filename="backend/realtime.ts" {8}
import { createRealtime } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

export const realtime = createRealtime({
  secret: process.env.NEON_REALTIME_SECRET!,
  db: "neondb",
  adapter: drizzleAdapter(),
  debugMode: process.env.NODE_ENV === "development"
})
```

Every query it seals then reports errors with the database's full message, plus its SQLSTATE code in `sqlState` when there is one. It's a backend option because it travels inside each sealed query.

**Warning: Development only**

Full error details can expose schema, table and column names to anyone who subscribes, including through any error message your UI shows. Never turn on `debugMode` in production.

--- [Document source](https://neon.com/docs/realtime/how-it-works.md) ---

> Summary: How Realtime works and how the layers compose and fit together.

# How it works

Last updated: 2026-10-15

Realtime is a live SQL query and sync engine, with (optional) higher-level reactivity primitives for client-side development.

```go
----------------    ----------------    -------------------    --------------------
|              |    |              |    |                 |    |                  |
|  (1)         |    |  (2)         |    |  (3)            |    |  (4)             |
|  Postgres    |    |  Live SQL    |    |  Lower level    |    |  Higher level    |
|              |---<|  API         |---<|  client SDKs    |---<|  reactive DX     |
|  [ live   ]  |    |              |    |                 |    |                  |
|  [ query  ]  |    |  [ sync   ]  |    |  `seal()`       |    |  `onUpdate`      |
|  [ engine ]  |    |  [ engine ]  |    |  `subscribe()`  |    |  `useLiveQuery`  |
|              |    |              |    |                 |    |                  |
----------------    ----------------    -------------------    --------------------
```

The layers of the system are composable. You can use the Live SQL API directly, consume it with lower-level client SDKs or code using the higher-level reactivity primitives.

## Postgres

[Enabling Realtime](./quickstart#enable-realtime) installs an incremental live query engine inside Lakebase Postgres.

This consumes logical replication, matches write operations to live queries and streams the changes to the Live SQL API.

## Live SQL API

The [Live SQL API](./reference/api) is a WebSocket API. Clients connect via WebSocket and send [live SQL queries](./guides/queries) to subscribe to.

The API validates the queries and sends them on to the live query engine inside Postgres. It then consumes changes from Postgres (over a single, multiplexed connection) and fans the changes back out to clients over their WebSocket connections.

**Warning: Beta: don't use the Live SQL API directly (yet)**

The WebSocket sync protocol is still evolving, so don't develop directly against it yet. Instead, use the clients and reactivity primitives provided, which will track any changes to the protocol for you.

## Lower-level client SDKs

The [TypeScript SDK](./sdks/typescript) allows you to use the Live SQL API by [defining](./guides/queries) and [subscribing](./guides/subscribing) to queries.

Queries are designed to be defined securely in your backend code and subscribed to safely in your frontend. You can define them using [raw SQL](./guides/queries#using-raw-sql):

```ts filename="backend/queries.ts"
import { rawSql } from "@neon/realtime/server"

interface Message {
  id: string;
  body: string;
}

const query = rawSql<Message>(
  "select id, body from messages where author_id = $1",
  [userId]
)
```

Or using your [ORM or query builder](./guides/queries#using-a-query-builder-or-orm), such as [Drizzle](./examples/drizzle) or [Kysely](./examples/kysely):

```ts filename="backend/queries.ts"
import { eq } from "drizzle-orm"

const query =
  db.select()
    .from(messages)
    .where(eq(messages.author_id, userId))
```

Once you've defined queries, you _can_ then subscribe to them [in your backend](./guides/subscribing#subscribe-in-trusted-backend-code):

```ts filename="backend/subscription.ts"
import { createRealtime } from "@neon/realtime/server"

const realtime = createRealtime({
  adapter: drizzleAdapter(),
  secret,
  db: "neondb",
  url: process.env.NEON_REALTIME_URL!
})

const subscription = await realtime.subscribe(query)
subscription.onChange(console.log)
```

However, the _main_ pattern is to [seal the query](./guides/queries#sealing-queries) so that you can safely pass it to an agent or frontend app:

```ts filename="backend/queries.ts"
import { createRealtime, type SealedLiveQuery } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

const secret = process.env.NEON_REALTIME_SECRET!

const realtime = createRealtime({
  adapter: drizzleAdapter(),
  db: "neondb",
  secret
})

async function sealQuery(userId: string): Promise<SealedLiveQuery<Message>> {
  const query =
    db.select()
      .from(messages)
      .where(eq(messages.author_id, userId))

  // Seal the query
  return realtime.seal({ query })
}
```

[Sealing](./guides/queries#sealing-queries) lets a frontend or agent subscribe to a query that your backend defined, without being able to change the query or its parameters, and without ever holding your Realtime secret. All the client holds is the sealed query, an opaque value that it passes to `subscribe()`. Sealed queries are short-lived, so the client [gets a fresh one](./guides/queries#renewing-sealed-queries) from your backend to keep its subscription going. That's what the `refreshQuery` function in the React example below does.

[Expose the query from an API endpoint](./guides/queries#exposing-an-endpoint), so authorization can be enforced and query parameters (like the `userId` in this example) can be filled in from the request context:

```ts filename="backend/server.ts"
import { Hono } from "hono"

const app = new Hono().post(
  "/api/v1/messages/live",
  async (c) => {
    const user = await requireUser(c)
    const sealedQuery = await sealQuery(user.id)

    return c.json(sealedQuery)
  }
)

export type AppType = typeof app
```

Fetch the `sealedQuery` and safely [subscribe to it](./guides/subscribing#subscribe-to-the-sealed-query) in your frontend code:

```ts filename="frontend/app.ts"
import { hc } from "hono/client"
import { createRealtimeClient } from "@neon/realtime/client"
import type { AppType } from "../backend/server"

const server = hc<AppType>(window.location.origin)
const client = createRealtimeClient({ url })

const response = await server.api.v1.messages.live.$post()
const sealedQuery = await response.json()

const subscription = client.subscribe(sealedQuery)
subscription.onChange(console.log)
```

## Higher-level reactive DX

Rather than subscribing manually and wiring the changes into your application state, most apps will use the [higher-level reactivity primitives](./guides/reactivity) that handle this for you.

These bind live query results to component or local application state and allow you to apply [optimistic mutations](./guides/mutations#how-optimistic-mutations-work) with automatic management of optimistic state.

For example, [with a React app](./guides/reactivity#react), you can use [`useLiveQuery`](./guides/reactivity#uselivequery) to bind a live query to your component state and the native [`useOptimistic` hook](./guides/mutations#with-reacts-useoptimistic-hook) to manage optimistic state:

```tsx filename="App.tsx"
import React, { useOptimistic, useTransition } from 'react'

import { useLiveQuery } from "@neon/realtime-react"
import type { SealedLiveQuery } from "@neon/realtime/client"

interface Props {
  sealedQuery: SealedLiveQuery<Message>;
  refreshQuery: () => Promise<SealedLiveQuery<Message>>;
}

export function Messages({ sealedQuery, refreshQuery}: Props) {
  const [ isPending, startTransition ] = useTransition()
  const { data, utils } = useLiveQuery(sealedQuery, { refreshQuery })

  const [ messages, addOptimisticState ] = useOptimistic(
    data ?? [],
    (synced: readonly Message[], { id, changes }: Write) => {
      return synced.map(msg =>
        msg.id === id ? { ...msg, ...changes } : msg
      )
    }
  )

  async function updateMessage(id: string, changes: Partial<Message>) {
    startTransition(async () => {
      addOptimisticState({ id, changes })

      const response = await server.api.v1.messages[":id"].$patch({ param: { id }, json: changes })
      const { txid } = await response.json()

      await utils.awaitTxId(txid)
    })
  }

  return (
    <ul>
      {messages.map((message) => (
        <li key={message.id}>
          <button onClick={ () => updateMessage(message.id, { body: message.body.toUpperCase() }) }>{message.body}</button>
        </li>
      ))}
    </ul>
  )
}
```

See the [reactivity](./guides/reactivity) and [mutations](./guides/mutations) guides and [Next.js](./examples/nextjs) and [TanStack](./examples/tanstack) examples for more on [SSR](./guides/ssr) and more advanced data loading and client-side data management patterns.

## Subscriptions and consistency

A subscription starts with the query's full initial result. After that, changes arrive in batches as transactions commit. Each batch covers one or more committed transactions and is applied all at once, so your rows never show a half-applied write.

A batch carries the IDs of its transactions (txids). [`awaitTxId()`](./guides/mutations#how-optimistic-mutations-work) uses them, along with the server's progress between batches, to know that your write has synced. The subscription reports a [status](./guides/subscribing#listen-for-changes) that you can show in your UI.

## Packages and guides

| Package                         | What it gives you                                       | Guide                                                                                                            |
| ------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `@neon/realtime/server`         | `createRealtime`, `rawSql`, `seal`                      | [Defining queries](./guides/queries)                                                                             |
| `@neon/realtime/client`         | `createRealtimeClient`, `subscribe`, `awaitTxId`        | [Subscribing](./guides/subscribing), [Optimistic mutations](./guides/mutations)                                  |
| `@neon/realtime-drizzle`        | `drizzleAdapter`                                        | [Query builder or ORM](./guides/queries#using-a-query-builder-or-orm), [Drizzle example](./examples/drizzle)     |
| `@neon/realtime-drizzle/client` | `drizzleParsers`                                        | [Drizzle example](./examples/drizzle)                                                                            |
| `@neon/realtime-kysely`         | `kyselyAdapter`                                         | [Query builder or ORM](./guides/queries#using-a-query-builder-or-orm), [Kysely example](./examples/kysely)       |
| `@neon/realtime-react`          | `RealtimeProvider`, `useLiveQuery`, `useRealtimeClient` | [React reactivity](./guides/reactivity#react), [SSR](./guides/ssr)                                               |
| `@neon/realtime-tanstack`       | `realtimeCollectionOptions`                             | [TanStack DB reactivity](./guides/reactivity#tanstack-db), [SSR with TanStack DB](./guides/ssr#with-tanstack-db) |

Start with the [quickstart](./quickstart), then read the guides in this order: [defining queries](./guides/queries), [subscribing](./guides/subscribing), [reactivity](./guides/reactivity), [optimistic mutations](./guides/mutations) and [server-side rendering](./guides/ssr).

--- [Document source](https://neon.com/docs/realtime/overview.md) ---

> Summary: Neon's Realtime makes any SQL query live. Subscribe in realtime to your Lakebase Postgres database. Develop apps and agents with end-to-end reactivity using type-safe live queries and optimistic mutations.

# Neon Realtime

Live queries that update your app's UI the moment your data changes.

Last updated: 2026-10-30

**Note: Beta**

**Realtime** is in beta. Share your feedback on [Discord](https://neon.com/discord) or via the [Neon Console](https://console.neon.tech/app/projects?modal=feedback).

Build apps and agents whose UIs update the moment your data changes. Realtime makes [any SQL query](https://neon.com/docs/realtime/guides/queries) live, so you can [subscribe](https://neon.com/docs/realtime/guides/subscribing) to your [Lakebase Postgres](https://neon.com/docs/postgres/overview) database and get end-to-end, type-safe reactivity with [live queries](https://neon.com/docs/realtime/guides/reactivity) and [optimistic mutations](https://neon.com/docs/realtime/guides/mutations).

[View prompt](https://neon.com/prompts/realtime-landing.md)

## Get started

Starting a new app? Scaffold one from the Realtime template:

```bash filename="Terminal"
npx neon@latest bootstrap my-app --template realtime-react
```

Realtime is available on all Neon plans. To enable it on an existing project, select **Postgres database** > **Realtime** in the Neon Console and click **Enable Realtime**, or run [`neon realtime enable`](https://neon.com/docs/cli/realtime#enable) on a linked project:

```bash filename="Terminal"
neon realtime enable
```

**Important: Before you enable Realtime**

- Your project must be in a [supported region](https://neon.com/docs/realtime/overview#which-regions-is-it-enabled-in).
- Enabling Realtime turns on [logical replication](https://neon.com/docs/guides/logical-replication-neon) for the whole project. This permanently changes `wal_level` to `logical` and suspends every compute in the project, on all branches, which drops active connections. Each compute starts again on its next connection. Disabling Realtime later doesn't turn logical replication off.

To add Realtime to an app by hand, follow the [Quickstart](https://neon.com/docs/realtime/quickstart). To see how the pieces fit together, read [how it works](https://neon.com/docs/realtime/how-it-works).

- [Quickstart](https://neon.com/docs/realtime/quickstart): Fire up Realtime and run your first live queries.
- [How it works](https://neon.com/docs/realtime/how-it-works): Learn how it works and how the layers compose.

See examples of how to build full-stack, reactive apps with [Next.js](https://neon.com/docs/realtime/examples/nextjs) and [TanStack](https://neon.com/docs/realtime/examples/tanstack) and how to [keep users and agents in sync](https://neon.com/docs/realtime/examples/mastra) with Mastra.

- [Next.js](https://neon.com/docs/realtime/examples/nextjs): Build a realtime, reactive app using Next.js with SSR support.
- [TanStack](https://neon.com/docs/realtime/examples/tanstack): Build a realtime, reactive app using TanStack Start and DB.
- [Mastra](https://neon.com/docs/realtime/examples/mastra): Keep users and agents in sync on the same data.

## Realtime live SQL

Realtime offers [arbitrary live SQL](https://neon.com/docs/realtime/guides/queries) with [full reactivity](https://neon.com/docs/realtime/guides/reactivity) on Lakebase Postgres. It allows you to build realtime, reactive apps and agents:

- without using a second or bespoke realtime system
- without changing your schema, queries, ORM or reactivity system
- without contorting your application around the limitations of your sync engine

There is no need to use a different database for realtime sync. You can reuse your existing query code and data loading patterns. This is full reactivity, on standard Postgres, with live SQL that just works.

## Integrated reactive DX

[Define](https://neon.com/docs/realtime/guides/queries) and [subscribe to queries](https://neon.com/docs/realtime/guides/subscribing) directly. Or use the batteries included: [end-to-end, type-safe reactivity](https://neon.com/docs/realtime/guides/reactivity) and [mutation](https://neon.com/docs/realtime/guides/mutations) primitives that integrate into your framework of choice.

In your backend, [define live queries](https://neon.com/docs/realtime/guides/queries) using raw SQL or your ORM of choice (in this case [Drizzle](https://neon.com/docs/realtime/examples/drizzle)):

```ts filename="your-api-server.ts"
import { createRealtime } from "@neon/realtime/server"
import { drizzleAdapter } from "@neon/realtime-drizzle"

const realtime = createRealtime({
  secret: process.env.NEON_REALTIME_SECRET!,
  db: "neondb",
  adapter: drizzleAdapter()
})

// `db` is your Drizzle instance and `messages` is a Drizzle table.
// This can be any SQL query, including joins, aggregates, ordering, etc.
const query = db.select().from(messages)
```

---

[Seal the live queries](https://neon.com/docs/realtime/guides/queries#sealing-queries) to safely [expose them to your frontend](https://neon.com/docs/realtime/guides/queries#exposing-queries):

```ts filename="your-api-server.ts"
const sealedQuery = await realtime.seal({ query })
```

---

Subscribe directly [using a low‑level client](https://neon.com/docs/realtime/guides/subscribing):

```ts filename="client-or-server.ts"
import { createRealtimeClient } from "@neon/realtime/client"

const client = createRealtimeClient({ url: process.env.NEON_REALTIME_URL! })

const subscription = client.subscribe(sealedQuery)
subscription.onChange(console.log)
```

---

Or, in your app, use the [higher-level reactivity primitives](https://neon.com/docs/realtime/guides/reactivity) to bind live queries to your component state:

```tsx filename="App.tsx"
import { useLiveQuery } from "@neon/realtime-react"
import { type SealedLiveQuery } from "@neon/realtime/client"

type Props = {
  sealedQuery: SealedLiveQuery<Message>
  initialData?: Message[]
}

export function Messages({ sealedQuery, initialData }: Props) {
  const { data } = useLiveQuery(sealedQuery, { initialData })

  return (
    <ul>
      {(data ?? []).map((message) => (
        <li key={message.id}>{ ... }</li>
      ))}
    </ul>
  )
}
```

---

Optionally passing in the `initialData` from SSR (e.g.: with [TanStack Start](https://neon.com/docs/realtime/examples/tanstack)):

```tsx filename="routes/messages.tsx"
import { createFileRoute } from "@tanstack/react-router"
import { createServerFn } from "@tanstack/react-start"

const loadMessages = createServerFn({ method: "GET" }).handler(async () => {
  const [initialData, sealedQuery] = await Promise.all([query, realtime.seal({ query })])

  return { initialData, sealedQuery }
})

export const Route = createFileRoute("/messages")({
  loader: () => loadMessages(),
  component: () => <Messages {...Route.useLoaderData()} />,
})
```

---

Or for more [advanced use](https://neon.com/docs/realtime/guides/reactivity#tanstack-db), sync the live query into a [TanStack DB collection](https://tanstack.com/db/latest/docs/overview):

```ts filename="db/collections.ts"
import { createCollection } from "@tanstack/db"
import { realtimeCollectionOptions } from "@neon/realtime-tanstack"

export const messagesCollection = createCollection(
  realtimeCollectionOptions({
    id: "messages",
    client,
    query: sealedQuery,
    ...,
    onUpdate: async ({ transaction, collection }) => {
      const updates = transaction.mutations.map(({ original, changes }) => ({ id: original.id, changes }))
      const { txid } = await api.messages.update(updates)

      await collection.utils.awaitTxId(txid)
    }
  })
)
```

---

Bind that to your components and benefit from instant local writes using [optimistic mutations](https://neon.com/docs/realtime/guides/mutations):

```tsx filename="App.tsx"
import { useLiveQuery } from "@tanstack/react-db"

export function Messages() {
  const { data } = useLiveQuery({
    query: (q) => q.from({ messagesCollection })
  })

  function star(message) {
    messagesCollection.update(message.id, (draft) => {
      draft.starred = true
    })
  }

  return (
    <ul>
      {(data ?? []).map((message) => (
        <li key={message.id} onClick={() => star(message)}>{ ... }</li>
      ))}
    </ul>
  )
}
```

---

That's it. You get [live SQL](https://neon.com/docs/realtime/guides/queries#defining-live-queries) and [end-to-end reactivity](https://neon.com/docs/realtime/guides/reactivity) on standard Postgres. With full type-safety and support for [SSR](https://neon.com/docs/realtime/guides/ssr), [instant local writes](https://neon.com/docs/realtime/guides/mutations), [multi-user, multi-device sync](https://neon.com/docs/realtime/how-it-works) and [local offline persistence](https://tanstack.com/blog/tanstack-db-0.6-app-ready-with-persistence-and-includes).

## Agent skills and MCP

Install the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server). Or [use the CLI](https://neon.com/docs/cli) to install the Realtime skill:

```bash filename="Terminal"
neon skills -s neon-realtime
```

## Frequently asked questions

Answers to frequently asked questions about Realtime:

### What's in the beta and what's not?

Functionally, Realtime already supports:

- arbitrary live SQL (any [read-only, deterministic `SELECT`](https://neon.com/docs/realtime/guides/queries#defining-live-queries))
- [end-to-end, type-safe reactivity](https://neon.com/docs/realtime/guides/reactivity)
- [SSR](https://neon.com/docs/realtime/guides/ssr) and [Managed Better Auth](https://neon.com/docs/realtime/guides/queries#authorization) support
- initial [ORM, query builder](https://neon.com/docs/realtime/guides/queries#using-a-query-builder-or-orm) and [framework integrations](https://neon.com/docs/realtime/guides/reactivity#react)
- support for branching and scale-to-zero

Realtime **does not** yet support:

- billing (Realtime is free to use during the beta)
- RLS (we [aim to support it by GA](https://neon.com/docs/realtime/guides/queries#why-not-row-level-security), if priorities allow)
- Lakebase Postgres on Databricks (Realtime is available only on Neon for now)

The transport protocol is not yet stable and we aim to add wider client and framework integrations for GA.

The beta also makes no performance guarantees. We have very ambitious performance goals but there's lots of optimization work still to do.

### How much does it cost? Is billing enabled?

Realtime is available on all Neon plans and is free to use during the beta. Neon does not charge for the live query engine compute or the Live SQL API service.

Using Realtime can still cause usage on your database:

- database compute: starting a live query may wake the database compute endpoint, which is billed according to your plan
- data transfer: outbound data transfer is measured as egress and is subject to your plan's data-transfer allowance and applicable overage charges

The beta waiver applies to the Realtime service itself. It does not waive database compute or network-transfer charges generated by your workload.

### What's the performance impact on my database?

Realtime switches the cost of queries from "query-execution on read" to "incremental cost on write". However that cost is incurred on a replica, which means Realtime has zero impact on the write-latency, write-throughput or write-compute of your primary database.

Realtime does require logical replication to be enabled. Technically, this adds a small metadata overhead to the Postgres WAL. For more information, see [Table requirements](https://neon.com/docs/realtime/guides/queries#table-requirements).

### Can I use my ORM / query-builder?

Yes. Realtime works with SQL, so any library that generates SQL can work with it. There are built-in adapters for [Drizzle](https://neon.com/docs/realtime/examples/drizzle) and [Kysely](https://neon.com/docs/realtime/examples/kysely), and you can write your own for other libraries.

See [Using a query builder or ORM](https://neon.com/docs/realtime/guides/queries#using-a-query-builder-or-orm) for how to set one up, and the [`RealtimeAdapter`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeadapter) reference for the interface.

### What SQL features are supported? Are there limitations?

Realtime supports any read-only, deterministic SQL query that [Postgres supports](https://neon.com/postgresql/tutorial/select), including joins, aggregates, window functions and [sub-queries](https://neon.com/postgresql/tutorial/subquery).

Queries can't have side effects, and any functions they use must be deterministic, so you can't use `now()` or `gen_random_uuid()`. Complex queries add write-processing latency, especially on larger datasets.

See [Defining live queries](https://neon.com/docs/realtime/guides/queries#defining-live-queries) for the details.

### Is Realtime enabled by default?

No. You enable it per project and branch. Child branches created from a Realtime-enabled branch have it enabled automatically.

Enable it on a branch with [`neon realtime enable`](https://neon.com/docs/cli/realtime#enable). Or, if you manage your project with `neon.ts`, declare it with `neon config add realtime` and apply it with `neon deploy`. You can also enable it in the Neon Console. See the [Quickstart](https://neon.com/docs/realtime/quickstart) for more details.

Realtime isn't available on [Claimable projects](https://neon.com/docs/reference/claimable-neon) until they're claimed.

### Which regions is it enabled in?

During the beta, Realtime is available in:

```text
aws-ap-southeast-1
aws-eu-central-1
aws-us-east-1
aws-us-east-2
```

See [product availability](https://neon.com/docs/introduction/regions#product-availability) for every region.

### Does Realtime support RLS?

Not yet. Realtime has been architected to support RLS and we aim to add it by GA if priorities allow. However, it's not yet been implemented and isn't the [recommended approach to auth](https://neon.com/docs/realtime/guides/queries#authorization).

See [Why not row-level security](https://neon.com/docs/realtime/guides/queries#why-not-row-level-security) for more details.

### Does Realtime support branching?

Yes, Realtime supports branching. Realtime is enabled at the branch level.

Branches support live queries and Realtime-enabled branches can be branched. Child branches of a Realtime-enabled branch automatically have Realtime enabled.

### Does Realtime support scale-to-zero?

Yes, using Realtime does not prevent your database from scaling to zero. Initiating live queries will wake your database. Holding subscriptions open does not.

### Do live queries use up database connections?

No. Realtime query connections from clients are terminated at the Live SQL API, which then speaks to the live query engine over a single TCP connection.

### Is there a risk of write-lag / WAL build-up?

No. There's no impact on write-throughput and no risk of WAL build-up.

### What about thundering herds?

Realtime has built-in protection from thundering herds in the client and the Live SQL API. There's no risk of a large spike of client-reconnections taking your database down.

### How does Neon Realtime compare with alternatives?

We don't speak for other systems. However, we have tried to articulate the key differences with some alternative realtime systems below.

#### Supabase

[Supabase Realtime](https://supabase.com/docs/guides/realtime) is a pubsub system with replay. It pushes messages and database changes to connected clients. Subscriptions can filter on column values but can't join, aggregate, order, limit or run arbitrary queries.

Neon Realtime is a sync engine that supports [arbitrary live SQL queries](https://neon.com/docs/realtime/guides/queries#defining-live-queries), including joins, aggregates, ordering and limits. The system keeps live query results consistently in sync with the database and provides type-safe primitives for [end-to-end reactivity](https://neon.com/docs/realtime/guides/reactivity) and [instant local writes](https://neon.com/docs/realtime/guides/mutations).

---

#### Convex

Compared with [Convex](https://www.convex.dev), Neon Realtime supports similar [end-to-end reactivity](https://neon.com/docs/realtime/guides/reactivity) but on standard Postgres and with standard web frameworks and build tooling. Realtime also uses delta-sync rather than query-invalidation, which is more efficient over the wire.

---

#### Materialize

Compared with [Materialize](https://materialize.com), Neon Realtime is a similarly expressive incremental view engine with live SQL support. However, Realtime is designed and optimized for serving live data to apps and agents, with efficient data matching and support for large numbers of concurrent clients.

---

#### Zero

[Zero](https://zero.rocicorp.dev) is an open-source sync engine with expressive sync and reactivity using a custom query language. Zero also provides advanced client-side data management. Realtime is built into Lakebase Postgres and the Neon platform and provides similar sync and reactivity on standard SQL. Both systems are composable with your existing schema and auth.

### Is Realtime compatible with, or based on, Electric?

Realtime isn't based on [Electric](https://neon.com/blog/electric-joins-neon), but it **is a drop-in replacement** for Electric's role in your stack. We recommend that teams using Electric migrate to Realtime.

Live SQL queries replace shapes. For TanStack DB users, [`realtimeCollectionOptions()`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionoptions) replaces `electricCollectionOptions()`.

## Next steps

[Get started](https://neon.com/docs/realtime/quickstart) with Realtime and learn more about [how it works](https://neon.com/docs/realtime/how-it-works).

--- [Document source](https://neon.com/docs/realtime/quickstart.md) ---

> Summary: Enable Realtime, run your first live SQL queries and build an app with realtime reactivity.

# Quickstart

Get started with Realtime.

Last updated: 2026-10-16

[Enable Realtime](https://neon.com/docs/realtime/quickstart#enable-realtime), run your [first live SQL queries](https://neon.com/docs/realtime/quickstart#subscribe-to-a-live-query) and [build an app with realtime reactivity](https://neon.com/docs/realtime/quickstart#build-a-realtime-app).

**Important: Create your project in a supported region**

Realtime is currently [available in limited regions](./overview#which-regions-is-it-enabled-in). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions#product-availability).

Realtime isn't available on [Claimable projects](https://neon.com/docs/reference/claimable-neon) until they're claimed.

## Get started

You'll need [Node.js 22 or later](https://nodejs.org/) and the [Neon CLI](https://neon.com/docs/cli/install):

```bash filename="Terminal"
npm i -g neon
```

## Link a project

Log in to Neon, then link a new, empty directory to a Neon project:

```bash filename="Terminal"
neon login
neon link
```

[`neon link`](https://neon.com/docs/cli/link) asks which project to use. Pick an existing project or create a new one. Either way, it needs to be in a supported region.

## Enable Realtime

You can enable Realtime in the Neon Console or using the CLI.

### In the Neon Console

In the Neon Console, select your project and then **Postgres database** > **Realtime** to navigate to the Realtime page.

![Realtime page with enable button](https://neon.com/docs/realtime/realtime-sidebar.png)

Click **Enable Realtime**. Once enabled, you'll see the Realtime page:

![Realtime enabled view](https://neon.com/docs/realtime/realtime-enabled.png)

The page gives you the two values your app needs:

- **Realtime SQL API endpoint URL**: your [Live SQL API](./how-it-works#live-sql-api) endpoint. Use it as the value for `NEON_REALTIME_URL`.
- **Copy secret**: copies the branch's shared secret, which you use when [sealing queries](./guides/queries#sealing-queries). The Console doesn't display the secret. Use it as the value for `NEON_REALTIME_SECRET`.

### Using the CLI

Run [`neon realtime enable`](https://neon.com/docs/cli/realtime#enable) to enable Realtime for the currently linked project and branch:

```bash filename="Terminal"
neon realtime enable
```

To get the URL and secret that the Console shows, you can run:

```bash filename="Terminal"
neon env pull --service realtime
```

It writes them to `.env.local` as `NEON_REALTIME_URL` and `NEON_REALTIME_SECRET`.

## Subscribe to a live query

The simplest way to try live queries is with the [Neon CLI](https://neon.com/docs/cli). First, if you need to, create a table to query and insert some data into it:

```bash filename="Terminal"
neon psql -- -c "CREATE TABLE items (id UUID PRIMARY KEY DEFAULT gen_random_uuid(), value TEXT)"
neon psql -- -c "INSERT INTO items (value) VALUES ('foo')"
```

Then use [`neon realtime subscribe`](https://neon.com/docs/cli/realtime#subscribe) to start a live query:

```bash filename="Terminal"
neon realtime subscribe "SELECT * FROM items"
```

This keeps running until you stop it with `Ctrl+C`. To see the result update, open a second terminal in the same directory and insert another row:

```bash filename="Terminal"
neon psql -- -c "INSERT INTO items (value) VALUES ('bar')"
```

By default, `neon realtime subscribe` prints the full query result every time it changes. To see the underlying delta sync instead, subscribe to the raw changes:

```bash filename="Terminal"
neon realtime subscribe --changes "SELECT * FROM items"
```

See [`neon realtime subscribe`](https://neon.com/docs/cli/realtime#subscribe) for JSON output and the other options.

## Build a realtime app

The `realtime-react` starter template is a shared todo app built with React, Vite, a Hono API and Drizzle, with optimistic updates.

Scaffold it with [`neon bootstrap`](https://neon.com/docs/cli/bootstrap):

```bash filename="Terminal"
neon bootstrap my-app --template realtime-react
```

Bootstrap scaffolds the app, installs the dependencies and links the new `my-app` directory to a Neon project via `neon.ts` config.

If the branch doesn't have Realtime yet, the link step can't pull the env vars and prints a warning to run `neon deploy`. That's the next step.

Run [`neon deploy`](https://neon.com/docs/cli/deploy) to apply the generated config, enabling Realtime for your project and branch:

```bash filename="Terminal"
cd my-app
neon deploy
```

This automatically writes your `DATABASE_URL`, `NEON_REALTIME_URL` and `NEON_REALTIME_SECRET` to `.env.local`. You can then run migrations and start the app:

```bash filename="Terminal"
npm run db:setup
npm run dev
```

Open [http://localhost:5173](http://localhost:5173) in your browser. If you open two windows or tabs, as you change data in one, you'll see it update in realtime in the other.

## Agent skills and MCP

Install the [Neon MCP server](https://neon.com/docs/ai/neon-mcp-server). Or [use the CLI](https://neon.com/docs/cli) to install the Realtime skill:

```bash filename="Terminal"
neon skills -s neon-realtime
```

Copy this to your coding agent to get started with Realtime. [View prompt](https://neon.com/prompts/neon-realtime.md)

## Manage Realtime

On the Realtime page in the Neon Console:

- **Rotate secret** replaces the branch's shared secret. Once rotation finishes, the old secret stops working, so click **Copy secret** and update `NEON_REALTIME_SECRET` in every app that uses it.
- **Disable Realtime** disconnects all Realtime clients on the branch and discards its shared secret.

To do the same from the CLI, and for details on how rotation and disabling work, see [`neon realtime rotate-secret`](https://neon.com/docs/cli/realtime#rotate-secret) and [`neon realtime disable`](https://neon.com/docs/cli/realtime#disable).

## Next steps

- learn [how Realtime works](./how-it-works) and how the layers fit together
- read the guides on [defining](./guides/queries) and [subscribing](./guides/subscribing) to queries, [reactivity](./guides/reactivity), [optimistic mutations](./guides/mutations) and [server-side rendering](./guides/ssr)
- see the [Next.js](./examples/nextjs) and [TanStack](./examples/tanstack) examples showing how to build full-stack reactive apps with auth and SSR support
- see the [Mastra](./examples/mastra) example showing how users and background agents work on the same data in real time
- view Realtime logs in the **Realtime** tab of the [Monitoring page](https://neon.com/docs/introduction/monitor-logs)

--- [Document source](https://neon.com/docs/realtime/reference/api.md) ---

> Summary: The Live SQL API endpoint is the WebSocket-based HTTP interface for subscribing to live query results from your Neon database.

# API

Live SQL API endpoint reference

Last updated: 2026-10-15

The Live SQL API endpoint is a WebSocket-based HTTP interface that enables real-time subscriptions to database queries.

The Live SQL API's wire protocol isn't stable yet and may change during the beta, so it isn't documented for direct use. We plan to document it before GA. Until then, use the [TypeScript SDK](../sdks/typescript), which handles the protocol for you. The [guides](../guides/queries) show how.

--- [Document source](https://neon.com/docs/realtime/sdks/typescript.md) ---

> Summary: Reference for the Realtime TypeScript SDK, covering backend query sealing, low-level client subscriptions, React integration, and TanStack DB adapter.

# TypeScript SDK

Seal queries, subscribe from clients, and sync with frameworks

Last updated: 2026-10-23

**Important: Upgrading to 0.2.0**

Realtime SDK 0.2.0 uses version 2 of the Realtime protocol. Upgrade `@neon/realtime` and every Realtime adapter you use (`@neon/realtime-react`, `@neon/realtime-tanstack`, `@neon/realtime-drizzle`, `@neon/realtime-kysely`) to 0.2.0 together, since the 0.2.0 adapters require `@neon/realtime` 0.2.0.

The Realtime SDK is split into modules:

- [Backend](https://neon.com/docs/realtime/sdks/typescript#backend) provides a [`RealtimeServer`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeserver) that [seals queries](../guides/queries#sealing-queries)
- [Client](https://neon.com/docs/realtime/sdks/typescript#client) provides a [`RealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#client-realtimeclient) that subscribes to live queries and materializes results
- [React](https://neon.com/docs/realtime/sdks/typescript#react) provides a [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider) and the [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery) and [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#react-userealtimeclient) hooks
- [TanStack DB](https://neon.com/docs/realtime/sdks/typescript#tanstack-db) provides [`realtimeCollectionOptions`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionoptions) to create a [TanStack DB collection](https://tanstack.com/db/latest/docs/overview#defining-collections)
- [Drizzle](https://neon.com/docs/realtime/sdks/typescript#drizzle) and [Kysely](https://neon.com/docs/realtime/sdks/typescript#kysely) provide [live query adapters](../guides/queries#using-a-query-builder-or-orm)

**Warning: Beta: APIs may change**

The TypeScript SDK is still evolving. The APIs are subject to change.

## Backend

Import the Backend module from `@neon/realtime/server`. It runs only on your server, because it uses your Realtime secret. It defines live queries and seals them, so an untrusted client can subscribe to a query without being able to read or change it. It's taught in the [Defining queries](../guides/queries) guide.

Create the server once, then seal a query:

```ts
import { createRealtime } from "@neon/realtime/server"

const realtime = createRealtime({ secret: process.env.NEON_REALTIME_SECRET!, db: "neondb" })
const sealedQuery = await realtime.seal({ query: messagesQuery(userId, channelId) })
```

`secret` is your `NEON_REALTIME_SECRET`, written by `neon env pull --service realtime` or shown on the Realtime page in the Neon Console. `db` is the database your queries run against. [Setup](../guides/queries#setup) covers both, and [`RealtimeServerOptions`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeserveroptions) lists the other options, including [`debugMode`](../guides/subscribing#show-full-database-errors).

### Direct subscriptions

Add a `url` to `createRealtime()` and it returns a [`RealtimeDirectServer`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimedirectserver), which subscribes to queries itself, for workers, trusted agents and other backend code. [Subscribe in trusted backend code](../guides/subscribing#subscribe-in-trusted-backend-code) shows how.

### Typed parameters

Most `rawSql` parameter values pass as they are. Wrap dates, JSON, `bytea` and arrays in a [`pgParam`](https://neon.com/docs/realtime/sdks/typescript#backend-pgparam) helper to name their Postgres type, as [Parameter types](../guides/queries#parameter-types) shows.

**Import specifier** `@neon/realtime/server`

### Symbols

| Symbol                                                                                                              | Kind       | Summary                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`createRealtime`](https://neon.com/docs/realtime/sdks/typescript#backend-createrealtime)                           | Function   | Create a server-only Realtime SDK. `seal()` performs local encryption and no network requests. Supplying a WebSocket `url` additionally enables trusted direct subscriptions that mint and refresh their own capabilities. Keep the project secret out of browser bundles.                                                                                  |
| [`encodeTextParameter`](https://neon.com/docs/realtime/sdks/typescript#backend-encodetextparameter)                 | Function   | Encode an already unambiguous scalar as a PostgreSQL text-format parameter. This low-level helper is intended for adapter authors. Application code using raw SQL should prefer [`pgParam`](https://neon.com/docs/realtime/sdks/typescript#backend-pgparam) for ambiguous PostgreSQL types.                                                                 |
| [`isTypedRawSqlParameter`](https://neon.com/docs/realtime/sdks/typescript#backend-istypedrawsqlparameter)           | Function   | Test whether a value was created by one of the [`pgParam`](https://neon.com/docs/realtime/sdks/typescript#backend-pgparam) helpers. This low-level helper is intended for query-adapter authors. Applications should normally pass the wrapper directly to the adapter or [`rawSql`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsql).        |
| [`rawSql`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsql)                                           | Function   | Define a typed raw SQL query. Values are sent separately from the SQL. Bare values use type OID `0`, asking PostgreSQL to infer their types from the SQL. Use [`pgParam`](https://neon.com/docs/realtime/sdks/typescript#backend-pgparam) when a value needs an explicit PostgreSQL encoder and built-in type OID. JavaScript `null` represents SQL `NULL`. |
| [`PostgresParameterHelpers`](https://neon.com/docs/realtime/sdks/typescript#backend-postgresparameterhelpers)       | Interface  | PostgreSQL text encoders for values that bare raw SQL cannot disambiguate.                                                                                                                                                                                                                                                                                  |
| [`PreparedLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#backend-preparedlivequery)                     | Interface  | Adapter-independent query encrypted into a live-query capability.                                                                                                                                                                                                                                                                                           |
| [`PreparedLiveQueryParameter`](https://neon.com/docs/realtime/sdks/typescript#backend-preparedlivequeryparameter)   | Interface  | One PostgreSQL text-format Bind parameter in a prepared live query.                                                                                                                                                                                                                                                                                         |
| [`RawSqlQuery`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsqlquery)                                 | Interface  | Parameterized raw PostgreSQL SQL carrying its declared result-row type.                                                                                                                                                                                                                                                                                     |
| [`RealtimeAdapter`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeadapter)                         | Interface  | Converts an ORM-native query into the prepared live-query representation.                                                                                                                                                                                                                                                                                   |
| [`RealtimeDirectServer`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimedirectserver)               | Interface  | Server-only SDK with trusted direct-query subscriptions. Each subscription prepares and encrypts its query locally, then uses a shared low-level client and refreshes its capability automatically. It retains its rows while connecting through retryable outages and transparently replaces an expired subscription after connectivity returns.           |
| [`RealtimeDirectServerOptions`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimedirectserveroptions) | Interface  | Configuration that enables trusted direct-query subscriptions.                                                                                                                                                                                                                                                                                              |
| [`RealtimeServer`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeserver)                           | Interface  | Server-only Realtime capability issuer.                                                                                                                                                                                                                                                                                                                     |
| [`RealtimeServerOptions`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeserveroptions)             | Interface  | Configuration for a server-only Realtime capability issuer.                                                                                                                                                                                                                                                                                                 |
| [`SealedLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#backend-sealedlivequery)                         | Interface  | JSON-compatible sealed representation of one exact live query. The query is a short-lived bearer credential. Transport it over HTTPS and do not put it in URLs, logs, or persistent browser storage.                                                                                                                                                        |
| [`TypedRawSqlParameter`](https://neon.com/docs/realtime/sdks/typescript#backend-typedrawsqlparameter)               | Interface  | A raw SQL parameter with an explicit PostgreSQL text encoder and type hint.                                                                                                                                                                                                                                                                                 |
| [`RawSqlParameter`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsqlparameter)                         | Type alias | A JavaScript value accepted as a PostgreSQL text-format parameter.                                                                                                                                                                                                                                                                                          |
| [`RealtimeAdapterSource`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeadaptersource)             | Type alias | Bounded query-builder family recorded in encrypted capabilities.                                                                                                                                                                                                                                                                                            |
| [`pgParam`](https://neon.com/docs/realtime/sdks/typescript#backend-pgparam)                                         | Variable   | Helpers for values whose PostgreSQL text encoding or type is ambiguous.                                                                                                                                                                                                                                                                                     |

### createRealtime

```ts
function createRealtime<Query = RawSqlQuery<unknown>>(options: RealtimeDirectServerOptions<Query>): RealtimeDirectServer<Query>
```

Create a server-only Realtime SDK.

`seal()` performs local encryption and no network requests. Supplying a
WebSocket `url` additionally enables trusted direct subscriptions that mint
and refresh their own capabilities. Keep the project secret out of browser
bundles.

**Returns:** A reusable capability issuer, extended with direct subscriptions
when `url` is present.

**Throws:** If the secret or database name is invalid.

#### Type parameters

| Name    | Default                | Description                                      |
| ------- | ---------------------- | ------------------------------------------------ |
| `Query` | `RawSqlQuery<unknown>` | Query object accepted by the configured adapter. |

#### Parameters

| Name      | Type                                 | Description                                                    |
| --------- | ------------------------------------ | -------------------------------------------------------------- |
| `options` | `RealtimeDirectServerOptions<Query>` | Server-only secret, database name, and optional query adapter. |

#### Returns

`RealtimeDirectServer<Query>`

```ts
function createRealtime<Query = RawSqlQuery<unknown>>(options: RealtimeServerOptions<Query>): RealtimeServer<Query>
```

Create a server-only Realtime SDK.

`seal()` performs local encryption and no network requests. Supplying a
WebSocket `url` additionally enables trusted direct subscriptions that mint
and refresh their own capabilities. Keep the project secret out of browser
bundles.

**Returns:** A reusable capability issuer, extended with direct subscriptions
when `url` is present.

**Throws:** If the secret or database name is invalid.

#### Type parameters

| Name    | Default                | Description                                      |
| ------- | ---------------------- | ------------------------------------------------ |
| `Query` | `RawSqlQuery<unknown>` | Query object accepted by the configured adapter. |

#### Parameters

| Name      | Type                           | Description                                                    |
| --------- | ------------------------------ | -------------------------------------------------------------- |
| `options` | `RealtimeServerOptions<Query>` | Server-only secret, database name, and optional query adapter. |

#### Returns

`RealtimeServer<Query>`

### encodeTextParameter

```ts
function encodeTextParameter(value: string | number | bigint | boolean | null, typeOid: number = 0): PreparedLiveQueryParameter
```

Encode an already unambiguous scalar as a PostgreSQL text-format parameter.

This low-level helper is intended for adapter authors. Application code
using raw SQL should prefer [`pgParam`](https://neon.com/docs/realtime/sdks/typescript#backend-pgparam) for ambiguous PostgreSQL types.

**Returns:** An immutable prepared parameter.

#### Parameters

| Name      | Type                                            | Description                                                 |
| --------- | ----------------------------------------------- | ----------------------------------------------------------- |
| `value`   | `string \| number \| bigint \| boolean \| null` | Scalar value, or `null` for SQL `NULL`.                     |
| `typeOid` | `number`                                        | PostgreSQL type OID hint, or `0` for SQL-context inference. |

#### Returns

`PreparedLiveQueryParameter`

### isTypedRawSqlParameter

```ts
function isTypedRawSqlParameter(value: unknown): value is TypedRawSqlParameter
```

Test whether a value was created by one of the [`pgParam`](https://neon.com/docs/realtime/sdks/typescript#backend-pgparam) helpers.

This low-level helper is intended for query-adapter authors. Applications
should normally pass the wrapper directly to the adapter or [`rawSql`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsql).

#### Parameters

| Name    | Type      | Description |
| ------- | --------- | ----------- |
| `value` | `unknown` |             |

#### Returns

`value is TypedRawSqlParameter`

### rawSql

```ts
function rawSql<Row>(sql: string, parameters: readonly RawSqlParameter[] = []): RawSqlQuery<Row>
```

Define a typed raw SQL query. Values are sent separately from the SQL. Bare
values use type OID `0`, asking PostgreSQL to infer their types from the
SQL. Use [`pgParam`](https://neon.com/docs/realtime/sdks/typescript#backend-pgparam) when a value needs an explicit PostgreSQL encoder
and built-in type OID. JavaScript `null` represents SQL `NULL`.

**Returns:** An immutable query descriptor accepted by `seal()`.

#### Type parameters

| Name  | Default | Description                |
| ----- | ------- | -------------------------- |
| `Row` |         | Row returned by the query. |

#### Parameters

| Name         | Type                         | Description                                                   |
| ------------ | ---------------------------- | ------------------------------------------------------------- |
| `sql`        | `string`                     | Parameterized SQL using PostgreSQL placeholders such as `$1`. |
| `parameters` | `readonly RawSqlParameter[]` | Values in placeholder order.                                  |

#### Returns

`RawSqlQuery<Row>`

### PostgresParameterHelpers

```ts
interface PostgresParameterHelpers
```

PostgreSQL text encoders for values that bare raw SQL cannot disambiguate.

#### Members

| Name          | Type                                                                                              | Description                                                                                                                                                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `array`       | `(elementType: string, values: readonly unknown[]) => TypedRawSqlParameter`                       | Encode a possibly nested PostgreSQL array. Built-in element types supply their stable array OID; database-specific or unknown element types use OID `0`. JavaScript `null` becomes a SQL NULL array element. Values are encoded immediately, so later mutations do not affect the parameter. |
| `bytea`       | `(value: Uint8Array) => TypedRawSqlParameter`                                                     | Encode bytes in PostgreSQL's hexadecimal `bytea` text format.                                                                                                                                                                                                                                |
| `date`        | `(value: string \| Date) => TypedRawSqlParameter`                                                 | Encode a JavaScript date as a PostgreSQL `date`. A `Date` uses its UTC calendar date. A string is passed through as an already encoded PostgreSQL text value.                                                                                                                                |
| `json`        | `(value: unknown) => TypedRawSqlParameter`                                                        | Encode a JavaScript value as PostgreSQL `json`.                                                                                                                                                                                                                                              |
| `jsonb`       | `(value: unknown) => TypedRawSqlParameter`                                                        | Encode a JavaScript value as PostgreSQL `jsonb`.                                                                                                                                                                                                                                             |
| `text`        | `(sqlType: string, value: string \| number \| bigint \| boolean \| null) => TypedRawSqlParameter` | Use an already encoded PostgreSQL text value for a named type. A recognized built-in type supplies its stable OID. Unknown, database-specific, and extension types use OID `0` for inference.                                                                                                |
| `timestamp`   | `(value: string \| Date) => TypedRawSqlParameter`                                                 | Encode a JavaScript date as a UTC PostgreSQL `timestamp` without time zone. A string is passed through as an already encoded PostgreSQL text value.                                                                                                                                          |
| `timestamptz` | `(value: string \| Date) => TypedRawSqlParameter`                                                 | Encode a JavaScript date as a PostgreSQL `timestamptz`. A `Date` uses its ISO 8601 representation. A string is passed through as an already encoded PostgreSQL text value.                                                                                                                   |

### PreparedLiveQuery

```ts
interface PreparedLiveQuery
```

Adapter-independent query encrypted into a live-query capability.

#### Members

| Name         | Type                                    | Description                                                             |
| ------------ | --------------------------------------- | ----------------------------------------------------------------------- |
| `parameters` | `readonly PreparedLiveQueryParameter[]` | PostgreSQL text-format Bind values and type hints in placeholder order. |
| `sql`        | `readonly string`                       | Parameterized SQL. Adapters must never interpolate runtime values here. |

### PreparedLiveQueryParameter

```ts
interface PreparedLiveQueryParameter
```

One PostgreSQL text-format Bind parameter in a prepared live query.

#### Members

| Name      | Type                      | Description                                                        |
| --------- | ------------------------- | ------------------------------------------------------------------ |
| `typeOid` | `readonly number`         | PostgreSQL type OID hint, or `0` to request SQL-context inference. |
| `value`   | `readonly string \| null` | PostgreSQL text-format value, or `null` for SQL `NULL`.            |

### RawSqlQuery

```ts
interface RawSqlQuery<Row> extends PreparedLiveQuery
```

Parameterized raw PostgreSQL SQL carrying its declared result-row type.

#### Members

| Name         | Type                                    | Description                                                             |
| ------------ | --------------------------------------- | ----------------------------------------------------------------------- |
| `parameters` | `readonly PreparedLiveQueryParameter[]` | PostgreSQL text-format Bind values and type hints in placeholder order. |
| `sql`        | `readonly string`                       | Parameterized SQL. Adapters must never interpolate runtime values here. |

### RealtimeAdapter

```ts
interface RealtimeAdapter<Query>
```

Converts an ORM-native query into the prepared live-query representation.

#### Members

| Name           | Type                                  | Description                                                                                                                                                                                      |
| -------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `querySource?` | `readonly RealtimeAdapterSource`      | Query-builder family used for aggregate Realtime usage metrics. Official adapters set this automatically; custom adapters may omit it.                                                           |
| `prepare`      | `(query: Query) => PreparedLiveQuery` | Convert an adapter-native query into parameterized SQL and text-format parameter values. Adapters may supply PostgreSQL type OID hints; `0` requests inference. The proxy supplies result types. |

### RealtimeDirectServer

```ts
interface RealtimeDirectServer<Query> extends RealtimeServer<Query>
```

Server-only SDK with trusted direct-query subscriptions.

Each subscription prepares and encrypts its query locally, then uses a
shared low-level client and refreshes its capability automatically. It
retains its rows while connecting through retryable outages and
transparently replaces an expired subscription after connectivity returns.

#### Members

| Name                                                                                                | Type                                                                                                                                                                                                                                                                                                                | Description                                                                                                                                                                                                                                                                                                              |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `close`                                                                                             | `() => void`                                                                                                                                                                                                                                                                                                        | Permanently close every direct subscription and the shared WebSocket.                                                                                                                                                                                                                                                    |
| [`seal`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimedirectserverseal)           | `<ConcreteQuery>(input: SealInput<ConcreteQuery>) => Promise<SealedLiveQuery<QueryRow<ConcreteQuery>>>`                                                                                                                                                                                                             | Encrypt a concrete query as a short-lived sealed query. Raw queries produced by [`rawSql`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsql) are always accepted. Other query objects are prepared by the configured adapter. SQL validation is deferred to the Realtime proxy when the capability is used. |
| [`subscribe`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimedirectserversubscribe) | `<ConcreteQuery>(query: ConcreteQuery, options?: MaterializedLiveQueryOptions<QueryRow<ConcreteQuery>>) => Promise<MaterializedLiveQuerySubscription<QueryRow<ConcreteQuery>>> & <ConcreteQuery>(query: ConcreteQuery, options: RawLiveQueryOptions) => Promise<RawLiveQuerySubscription<QueryRow<ConcreteQuery>>>` | Subscribe to a query and retain its current materialized rows.                                                                                                                                                                                                                                                           |

#### RealtimeDirectServer.seal

```ts
seal<ConcreteQuery>(input: SealInput<ConcreteQuery>): Promise<SealedLiveQuery<QueryRow<ConcreteQuery>>>
```

Encrypt a concrete query as a short-lived sealed query.

Raw queries produced by [`rawSql`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsql) are always accepted. Other query
objects are prepared by the configured adapter. SQL validation is deferred
to the Realtime proxy when the capability is used.

**Returns:** A JSON-compatible bearer capability with its public fingerprint
and expiry.

**Throws:** If no adapter can prepare the query or capability encryption fails.

**Parameters**

| Name    | Type                       | Description             |
| ------- | -------------------------- | ----------------------- |
| `input` | `SealInput<ConcreteQuery>` | Concrete query to seal. |

#### RealtimeDirectServer.subscribe

```ts
subscribe<ConcreteQuery>(query: ConcreteQuery, options?: MaterializedLiveQueryOptions<QueryRow<ConcreteQuery>>): Promise<MaterializedLiveQuerySubscription<QueryRow<ConcreteQuery>>>
```

Subscribe to a query and retain its current materialized rows.

**Returns:** An independently disposable subscription after its initial
capability has been minted locally.

**Throws:** If the query is invalid or the direct client has been closed.

**Parameters**

| Name       | Type                                                    | Description                                          |
| ---------- | ------------------------------------------------------- | ---------------------------------------------------- |
| `query`    | `ConcreteQuery`                                         | Concrete raw SQL or adapter-native query.            |
| `options?` | `MaterializedLiveQueryOptions<QueryRow<ConcreteQuery>>` | Materialization and optional preloaded-row settings. |

```ts
subscribe<ConcreteQuery>(query: ConcreteQuery, options: RawLiveQueryOptions): Promise<RawLiveQuerySubscription<QueryRow<ConcreteQuery>>>
```

Subscribe to complete rows and atomic change batches without retaining rows.

**Returns:** An independently disposable raw subscription after its initial
capability has been minted locally.

**Throws:** If the query is invalid or the direct client has been closed.

**Parameters**

| Name      | Type                  | Description                                         |
| --------- | --------------------- | --------------------------------------------------- |
| `query`   | `ConcreteQuery`       | Concrete raw SQL or adapter-native query.           |
| `options` | `RawLiveQueryOptions` | Set `materialize` to `false` to consume raw events. |

### RealtimeDirectServerOptions

```ts
interface RealtimeDirectServerOptions<Query> extends RealtimeServerOptions<Query>
```

Configuration that enables trusted direct-query subscriptions.

#### Members

| Name                                                                                                        | Type                                                                                                                  | Description                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `adapter?`                                                                                                  | `readonly RealtimeAdapter<Query>`                                                                                     | Adapter for ORM-native queries; omit when sealing only raw SQL.                                                                                                                                           |
| `db`                                                                                                        | `readonly string`                                                                                                     | PostgreSQL database for this SDK instance. It is embedded in every query capability. The first capability accepted on a WebSocket binds that connection to this database.                                 |
| [`debugMode?`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimedirectserveroptionsdebugmode) | `readonly boolean`                                                                                                    | Include full database error details in subscription errors. Enable this only in development. Detailed errors can expose schema names, table names, column names, and other database structure to clients. |
| `logger?`                                                                                                   | `readonly RealtimeLogger`                                                                                             | Structured diagnostic sink for the internal direct-subscription client.                                                                                                                                   |
| `logLevel?`                                                                                                 | `readonly RealtimeLogLevel`                                                                                           | Minimum diagnostic level for the internal direct-subscription client.                                                                                                                                     |
| `parsers?`                                                                                                  | `readonly Readonly<Record<number, PostgreSQLBytesParser<unknown> \| PostgreSQLTextParser<unknown>> & BuiltInParsers>` | PostgreSQL result-parser overrides for trusted direct subscriptions.                                                                                                                                      |
| `secret`                                                                                                    | `readonly string`                                                                                                     | Opaque server-only credential issued by Realtime.                                                                                                                                                         |
| `url`                                                                                                       | `readonly string`                                                                                                     | Realtime WebSocket endpoint URL. Supplying it adds `subscribe()` and `close()` to the returned SDK.                                                                                                       |

#### RealtimeDirectServerOptions.debugMode

```ts
readonly debugMode?: boolean
```

Include full database error details in subscription errors.

Enable this only in development. Detailed errors can expose schema names,
table names, column names, and other database structure to clients.

**Default**

```ts
false
```

### RealtimeServer

```ts
interface RealtimeServer<Query>
```

Server-only Realtime capability issuer.

#### Members

| Name                                                                                | Type                                                                                                    | Description                                                                                                                                                                                                                                                                                                              |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`seal`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeserverseal) | `<ConcreteQuery>(input: SealInput<ConcreteQuery>) => Promise<SealedLiveQuery<QueryRow<ConcreteQuery>>>` | Encrypt a concrete query as a short-lived sealed query. Raw queries produced by [`rawSql`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsql) are always accepted. Other query objects are prepared by the configured adapter. SQL validation is deferred to the Realtime proxy when the capability is used. |

#### RealtimeServer.seal

```ts
seal<ConcreteQuery>(input: SealInput<ConcreteQuery>): Promise<SealedLiveQuery<QueryRow<ConcreteQuery>>>
```

Encrypt a concrete query as a short-lived sealed query.

Raw queries produced by [`rawSql`](https://neon.com/docs/realtime/sdks/typescript#backend-rawsql) are always accepted. Other query
objects are prepared by the configured adapter. SQL validation is deferred
to the Realtime proxy when the capability is used.

**Returns:** A JSON-compatible bearer capability with its public fingerprint
and expiry.

**Throws:** If no adapter can prepare the query or capability encryption fails.

**Parameters**

| Name    | Type                       | Description             |
| ------- | -------------------------- | ----------------------- |
| `input` | `SealInput<ConcreteQuery>` | Concrete query to seal. |

### RealtimeServerOptions

```ts
interface RealtimeServerOptions<Query>
```

Configuration for a server-only Realtime capability issuer.

#### Members

| Name                                                                                                  | Type                              | Description                                                                                                                                                                                               |
| ----------------------------------------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `adapter?`                                                                                            | `readonly RealtimeAdapter<Query>` | Adapter for ORM-native queries; omit when sealing only raw SQL.                                                                                                                                           |
| `db`                                                                                                  | `readonly string`                 | PostgreSQL database for this SDK instance. It is embedded in every query capability. The first capability accepted on a WebSocket binds that connection to this database.                                 |
| [`debugMode?`](https://neon.com/docs/realtime/sdks/typescript#backend-realtimeserveroptionsdebugmode) | `readonly boolean`                | Include full database error details in subscription errors. Enable this only in development. Detailed errors can expose schema names, table names, column names, and other database structure to clients. |
| `secret`                                                                                              | `readonly string`                 | Opaque server-only credential issued by Realtime.                                                                                                                                                         |

#### RealtimeServerOptions.debugMode

```ts
readonly debugMode?: boolean
```

Include full database error details in subscription errors.

Enable this only in development. Detailed errors can expose schema names,
table names, column names, and other database structure to clients.

**Default**

```ts
false
```

### SealedLiveQuery

```ts
interface SealedLiveQuery<Row>
```

JSON-compatible sealed representation of one exact live query.

The query is a short-lived bearer credential. Transport it over
HTTPS and do not put it in URLs, logs, or persistent browser storage.

#### Members

| Name               | Type              | Description                                                              |
| ------------------ | ----------------- | ------------------------------------------------------------------------ |
| `capability`       | `readonly string` | Opaque encrypted bearer capability.                                      |
| `expiresAt`        | `readonly number` | Capability expiry as Unix milliseconds.                                  |
| `queryFingerprint` | `readonly string` | Stable identity used to prevent accidentally renewing a different query. |

### TypedRawSqlParameter

```ts
interface TypedRawSqlParameter extends PreparedLiveQueryParameter
```

A raw SQL parameter with an explicit PostgreSQL text encoder and type hint.

#### Members

| Name      | Type                      | Description                                                        |
| --------- | ------------------------- | ------------------------------------------------------------------ |
| `typeOid` | `readonly number`         | PostgreSQL type OID hint, or `0` to request SQL-context inference. |
| `value`   | `readonly string \| null` | PostgreSQL text-format value, or `null` for SQL `NULL`.            |

### RawSqlParameter

```ts
type RawSqlParameter = string | number | boolean | bigint | null | TypedRawSqlParameter
```

A JavaScript value accepted as a PostgreSQL text-format parameter.

### RealtimeAdapterSource

```ts
type RealtimeAdapterSource = "drizzle" | "kysely" | "custom"
```

Bounded query-builder family recorded in encrypted capabilities.

### pgParam

```ts
const pgParam: PostgresParameterHelpers
```

Helpers for values whose PostgreSQL text encoding or type is ambiguous.

## Client

Import the Client module from `@neon/realtime/client`. It runs in the browser, where it subscribes to sealed queries over one shared WebSocket and keeps their results up to date. It's taught in the [Subscribing to queries](../guides/subscribing) guide.

Create one client for your app, then subscribe to a sealed query from your backend:

```ts
import { createRealtimeClient } from "@neon/realtime/client"

const client = createRealtimeClient({ url: import.meta.env.VITE_NEON_REALTIME_URL })
const subscription = client.subscribe(sealedQuery)
subscription.onChange(({ data, status }) => render(data, status))
```

Pass a `logLevel` to see what the client is doing, as [Log client diagnostics](../guides/subscribing#log-client-diagnostics) shows.

### React Native

The client also runs in React Native apps, with `@neon/realtime` 0.1.2 or later. Import it from `@neon/realtime/client` as usual.

React Native's WebSocket sends an `Origin` header derived from the Realtime endpoint. If your branch restricts Realtime to specific origins, pass a `webSocketFactory` that sends one of the allowed origins:

```ts
const client = createRealtimeClient({
  url: realtimeUrl,
  webSocketFactory: (url, protocols) =>
    new WebSocket(url, protocols, {
      headers: { origin: "https://app.example.com" },
    }),
})
```

The third `WebSocket` argument is a React Native extension and isn't available in browsers. An origin allowlist protects browser apps only. A native app can send any origin, so don't rely on it to authenticate native clients.

### Renewing sealed queries

Most apps pass a `refreshQuery` function to the [React or TanStack DB bindings](../guides/reactivity), which renew for them. To renew a subscription yourself, see [Renew the sealed query](../guides/subscribing#renew-the-sealed-query). Integration authors can build on [`QueryRefreshController`](https://neon.com/docs/realtime/sdks/typescript#client-queryrefreshcontroller).

**Import specifier** `@neon/realtime/client`

### Symbols

| Symbol                                                                                                                         | Kind       | Summary                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------------------------------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`createRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#client-createrealtimeclient)                           | Function   | Create a reusable client that lazily opens and multiplexes a Realtime WebSocket connection that is bound by its first accepted query capability. The connection carries no user session credential; each subscription sends its own short-lived sealed query. Idle connections are heartbeat-probed, and recoverable disconnects retry with capped jittered backoff until the connection recovers or the client is closed. |
| [`defineParsers`](https://neon.com/docs/realtime/sdks/typescript#client-defineparsers)                                         | Function   | Define an OID-keyed parser preset with contextual input types. OID `pgTypeOids.bytea` receives `Uint8Array`; every other OID receives PostgreSQL text. The returned object is a frozen snapshot of the input.                                                                                                                                                                                                              |
| [`QueryRefreshController`](https://neon.com/docs/realtime/sdks/typescript#client-queryrefreshcontroller)                       | Class      | Schedules capability refreshes for framework integrations. Most applications should supply `refreshQuery` to their React or TanStack DB integration instead of constructing this class. Integration authors can use it to refresh shortly before expiry and keep retrying across capability expiry or an arbitrarily long transport outage.                                                                                |
| [`LiveQueryBatchInfo`](https://neon.com/docs/realtime/sdks/typescript#client-livequerybatchinfo)                               | Interface  | Metadata for one atomically published batch of PostgreSQL transactions.                                                                                                                                                                                                                                                                                                                                                    |
| [`LiveQueryError`](https://neon.com/docs/realtime/sdks/typescript#client-livequeryerror)                                       | Interface  | An error reported by a live-query subscription.                                                                                                                                                                                                                                                                                                                                                                            |
| [`MaterializedLiveQueryOptions`](https://neon.com/docs/realtime/sdks/typescript#client-materializedlivequeryoptions)           | Interface  | Options for the default materialized subscription.                                                                                                                                                                                                                                                                                                                                                                         |
| [`MaterializedLiveQuerySubscription`](https://neon.com/docs/realtime/sdks/typescript#client-materializedlivequerysubscription) | Interface  | A live-query subscription that also retains and publishes the current rows.                                                                                                                                                                                                                                                                                                                                                |
| [`RawLiveQueryOptions`](https://neon.com/docs/realtime/sdks/typescript#client-rawlivequeryoptions)                             | Interface  | Options for a raw, non-materializing subscription.                                                                                                                                                                                                                                                                                                                                                                         |
| [`RawLiveQueryRow`](https://neon.com/docs/realtime/sdks/typescript#client-rawlivequeryrow)                                     | Interface  | A row in a complete raw result, paired with its opaque Realtime identity.                                                                                                                                                                                                                                                                                                                                                  |
| [`RawLiveQuerySubscription`](https://neon.com/docs/realtime/sdks/typescript#client-rawlivequerysubscription)                   | Interface  | A live-query subscription that exposes ordered raw result updates.                                                                                                                                                                                                                                                                                                                                                         |
| [`RealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#client-realtimeclient)                                       | Interface  | A client that multiplexes independently disposable subscriptions.                                                                                                                                                                                                                                                                                                                                                          |
| [`RealtimeClientOptions`](https://neon.com/docs/realtime/sdks/typescript#client-realtimeclientoptions)                         | Interface  | Configuration for a reusable Realtime browser client.                                                                                                                                                                                                                                                                                                                                                                      |
| [`WebSocketLike`](https://neon.com/docs/realtime/sdks/typescript#client-websocketlike)                                         | Interface  | Minimal WebSocket contract used by the Realtime client.                                                                                                                                                                                                                                                                                                                                                                    |
| [`LiveQueryChange`](https://neon.com/docs/realtime/sdks/typescript#client-livequerychange)                                     | Type alias | A row upsert, removal, or sequential move in an atomic publication batch.                                                                                                                                                                                                                                                                                                                                                  |
| [`LiveQuerySnapshot`](https://neon.com/docs/realtime/sdks/typescript#client-livequerysnapshot)                                 | Type alias | Materialized query rows paired with their atomic lifecycle state.                                                                                                                                                                                                                                                                                                                                                          |
| [`LiveQueryState`](https://neon.com/docs/realtime/sdks/typescript#client-livequerystate)                                       | Type alias | Atomic lifecycle state for a live-query subscription.                                                                                                                                                                                                                                                                                                                                                                      |
| [`PostgreSQLBytesParser`](https://neon.com/docs/realtime/sdks/typescript#client-postgresqlbytesparser)                         | Type alias | A parser for PostgreSQL `bytea`, transported as decoded bytes.                                                                                                                                                                                                                                                                                                                                                             |
| [`PostgreSQLParserForOid`](https://neon.com/docs/realtime/sdks/typescript#client-postgresqlparserforoid)                       | Type alias | Parser input selected by the fixed Realtime OID/codec mapping.                                                                                                                                                                                                                                                                                                                                                             |
| [`PostgreSQLParsers`](https://neon.com/docs/realtime/sdks/typescript#client-postgresqlparsers)                                 | Type alias | A sparse collection of result parsers keyed by PostgreSQL type OID.                                                                                                                                                                                                                                                                                                                                                        |
| [`PostgreSQLTextParser`](https://neon.com/docs/realtime/sdks/typescript#client-postgresqltextparser)                           | Type alias | A parser for a PostgreSQL value transported with the `pg_text` codec.                                                                                                                                                                                                                                                                                                                                                      |
| [`RawLiveQueryUpdate`](https://neon.com/docs/realtime/sdks/typescript#client-rawlivequeryupdate)                               | Type alias | One authoritative raw query-result update. `rows` replaces the complete preceding result and invalidates its row-ID namespace. `changes` applies incrementally to the current result.                                                                                                                                                                                                                                      |
| [`RealtimeLogEntry`](https://neon.com/docs/realtime/sdks/typescript#client-realtimelogentry)                                   | Type alias | Structured client diagnostic passed to a configured logger. Narrowing on `event` also narrows the metadata available on the entry.                                                                                                                                                                                                                                                                                         |
| [`RealtimeLogEvent`](https://neon.com/docs/realtime/sdks/typescript#client-realtimelogevent)                                   | Type alias | Stable name for one client diagnostic event.                                                                                                                                                                                                                                                                                                                                                                               |
| [`RealtimeLogger`](https://neon.com/docs/realtime/sdks/typescript#client-realtimelogger)                                       | Type alias | Receives structured Realtime client diagnostics.                                                                                                                                                                                                                                                                                                                                                                           |
| [`RealtimeLogLevel`](https://neon.com/docs/realtime/sdks/typescript#client-realtimeloglevel)                                   | Type alias | Client-side diagnostic verbosity.                                                                                                                                                                                                                                                                                                                                                                                          |
| [`WebSocketFactory`](https://neon.com/docs/realtime/sdks/typescript#client-websocketfactory)                                   | Type alias | Create a WebSocket-compatible transport for the Realtime client.                                                                                                                                                                                                                                                                                                                                                           |
| [`nodePostgresParsers`](https://neon.com/docs/realtime/sdks/typescript#client-nodepostgresparsers)                             | Variable   | Core result parsers matching familiar node-postgres/Neon Serverless values. Less-common and unknown OIDs are intentionally absent and fall back to their exact PostgreSQL text. Known built-in array OIDs are decoded recursively by the client using the active parser for their element OID.                                                                                                                             |
| [`pgTypeOids`](https://neon.com/docs/realtime/sdks/typescript#client-pgtypeoids)                                               | Variable   | Stable PostgreSQL type OIDs used by the built-in Realtime parsers.                                                                                                                                                                                                                                                                                                                                                         |
| [`postgresJsParsers`](https://neon.com/docs/realtime/sdks/typescript#client-postgresjsparsers)                                 | Variable   | Parsers that differ from the core defaults when matching Postgres.js. Spread this partial preset into the client's `parsers` option.                                                                                                                                                                                                                                                                                       |
| [`SealedLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#client-sealedlivequery)                                     | Re-export  |                                                                                                                                                                                                                                                                                                                                                                                                                            |

### createRealtimeClient

```ts
function createRealtimeClient(options: RealtimeClientOptions): RealtimeClient
```

Create a reusable client that lazily opens and multiplexes a Realtime
WebSocket connection that is bound by its first accepted query capability.

The connection carries no user session credential; each subscription sends
its own short-lived sealed query. Idle connections are heartbeat-probed,
and recoverable disconnects retry with capped jittered backoff until the
connection recovers or the client is closed.

**Returns:** A client that opens its connection when the first query subscribes.

#### Parameters

| Name      | Type                    | Description                                                      |
| --------- | ----------------------- | ---------------------------------------------------------------- |
| `options` | `RealtimeClientOptions` | Browser client configuration, including the proxy WebSocket URL. |

#### Returns

`RealtimeClient`

### defineParsers

```ts
function defineParsers(parsers: BuiltInParsers): PostgreSQLParsers
```

Define an OID-keyed parser preset with contextual input types.

OID `pgTypeOids.bytea` receives `Uint8Array`; every other OID receives
PostgreSQL text. The returned object is a frozen snapshot of the input.

#### Parameters

| Name      | Type             | Description |
| --------- | ---------------- | ----------- |
| `parsers` | `BuiltInParsers` |             |

#### Returns

`PostgreSQLParsers`

```ts
function defineParsers(parsers: Readonly<Record<number, PostgreSQLTextParser>>): PostgreSQLParsers
```

Define an OID-keyed parser preset with contextual input types.

OID `pgTypeOids.bytea` receives `Uint8Array`; every other OID receives
PostgreSQL text. The returned object is a frozen snapshot of the input.

#### Parameters

| Name      | Type                                             | Description |
| --------- | ------------------------------------------------ | ----------- |
| `parsers` | `Readonly<Record<number, PostgreSQLTextParser>>` |             |

#### Returns

`PostgreSQLParsers`

### QueryRefreshController

```ts
class QueryRefreshController<Row>
```

Schedules capability refreshes for framework integrations.

Most applications should supply `refreshQuery` to their React or
TanStack DB integration instead of constructing this class. Integration
authors can use it to refresh shortly before expiry and keep retrying across
capability expiry or an arbitrarily long transport outage.

#### Members

| Name                                                                                                                   | Type                                                                                    | Description                                                                                                                               |
| ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `constructor`                                                                                                          | `new <Row>(options: QueryRefreshControllerOptions<Row>) => QueryRefreshController<Row>` |                                                                                                                                           |
| `currentQuery`                                                                                                         | `() => SealedLiveQuery<Row>`                                                            | Return the capability currently managed by this controller.                                                                               |
| [`replaceSealedQuery`](https://neon.com/docs/realtime/sdks/typescript#client-queryrefreshcontrollerreplacesealedquery) | `(query: SealedLiveQuery<Row>) => Promise<void>`                                        | Apply a replacement capability immediately and schedule its next refresh.                                                                 |
| `setRefreshCallback`                                                                                                   | `(refreshQuery: (() => Promise<SealedLiveQuery<Row>>) \| undefined) => void`            | Replace the callback used to obtain a fresh capability. Passing `undefined` disables scheduled refreshes without stopping the controller. |
| `setSubscription`                                                                                                      | `(subscription: RawLiveQuerySubscription<Row> \| undefined) => void`                    | Associate the active subscription managed by this controller.                                                                             |
| `start`                                                                                                                | `() => void`                                                                            | Start scheduling refreshes. Calling this more than once has no effect.                                                                    |
| `stop`                                                                                                                 | `() => void`                                                                            | Stop scheduling refreshes and ignore any refresh already in flight.                                                                       |

#### QueryRefreshController.replaceSealedQuery

```ts
replaceSealedQuery(query: SealedLiveQuery<Row>): Promise<void>
```

Apply a replacement capability immediately and schedule its next refresh.

**Throws:** If the replacement capability belongs to a different query, or if
applying it to the active subscription fails.

**Parameters**

| Name    | Type                   | Description |
| ------- | ---------------------- | ----------- |
| `query` | `SealedLiveQuery<Row>` |             |

### LiveQueryBatchInfo

```ts
interface LiveQueryBatchInfo
```

Metadata for one atomically published batch of PostgreSQL transactions.

#### Members

| Name    | Type                | Description                                                      |
| ------- | ------------------- | ---------------------------------------------------------------- |
| `txids` | `readonly string[]` | Exact PostgreSQL transaction IDs represented as decimal strings. |

### LiveQueryError

```ts
interface LiveQueryError extends Error
```

An error reported by a live-query subscription.

#### Members

| Name        | Type               | Description                                                            |
| ----------- | ------------------ | ---------------------------------------------------------------------- |
| `cause?`    | `unknown`          |                                                                        |
| `code`      | `readonly string`  | Stable machine-readable error code.                                    |
| `message`   | `string`           |                                                                        |
| `name`      | `string`           |                                                                        |
| `retryable` | `readonly boolean` | Whether reconnecting or obtaining a fresh sealed query may recover it. |
| `sqlState?` | `readonly string`  | PostgreSQL SQLSTATE supplied for an authenticated debug query failure. |
| `stack?`    | `string`           |                                                                        |

### MaterializedLiveQueryOptions

```ts
interface MaterializedLiveQueryOptions<Row>
```

Options for the default materialized subscription.

#### Members

| Name           | Type             | Description                                                                                                                                                                                                             |
| -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialData?` | `readonly Row[]` | Preloaded rows exposed while connecting to the authoritative result. Supply decoded rows matching the live result, restoring any values changed by transport serialization (for example, JSON date strings) beforehand. |
| `materialize?` | `readonly true`  | Select materialization; omitted and `true` are equivalent.                                                                                                                                                              |

### MaterializedLiveQuerySubscription

```ts
interface MaterializedLiveQuerySubscription<Row> extends RawLiveQuerySubscription<Row>
```

A live-query subscription that also retains and publishes the current rows.

#### Members

| Name                                                                                                                    | Type                                                                              | Description                                                                                                                                                                                                                                                                                     |
| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`awaitRows`](https://neon.com/docs/realtime/sdks/typescript#client-materializedlivequerysubscriptionawaitrows)         | `(matches: (rows: readonly Row[]) => boolean, timeout?: number) => Promise<void>` | Wait until the materialized rows satisfy a predicate. The current snapshot is inspected before waiting for later changes, so this also succeeds when matching rows arrived before the call.                                                                                                     |
| [`awaitTxId`](https://neon.com/docs/realtime/sdks/typescript#client-materializedlivequerysubscriptionawaittxid)         | `(txid: string, timeout?: number) => Promise<void>`                               | Wait until this subscription has applied a PostgreSQL transaction. Recently applied transaction IDs are retained so this also succeeds when the batch arrives before the caller receives the mutation response.                                                                                 |
| `getSnapshot`                                                                                                           | `() => LiveQuerySnapshot<Row>`                                                    | Return the current rows and lifecycle state atomically.                                                                                                                                                                                                                                         |
| `getState`                                                                                                              | `() => LiveQueryState`                                                            | Return the complete current lifecycle state.                                                                                                                                                                                                                                                    |
| [`onChange`](https://neon.com/docs/realtime/sdks/typescript#client-materializedlivequerysubscriptiononchange)           | `(listener: (snapshot: LiveQuerySnapshot<Row>) => void) => () => void`            | Observe row or lifecycle changes as complete snapshots. The listener runs after complete-row replacements, incremental changes, and state transitions.                                                                                                                                          |
| [`onStateChange`](https://neon.com/docs/realtime/sdks/typescript#client-materializedlivequerysubscriptiononstatechange) | `(listener: (state: LiveQueryState) => void) => () => void`                       | Observe lifecycle transitions.                                                                                                                                                                                                                                                                  |
| [`onUpdate`](https://neon.com/docs/realtime/sdks/typescript#client-materializedlivequerysubscriptiononupdate)           | `(listener: (update: RawLiveQueryUpdate<Row>) => void) => () => void`             | Observe complete-row replacements and incremental changes through one ordered update stream. Every affected materialized subscription has already applied an update before its listener runs.                                                                                                   |
| [`renew`](https://neon.com/docs/realtime/sdks/typescript#client-materializedlivequerysubscriptionrenew)                 | `(query: SealedLiveQuery<Row>) => Promise<void>`                                  | Renew this logical subscription with a capability for the same exact query. If the preceding subscription has expired, the client creates a new wire subscription while preserving this object, its listeners, and any retained rows. The replacement then produces a new authoritative result. |
| `unsubscribe`                                                                                                           | `() => void`                                                                      | Permanently close this subscription and remove its listeners.                                                                                                                                                                                                                                   |

#### MaterializedLiveQuerySubscription.awaitRows

```ts
awaitRows(matches: (rows: readonly Row[]) => boolean, timeout?: number): Promise<void>
```

Wait until the materialized rows satisfy a predicate.

The current snapshot is inspected before waiting for later changes, so
this also succeeds when matching rows arrived before the call.

**Throws:** If a supplied timeout elapses, the predicate throws, or the
subscription closes or enters a terminal error before the rows match.

**Parameters**

| Name       | Type                                | Description                                                                                                                    |
| ---------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `matches`  | `(rows: readonly Row[]) => boolean` | Predicate evaluated against each complete row snapshot.                                                                        |
| `timeout?` | `number`                            | Optional maximum wait in milliseconds. By default the promise remains pending until the rows match or the subscription closes. |

#### MaterializedLiveQuerySubscription.awaitTxId

```ts
awaitTxId(txid: string, timeout?: number): Promise<void>
```

Wait until this subscription has applied a PostgreSQL transaction.

Recently applied transaction IDs are retained so this also succeeds when
the batch arrives before the caller receives the mutation response.

**Remarks:** This does not determine whether a transaction committed, so pass only IDs
from transactions known to have committed.

**Throws:** If the timeout elapses, the transaction ID is invalid, or the
subscription fails or closes before applying the transaction.

**Parameters**

| Name       | Type     | Description                                                                                                                                                      |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `txid`     | `string` | PostgreSQL transaction ID as a decimal string.                                                                                                                   |
| `timeout?` | `number` | Optional maximum wait in milliseconds. By default the promise remains pending until the transaction arrives, the subscription fails, or the subscription closes. |

#### MaterializedLiveQuerySubscription.onChange

```ts
onChange(listener: (snapshot: LiveQuerySnapshot<Row>) => void): () => void
```

Observe row or lifecycle changes as complete snapshots.
The listener runs after complete-row replacements, incremental changes,
and state transitions.

**Returns:** A function that removes this listener.

**Parameters**

| Name       | Type                                         | Description |
| ---------- | -------------------------------------------- | ----------- |
| `listener` | `(snapshot: LiveQuerySnapshot<Row>) => void` |             |

#### MaterializedLiveQuerySubscription.onStateChange

```ts
onStateChange(listener: (state: LiveQueryState) => void): () => void
```

Observe lifecycle transitions.

**Returns:** A function that removes this listener.

**Parameters**

| Name       | Type                              | Description |
| ---------- | --------------------------------- | ----------- |
| `listener` | `(state: LiveQueryState) => void` |             |

#### MaterializedLiveQuerySubscription.onUpdate

```ts
onUpdate(listener: (update: RawLiveQueryUpdate<Row>) => void): () => void
```

Observe complete-row replacements and incremental changes through one
ordered update stream. Every affected materialized subscription has
already applied an update before its listener runs.

**Returns:** A function that removes this listener.

**Parameters**

| Name       | Type                                        | Description |
| ---------- | ------------------------------------------- | ----------- |
| `listener` | `(update: RawLiveQueryUpdate<Row>) => void` |             |

#### MaterializedLiveQuerySubscription.renew

```ts
renew(query: SealedLiveQuery<Row>): Promise<void>
```

Renew this logical subscription with a capability for the same exact query.
If the preceding subscription has expired, the client creates a new
wire subscription while preserving this object, its listeners, and any
retained rows. The replacement then produces a new authoritative result.

**Returns:** A promise that resolves after the proxy accepts the replacement.
Calling this while `stale` moves the subscription to `connecting`; a
subsequent authoritative result returns it to `live`.

**Throws:** If the replacement query fingerprint differs or renewal is rejected.

**Parameters**

| Name    | Type                   | Description |
| ------- | ---------------------- | ----------- |
| `query` | `SealedLiveQuery<Row>` |             |

### RawLiveQueryOptions

```ts
interface RawLiveQueryOptions
```

Options for a raw, non-materializing subscription.

#### Members

| Name          | Type             | Description                                                          |
| ------------- | ---------------- | -------------------------------------------------------------------- |
| `materialize` | `readonly false` | Disable SDK materialization and consume raw result updates directly. |

### RawLiveQueryRow

```ts
interface RawLiveQueryRow<Row>
```

A row in a complete raw result, paired with its opaque Realtime identity.

#### Members

| Name    | Type              | Description                                                     |
| ------- | ----------------- | --------------------------------------------------------------- |
| `row`   | `readonly Row`    | Decoded query row.                                              |
| `rowId` | `readonly string` | Opaque identity invalidated by the next complete `rows` update. |

### RawLiveQuerySubscription

```ts
interface RawLiveQuerySubscription<Row>
```

A live-query subscription that exposes ordered raw result updates.

#### Members

| Name                                                                                                           | Type                                                                  | Description                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`awaitTxId`](https://neon.com/docs/realtime/sdks/typescript#client-rawlivequerysubscriptionawaittxid)         | `(txid: string, timeout?: number) => Promise<void>`                   | Wait until this subscription has applied a PostgreSQL transaction. Recently applied transaction IDs are retained so this also succeeds when the batch arrives before the caller receives the mutation response.                                                                                 |
| `getState`                                                                                                     | `() => LiveQueryState`                                                | Return the complete current lifecycle state.                                                                                                                                                                                                                                                    |
| [`onStateChange`](https://neon.com/docs/realtime/sdks/typescript#client-rawlivequerysubscriptiononstatechange) | `(listener: (state: LiveQueryState) => void) => () => void`           | Observe lifecycle transitions.                                                                                                                                                                                                                                                                  |
| [`onUpdate`](https://neon.com/docs/realtime/sdks/typescript#client-rawlivequerysubscriptiononupdate)           | `(listener: (update: RawLiveQueryUpdate<Row>) => void) => () => void` | Observe complete-row replacements and incremental changes through one ordered update stream. Every affected materialized subscription has already applied an update before its listener runs.                                                                                                   |
| [`renew`](https://neon.com/docs/realtime/sdks/typescript#client-rawlivequerysubscriptionrenew)                 | `(query: SealedLiveQuery<Row>) => Promise<void>`                      | Renew this logical subscription with a capability for the same exact query. If the preceding subscription has expired, the client creates a new wire subscription while preserving this object, its listeners, and any retained rows. The replacement then produces a new authoritative result. |
| `unsubscribe`                                                                                                  | `() => void`                                                          | Permanently close this subscription and remove its listeners.                                                                                                                                                                                                                                   |

#### RawLiveQuerySubscription.awaitTxId

```ts
awaitTxId(txid: string, timeout?: number): Promise<void>
```

Wait until this subscription has applied a PostgreSQL transaction.

Recently applied transaction IDs are retained so this also succeeds when
the batch arrives before the caller receives the mutation response.

**Remarks:** This does not determine whether a transaction committed, so pass only IDs
from transactions known to have committed.

**Throws:** If the timeout elapses, the transaction ID is invalid, or the
subscription fails or closes before applying the transaction.

**Parameters**

| Name       | Type     | Description                                                                                                                                                      |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `txid`     | `string` | PostgreSQL transaction ID as a decimal string.                                                                                                                   |
| `timeout?` | `number` | Optional maximum wait in milliseconds. By default the promise remains pending until the transaction arrives, the subscription fails, or the subscription closes. |

#### RawLiveQuerySubscription.onStateChange

```ts
onStateChange(listener: (state: LiveQueryState) => void): () => void
```

Observe lifecycle transitions.

**Returns:** A function that removes this listener.

**Parameters**

| Name       | Type                              | Description |
| ---------- | --------------------------------- | ----------- |
| `listener` | `(state: LiveQueryState) => void` |             |

#### RawLiveQuerySubscription.onUpdate

```ts
onUpdate(listener: (update: RawLiveQueryUpdate<Row>) => void): () => void
```

Observe complete-row replacements and incremental changes through one
ordered update stream. Every affected materialized subscription has
already applied an update before its listener runs.

**Returns:** A function that removes this listener.

**Parameters**

| Name       | Type                                        | Description |
| ---------- | ------------------------------------------- | ----------- |
| `listener` | `(update: RawLiveQueryUpdate<Row>) => void` |             |

#### RawLiveQuerySubscription.renew

```ts
renew(query: SealedLiveQuery<Row>): Promise<void>
```

Renew this logical subscription with a capability for the same exact query.
If the preceding subscription has expired, the client creates a new
wire subscription while preserving this object, its listeners, and any
retained rows. The replacement then produces a new authoritative result.

**Returns:** A promise that resolves after the proxy accepts the replacement.
Calling this while `stale` moves the subscription to `connecting`; a
subsequent authoritative result returns it to `live`.

**Throws:** If the replacement query fingerprint differs or renewal is rejected.

**Parameters**

| Name    | Type                   | Description |
| ------- | ---------------------- | ----------- |
| `query` | `SealedLiveQuery<Row>` |             |

### RealtimeClient

```ts
interface RealtimeClient
```

A client that multiplexes independently disposable subscriptions.

#### Members

| Name                                                                                         | Type                                                                                                                                                                                                                                           | Description                                                        |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `close`                                                                                      | `() => void`                                                                                                                                                                                                                                   | Permanently close all subscriptions and the underlying WebSocket.  |
| [`subscribe`](https://neon.com/docs/realtime/sdks/typescript#client-realtimeclientsubscribe) | `<Row>(query: SealedLiveQuery<Row>, options?: MaterializedLiveQueryOptions<NoInferCompat<Row>>) => MaterializedLiveQuerySubscription<Row> & <Row>(query: SealedLiveQuery<Row>, options: RawLiveQueryOptions) => RawLiveQuerySubscription<Row>` | Start a materialized subscription, optionally with preloaded rows. |

#### RealtimeClient.subscribe

```ts
subscribe<Row>(query: SealedLiveQuery<Row>, options?: MaterializedLiveQueryOptions<NoInferCompat<Row>>): MaterializedLiveQuerySubscription<Row>
```

Start a materialized subscription, optionally with preloaded rows.

**Returns:** An independently disposable materialized subscription.

**Throws:** If the query is malformed or the client is closed.

**Parameters**

| Name       | Type                                               | Description                                                 |
| ---------- | -------------------------------------------------- | ----------------------------------------------------------- |
| `query`    | `SealedLiveQuery<Row>`                             | Short-lived capability returned by the application backend. |
| `options?` | `MaterializedLiveQueryOptions<NoInferCompat<Row>>` | Materialization and optional preloaded-row settings.        |

```ts
subscribe<Row>(query: SealedLiveQuery<Row>, options: RawLiveQueryOptions): RawLiveQuerySubscription<Row>
```

Start a raw subscription without retaining query rows in the SDK.

**Returns:** An independently disposable raw subscription.

**Throws:** If the query is malformed or the client is closed.

**Parameters**

| Name      | Type                   | Description                                                 |
| --------- | ---------------------- | ----------------------------------------------------------- |
| `query`   | `SealedLiveQuery<Row>` | Short-lived capability returned by the application backend. |
| `options` | `RawLiveQueryOptions`  | Set `materialize` to `false` to consume raw events.         |

### RealtimeClientOptions

```ts
interface RealtimeClientOptions
```

Configuration for a reusable Realtime browser client.

#### Members

| Name                | Type                                                                                                                  | Description                                                                                                                                                                                                                                                    |
| ------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `logger?`           | `readonly RealtimeLogger`                                                                                             | Structured diagnostic sink. It is called only for events enabled by `logLevel`; exceptions from the sink are ignored. Server-issued client warnings do not use this sink.                                                                                      |
| `logLevel?`         | `readonly RealtimeLogLevel`                                                                                           | Minimum client diagnostic level. The default, `silent`, emits no structured diagnostics. Server-issued client warnings are always written to `console.error` independently of this setting. When enabled without `logger`, entries are written to `console`.   |
| `parsers?`          | `readonly Readonly<Record<number, PostgreSQLBytesParser<unknown> \| PostgreSQLTextParser<unknown>> & BuiltInParsers>` | PostgreSQL result parsers keyed by type OID. These entries override [`nodePostgresParsers`](https://neon.com/docs/realtime/sdks/typescript#client-nodepostgresparsers). The client snapshots the object when it is created, so later mutations have no effect. |
| `url`               | `readonly string`                                                                                                     | Realtime proxy WebSocket URL, using `wss:` outside local development.                                                                                                                                                                                          |
| `webSocketFactory?` | `readonly WebSocketFactory`                                                                                           | Override how the client creates its WebSocket. This is primarily useful in runtimes such as React Native, whose WebSocket constructor accepts platform-specific connection options. In browsers, omit this option to use the built-in WebSocket constructor.   |

### WebSocketLike

```ts
interface WebSocketLike
```

Minimal WebSocket contract used by the Realtime client.

#### Members

| Name               | Type                                                                                                                                                                                                                              | Description                                                            |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `readyState`       | `readonly number`                                                                                                                                                                                                                 |                                                                        |
| `addEventListener` | `(type: "open", listener: () => void) => void & (type: "message", listener: (event: { readonly data: unknown }) => void) => void & (type: "close", listener: () => void) => void & (type: "error", listener: () => void) => void` |                                                                        |
| `close`            | `(code?: number, reason?: string) => void`                                                                                                                                                                                        |                                                                        |
| `send`             | `(data: string) => void`                                                                                                                                                                                                          |                                                                        |
| `terminate?`       | `() => void`                                                                                                                                                                                                                      | Immediately destroy the transport when the implementation supports it. |

### LiveQueryChange

```ts
type LiveQueryChange<Row> = { readonly row: Row; readonly rowId: string; readonly type: "upsert" } | { readonly rowId: string; readonly type: "remove" } | { readonly afterRowId: string | null; readonly rowId: string; readonly type: "move" }
```

A row upsert, removal, or sequential move in an atomic publication batch.

### LiveQuerySnapshot

```ts
type LiveQuerySnapshot<Row> = LiveQueryState & { data: readonly Row[] | undefined }
```

Materialized query rows paired with their atomic lifecycle state.

### LiveQueryState

```ts
type LiveQueryState = { readonly error: undefined; readonly status: "connecting" | "live" | "stale" | "closed" } | { readonly error: LiveQueryError; readonly status: "error" }
```

Atomic lifecycle state for a live-query subscription.

### PostgreSQLBytesParser

```ts
type PostgreSQLBytesParser<Value = unknown> = (value: Uint8Array) => Value
```

A parser for PostgreSQL `bytea`, transported as decoded bytes.

### PostgreSQLParserForOid

```ts
type PostgreSQLParserForOid<Oid extends number> = Oid extends typeof pgTypeOids.bytea ? PostgreSQLBytesParser : PostgreSQLTextParser
```

Parser input selected by the fixed Realtime OID/codec mapping.

### PostgreSQLParsers

```ts
type PostgreSQLParsers = Readonly<Record<number, PostgreSQLTextParser | PostgreSQLBytesParser> & BuiltInParsers>
```

A sparse collection of result parsers keyed by PostgreSQL type OID.

### PostgreSQLTextParser

```ts
type PostgreSQLTextParser<Value = unknown> = (value: string) => Value
```

A parser for a PostgreSQL value transported with the `pg_text` codec.

### RawLiveQueryUpdate

```ts
type RawLiveQueryUpdate<Row> = { rows: readonly RawLiveQueryRow<Row>[]; readonly type: "rows" } | { readonly batch: LiveQueryBatchInfo; changes: readonly LiveQueryChange<Row>[]; readonly type: "changes" }
```

One authoritative raw query-result update.

`rows` replaces the complete preceding result and invalidates its row-ID
namespace. `changes` applies incrementally to the current result.

### RealtimeLogEntry

```ts
type RealtimeLogEntry = { [Event in RealtimeLogEvent]: RealtimeLogEntryFor<Event> }[RealtimeLogEvent]
```

Structured client diagnostic passed to a configured logger.

Narrowing on `event` also narrows the metadata available on the entry.

### RealtimeLogEvent

```ts
type RealtimeLogEvent = keyof RealtimeLogEventDefinition
```

Stable name for one client diagnostic event.

### RealtimeLogger

```ts
type RealtimeLogger = (entry: RealtimeLogEntry) => void
```

Receives structured Realtime client diagnostics.

### RealtimeLogLevel

```ts
type RealtimeLogLevel = "silent" | "error" | "warn" | "info" | "debug"
```

Client-side diagnostic verbosity.

### WebSocketFactory

```ts
type WebSocketFactory = (url: string, protocols: string | string[]) => WebSocketLike
```

Create a WebSocket-compatible transport for the Realtime client.

### nodePostgresParsers

```ts
const nodePostgresParsers: PostgreSQLParsers
```

Core result parsers matching familiar node-postgres/Neon Serverless values.

Less-common and unknown OIDs are intentionally absent and fall back to their
exact PostgreSQL text. Known built-in array OIDs are decoded recursively by
the client using the active parser for their element OID.

### pgTypeOids

```ts
const pgTypeOids: Readonly<{ readonly bit: 1560; readonly bitArray: 1561; readonly bool: 16; readonly boolArray: 1000; readonly box: 603; readonly boxArray: 1020; readonly bpchar: 1042; readonly bpcharArray: 1014; readonly bytea: 17; readonly byteaArray: 1001; readonly char: 18; readonly charArray: 1002; readonly cidr: 650; readonly cidrArray: 651; readonly circle: 718; readonly circleArray: 719; readonly cstring: 2275; readonly cstringArray: 1263; readonly date: 1082; readonly dateArray: 1182; readonly float4: 700; readonly float4Array: 1021; readonly float8: 701; readonly float8Array: 1022; readonly inet: 869; readonly inetArray: 1041; readonly int2: 21; readonly int2Array: 1005; readonly int4: 23; readonly int4Array: 1007; readonly int8: 20; readonly int8Array: 1016; readonly interval: 1186; readonly intervalArray: 1187; readonly json: 114; readonly jsonArray: 199; readonly jsonb: 3802; readonly jsonbArray: 3807; readonly line: 628; readonly lineArray: 629; readonly lseg: 601; readonly lsegArray: 1018; readonly macaddr: 829; readonly macaddr8: 774; readonly macaddr8Array: 775; readonly macaddrArray: 1040; readonly money: 790; readonly moneyArray: 791; readonly name: 19; readonly nameArray: 1003; readonly numeric: 1700; readonly numericArray: 1231; readonly oid: 26; readonly oidArray: 1028; readonly path: 602; readonly pathArray: 1019; readonly pgLsn: 3220; readonly pgLsnArray: 3221; readonly point: 600; readonly pointArray: 1017; readonly polygon: 604; readonly polygonArray: 1027; readonly text: 25; readonly textArray: 1009; readonly time: 1083; readonly timeArray: 1183; readonly timestamp: 1114; readonly timestampArray: 1115; readonly timestamptz: 1184; readonly timestamptzArray: 1185; readonly timetz: 1266; readonly timetzArray: 1270; readonly uuid: 2950; readonly uuidArray: 2951; readonly varbit: 1562; readonly varbitArray: 1563; readonly varchar: 1043; readonly varcharArray: 1015; readonly xml: 142; readonly xmlArray: 143 }>
```

Stable PostgreSQL type OIDs used by the built-in Realtime parsers.

### postgresJsParsers

```ts
const postgresJsParsers: PostgreSQLParsers
```

Parsers that differ from the core defaults when matching Postgres.js.
Spread this partial preset into the client's `parsers` option.

### SealedLiveQuery

Re-exported from [Backend](https://neon.com/docs/realtime/sdks/typescript#backend-sealedlivequery).

## React

Import the React bindings from `@neon/realtime-react`. They run in your React frontend: [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider) shares one client, [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery) subscribes a component to a sealed query, and [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#react-userealtimeclient) returns the shared client. They're taught in the [React section](../guides/reactivity#react) of the reactivity guide.

**Import specifier** `@neon/realtime-react`

### Symbols

| Symbol                                                                                                | Kind       | Summary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider)           | Function   | Provide one shared Realtime client to descendant [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery) and [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#react-userealtimeclient) hooks. Create the client once for the browser application. The provider does not fetch sealed queries or close the client when it unmounts.                                                                                                                                                                         |
| [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery)                   | Function   | Subscribe to a sealed query and expose its materialized snapshot to React. The hook owns subscription cleanup.                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#react-userealtimeclient)         | Function   | Read the shared Realtime client from the nearest [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider). Use it alongside [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery) when a component needs the client itself: to pass it to `realtimeCollectionOptions()` from `@neon/realtime-tanstack`, or to call `subscribe()` with a sealed query directly. Subscriptions opened through `subscribe()` are not owned by React, so call `unsubscribe()` when they are no longer needed. |
| [`RealtimeProviderProps`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeproviderprops) | Interface  | Props accepted by [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider).                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| [`UseLiveQueryOptions`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequeryoptions)     | Interface  | Options for [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery).                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| [`UseLiveQueryResult`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequeryresult)       | Type alias | React-facing snapshot and lower-level utilities returned by `useLiveQuery()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| [`UseLiveQueryUtils`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequeryutils)         | Type alias | Stable imperative access to the hook's underlying materialized subscription. Cleanup remains owned by React, so `unsubscribe()` is intentionally omitted.                                                                                                                                                                                                                                                                                                                                                                                                  |

### RealtimeProvider

```ts
function RealtimeProvider(props: RealtimeProviderProps): ReactElement
```

Provide one shared Realtime client to descendant [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery) and
[`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#react-userealtimeclient) hooks.

Create the client once for the browser application. The provider does not
fetch sealed queries or close the client when it unmounts.

**Returns:** A context provider for Realtime hooks.

#### Parameters

| Name    | Type                    | Description                              |
| ------- | ----------------------- | ---------------------------------------- |
| `props` | `RealtimeProviderProps` | Shared client and descendant React tree. |

#### Returns

`ReactElement`

### useLiveQuery

```ts
function useLiveQuery<Row>(query: SealedLiveQuery<Row>, options: UseLiveQueryOptions<NoInferCompat<Row>> = {}): UseLiveQueryResult<Row>
```

Subscribe to a sealed query and expose its materialized snapshot to
React. The hook owns subscription cleanup.

**Returns:** The current rows and lifecycle state plus stable subscription
utilities.

**Throws:** If used outside a [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider).

#### Type parameters

| Name  | Default | Description                  |
| ----- | ------- | ---------------------------- |
| `Row` |         | Row inferred from the query. |

#### Parameters

| Name      | Type                                      | Description                                              |
| --------- | ----------------------------------------- | -------------------------------------------------------- |
| `query`   | `SealedLiveQuery<Row>`                    | Capability obtained from the application backend.        |
| `options` | `UseLiveQueryOptions<NoInferCompat<Row>>` | Optional preloaded rows and capability-refresh callback. |

#### Returns

`UseLiveQueryResult<Row>`

### useRealtimeClient

```ts
function useRealtimeClient(): RealtimeClient
```

Read the shared Realtime client from the nearest [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider).

Use it alongside [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery) when a component needs the client
itself: to pass it to `realtimeCollectionOptions()` from
`@neon/realtime-tanstack`, or to call `subscribe()` with a sealed query
directly. Subscriptions opened through `subscribe()` are not owned by React,
so call `unsubscribe()` when they are no longer needed.

**Returns:** The client passed to the nearest provider.

**Throws:** If used outside a [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider).

**Example**

```tsx
import type { SealedLiveQuery } from "@neon/realtime/client";
import { useRealtimeClient } from "@neon/realtime-react";
import { realtimeCollectionOptions } from "@neon/realtime-tanstack";
import { createCollection } from "@tanstack/db";
import { useMemo } from "react";

interface Todo {
  id: string;
  title: string;
}

function useTodos(query: SealedLiveQuery<Todo>) {
  const client = useRealtimeClient();
  return useMemo(
    () =>
      createCollection(realtimeCollectionOptions({
        client,
        query,
        getKey: (todo) => todo.id,
      })),
    [client, query],
  );
}
```

#### Returns

`RealtimeClient`

### RealtimeProviderProps

```ts
interface RealtimeProviderProps
```

Props accepted by [`RealtimeProvider`](https://neon.com/docs/realtime/sdks/typescript#react-realtimeprovider).

#### Members

| Name       | Type                      | Description                                                                                                                                                                                                       |
| ---------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children` | `readonly ReactNode`      | React subtree that may call [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery) or [`useRealtimeClient`](https://neon.com/docs/realtime/sdks/typescript#react-userealtimeclient). |
| `client`   | `readonly RealtimeClient` | Shared browser client made available to descendant hooks.                                                                                                                                                         |

### UseLiveQueryOptions

```ts
interface UseLiveQueryOptions<Row>
```

Options for [`useLiveQuery`](https://neon.com/docs/realtime/sdks/typescript#react-uselivequery).

#### Members

| Name            | Type                                           | Description                                                                                                                                        |
| --------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `initialData?`  | `readonly Row[]`                               | Decoded rows exposed immediately, including during server rendering. Restore values changed by transport serialization before passing them here.   |
| `refreshQuery?` | `readonly () => Promise<SealedLiveQuery<Row>>` | Obtain a replacement capability for the same exact query before expiry. Transient failures are retried while the current capability remains valid. |

### UseLiveQueryResult

```ts
type UseLiveQueryResult<Row> = LiveQuerySnapshot<Row> & { readonly utils: UseLiveQueryUtils<Row> }
```

React-facing snapshot and lower-level utilities returned by `useLiveQuery()`.

### UseLiveQueryUtils

```ts
type UseLiveQueryUtils<Row> = Omit<MaterializedLiveQuerySubscription<Row>, "unsubscribe">
```

Stable imperative access to the hook's underlying materialized subscription.

Cleanup remains owned by React, so `unsubscribe()` is intentionally omitted.

## TanStack DB

Import the TanStack DB adapter from `@neon/realtime-tanstack`. It runs in the browser, where [`realtimeCollectionOptions`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionoptions) turns a sealed query into a TanStack DB collection. It's taught in the [TanStack DB section](../guides/reactivity#tanstack-db) of the reactivity guide. The mutations guide covers [optimistic writes](../guides/mutations#with-tanstack-db-collections), and the SSR guide covers [hydration](../guides/ssr#with-tanstack-db).

**Import specifier** `@neon/realtime-tanstack`

### Symbols

| Symbol                                                                                                                | Kind       | Summary                                                                                                                                                                                                                                                                                                                        |
| --------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`realtimeCollectionOptions`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionoptions)   | Function   | Create TanStack DB collection options backed by a raw live-query subscription. Complete-row replacements and committed change batches are applied atomically. This is an unordered keyed collection: move operations do not change membership or values and are ignored. Use core materialized subscriptions for server order. |
| [`RealtimeCollectionConfig`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionconfig)     | Interface  | Configuration for a Realtime-backed TanStack DB collection. The adapter owns `sync`, uses eager synchronization, and supplies its own collection utilities.                                                                                                                                                                    |
| [`RealtimeCollectionUtils`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionutils)       | Interface  | Utilities attached to a Realtime-backed TanStack DB collection.                                                                                                                                                                                                                                                                |
| [`RealtimeCollectionOptions`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionoptions-2) | Type alias | TanStack DB collection options produced by [`realtimeCollectionOptions`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionoptions).                                                                                                                                                                |

### realtimeCollectionOptions

```ts
function realtimeCollectionOptions<Row extends object, Key extends string | number = string | number, Schema extends StandardSchemaV1<unknown, unknown> = never>(config: RealtimeCollectionConfig<NoInferCompat<Row>, Key, Schema> & { readonly query: SealedLiveQuery<Row> }): RealtimeCollectionOptions<Row, Key, Schema>
```

Create TanStack DB collection options backed by a raw live-query subscription.
Complete-row replacements and committed change batches are applied atomically.
This is an unordered keyed collection: move operations do not change membership
or values and are ignored. Use core materialized subscriptions for server order.

**Returns:** Collection options to pass to TanStack DB's `createCollection()`.

#### Type parameters

| Name     | Default            | Description                                   |
| -------- | ------------------ | --------------------------------------------- |
| `Row`    |                    | Object row synchronized into the collection.  |
| `Key`    | `string \| number` | Stable key returned by `getKey`.              |
| `Schema` | `never`            | Optional Standard Schema used by TanStack DB. |

#### Parameters

| Name     | Type                                                                                                   | Description                                                                   |
| -------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `config` | `RealtimeCollectionConfig<NoInferCompat<Row>, Key, Schema> & { readonly query: SealedLiveQuery<Row> }` | Live-query subscription settings and ordinary TanStack DB collection options. |

#### Returns

`RealtimeCollectionOptions<Row, Key, Schema>`

### RealtimeCollectionConfig

```ts
interface RealtimeCollectionConfig<Row extends object, Key extends string | number = string | number, Schema extends StandardSchemaV1 = never> extends Omit<BaseCollectionConfig<Row, Key, Schema, RealtimeCollectionUtils, void>, "syncMode" | "utils">
```

Configuration for a Realtime-backed TanStack DB collection.

The adapter owns `sync`, uses eager synchronization, and supplies its own
collection utilities.

#### Members

| Name                                                                                                                       | Type                                                        | Description                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`autoIndex?`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionconfigautoindex)               | `"off" \| "eager"`                                          | Auto-indexing mode for the collection. When enabled, indexes will be automatically created for simple where expressions.                                                                                                                                                                                                                                                                                               |
| `client`                                                                                                                   | `readonly RealtimeClient`                                   | Reusable low-level Realtime client.                                                                                                                                                                                                                                                                                                                                                                                    |
| [`compare?`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionconfigcompare)                   | `(x: Row, y: Row) => number`                                | Optional function to compare two items. This is used to order the items in the collection.                                                                                                                                                                                                                                                                                                                             |
| [`defaultIndexType?`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionconfigdefaultindextype) | `IndexConstructor<Key>`                                     | Default index type to use when creating indexes without an explicit type. Required for auto-indexing. Import from '@tanstack/db'.                                                                                                                                                                                                                                                                                      |
| `defaultStringCollation?`                                                                                                  | `StringCollationConfig`                                     | Specifies how to compare data in the collection. This should be configured to match data ordering on the backend. E.g., when using the Electric DB collection these options should match the database's collation settings.                                                                                                                                                                                            |
| `gcTime?`                                                                                                                  | `number`                                                    | Time in milliseconds after which the collection will be garbage collected when it has no active subscribers. Defaults to 5 minutes (300000ms).                                                                                                                                                                                                                                                                         |
| `getKey`                                                                                                                   | `readonly (row: Row) => Key`                                | Derive the stable unique TanStack DB key for a row.                                                                                                                                                                                                                                                                                                                                                                    |
| `id?`                                                                                                                      | `string`                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [`onDelete?`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionconfigondelete)                 | `DeleteMutationFn<Row, Key, RealtimeCollectionUtils, void>` | Optional asynchronous handler function called before a delete operation                                                                                                                                                                                                                                                                                                                                                |
| [`onInsert?`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionconfigoninsert)                 | `InsertMutationFn<Row, Key, RealtimeCollectionUtils, void>` | Optional asynchronous handler function called before an insert operation                                                                                                                                                                                                                                                                                                                                               |
| [`onUpdate?`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionconfigonupdate)                 | `UpdateMutationFn<Row, Key, RealtimeCollectionUtils, void>` | Optional asynchronous handler function called before an update operation                                                                                                                                                                                                                                                                                                                                               |
| `query`                                                                                                                    | `readonly SealedLiveQuery<Row>`                             | Initial query for the exact query backing this collection.                                                                                                                                                                                                                                                                                                                                                             |
| `refreshQuery?`                                                                                                            | `readonly () => Promise<SealedLiveQuery<Row>>`              | Obtain a replacement capability for the same exact query before expiry. Transient failures are retried while the current capability remains valid.                                                                                                                                                                                                                                                                     |
| `schema?`                                                                                                                  | `Schema`                                                    |                                                                                                                                                                                                                                                                                                                                                                                                                        |
| [`startSync?`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionconfigstartsync)               | `boolean`                                                   | Whether to eagerly start syncing on collection creation. When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches. Note: Even with startSync=true, collections will pause syncing when there are no active subscribers (typically when components querying the collection unmount), resuming when new subscribers attach. This preserves normal staleTime/gcTime behavior. |

#### RealtimeCollectionConfig.autoIndex

```ts
autoIndex?: "off" | "eager"
```

Auto-indexing mode for the collection.
When enabled, indexes will be automatically created for simple where expressions.

**Default**

```ts
"off"
```

- "off": No automatic indexing (default). Use explicit indexes for better bundle size.
- "eager": Automatically create indexes for simple where expressions in subscribeChanges.
  Requires setting defaultIndexType.

#### RealtimeCollectionConfig.compare

```ts
compare?: (x: Row, y: Row) => number
```

Optional function to compare two items.
This is used to order the items in the collection.

**Example**

```ts
// For a collection with a 'createdAt' field
compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()
```

#### RealtimeCollectionConfig.defaultIndexType

```ts
defaultIndexType?: IndexConstructor<Key>
```

Default index type to use when creating indexes without an explicit type.
Required for auto-indexing. Import from '@tanstack/db'.

**Example**

```ts
import { BasicIndex } from '@tanstack/db'
const collection = createCollection({
  defaultIndexType: BasicIndex,
  autoIndex: 'eager',
  // ...
})
```

#### RealtimeCollectionConfig.onDelete

```ts
onDelete?: DeleteMutationFn<Row, Key, RealtimeCollectionUtils, void>
```

Optional asynchronous handler function called before a delete operation

**Parameter `params`:** Object containing transaction and collection information

**Returns:** Promise resolving to any value

**Example**

```ts
// Basic delete handler
onDelete: async ({ transaction, collection }) => {
  const deletedKey = transaction.mutations[0].key
  await api.deleteTodo(deletedKey)
}
```

**Example**

```ts
// Delete handler with multiple items
onDelete: async ({ transaction, collection }) => {
  const keysToDelete = transaction.mutations.map(m => m.key)
  await api.deleteTodos(keysToDelete)
}
```

**Example**

```ts
// Delete handler with confirmation
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  const shouldDelete = await confirmDeletion(mutation.original)
  if (!shouldDelete) {
    throw new Error('Delete cancelled by user')
  }
  await api.deleteTodo(mutation.original.id)
}
```

**Example**

```ts
// Delete handler with optimistic rollback
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  try {
    await api.deleteTodo(mutation.original.id)
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Delete failed, rolling back:', error)
    throw error
  }
}
```

#### RealtimeCollectionConfig.onInsert

```ts
onInsert?: InsertMutationFn<Row, Key, RealtimeCollectionUtils, void>
```

Optional asynchronous handler function called before an insert operation

**Parameter `params`:** Object containing transaction and collection information

**Returns:** Promise resolving to any value

**Example**

```ts
// Basic insert handler
onInsert: async ({ transaction, collection }) => {
  const newItem = transaction.mutations[0].modified
  await api.createTodo(newItem)
}
```

**Example**

```ts
// Insert handler with multiple items
onInsert: async ({ transaction, collection }) => {
  const items = transaction.mutations.map(m => m.modified)
  await api.createTodos(items)
}
```

**Example**

```ts
// Insert handler with error handling
onInsert: async ({ transaction, collection }) => {
  try {
    const newItem = transaction.mutations[0].modified
    const result = await api.createTodo(newItem)
    return result
  } catch (error) {
    console.error('Insert failed:', error)
    throw error // This will cause the transaction to fail
  }
}
```

**Example**

```ts
// Insert handler with metadata
onInsert: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.createTodo(mutation.modified, {
    source: mutation.metadata?.source,
    timestamp: mutation.createdAt
  })
}
```

#### RealtimeCollectionConfig.onUpdate

```ts
onUpdate?: UpdateMutationFn<Row, Key, RealtimeCollectionUtils, void>
```

Optional asynchronous handler function called before an update operation

**Parameter `params`:** Object containing transaction and collection information

**Returns:** Promise resolving to any value

**Example**

```ts
// Basic update handler
onUpdate: async ({ transaction, collection }) => {
  const updatedItem = transaction.mutations[0].modified
  await api.updateTodo(updatedItem.id, updatedItem)
}
```

**Example**

```ts
// Update handler with partial updates
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  const changes = mutation.changes // Only the changed fields
  await api.updateTodo(mutation.original.id, changes)
}
```

**Example**

```ts
// Update handler with multiple items
onUpdate: async ({ transaction, collection }) => {
  const updates = transaction.mutations.map(m => ({
    id: m.key,
    changes: m.changes
  }))
  await api.updateTodos(updates)
}
```

**Example**

```ts
// Update handler with optimistic rollback
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  try {
    await api.updateTodo(mutation.original.id, mutation.changes)
  } catch (error) {
    // Transaction will automatically rollback optimistic changes
    console.error('Update failed, rolling back:', error)
    throw error
  }
}
```

#### RealtimeCollectionConfig.startSync

```ts
startSync?: boolean
```

Whether to eagerly start syncing on collection creation.
When true, syncing begins immediately. When false, syncing starts when the first subscriber attaches.

Note: Even with startSync=true, collections will pause syncing when there are no active
subscribers (typically when components querying the collection unmount), resuming when new
subscribers attach. This preserves normal staleTime/gcTime behavior.

**Default**

```ts
false
```

### RealtimeCollectionUtils

```ts
interface RealtimeCollectionUtils extends UtilsRecord
```

Utilities attached to a Realtime-backed TanStack DB collection.

#### Members

| Name                                                                                                       | Type                                                   | Description                                                                                                                                                   |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`awaitTxId`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionutilsawaittxid) | `(txid: string, timeout?: number) => Promise<boolean>` | Wait until this query has processed a known committed PostgreSQL transaction. Covered row changes enter TanStack DB's causal sync queue before this resolves. |
| `[key: string]`                                                                                            | `any`                                                  |                                                                                                                                                               |

#### RealtimeCollectionUtils.awaitTxId

```ts
awaitTxId(txid: string, timeout?: number): Promise<boolean>
```

Wait until this query has processed a known committed PostgreSQL transaction.
Covered row changes enter TanStack DB's causal sync queue before this resolves.

**Remarks:** This does not determine whether a transaction committed, so pass only IDs
from transactions known to have committed.

**Throws:** If a supplied timeout elapses or the collection is cleaned up.

**Parameters**

| Name       | Type     | Description                                                                                                                                   |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `txid`     | `string` | PostgreSQL transaction ID as a decimal string.                                                                                                |
| `timeout?` | `number` | Optional maximum wait in milliseconds. By default, the promise remains pending until the transaction arrives or the collection is cleaned up. |

### RealtimeCollectionOptions

```ts
type RealtimeCollectionOptions<Row extends object, Key extends string | number, Schema extends StandardSchemaV1> = Omit<CollectionConfig<Row, Key, Schema, RealtimeCollectionUtils>, "utils"> & { readonly utils: RealtimeCollectionUtils }
```

TanStack DB collection options produced by [`realtimeCollectionOptions`](https://neon.com/docs/realtime/sdks/typescript#tanstack-db-realtimecollectionoptions).

## Drizzle

Import the Drizzle adapter from `@neon/realtime-drizzle`. It runs on your server: pass `drizzleAdapter()` as the `adapter` option to `createRealtime()`, then seal Drizzle selects like any other query. It's taught in [Using a query builder or ORM](../guides/queries#using-a-query-builder-or-orm), and the [Drizzle example](../examples/drizzle) goes further.

**Import specifier** `@neon/realtime-drizzle`

### Symbols

| Symbol                                                                                    | Kind     | Summary                                                                                                                                                                                                                                                                            |
| ----------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`drizzleAdapter`](https://neon.com/docs/realtime/sdks/typescript#drizzle-drizzleadapter) | Function | Prepare concrete Drizzle PostgreSQL selects as live queries. Drizzle supplies parameterized SQL and driver-ready values. Every parameter uses OID `0`, allowing PostgreSQL to infer its type from SQL context. The proxy returns result metadata when it accepts the subscription. |

### drizzleAdapter

```ts
function drizzleAdapter(): RealtimeAdapter<ConcretePgSelectQuery>
```

Prepare concrete Drizzle PostgreSQL selects as live queries.

Drizzle supplies parameterized SQL and driver-ready values. Every parameter
uses OID `0`, allowing PostgreSQL to infer its type from SQL context. The
proxy returns result metadata when it accepts the subscription.

**Returns:** An adapter to pass to `createRealtime()` on the application backend.

#### Returns

`RealtimeAdapter<ConcretePgSelectQuery>`

### Drizzle client

Import `drizzleParsers` from `@neon/realtime-drizzle/client`. It runs in the browser: spread it into the client's `parsers` option so dates and timestamps decode the way Drizzle decodes them. The [Drizzle example](../examples/drizzle) shows it in use.

**Import specifier** `@neon/realtime-drizzle/client`

### Symbols

| Symbol                                                                                           | Kind     | Summary                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`drizzleParsers`](https://neon.com/docs/realtime/sdks/typescript#drizzle-client-drizzleparsers) | Variable | Parser overrides for Drizzle-compatible hydrated values. PostgreSQL `date` remains a string and zone-less `timestamp` is interpreted as UTC, matching Drizzle's default PostgreSQL column modes. Spread this preset into `createRealtimeClient({ parsers })`. Per-column Drizzle modes are intentionally outside this OID-only compatibility layer. |

### drizzleParsers

```ts
const drizzleParsers: PostgreSQLParsers
```

Parser overrides for Drizzle-compatible hydrated values.

PostgreSQL `date` remains a string and zone-less `timestamp` is interpreted
as UTC, matching Drizzle's default PostgreSQL column modes. Spread this
preset into `createRealtimeClient({ parsers })`. Per-column Drizzle modes are
intentionally outside this OID-only compatibility layer.

## Kysely

Import the Kysely adapter from `@neon/realtime-kysely`. It runs on your server: pass `kyselyAdapter()` as the `adapter` option to `createRealtime()`, then seal Kysely selects like any other query. It's taught in [Using a query builder or ORM](../guides/queries#using-a-query-builder-or-orm), and the [Kysely example](../examples/kysely) goes further.

**Import specifier** `@neon/realtime-kysely`

### Symbols

| Symbol                                                                                 | Kind     | Summary                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`kyselyAdapter`](https://neon.com/docs/realtime/sdks/typescript#kysely-kyselyadapter) | Function | Prepare concrete Kysely selects as live queries. The adapter compiles Kysely's operation tree with its PostgreSQL compiler, then encodes the raw parameters using node-postgres-compatible rules. It never connects to or executes against the configured Kysely database. |

### kyselyAdapter

```ts
function kyselyAdapter(): RealtimeAdapter<KyselySelectQuery>
```

Prepare concrete Kysely selects as live queries.

The adapter compiles Kysely's operation tree with its PostgreSQL compiler,
then encodes the raw parameters using node-postgres-compatible rules. It
never connects to or executes against the configured Kysely database.

**Returns:** An adapter to pass to `createRealtime()` on the application backend.

#### Returns

`RealtimeAdapter<KyselySelectQuery>`

--- [Document source](https://neon.com/docs/reference/api.md) ---

# Neon API Reference

Base URL: https://console.neon.tech/api/v2
Auth: `Authorization: Bearer $NEON_API_KEY`

Interface-specific indexes:
- [API endpoint index](https://neon.com/docs/reference/api.md): all endpoints grouped by resource, each with curl and SDK examples
- [Neon CLI](https://neon.com/docs/cli.md): Neon CLI commands, options, and usage
- [OpenAPI spec](https://neon.com/api_spec/release/v2.json): machine-readable schemas for request/response validation and codegen

## AI Gateway

[All ai-gateway endpoints](https://neon.com/docs/reference/api/ai-gateway.md)

- [Get branch AI Gateway endpoint](https://neon.com/docs/reference/api/ai-gateway/get-project-branch-ai-gateway.md) `GET /projects/{project_id}/branches/{branch_id}/ai_gateway`

## API Keys

[All api-keys endpoints](https://neon.com/docs/reference/api/api-keys.md)

- [Create API key](https://neon.com/docs/reference/api/api-keys/create-api-key.md) `POST /api_keys`
- [List API keys](https://neon.com/docs/reference/api/api-keys/list-api-keys.md) `GET /api_keys`
- [Revoke API key](https://neon.com/docs/reference/api/api-keys/revoke-api-key.md) `DELETE /api_keys/{key_id}`

## Authentication

[All auth endpoints](https://neon.com/docs/reference/api/auth.md)

- [Add an OAuth provider](https://neon.com/docs/reference/api/auth/add-branch-neon-auth-oauth-provider.md) `POST /projects/{project_id}/branches/{branch_id}/auth/oauth_providers`
- [Add domain to redirect_uri whitelist](https://neon.com/docs/reference/api/auth/add-branch-neon-auth-trusted-domain.md) `POST /projects/{project_id}/branches/{branch_id}/auth/domains`
- [Create an OAuth client](https://neon.com/docs/reference/api/auth/create-neon-auth-o-auth-client.md) `POST /projects/{project_id}/branches/{branch_id}/auth/oauth-provider/clients`
- [Create new auth user](https://neon.com/docs/reference/api/auth/create-branch-neon-auth-new-user.md) `POST /projects/{project_id}/branches/{branch_id}/auth/users`
- [Delete an OAuth client](https://neon.com/docs/reference/api/auth/delete-neon-auth-o-auth-client.md) `DELETE /projects/{project_id}/branches/{branch_id}/auth/oauth-provider/clients/{client_id}`
- [Delete auth user](https://neon.com/docs/reference/api/auth/delete-branch-neon-auth-user.md) `DELETE /projects/{project_id}/branches/{branch_id}/auth/users/{auth_user_id}`
- [Delete domain from redirect_uri whitelist](https://neon.com/docs/reference/api/auth/delete-branch-neon-auth-trusted-domain.md) `DELETE /projects/{project_id}/branches/{branch_id}/auth/domains`
- [Delete OAuth provider](https://neon.com/docs/reference/api/auth/delete-branch-neon-auth-oauth-provider.md) `DELETE /projects/{project_id}/branches/{branch_id}/auth/oauth_providers/{oauth_provider_id}`
- [Disable Neon Auth for the branch](https://neon.com/docs/reference/api/auth/disable-neon-auth.md) `DELETE /projects/{project_id}/branches/{branch_id}/auth`
- [Enable Neon Auth for the branch](https://neon.com/docs/reference/api/auth/create-neon-auth.md) `POST /projects/{project_id}/branches/{branch_id}/auth`
- [List domains in redirect_uri whitelist](https://neon.com/docs/reference/api/auth/list-branch-neon-auth-trusted-domains.md) `GET /projects/{project_id}/branches/{branch_id}/auth/domains`
- [List OAuth clients](https://neon.com/docs/reference/api/auth/list-neon-auth-o-auth-clients.md) `GET /projects/{project_id}/branches/{branch_id}/auth/oauth-provider/clients`
- [List OAuth providers for the branch](https://neon.com/docs/reference/api/auth/list-branch-neon-auth-oauth-providers.md) `GET /projects/{project_id}/branches/{branch_id}/auth/oauth_providers`
- [Retrieve an OAuth client](https://neon.com/docs/reference/api/auth/get-neon-auth-o-auth-client.md) `GET /projects/{project_id}/branches/{branch_id}/auth/oauth-provider/clients/{client_id}`
- [Retrieve email and password configuration](https://neon.com/docs/reference/api/auth/get-neon-auth-email-and-password-config.md) `GET /projects/{project_id}/branches/{branch_id}/auth/email_and_password`
- [Retrieve email provider configuration](https://neon.com/docs/reference/api/auth/get-neon-auth-email-provider.md) `GET /projects/{project_id}/branches/{branch_id}/auth/email_provider`
- [Retrieve localhost allow setting](https://neon.com/docs/reference/api/auth/get-neon-auth-allow-localhost.md) `GET /projects/{project_id}/branches/{branch_id}/auth/allow_localhost`
- [Retrieve Neon Auth details for the branch](https://neon.com/docs/reference/api/auth/get-neon-auth.md) `GET /projects/{project_id}/branches/{branch_id}/auth`
- [Retrieve Neon Auth plugin configurations](https://neon.com/docs/reference/api/auth/get-neon-auth-plugin-configs.md) `GET /projects/{project_id}/branches/{branch_id}/auth/plugins`
- [Retrieve Neon Auth webhook configuration](https://neon.com/docs/reference/api/auth/get-neon-auth-webhook-config.md) `GET /projects/{project_id}/branches/{branch_id}/auth/webhooks`
- [Retrieve OAuth provider plugin configuration](https://neon.com/docs/reference/api/auth/get-neon-auth-o-auth-provider-plugin.md) `GET /projects/{project_id}/branches/{branch_id}/auth/plugins/oauth-provider`
- [Retrieve phone number plugin configuration](https://neon.com/docs/reference/api/auth/get-neon-auth-phone-number-plugin.md) `GET /projects/{project_id}/branches/{branch_id}/auth/plugins/phone-number`
- [Rotate an OAuth client secret](https://neon.com/docs/reference/api/auth/rotate-neon-auth-o-auth-client-secret.md) `POST /projects/{project_id}/branches/{branch_id}/auth/oauth-provider/clients/{client_id}/rotate_secret`
- [Send test email using the saved email provider](https://neon.com/docs/reference/api/auth/send-neon-auth-email-provider-test.md) `POST /projects/{project_id}/branches/{branch_id}/auth/email_provider/test`
- [Update an OAuth client](https://neon.com/docs/reference/api/auth/update-neon-auth-o-auth-client.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/oauth-provider/clients/{client_id}`
- [Update auth configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-config.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/config`
- [Update auth user role](https://neon.com/docs/reference/api/auth/update-neon-auth-user-role.md) `PUT /projects/{project_id}/branches/{branch_id}/auth/users/{auth_user_id}/role`
- [Update email and password configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-email-and-password-config.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/email_and_password`
- [Update email provider configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-email-provider.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/email_provider`
- [Update localhost allow setting](https://neon.com/docs/reference/api/auth/update-neon-auth-allow-localhost.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/allow_localhost`
- [Update magic link plugin configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-magic-link-plugin.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/plugins/magic-link`
- [Update Neon Auth logs export setting](https://neon.com/docs/reference/api/auth/update-neon-auth-logs-export.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/logs_export`
- [Update Neon Auth webhook configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-webhook-config.md) `PUT /projects/{project_id}/branches/{branch_id}/auth/webhooks`
- [Update OAuth provider](https://neon.com/docs/reference/api/auth/update-branch-neon-auth-oauth-provider.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/oauth_providers/{oauth_provider_id}`
- [Update OAuth provider plugin configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-o-auth-provider-plugin.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/plugins/oauth-provider`
- [Update organization plugin configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-organization-plugin.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/plugins/organization`
- [Update phone number plugin configuration](https://neon.com/docs/reference/api/auth/update-neon-auth-phone-number-plugin.md) `PATCH /projects/{project_id}/branches/{branch_id}/auth/plugins/phone-number`
- [Send test email](https://neon.com/docs/reference/api/auth/send-neon-auth-test-email.md) `POST /projects/{project_id}/branches/{branch_id}/auth/send_test_email`

## Branches

[All branches endpoints](https://neon.com/docs/reference/api/branches.md)

- [Compare database schema](https://neon.com/docs/reference/api/branches/get-project-branch-schema-comparison.md) `GET /projects/{project_id}/branches/{branch_id}/compare_schema`
- [Create anonymized branch](https://neon.com/docs/reference/api/branches/create-project-branch-anonymized.md) `POST /projects/{project_id}/branch_anonymized`
- [Create branch](https://neon.com/docs/reference/api/branches/create-project-branch.md) `POST /projects/{project_id}/branches`
- [Create database](https://neon.com/docs/reference/api/branches/create-project-branch-database.md) `POST /projects/{project_id}/branches/{branch_id}/databases`
- [Create role](https://neon.com/docs/reference/api/branches/create-project-branch-role.md) `POST /projects/{project_id}/branches/{branch_id}/roles`
- [Delete branch](https://neon.com/docs/reference/api/branches/delete-project-branch.md) `DELETE /projects/{project_id}/branches/{branch_id}`
- [Delete database](https://neon.com/docs/reference/api/branches/delete-project-branch-database.md) `DELETE /projects/{project_id}/branches/{branch_id}/databases/{database_name}`
- [Delete role](https://neon.com/docs/reference/api/branches/delete-project-branch-role.md) `DELETE /projects/{project_id}/branches/{branch_id}/roles/{role_name}`
- [Finalize branch restore from snapshot](https://neon.com/docs/reference/api/branches/finalize-restore-branch.md) `POST /projects/{project_id}/branches/{branch_id}/finalize_restore`
- [List branch endpoints](https://neon.com/docs/reference/api/branches/list-project-branch-endpoints.md) `GET /projects/{project_id}/branches/{branch_id}/endpoints`
- [List branches](https://neon.com/docs/reference/api/branches/list-project-branches.md) `GET /projects/{project_id}/branches`
- [List databases](https://neon.com/docs/reference/api/branches/list-project-branch-databases.md) `GET /projects/{project_id}/branches/{branch_id}/databases`
- [List roles](https://neon.com/docs/reference/api/branches/list-project-branch-roles.md) `GET /projects/{project_id}/branches/{branch_id}/roles`
- [Reset role password](https://neon.com/docs/reference/api/branches/reset-project-branch-role-password.md) `POST /projects/{project_id}/branches/{branch_id}/roles/{role_name}/reset_password`
- [Restore branch to a historical state](https://neon.com/docs/reference/api/branches/restore-project-branch.md) `POST /projects/{project_id}/branches/{branch_id}/restore`
- [Retrieve anonymized branch status](https://neon.com/docs/reference/api/branches/get-anonymized-branch-status.md) `GET /projects/{project_id}/branches/{branch_id}/anonymized_status`
- [Retrieve branch details](https://neon.com/docs/reference/api/branches/get-project-branch.md) `GET /projects/{project_id}/branches/{branch_id}`
- [Retrieve database details](https://neon.com/docs/reference/api/branches/get-project-branch-database.md) `GET /projects/{project_id}/branches/{branch_id}/databases/{database_name}`
- [Retrieve database schema](https://neon.com/docs/reference/api/branches/get-project-branch-schema.md) `GET /projects/{project_id}/branches/{branch_id}/schema`
- [Retrieve masking rules](https://neon.com/docs/reference/api/branches/get-masking-rules.md) `GET /projects/{project_id}/branches/{branch_id}/masking_rules`
- [Retrieve number of branches](https://neon.com/docs/reference/api/branches/count-project-branches.md) `GET /projects/{project_id}/branches/count`
- [Retrieve role details](https://neon.com/docs/reference/api/branches/get-project-branch-role.md) `GET /projects/{project_id}/branches/{branch_id}/roles/{role_name}`
- [Retrieve role password](https://neon.com/docs/reference/api/branches/get-project-branch-role-password.md) `GET /projects/{project_id}/branches/{branch_id}/roles/{role_name}/reveal_password`
- [Set branch as default](https://neon.com/docs/reference/api/branches/set-default-project-branch.md) `POST /projects/{project_id}/branches/{branch_id}/set_as_default`
- [Start anonymization](https://neon.com/docs/reference/api/branches/start-anonymization.md) `POST /projects/{project_id}/branches/{branch_id}/anonymize`
- [Update branch](https://neon.com/docs/reference/api/branches/update-project-branch.md) `PATCH /projects/{project_id}/branches/{branch_id}`
- [Update database](https://neon.com/docs/reference/api/branches/update-project-branch-database.md) `PATCH /projects/{project_id}/branches/{branch_id}/databases/{database_name}`
- [Update masking rules](https://neon.com/docs/reference/api/branches/update-masking-rules.md) `PATCH /projects/{project_id}/branches/{branch_id}/masking_rules`

## Buckets

[All buckets endpoints](https://neon.com/docs/reference/api/buckets.md)

- [Create a bucket on the branch](https://neon.com/docs/reference/api/buckets/create-project-branch-bucket.md) `POST /projects/{project_id}/branches/{branch_id}/buckets`
- [Delete a bucket on the branch](https://neon.com/docs/reference/api/buckets/delete-project-branch-bucket.md) `DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}`
- [Delete an object in a bucket](https://neon.com/docs/reference/api/buckets/delete-project-branch-bucket-object.md) `DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}`
- [Delete every object under a key prefix (folder) in a bucket](https://neon.com/docs/reference/api/buckets/delete-project-branch-bucket-objects-by-prefix.md) `DELETE /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects-by-prefix`
- [Download an object's bytes](https://neon.com/docs/reference/api/buckets/get-project-branch-bucket-object.md) `GET /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}/download`
- [List buckets on the branch](https://neon.com/docs/reference/api/buckets/list-project-branch-buckets.md) `GET /projects/{project_id}/branches/{branch_id}/buckets`
- [List objects in a bucket](https://neon.com/docs/reference/api/buckets/list-project-branch-bucket-objects.md) `GET /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects`
- [Presign an upload or download for an object in a bucket](https://neon.com/docs/reference/api/buckets/presign-project-branch-bucket-object.md) `POST /projects/{project_id}/branches/{branch_id}/buckets/{bucket_name}/objects/{object_key}/presign`

## Consumption

[All consumption endpoints](https://neon.com/docs/reference/api/consumption.md)

- [Retrieve branch consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-branch-v2.md) `GET /consumption_history/v2/branches`
- [Retrieve project consumption metrics](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project-v2.md) `GET /consumption_history/v2/projects`
- [Retrieve project consumption metrics (legacy plans)](https://neon.com/docs/reference/api/consumption/get-consumption-history-per-project.md) `GET /consumption_history/projects`

## Credentials

[All credentials endpoints](https://neon.com/docs/reference/api/credentials.md)

- [Issue a scoped credential on the branch](https://neon.com/docs/reference/api/credentials/create-credential.md) `POST /projects/{project_id}/branches/{branch_id}/credentials`
- [List credentials on the branch](https://neon.com/docs/reference/api/credentials/list-credentials.md) `GET /projects/{project_id}/branches/{branch_id}/credentials`
- [Reveal a credential's secrets](https://neon.com/docs/reference/api/credentials/reveal-credential.md) `POST /projects/{project_id}/branches/{branch_id}/credentials/{token_id}/reveal`
- [Revoke a credential](https://neon.com/docs/reference/api/credentials/revoke-credential.md) `DELETE /projects/{project_id}/branches/{branch_id}/credentials/{token_id}`
- [Rotate a credential's secrets](https://neon.com/docs/reference/api/credentials/rotate-credential.md) `POST /projects/{project_id}/branches/{branch_id}/credentials/{token_id}/rotate`

## Data API

[All dataapi endpoints](https://neon.com/docs/reference/api/dataapi.md)

- [Create Neon Data API](https://neon.com/docs/reference/api/dataapi/create-project-branch-data-api.md) `POST /projects/{project_id}/branches/{branch_id}/data-api/{database_name}`
- [Delete Neon Data API](https://neon.com/docs/reference/api/dataapi/delete-project-branch-data-api.md) `DELETE /projects/{project_id}/branches/{branch_id}/data-api/{database_name}`
- [Get advisor issues](https://neon.com/docs/reference/api/dataapi/get-project-advisor-security-issues.md) `GET /projects/{project_id}/advisors`
- [Retrieve Neon Data API configuration](https://neon.com/docs/reference/api/dataapi/get-project-branch-data-api.md) `GET /projects/{project_id}/branches/{branch_id}/data-api/{database_name}`
- [Update Neon Data API](https://neon.com/docs/reference/api/dataapi/update-project-branch-data-api.md) `PATCH /projects/{project_id}/branches/{branch_id}/data-api/{database_name}`

## Endpoints

[All endpoints endpoints](https://neon.com/docs/reference/api/endpoints.md)

- [Create compute endpoint](https://neon.com/docs/reference/api/endpoints/create-project-endpoint.md) `POST /projects/{project_id}/endpoints`
- [Delete compute endpoint](https://neon.com/docs/reference/api/endpoints/delete-project-endpoint.md) `DELETE /projects/{project_id}/endpoints/{endpoint_id}`
- [List compute endpoints](https://neon.com/docs/reference/api/endpoints/list-project-endpoints.md) `GET /projects/{project_id}/endpoints`
- [Restart compute endpoint](https://neon.com/docs/reference/api/endpoints/restart-project-endpoint.md) `POST /projects/{project_id}/endpoints/{endpoint_id}/restart`
- [Retrieve compute endpoint details](https://neon.com/docs/reference/api/endpoints/get-project-endpoint.md) `GET /projects/{project_id}/endpoints/{endpoint_id}`
- [Start compute endpoint](https://neon.com/docs/reference/api/endpoints/start-project-endpoint.md) `POST /projects/{project_id}/endpoints/{endpoint_id}/start`
- [Suspend compute endpoint](https://neon.com/docs/reference/api/endpoints/suspend-project-endpoint.md) `POST /projects/{project_id}/endpoints/{endpoint_id}/suspend`
- [Update compute endpoint](https://neon.com/docs/reference/api/endpoints/update-project-endpoint.md) `PATCH /projects/{project_id}/endpoints/{endpoint_id}`

## Functions

[All functions endpoints](https://neon.com/docs/reference/api/functions.md)

- [Create a trigger](https://neon.com/docs/reference/api/functions/create-project-branch-trigger.md) `POST /projects/{project_id}/branches/{branch_id}/triggers`
- [Delete a custom domain from a branch](https://neon.com/docs/reference/api/functions/delete-project-branch-custom-domain.md) `DELETE /projects/{project_id}/branches/{branch_id}/custom-domains/{domain}`
- [Delete a function on the branch](https://neon.com/docs/reference/api/functions/delete-project-branch-function.md) `DELETE /projects/{project_id}/branches/{branch_id}/functions/{slug}`
- [Delete a trigger](https://neon.com/docs/reference/api/functions/delete-project-branch-trigger.md) `DELETE /projects/{project_id}/branches/{branch_id}/triggers/{trigger_id}`
- [Deploy code to a function](https://neon.com/docs/reference/api/functions/create-project-branch-function-deployment.md) `POST /projects/{project_id}/branches/{branch_id}/functions/{slug}/deployments`
- [Get a trigger](https://neon.com/docs/reference/api/functions/get-project-branch-trigger.md) `GET /projects/{project_id}/branches/{branch_id}/triggers/{trigger_id}`
- [Get function details](https://neon.com/docs/reference/api/functions/get-project-branch-function.md) `GET /projects/{project_id}/branches/{branch_id}/functions/{slug}`
- [List functions on the branch](https://neon.com/docs/reference/api/functions/list-project-branch-functions.md) `GET /projects/{project_id}/branches/{branch_id}/functions`
- [List the custom domains on a branch](https://neon.com/docs/reference/api/functions/list-project-branch-custom-domains.md) `GET /projects/{project_id}/branches/{branch_id}/custom-domains`
- [List triggers on the branch](https://neon.com/docs/reference/api/functions/list-project-branch-triggers.md) `GET /projects/{project_id}/branches/{branch_id}/triggers`
- [Register a custom domain on a branch](https://neon.com/docs/reference/api/functions/register-project-branch-custom-domain.md) `POST /projects/{project_id}/branches/{branch_id}/custom-domains`
- [Update a function](https://neon.com/docs/reference/api/functions/update-project-branch-function.md) `PATCH /projects/{project_id}/branches/{branch_id}/functions/{slug}`
- [Update a trigger](https://neon.com/docs/reference/api/functions/update-project-branch-trigger.md) `PATCH /projects/{project_id}/branches/{branch_id}/triggers/{trigger_id}`

## Logs

[All logs endpoints](https://neon.com/docs/reference/api/logs.md)

- [List branch log field values](https://neon.com/docs/reference/api/logs/list-project-branch-log-field-values.md) `GET /projects/{project_id}/branches/{branch_id}/logs/fields/{field_name}/values`
- [List branch log fields](https://neon.com/docs/reference/api/logs/list-project-branch-log-fields.md) `GET /projects/{project_id}/branches/{branch_id}/logs/fields`
- [Query branch logs](https://neon.com/docs/reference/api/logs/query-project-branch-logs.md) `POST /projects/{project_id}/branches/{branch_id}/logs/query`

## Operations

[All operations endpoints](https://neon.com/docs/reference/api/operations.md)

- [List operations](https://neon.com/docs/reference/api/operations/list-project-operations.md) `GET /projects/{project_id}/operations`
- [Retrieve operation details](https://neon.com/docs/reference/api/operations/get-project-operation.md) `GET /projects/{project_id}/operations/{operation_id}`

## Organizations

[All organizations endpoints](https://neon.com/docs/reference/api/organizations.md)

- [Assign or update VPC endpoint](https://neon.com/docs/reference/api/organizations/assign-organization-vpc-endpoint.md) `POST /organizations/{org_id}/vpc/region/{region_id}/vpc_endpoints/{vpc_endpoint_id}`
- [Create organization API key](https://neon.com/docs/reference/api/organizations/create-org-api-key.md) `POST /organizations/{org_id}/api_keys`
- [Create organization invitations](https://neon.com/docs/reference/api/organizations/create-organization-invitations.md) `POST /organizations/{org_id}/invitations`
- [Delete VPC endpoint](https://neon.com/docs/reference/api/organizations/delete-organization-vpc-endpoint.md) `DELETE /organizations/{org_id}/vpc/region/{region_id}/vpc_endpoints/{vpc_endpoint_id}`
- [List organization API keys](https://neon.com/docs/reference/api/organizations/list-org-api-keys.md) `GET /organizations/{org_id}/api_keys`
- [List organization invitations](https://neon.com/docs/reference/api/organizations/get-organization-invitations.md) `GET /organizations/{org_id}/invitations`
- [List organization members](https://neon.com/docs/reference/api/organizations/get-organization-members.md) `GET /organizations/{org_id}/members`
- [List VPC endpoints](https://neon.com/docs/reference/api/organizations/list-organization-vpc-endpoints.md) `GET /organizations/{org_id}/vpc/region/{region_id}/vpc_endpoints`
- [List VPC endpoints across all regions](https://neon.com/docs/reference/api/organizations/list-organization-vpc-endpoints-all-regions.md) `GET /organizations/{org_id}/vpc/vpc_endpoints`
- [Remove organization member](https://neon.com/docs/reference/api/organizations/remove-organization-member.md) `DELETE /organizations/{org_id}/members/{member_id}`
- [Remove organization spending limit](https://neon.com/docs/reference/api/organizations/delete-organization-spending-limit.md) `DELETE /organizations/{org_id}/billing/spending_limit`
- [Retrieve organization details](https://neon.com/docs/reference/api/organizations/get-organization.md) `GET /organizations/{org_id}`
- [Retrieve organization member details](https://neon.com/docs/reference/api/organizations/get-organization-member.md) `GET /organizations/{org_id}/members/{member_id}`
- [Retrieve organization spending limit](https://neon.com/docs/reference/api/organizations/get-organization-spending-limit.md) `GET /organizations/{org_id}/billing/spending_limit`
- [Retrieve VPC endpoint details](https://neon.com/docs/reference/api/organizations/get-organization-vpc-endpoint-details.md) `GET /organizations/{org_id}/vpc/region/{region_id}/vpc_endpoints/{vpc_endpoint_id}`
- [Revoke organization API key](https://neon.com/docs/reference/api/organizations/revoke-org-api-key.md) `DELETE /organizations/{org_id}/api_keys/{key_id}`
- [Set organization spending limit](https://neon.com/docs/reference/api/organizations/set-organization-spending-limit.md) `PUT /organizations/{org_id}/billing/spending_limit`
- [Transfer projects between organizations](https://neon.com/docs/reference/api/organizations/transfer-projects-from-org-to-org.md) `POST /organizations/{source_org_id}/projects/transfer`
- [Update role for organization member](https://neon.com/docs/reference/api/organizations/update-organization-member.md) `PATCH /organizations/{org_id}/members/{member_id}`

## Projects

[All projects endpoints](https://neon.com/docs/reference/api/projects.md)

- [Accept a project transfer request](https://neon.com/docs/reference/api/projects/accept-project-transfer-request.md) `PUT /projects/{project_id}/transfer_requests/{request_id}`
- [Add JWKS URL](https://neon.com/docs/reference/api/projects/add-project-jwks.md) `POST /projects/{project_id}/jwks`
- [Create a project transfer request](https://neon.com/docs/reference/api/projects/create-project-transfer-request.md) `POST /projects/{project_id}/transfer_requests`
- [Create project](https://neon.com/docs/reference/api/projects/create-project.md) `POST /projects`
- [Delete JWKS URL](https://neon.com/docs/reference/api/projects/delete-project-jwks.md) `DELETE /projects/{project_id}/jwks/{jwks_id}`
- [Delete project](https://neon.com/docs/reference/api/projects/delete-project.md) `DELETE /projects/{project_id}`
- [Delete VPC endpoint restriction](https://neon.com/docs/reference/api/projects/delete-project-vpc-endpoint.md) `DELETE /projects/{project_id}/vpc_endpoints/{vpc_endpoint_id}`
- [Grant project access](https://neon.com/docs/reference/api/projects/grant-permission-to-project.md) `POST /projects/{project_id}/permissions`
- [List available shared preload libraries](https://neon.com/docs/reference/api/projects/get-available-preload-libraries.md) `GET /projects/{project_id}/available_preload_libraries`
- [List JWKS URLs](https://neon.com/docs/reference/api/projects/get-project-jwks.md) `GET /projects/{project_id}/jwks`
- [List org members and their project roles](https://neon.com/docs/reference/api/projects/list-project-members.md) `GET /projects/{project_id}/members`
- [List project access](https://neon.com/docs/reference/api/projects/list-project-permissions.md) `GET /projects/{project_id}/permissions`
- [List projects](https://neon.com/docs/reference/api/projects/list-projects.md) `GET /projects`
- [List shared projects](https://neon.com/docs/reference/api/projects/list-shared-projects.md) `GET /projects/shared`
- [List VPC endpoint restrictions](https://neon.com/docs/reference/api/projects/list-project-vpc-endpoints.md) `GET /projects/{project_id}/vpc_endpoints`
- [Recover a deleted project](https://neon.com/docs/reference/api/projects/recover-project.md) `POST /projects/{project_id}/recover`
- [Remove an org member's role on a project](https://neon.com/docs/reference/api/projects/remove-project-member-role.md) `DELETE /projects/{project_id}/members/{member_id}/role`
- [Retrieve connection URI](https://neon.com/docs/reference/api/projects/get-connection-uri.md) `GET /projects/{project_id}/connection_uri`
- [Retrieve project details](https://neon.com/docs/reference/api/projects/get-project.md) `GET /projects/{project_id}`
- [Retrieve projects count](https://neon.com/docs/reference/api/projects/count-projects.md) `GET /projects/count`
- [Revoke project access](https://neon.com/docs/reference/api/projects/revoke-permission-from-project.md) `DELETE /projects/{project_id}/permissions/{permission_id}`
- [Set an org member's role on a project](https://neon.com/docs/reference/api/projects/set-project-member-role.md) `PUT /projects/{project_id}/members/{member_id}/role`
- [Set VPC endpoint restriction](https://neon.com/docs/reference/api/projects/assign-project-vpc-endpoint.md) `POST /projects/{project_id}/vpc_endpoints/{vpc_endpoint_id}`
- [Update project](https://neon.com/docs/reference/api/projects/update-project.md) `PATCH /projects/{project_id}`

## Realtime

[All realtime endpoints](https://neon.com/docs/reference/api/realtime.md)

- [Disable Realtime](https://neon.com/docs/reference/api/realtime/disable-project-branch-realtime.md) `DELETE /projects/{project_id}/branches/{branch_id}/realtime`
- [Enable Realtime](https://neon.com/docs/reference/api/realtime/enable-project-branch-realtime.md) `POST /projects/{project_id}/branches/{branch_id}/realtime`
- [Retrieve Realtime state](https://neon.com/docs/reference/api/realtime/get-project-branch-realtime.md) `GET /projects/{project_id}/branches/{branch_id}/realtime`
- [Retrieve the Realtime shared secret](https://neon.com/docs/reference/api/realtime/get-project-branch-realtime-secret.md) `GET /projects/{project_id}/branches/{branch_id}/realtime/secret`
- [Rotate the Realtime shared secret](https://neon.com/docs/reference/api/realtime/rotate-project-branch-realtime-secret.md) `POST /projects/{project_id}/branches/{branch_id}/realtime/rotate_secret`

## Regions

[All regions endpoints](https://neon.com/docs/reference/api/regions.md)

- [List supported regions](https://neon.com/docs/reference/api/regions/get-active-regions.md) `GET /regions`

## Snapshots

[All snapshots endpoints](https://neon.com/docs/reference/api/snapshots.md)

- [Create snapshot](https://neon.com/docs/reference/api/snapshots/create-snapshot.md) `POST /projects/{project_id}/branches/{branch_id}/snapshot`
- [Delete snapshot](https://neon.com/docs/reference/api/snapshots/delete-snapshot.md) `DELETE /projects/{project_id}/snapshots/{snapshot_id}`
- [List project snapshots](https://neon.com/docs/reference/api/snapshots/list-snapshots.md) `GET /projects/{project_id}/snapshots`
- [Restore snapshot](https://neon.com/docs/reference/api/snapshots/restore-snapshot.md) `POST /projects/{project_id}/snapshots/{snapshot_id}/restore`
- [Retrieve backup schedule](https://neon.com/docs/reference/api/snapshots/get-snapshot-schedule.md) `GET /projects/{project_id}/branches/{branch_id}/backup_schedule`
- [Update backup schedule](https://neon.com/docs/reference/api/snapshots/set-snapshot-schedule.md) `PUT /projects/{project_id}/branches/{branch_id}/backup_schedule`
- [Update snapshot](https://neon.com/docs/reference/api/snapshots/update-snapshot.md) `PATCH /projects/{project_id}/snapshots/{snapshot_id}`

## Storage

[All storage endpoints](https://neon.com/docs/reference/api/storage.md)

- [Get branch object storage state](https://neon.com/docs/reference/api/storage/get-project-branch-storage.md) `GET /projects/{project_id}/branches/{branch_id}/storage`

## Users

[All users endpoints](https://neon.com/docs/reference/api/users.md)

- [List organizations for the current user](https://neon.com/docs/reference/api/users/get-current-user-organizations.md) `GET /users/me/organizations`
- [Retrieve current user details](https://neon.com/docs/reference/api/users/get-current-user-info.md) `GET /users/me`
- [Retrieve request authentication details](https://neon.com/docs/reference/api/users/get-auth-details.md) `GET /auth`
- [Transfer projects from personal account to organization](https://neon.com/docs/reference/api/users/transfer-projects-from-user-to-org.md) `POST /users/me/projects/transfer`

## Legacy Auth

[All auth-legacy endpoints](https://neon.com/docs/reference/api/auth-legacy.md)

- [Create Auth Provider SDK keys](https://neon.com/docs/reference/api/auth-legacy/create-neon-auth-provider-sdk-keys.md) `POST /projects/auth/keys`
- [Transfer Neon-managed auth project to your own account](https://neon.com/docs/reference/api/auth-legacy/transfer-neon-auth-provider-project.md) `POST /projects/auth/transfer_ownership`
- [Add an OAuth provider](https://neon.com/docs/reference/api/auth-legacy/add-neon-auth-oauth-provider.md) `POST /projects/{project_id}/auth/oauth_providers`
- [Add trusted redirect URI domain](https://neon.com/docs/reference/api/auth-legacy/add-neon-auth-domain-to-redirect-uri-whitelist.md) `POST /projects/{project_id}/auth/domains`
- [Create Neon Auth integration](https://neon.com/docs/reference/api/auth-legacy/create-neon-auth-integration.md) `POST /projects/auth/create`
- [Create new auth user](https://neon.com/docs/reference/api/auth-legacy/create-neon-auth-new-user.md) `POST /projects/auth/user`
- [Delete auth user](https://neon.com/docs/reference/api/auth-legacy/delete-neon-auth-user.md) `DELETE /projects/{project_id}/auth/users/{auth_user_id}`
- [Delete integration with auth provider](https://neon.com/docs/reference/api/auth-legacy/delete-neon-auth-integration.md) `DELETE /projects/{project_id}/auth/integration/{auth_provider}`
- [Delete OAuth provider](https://neon.com/docs/reference/api/auth-legacy/delete-neon-auth-oauth-provider.md) `DELETE /projects/{project_id}/auth/oauth_providers/{oauth_provider_id}`
- [Delete trusted redirect URI domain](https://neon.com/docs/reference/api/auth-legacy/delete-neon-auth-domain-from-redirect-uri-whitelist.md) `DELETE /projects/{project_id}/auth/domains`
- [List active integrations with auth providers](https://neon.com/docs/reference/api/auth-legacy/list-neon-auth-integrations.md) `GET /projects/{project_id}/auth/integrations`
- [List OAuth providers](https://neon.com/docs/reference/api/auth-legacy/list-neon-auth-oauth-providers.md) `GET /projects/{project_id}/auth/oauth_providers`
- [List trusted redirect URI domains](https://neon.com/docs/reference/api/auth-legacy/list-neon-auth-redirect-uri-whitelist-domains.md) `GET /projects/{project_id}/auth/domains`
- [Retrieve email server configuration](https://neon.com/docs/reference/api/auth-legacy/get-neon-auth-email-server.md) `GET /projects/{project_id}/auth/email_server`
- [Update email server configuration](https://neon.com/docs/reference/api/auth-legacy/update-neon-auth-email-server.md) `PATCH /projects/{project_id}/auth/email_server`
- [Update OAuth provider](https://neon.com/docs/reference/api/auth-legacy/update-neon-auth-oauth-provider.md) `PATCH /projects/{project_id}/auth/oauth_providers/{oauth_provider_id}`

--- [Document source](https://neon.com/docs/reference/api/get-started.md) ---

> Summary: Create a Neon API key, authenticate with the REST API, and make your first request to list projects using curl.

# Get started with the Neon API

Create an API key and make your first authenticated request.

Last updated: 2026-09-04

Copy into your AI assistant to get an API key and make your first API call. [View prompt](https://neon.com/prompts/neon-api-prompt.md)

The Neon API uses API keys and Bearer authentication. This page shows the shortest REST API path: create a key, set it as an environment variable, and call the `/projects` endpoint.

## Get an API key

Create an API key in the Neon Console under **Account settings** > **API keys**. For detailed instructions and security best practices, see [Manage API keys](https://neon.com/docs/manage/api-keys).

Neon supports three API key types:

| Key type                   | Scope                                                | Best for                      |
| -------------------------- | ---------------------------------------------------- | ----------------------------- |
| **Personal API key**       | All organization projects where the user is a member | Personal development, scripts |
| **Organization API key**   | All projects within an organization                  | Team automation, CI/CD        |
| **Project-scoped API key** | Single project only                                  | Limited access integrations   |

**Important:** API key tokens are shown only once at creation. Store them securely because you can't retrieve them later.

## Base URL and authentication

All API requests use this base URL:

```text
https://console.neon.tech/api/v2/
```

Include your API key in the `Authorization` header using Bearer authentication:

```bash
-H "Authorization: Bearer $NEON_API_KEY"
```

## Make your first request

Set your API key as an environment variable, then list your projects:

```bash
export NEON_API_KEY="your-api-key-here"

curl 'https://console.neon.tech/api/v2/projects' \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer $NEON_API_KEY" | jq
```

The response includes your projects with their IDs, regions, and other details:

```json
{
  "projects": [
    {
      "id": "spring-example-302709",
      "name": "my-project",
      "region_id": "aws-us-east-2",
      "pg_version": 17,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": { "cursor": "eyJsaW1pdCI6MX0" }
}
```

## Next steps

- Use the [endpoint index](https://neon.com/docs/reference/api/reference) to search all generated API operation pages.
- Review [key concepts](https://neon.com/docs/reference/api/key-concepts) before building automation.
- Download the [OpenAPI specification](https://neon.com/api_spec/release/v2.json) for code generation or API tooling.

--- [Document source](https://neon.com/docs/reference/api/key-concepts.md) ---

> Summary: Understand asynchronous operations, rate limits, pagination, and important constraints before building automation with the Neon API.

# Neon API key concepts

Asynchronous operations, rate limits, and pagination.

Last updated: 2026-09-04

Review these API behavior notes before you build scripts, CI/CD workflows, or control-plane integrations on top of Neon.

## Asynchronous operations

Many Neon API operations, including creating branches and starting computes, are asynchronous. The API response includes an `operations` array with status information:

```json
"operations": [
  {
    "id": "22acbb37-209b-4b90-a39c-8460090e1329",
    "action": "create_branch",
    "status": "running"
  }
]
```

Status values include `scheduling`, `running`, `finished`, `failed`, `cancelling`, `cancelled`, and `skipped`.

When building automation, poll the operation status before proceeding with dependent requests:

```bash
curl 'https://console.neon.tech/api/v2/projects/{project_id}/operations/{operation_id}' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

For details, see [Poll operation status](https://neon.com/docs/manage/operations#poll-operation-status).

## Rate limiting

The Neon API has these rate limits:

- 700 requests per minute, or approximately 11 per second
- 40 requests per second burst limit per route
- 10 requests per second for organization API key creation (`POST /organizations/{org_id}/api_keys`)

Exceeding these limits returns `HTTP 429 Too Many Requests`. Use retry logic with exponential backoff in your applications.

## Pagination

Some list endpoints support cursor-based pagination. Include `limit` and `cursor` parameters:

```bash
# First request with limit
curl 'https://console.neon.tech/api/v2/projects?limit=10' \
  -H "Authorization: Bearer $NEON_API_KEY"

# Subsequent request with cursor from the previous response
curl 'https://console.neon.tech/api/v2/projects?limit=10&cursor=...' \
  -H "Authorization: Bearer $NEON_API_KEY"
```

## API constraints and limits

These constraints apply when building automation with the Neon API:

- You can't delete a project's root or default branch.
- You can't delete a branch that has child branches. Delete all children first.
- Creating a new role may drop existing connections to the active compute endpoint.
- A branch can have only one `read_write` endpoint but multiple `read_only` endpoints.
- Neon limits overlapping operations on a project. Requests that try to schedule new work while conflicting operations are still running return `423 Locked`. Retry with exponential backoff, or poll for completion first. See [Handle concurrent operation errors](https://neon.com/docs/manage/operations#handle-concurrent-operation-errors).
- Operations older than 6 months may be removed from Neon's systems.

--- [Document source](https://neon.com/docs/reference/claimable-neon.md) ---

> Summary: If an agent needs a Neon account and the user is not around, provision a project now; they claim it later. Agents fetch https://neon.com/auth.md from neon.com/docs/llms.txt.

# Claimable Neon

CLI, claim, and HTTP reference

Last updated: 2026-10-31

If an agent needs a Neon account and the user is not around, it provisions a project now. A human claims it later if they want to keep it. The agent receives credentials scoped to one project, builds with standard Postgres tools, and hands over a claim link. Unclaimed projects expire in 72 hours (`project.expires_at`) and are capped at 100 MB storage and 1 GB transfer. Claim codes expire in 15 minutes (`expires_in`). Those are two clocks.

Start in the browser at [neon.com/claimable-neon](https://neon.com/claimable-neon), or give an agent [`auth.md`](https://neon.com/auth.md).

## Quick start

**Neon CLI**

If `neon claim` is not a command, or `neon claim --help` does not list `create`, use the Agent API tab.

Create a project and write its credentials to `.env`:

```bash
neon claim create --env-pull
```

Request Data API or Managed Better Auth when the app needs them:

```bash
neon claim create \
  --service data-api \
  --service auth \
  --env-pull
```

`neon claim create` uses `aws-us-east-2` unless you pass `--region-id`, for example `--region-id aws-eu-central-1`. Pass `--project-name` to name the project; it keeps the name after the claim.

The CLI saves the project's identity assertion in its secure credential store. Existing commands then use the claimable project automatically:

```bash
neon branches list
neon psql --role-name neondb_owner
```

**Agent API**

An agent starts with the protocol document:

```bash
curl https://neon.com/auth.md
```

Register an anonymous agent identity:

```bash
curl --request POST https://claimable.neon.tech/v1/agent/identity \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "anonymous",
    "capabilities": ["postgres", "data_api"],
    "source": "example-agent"
  }'
```

The response contains an `identity_assertion`, project metadata, and one decision for every requested capability. Exchange the assertion for a short-lived access token before calling project endpoints.

## Agent discovery

If an agent needs a Neon account and the user is not around, [neon.com/docs/llms.txt](https://neon.com/docs/llms.txt) points at [`auth.md`](https://neon.com/auth.md).

Claimable Neon implements [auth.md](https://workos.com/auth-md/docs/auth-md). Agents can discover the complete authentication and provisioning flow without a vendor-specific integration.

| Document or endpoint                                                    | Purpose                                                                               |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `GET https://neon.com/auth.md`                                          | Protocol file (`agent_auth.skill`)                                                    |
| `GET https://neon.com/.well-known/oauth-authorization-server/claimable` | Token, revocation, identity, and skill discovery. Issuer `https://neon.com/claimable` |
| `GET https://claimable.neon.tech/.well-known/oauth-protected-resource`  | Resource server metadata                                                              |
| `GET https://claimable.neon.tech/.well-known/jwks.json`                 | Public keys for verifying Claimable Neon tokens                                       |
| `POST https://claimable.neon.tech/v1/agent/identity`                    | Provision a project and issue a durable identity assertion                            |
| `POST https://claimable.neon.tech/v1/oauth2/token`                      | Exchange the assertion for a short-lived bearer access token                          |
| `POST https://claimable.neon.tech/v1/oauth2/revoke`                     | Revoke an access token or identity assertion                                          |
| `GET https://claimable.neon.tech/v1/projects/{project_id}/credentials`  | Read scoped project and service credentials                                           |
| `POST https://claimable.neon.tech/v1/projects/{project_id}/claim`       | Create a short-lived human claim code                                                 |
| `GET https://claimable.neon.tech/v1/projects/{project_id}/claim`        | Read claim and reconciliation status                                                  |
| `DELETE https://claimable.neon.tech/v1/projects/{project_id}`           | Delete an unclaimed project                                                           |
| `/v1/projects/{project_id}/...` on `claimable.neon.tech`                | Use supported Neon Management API operations before claiming                          |

The identity assertion is a secret. Store it like an API key. There are no refresh tokens. Exchange the assertion again when an access token expires.

## Register and provision

```http
POST /v1/agent/identity
Content-Type: application/json
```

```json
{
  "type": "anonymous",
  "capabilities": ["postgres", "data_api", "auth"],
  "source": "example-agent"
}
```

`postgres` is always requested. Add `data_api` or `auth` only when the app needs them.

`region_id` is optional. Without it, the project is created in `aws-us-east-2`. Pass any AWS [region](https://neon.com/docs/introduction/regions) that accepts new projects, for example `"region_id": "aws-eu-central-1"`. `project_name` is optional too and stays the project's name after the claim.

The response has this shape:

```json
{
  "registration_id": "reg_...",
  "identity_assertion": "eyJ...",
  "project": {
    "id": "quiet-fog-12345678",
    "branch_id": "br-...",
    "region_id": "aws-us-east-2",
    "expires_at": "2026-08-14T12:00:00.000Z"
  },
  "capabilities": [
    {
      "capability": "postgres",
      "granted": true,
      "scopes": ["postgres.read", "postgres.write"]
    },
    {
      "capability": "data_api",
      "granted": true,
      "scopes": ["data_api.query"]
    }
  ]
}
```

Check every capability decision. A successful registration can contain denied optional capabilities.

### Exchange the identity assertion

```bash
curl --request POST https://claimable.neon.tech/v1/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
  --data-urlencode 'assertion=YOUR_IDENTITY_ASSERTION' \
  --data-urlencode 'resource=https://claimable.neon.tech/'
```

The response contains a bearer `access_token`, its scope, and its expiration:

```json
{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "postgres.read postgres.write data_api.query"
}
```

### Pull credentials

```bash
curl https://claimable.neon.tech/v1/projects/quiet-fog-12345678/credentials \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "project_id": "quiet-fog-12345678",
  "branch_id": "br-...",
  "database_url": "postgresql://neondb_owner:...@ep-...-pooler.../neondb?sslmode=require",
  "expires_at": "2026-08-14T12:00:00.000Z",
  "services": {
    "data_api": {
      "url": "https://ep-....apirest.c-2.us-east-2.aws.neon.tech/neondb/rest/v1"
    },
    "auth": {
      "base_url": "https://ep-....neonauth.c-2.us-east-2.aws.neon.tech/api/auth",
      "jwks_url": "https://ep-....neonauth.c-2.us-east-2.aws.neon.tech/.well-known/jwks.json"
    }
  }
}
```

Only requested and granted services appear under `services`.

## Capabilities

| Capability          | Available before claim                      | Environment variable          |
| ------------------- | ------------------------------------------- | ----------------------------- |
| Postgres            | Yes                                         | `DATABASE_URL`                |
| Data API            | When requested, or later with `neon deploy` | `NEON_DATA_API_URL`           |
| Managed Better Auth | When requested, or later with `neon deploy` | `NEON_AUTH_BASE_URL`          |
| Functions           | No                                          | Requires claiming the project |
| Object Storage      | No                                          | Requires claiming the project |
| AI Gateway          | No                                          | Requires claiming the project |

Registration records those as `{ granted: false, reason: "requires_claim" }`. A later protected operation returns `capability_requires_claim`. Preserve the denied capability and give the human a claim link; do not retry or drop it.

After create, add Auth or the Data API with `neon.ts` and `neon deploy` on the unclaimed project. After claim, the same config talks to Neon directly.

## Use the Neon CLI

`neon claim` and its `neon claimable` alias manage anonymous projects. If `neon claim` is not a command, or `neon claim --help` does not list `create`, use the HTTP flow in this page.

```bash
neon claim create --env-pull

neon claim create --service data-api --service auth --env-pull

neon claim status

neon claim accept --no-open

neon claim list

neon claim delete --yes
```

`neon claim accept` opens a browser by default. `--no-open` prints the URL for a human to open.

After `claim create`, regular Neon CLI commands exchange the saved identity assertion and route supported management operations through Claimable Neon. Explicit Neon account credentials take precedence when you pass them.

If a `neon.ts` file is present, `claim create` requests its declared services automatically:

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

export default defineConfig({
  auth: true,
  dataApi: true,
});
```

Services that require human ownership still run through normal Config-as-Code planning. Claimable Neon returns `capability_requires_claim` for those operations, so the agent can ask for a claim instead of silently omitting part of the configuration.

## Claim a project

Create a claim code with the API:

```bash
curl --request POST \
  https://claimable.neon.tech/v1/projects/quiet-fog-12345678/claim \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

```json
{
  "user_code": "ABCD-2345",
  "verification_uri": "https://claimable.neon.tech/claim",
  "verification_uri_complete": "https://claimable.neon.tech/claim?user_code=ABCD-2345",
  "expires_in": 900,
  "interval": 5
}
```

`expires_in` is 900 seconds (15 minutes) today. If the unused code expires, POST `/claim` again. Each POST cancels the previous unused code and returns a new one. Re-issue only while `project.expires_at` is still in the future.

Open `verification_uri_complete` and sign in to Neon. Opening the URL does not freeze access. Continuing to Neon starts a transfer with a new 15-minute window: it revokes the project key, access tokens, and database password before the console transfer URL is shown. Auth and the Data API stay enabled and transfer with the project if they were enabled. If that transfer window expires before you accept, POST `/claim` again. The project key and database password stay revoked.

Choose the destination organization. The project then moves through these states:

1. `pending`: the claim code exists, but the transfer has not completed.
2. `accepted`: the project has left the unclaimed-project organization.
3. `reconciled`: the identity assertion is revoked and the ceremony is finished.

Continuing to Neon revokes existing access tokens. Re-exchange the identity assertion, then poll claim status at the server-provided `interval`. The new token has no project scopes. It authorizes that poll, and a replacement claim code if the transfer window expires.

```bash
curl --request POST https://claimable.neon.tech/v1/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer' \
  --data-urlencode "assertion=$IDENTITY_ASSERTION" \
  --data-urlencode 'resource=https://claimable.neon.tech/'

curl https://claimable.neon.tech/v1/projects/quiet-fog-12345678/claim \
  --header "Authorization: Bearer $ACCESS_TOKEN"
```

Only `reconciled` means the assertion is dead. Use credentials from the destination Neon organization after that. Fetch a new `DATABASE_URL` there; Auth and the Data API keep working if they were enabled.

Add Auth or the Data API with `neon.ts` and `neon deploy` before or after claim. Data API with the default auth provider requires Auth. An external JWKS is only accepted after claim:

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

export default defineConfig({
  auth: true,
  dataApi: true,
});
```

```bash
neon deploy
```

`neon checkout` does not apply this to an existing branch. `neon deploy` (alias of `neon config apply`) does.

```typescript
dataApi: {
  authProvider: 'external',
  jwksUrl: 'https://example.com/.well-known/jwks.json',
}
```

## Errors

Errors use one JSON shape across provisioning, token, credential, and management endpoints:

```json
{
  "error": {
    "code": "capability_requires_claim",
    "origin": "proxy",
    "message": "Functions require claiming this project.",
    "retryable": false,
    "request_id": "req_..."
  }
}
```

Use `error.code` for control flow and show `error.message` to the user. Retry only when `retryable` is `true`.

Common codes include:

| Code                        | Meaning                                                                          |
| --------------------------- | -------------------------------------------------------------------------------- |
| `invalid_request`           | The request body or parameter is invalid                                         |
| `invalid_grant`             | The identity assertion cannot be exchanged. Discard it                           |
| `unauthorized`              | No credential was presented, or it did not verify                                |
| `token_expired`             | The access token expired. Re-exchange the identity assertion                     |
| `scope_insufficient`        | The access token does not permit the operation                                   |
| `capability_requires_claim` | The requested service or operation requires human ownership                      |
| `claim_in_progress`         | The transfer window is still live. Poll status; mint a new code after it expires |
| `project_claimed`           | The project transferred. Discard the identity assertion                          |
| `project_expired`           | The unclaimed window closed. Discard the identity assertion                      |
| `upstream_error`            | A Neon API or service dependency failed                                          |

## Resources

- [Create a project in the browser](https://neon.com/claimable-neon)
- [Claimable Neon auth.md](https://neon.com/auth.md)
- [Neon CLI reference](https://neon.com/docs/cli)
- [Claimable database integration](https://neon.com/docs/workflows/claimable-database-integration)

--- [Document source](https://neon.com/docs/reference/compatibility.md) ---

> Summary: Neon's Postgres compatibility reference catalogs managed-service deviations from standard Postgres: no superuser access (replaced by `neon_superuser`), compute-size-dependent defaults for `max_connections`, `shared_buffers`, and `maintenance_work_mem`, plus unsupported features like tablespaces and persistent unlogged tables. Use this page when migrating to Neon to identify which permissions, extensions, collation providers, or session behaviors differ from a self-hosted install. Instance-level parameters are not user-configurable on Neon except on the Scale plan via Neon Support.

# Postgres compatibility

Learn about Neon as a managed Postgres service

Last updated: 2026-09-17

**Neon is Postgres**. However, as a managed Postgres service, there are some differences you should be aware of.

## Postgres versions

Neon supports Postgres 14, 15, 16, 17, and 18. You select the Postgres version you want to use when creating a Neon project. For information about creating a Neon project, see [Manage projects](https://neon.com/docs/manage/projects). Minor Postgres point releases are rolled out by Neon after extensive validation as part of regular platform maintenance.

For the current latest minor version available on Neon for each major version, and for details on how minor and major version updates work, see the [Lakebase Postgres version support policy](https://neon.com/docs/postgresql/postgres-version-support).

## Postgres extensions

Neon supports numerous Postgres extensions, and we regularly add support for more. For the extensions that Neon supports, see [Postgres Extensions](https://neon.com/docs/extensions/pg-extensions). To request support for additional extensions, please reach out to us on our [Discord Server](https://neon.com/discord). Please keep in mind that privilege requirements, local file system access, and functionality that is incompatible with Neon features such as Autoscaling and Scale to Zero may prevent Neon from being able to offer support for certain extensions.

## Roles and permissions

Neon is a managed Postgres service, so you cannot access the host operating system, and you can't connect using the Postgres `superuser` account. In place of the Postgres superuser role, Neon provides a `neon_superuser` role.

Roles created in the Neon Console or API, including the default role created with a Neon project, are granted membership in the `neon_superuser` role. So are roles created with `neon roles create` unless you pass `--access read_only` or `--access read_write`. For information about the privileges associated with this role, see [The neon_superuser role](https://neon.com/docs/manage/roles#the-neonsuperuser-role).

Roles created in Neon with SQL syntax, from a command-line tool like `psql` or the [Neon SQL Editor](https://neon.com/docs/connect/query-with-psql-editor), have the same privileges as newly created roles in a standalone Postgres installation. These roles are not granted membership in the `neon_superuser` role. You must grant these roles the privileges you want them to have. For more information, see [Manage roles with SQL](https://neon.com/docs/manage/roles#manage-roles-with-sql).

Neon roles cannot install Postgres extensions other than those supported by Neon.

## Postgres parameter settings

The following table shows parameter settings that are set explicitly for your database. These values may differ from standard Postgres defaults, and a few settings differ based on your Neon compute size.

**Note:** Because Neon is a managed Postgres service, Postgres parameters are not user-configurable outside of a [session, database, or role context](https://neon.com/docs/reference/compatibility#configuring-postgres-parameters-for-a-session-database-or-role).

If you are a Neon [Scale plan](https://neon.com/docs/introduction/plans) user and require a different Postgres instance-level setting, you can contact [Neon Support](https://neon.com/docs/introduction/support) to see if the desired setting can be supported. Please keep in mind that it may not be possible to support some parameters due to platform limitations and constraints.

| Parameter                             | Value         | Note                                                                                                                                                                                                                                                                                 |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `client_connection_check_interval`    | 60000         |                                                                                                                                                                                                                                                                                      |
| `dynamic_shared_memory_type`          | mmap          |                                                                                                                                                                                                                                                                                      |
| `effective_io_concurrency`            | 20            |                                                                                                                                                                                                                                                                                      |
| `effective_cache_size`                |               | Set based on the [compute cache](https://neon.com/docs/reference/glossary#compute-cache) size of your maximum Neon compute size                                                                                                                                                      |
| `fsync`                               | off           | Neon syncs data to the Neon database storage engine to store your data safely and reliably                                                                                                                                                                                           |
| `hot_standby`                         | off           |                                                                                                                                                                                                                                                                                      |
| `idle_in_transaction_session_timeout` | 300000        |                                                                                                                                                                                                                                                                                      |
| `listen_addresses`                    | '\*'          |                                                                                                                                                                                                                                                                                      |
| `log_connections`                     | on            |                                                                                                                                                                                                                                                                                      |
| `log_disconnections`                  | on            |                                                                                                                                                                                                                                                                                      |
| `log_min_error_statement`             | panic         |                                                                                                                                                                                                                                                                                      |
| `log_temp_files`                      | 1048576       |                                                                                                                                                                                                                                                                                      |
| `maintenance_work_mem`                | 65536         | The value differs by compute size. See [below](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size).                                                                                                                                        |
| `max_connections`                     | 112           | The value differs by compute size. See [below](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size).                                                                                                                                        |
| `max_parallel_workers`                | 8             |                                                                                                                                                                                                                                                                                      |
| `max_replication_flush_lag`           | 10240         |                                                                                                                                                                                                                                                                                      |
| `max_replication_slots`               | 10            |                                                                                                                                                                                                                                                                                      |
| `max_replication_write_lag`           | 500           |                                                                                                                                                                                                                                                                                      |
| `max_wal_senders`                     | 10            |                                                                                                                                                                                                                                                                                      |
| `max_wal_size`                        | 1024          |                                                                                                                                                                                                                                                                                      |
| `max_worker_processes`                | 26            | The value differs by compute size. See [below](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size).                                                                                                                                        |
| `password_encryption`                 | scram-sha-256 |                                                                                                                                                                                                                                                                                      |
| `restart_after_crash`                 | off           |                                                                                                                                                                                                                                                                                      |
| `shared_buffers`                      | 128MB         | The `shared_buffers` value differs by compute size; the [compute cache](https://neon.com/docs/reference/glossary#compute-cache) provides up to 75% of your compute's RAM. See [below](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size). |
| `superuser_reserved_connections`      | 7             |                                                                                                                                                                                                                                                                                      |
| `synchronous_standby_names`           | 'walproposer' |                                                                                                                                                                                                                                                                                      |
| `wal_level`                           | replica       | Defaults to `replica`. When you [enable logical replication](https://neon.com/docs/guides/logical-replication-neon#enable-logical-replication), Neon changes it to `logical`.                                                                                                        |
| `wal_log_hints`                       | off           |                                                                                                                                                                                                                                                                                      |
| `wal_sender_timeout`                  | 10000         |                                                                                                                                                                                                                                                                                      |

### Parameter settings that differ by compute size

Of the parameter settings listed above, the `max_connections`, `maintenance_work_mem`,
`shared_buffers`, `max_worker_processes`, and `effective_cache_size` differ by your compute size (defined in [Compute Units (CU)](https://neon.com/docs/reference/glossary#compute-unit-cu)) or by your autoscaling configuration, which has a minimum and maximum compute size. To understand how values are set, see the formulas below.

- The formula for `max_connections` is:

  ```go
  compute_size = min(max_compute_size, 8 × min_compute_size)
  max_connections = max(100, min(4000, floor(compute_size × 419.66)))
  ```

  In simpler terms:

  - Neon first determines the effective compute size by taking the smaller of: your maximum size, or 8 times your minimum size
  - This compute size is then multiplied by approximately 420 connections per CU
  - The result is capped between a minimum of 100 and a maximum of 4,000 connections

  **Examples:**

  - **Fixed compute size of 4 CU:**
    - Since your min and max are both 4 CU, the compute size is 4.
    - Max connections = 4 × 419.66 = 1,678 connections
  - **Autoscaling from 0.25 to 2 CU:**
    - Compute size = min(2, 8 × 0.25) = min(2, 2) = 2
    - Max connections = 2 × 419.66 = 839 connections
  - **Autoscaling from 0.25 to 4 CU:**
    - Compute size = min(4, 8 × 0.25) = min(4, 2) = 2
    - Max connections = 2 × 419.66 = 839 connections
  - **Autoscaling from 2 to 8 CU:**
    - Compute size = min(8, 8 × 2) = min(8, 16) = 8
    - Max connections = 8 × 419.66 = 3,357 connections

You can view your `max_connections` setting in the Neon Console by navigating to **Branches**, selecting your compute, and clicking **Edit** on the **Compute** tab. The value is displayed as **direct connections**. As you adjust your compute settings, you'll see how changes to your min/max compute size affect the number of direct connections available.

![max\_connections calculator](https://neon.com/docs/reference/max_connections_calculator.png)

_For most applications, we recommend using connection pooling, which supports up to 10,000 concurrent connections regardless of compute size. Direct connections are best for specific use cases like running `pg_dump`, session-dependent features, or schema migrations. For more information, see [Connection pooling](https://neon.com/docs/connect/connection-pooling)._

- The `maintenance_work_mem` value is set according to your minimum compute size RAM. The formula is:

  ```go
  maintenance_work_mem = max(min_compute_size RAM in bytes * 1024/63,963,136, 65,536)
  ```

  However, you can increase the setting for the current session; for example:

  ```sql
  SET maintenance_work_mem='10 GB';
  ```

  If you do increase `maintenance_work_mem`, your setting should not exceed 60 percent of your compute's available RAM.

  | Compute Units (CU) | RAM    | maintenance\_work\_mem |
  | :----------------- | :----- | :--------------------- |
  | 0.25               | 1 GB   | 64 MB                  |
  | 0.50               | 2 GB   | 64 MB                  |
  | 1                  | 4 GB   | 67 MB                  |
  | 2                  | 8 GB   | 134 MB                 |
  | 3                  | 12 GB  | 201 MB                 |
  | 4                  | 16 GB  | 268 MB                 |
  | 5                  | 20 GB  | 335 MB                 |
  | 6                  | 24 GB  | 402 MB                 |
  | 7                  | 28 GB  | 470 MB                 |
  | 8                  | 32 GB  | 537 MB                 |
  | 9                  | 36 GB  | 604 MB                 |
  | 10                 | 40 GB  | 671 MB                 |
  | 11                 | 44 GB  | 738 MB                 |
  | 12                 | 48 GB  | 805 MB                 |
  | 13                 | 52 GB  | 872 MB                 |
  | 14                 | 56 GB  | 939 MB                 |
  | 15                 | 60 GB  | 1007 MB                |
  | 16                 | 64 GB  | 1074 MB                |
  | 18                 | 72 GB  | 1208 MB                |
  | 20                 | 80 GB  | 1342 MB                |
  | 22                 | 88 GB  | 1476 MB                |
  | 24                 | 96 GB  | 1610 MB                |
  | 26                 | 104 GB | 1744 MB                |
  | 28                 | 112 GB | 1878 MB                |
  | 30                 | 120 GB | 2012 MB                |
  | 32                 | 128 GB | 2146 MB                |
  | 34                 | 136 GB | 2280 MB                |
  | 36                 | 144 GB | 2414 MB                |
  | 38                 | 152 GB | 2548 MB                |
  | 40                 | 160 GB | 2682 MB                |
  | 42                 | 168 GB | 2816 MB                |
  | 44                 | 176 GB | 2950 MB                |
  | 46                 | 184 GB | 3084 MB                |
  | 48                 | 192 GB | 3218 MB                |
  | 50                 | 200 GB | 3352 MB                |
  | 52                 | 208 GB | 3486 MB                |
  | 54                 | 216 GB | 3620 MB                |
  | 56                 | 224 GB | 3754 MB                |

- The formula for `max_worker_processes` is:

  ```go
  max_worker_processes := 13 + floor(2 * max_compute_size)
  ```

  For example, if your `max_compute_size` is 4 CU, your `max_worker_processes` setting would be 21.

- The formula for `shared_buffers` is:

  ```go
  backends = 1 + max_connections + max_worker_processes
  shared_buffers_mb = max(128, (1023 + backends * 256) / 1024)
  ```

  On large fixed-size computes (18 CU and above), `shared_buffers` is instead set to 75% of your compute's RAM (backed by huge pages) and the secondary file cache is disabled, so this formula does not apply. See [What is the compute cache?](https://neon.com/docs/extensions/neon#what-is-the-compute-cache).

- The `effective_cache_size` parameter is set based on the [compute cache](https://neon.com/docs/reference/glossary#compute-cache) size of your maximum Neon compute size. This helps the Postgres query planner make smarter decisions, which can improve query performance. For details on compute cache size by compute size, see the table in [How to size your compute](https://neon.com/docs/manage/computes#how-to-size-your-compute).

### Configuring Postgres parameters for a session, database, or role

Neon permits configuring parameters that have a `user` context, meaning that these parameters can be set for a session, database, or role. You can identify Postgres parameters with a `user` context by running the following query:

```sql
SELECT name
FROM pg_settings
WHERE context = 'user';
```

To set a parameter for a specific session, use a [SET](https://www.postgresql.org/docs/current/sql-set.html) command.

For example, the `maintenance_work_mem` parameter supports a `user` context, which lets you set it for the current session with a `SET` command:

```sql
SET maintenance_work_mem='1 GB';
```

To set parameters for a database or role:

```sql
ALTER DATABASE neondb SET maintenance_work_mem='1 GB';
```

```sql
ALTER USER neondb_owner SET maintenance_work_mem='1 GB';
```

## Tablespaces

Neon does not support PostgreSQL [tablespaces](https://www.postgresql.org/docs/current/manage-ag-tablespaces.html). Attempting to create a tablespace with the `CREATE TABLESPACE` command will result in an error. This is due to Neon's managed cloud architecture, which does not permit direct file system access for custom storage locations.

If you have existing applications or scripts that use tablespaces for organizing database objects across different storage devices, you'll need to remove or modify these references when migrating to Neon.

## Postgres logs

Postgres logs can be accessed through the [Datadog](https://neon.com/docs/guides/datadog) or [OpenTelemetry](https://neon.com/docs/guides/opentelemetry) integration on the Scale plan. The integration forwards logs including error messages, database connection events, system notifications, and general PostgreSQL logs. For other plans or if you need specific log information for troubleshooting purposes, please contact [Neon Support](https://neon.com/docs/introduction/support).

## Unlogged tables

Unlogged tables are tables that do not write to the Postgres write-ahead log (WAL). In Neon, these tables are stored on compute local storage and are not persisted across compute restarts or when a compute scales to zero. This is unlike standard Postgres, where unlogged tables are only truncated in the event of abnormal process termination. Additionally, unlogged tables are limited by compute local disk space. Computes allocate 20 GiB of local disk space or 15 GiB x the maximum compute size (whichever is highest) for temporary files used by Postgres.

## Temporary tables

Temporary tables are tied to a session (or optionally a transaction). They exist only for the lifetime of the session or transaction and are automatically dropped when it ends. Like unlogged tables, they are stored on compute local storage and limited by compute local disk space.

## Memory

SQL queries and index builds can generate large volumes of data that may not fit in memory. In Neon, the size of your compute determines the amount of memory that is available. For information about compute size and available memory, see [How to size your compute](https://neon.com/docs/manage/endpoints#how-to-size-your-compute).

## Session context

The Neon cloud service automatically closes idle connections after a period of inactivity, as described in [Compute lifecycle](https://neon.com/docs/introduction/compute-lifecycle). When connections are closed, anything that exists within a session context is forgotten and must be recreated before being used again. For example, parameters set for a specific session, in-memory statistics, temporary tables, prepared statements, advisory locks, and notifications and listeners defined using [NOTIFY](https://www.postgresql.org/docs/current/sql-notify.html)/[LISTEN](https://www.postgresql.org/docs/current/sql-listen.html) commands only exist for the duration of the current session and are lost when the session ends. To avoid losing session-level contexts in Neon, you can disable Neon's [Scale to Zero](https://neon.com/docs/guides/scale-to-zero-guide) feature, which is possible on any of Neon's paid plans. However, disabling scale to zero also means that your compute will run 24/7. You can't disable scale to zero on Neon's Free plan, where your compute always suspends after 5 minutes of inactivity.

## Statistics collection

Statistics collected by the Postgres [cumulative statistics system](https://www.postgresql.org/docs/current/monitoring-stats.html) are not saved when a Neon compute (where Postgres runs) is suspended due to inactivity or restarted. For information about the lifecycle of a Neon compute, see [Compute lifecycle](https://neon.com/docs/introduction/compute-lifecycle). For information about configuring Neon's scale to zero behavior, see [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero).

## Database encoding

Neon supports UTF8 encoding (Unicode, 8-bit variable-width encoding). This is the most widely used and recommended encoding for Postgres.

To view the encoding and collation for your database, you can run the following query:

```sql
SELECT
    pg_database.datname AS database_name,
    pg_encoding_to_char(pg_database.encoding) AS encoding,
    pg_database.datcollate AS collation,
    pg_database.datctype AS ctype
FROM
    pg_database
WHERE
    pg_database.datname = 'your_database_name';
```

You can also issue this command from [psql](https://neon.com/docs/connect/query-with-psql-editor) or the Neon SQL Editor:

```bash
\l
```

**Note:** In Postgres, you cannot change a database's encoding or collation after it has been created.

## Collation support

A collation is an SQL schema object that maps an SQL name to locales provided by libraries installed in the operating system. A collation has a provider that specifies which library supplies the locale data. For example, a common standard provider, `libc`, uses locales provided by the operating system C library.

By default, Neon uses the `C.UTF-8` collation. `C.UTF-8` supports the full range of UTF-8 encoded characters.

Another provider supported by Neon is `icu`, which uses the external [ICU](https://icu.unicode.org/) library. In Neon, support for standard `libc` locales is limited compared to what you might find in a locally installed Postgres instance where there's typically a wider range of locales provided by libraries installed on your operating system. For this reason, Neon provides a full series of [predefined icu locales](https://www.postgresql.org/docs/current/collation.html#COLLATION-MANAGING-PREDEFINED-ICU) in case you require locale-specific sorting or case conversions.

To view all of the predefined locales available to you, use the query `SELECT * FROM pg_collation`, or the command `\dOS+` from the [Neon SQL Editor](https://neon.com/docs/connect/query-with-psql-editor) or an SQL client like [psql](https://neon.com/docs/connect/query-with-psql-editor).

To create a database with a predefined `icu` locale, you can issue a query similar to this one with your preferred locale:

```sql
CREATE DATABASE my_arabic_db
LOCALE_PROVIDER icu
icu_locale 'ar-x-icu'
template template0;
```

To specify the locale for individual columns, you can use this syntax:

```sql
CREATE TABLE my_ru_table (
    id serial PRIMARY KEY,
    russian_text_column text COLLATE "ru-x-icu",
    description text
);
```

ICU also supports creating custom collations. For more information, see [ICU Custom Collations](https://www.postgresql.org/docs/current/collation.html#ICU-CUSTOM-COLLATIONS).

For more about collations in Postgres, see [Collation Support](https://www.postgresql.org/docs/current/collation.html#COLLATION).

## track_commit_timestamp parameter

The `track_commit_timestamp` Postgres parameter is currently not supported in Neon due to platform constraints.

--- [Document source](https://neon.com/docs/reference/config-runtime.md) ---

> Summary: @neon/config-runtime is the lower-level, scriptable engine behind neon config / neon deploy: inspect, plan, and apply a neon.ts policy directly from Node.js, without going through the neon CLI. Use it to build a custom CI step, a deploy script, or another tool that needs to reconcile a branch against a neon.ts policy.

# @neon/config-runtime

Programmatic API for running a neon.ts policy from your own scripts and CI.

Last updated: 2026-10-30

`@neon/config-runtime` is the package the [`neon` CLI](https://neon.com/docs/cli/config) itself uses to run a [`neon.ts`](https://neon.com/docs/reference/neon-ts) policy: read a branch's live state, diff a policy against it, apply the result, bundle and deploy Neon Functions, and register their custom domains. Import it directly when you're writing your own CI step or script and the CLI commands (`neon config plan`, `neon deploy`) don't fit. For example, a custom GitHub Actions job that applies a policy to a freshly created preview branch.

If you just want to run `neon.ts` from the command line, use the [`neon config` / `neon deploy` commands](https://neon.com/docs/cli/config) instead. Reach for this package only when you need to call the same logic from your own Node.js code.

**Note:** `@neon/config-runtime` doesn't read a `.neon` context file, `NEON_*` environment variables, or CLI credential files. Resolve `projectId` and `branchId` yourself, then pass either an API key or a custom `api` adapter. This is different from the `neon` CLI, which resolves project context and credentials for you.

## Install

```bash
npm install @neon/config-runtime
```

Requires Node.js 20.19 or later. Import from the `/v1` subpath to pin a specific major version:

```ts
import { inspect, plan, apply } from "@neon/config-runtime/v1";
```

This package pulls in `esbuild` (a native binary) to bundle Neon Functions for deploy, so it belongs in a CLI, CI job, or deploy script, not in `neon.ts` itself. `neon.ts` should only ever import [`@neon/config`](https://neon.com/docs/reference/neon-ts), which has no native dependencies.

## Resolving project and branch ids

Every function on this page takes `projectId` and a Neon branch id (`br-…`), not a branch name. Look these up yourself before calling in:

- `neon projects list --output json` and `neon branches list --output json` (the [Neon CLI](https://neon.com/docs/cli))
- The Neon API's [list branches](https://neon.com/docs/reference/api/branches/list-project-branches) endpoint
- The `.neon` context file written by `neon link` (the CLI's own resolution mechanism, if your script runs alongside it)

Passing a branch name where an id is expected fails with a `PLATFORM_BRANCH_NOT_FOUND` error (see [Error handling](https://neon.com/docs/reference/config-runtime#error-handling)).

## Quick example

```ts
import config from "../neon";
import { apply, inspect, plan } from "@neon/config-runtime/v1";

const target = {
  projectId: "solitary-fog-12345678",
  branchId: "br-cool-forest-12345678",
  apiKey: process.env.NEON_API_KEY!,
};

const live = await inspect(target); // read the branch's current live state
const diff = await plan(config, target); // dry-run: what would apply change?
const result = await apply(config, target); // apply the policy for real
```

`apply` throws if the branch already has settings your policy would override. See [`apply`](https://neon.com/docs/reference/config-runtime#apply) for how to allow that.

## Authentication

None of the functions on this page take a Neon session or browser login. [Create a Neon API key in the Console](https://console.neon.tech/app/settings/api-keys), then pass it in the `apiKey` option, or inject your own `NeonApi` adapter with `api`. The package doesn't read `NEON_API_KEY` or the credentials written by `neon login`. If you omit both `apiKey` and `api`, the operation throws a `PlatformError` with code `PLATFORM_MISSING_API_KEY`.

For `inspect`, `plan`, `apply`, `pullConfig`, and `pushConfig`, the optional `apiHost` selects a non-production API host. If you omit it, the package uses Neon's production API. The package doesn't read `NEON_API_HOST`. `CreateBranchOptions` has no `apiHost` field, so you can't override the host per call to `createBranch`.

In CI, read the secret from your CI environment and pass its value as `apiKey`, as shown in [A custom CI step](https://neon.com/docs/reference/config-runtime#a-custom-ci-step).

Pass `api` instead to inject your own `NeonApi` adapter (used internally for tests; most callers don't need this).

## Operations

The three functions below mirror the Terraform mental model (`inspect` reads state, `plan` previews a diff, `apply` reconciles it) and are what `neon config status` / `plan` / `apply` call internally.

### `inspect`

```ts
function inspect(options: ConfigOperationOptions): Promise<PulledBranchConfig>;
```

Reads a branch's live Neon state and reverse-engineers it into a `neon.ts`-shaped `Config`, plus raw project/branch metadata. Read-only, and never mutates anything.

| `ConfigOperationOptions` field | Type       | Description                                                               |
| ------------------------------ | ---------- | ------------------------------------------------------------------------- |
| `projectId`                    | `string`   | Required.                                                                 |
| `branchId`                     | `string`   | Required. Must already exist on the project; `inspect` never creates one. |
| `apiKey`                       | `string?`  | Required unless you pass `api`.                                           |
| `apiHost`                      | `string?`  | Optional non-production API host. Defaults to Neon's production API.      |
| `api`                          | `NeonApi?` | Inject a custom adapter (mainly for tests).                               |

Returns a `PulledBranchConfig`:

| Field     | Type                                                      | Description                                                                                                                                                 |
| --------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project` | `{ id, name, region, pgVersion, orgId? }`                 | Project metadata.                                                                                                                                           |
| `branch`  | `{ id, name, parent?, isDefault, protected, expiresAt? }` | Branch metadata.                                                                                                                                            |
| `config`  | `Config`                                                  | The branch's state, expressed as a `neon.ts`-shaped policy (static `auth`/`dataApi` toggles plus a `branch` closure carrying its lifecycle/compute tuning). |
| `preview` | `PulledPreview?`                                          | Buckets, functions, and issued credentials on the branch. Omitted entirely when the branch has none.                                                        |

A pulled function is reported as `{ slug, name }` only: the remote has no record of the local `source` file path, so a pulled config can't redeploy a function without you re-adding `source` by hand.

### `plan`

```ts
function plan(config: Config, options: ConfigOperationOptions): Promise<PushResult>;
```

Computes what `apply` would do, without mutating anything (the equivalent of `terraform plan`). Takes the same options as `inspect`.

Returns a `PushResult` with the same shape as [`apply`](https://neon.com/docs/reference/config-runtime#apply). On a dry run, `applied` describes the changes that would be applied; no remote state is modified.

### `apply`

```ts
function apply(config: Config, options: ApplyOptions): Promise<PushResult>;
```

Applies a `neon.ts` policy to an existing branch. Never creates a project or branch: both must already exist (use [`createBranch`](https://neon.com/docs/reference/config-runtime#createbranch) to provision one from a policy). `ApplyOptions` extends `ConfigOperationOptions` with:

| Field                  | Type                                                           | Default | Description                                                                                                                                                                                                                    |
| ---------------------- | -------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `updateExisting`       | `boolean`                                                      | `false` | Auto-confirm overriding existing remote settings (TTL, `protected`, compute settings). Without it, drift from the branch's current state throws `PushConflictError`.                                                           |
| `allowProtectedBranch` | `boolean`                                                      | `false` | Auto-confirm applying to a branch marked protected on Neon (see the note below the table).                                                                                                                                     |
| `confirm`              | `(context: PushConfirmContext) => boolean \| Promise<boolean>` | none    | Asked once, before any change, when the apply needs confirmation. See [`pushConfig`](https://neon.com/docs/reference/config-runtime#pushconfig) for when it runs and what it receives.                                         |
| `beforeMutations`      | `() => void \| Promise<void>`                                  | none    | Runs once on every real apply (not on a dry run), after `confirm` approves or isn't needed and before the first change or function bundle, even when there's nothing to change. A throw aborts the apply with nothing changed. |
| `bundleFunction`       | `FunctionBundler?`                                             | esbuild | Custom bundler for function source. See [Function bundling](https://neon.com/docs/reference/config-runtime#function-bundling).                                                                                                 |

Without a `confirm` callback, `apply` is non-interactive: pass `updateExisting`/`allowProtectedBranch` up front, or unresolved drift throws `PushConflictError` (see [Error handling](https://neon.com/docs/reference/config-runtime#error-handling)). Pass `confirm` to ask before overriding existing settings or applying to a protected branch instead. A protected branch with **no** other drift isn't blocked when `allowProtectedBranch` is `false` and no `confirm` callback is set.

Returns a `PushResult`:

| Field           | Type                                     | Description                                                                                                                                                                                                                                                                     |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `projectId`     | `string`                                 | Target project id.                                                                                                                                                                                                                                                              |
| `orgId`         | `string?`                                | Organization id for the target project, when the API returns one.                                                                                                                                                                                                               |
| `branchId`      | `string`                                 | Target branch id.                                                                                                                                                                                                                                                               |
| `branchName`    | `string`                                 | Target branch name.                                                                                                                                                                                                                                                             |
| `dryRun`        | `boolean`                                | `true` for `plan` / `pushConfig({ dryRun: true })`; `applied` then records planned changes only.                                                                                                                                                                                |
| `applied`       | `AppliedChange[]`                        | Ordered list of policy changes that were applied or, on dry runs, would be applied. Each entry identifies the changed resource and field.                                                                                                                                       |
| `conflicts`     | `ConflictReport[]`                       | Conflicts found while comparing local policy with remote state. Empty when the push can proceed.                                                                                                                                                                                |
| `customDomains` | `Array<{ domain, slug, cnameTarget? }>?` | Custom domains declared for the branch after the push, or what `apply` would leave in place on a dry run. `cnameTarget` is absent for a not-yet-registered domain on a dry run, and is an empty string when the region has no custom-domains front door.                        |
| `warnings`      | `string[]`                               | Advisory messages from the push, for example a function that bundles a native dependency it never declared. Always present, and empty when there's nothing to report. Only the default bundler adds to it. If you pass your own `bundleFunction`, you report your own warnings. |

### `createBranch`

```ts
function createBranch(config: Config, options: CreateBranchOptions): Promise<CreateBranchResult>;
```

Creates a branch **from** a `neon.ts` policy and brings it up with its declared settings in one step: it calls the Neon API directly to create the branch, then applies the rest of the policy to it with `pushConfig`. This is the flow `neon checkout <new-name>` needs when it creates a new branch, and the CLI calls this function to get it (not the other way around). Concretely, `createBranch` evaluates the policy with `branch.exists: false` (so creation-time tuning gated on `!branch.exists` actually resolves), creates the branch from the policy's `parent` (falling back to the project's default branch), then reconciles the rest of the policy onto it.

| `CreateBranchOptions` field | Type               | Description                                                                                                |
| --------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- |
| `projectId`                 | `string`           | Required.                                                                                                  |
| `branchName`                | `string`           | Required. Must not already exist on the project.                                                           |
| `apiKey`                    | `string?`          | Required unless you pass `api`.                                                                            |
| `api`                       | `NeonApi?`         | Inject a custom adapter.                                                                                   |
| `bundleFunction`            | `FunctionBundler?` | Custom bundler. See [Function bundling](https://neon.com/docs/reference/config-runtime#function-bundling). |

Returns `{ branchId, branchName, result: PushResult }`. Throws a `PlatformError` (`PLATFORM_CONFLICT`) if `branchName` already exists, or (`PLATFORM_BRANCH_NOT_FOUND`) if the policy's `parent` names a branch that doesn't exist on the project.

## Lower-level: `pullConfig` and `pushConfig`

`inspect`, `plan`, and `apply` are thin, intent-revealing wrappers over two lower-level primitives. Reach for these directly when you need control they don't expose: most commonly, evaluating the `branch` closure as a creation (`branchExists: false`) so creation-time tuning resolves.

`pushConfig` always requires a `branchId` that already exists on the project; `branchExists: false` only changes how the policy is evaluated, not whether the branch has to exist. `pushConfig` never creates a branch, on `dryRun` or otherwise. If the branch doesn't exist yet, use [`createBranch`](https://neon.com/docs/reference/config-runtime#createbranch) instead.

### `pullConfig`

```ts
function pullConfig(options: PullConfigOptions): Promise<PulledBranchConfig>;
```

Functionally identical to [`inspect`](https://neon.com/docs/reference/config-runtime#inspect): `inspect` forwards its options (`projectId`, `branchId`, `api`, `apiKey`, `apiHost`) to `pullConfig` unchanged and returns its result directly, with no other logic in between. The two names exist so call sites can read naturally (`inspect` next to `plan`/`apply`) while the engine module stays named after what it does.

### `pushConfig`

```ts
function pushConfig(config: Config, options: PushConfigOptions): Promise<PushResult>;
```

Returns the same `PushResult` shape as [`apply`](https://neon.com/docs/reference/config-runtime#apply). With `dryRun: true`, `applied` is the ordered list of changes that would be applied, and the function does not mutate remote state.

The engine behind `plan` and `apply`. `PushConfigOptions` takes every `ApplyOptions` field, adds `branchExists` and `dryRun`, and the table below describes `confirm` in full:

| Field          | Type                                                           | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| -------------- | -------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `branchExists` | `boolean`                                                      | `true`  | Evaluate the policy's `branch` closure as if the target branch doesn't exist yet (`branch.exists: false`), without changing whether it physically exists on Neon. `createBranch` uses this internally so creation-time tuning (TTL, compute, `parent`) resolves right after provisioning.                                                                                                                                                                              |
| `confirm`      | `(context: PushConfirmContext) => boolean \| Promise<boolean>` | none    | Invoked once, before any mutation, when the push needs confirmation: either the branch is protected (and `allowProtectedBranch` isn't `true`) or applying would override existing settings (and `updateExisting` isn't `true`). Return `true` to proceed; a `false` return throws `PushAbortedError`. Not invoked, and no mutation runs, when the plan has unresolvable conflicts: those throw `PushConflictError` regardless of `confirm`. Never invoked on `dryRun`. |
| `dryRun`       | `boolean`                                                      | `false` | Compute the full plan against live remote state without executing any mutations. `plan(config, target)` is exactly `pushConfig(config, { ...target, dryRun: true, updateExisting: true })`.                                                                                                                                                                                                                                                                            |

`PushConfirmContext` passed to `confirm`:

| Field             | Type                        | Description                                                                                                                                                            |
| ----------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `branchName`      | `string`                    | Target branch's name.                                                                                                                                                  |
| `protectedBranch` | `boolean`                   | `true` when the branch is protected on Neon and `allowProtectedBranch` wasn't set.                                                                                     |
| `overrideUpdates` | `boolean`                   | `true` when the plan would override existing remote settings and `updateExisting` wasn't set. Additive changes (enabling a service for the first time) never set this. |
| `overrides`       | `readonly ConflictReport[]` | The settings that would be overridden, as current and desired values, so you can show what you're asking about. Empty when only `protectedBranch` applies.             |

Use `confirm` to render your own "are you sure?" prompt instead of failing closed with `PushConflictError`, for example in an interactive CLI built on top of this package.

## Function bundling

Deploying a Neon Function means bundling its source into a ZIP archive. By default, `apply`, `pushConfig`, and `createBranch` do this with esbuild:

```ts
type FunctionBundler = (fn: ResolvedFunctionConfig) => Promise<Uint8Array>;

function buildFunctionBundle(fn: ResolvedFunctionConfig): Promise<Uint8Array>;
```

`buildFunctionBundle` is loaded lazily and only when a deploy actually bundles a function, so a caller that never deploys functions, or that supplies its own `bundleFunction`, never pulls esbuild's native binary into their build. Inject a custom bundler via the `bundleFunction` option on `apply` / `pushConfig` / `createBranch` when your runtime can't ship that binary, for example a single-file packaged CLI, or a restricted CI sandbox.

`ResolvedFunctionConfig` (what your bundler receives) has all deploy defaults already applied: `slug`, `name`, `source` (path to the entry file), `env` (resolved key/value pairs), `runtime`, and an optional `dev` block used only by `neon dev`.

**Note:** The `neon` CLI has its own separate `NEON_ESBUILD_PATH` escape hatch for "esbuild not found" errors (see [Deploy and manage Neon Functions](https://neon.com/docs/compute/functions/deploy#deploy-with-neon-functions-deploy)). That variable is read by the CLI's own bundler, not by `buildFunctionBundle` in this package, so it has no effect when you call `@neon/config-runtime` directly. Pass `bundleFunction` instead.

## Load a `neon.ts` file

```ts
function loadConfigFromFile(options?: LoadConfigOptions): Promise<{ config: Config; resolvedPath: string }>;
```

Re-exported from `@neon/config` for convenience. Use it when your script doesn't already have a `Config` object in scope, for example a CI step that runs independently of a bundler that could `import` `neon.ts` directly.

| `LoadConfigOptions` field | Type      | Description                                                             |
| ------------------------- | --------- | ----------------------------------------------------------------------- |
| `path`                    | `string?` | Explicit path to a config file. Takes precedence over the search below. |
| `cwd`                     | `string?` | Starting directory for the upward search. Defaults to `process.cwd()`.  |
| `stopAt`                  | `string?` | Hard ceiling for the upward walk. Defaults to the OS home directory.    |

Without `path`, it walks up from `cwd` looking for `neon.ts` / `neon.mts` / `neon.js` / `neon.mjs`, stopping at the first directory containing `.git` (monorepo-friendly: an intermediate `package.json` doesn't stop the walk).

## A custom CI step

Putting the pieces together: a script that plans and applies a policy against a specific branch, suitable as its own CI job:

```ts filename="scripts/deploy-branch.ts"
import { loadConfigFromFile, plan, apply } from "@neon/config-runtime/v1";

// Resolve these yourself from CI variables, `neon branches list --output json`,
// or the Neon API. This package never reads `.neon` or `NEON_*`.
const projectId = process.env.NEON_PROJECT_ID!;
const branchId = process.env.NEON_BRANCH_ID!;
const apiKey = process.env.NEON_API_KEY!;
const shouldApply = process.env.NEON_APPLY === "true";

const { config } = await loadConfigFromFile();

const target = {
  projectId,
  branchId,
  apiKey,
  updateExisting: true,
  allowProtectedBranch: true,
};

const planned = await plan(config, target);
console.log(`Plan: ${planned.applied.length} change(s) for ${planned.branchName}`);

if (!shouldApply) {
  console.log("Dry run only. Set NEON_APPLY=true to apply this plan.");
  process.exit(0);
}

const result = await apply(config, target);

console.log(`Applied ${result.applied.length} change(s) to ${result.branchName}`);
```

Run it with `tsx` or after compiling with `tsc`, the same as any Node.js script:

```bash
npx tsx scripts/deploy-branch.ts
```

## Error handling

Every error this package throws extends `PlatformError` (also re-exported here from `@neon/config`), which carries a stable `code` string plus optional `details`. Prefer `isPlatformError(err)` over `err instanceof PlatformError`: a `neon.ts` loaded through the internal TypeScript loader ([jiti](https://github.com/unjs/jiti)) imports its own copy of this package, so an error it throws can fail `instanceof` across that boundary. `isPlatformError` checks the `code` string instead, which survives it.

The subclasses relevant to programmatic use:

| Class                                                 | `code`                        | Thrown by             | When                                                                                                                                                                                                                         |
| ----------------------------------------------------- | ----------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PushConflictError`                                   | `PLATFORM_PUSH_CONFLICT`      | `apply`, `pushConfig` | Local policy conflicts with remote state and you passed neither `updateExisting` nor a `confirm` callback, or the conflict can't be resolved. Carries a `conflicts: ConflictReport[]` array.                                 |
| `PushAbortedError`                                    | `PLATFORM_PUSH_ABORTED`       | `apply`, `pushConfig` | Your `confirm` callback returned `false`. Carries `branchName` and `reasons`.                                                                                                                                                |
| `ConfigLoadError`                                     | `PLATFORM_CONFIG_LOAD_FAILED` | `loadConfigFromFile`  | No config file found, or it failed to evaluate.                                                                                                                                                                              |
| `PlatformError` with code `PLATFORM_MISSING_API_KEY`  | `PLATFORM_MISSING_API_KEY`    | any operation         | You passed neither `apiKey` nor an `api` adapter. See [Authentication](https://neon.com/docs/reference/config-runtime#authentication).                                                                                       |
| `PlatformError` with code `PLATFORM_BRANCH_NOT_FOUND` | `PLATFORM_BRANCH_NOT_FOUND`   | any operation         | `branchId` doesn't exist on the project (see [Resolving project and branch ids](https://neon.com/docs/reference/config-runtime#resolving-project-and-branch-ids)), or a policy's `parent` names a branch that doesn't exist. |

A `ConflictReport` (on `PushConflictError.conflicts` and `PushResult.conflicts`) has `kind`, `identifier`, `field`, `current`, `desired`, and a human-readable `reason`.

## Related

- [`neon.ts` reference](https://neon.com/docs/reference/neon-ts): the policy this package operates on, and the `neon config` / `neon deploy` CLI commands that wrap it.
- [neon-pkgs source](https://github.com/neondatabase/neon-pkgs/tree/main/packages/config-runtime) on GitHub.

--- [Document source](https://neon.com/docs/reference/effect-sdk.md) ---

> Summary: @neon/effect wraps the @neon/sdk ergonomic client in Effect v4. Every API method returns an Effect, paginated lists return a Stream, and SDK errors are tagged for Effect.catchTag. Interrupting a fiber cancels the in-flight request and readiness polling, so retries, timeouts, and cancellation compose with the rest of your Effect program. Provide the client with layer(config) or layerConfig, or create one directly with make(config).

# Effect bindings for the Neon SDK

Use the Neon Management SDK with Effect v4 — every call an Effect, every paginated list a Stream, with tagged errors and interruption.

Last updated: 2026-10-02

**What you will learn:**

- How to provide and configure the Effect client
- Which methods return an Effect and which return a Stream
- How tagged errors, cancellation, and deadlines work

**Related resources**

- [Neon Management SDK (@neon/sdk)](https://neon.com/docs/reference/typescript-sdk)
- [Neon API Reference](https://neon.com/docs/reference/api)

**Source code**

- [@neon/effect on npm](https://www.npmjs.com/package/@neon/effect)
- [@neon/effect on GitHub](https://github.com/neondatabase/neon-pkgs/tree/main/packages/effect)

`@neon/effect` provides [Effect](https://effect.website) v4 bindings for the [`@neon/sdk`](https://neon.com/docs/reference/typescript-sdk) ergonomic client (`createNeonClient`). Every API method returns an `Effect`, paginated lists return a `Stream`, and SDK errors are tagged so you can handle them with `Effect.catchTag`. Interrupting a fiber cancels its in-flight HTTP request and any readiness polling.

Use it when you already build with Effect and want retries, timeouts, and cancellation to compose with the rest of your program. If your code doesn't use Effect, use [`@neon/sdk`](https://neon.com/docs/reference/typescript-sdk) directly.

**Note: Requires Effect v4**

Install `effect` v4 alongside `@neon/effect`. The package declares `effect` as a peer dependency and bundles `@neon/sdk` as a dependency.

```bash
npm install @neon/effect effect
```

## Quick start

Set `NEON_API_KEY` (and optionally `NEON_ORG_ID`), then provide the client with `layerConfig`:

```ts
import { Neon, layerConfig } from '@neon/effect';
import { Effect, Stream } from 'effect';

const program = Effect.gen(function* () {
  const neon = yield* Neon;

  const projects = yield* neon.projects.list().pipe(Stream.take(10), Stream.runCollect);

  const project = yield* neon.projects
    .get({ projectId: 'my-project-id' })
    .pipe(Effect.catchTag('NeonNotFoundError', () => Effect.succeed(undefined)));

  return { projects, project };
});

Effect.runPromise(program.pipe(Effect.provide(layerConfig)));
```

## Configuration

`Neon` is a `Context.Service` whose value is a `NeonEffectClient`. Provide it one of three ways:

| Export          | Behavior                                                                                                                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `layer(config)` | Provides `Neon` from explicit configuration. Reads no environment variables. Fails with `NeonClientError` on invalid configuration.                                                         |
| `layerConfig`   | Provides `Neon` through Effect `Config`. Reads required `NEON_API_KEY` with `Config.Redacted` and optional `NEON_ORG_ID` as the default org. Fails with `NeonClientError` or `ConfigError`. |
| `make(config)`  | Returns a `NeonEffectClient` directly, without a network request. Throws `NeonClientError` on invalid configuration.                                                                        |

`NeonEffectConfig` accepts the SDK's [client configuration](https://neon.com/docs/reference/typescript-sdk), excluding `throwOnError`: `apiKey` (string or sync/async function), `orgId`, `baseUrl`, `fetch`, `retries`, `requestTimeoutMs`, `waitForReadiness`, and `wait`.

```ts
import { Neon, layer, make } from '@neon/effect';
import { Effect } from 'effect';

const apiKey = process.env.NEON_API_KEY;
if (!apiKey) throw new Error('NEON_API_KEY is required');

const config = { apiKey, requestTimeoutMs: 10_000 };

// Provide the service to a program:
Effect.runPromise(program.pipe(Effect.provide(layer(config))));

// Or build a client directly:
const neon = make(config);
await Effect.runPromise(neon.projects.get({ projectId: 'my-project-id' }));
```

An empty `apiKey` or an invalid `retries` or `requestTimeoutMs` fails configuration validation.

## Methods and pagination

Method names and named parameters follow the [SDK API reference](https://neon.com/docs/reference/typescript-sdk). Each method takes its SDK per-call options as the last argument, excluding `signal` and `throwOnError`.

```ts
neon.projects.list(undefined, { requestTimeoutMs: 5_000 });
neon.user.me({ requestTimeoutMs: 5_000 });
neon.branches.create({ projectId, name: 'preview' }, { waitForReadiness: true });
neon.operations.waitFor({ operations }, { timeoutMs: 30_000, pollIntervalMs: 250 });
```

Paginated methods return `Stream<Item, NeonEffectError>`:

- `projects.list`, `projects.members.list`
- `branches.list`, `operations.list`
- `functions.list`, `functions.customDomains.list`
- `logs.query`
- `consumption.perProject`, `consumption.perProjectV2`, `consumption.perBranchV2`

Every other method returns `Effect<T, NeonEffectError>`, including array results such as `regions.list` and `postgres.roles.list`. Successful Effects yield the SDK resource directly.

Retries for `423`, `429`, and `503` (including `Retry-After` handling), readiness polling, `createAndConnect`, and connection-string resolution all run through the SDK unchanged.

## Errors

`NeonEffectError` is the union of the tagged error classes below. Each class's `_tag` matches its name, and every error carries `message` and `cause` (the original `@neon/sdk` error), so you can branch on them with `Effect.catchTag`.

| Class / `_tag`            | Fields                                            |
| ------------------------- | ------------------------------------------------- |
| `NeonApiError`            | `status`, `code`, `requestId`, `response`, `body` |
| `NeonNotFoundError`       | Same HTTP fields; 404                             |
| `NeonAuthError`           | Same HTTP fields; 401/403                         |
| `NeonRateLimitError`      | Same HTTP fields; 429 after retries               |
| `NeonOperationError`      | `operationId`, `status`                           |
| `NeonRequestTimeoutError` | `timeoutMs`                                       |
| `NeonWaitTimeoutError`    | `timeoutMs`, `operations`                         |
| `NeonNetworkError`        | `reason`                                          |
| `NeonClientError`         | `message`, `cause`                                |

A wait timeout means the mutation was accepted. Continue waiting on its outstanding operations:

```ts
import { Neon, layerConfig } from '@neon/effect';
import { Effect } from 'effect';

const createBranch = Effect.gen(function* () {
  const neon = yield* Neon;
  return yield* neon.branches
    .create({ projectId: 'my-project-id', name: 'preview' }, { wait: { timeoutMs: 30_000 } })
    .pipe(
      Effect.catchTag('NeonWaitTimeoutError', (error) =>
        neon.operations.waitFor({ operations: error.operations }),
      ),
    );
});

Effect.runPromise(createBranch.pipe(Effect.provide(layerConfig)));
```

Exceptions outside the SDK error hierarchy become Effect defects. Cancellation interrupts the fiber; the SDK's `aborted` error kind has no tagged counterpart.

## Cancellation and deadlines

Interruption through `Effect.timeout`, `Fiber.interrupt`, `Effect.race`, or scope closure aborts the in-flight request and stops readiness polling. Each `Stream` page uses the signal of the Effect that pulls it.

`requestTimeoutMs` bounds each HTTP request and its retries. For a `Stream`, that budget applies to each page. To bound consumption of a whole Stream, apply `Effect.timeout`:

```ts
import { Neon, layerConfig } from '@neon/effect';
import { Effect, Stream } from 'effect';

const projects = Effect.gen(function* () {
  const neon = yield* Neon;
  return yield* neon.projects
    .list(undefined, { requestTimeoutMs: 5_000 })
    .pipe(Stream.runCollect, Effect.timeout('30 seconds'));
});

Effect.runPromise(projects.pipe(Effect.provide(layerConfig)));
```

--- [Document source](https://neon.com/docs/reference/feeds.md) ---

> Summary: Neon RSS feeds give subscribers real-time updates from the Changelog (neon.com/docs/changelog/rss.xml), Blog, Community Guides, and Status page tracking regional uptime. Use this page when you want to monitor Neon releases, blog posts, or incidents without polling the site, including routing feeds into Slack with the /feed subscribe command.

# Neon RSS feeds

Stay updated with the latest news from Neon

Last updated: 2026-07-22

Stay updated with the latest information and announcements from Neon by subscribing to our RSS feeds. You can monitor the Neon Changelog, and blog posts, and Neon status updates through your preferred RSS reader or [Slack channel](https://neon.com/docs/reference/feeds#subscribe-to-feeds-in-slack).

## Changelog

Keep track of new features, improvements, and fixes by subscribing to the [Neon Changelog](https://neon.com/docs/changelog) RSS feed.

```bash
https://neon.com/docs/changelog/rss.xml
```

## Blog

Stay informed on the latest articles and news by following the [Neon Blog](https://neon.com/blog) RSS feed.

```bash
https://neon.com/blog/rss.xml
```

## Community Guides

Get the latest tips, tutorials, and best practices by subscribing to the [Neon Community Guides](https://neon.com/guides) RSS feed.

```bash
https://neon.com/guides/rss.xml
```

## Status

Monitor the operational status of Neon across different regions by subscribing to the [Neon Status](https://neonstatus.com/) RSS feed.

You can find the Neon Status RSS URL by navigating to the [Neon Status](https://neonstatus.com/) page, clicking subscribe, and choosing the RSS option.

## Subscribe to feeds in Slack

To receive updates in Slack, enter the `/feed subscribe` command with the desired RSS feed into your Slack channel:

```bash
/feed subscribe https://neon.com/docs/changelog/rss.xml
```

## Remove feeds from Slack

To remove feeds from Slack, enter the `/feed list` command and note the feed ID number.

Enter `/feed remove [ID number]` to remove the feed.

--- [Document source](https://neon.com/docs/reference/glossary.md) ---

> Summary: The Neon glossary defines platform-specific and Postgres terms including branch, Compute Unit (CU), WAL, autoscaling, pooled connection string, instant restore, and logical replication. Look up Neon concepts like scale-to-zero, Pageserver, history window, Safekeeper, or GB-month, or distinguish Neon-specific usage from standard Postgres terminology. Billing metrics, organization roles, branch types, and Control Plane operations are all defined here.

# Glossary

Last updated: 2026-10-28

## access token

See [Token](https://neon.com/docs/reference/glossary#token).

## active hours

A usage metric that tracks the amount of time a compute is active, rather than idle when suspended due to inactivity. The time that your compute is idle is not counted toward compute usage.

Also see [Compute hours](https://neon.com/docs/reference/glossary#compute-hours).

## Activity Monitor

A process that monitors a Neon compute for activity. During periods of inactivity, the Activity Monitor gracefully places the compute into an idle state to save energy and resources. The Activity Monitor closes idle connections after 5 minutes of inactivity. When a connection is made to an idle compute, the Activity Monitor reactivates the compute.

## Admin

An [Organizations](https://neon.com/docs/reference/glossary#organization) role in Neon with full access to all projects, permissions, invitations, and billing for an organization. Admins can manage members, assign roles, set permissions, and delete the organization.

## API

See [Neon API](https://neon.com/docs/reference/glossary#neon-api).

## API Key

A unique identifier used to authenticate a user or a calling program to an API. An API key is required to authenticate to the Neon API. For more information, see [Manage API keys](https://neon.com/docs/manage/api-keys).

## apply_config

A Neon Control Plane operation that applies a new configuration to a Neon object or resource. For example, creating, deleting, or updating Postgres users and databases initiates this operation. See [System operations](https://neon.com/docs/manage/operations) for more information.

## Archive storage

Cost-efficient storage where Neon archives inactive branches after a defined threshold. For Neon projects created in AWS regions, inactive branches are archived in Amazon S3 storage. For Neon projects created in Azure regions, branches are archived in Azure Blob storage.

## autoscaler-agent

A control mechanism in the Neon autoscaling system that collects metrics from VMs, makes scaling decisions, and performs checks and requests to implement those decisions.

## Autoscaling

A feature that automatically adjusts the allocation of compute resources within specified minimum and maximum compute size boundaries, optimizing for performance and cost-efficiency. For information about how Neon implements the _Autoscaling_ feature, see [Autoscaling](https://neon.com/docs/introduction/autoscaling).

## Availability Checker

A periodic load generated by the Control Plane to determine if a compute can start and read and write data. The Availability Checker queries a system database without accessing user data. You can monitor these checks, how long they take, and how often they occur, on the **Systems operations** tab on the **Monitoring** page in the Neon Console.

## backpressure

A mechanism that manages the lag between the Pageserver and compute node or the Pageserver and Write-Ahead Log (WAL) service. If the WAL service runs ahead of the Pageserver, the time to serve page requests increases, which could result in increased query times or timeout errors. The backpressure mechanism manages lag using a stop-and-wait backend throttling strategy.

## backup branch

A branch created by a [instant restore](https://neon.com/docs/reference/glossary#branch-restore) operation. When you restore a branch from a particular point in time, the current branch is saved as a backup branch.

## branch

An isolated copy of data, similar to a Git branch. Data includes databases, schemas, tables, records, indexes, roles (everything that comprises data in a Postgres instance). Just as a Git branch allows developers to work on separate features or fixes without impacting their main line of code, a Neon branch enables users to modify a copy of their data in isolation from their main line of data. This enables parallel database development, testing, and other workflows, similar to Git's code branching system.

Each Neon project is created with a root branch, which also serves as the default branch. Projects created in the Console have a root branch named `production`, while projects created via the API or CLI have a root branch named `main`.

You can create additional branches as needed. Common examples include:

- **development** - A child branch dedicated to development work, providing an isolated environment for testing changes.
- **staging** - A child branch for staging environments before promoting changes to production.

You can create a branch from the current or past state of another branch. A branch created from the current state of another branch includes the data that existed on that branch at the time of branch creation. A branch created from a past state of another branch includes the data that existed in the past state.

Connecting to a database on a branch requires connecting via a compute attached to the branch. See [Connect to a branch](https://neon.com/docs/manage/branches#connect-to-a-branch).

## branch archiving

The automatic archiving of inactive branches in cost-efficient archive storage after a defined threshold. For more, see [Branch archiving](https://neon.com/docs/guides/branch-archiving).

## Branching

A Neon feature that allows you to create an isolated copy of your data for parallel database development, testing, and other purposes, similar to branching in Git. See [Branch](https://neon.com/docs/reference/glossary#branch).

### Business plan

A legacy paid plan (no longer available) that was designed for mid-to-large enterprises requiring higher compute capacity and advanced security and compliance features. See [Neon plans](https://neon.com/docs/introduction/plans) for current plan options.

## check_availability

A Neon Control Plane operation that checks the availability of data in a branch and that a compute can start on a branch. Branches without a compute are not checked. This operation, performed by the availability checker, is a periodic load generated by the Control Plane. You can monitor these checks, how long they take, and how often they occur, on the **Systems operations** tab on the **Monitoring** page in the Neon Console.

## child branch

A [branch](https://neon.com/docs/reference/glossary#branch) in a Neon project that is created from a [root branch](https://neon.com/docs/reference/glossary#root-branch) or another branch. The source branch is considered the parent branch.

## CI/CD

Continuous integration and continuous delivery or continuous deployment.

## CIDR notation

CIDR (Classless Inter-Domain Routing) notation is a method used to define ranges of IP addresses in network management. It is presented in the format of an IP address, followed by a slash, and then a number (for example, 203.0.113.0/24). The number after the slash represents the size of the address block, providing a compact way to specify a large range of IP addresses. In Neon's IP Allow feature, CIDR notation allows for efficiently specifying a block of IP addresses, especially useful for larger networks or subnets. This can be advantageous when managing access to branches with numerous potential users, such as in a large development team or a company-wide network. For related information, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

## cgroups

Control groups, a Linux kernel feature that allows the organization, prioritization, and accounting of system resources for groups of processes.

## Collaborator

A role in Neon with limited access to specific projects shared with them. Shared projects appear under the "Shared with you" section in the Neon Console.

## Compute

A service that provides virtualized computing resources, equipped with an operating system and a defined amount of RAM. It provides the processing power and resources for running applications. In the context of Neon, a compute runs Postgres and includes supporting components and extensions.

A [compute endpoint](https://neon.com/docs/reference/glossary#compute-endpoint) is the access point for connecting to a Neon compute.

Neon creates a primary read-write compute for the project's default branch. Neon supports both read-write and [read replica](https://neon.com/docs/introduction/read-replicas) computes. A branch can have a single primary (read-write) compute and multiple read replica computes (up to 6 per branch on paid plans). The compute hostname is required to connect to a database from a client or application.

## compute cache

The compute cache is a layer of caching on the compute that stores frequently accessed data from the storage layer, reducing latency and improving query performance by avoiding repeated fetches from storage. Exposed as a single cache, it can span two tiers: Postgres [shared buffers](https://neon.com/docs/reference/glossary#shared-buffers), which are held in memory, and a larger secondary file cache on the compute's local disk. It provides up to 75% of your compute's RAM in capacity. For details, see [What is the compute cache?](https://neon.com/docs/extensions/neon#what-is-the-compute-cache).

## compute endpoint

The network access point for connecting to a [Neon compute](https://neon.com/docs/reference/glossary#compute).

In Neon, a compute endpoint is represented by a hostname, such as `ep-aged-math-668285.us-east-2.aws.neon.tech`, which directs traffic to the appropriate Neon compute. Additional attributes further define a compute endpoint, including `project_id`, `region_id`, `branch_id`, and `type`. These attributes specify the associated Neon project, branch, cloud service region, and whether the endpoint is read-write or read-only. For additional endpoint attributes, refer to the [Neon API](https://neon.com/docs/reference/api/endpoints/create-project-endpoint).

## compute size

The Compute Units (CU) that are allocated to a Neon compute. A Neon compute can have anywhere from .25 to 56 CU. The number of units determines the processing capacity of the compute.

## Compute Unit (CU)

A unit that measures the processing power or "size" of a Neon compute. Each Compute Unit (CU) allocates approximately 4 GB of RAM to the database instance, along with associated CPU and local SSD resources. Scaling up increases these resources linearly. A Neon compute can have anywhere from .25 to 56 CUs. See [Compute size and autoscaling configuration](https://neon.com/docs/manage/computes#compute-size-and-autoscaling-configuration).

## compute hours

A usage metric for tracking compute usage. 1 compute hour is equal to 1 [active hour](https://neon.com/docs/reference/glossary#active-hours) for a compute with 1 CU. If you have a compute with .25 CU, as you would on the Neon Free plan, it would require 4 _active hours_ to use 1 compute hour. On the other hand, if you have a compute with 4 CU, it would only take 15 minutes to use 1 compute hour.

To calculate compute hour usage, you would use the following formula:

```
compute hours = compute size * active hours
```

Also see [Active hours](https://neon.com/docs/reference/glossary#active-hours).

## connection pooling

A method of creating a pool of connections and caching those connections for reuse. Neon supports `PgBouncer` in `transaction mode` for connection pooling. For more information, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

## connection string

A string containing details for connecting to a database. The details include a user name (role), compute hostname, and database name; for example:

```bash
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.c-2.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

The compute hostname includes an `endpoint_id` (`ep-cool-darkness-123456`), a region slug (`c-2.us-east-2`), the cloud platform (`aws`), and Neon domain (`neon.tech`). Connection strings in some AWS regions may include a cell identifier (for example, `c-2`) in the region slug to support scalability in Neon's high-demand regions.

Connection strings for a Neon databases can be obtained by clicking the **Connect** button in the Console nav. For information about connecting to Neon, see [Connect from any application](https://neon.com/docs/connect/connect-from-any-app).

## console

See [Neon Console](https://neon.com/docs/reference/glossary#neon-console).

## Control Plane

The part of the lakebase architecture that manages cloud storage and compute resources.

## Context file

A JSON file (`.neon` by default) used by the Neon CLI to store project and organization context, allowing you to run commands without specifying `--project-id` or `--org-id` each time. The context file is created by the `neon set-context` command or by accepting the CLI's prompt to save your organization as the default.

The CLI determines the context file location by walking up the directory tree from your current directory, stopping when it finds a directory containing `.neon`, `package.json`, or `.git`. The `.neon` file is then read from (or created in) that directory. Using `package.json` and `.git` as markers ensures that context files are stored at your project root rather than in a subdirectory. The search stops at your home directory, so there is no global context file.

Example context file contents:

```json
{
  "orgId": "org-example-12345678",
  "projectId": "cool-forest-86753099"
}
```

For more information, see [Neon CLI commands — set-context](https://neon.com/docs/cli/set-context).

## copy-on-write

A technique used to copy data efficiently. Neon uses the copy-on-write technique when creating [branches](https://neon.com/docs/reference/glossary#branch). When a branch is created, data is marked as shared rather than physically duplicated. Parent and child branches refer to the same physical data resource. Data is only physically copied when a write occurs. The affected portion of data is copied and the write is performed on the copied data.

## create_branch

A Neon Control Plane operation that creates a branch in a Neon project. For related information, see Manage branches. See [System operations](https://neon.com/docs/manage/operations) for more information.

## create_timeline

Sets up storage and creates the default branch when a Neon [project](https://neon.com/docs/reference/glossary#project) is created. See [System operations](https://neon.com/docs/manage/operations) for more information.

## data-at-rest encryption

A method of storing inactive data that converts plaintext data into a coded form or cipher text, making it unreadable without an encryption key. Neon stores inactive data in [NVMe SSD volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ssd-instance-store.html#nvme-ssd-volumes). The data on NVMe instance storage is encrypted using an XTS-AES-256 block cipher implemented in a hardware module on the instance.

## Data transfer

A usage metric that measures the total volume of data transferred out of Neon (egress) during a billing period. Egress also includes data transferred from Neon via Postgres logical replication to any destination, including Neon itself. Each Free plan project is limited to 5 GB per month.

## Database

A named collection of database objects. A Neon project is created with a database that resides in the default `public` schema. If you do not specify a name for the database when creating a Neon project, it's created with the name `neondb`. A Neon project can contain multiple databases. Users cannot manipulate system databases, such as the `postgres`, `template0`, or `template1` databases.

## database branching

See [Branching](https://neon.com/docs/reference/glossary#branching).

## database fleet

A collection of database instances, typically managed as a single entity.

## decoder plugin

Utilized in PostgreSQL replication architecture to decode WAL entries into a format understandable by the subscriber. The `pgoutput` decoder plugin is the default decoder, with alternatives like `wal2json` for specific use cases. Neon supports `pgoutput` and `wal2json`. See [Postgres logical replication concepts](https://neon.com/docs/guides/logical-replication-concepts).

## dedicated resources

Resources including compute and storage dedicated to a single Neon account.

## delete_tenant

A Neon Control Plane operation that deletes stored data when a Neon project is deleted. See [System operations](https://neon.com/docs/manage/operations) for more information.

## Endpoint ID

A string that identifies a Neon compute endpoint. Neon Endpoint IDs are generated Heroku-like memorable random names, similar to `ep-calm-flower-a5b75h79`. These names are always prefixed by `ep` for "endpoint". You can find your Endpoint ID by navigating to your project in the Neon Console, selecting **Branches** in the sidebar, and clicking on a branch. The **Endpoint ID** is shown in the table under the **Computes** heading.

## Egress

The data transferred out of the Neon service to an external destination. See [Data transfer](https://neon.com/docs/reference/glossary#data-transfer).

## Enterprise plan

A legacy paid plan offered by Neon. See [Neon plans](https://neon.com/docs/introduction/plans).

## Free plan

See [Neon plans](https://neon.com/docs/introduction/plans) for details about the Free plan.

## GB-month

In Neon, **GB-month** is a unit of measure representing the storage of 1 gigabyte (GB) of data for one month. A gigabyte is defined as 10^9 bytes (1,000,000,000 bytes). Storage usage is measured periodically and accumulated over the billing period. At the start of each billing period, GB-month usage resets to zero.

GB-month usage reflects both the amount of storage used and how long it was used. For example, storing 10 GB for an entire month results in **10 GB-months**, while storing 10 GB for half a month results in **5 GB-months**.

Deleting data will reduce the rate at which GB-month usage increases from that point forward, but it does not decrease the GB-month usage accrued up to that point.

## History

The history of data changes for all branches in your Neon project. This history is retained to support [instant restore](https://neon.com/docs/introduction/branch-restore), [Time Travel](https://neon.com/docs/guides/time-travel-assist), and other data recovery features. See [History window](https://neon.com/docs/introduction/history-window) for how long Neon retains that history for **instant restore** and related features.

## Instant restore

Restoration of data to a state that existed at an earlier time. Neon retains a history of changes in the form of Write-Ahead-Log (WAL) records; your project's **[history window](https://neon.com/docs/introduction/history-window)** setting controls how long that history is kept, which defines how far back **instant restore** can go. For more information, see [Instant restore](https://neon.com/docs/introduction/branch-restore).

## IP Allow

A Neon feature used to control which IP addresses can access databases in a Neon project, often used to restrict public internet access. See [IP Allow](https://neon.com/docs/introduction/ip-allow).

## IP allowlist

An IP allowlist is a security measure used in network and database management. It specifies a list of IP addresses that are permitted to access a certain resource. Any IP address not on the list is automatically blocked, ensuring that only authorized users or systems can gain access. For more information, see [Configure the IP Allow list](https://neon.com/docs/manage/projects#configure-tip-allow).

## Kubernetes

An open-source container orchestration platform that automates the deployment, scaling, and management of containerized applications.

## Kubernetes cluster

A set of interconnected nodes that run containerized applications and services using Kubernetes, an open-source orchestration platform for automating deployment, scaling, and management of containerized applications. The cluster consists of at least one control plane node, which manages the overall state of the cluster, and multiple worker nodes, where the actual application containers are deployed and executed. The worker nodes communicate with the control plane node to ensure the desired state of the applications is maintained.

## Kubernetes node

A worker machine in a Kubernetes cluster, which runs containerized applications.

## Kubernetes scheduler

A component of Kubernetes that assigns newly created pods to nodes based on resource availability and other constraints.

## KVM

Kernel-based Virtual Machine, a virtualization infrastructure built into the Linux kernel that allows it to act as a hypervisor for virtual machines.

## Launch plan

A Neon plan designed for startups and growing teams that need more resources, features, and flexibility. It offers usage-based pricing, starting at $5/month. See [Neon plans](https://neon.com/docs/introduction/plans).

## live migration

A feature provided by some hypervisors, such as QEMU, that allows the transfer of a running virtual machine from one host to another with minimal interruption.

### logical data size

For a Postgres database, it is the size of the database, including all tables, indexes, views, and stored procedures. In Neon, a branch can have multiple databases. The logical data size for a branch is therefore equal to the total logical size of all databases on the branch.

## Live SQL

Live SQL queries are queries that can be subscribed to live, in realtime. You can use Live SQL with [Realtime](https://neon.com/docs/realtime/overview) to subscribe to data changes and build apps with full reactivity on standard Postgres. See [Live SQL queries](https://neon.com/docs/introduction/live-sql-queries).

## Live SQL API

The primary web service API provided to clients by [Realtime](https://neon.com/docs/realtime/overview) to subscribe to [Live SQL](https://neon.com/docs/introduction/live-sql-queries) queries.

## logical replication

A method of replicating data between databases or platforms, focusing on replicating transactional changes (like `INSERT`, `UPDATE`, `DELETE`) rather than the entire database, enabling selective replication of specific tables or rows. See [Logical replication](https://neon.com/docs/guides/logical-replication-guide).

## LSN

Log Sequence Number. A byte offset to a location in the [WAL stream](https://neon.com/docs/reference/glossary#wal-stream). The Neon branching feature supports creating branches with data up to a specified LSN.

## LRU policy

Least Recently Used policy, an algorithm for cache replacement that evicts the least recently accessed items first.

## Monitoring Dashboard

A feature of the Neon Console that provides several graphs to help you monitor system and database metrics, updated in real time based on your usage data.

## Member

An [Organizations](https://neon.com/docs/reference/glossary#organization) role in Neon with access to all projects within the organization. Members cannot manage billing, members, or permissions. They must be invited to the organization by an [Admin](https://neon.com/docs/reference/glossary#admin).

## Neon

The backend for apps and agents. Includes Lakebase Postgres, Managed Better Auth, Data API, [AI Gateway](https://neon.com/docs/ai-gateway/overview), [Object Storage](https://neon.com/docs/storage/overview), and [Functions](https://neon.com/docs/compute/functions/overview). Lakebase Postgres is serverless, with autoscaling, branching, instant restore, and scale-to-zero. For more information, see [Why Neon?](https://neon.com/docs/get-started/why-neon).

## Neon API

The Neon RESTful Application Programming Interface. Any operation performed in the Neon Console can also be performed using the Neon API.

## Neon Console

A browser-based graphical interface for managing Neon projects and resources.

## Neon Free plan

A Neon plan for which there are no usage charges. For information about the Neon Free plan and associated limits, see [Neon plans](https://neon.com/docs/introduction/plans).

## Neon Proxy

A component of the Neon platform that acts as an intermediary between connecting clients and compute nodes where Postgres runs. The Neon Proxy is responsible for tasks such as connection routing, authentication, and metrics collection. From a security perspective, it helps protect the integrity of the Neon platform through a combination of authentication, authorization, and other security measures.

## Neon user

The user account that registers and authenticates with Neon using an email, GitHub, Google, or partner account. After authenticating, a Neon user account can create and manage projects, branches, users, databases, and other project resources.

## Neon Org

A named organization entity in Neon that groups multiple Neon users under a shared account. See [Organization](https://neon.com/docs/reference/glossary#organization) for details.

## NeonVM

A QEMU-based tool used by Neon to create and manage VMs within a Kubernetes cluster, allowing for the allocation and deallocation of compute resources. For more information, refer to the NeonVM source in the [neondatabase/autoscaling](https://github.com/neondatabase/autoscaling/tree/main/neonvm) repository.

## non-default branch

Any branch in a Neon project that is not designated as the [default branch](https://neon.com/docs/reference/glossary#default-branch). For more information, see [Non-default branch](https://neon.com/docs/manage/branches#non-default-branch).

## Organization

A feature in Neon that enables teams to collaborate on projects under a shared account. Organizations provide centralized management for billing, user roles, and project collaboration. Members can be invited to join, and roles such as Admin, Member, and Collaborator determine access and permissions within the organization.

Admins oversee all aspects of the organization, including managing members, permissions, billing, and projects. Members have access to all organizational projects but cannot manage billing or members. Collaborators have limited access to specific projects shared with them and do not have access to the organization dashboard.

Neon organizations can be free or paid. You can create new organizations at any time. For more, see [Organizations](https://neon.com/docs/manage/organizations).

## Page

An 8KB unit of data, which is the smallest unit that Postgres uses for storing relations and indexes on disk. In Neon, a page is also the smallest unit of data that resides on a Pageserver. For information about Postgres page format, see [Database Page Layout](https://www.postgresql.org/docs/14/storage-page-layout.html), in the _PostgreSQL Documentation_.

## Paid plan

A paid Neon service plan. See [Neon plans](https://neon.com/docs/introduction/plans).

## Pageserver

A lakebase architecture component that reads WAL records from Safekeepers to identify modified pages. The Pageserver accumulates and indexes incoming WAL records in memory and writes them to disk in batches. Each batch is written to an immutable file that is never modified after creation. Using these files, the Pageserver can quickly reconstruct any version of a page dating back to the limit set by your project's [history window](https://neon.com/docs/introduction/history-window). Neon retains a history for all branches.

The Pageserver uploads immutable files to cloud storage, which is the final, highly durable destination for data. After a file is successfully uploaded to cloud storage, the corresponding WAL records can be removed from the Safekeepers.

## passwordless authentication

The ability to authenticate without providing a password. Neon's [Passwordless auth](https://neon.com/docs/reference/glossary#passwordless-auth) feature supports passwordless authentication.

## peak usage

Peak usage is the highest amount of a resource (like storage or projects) you've used during the current billing period. If you go over your plan's limit, extra charges are added in set increments. You're charged for these extra units from the date you went over the limit, with the charges prorated for the rest of the month.

## point-in-time restore (PITR)

A database recovery capability that allows restoring data to a specific moment in the past using Write-Ahead Log (WAL) records. In Neon, this capability is implemented through the instant restore feature, which performs point-in-time restores with near-zero delay.

## pooled connection string

A pooled connection string in Neon includes a `-pooler` option, which directs your connection to a pooled connection port at the Neon Proxy. This is an example of a pooled connection:

```text
postgresql://alex:AbC123dEf@ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

A pooled connection can support a high number of concurrent users and is recommended for use with serverless and edge functions. For more information, see [Connection pooling](https://neon.com/docs/connect/connection-pooling).

You can obtain a pooled connection string for your database by clicking the **Connect** button in the Console nav. Select the **Connection pooling** option to add the `-pooler` option to the connection string. For further instructions, see [How to use connection pooling](https://neon.com/docs/connect/connection-pooling#how-to-use-connection-pooling).

## PostgreSQL

An open-source relational database management system (RDBMS) emphasizing extensibility and SQL compliance.

## Postgres role

A Postgres role is an entity that can own database objects and has privileges to perform database actions.

A Postgres role named `neondb_owner` is created with each Neon project by default. This role owns the ready-to-use `neondb` database, also created by default with each new Neon project. This role and any additional role created in the Neon Console, API, or CLI is assigned the [neon_superuser](https://neon.com/docs/manage/roles#the-neonsuperuser-role) role, which allows creating databases, roles, and reading and writing data in all tables, views, sequences. Roles created with SQL are created with the same basic [public schema privileges](https://neon.com/docs/manage/database-access#public-schema-privileges) granted to newly created roles in a standalone Postgres installation. These users are not assigned the `neon_superuser` role. They must be selectively granted permissions for each database object. For more information, see [Manage database access](https://neon.com/docs/manage/database-access).

Older projects may have a `web-access` system role, used by the [SQL Editor](https://neon.com/docs/reference/glossary#sql-editor) and Neon's [Passwordless auth](https://neon.com/docs/reference/glossary#passwordless-auth). The `web-access` role is system-managed. It cannot be modified, removed, or used in other authentication scenarios.

## Private Networking

A feature in Neon that allows secure connections to Neon databases through AWS PrivateLink, bypassing the open internet. This ensures all data traffic remains within AWS's private network for enhanced security and compliance. See [Private Networking](https://neon.com/docs/guides/neon-private-networking).

## default branch

A designation that is given to a [branch](https://neon.com/docs/reference/glossary#branch) in a Neon project. Each Neon project is initially created with a [root branch](https://neon.com/docs/reference/glossary#root-branch) (named `production` in the Console, `main` via API/CLI), which carries the _default branch_ designation by default.

When creating a new branch without specifying the parent, a new branch is created from your project's default branch. The [Neon-Managed Vercel integration](https://neon.com/docs/guides/neon-managed-vercel-integration) also creates preview deployment branches from your project's default branch.

You can change your default branch, but a branch carrying the default branch designation cannot be deleted.

For more information, see [default branch](https://neon.com/docs/manage/branches#default-branch).

## Default organization

The organization stored in a Neon CLI [context file](https://neon.com/docs/reference/glossary#context-file) (`.neon`), used when no `--org-id` option is specified.

When you run a Neon CLI command without specifying an organization (via `--org-id` or a context file), the CLI prompts you to select one and offers to save it as your default. Only if you choose to save does the CLI create a `.neon` context file containing the selected organization ID.

Since the CLI walks up the directory tree to find context files, a `.neon` file in your project root serves as the default organization for that project and all its subdirectories. You can also set it explicitly using `neon set-context --org-id <org-id>`.

For more information, see [Neon CLI commands — set-context](https://neon.com/docs/cli/set-context).

## Project

A collection of branches, databases, roles, and other project resources and settings. A project contains a primary [compute](https://neon.com/docs/reference/glossary#compute) that runs Postgres. It may also include [read replicas](https://neon.com/docs/reference/glossary#read-replica). A Neon account may have multiple projects.

## Project ID

A string that identifies your Neon project. Neon Project IDs are generated Heroku-like memorable random names, similar to `cool-forest-86753099`. You can find your project ID by navigating to your project in the Neon Console and selecting **Settings** from the sidebar. The project ID is also visible in the Neon Console URL after navigating to a project: `https://console.neon.tech/app/projects/cool-forest-86753099`

## Project Collaboration

A feature that lets you invite other Neon users to work on a project together. Note that organization members don't need to be added as collaborators since they automatically get access to all organization projects. See [Invite collaborators](https://neon.com/docs/manage/projects#invite-collaborators-to-a-project) for more information.

## Project storage

The total volume of data stored in your Neon project.

## prorate

Adjusting a payment or charge so it corresponds to the actual usage or time period involved, rather than charging a full amount. Neon prorates the cost for extra units of storage when you exceed your plan's allowance. For example, if you purchase an extra unit of storage halfway through the monthly billing period, you are only charged half the unit price.

## Proxy

A Neon component that functions as a multitenant service that accepts and handles connections from clients that use the Postgres protocol.

## Protected Branches

A feature in Neon you can use to designate a Neon branch as "protected", which enables a series of protections:

- Protected branches cannot be deleted.
- Protected branches cannot be [reset](https://neon.com/docs/manage/branches#reset-a-branch-from-parent).
- Projects with protected branches cannot be deleted.
- Computes associated with a protected branch cannot be deleted.
- New passwords are automatically generated for Postgres roles on branches created from protected branches. [See below](https://neon.com/docs/reference/glossary#new-passwords-generated-for-postgres-roles-on-child-branches).
- With additional configuration steps, you can apply IP Allow restrictions to protected branches only. See [below](https://neon.com/docs/reference/glossary#how-to-apply-ip-restrictions-to-protected-branches).
- Protected branches are not [archived](https://neon.com/docs/guides/branch-archiving) due to inactivity.

The protected branches feature is available on all Neon paid plans. Typically, the protected branch status is given to a branch or branches that hold production data or sensitive data. For information about how to configure a protected branch, refer to our [Protected branches guide](https://neon.com/docs/guides/protected-branches).

## Publisher

In the context of logical replication, the publisher is the primary data source where changes occur. It's responsible for sending those changes to one or more subscribers. A Neon database can act as a publisher in a logical replication setup. See [Logical replication](https://neon.com/docs/guides/logical-replication-guide).

## QEMU

A free and open-source emulator and virtualizer that performs hardware virtualization.

## RAM

Random Access Memory, a type of computer memory used to store data that is being actively processed.

## reactive DX

The development model of building reactive apps with live data bindings between the client and the server. Application code typically defines declarative data bindings (aka live queries) and mutations and the system takes care of handling data transfer and synchronization. You can build reactive apps with a fully reactive, end-to-end, type-safe DX on standard Postgres using [Realtime](https://neon.com/docs/realtime/overview). See [Reactivity](https://neon.com/docs/introduction/reactivity).

## read replica

A read replica in Neon is a read-only compute that connects to the same underlying storage as the primary read-write compute but operates in read-only mode. It lets you offload read queries from your primary compute to improve performance and scalability, especially for analytical or reporting workloads. Read replica computes can be added to a branch or removed without affecting the primary compute.

## Realtime

Neon's realtime service, with [live SQL](https://neon.com/docs/reference/glossary#live-sql) and [reactive DX](https://neon.com/docs/reference/glossary#reactive-dx) for building apps and agents on standard Postgres. See [Realtime](https://neon.com/docs/realtime/overview).

## region

The geographic location where Neon project resources are located. Neon supports creating projects in Amazon Web Services (AWS) and Azure regions. For information about regions supported by Neon, see [Regions](https://neon.com/docs/introduction/regions).

## replication slot

On the publisher database in a logical replication setup, replication slots track the progress of replication to ensure no data in the WAL is purged before the subscriber has successfully replicated it, thus preventing data loss or inconsistency. See [Postgres logical replication concepts](https://neon.com/docs/guides/logical-replication-concepts).

## resale

Selling the Neon service as part of another service offering.

## History window

The Neon Console setting (under **Settings → Postgres**) that controls how long Neon retains change history for your branches. It defines how far back **[instant restore](https://neon.com/docs/reference/glossary#instant-restore)** can reach and how far back you can run [Time Travel](https://neon.com/docs/reference/glossary#time-travel) queries or branch from past states. It is configurable per project and affects **History** usage (instant restore storage) on your bill. See [History window](https://neon.com/docs/introduction/history-window).

## root branch

Each Neon project is created with a root branch, which cannot be deleted and is set as the [default branch](https://neon.com/docs/reference/glossary#default-branch) for the project. Projects created in the Console have a root branch named `production`, while projects created via the API or CLI have a root branch named `main`. A root branch has no parent branch.

Neon also supports two other types of root branches that have no parent but _can_ be deleted:

- [Backup branches](https://neon.com/docs/reference/glossary#backup-branch), created by instant restore operations on other root branches.
- [Schema-only branches](https://neon.com/docs/reference/glossary#schema-only-branch).

The number of root branches allowed in a project depends on your Neon plan. See [Branch types: Root branch](https://neon.com/docs/manage/branches#root-branch).

## Safekeeper

A lakebase architecture component responsible for the durability of database changes. Postgres streams WAL records to Safekeepers. A quorum algorithm based on Paxos ensures that when a transaction is committed, it is stored on a majority of Safekeepers and can be recovered if a node is lost. Safekeepers are deployed in different availability zones to ensure high availability and durability.

## Scale plan

A Neon pricing plan designed for scaling production workloads. See [Neon plans](https://neon.com/docs/introduction/plans).

## Scale to Zero

A Neon feature that suspends a compute after a specified period of inactivity (5 minutes by default) to minimize compute usage. When suspended, a compute is placed into an idle state. Otherwise, the compute is in an `Active` state. Users on paid plans can disable the _Scale to Zero_ feature for an "always-active" compute. For more information, see [Edit a compute](https://neon.com/docs/manage/endpoints#edit-a-compute).

## schema-only branch

A branch that replicates only the database schema from a source branch, without copying any of the actual data. This feature is particularly valuable when working with sensitive information. Rather than creating branches that include confidential data, you can duplicate just the database structure and then populate it with your own data.

Schema-only branches are [root branches](https://neon.com/docs/reference/glossary#root-branch), meaning they have no parent. As a root branch, each schema-only branch starts an independent line of data in a Neon project.

See [Schema-only branches](https://neon.com/docs/guides/branching-schema-only).

## Schema Diff

A Neon feature that lets you compare database schemas between different branches for better debugging, code review, and team collaboration. See [Schema Diff](https://neon.com/docs/guides/schema-diff).

## Concurrently active compute limit

This limit caps how many computes can run at the same time to prevent resource exhaustion. It protects against accidental surges, such as starting many endpoints at once. The default limit is 20 concurrently active computes.

When you exceed the limit, additional computes beyond the limit will remain suspended and you will see an error when attempting to connect to them. You can suspend other active computes and try again. Alternatively, if you encounter this error often, you can reach out to [Support](https://neon.com/docs/introduction/support) to request a `max_active_endpoints` limit increase.

## serverless

A cloud-based development model that enables developing and running applications without having to manage servers.

## shared buffers

A memory area in Postgres for caching blocks of data from storage (disk on standalone Postgres or Pageservers in Neon). This cache enhances the performance of database operations by reducing the need to access the slower storage for frequently accessed data. In Neon, `shared_buffers` is the in-memory tier of the [compute cache](https://neon.com/docs/reference/glossary#compute-cache), and its value [differs by compute size](https://neon.com/docs/reference/compatibility#parameter-settings-that-differ-by-compute-size). For additional information about shared buffers in Postgres, see [Resource Consumption](https://www.postgresql.org/docs/current/runtime-config-resource.html), in the Postgres documentation.

## Snapshot

A read-only, point-in-time copy of a root branch's complete state, including the schema and all data. A snapshot is created instantly with minimal performance impact. See [Backup & restore](https://neon.com/docs/guides/backup-restore) for details.

## SNI

Server Name Indication. A TLS protocol extension that allows a client or browser to indicate which hostname it wants to connect to at the beginning of a TLS handshake.

## SQL Editor

A feature of the Neon Console that enables running queries on a Neon database. The SQL Editor also enables saving queries, viewing query history, and analyzing or explaining queries.

## start_compute

A Neon Control Plane operation that starts a compute when there is an event or action that requires compute resources. For example, connecting to a suspended compute initiates this operation. See [System operations](https://neon.com/docs/manage/operations) for more information. For information about how Neon manages compute resources, see [Compute lifecycle](https://neon.com/docs/introduction/compute-lifecycle).

## Storage

Where data is recorded and stored. Neon's database storage consists of Pageservers, which store hot data, and a cloud object store, such as Amazon S3, that stores cold data for cost optimization and durability.

Also, a usage metric that tracks the total volume of data and [history](https://neon.com/docs/reference/glossary#history) stored in Neon. For more information, see [Storage](https://neon.com/docs/reference/glossary#storage).

## subscriber

The database or platform receiving changes from the publisher in a logical replication setup. It applies changes received from the publisher to its own data set. Currently, a Neon database can only act as a publisher in a logical replication setup. See [Logical replication](https://neon.com/docs/guides/logical-replication-guide).

## subscription

Represents the downstream side of logical replication, establishing a connection to the publisher and subscribing to one or more publications to receive updates. See [Postgres logical replication concepts](https://neon.com/docs/guides/logical-replication-concepts).

## suspend_compute

A Neon Control Plane operation that suspends a compute after a period of inactivity. See [System operations](https://neon.com/docs/manage/operations) for more information. For information about how Neon manages compute resources, see [Compute lifecycle](https://neon.com/docs/introduction/compute-lifecycle).

## sync

Data synchronization: keeping data consistent and in sync between Postgres and client applications.

## technical preview

An early version of a feature or changes released for testing and feedback purposes.

## tenant_attach

A Neon Control Plane operation that attaches a Neon project to storage. For example, this operation occurs when you create a new Neon project. See [System operations](https://neon.com/docs/manage/operations) for more information.

## tenant_detach

A Neon Control Plane operation that detaches a Neon project from storage. For example, this operation occurs after the project as been idle for 30 days. See [System operations](https://neon.com/docs/manage/operations) for more information.

## tenant_reattach

A Neon Control Plane operation that reattaches a Neon project to storage. For example, this operation occurs when a detached Neon project receives a request. See [System operations](https://neon.com/docs/manage/operations) for more information.

## token

An encrypted access token that enables you to authenticate with Neon using the Neon API. An access token is generated when creating a Neon API key. For more information, see [Manage API keys](https://neon.com/docs/manage/api-keys).

## unpooled connection string

An unpooled connection string connects to your Neon database directly. It does not use [connection pooling](https://neon.com/docs/reference/glossary#connection-pooling), and it looks similar to this:

```text
postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require
```

You can obtain an unpooled connection string for your database by clicking the **Connect** button in the Console nav. Ensure that the **Connection pooling** option is **not** selected. A direct connection is subject to the `max_connections` limit for your compute. For more information, see [How to size your compute](https://neon.com/docs/manage/endpoints#how-to-size-your-compute).

## Time Travel

A Neon feature that lets you connect to any selected point in time still covered by your [history window](https://neon.com/docs/introduction/history-window) for **instant restore**, and run queries against that connection. See [Time Travel](https://neon.com/docs/guides/time-travel-assist).

## user

See [Neon user](https://neon.com/docs/reference/glossary#neon-user) and [Postgres role](https://neon.com/docs/reference/glossary#postgresql-role).

## vm-monitor

A program that runs inside the VM alongside Postgres, responsible for requesting more resources from the autoscaler-agent and validating proposed downscaling to ensure sufficient memory.

## WAL

See [Write-Ahead Logging](https://neon.com/docs/reference/glossary#write-ahead-logging-wal).

## WAL receiver

In logical replication, on the subscriber side, the WAL receiver is a process that receives the replication stream (decoded WAL data) and applies these changes to the subscriber's database. See [Postgres logical replication concepts](https://neon.com/docs/guides/logical-replication-concepts).

## WAL sender

In logical replication, the WAL sender is a process on the publisher database that reads the WAL and sends relevant data to the subscriber. See [Postgres logical replication concepts](https://neon.com/docs/guides/logical-replication-concepts).

## WAL slice

Write-ahead logs in a specific LSN range.

## WAL stream

The stream of data written to the Write-Ahead Log (WAL) during transactional processing.

## working set

A subset of frequently accessed or recently used data and indexes that ideally reside in memory (RAM) for quick access, allowing for better performance. See [how to size your compute](https://neon.com/docs/manage/endpoints#how-to-size-your-compute) to learn how to set your minimum compute to an adequate size to handle your working set.

## Write-Ahead Logging (WAL)

A standard mechanism that ensures the durability of your data. Neon relies on WAL to separate storage and compute, and to support features such as branching and instant restore.

In logical replication, the WAL records all changes to the data, serving as the source for data that needs to be replicated.

## Written data

A usage metric that measures the total volume of data written from compute to storage within a given billing period, measured in gigabytes (GB). Writing data from compute to storage ensures the durability and integrity of your data.

--- [Document source](https://neon.com/docs/reference/javascript-sdk.md) ---

> Summary: The `@neon/neon-js` TypeScript SDK combines Managed Better Auth and the Neon Data API in one client, covering auth methods (email/password, OAuth, OTP, password reset) alongside a PostgREST-style query builder (select, insert, update, delete, rpc, filters) with automatic JWT forwarding. Choose this page over the standalone `@neon/postgrest-js` or `@neon/auth` packages when you need the full combined API reference in one place. Three adapters are documented: BetterAuthVanillaAdapter (default, Promise-based), BetterAuthReactAdapter (React hooks), and SupabaseAuthAdapter (Supabase-compatible migration path).

# Managed Better Auth and Data API SDK

Reference documentation for @neon/neon-js (authentication and Data API database queries)

Last updated: 2026-08-31

This page documents `@neon/neon-js`, which combines Managed Better Auth and the Data API in a single client. Neon also publishes standalone packages:

- [`@neon/postgrest-js`](https://neon.com/docs/data-api/get-started#any-authentication-provider): Data API with any authentication provider
- [`@neon/auth`](https://www.npmjs.com/package/@neon/auth): Managed Better Auth without the Data API

Authentication is provided through an adapter-based architecture, letting you work more easily with your existing code or preferred framework. Available adapters:

- **BetterAuthVanillaAdapter** (default): Promise-based authentication methods like `client.auth.signIn.email()`. Used in all examples on this page.
- **BetterAuthReactAdapter**: Similar API but with React hooks like `useSession()`. See the [React quickstart](https://neon.com/docs/auth/quick-start/react).
- **SupabaseAuthAdapter**: Supabase-compatible API for easy migration, built into `createClient` from `@neon/neon-js/supabase`. See the [migration guide](https://neon.com/docs/auth/migrate/from-supabase).

Database query methods (`client.from()`, `.select()`, etc.) work the same regardless of which adapter you use.

## Installation

Install the TypeScript SDK in your project using npm, yarn, pnpm, or bun.

```bash
npm install @neon/neon-js
```

## Initialize the client

Method: `createClient(), createAuthClient()`

**Full client (`createClient`)**

Use this when you need both authentication and database queries. You get:

- Auth methods like `client.auth.signIn.email()` and `client.auth.signUp.email()`.
- Database queries like `client.from('todos').select()` and `client.from('users').insert()`.

**Auth-only client (`createAuthClient`)**

Use this when you only need authentication (no database queries). You get:

- Auth methods like `auth.signIn.email()` and `auth.signUp.email()`
- No database query methods

The auth methods are identical; only the access path differs. `client.auth.signIn.email()` and `auth.signIn.email()` do the same thing.

For the full client, pass a single HTTPS Neon database URL without credentials or query parameters. The SDK derives the Managed Better Auth URL and Data API URL automatically. If you already have a Managed Better Auth URL or Data API URL, use the same URL without the `.neonauth` or `.apirest` hostname label and without the trailing `/auth` or `/rest/v1` path. The cell label (if present), region, and database path stay the same. If you need to override either derived URL, the object form is still supported.

**Full client**

```typescript
import { createClient } from '@neon/neon-js';

// Use your Neon database URL without credentials or query parameters.
// Example: https://ep-example.c-2.us-east-1.aws.neon.tech/neondb
const client = createClient(import.meta.env.VITE_NEON_DATABASE_URL);
```

**Auth-only**

```typescript
import { createAuthClient } from '@neon/neon-js/auth';

const auth = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL);
```

**With TypeScript types**

```typescript
import { createClient } from '@neon/neon-js';
import type { Database } from './types/database.types';

const client = createClient<Database>(import.meta.env.VITE_NEON_DATABASE_URL);
```

**With a different adapter**

```typescript
import { createClient } from '@neon/neon-js';
import { BetterAuthReactAdapter } from '@neon/neon-js/auth/react/adapters';

const client = createClient(import.meta.env.VITE_NEON_DATABASE_URL, {
  auth: {
    adapter: BetterAuthReactAdapter(),
  },
});
```

The object form remains available for custom endpoint layouts or local development setups where the Auth and Data API URLs cannot be derived from the same Neon database URL:

```typescript
const client = createClient({
  auth: {
    url: import.meta.env.VITE_NEON_AUTH_URL,
  },
  dataApi: {
    url: import.meta.env.VITE_NEON_DATA_API_URL,
  },
});
```

## Create a new user account

Method: `auth.signUp.email()`

- Returns user and session data on success
- User data is stored in your database
- Sessions are managed automatically

### Parameters

<details>

<summary>View parameters</summary>

| Parameter   | Type                | Required |
| ----------- | ------------------- | -------- |
| email       | string              | ✓        |
| name        | string              | ✓        |
| password    | string              | ✓        |
| image       | string \| undefined |          |
| callbackURL | string \| undefined |          |

</details>

```typescript
const result = await client.auth.signUp.email({
  email: 'user@example.com',
  password: 'password123',
  name: 'John Doe'
})

if (result.error) {
console.error('Sign up error:', result.error.message)
} else {
console.log('User created:', result.data.user)
}

```

## Sign in with email and password

Method: `auth.signIn.email()`

- Returns user and session on success
- Session tokens are cached automatically
- Authentication state syncs across browser tabs

### Parameters

<details>

<summary>View parameters</summary>

| Parameter   | Type                 | Required |
| ----------- | -------------------- | -------- |
| email       | string               | ✓        |
| password    | string               | ✓        |
| rememberMe  | boolean \| undefined |          |
| callbackURL | string \| undefined  |          |

</details>

```typescript
const result = await client.auth.signIn.email({
  email: 'user@example.com',
  password: 'password123'
})

if (result.error) {
console.error('Sign in error:', result.error.message)
} else {
console.log('Signed in:', result.data.user.email)
}

```

## Sign in with OAuth provider

Method: `auth.signIn.social()`

Sign in with an OAuth provider like Google, GitHub, etc.

- Redirects user to provider's authorization page
- User is redirected back after authorization
- Session is created automatically

### Parameters

<details>

<summary>View parameters</summary>

| Parameter          | Type                   | Required |
| ------------------ | ---------------------- | -------- |
| provider           | string                 | ✓        |
| callbackURL        | string \| undefined    |          |
| newUserCallbackURL | string \| undefined    |          |
| errorCallbackURL   | string \| undefined    |          |
| disableRedirect    | boolean \| undefined   |          |
| idToken            | object                 |          |
| scopes             | string\[] \| undefined |          |
| requestSignUp      | boolean \| undefined   |          |
| loginHint          | string \| undefined    |          |
| additionalData     | object                 |          |

</details>

**Sign in with GitHub**

```typescript
await client.auth.signIn.social({
  provider: 'github',
  callbackURL: 'https://yourapp.com/auth/callback',
});
```

**Sign in with custom redirect**

```typescript
await client.auth.signIn.social({
  provider: 'google',
  callbackURL: 'https://yourapp.com/auth/callback',
});
```

## Sign out

Method: `auth.signOut()`

- Clears local session cache
- Notifies other browser tabs (cross-tab sync)
- Removes authentication tokens

```typescript
const { error } = await client.auth.signOut()

if (error) {
console.error('Sign out error:', error.message)
}

```

## Get current session

Method: `auth.getSession()`

- Returns cached session if available (fast)
- Automatically refreshes expired tokens
- Returns null if no active session

```typescript
const { data, error } = await client.auth.getSession()

if (data.session) {
console.log('User is logged in:', data.user.email)
} else {
console.log('No active session')
}

```

## Update user profile

Method: `auth.updateUser()`

Note: Password updates require password reset flow for security.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type                        | Required |
| --------- | --------------------------- | -------- |
| name      | string \| undefined         |          |
| image     | string \| null \| undefined |          |

</details>

```typescript
const { data, error } = await client.auth.updateUser({
  name: 'New Name'
})
```

## Send verification OTP code

Method: `auth.emailOtp.sendVerificationOtp()`

Sends an OTP (one-time password) code to the user's email for sign-in.
The user must then call `signIn.emailOtp()` with the received code.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type                                                   | Required |
| --------- | ------------------------------------------------------ | -------- |
| email     | string                                                 | ✓        |
| type      | "email-verification" \| "sign-in" \| "forget-password" | ✓        |

</details>

```typescript
const { error } = await client.auth.emailOtp.sendVerificationOtp({
  email: 'user@example.com',
  type: 'sign-in'
})

if (error) {
console.error('Failed to send OTP:', error.message)
}

```

## Sign in with OTP code

Method: `auth.signIn.emailOtp()`

Signs in a user using an OTP code received via email.
First call `emailOtp.sendVerificationOtp()` to send the code.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| email     | string | ✓        |
| otp       | string | ✓        |

</details>

```typescript
const { data, error } = await client.auth.signIn.emailOtp({
  email: 'user@example.com',
  otp: '123456'
})

if (error) {
console.error('OTP verification failed:', error.message)
} else {
console.log('Signed in:', data.user.email)
}

```

## Verify email with OTP

Method: `auth.emailOtp.verifyEmail()`

Verifies a user's email address using an OTP code sent during signup.
This is typically used after `signUp.email()` when email verification is required.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| email     | string | ✓        |
| otp       | string | ✓        |

</details>

```typescript
const { data, error } = await client.auth.emailOtp.verifyEmail({
  email: 'user@example.com',
  otp: '123456'
})

if (error) {
console.error('Email verification failed:', error.message)
} else {
console.log('Email verified successfully')
}

```

## Check verification OTP code

Method: `auth.emailOtp.checkVerificationOtp()`

Checks if an OTP code is valid without completing the verification flow.
Useful for password reset flows where you need to verify the code before allowing password change.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type                                                   | Required |
| --------- | ------------------------------------------------------ | -------- |
| email     | string                                                 | ✓        |
| type      | "email-verification" \| "sign-in" \| "forget-password" | ✓        |
| otp       | string                                                 | ✓        |

</details>

```typescript
const { data, error } = await client.auth.emailOtp.checkVerificationOtp({
  email: 'user@example.com',
  otp: '123456',
  type: 'forget-password'
})

if (error || !data.success) {
console.error('Invalid OTP code')
}

```

## Send verification email

Method: `auth.sendVerificationEmail()`

Sends a verification email to the user. Used for email verification after signup or email change.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter   | Type                | Required |
| ----------- | ------------------- | -------- |
| email       | string              | ✓        |
| callbackURL | string \| undefined |          |

</details>

```typescript
const { error } = await client.auth.sendVerificationEmail({
  email: 'user@example.com',
  callbackURL: 'https://yourapp.com/verify-email'
})

if (error) {
console.error('Failed to send verification email:', error.message)
}

```

## Verify email address

Method: `auth.verifyEmail()`

Verifies an email address using a token from a verification email link.
Used for email change verification.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type   | Required |
| --------- | ------ | -------- |
| query     | object | ✓        |

</details>

```typescript
const { data, error } = await client.auth.verifyEmail({
  query: {
    token: 'verification-token-from-email',
    callbackURL: 'https://yourapp.com/email-verified'
  }
})

if (error) {
console.error('Email verification failed:', error.message)
}

```

## Request password reset

Method: `auth.requestPasswordReset()`

Sends a password reset email to the user. The email contains a link to reset the password.

### Parameters

<details>

<summary>View parameters</summary>

| Parameter  | Type                | Required |
| ---------- | ------------------- | -------- |
| email      | string              | ✓        |
| redirectTo | string \| undefined |          |

</details>

```typescript
const { error } = await client.auth.requestPasswordReset({
  email: 'user@example.com',
  redirectTo: 'https://yourapp.com/reset-password'
})

if (error) {
console.error('Failed to send password reset email:', error.message)
}

```

## Fetch data from a table

Method: `from().select()`

- Authentication token is included automatically if user is signed in
- Returns typed data based on your database schema
- Row-level security policies determine what data is returned

**Select all rows**

```typescript
const { data, error } = await client.from('todos').select('*');
```

**Select specific columns**

```typescript
const { data, error } = await client.from('todos').select('id, title, completed');
```

**Select with filter**

```typescript
const { data, error } = await client.from('todos').select('*').eq('completed', false);
```

**Select with related tables**

```typescript
const { data, error } = await client.from('todos').select('*, owner:users(*)');
```

## Insert data into a table

Method: `from().insert()`

- Authentication token is included automatically
- Can insert single or multiple rows
- Returns inserted data by default

**Insert a single row**

```typescript
const { data, error } = await client
  .from('todos')
  .insert({ title: 'Buy groceries', completed: false })
  .select();
```

**Insert multiple rows**

```typescript
const { data, error } = await client
  .from('todos')
  .insert([
    { title: 'Task 1', completed: false },
    { title: 'Task 2', completed: false },
  ])
  .select();
```

## Update existing rows

Method: `from().update()`

- Requires filter to specify which rows to update
- Authentication token is included automatically

```typescript
const { data, error } = await client
  .from('todos')
  .update({ completed: true })
  .eq('id', 1)
  .select()
```

## Delete rows from a table

Method: `from().delete()`

- Requires filter to specify which rows to delete
- Authentication token is included automatically

### Parameters

<details>

<summary>View parameters</summary>

| Parameter | Type                                             | Required |
| --------- | ------------------------------------------------ | -------- |
| count     | "exact" \| "planned" \| "estimated" \| undefined |          |

</details>

```typescript
const { error } = await client
  .from('todos')
  .delete()
  .eq('id', 1)
```

## Call a stored procedure

Method: `.rpc()`

- Authentication token is included automatically
- Pass parameters as object
- Returns function result

```typescript
const { data, error } = await client.rpc('get_user_stats', {
  user_id: 123,
  start_date: '2024-01-01'
})

if (error) {
console.error('RPC error:', error.message)
} else {
console.log('Stats:', data)
}

```

## Column is equal to a value

Method: `.eq(column, value)`

Filters rows where the specified column equals the given value.
Can be chained with other filters to create complex queries.

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .eq('completed', true)
```

## Column is not equal to a value

Method: `.neq(column, value)`

Filters rows where the specified column does not equal the given value.
Useful for excluding specific values from results.

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .neq('status', 'archived')
```

## Column is greater than a value

Method: `.gt(column, value)`

Filters rows where the specified column is greater than the given value.
Works with numeric values, dates, and other comparable types.

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .gt('priority', 5)
```

## Column is less than a value

Method: `.lt(column, value)`

Filters rows where the specified column is less than the given value.
Works with numeric values, dates, and other comparable types.

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .lt('priority', 10)
```

## Order results by column

Method: `.order(column, options)`

Sorts query results by the specified column.
Use `{ ascending: true }` for ascending order or `{ ascending: false }` for descending order.

**Order ascending**

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .order('created_at', { ascending: true });
```

**Order descending**

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .order('created_at', { ascending: false });
```

## Limit number of results

Method: `.limit(count)`

Limits the number of rows returned by the query.
Useful for pagination and preventing large result sets.

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .limit(10)
```

## Column is greater than or equal to a value

Method: `.gte(column, value)`

Filters rows where the specified column is greater than or equal to the given value.
The comparison is inclusive (includes rows where column equals the value).

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .gte('priority', 5)
```

## Column is less than or equal to a value

Method: `.lte(column, value)`

Filters rows where the specified column is less than or equal to the given value.
The comparison is inclusive (includes rows where column equals the value).

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .lte('priority', 10)
```

## Column matches a pattern

Method: `.like(column, pattern)`

Filter rows where column matches pattern (case-sensitive).

Use % as wildcard: '%pattern%' matches any string containing 'pattern'

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .like('title', '%groceries%')
```

## Column matches a pattern (case-insensitive)

Method: `.ilike(column, pattern)`

Use % as wildcard: '%pattern%' matches any string containing 'pattern'

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .ilike('title', '%groceries%')
```

## Column is null or not null

Method: `.is(column, value)`

Filters rows based on whether a column is null or not null.
Use `.is(column, null)` to find rows where the column is null, or `.not(column, 'is', null)` to find rows where it's not null.

**Is null**

```typescript
const { data, error } = await client.from('todos').select('*').is('deleted_at', null);
```

**Is not null**

```typescript
const { data, error } = await client.from('todos').select('*').not('completed_at', 'is', null);
```

## Column value is in an array

Method: `.in(column, array)`

Filters rows where the column value matches any value in the provided array.
Useful for filtering by multiple possible values (for example, status in ['pending', 'active']).

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .in('status', ['pending', 'in-progress'])
```

## Array or JSONB column contains value

Method: `.contains(column, value)`

Filters rows where an array or JSONB column contains the specified value.
For arrays, checks if the value exists in the array. For JSONB, checks if the value is contained in the JSON object.

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .contains('tags', ['urgent'])
```

## Column value is between two values

Method: `.gte(column, start).lte(column, end)`

Use `.gte()` and `.lte()` to include both the start and end values.

```typescript
const { data, error } = await client
  .from('todos')
  .select('*')
  .gte('priority', 5)
  .lte('priority', 10)
```

## Auth method differences by adapter

Each adapter exposes a different API surface for authentication. Using the wrong method for your adapter is a common source of errors.

| Adapter                  | Sign in                                        | Sign up                                  |
| ------------------------ | ---------------------------------------------- | ---------------------------------------- |
| BetterAuthVanillaAdapter | `auth.signIn.email({ email, password })`       | `auth.signUp.email({ email, password })` |
| BetterAuthReactAdapter   | `auth.signIn.email({ email, password })`       | `auth.signUp.email({ email, password })` |
| SupabaseAuthAdapter      | `auth.signInWithPassword({ email, password })` | `auth.signUp({ email, password })`       |

For common authentication troubleshooting (missing environment variables, CSS conflicts, wrong imports), see [Auth troubleshooting](https://neon.com/docs/auth/troubleshooting).

--- [Document source](https://neon.com/docs/reference/metrics-logs.md) ---

> Summary: Complete field-level reference for all metrics and Postgres log fields that Neon exports to Datadog, Grafana Cloud, and OpenTelemetry, including metric names, label keys (project_id, endpoint_id, compute_id, job), and log metadata. Use this page to identify exact metric identifiers such as neon_connection_counts, neon_lfc_hits, and host_cpu_seconds_total when building dashboards or alerts. Metrics are not sent while a compute is suspended by Scale to Zero, which can cause gaps; log export also counts toward your plan's public network transfer allowance.

# Metrics and logs reference

Complete reference for all metrics and log fields exported by Neon

Last updated: 2026-08-07

This page provides a comprehensive reference for all metrics and log fields that Neon exports to observability platforms through integrations like [Datadog](https://neon.com/docs/guides/datadog), [Grafana Cloud](https://neon.com/docs/guides/grafana-cloud), and [OpenTelemetry](https://neon.com/docs/guides/opentelemetry).

## Available metrics

Neon makes the following metrics available for export to third parties through our observability integrations.

All metrics include the following labels:

- `project_id`
- `endpoint_id`
- `compute_id`
- `job`

Here's an example of the metric `db_total_size` with all labels:

```json
neon_db_total_size{project_id="square-daffodil-12345678", endpoint_id="ep-aged-art-260862", compute_id="compute-shrill-blaze-b4hry7fg", job="sql-metrics"} 10485760
```

**Note:** In Datadog, metric labels are referred to as `tags.` See [Getting Started with Tags](https://docs.datadoghq.com/getting_started/tagging/) in the Datadog Docs.

| Name                                                         | Job                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| neon\_connection\_counts                                     | sql-metrics          | Total number of database connections. The `state` label indicates whether the connection is `active` (executing queries), `idle` (awaiting queries), or in a variety of other states derived from the [pg\_stat\_activity](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-ACTIVITY-VIEW) Postgres view.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| neon\_db\_total\_size                                        | sql-metrics          | Total size of all databases in your project, measured in bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| neon\_lfc\_approximate\_working\_set\_size\_windows          | sql-metrics          | Approximate [working set size](https://neon.com/docs/manage/endpoints#sizing-your-compute-based-on-the-working-set) in pages of 8192 bytes. The metric is tracked over time windows (5m, 15m, 1h) to gauge access patterns. Duration values: `duration="5m"`, `duration="15m"`, `duration="1h"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| neon\_lfc\_cache\_size\_limit                                | sql-metrics          | The limit on the size of the compute cache, measured in bytes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| neon\_lfc\_hits                                              | sql-metrics          | The number of times requested data was found in the compute cache (cache hit). Higher cache hit rates indicate efficient memory use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| neon\_lfc\_misses                                            | sql-metrics          | The number of times requested data was not found in the compute cache (cache miss), forcing a read from slower storage. High miss rates may indicate insufficient compute size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| neon\_lfc\_used                                              | sql-metrics          | The amount of space currently used in the compute cache, measured in 1MB chunks. It reflects how much of the cache limit is being utilized.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| neon\_lfc\_writes                                            | sql-metrics          | The number of write operations to the compute cache.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| neon\_max\_cluster\_size                                     | sql-metrics          | The `neon.max_cluster_size` setting in MB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| neon\_pg\_stats\_userdb                                      | sql-metrics          | Aggregated metrics from the [pg\_stat\_database](https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-PG-STAT-DATABASE-VIEW) Postgres view.<br/><br/>We collect stats from the oldest non-system databases based on their creation time, but not for all databases. Only the first X databases (sorted by creation time) are included.<br/><br/>**datname**: The name of the database<br/>**kind**: The type of value being reported. One of the following:<br/>- **db\_size**: The size of the database on disk, in bytes (`pg_database_size(datname)`)<br/>- **deadlocks**: The number of deadlocks detected<br/>- **inserted**: The number of rows inserted (`tup_inserted`)<br/>- **updated**: The number of rows updated (`tup_updated`)<br/>- **deleted**: The number of rows deleted (`tup_deleted`) |
| neon\_pgbouncer\_config\_max\_client\_connections            | sql-metrics          | Configured maximum number of client connections in pgBouncer.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| neon\_pgbouncer\_pools\_client\_active\_cancel\_connections  | sql-metrics          | Number of active cancel requests from clients in pgBouncer pools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| neon\_pgbouncer\_pools\_client\_active\_connections          | sql-metrics          | Number of active client connections in pgBouncer pools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| neon\_pgbouncer\_pools\_client\_maxwait\_seconds             | sql-metrics          | Maximum client wait time in seconds for pgBouncer pools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| neon\_pgbouncer\_pools\_client\_waiting\_cancel\_connections | sql-metrics          | Number of cancel requests waiting in pgBouncer pools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| neon\_pgbouncer\_pools\_client\_waiting\_connections         | sql-metrics          | Number of client connections waiting in pgBouncer pools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| neon\_pgbouncer\_pools\_server\_active\_connections          | sql-metrics          | Number of active server connections in pgBouncer pools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| neon\_pgbouncer\_pools\_server\_idle\_connections            | sql-metrics          | Number of idle server connections in pgBouncer pools.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| neon\_replication\_delay\_bytes                              | sql-metrics          | The number of bytes between the last received LSN (`Log Sequence Number`) and the last replayed one. Large values indicate replication lag.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| neon\_replication\_delay\_seconds                            | sql-metrics          | Time since the last `LSN` was replayed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| host\_cpu\_seconds\_total                                    | compute-host-metrics | The number of CPU seconds accumulated in different operating modes (user, system, idle, etc.).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| host\_load1                                                  | compute-host-metrics | System load averaged over the last 1 minute. Example: for 0.25 CU, `host_load1` of `0.25` means full utilization, >0.25 indicates waiting processes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| host\_load5                                                  | compute-host-metrics | System load averaged over the last 5 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| host\_load15                                                 | compute-host-metrics | System load averaged over the last 15 minutes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| host\_memory\_active\_bytes                                  | compute-host-metrics | The number of bytes of active main memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| host\_memory\_available\_bytes                               | compute-host-metrics | The number of bytes of main memory available.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| host\_memory\_buffers\_bytes                                 | compute-host-metrics | The number of bytes of main memory used by buffers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| host\_memory\_cached\_bytes                                  | compute-host-metrics | The number of bytes of main memory used by cached blocks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| host\_memory\_free\_bytes                                    | compute-host-metrics | The number of bytes of main memory not used.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| host\_memory\_shared\_bytes                                  | compute-host-metrics | The number of bytes of main memory shared between processes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| host\_memory\_swap\_free\_bytes                              | compute-host-metrics | The number of free bytes of swap space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| host\_memory\_swap\_total\_bytes                             | compute-host-metrics | The total number of bytes of swap space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| host\_memory\_swap\_used\_bytes                              | compute-host-metrics | The number of used bytes of swap space.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| host\_memory\_swapped\_in\_bytes\_total                      | compute-host-metrics | The number of bytes that have been swapped into main memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| host\_memory\_swapped\_out\_bytes\_total                     | compute-host-metrics | The number of bytes that have been swapped out from main memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| host\_memory\_total\_bytes                                   | compute-host-metrics | The total number of bytes of main memory.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| host\_memory\_used\_bytes                                    | compute-host-metrics | The number of bytes of main memory used by programs or caches.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

## Postgres logs

Neon can export Postgres logs to observability platforms, providing visibility into database activity, errors, and performance. When log export is enabled, Postgres sends its standard server log output to the integration, so what you receive is controlled by the Postgres [logging parameters](https://www.postgresql.org/docs/current/runtime-config-logging.html).

### What's logged by default

Neon computes use these logging settings:

| Parameter                     | Value     | What you'll see in exported logs                                                                                                                             |
| ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `log_min_messages`            | `warning` | Warnings, errors, and more severe messages. `NOTICE`, `INFO`, and `DEBUG` aren't sent.                                                                       |
| `log_connections`             | `on`      | `connection received`, `connection authenticated`, and `connection authorized` lines for each new connection. This is often the largest share of log volume. |
| `log_disconnections`          | `on`      | A line for each closed connection, including session duration.                                                                                               |
| `log_checkpoints`             | `on`      | A line for each checkpoint, with timing and the number of buffers written.                                                                                   |
| `log_autovacuum_min_duration` | `1000`    | Autovacuum and autoanalyze runs that take longer than 1 second.                                                                                              |
| `log_temp_files`              | `1048576` | Temporary files of 1 GB or more, such as large sorts or hashes that spill to disk.                                                                           |
| `log_error_verbosity`         | `terse`   | Errors and warnings without `DETAIL`, `HINT`, or `CONTEXT` lines.                                                                                            |
| `log_min_error_statement`     | `panic`   | The SQL statement that caused an error isn't included, to keep query data out of logs.                                                                       |

Statement logging is off by default. Query text isn't logged (`log_statement` is `none`), slow queries aren't logged (`log_min_duration_statement` is `-1`), and lock waits aren't logged (`log_lock_waits` is `off`). To find slow or frequent queries without changing log settings, use [Monitor query performance](https://neon.com/docs/introduction/monitor-query-performance).

For the full list of Neon's Postgres settings, see [Postgres parameter settings](https://neon.com/docs/reference/compatibility#postgres-parameter-settings).

### Log slow queries

You can turn on slow-query logging for a compute by setting `log_min_duration_statement` in the compute's `pg_settings` with the [Update compute endpoint](https://neon.com/docs/reference/api/endpoints/update-project-endpoint) API. Postgres then logs every statement that runs longer than the value you set, in milliseconds. The minimum value is `500`. The setting applies without a compute restart.

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/<project_id>/endpoints/<endpoint_id> \
     --header 'accept: application/json' \
     --header "authorization: Bearer $NEON_API_KEY" \
     --header 'content-type: application/json' \
     --data '
{
  "endpoint": {
    "settings": {
      "pg_settings": {
        "log_min_duration_statement": "1000"
      }
    }
  }
}
'
```

**Warning:** Slow-query log lines include the full statement text, including any literal values in the query. If your queries contain sensitive data, consider what you send to your observability platform before you turn this on.

The other statement logging parameters, such as `log_statement` and `log_lock_waits`, can't be changed. You can't set any of them with `SET` or `ALTER DATABASE`, because they require superuser privileges.

### Log fields and metadata

Each log message starts with a prefix that Neon sets through `log_line_prefix`. It includes:

- Timestamp, in GMT
- `sqlstate`: the [SQLSTATE error code](https://www.postgresql.org/docs/current/errcodes-appendix.html), or `00000` for messages that aren't errors
- `user`: the Postgres role
- `dboid`: the database OID. To map it to a name, run `SELECT oid, datname FROM pg_database;`.
- `backend`: the process type, such as `client backend`, `autovacuum worker`, or `checkpointer`
- `app`: the client's `application_name`
- Process ID

Each exported log record also includes these attributes:

- Log level (severity). See [Log levels](https://neon.com/docs/reference/metrics-logs#log-levels).
- `project_id`
- `endpoint_id`
- `compute_binding_id`: identifies the individual compute instance behind the endpoint
- `compute_role`: `read_write` or `read_only`
- `endpoint_type`: `read_write` or `read_only`
- `region_id`
- `host`, set to `neon-collector-<project_id>`
- `service.name`: OpenTelemetry integration only, if you set it in the integration's resource attributes

If you connect through a [pooled connection string](https://neon.com/docs/connect/connection-pooling), connection lines show `application_name=pgbouncer`, because PgBouncer opens the connection to Postgres for you. Your client's `application_name` still appears in the `app` field on statement and error lines.

### Log levels

Postgres maps its message levels to syslog severities that don't line up with the level names, so the severity on an exported record often differs from the level in the message text:

| Postgres level (in the message) | Exported severity |
| ------------------------------- | ----------------- |
| `LOG`, `INFO`                   | `info`            |
| `WARNING`                       | `notice`          |
| `ERROR`                         | `warning`         |
| `FATAL`                         | `err`             |
| `PANIC`                         | `crit`            |

To find errors, filter on the message text (for example, `ERROR:`) or on the `sqlstate` field instead of the record severity. `NOTICE` messages aren't exported, because `log_min_messages` is `warning`.

### Internal log lines

Neon filters out some internal storage-layer log lines before export, but you'll still see activity from Neon's own processes:

- **Connection lines.** Neon checks each compute's health by connecting to Postgres about once a minute, and its metrics collectors and other management tasks connect too. On an idle compute, these can make up close to half of all exported lines. The `connection authenticated`, `connection authorized`, and `disconnection` lines have `user=[cloud_admin]`. The `connection received` lines are logged before authentication, so they show `user=[[unknown]]` and `host=127.0.0.1`. To hide this activity, exclude lines with `user=[cloud_admin]` and lines containing `connection received: host=127.0.0.1`.
- **Storage and replication messages.** Lines tagged `[COMMUNICATOR]` or `[WP]` come from Neon's storage layer and are informational.
- **Restart messages.** When a compute restarts or reconfigures, you'll see `FATAL: terminating connection due to administrator command` for Neon's background processes, and `LOG` lines about reloading configuration. These are expected.
- **Internal standby.** A compute can have an internal standby instance that also sends logs. Its records have a `compute_binding_id` ending in `-internal` and a `compute_role` of `read_only`, under the same `endpoint_id`.

### Performance considerations

Enabling log export may result in:

- An increase in compute resource usage for log processing
- Additional public network transfer for log transmission, which counts toward your plan's [network transfer allowance](https://neon.com/docs/introduction/network-transfer)
- Associated costs based on log volume in your observability platform

**Note:** Neon computes only send logs and metrics when they are active. If the [Scale to Zero](https://neon.com/docs/introduction/scale-to-zero) feature is enabled and a compute is suspended due to inactivity, no logs or metrics will be sent during the suspension. This may result in gaps in your data.

Additionally, if you are setting up an integration for a project with an inactive compute, you'll need to activate the compute before it can send data. To activate it, simply run a query from the [Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor) or any connected client.

### Technical details

Neon processes logs directly on each compute instance using [rsyslogd](https://www.rsyslog.com/doc/index.html), an industry-standard open source logging utility. This compute-level processing means that log collection contributes to your compute's resource usage.

To keep log export from slowing down your database, the compute buffers log lines while forwarding them. If your observability platform is unreachable for long enough that the buffer fills, some log lines are dropped rather than delaying Postgres.

## Integration guides

For platform-specific setup instructions and examples, see:

- [Datadog integration](https://neon.com/docs/guides/datadog) - Setup instructions, dashboard configuration, and Datadog-specific features
- [Grafana Cloud integration](https://neon.com/docs/guides/grafana-cloud) - Native OTLP integration with automatic routing to Mimir, Loki, and Tempo
- [OpenTelemetry integration](https://neon.com/docs/guides/opentelemetry) - OTLP configuration for any compatible observability platform

--- [Document source](https://neon.com/docs/reference/migrate-api-client-to-sdk.md) ---

> Summary: Step-by-step migration from @neondatabase/api-client to @neon/sdk: package install, createNeonClient, namespace method mapping, error handling, and raw layer 1.0 breaking changes. Use this page when updating scripts, CI jobs, or apps that call the Neon Platform API with TypeScript.

# Migrate from @neondatabase/api-client to @neon/sdk

Move Platform API automation from the legacy Axios client to the official fetch-based SDK

Last updated: 2026-08-27

**Note: @neondatabase/api-client still works**

The legacy [`@neondatabase/api-client`](https://www.npmjs.com/package/@neondatabase/api-client) package continues to work. [`@neon/sdk`](https://www.npmjs.com/package/@neon/sdk) is the recommended replacement for new projects and for teams that want fetch-based, zero-dependency Platform API access with ergonomic workflows.

This guide maps common `@neondatabase/api-client` patterns to [`@neon/sdk`](https://neon.com/docs/reference/typescript-sdk). For full method reference, see the [Neon Management SDK](https://neon.com/docs/reference/typescript-sdk) documentation.

## What changes

|               | `@neondatabase/api-client`                      | `@neon/sdk`                                                              |
| ------------- | ----------------------------------------------- | ------------------------------------------------------------------------ |
| HTTP client   | Axios                                           | `fetch` (zero runtime dependencies)                                      |
| Factory       | `createApiClient({ apiKey })`                   | `createNeonClient({ apiKey })`                                           |
| Method layout | Flat (`listProjects`, `createProjectBranch`, …) | Namespaced (`neon.projects.list()`, `neon.branches.create()`, …)         |
| Success path  | `response.data` on Axios responses              | `{ data, error }` by default, or bare resource with `throwOnError: true` |
| Errors        | `AxiosError` + `error.response`                 | Typed `NeonError` hierarchy (`kind`: `api`, `not_found`, `auth`, …)      |
| Node.js       | Broader support                                 | **≥ 20.19** (or any runtime with global `fetch`)                         |
| Low-level API | Generated methods on the client                 | `raw.*` functions + `neon.client`                                        |

## Install and swap the package

```bash
npm uninstall @neondatabase/api-client
npm install @neon/sdk
```

Update imports:

```typescript
// Before
import { createApiClient } from '@neondatabase/api-client';

// After
import { createNeonClient } from '@neon/sdk';
```

## Client setup

```typescript
// Before
const apiClient = createApiClient({
  apiKey: process.env.NEON_API_KEY!,
});

// After — check { data, error } on each call
const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
});

// After — throw on error (closer to try/catch style)
const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
  throwOnError: true,
});
```

`createNeonClient` also supports `orgId`, `waitForReadiness`, `retries`, `baseUrl`, and a custom `fetch` implementation. See [Neon Management SDK](https://neon.com/docs/reference/typescript-sdk#client-configuration).

## Method mapping

Common Platform API calls and their `@neon/sdk` equivalents:

| `@neondatabase/api-client`             | `@neon/sdk`                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------- |
| `getCurrentUserOrganizations()`        | `neon.user.organizations()`                                                     |
| `getCurrentUserInfo()`                 | `neon.user.me()`                                                                |
| `listProjects({ org_id })`             | `neon.projects.list({ org_id }).page()` or `.all()`                             |
| `createProject({ project })`           | `neon.projects.create({ name, region_id, … })`                                  |
| `getProject(projectId)`                | `neon.projects.get(projectId)`                                                  |
| `deleteProject(projectId)`             | `neon.projects.delete(projectId)`                                               |
| `listProjectBranches({ projectId })`   | `neon.branches.list(projectId).page()` or `.all()`                              |
| `createProjectBranch(projectId, body)` | `neon.branches.create(projectId, input)` or `neon.branches.createAndConnect(…)` |
| `getConnectionUri(projectId, query)`   | `neon.postgres.connectionString({ projectId, … })`                              |
| `listProjectBranchDatabases(…)`        | `neon.postgres.databases.list(…)`                                               |
| `createProjectBranchDatabase(…)`       | `neon.postgres.databases.create(…)`                                             |
| `listProjectBranchRoles(…)`            | `neon.postgres.roles.list(…)`                                                   |
| `createProjectBranchRole(…)`           | `neon.postgres.roles.create(…)`                                                 |
| `listProjectEndpoints(projectId)`      | `neon.postgres.endpoints.list(projectId)`                                       |
| `listApiKeys()`                        | `neon.apiKeys.list()`                                                           |
| `getActiveRegions()`                   | `neon.regions.list()`                                                           |

Endpoints that are not wrapped in an ergonomic namespace remain available through [`raw`](https://neon.com/docs/reference/typescript-sdk#raw-layer).

## Error handling

**Before** — Axios throws; inspect `error.response`:

```typescript
try {
  const response = await apiClient.getProject(projectId);
  console.log(response.data.project);
} catch (error) {
  // AxiosError — error.response?.status, error.response?.data
}
```

**After** — default `{ data, error }` envelope:

```typescript
const { data: project, error } = await neon.projects.get(projectId);
if (error) {
  if (error.kind === 'not_found') {
    // handle 404
  }
  throw error;
}
console.log(project);
```

**After** — `throwOnError: true` on the client or per call:

```typescript
const neon = createNeonClient({ apiKey, throwOnError: true });
const project = await neon.projects.get(projectId); // throws NeonError on failure
```

## Side-by-side examples

### List projects

```typescript
// Before
const orgs = await apiClient.getCurrentUserOrganizations();
const orgId = orgs.data.organizations[0].id;
const response = await apiClient.listProjects({ org_id: orgId });
console.log(response.data.projects);

// After
const { data: orgs, error: orgsError } = await neon.user.organizations();
if (orgsError) throw orgsError;

const { data: page, error } = await neon.projects.list({ org_id: orgs[0].id }).page();
if (error) throw error;
console.log(page.items);
```

### Create a project with a connection string

```typescript
// Before
const response = await apiClient.createProject({
  project: { name: 'my-app', region_id: 'aws-us-east-1', pg_version: 17 },
});
const uri = response.data.connection_uris[0].connection_uri;

// After — waits for provisioning; data is { project, connectionString }
const { data, error } = await neon.projects.createAndConnect({
  name: 'my-app',
  region_id: 'aws-us-east-1',
  pg_version: 17,
});
if (error) throw error;
const { project, connectionString } = data;
```

### Create a branch with compute

```typescript
// Before
import { EndpointType } from '@neondatabase/api-client';

await apiClient.createProjectBranch(projectId, {
  branch: { name: 'dev-1', parent_id: parentBranchId },
  endpoints: [{ type: EndpointType.ReadWrite }],
});

// After — read-write compute is attached by default
const { data, error } = await neon.branches.create(projectId, {
  name: 'dev-1',
  parent_id: parentBranchId,
});
if (error) throw error;
const branch = data;
```

### Create a database

```typescript
// Before
await apiClient.createProjectBranchDatabase(projectId, branchId, {
  database: { name: 'mydb', owner_name: 'neondb_owner' },
});

// After
const { error } = await neon.postgres.databases.create(projectId, branchId, {
  name: 'mydb',
  owner_name: 'neondb_owner',
});
if (error) throw error;
```

## Raw layer changes in 1.0

If you adopted `@neon/sdk` **0.x** and used `raw.*` directly, **1.0 changes the raw contract**:

| 0.x                                            | 1.0                                               |
| ---------------------------------------------- | ------------------------------------------------- |
| hey-api `{ data, request, response }` envelope | `{ data, error }` `NeonResult`                    |
| `responseStyle: "data"`                        | **Removed**                                       |
| `throwOnError: true` needed workarounds        | Returns the bare resource; types narrow correctly |

```typescript
// Before (0.x)
const project = await raw.getProject({
  client: neon.client,
  path: { project_id: projectId },
  throwOnError: true,
  responseStyle: 'data',
});

// After (1.0)
const project = await raw.getProject({
  client: neon.client,
  path: { project_id: projectId },
  throwOnError: true,
});
```

Drop any `unwrapRaw` helpers or `responseStyle` usage.

## Types

Import request/response types from `@neon/sdk` instead of `@neondatabase/api-client`:

```typescript
import type { Project, Branch } from '@neon/sdk';
```

Some generated type names changed (for example, `DataAPI*` → `DataApi*`). Endpoint types are string unions (`"read_write"` / `"read_only"`) rather than enums.

## What you gain

- **Workflow helpers** such as `projects.createAndConnect` and `branches.createAndConnect` that poll operations and return `{ project, connectionString }` or `{ branch, endpoint, connectionString }`. `create` returns the resource; `branches.create` attaches a read-write endpoint unless you pass `noCompute: true`.
- **Readiness polling** via `waitForReadiness` and `neon.operations.waitFor`
- **Automatic retries** on safe statuses (`423`, `429`, `503`)
- **Ergonomic beta APIs** for storage, functions, credentials, AI gateway, snapshots, and branch-scoped Managed Better Auth (`neon.auth`, `neon.storage`, …)
- **Tree-shakeable raw imports** from `@neon/sdk/raw`

## Next steps

- [Neon Management SDK](https://neon.com/docs/reference/typescript-sdk) — install, configuration, examples, and namespace reference
- [Neon API Reference](https://neon.com/docs/reference/api) — REST endpoint details
- [`@neon/sdk` on GitHub](https://github.com/neondatabase/neon-pkgs/tree/main/packages/sdk) — full method tables and regeneration notes

--- [Document source](https://neon.com/docs/reference/neon-ts.md) ---

> Summary: neon.ts declares which Neon services exist on a project and how each branch is configured. Use it for branch policy alone, or add services like Functions, Object Storage, and AI Gateway. Works with neon deploy, neon dev, and neon checkout.

# neon.ts

Configuration as code for your Neon project.

Last updated: 2026-10-15

`neon.ts` is a TypeScript config file you commit to your repository. It declares which Neon services exist on your project and how each branch is configured.

Specifically:

- **Declares services**: which Neon services (`auth`, `dataApi`, `aiGateway`, `functions`, `buckets`, and `preview.realtime`) exist on the project and are available on every branch.
- **Configures branches**: optional per-branch tuning (TTLs, compute sizing, protected status) via a `branch` closure.

Services and branch policy are independent. Use one, the other, or both.

The fastest way to create a `neon.ts` is [`neon config init`](https://neon.com/docs/cli/config#init), which scaffolds a starter policy and installs the config packages. To set it up by hand instead, install the package:

```bash
npm install @neon/config
```

`@neon/config` provides `defineConfig` and is all you need to author a `neon.ts`; you apply it with `neon deploy`. Two optional packages extend it:

- [`@neon/env`](https://neon.com/docs/reference/neon-ts#type-safe-environment-variables): type-safe access to the injected variables.
- [`@neon/config-runtime`](https://neon.com/docs/reference/config-runtime): run the `inspect` / `plan` / `apply` logic yourself instead of through the CLI.

The package [source is on GitHub](https://github.com/neondatabase/neon-pkgs/tree/main/packages/config).

`neon.ts` is declarative: it describes the policy but doesn't apply it. `neon deploy` (an alias for `neon config apply`) applies it to the linked branch. It provisions or updates the declared services, applies your branch tuning, and pulls the branch's variables into your local `.env`. Run it whenever you change `neon.ts`.

Link your working directory to a Neon project before using `neon.ts` commands:

```bash
neon link
```

## Config structure

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  // Services: what exists on every branch
  auth: true,

  // Branch policy: per-branch tuning
  branch: (branch) => {
    if (branch.isDefault) {
      // Default branch: no overrides, uses project defaults
      return {};
    }
    if (!branch.exists) {
      // New non-default branches: auto-expire
      return { ttl: "7d" };
    }
    // Existing branch: no changes
    return {};
  },
});
```

`defineConfig` takes two optional parts:

- **Static fields** (`auth`, `dataApi`, `aiGateway`, `functions`, `buckets`, `preview.realtime`): declare which services exist. Same set on every branch.
- **`branch` closure**: receives a read-only `BranchTarget` and returns per-branch tuning. It can adjust settings, but can't add or remove services.

## Services

Declare services as top-level keys in `defineConfig`; declare only the ones you use. Every branch always has Postgres, so `DATABASE_URL` is injected without being declared here. After `neon deploy`, `neon env pull` writes any injected URLs and credentials to your local `.env` file automatically.

To add any of these to an existing `neon.ts` without editing the file by hand, use [`neon config add`](https://neon.com/docs/cli/config#add); for a function it also creates the handler file.

| Field              | Values / type                                                                             | Default | What it enables                                                                                                                                                                                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `auth`             | `true`, `false`, `{ enabled: bool }`                                                      | `false` | [Managed Better Auth](https://neon.com/docs/auth/overview). Injects `NEON_AUTH_BASE_URL`, `NEON_AUTH_JWKS_URL`                                                                                                                                                                 |
| `dataApi`          | `true`, `false`, [`DataApiConfig`](https://neon.com/docs/reference/neon-ts#dataapi)       | `false` | [Neon Data API](https://neon.com/docs/data-api/overview). Injects `NEON_DATA_API_URL`                                                                                                                                                                                          |
| `aiGateway`        | `true`, `false`, `{ enabled: bool }`                                                      | `false` | [Neon AI Gateway](https://neon.com/docs/ai-gateway/overview). Injects `NEON_AI_GATEWAY_TOKEN`, `NEON_AI_GATEWAY_BASE_URL`                                                                                                                                                      |
| `functions`        | Record of slug → [function def](https://neon.com/docs/reference/neon-ts#functions)        | (none)  | [Neon Functions](https://neon.com/docs/compute/functions/overview). Long-running Node.js compute. The branch's service variables (`DATABASE_URL` and more) are injected at runtime; see [Environment variables](https://neon.com/docs/compute/functions/environment-variables) |
| `buckets`          | Record of name → [bucket def](https://neon.com/docs/reference/neon-ts#buckets)            | (none)  | [Neon Object Storage](https://neon.com/docs/storage/overview). S3-compatible object storage, branched with your database. Injects `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, `AWS_REGION`                                                            |
| `triggers`         | Record of name → [trigger def](https://neon.com/docs/reference/neon-ts#triggers)          | (none)  | [Function Triggers](https://neon.com/docs/compute/functions/triggers/overview). Invoke a function on a schedule or when an object is created in a bucket.                                                                                                                      |
| `preview.realtime` | `true`, `false`, [`{ allowedOrigins }`](https://neon.com/docs/reference/neon-ts#realtime) | (none)  | [Neon Realtime](https://neon.com/docs/realtime/overview). Live SQL query subscriptions. Injects `NEON_REALTIME_URL`, `NEON_REALTIME_SECRET`                                                                                                                                    |

**Note: aiGateway, functions, and buckets moved out of preview**

The `preview` block holds features that are still in preview, currently [`realtime`](https://neon.com/docs/reference/neon-ts#realtime). `aiGateway`, `functions`, and `buckets` used to live there too; `@neon/config` 1.6.0 and later accept them as the top-level keys shown here. Declaring those three under `preview` still works but logs a deprecation warning on `neon deploy`, so keep them there only if you're on a version earlier than 1.6.0. See [Troubleshooting](https://neon.com/docs/reference/neon-ts#troubleshooting) if a top-level config fails to apply on an older install.

### dataApi

`dataApi: true` uses Managed Better Auth as the JWT verifier (the default). When using this form, `auth: true` must also be set. Omitting it raises a TypeScript error at the `dataApi` field that includes the fix:

```text
Type 'true' is not assignable to type '"`dataApi` with Neon Auth (the default
`authProvider: 'neon'`) requires Neon Auth, so add `auth: true`. To enable the
Data API WITHOUT Neon Auth, verify a third-party IdP instead: `dataApi: {
authProvider: 'external', jwksUrl: 'https://your-idp/.well-known/jwks.json' }`"'
```

To use the Data API with an external identity provider instead, pass the object form:

```ts
dataApi: {
  authProvider: "external",
  jwksUrl: "https://your-idp/.well-known/jwks.json",
}
```

### functions

Each key is the function's slug, the permanent identifier used in CLI commands and the invocation URL:

**Top level (@neon/config 1.6.0+)**

```ts
functions: {
  "<slug>": {
    name: string,       // display name shown in neon functions list and the console
    source: string,     // path to entry file, relative to neon.ts
    env?: Record<string, string>,
    bundler?: "esbuild" | "none" | ((fn) => Promise<FunctionBundle>),  // default "esbuild"
    dev?: {
      port?: number,    // local port for neon dev; fails if taken; auto-assigned if omitted
    },
    customDomains?: string[],  // hostnames to serve this function; default branch only
  },
},
```

**Under preview (deprecated alias)**

```ts
preview: {
  functions: {
    "<slug>": {
      name: string,
      source: string,
      env?: Record<string, string>,
      bundler?: "esbuild" | "none" | ((fn) => Promise<FunctionBundle>),
      dev?: { port?: number },
      customDomains?: string[],  // hostnames to serve this function; default branch only
    },
  },
},
```

Slugs must match `^[a-z0-9]{1,20}$` and are immutable after first deployment. Because slugs can't use separators, use `name` for a human-readable label. For example, `slug: "myrestapi"` with `name: "My REST API"`. See [Deploy and manage functions](https://neon.com/docs/compute/functions/deploy#slugs).

`env` values are resolved at deploy time when `neon deploy` runs. Reading `process.env.X` here captures the value in your shell at deploy time, not at function runtime. Every value must be a defined string, so set each variable before you deploy and mark the read with `!`:

```ts
env: {
  API_KEY: process.env.API_KEY!,
}
```

Skip empty-string fallbacks like `?? ""`, because deploying an empty value deletes that variable from the live function. If you don't want to set a variable, remove its key from `neon.ts`. For an optional variable, declare it only when it has a value:

```ts
env: {
  ...(process.env.SENTRY_RELEASE ? { SENTRY_RELEASE: process.env.SENTRY_RELEASE } : {}),
}
```

Use `neon deploy --env .env.production` to load a `.env` file before evaluation. Commands that evaluate `neon.ts`, such as `neon deploy` and [`neon dev`](https://neon.com/docs/cli/dev#environment-variables), check that every `env` value is set and report any missing variable by name. For typed access to these variables inside your function at runtime, see [Environment variables](https://neon.com/docs/compute/functions/environment-variables).

`bundler` controls how `source` becomes the deployed archive. The default, `"esbuild"`, bundles your source (TypeScript is compiled here). Set `"none"` to ship a prebuilt directory or file as-is, in which case the entry must be named `index.mjs` or `index.js`. This is the config form of the CLI's [`--no-bundle`](https://neon.com/docs/compute/functions/deploy#deploy-with-neon-functions-deploy) flag. To use your own build system, set `bundler` to a function that receives the resolved function config and returns the files to deploy (a `FunctionBundle`, a record of path to file contents), so a framework that already emits its own build output can deploy it unchanged.

`dev` settings apply only to `neon dev` and never affect deploy.

Triggers are declared separately in [`triggers`](https://neon.com/docs/reference/neon-ts#triggers); each entry's `function` field references a slug declared here.

`customDomains` lists hostnames you own that serve the function, such as `["api.example.com"]`. `neon deploy` registers them, and each hostname can point at only one function on one branch. Static `customDomains` apply on the default branch only. For DNS setup, per-branch domains, status checks, and TLS verification, see [Custom domains for Neon Functions](https://neon.com/docs/compute/functions/custom-domains).

### triggers

Each key is the trigger's name, unique across the branch. Each entry's `function` field references a function slug declared under `functions`.

```ts
triggers: {
  "<name>": {
    type: "schedule" | "storage_object_created",
    function: string,       // slug of the function to invoke
    cron?: string,          // schedule only: five-field UTC expression
    bucket?: string,        // storage only: bucket name declared under buckets
    prefix?: string,        // storage only: object-key prefix filter
    functionPath?: string,  // request path sent to the function; default "/"
    enabled?: boolean,      // default true
  },
},
```

| Field          | Required                 | Description                                                                                     |
| -------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
| `type`         | Yes                      | `"schedule"` or `"storage_object_created"`                                                      |
| `function`     | Yes                      | Slug of the function to invoke. The API and CLI call this `function_slug`                       |
| `cron`         | `schedule`               | Five-field UTC cron expression                                                                  |
| `bucket`       | `storage_object_created` | Bucket to watch. The API and CLI call this `storage_object_created.bucket_name`                 |
| `prefix`       | No                       | Only objects whose key starts with this prefix fire the trigger (`storage_object_created` only) |
| `functionPath` | No                       | Request path sent to the function. Default `/`                                                  |
| `enabled`      | No                       | Default `true`                                                                                  |

Triggers that exist remotely but are omitted from `neon.ts` are left alone. Inherited triggers on a child branch start disabled; deploying a `neon.ts` that declares the same trigger enables the inherited copy. See [Function Triggers overview](https://neon.com/docs/compute/functions/triggers/overview) for branching behavior, delivery payloads, and the Console, CLI, and API alternatives.

### buckets

**Top level (@neon/config 1.6.0+)**

```ts
buckets: {
  "<name>": {
    access?: "private" | "public_read",  // default: "private"
  },
},
```

**Under preview (deprecated alias)**

```ts
preview: {
  buckets: {
    "<name>": {
      access?: "private" | "public_read",
    },
  },
},
```

Bucket names follow S3 naming rules. `public_read` makes objects accessible without credentials at the branch's storage endpoint.

### preview.realtime

Enables [Neon Realtime](https://neon.com/docs/realtime/overview) on the branch, so clients can subscribe to live SQL queries. Requires `@neon/config` 1.9.0 or later. Pass `true`, or an object to set the browser origins allowed to connect:

```ts
preview: {
  realtime: {
    allowedOrigins?: string[],  // "*", or http(s) origins with no path; max 16
  },
},
```

Each origin must be `*` or an `http` or `https` origin with no path, query, or fragment, such as `https://app.example.com`. `*` allows every origin and can't be combined with others. `defineConfig` rejects invalid values before anything is sent. With `true`, any browser origin can connect unless the branch already has an origin list, which is kept. Allowed origins only restrict browsers, not server clients.

| Value                | What `neon deploy` does                                           |
| -------------------- | ----------------------------------------------------------------- |
| `true`               | Enables Realtime without changing allowed origins                 |
| `{ allowedOrigins }` | Enables Realtime and sets the browser origins allowed to connect  |
| `false`              | Disables Realtime                                                 |
| omitted              | Leaves Realtime unmanaged: whatever the branch has stays as it is |

Realtime is a static field, so the `branch` closure can't set it per branch.

On `neon deploy`, a branch without Realtime gets it enabled. Changing `allowedOrigins` on a branch that already has Realtime, or setting `realtime: false` to disable it, is reported as a conflict unless you pass `--update-existing`. Omitting the key leaves the branch's Realtime as it is. To add it without editing the file by hand, use [`neon config add realtime`](https://neon.com/docs/cli/config#add-realtime); to stream a query from the terminal, use [`neon realtime subscribe`](https://neon.com/docs/cli/realtime#subscribe).

## Branch policy

The `branch` closure works on any Neon project. The examples below configure the default branch and apply TTL and compute to new branches at creation. Returning `{}` for existing branches is deliberate: it avoids overwriting settings on branches already in use:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  branch: (branch) => {
    if (branch.isDefault) {
      // Default branch: no overrides, uses project defaults
      return {};
    }
    if (!branch.exists) {
      // New non-default branches: minimum compute, auto-expire
      return {
        ttl: "7d",
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25,
            autoscalingLimitMaxCu: 0.25,
          },
        },
      };
    }
    // Existing branch: no changes
    return {};
  },
});
```

On paid plans, you can also protect the default branch and control suspend timeouts:

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  branch: (branch) => {
    if (branch.isDefault) {
      // Protect and size for production
      return {
        protected: true,
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.5,
            autoscalingLimitMaxCu: 4,
          },
        },
      };
    }
    if (!branch.exists) {
      // New non-default branches: minimum compute, auto-expire, suspend on idle
      return {
        ttl: "7d",
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25,
            autoscalingLimitMaxCu: 0.25,
            suspendTimeout: "5m",
          },
        },
      };
    }
    // Existing branch: no changes
    return {};
  },
});
```

When `neon checkout` creates a new branch, the closure runs with `branch.exists === false`, so TTL, compute settings, and services take effect at creation. Checking out an existing branch doesn't apply or reconcile the policy.

### BranchTarget fields

| Field         | Type       | Description                                                                          |
| ------------- | ---------- | ------------------------------------------------------------------------------------ |
| `name`        | `string`   | Branch name                                                                          |
| `id`          | `string?`  | Branch ID. Not set during pre-create evaluation                                      |
| `exists`      | `boolean`  | `false` during pre-create evaluation                                                 |
| `isDefault`   | `boolean?` | Whether this is the project's default branch. Not set during pre-create evaluation   |
| `isProtected` | `boolean?` | Whether the branch is marked protected in Neon. Not set during pre-create evaluation |
| `parentId`    | `string?`  | ID of the parent branch. Not always present                                          |
| `expiresAt`   | `string?`  | Branch expiry timestamp. Not always present                                          |

### BranchTuning fields

| Field                                            | Type                        | Description                                                                                                                                                      |
| ------------------------------------------------ | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parent`                                         | `string`                    | Parent branch name or ID                                                                                                                                         |
| `protected`                                      | `boolean`                   | Mark the branch as protected                                                                                                                                     |
| `ttl`                                            | `string \| number`          | Branch lifetime: `"7d"`, `"2h"`, or seconds as a number. Maximum 30 days. Validated at deploy time, not by TypeScript                                            |
| `postgres.computeSettings.autoscalingLimitMinCu` | `ComputeUnit`               | Minimum compute units. Any size Neon offers: 0.25, 0.5, every integer 1 to 16, and even sizes 18 to 56                                                           |
| `postgres.computeSettings.autoscalingLimitMaxCu` | `ComputeUnit`               | Maximum compute units. For an autoscaling range, keep both bounds at 16 or below and no more than 8 CU apart; sizes above 16 are fixed-size (`min` equals `max`) |
| `postgres.computeSettings.suspendTimeout`        | `false \| string \| number` | Idle suspend timeout. `false` disables suspend                                                                                                                   |

## Type-safe environment variables

`@neon/env` gives you type-safe access to your branch's injected variables. It reads `process.env` at runtime and validates each variable against the services declared in your `neon.ts` config. Missing or empty variables throw with a clear error.

```bash
npm install @neon/env
```

```ts
import { parseEnv } from '@neon/env';
import config from './neon';

const env = parseEnv(config);

env.postgres.databaseUrl;         // DATABASE_URL
env.postgres.databaseUrlUnpooled; // DATABASE_URL_UNPOOLED
env.branch.name;                  // NEON_BRANCH             (when NEON_BRANCH is set)
env.branch.id;                    // NEON_BRANCH_ID
env.branch.functionHostSuffix;    // NEON_FUNCTION_HOST_SUFFIX
env.auth.baseUrl;                 // NEON_AUTH_BASE_URL       (env.auth when auth: true)
env.auth.jwksUrl;                 // NEON_AUTH_JWKS_URL
env.dataApi.url;                  // NEON_DATA_API_URL        (env.dataApi when dataApi enabled)
env.aiGateway.apiKey;             // NEON_AI_GATEWAY_TOKEN    (env.aiGateway when aiGateway enabled)
env.aiGateway.baseUrl;            // NEON_AI_GATEWAY_BASE_URL
env.storage.accessKeyId;          // AWS_ACCESS_KEY_ID        (env.storage when buckets declared)
env.storage.secretAccessKey;      // AWS_SECRET_ACCESS_KEY
env.storage.endpoint;             // AWS_ENDPOINT_URL_S3
env.storage.region;               // AWS_REGION
env.realtime.url;                 // NEON_REALTIME_URL        (env.realtime when preview.realtime enabled)
env.realtime.secret;              // NEON_REALTIME_SECRET
```

Each namespace exists only when its service is declared: `env.auth` when `auth: true`, `env.storage` when you declare `buckets`, and so on. If you access a namespace your config doesn't declare, TypeScript catches it.

`env.branch.id` and `env.branch.functionHostSuffix` are optional, like `env.branch.name`. To require them, select their keys: `parseEnv(config, ['NEON_BRANCH_ID', 'NEON_FUNCTION_HOST_SUFFIX'])`. To call another function, use `functionBaseUrl('<slug>')` from `@neon/env` rather than building the URL yourself. `@neon/env` 2.0.0 removed `env.functions`. See [Call another function](https://neon.com/docs/compute/functions/environment-variables#call-another-function).

`parseEnv(config, '<slug>')` adds `env.function`: the scoped env for code running inside that function, exposing the `env` vars declared in its `neon.ts` definition.

Pass an array of keys to validate and return only a subset. Useful when a process needs just one or two variables:

```ts
const { postgres } = parseEnv(config, ["DATABASE_URL"]);
postgres.databaseUrl; // string (databaseUrlUnpooled is absent)
```

The key list autocompletes from your config, so selecting a variable from a service you haven't declared is a type error.

### Inject env at runtime without a file

`@neon/env` also ships a `neon-env` binary for the cases where you don't want the branch's variables written to disk. It resolves them from your `neon.ts` policy at runtime:

```bash
# Run a command with the branch's Neon env vars injected into its environment.
# Use `--` to separate the command:
neon-env run -- npm run dev

# Print the branch's Neon env vars to stdout, as dotenv lines or JSON,
# for piping into another env manager:
neon-env export
neon-env export --format json
```

Use `neon-env run` as the runtime counterpart to the on-disk [`neon env pull`](https://neon.com/docs/cli/env) when you'd rather not keep secrets in the working tree, and `neon-env export` when another tool (for example [varlock](https://varlock.dev)) should ingest the values.

### Resolve env in code with `fetchEnv`

`parseEnv` reads variables already present in `process.env`. `fetchEnv` is its programmatic runtime sibling: it fetches a branch's env from Neon and returns the same typed, namespaced shape, so code can resolve a branch's env without shelling out or writing a file first. Unlike the `neon-env` CLI, `fetchEnv` reads no environment variables or credential files on your behalf. Pass a Neon API key explicitly as `apiKey`, or it throws.

```ts
import { fetchEnv } from '@neon/env';
import config from './neon';

const env = await fetchEnv(config, {
  projectId: 'patient-art-12345',
  branch: 'main',
  apiKey: process.env.NEON_API_KEY,
});
env.postgres.databaseUrl;
```

## CLI commands

| Command                                                     | What it does                                                                                              |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| [`neon config init`](https://neon.com/docs/cli/config#init) | Scaffold a starter `neon.ts` and install the config packages                                              |
| [`neon link`](https://neon.com/docs/cli/link)               | Connect the current directory to a Neon project. Required to use linked branch defaults in other commands |
| [`neon deploy`](https://neon.com/docs/cli/config)           | Apply `neon.ts` to the linked branch (alias for `neon config apply`)                                      |
| [`neon config plan`](https://neon.com/docs/cli/config)      | Preview what `neon deploy` would change, without applying                                                 |
| [`neon config status`](https://neon.com/docs/cli/config)    | Show the current live state of the branch as a `neon.ts`-shaped config                                    |
| [`neon env pull`](https://neon.com/docs/cli/env)            | Write the branch's Neon-managed variables to `.env.local` (or `.env` if it already exists)                |
| [`neon checkout`](https://neon.com/docs/cli/checkout)       | Switch to or create a branch; new branches are created from the `neon.ts` policy (TTL, compute, services) |
| [`neon dev`](https://neon.com/docs/cli/dev)                 | Run functions locally against the linked branch; watches for changes and hot-reloads                      |

`neon deploy` is an alias for `neon config apply`. For its flags (`--branch`, `--project-id`, `--config`, `--env`, `--update-existing`, and more), see the [`neon config`](https://neon.com/docs/cli/config) reference.

## Full stack example

All services combined. `neon deploy` provisions everything and writes credentials to `.env.local`.

```ts filename="neon.ts"
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true,
  dataApi: true,

  aiGateway: true,
  buckets: {
    uploads: {},
  },
  functions: {
    api: {
      name: "API",
      source: "./functions/api.ts",
    },
  },
  preview: {
    realtime: { allowedOrigins: ["https://app.example.com"] },
  },

  branch: (branch) => {
    if (branch.isDefault) {
      // Protect and size for production
      return {
        protected: true,
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.5,
            autoscalingLimitMaxCu: 4,
          },
        },
      };
    }
    if (!branch.exists) {
      // New non-default branches: minimum compute, auto-expire, suspend on idle
      return {
        ttl: "7d",
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25,
            autoscalingLimitMaxCu: 0.25,
            suspendTimeout: "5m",
          },
        },
      };
    }
    // Existing branch: no changes
    return {};
  },
});
```

## Troubleshooting

### "keys can be lifted out of preview" warning

```text
These neon.ts keys are now GA and can be lifted out of preview: preview.aiGateway → aiGateway, preview.functions → functions, preview.buckets → buckets.
```

Informational, not an error: your services still deploy. You're declaring GA services under `preview`, where they're deprecated aliases, on `@neon/config` 1.6.0 or later. Move those keys to the top level to clear it, or keep `preview` if you also run on installs older than 1.6.0.

### "unknown keys" error

```text
ConfigValidationError: Invalid Neon config:
  - unknown keys: "aiGateway", "functions"
```

Your `@neon/config` is older than 1.6.0, which introduced top-level `aiGateway`, `functions`, and `buckets`. Upgrade with `npm install @neon/config@latest` (and `npm install -g neon@latest`), or keep the services under `preview`.

--- [Document source](https://neon.com/docs/reference/python-sdk.md) ---

> Summary: The Neon Python SDK (neon-api, installable via pip) wraps the Neon REST API and exposes methods for creating, updating, and deleting projects, branches, databases, endpoints, roles, API keys, and organizations from Python code. Use it when you need to automate Neon platform operations in Python scripts or applications without constructing raw HTTP requests against the Neon API.

# Python SDK (Neon API)

Programmatically manage Neon projects, branches, databases, and other platform resources

Last updated: 2026-08-31

**What you will learn:**

- What is the Neon Python SDK
- Basic usage
- Where to find the docs
- Supported methods

**Related resources**

- [Neon API Reference](https://neon.com/docs/reference/api)

**Source code**

- [Python wrapper for the Neon API (GitHub)](https://github.com/neondatabase/neon-api-python)
- [Python wrapper for the Neon API (Python Package Index)](https://pypi.org/project/neon-api/)

## About the SDK

Neon supports the [neon-api - Python client for the Neon API](https://pypi.org/project/neon-api/), a wrapper for the [Neon API](https://neon.com/docs/reference/api). This SDK simplifies integration of Python applications with the Neon platform, providing methods to programmatically manage API keys, Neon projects, branches, databases, endpoints, roles, and operations.

**Warning: Compatibility limits in version 0.3.0**

The published Python SDK does not yet support all Neon API routes. Use the [Neon REST API](https://neon.com/docs/reference/api) or [Neon TypeScript SDK](https://neon.com/docs/reference/typescript-sdk) for the operations below.

| Python SDK method            | SDK request                                  | Current API contract                     |
| ---------------------------- | -------------------------------------------- | ---------------------------------------- |
| `branch_set_as_primary`      | `POST .../set_as_primary`                    | `POST .../set_as_default`                |
| `project_permissions_revoke` | `DELETE .../permissions` with a request body | `DELETE .../permissions/{permission_id}` |
| `role_password_reveal`       | `POST .../reveal_password`                   | `GET .../reveal_password`                |

The current API contract doesn't document compatibility aliases for the outdated requests.

**Tip: AI assistant support**

Neon's [Agent Skills](https://neon.com/docs/ai/agent-skills) give AI coding assistants context about the Neon Python SDK for managing resources programmatically and other Neon features. Install them for more accurate code suggestions.

## Installation

Installation of `neon_api` is easy, with `pip`:

```shell
$ pip install neon-api
```

## Usage

```python
from neon_api import NeonAPI

# Initialize the client.
neon = NeonAPI(api_key='your_api_key')
```

## Documentation

Documentation for the `neon-api - Python SDK`, including a [Quickstart](https://neon-api-python.readthedocs.io/en/latest/#quickstart), can be found on **Read the Docs**. See [neon-api: Python client for the Neon API](https://neon-api-python.readthedocs.io/en/latest/#neon-api-python-client-for-the-neon-api).

## Methods of the `NeonAPI` Class

The following list describes the methods exposed by the published Python package. The compatibility warning above identifies methods whose requests don't match the current API contract.

- `me()`: Returns the current user.
- `current_user_organizations()`: Returns the current user's organizations.

### Manage API Keys

- `api_keys()`: Returns a list of API keys.
- `api_key_create(**json)`: Creates an API key.
- `api_key_delete(key_id)`: Deletes a given API key.

### Manage Projects

All Neon accounts are organization-based. To list projects, first retrieve the user's organization with `current_user_organizations()`, then pass `org_id`:

```python
orgs = neon.current_user_organizations()
org_id = orgs[0].id
projects = neon.projects(org_id=org_id)
```

- `projects(org_id=None)`: Returns a list of projects. Pass `org_id` to list projects within an organization.
- `project(project_id)`: Returns a specific project.
- `project_create(project_id, **json)`: Creates a new project.
- `project_update(project_id, **json)`: Updates a given project.
- `project_delete(project_id)`: Deletes a given project.
- `project_permissions(project_id)`: Returns a list of permissions for a given project.
- `project_permissions_grant(project_id, **json)`: Grants permissions to a given project.
- `project_permissions_revoke(project_id, **json)`: Revokes permissions from a given project.
- `connection_uri(project_id, database_name, role_name)`: Returns the connection string for a given project.

### Manage Branches

- `branches(project_id)`: Returns a list of branches for a given project.
- `branch(project_id, branch_id)`: Returns a specific branch.
- `branch_create(project_id, **json)`: Creates a new branch. Branch names are optional (defaults to branch ID if not specified). If provided, names must be unique within the project, can be up to 256 characters, and cannot be empty or only whitespace. See [Branch naming requirements](https://neon.com/docs/manage/branches#branch-naming-requirements).
- `branch_update(project_id, branch_id, **json)`: Updates a given branch.
- `branch_delete(project_id, branch_id)`: Deletes a given branch.
- `branch_set_as_primary(project_id, branch_id)`: Sets a given branch as primary.

### Manage Databases

- `databases(project_id, branch_id)`: Returns a list of databases for a given project and branch.
- `database(project_id, branch_id, database_id)`: Returns a specific database.
- `database_create(project_id, branch_id, **json)`: Creates a new database.
- `database_update(project_id, branch_id, **json)`: Updates a given database.
- `database_delete(project_id, branch_id, database_id)`: Deletes a given database.

### Manage Endpoints

- `endpoints(project_id, branch_id)`: Returns a list of endpoints for a given project and branch.
- `endpoint_create(project_id, branch_id, **json)`: Creates a new endpoint.
- `endpoint_update(project_id, branch_id, endpoint_id, **json)`: Updates a given endpoint.
- `endpoint_delete(project_id, branch_id, endpoint_id)`: Deletes a given endpoint.
- `endpoint_start(project_id, branch_id, endpoint_id)`: Starts a given endpoint.
- `endpoint_suspend(project_id, branch_id, endpoint_id)`: Suspends a given endpoint.

### Manage Roles

- `roles(project_id, branch_id)`: Returns a list of roles for a given project and branch.
- `role(project_id, branch_id, role_name)`: Returns a specific role.
- `role_create(project_id, branch_id, role_name)`: Creates a new role.
- `role_delete(project_id, branch_id, role_name)`: Deletes a given role.
- `role_password_reveal(project_id, branch_id, role_name)`: Reveals the password for a given role.
- `role_password_reset(project_id, branch_id, role_name)`: Resets the password for a given role.

### Manage Organizations

- `organization(org_id)`: Returns details for a specific organization.

### Manage Operations

- `operations(project_id)`: Returns a list of operations for a given project.
- `operation(project_id, operation_id)`: Returns a specific operation.

### Experimental

- `consumption()`: Returns a list of project consumption metrics.

_View the [Neon API](https://neon.com/docs/reference/api) documentation for more information on the available endpoints and their parameters._

--- [Document source](https://neon.com/docs/reference/sdk.md) ---

> Summary: Neon SDKs split into two categories: Client SDKs (TypeScript) for building apps with the Data API and Managed Better Auth, and Management SDKs (TypeScript, Python) for programmatically creating and controlling projects, branches, databases, endpoints, and roles via the Neon API. Client SDKs target app developers who need database queries and user authentication; Management SDKs target platform automation and DevOps workflows.

# Neon SDKs

Last updated: 2026-10-02

Neon provides two categories of SDKs to support different use cases:

- **Client SDKs**: For application developers building apps with the [Data API](https://neon.com/docs/data-api/overview) and optionally [Managed Better Auth](https://neon.com/docs/auth/overview). These SDKs handle database queries and user authentication from your application.
- **Management SDKs**: For programmatically managing Neon platform resources like projects, branches, databases, endpoints, and roles. These are wrappers around the [Neon API](https://neon.com/docs/reference/api).

## Client SDKs

Use these SDKs to build applications with the Data API and optional authentication via Managed Better Auth or another JWT provider.

- [Auth and Data API SDK](https://neon.com/docs/reference/javascript-sdk): Build apps with the Data API using Managed Better Auth and database queries

## Management SDKs

Use these SDKs to programmatically manage your Neon infrastructure (projects, branches, databases, endpoints, roles, and operations).

- [Neon Management SDK](https://neon.com/docs/reference/typescript-sdk): The official TypeScript SDK for the Neon API. Manage projects, branches, Postgres, storage, functions, and auth from one typed client
- [Effect bindings](https://neon.com/docs/reference/effect-sdk): Effect v4 bindings for the Management SDK: every call an Effect, every paginated list a Stream, with tagged errors and interruption
- [Migrate to @neon/sdk](https://neon.com/docs/reference/migrate-api-client-to-sdk): Migrate from @neondatabase/api-client to @neon/sdk
- [Python SDK (Neon API)](https://neon.com/docs/reference/python-sdk): Programmatically manage Neon projects, branches, databases, and other platform resources

--- [Document source](https://neon.com/docs/reference/terraform.md) ---

> Summary: The community-maintained Terraform provider for Neon (`kislerdm/neon`) lets you define Neon projects, branches, compute endpoints, roles, databases, API keys, and VPC endpoints as infrastructure-as-code in declarative HCL. Choose this page when you want to provision new Neon resources or bring existing Console-created resources under Terraform management using `terraform import` or the declarative import-block syntax. The provider is not officially supported by Neon; the guide covers upgrade practices to prevent unintended resource replacements and data loss during `terraform init -upgrade`.

# Manage Neon with Terraform

Use Terraform to provision and manage your Neon projects, branches, endpoints, roles, databases, and other resources as code.

Last updated: 2026-08-04

Terraform is an open-source infrastructure as code (IaC) tool that allows you to define and provision cloud resources in a declarative configuration language. By codifying infrastructure, Terraform enables consistent, repeatable, and automated deployments, significantly reducing manual errors.

This guide will show you how to use **Terraform to manage your Neon projects**, including your branches, databases, and compute endpoints. By using Terraform with Neon, you get better control, can track changes, and automate your database setup.

Neon sponsors the following community-developed Terraform provider for managing Neon resources:

**Terraform Provider Neon - Maintainer: Dmitry Kisler**

- [GitHub repository](https://github.com/kislerdm/terraform-provider-neon)
- [Terraform Registry](https://registry.terraform.io/providers/kislerdm/neon/0.6.1)
- [Terraform Registry Documentation](https://registry.terraform.io/providers/kislerdm/neon/latest/docs)

**Note:** This provider is not maintained or officially supported by Neon. Use at your own discretion. If you have questions about the provider, please contact the project maintainer.

## Provider usage notes

- **Provider upgrades**: When using `terraform init -upgrade` to update a custom Terraform provider, be aware that changes in the provider's schema or defaults can lead to unintended resource replacements. This may occur when certain attributes are altered or reset. For example, fields previously set to specific values might be reset to `null`, forcing the replacement of the entire resource.

  To avoid unintended resource replacements which can result in data loss:

  - Review the provider's changelog for any breaking changes that might affect your resources before upgrading to a new version.
  - For CI pipelines and auto-approved pull requests, only use `terraform init`. Running `terraform init -upgrade` should be done manually followed by plan reviews.
  - Run `terraform plan` before applying any changes to detect potential differences and review the behavior of resource updates.
  - Use [lifecycle protections](https://developer.hashicorp.com/terraform/language/meta-arguments/lifecycle#prevent_destroy) on critical resources to ensure they're not recreated unintentionally.
  - Explicitly define all critical resource parameters in your Terraform configurations, even if they had defaults previously.
  - On Neon paid plans, you can enable branch protection to prevent unintended deletion of branches and projects. To learn more, see [Protected branches](https://neon.com/docs/guides/protected-branches).

- **Provider maintenance**: As Neon enhances existing features and introduces new ones, the [Neon API](https://neon.com/docs/reference/api) will continue to evolve. These changes may not immediately appear in community-maintained Terraform providers. If you notice that a provider requires an update, please reach out to the maintainer by opening an issue or contributing to the provider's GitHub repository.

## Prerequisites

Before you begin, ensure you have the following:

1. **Terraform CLI installed:** If you don't have Terraform installed, download and install it from the [official Terraform website](https://developer.hashicorp.com/terraform/install). The Neon provider requires Terraform version `1.14.x` or later.
2. **Neon Account:** You'll need a Neon account. If you don't have one, sign up at [neon.tech](https://console.neon.tech/signup).
3. **Neon API key:** Generate an API key from the Neon Console. Navigate to your Account Settings > API Keys. This key is required for the provider to authenticate with the Neon API. Learn more about creating API keys in [Manage API keys](https://neon.com/docs/manage/api-keys).

## Set up the Terraform Neon provider

1. **Create a project directory:**
   Create a new directory for your Terraform project and navigate into it.

   ```shell
   mkdir neon-terraform-project
   cd neon-terraform-project
   ```

2. **Create a `main.tf` file:**
   This file will contain your Terraform configuration. Start by declaring the required Neon provider.

   ```terraform
   terraform {
     required_providers {
       neon = {
         source  = "kislerdm/neon"
       }
     }
   }

   provider "neon" {}
   ```

3. **Initialize terraform:**
   Run the `terraform init` command in your project directory. This command downloads and installs the Neon provider.
   ```shell
   terraform init
   ```

## Configure authentication

The Neon provider needs your Neon API key to manage resources. You can configure it in two ways:

1. **Directly in the provider block (Less secure):**
   For quick testing, you can **hardcode your API key** directly within `provider "neon"` block. However, this method isn't recommended for production environments or shared configurations. A more secure alternative is to retrieve the API key from a secrets management service like [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) or [HashiCorp Vault](https://developer.hashicorp.com/vault), and then update your provider block to reflect this.

   ```terraform
   provider "neon" {
     api_key = "<YOUR_NEON_API_KEY>"
   }
   ```

2. **Using environment variables:**
   The provider will automatically use the `NEON_API_KEY` environment variable if set.

   ```shell
   export NEON_API_KEY="<YOUR_NEON_API_KEY>"
   ```

   If the environment variable is set, you can leave the `provider "neon"` block empty:

   ```terraform
   provider "neon" {}
   ```

**Note:** The following sections primarily detail the creation of Neon resources. To manage existing resources, use the `terraform import` command. More information can be found in the [Importing Existing Resources](https://neon.com/docs/reference/terraform#import-existing-neon-resources) section.

## Manage Neon resources

Now you can start defining Neon resources in your `main.tf` file.

### Managing projects

**Warning:** Always set the `org_id` attribute when creating a `neon_project`. You can find your Organization ID in the Neon Console under Account Settings → Organization settings.

![finding your organization ID from the settings page](https://neon.com/docs/manage/orgs_id.png)

Omitting `orgId` can cause resources to be created in the wrong organization or produce duplicate projects, and subsequent `terraform plan` / `terraform apply` runs may attempt destructive changes (including deletions). To avoid this, explicitly provide `orgId` when defining your project as shown in the example below.

A Neon project is the top-level container for your Postgres databases, branches, and endpoints.

```terraform
resource "neon_project" "my_app_project" {
  name       = "my-application-project"
  pg_version = 16
  region_id  = "aws-us-east-1"
  org_id     = "your-neon-organization-id" # Replace with your actual Org ID
  # free accounts have maximum retention window of 6 hours (21600 seconds)
  history_retention_seconds = 21600

  # Configure default branch settings (optional)
  branch {
    name          = "production"
    database_name = "app_db"
    role_name     = "app_admin"
  }

  # Configure default endpoint settings (optional)
  default_endpoint_settings {
    autoscaling_limit_min_cu = 0.25
    autoscaling_limit_max_cu = 1.0
    # suspend_timeout_seconds  = 300
  }
}
```

This configuration creates a new Neon project.

**Key `neon_project` attributes:**

- `name`: (Optional) Name of the project.
- `pg_version`: (Optional) The major supported PostgreSQL version, such as 17.
- `region_id`: (Optional) The region where the project will be created (for example, `aws-us-east-1`).
  > For up-to-date information on available regions, see [Neon Regions](https://neon.com/docs/introduction/regions).
- `org_id`: The Organization ID under which to create the project.
- `history_retention_seconds`: (Optional) Duration in seconds to retain historical data for point-in-time recovery. Free plans have a maximum of 21600 seconds (6 hours). Default is 86400 seconds (24 hours) for paid plans.
- `branch {}`: (Optional) Block to configure the default primary branch.

**Output project details:**
You can output computed values like the project ID or connection URI:

```terraform
output "project_id" {
  value = neon_project.my_app_project.id
}

output "project_connection_uri" {
  description = "Default connection URI for the primary branch (contains credentials)."
  value       = neon_project.my_app_project.connection_uri
  sensitive   = true
}

output "project_default_branch_id" {
  value = neon_project.my_app_project.default_branch_id
}

output "project_database_user" {
  value = neon_project.my_app_project.database_user
}
```

For more attributes and options on managing projects, refer to the [Provider's documentation](https://github.com/kislerdm/terraform-provider-neon/blob/master/docs/resources/project.md).

### Managing branches

You can create branches from the primary branch or any other existing branch.

```terraform
resource "neon_branch" "dev_branch" {
  project_id = neon_project.my_app_project.id
  name       = "feature-x-development"
  parent_id  = neon_project.my_app_project.default_branch_id # Branch from the project's primary branch

  # Optional: Create a protected branch
  # protected = "yes"

  # Optional: Create from a specific LSN or timestamp of the parent
  # parent_lsn = "..."
  # parent_timestamp = 1678886400 # Unix epoch
}
```

**Key `neon_branch` attributes:**

- `project_id`: (Required) ID of the parent project.
- `name`: (Optional) Name for the new branch. If not specified, defaults to the branch ID. If provided, must be unique within the project and can be up to 256 characters. Cannot be empty or only whitespace. See [Branch naming requirements](https://neon.com/docs/manage/branches#branch-naming-requirements).
- `parent_id`: (Optional) ID of the parent branch. If not specified, defaults to the project's primary branch.
- `protected`: (Optional, String: "yes" or "no") Set to protect the branch.
- `parent_lsn`: (Optional) LSN of the parent branch to create from.
- `parent_timestamp`: (Optional) Timestamp of the parent branch to create from.

> `protected` attribute is only available for paid plans. It allows you to protect branches from deletion or modification.

For more attributes and options on managing branches, refer to the [Provider's documentation](https://github.com/kislerdm/terraform-provider-neon/blob/master/docs/resources/branch.md).

### Managing endpoints

Endpoints provide connection strings to access your branches. Each branch can have multiple read-only endpoints but only one read-write endpoint.

Before creating an endpoint, you must first create a **branch** for it to connect to. Here's how to create a read-write endpoint for your `dev_branch`:

```terraform
resource "neon_endpoint" "dev_endpoint" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id
  type       = "read_write" # "read_write" or "read_only"

  autoscaling_limit_min_cu = 0.25
  autoscaling_limit_max_cu = 0.5
  # suspend_timeout_seconds  = 600

  # Optional: Enable connection pooling
  # pooler_enabled = true
}

output "dev_endpoint_host" {
  value = neon_endpoint.dev_endpoint.host
}
```

**Key `neon_endpoint` attributes:**

- `project_id`: (Required) ID of the parent project.
- `branch_id`: (Required) ID of the branch this endpoint connects to.
- `type`: (Optional) `read_write` (default) or `read_only`. A branch can only have one `read_write` endpoint.
- `autoscaling_limit_min_cu`/`autoscaling_limit_max_cu`: (Optional) Compute units for autoscaling.
- `suspend_timeout_seconds`: (Optional) Inactivity period before suspension. Only available for paid plans.
- `pooler_enabled`: (Optional) Enable connection pooling.

**Note:** It is not possible currently to change the endpoint type after creation. The `type` attribute is immutable, meaning you cannot modify it once the endpoint is created. This includes changing from `read_write` to `read_only` or vice versa. This is a limitation of the Neon API and the provider's current implementation. You must destroy the existing endpoint and create a new one with the desired type.

For more attributes and options on managing endpoints, refer to the [Provider's documentation](https://github.com/kislerdm/terraform-provider-neon/blob/master/docs/resources/endpoint.md)

### Managing roles

Roles (users) are managed per branch. Before creating a role, ensure you have a branch created. Follow the [Managing Branches](https://neon.com/docs/reference/terraform#managing-branches) section for details.

```terraform
resource "neon_role" "app_user" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id
  name       = "application_user"
}

output "app_user_password" {
  value     = neon_role.app_user.password
  sensitive = true
}
```

**Key `neon_role` attributes:**

- `project_id`: (Required) ID of the parent project.
- `branch_id`: (Required) ID of the branch for this role.
- `name`: (Required) Name of the role.
- `password`: (Computed, Sensitive) The generated password for the role.

For more attributes and options on managing roles, refer to the [Provider's documentation](https://github.com/kislerdm/terraform-provider-neon/blob/master/docs/resources/role.md)

### Managing databases

Databases are also managed per branch. Follow the [Managing Branches](https://neon.com/docs/reference/terraform#managing-branches) section for details on creating a branch.

```terraform
resource "neon_database" "service_db" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id
  name       = "service_specific_database"
  owner_name = neon_role.app_user.name
}
```

**Key `neon_database` attributes:**

- `project_id`: (Required) ID of the parent project.
- `branch_id`: (Required) ID of the branch for this database.
- `name`: (Required) Name of the database.
- `owner_name`: (Required) Name of the role that will own this database.

For more attributes and options on managing databases, refer to the [Provider's documentation](https://github.com/kislerdm/terraform-provider-neon/blob/master/docs/resources/database.md)

### Managing API keys

You can manage Neon API keys themselves using Terraform.

```terraform
resource "neon_api_key" "ci_cd_key" {
  name = "automation-key-for-ci"
}

output "ci_cd_api_key_value" {
  description = "The actual API key token."
  value       = neon_api_key.ci_cd_key.key
  sensitive   = true
}
```

**Key `neon_api_key` attributes:**

- `name`: (Required) A descriptive name for the API key.
- `key`: (Computed, Sensitive) The generated API key token.

### Advanced: Project permissions

Share project access with other users.

```terraform
resource "neon_project_permission" "share_with_colleague" {
  project_id = neon_project.my_app_project.id
  grantee    = "colleague@example.com"
}
```

### Advanced: VPC endpoint management (for Neon private networking)

These resources are used for organizations requiring private networking.

#### Assign VPC endpoint to organization

```terraform
resource "neon_vpc_endpoint_assignment" "org_vpc_endpoint" {
  org_id          = "your-neon-organization-id" # Replace with your actual Org ID
  region_id       = "aws-us-east-1"             # Neon region ID
  vpc_endpoint_id = "vpce-xxxxxxxxxxxxxxxxx"    # Your AWS VPC Endpoint ID
  label           = "main-aws-vpc-endpoint"
}
```

For more attributes and options on managing VPC endpoints, refer to the [Provider's documentation](https://github.com/kislerdm/terraform-provider-neon/blob/master/docs/resources/vpc_endpoint_assignment.md)

#### Restrict project to VPC endpoint

```terraform
resource "neon_vpc_endpoint_restriction" "project_to_vpc" {
  project_id      = neon_project.my_app_project.id
  vpc_endpoint_id = neon_vpc_endpoint_assignment.org_vpc_endpoint.vpc_endpoint_id
  label           = "restrict-my-app-project-to-vpc"
}
```

For more attributes and options on managing VPC endpoint restrictions, refer to the [Provider's documentation](https://github.com/kislerdm/terraform-provider-neon/blob/master/docs/resources/vpc_endpoint_restriction.md)

## Apply the configuration

Once you have defined your resources:

1. **Format and validate:**

   ```shell
   terraform fmt
   terraform validate
   ```

2. **Plan:**
   Run `terraform plan` to see what actions Terraform will take. This command shows you the resources that will be created, modified, or destroyed without making any changes. Review the output carefully to ensure it matches your expectations.

   ```shell
   terraform plan -out=tfplan
   ```

3. **Apply:**
   Run `terraform apply` to create the resources in Neon.
   ```shell
   terraform apply tfplan
   ```
   Terraform will ask for confirmation before proceeding with the changes. Type `yes` to confirm.

You have now successfully created and managed Neon resources using Terraform! You can continue to modify your `main.tf` file to add, change, or remove resources as needed. After making changes, always run `terraform plan` to review the changes before applying them.

## Import existing Neon resources

If you have existing Neon resources that were created outside of Terraform (for example, via the Neon Console or API directly), you can bring them under Terraform's management. This allows you to manage their lifecycle with code moving forward.

Terraform offers two primary ways to do this: using the `terraform import` CLI command or, for Terraform `1.5.0` and later, using declarative `import` blocks directly in your configuration.

Both methods involve telling Terraform about an existing resource and associating it with a resource block in your configuration.

### Set up your Terraform configuration

Before you can import any resources, ensure your Terraform environment is configured for the Neon provider:

1. **Define the provider:** Make sure you have the `neon` provider declared in your `main.tf` or a dedicated `providers.tf` file.

   ```terraform
   terraform {
     required_providers {
       neon = {
         source  = "kislerdm/neon"
       }
     }
   }

   provider "neon" {}
   ```

2. **Initialize terraform:** If you haven't already, or if you've just added the provider configuration, run:

   ```shell
   terraform init
   ```

   This downloads the Neon provider plugin.

   **Warning: Important: Provider Upgrades**

   Avoid using `terraform init -upgrade` in CI pipelines and auto-approved pull requests, as this can lead to unintended resource replacements and data loss if there are breaking changes or major version jumps. Instead, use `terraform init` in your automated workflows. Running `terraform init -upgrade` should always be done manually, followed by plan reviews. For additional guidance, see [Important usage notes](https://neon.com/docs/reference/terraform#provider-usage-notes).

3. **Configure authentication:** Follow the authentication steps mentioned in [Configure Authentication](https://neon.com/docs/reference/terraform#configure-authentication) to ensure Terraform can communicate with your Neon account.

### Neon resource IDs for import

When importing Neon resources, you need to know the specific ID format for each resource type. Always refer to the "Import" section of the specific resource's documentation page on the [Provider's GitHub: `kislerdm/terraform-provider-neon`](https://github.com/kislerdm/terraform-provider-neon/tree/master/docs/resources) for the exact ID format.

Here are some common formats for different Neon resources:

- **`neon_project`:** Uses the Project ID (for example, `damp-recipe-88779456`).
- **`neon_branch`:** Uses the Branch ID (for example, `br-orange-bonus-a4v00wjl`).
- **`neon_endpoint`:** Uses the Endpoint ID (for example, `ep-blue-cell-a4xzunwf`).
- **`neon_role`:** Uses a composite ID: `<project_id>/<branch_id>/<role_name>` (for example, `damp-recipe-88779456/br-orange-bonus-a4v00wjl/application_user`).
- **`neon_database`:** Uses a composite ID: `<project_id>/<branch_id>/<database_name>` (for example, `damp-recipe-88779456/br-orange-bonus-a4v00wjl/service_specific_database`).
- **`neon_api_key` and `neon_jwks_url`:** These resources do not support import. You'll need to recreate them using Terraform if you want to manage them via IaC.

### Order of import for dependent resources

When importing resources that depend on each other, it's best practice to import them in the order of their dependencies. This helps ensure that Terraform can correctly understand relationships and that your HCL resource blocks can reference already-imported parent resources.

A common order for importing Neon resources is:

```plaintext
Project -> Branch -> Endpoint -> Role -> Database
```

Depending on your preference and the version of Terraform you are using, you can choose between two methods to import existing Neon resources into Terraform. Follow [Method 1](https://neon.com/docs/reference/terraform#method-1-using-the-terraform-import-cli-command) if you prefer the traditional CLI import command, or [Method 2](https://neon.com/docs/reference/terraform#method-2-using-import-blocks-terraform-150) if you want to use the newer declarative `import` blocks introduced in Terraform `1.5.0`.

### Method 1: Using the `terraform import` CLI command

For each Neon resource you want to import, you'll generally follow these two steps:

1. **Write a resource block:** Add a corresponding `resource` block to your Terraform configuration files (for example, `main.tf`). This block tells Terraform how you _want_ the resource to be configured. You might not know all the attributes perfectly upfront; Terraform will populate many of them from the actual state of the resource during the import.

2. **Run `terraform import`:** Execute the import command, which takes the Terraform resource address and the Neon-specific ID of the existing resource.
   ```shell
   terraform import <terraform_resource_address> <neon_resource_id>
   ```

#### Example: Importing the previously defined resources

In this example, we'll import the resources we defined earlier in the [Manage Neon Resources](https://neon.com/docs/reference/terraform#manage-neon-resources) section. This needs a project, a branch, an endpoint, a role, and a database already created in your Neon account. These resources will now be imported into a new Terraform configuration.

##### Define the HCL resource blocks

In your `main.tf` file, define the resource blocks for the existing resources. You can start with minimal definitions, as Terraform will populate the actual values during the import process. You primarily need to define the resource type and a name for Terraform to use. Terraform will populate the actual attribute values from the live resource into its state file during the import. You'll then use `terraform plan` to see these and update your HCL to match or to define your desired state.

For required attributes (like `project_id` for a branch), you'll either need to hardcode the known ID or reference a resource that will also be imported.

```terraform
terraform {
  required_providers {
    neon = {
      source  = "kislerdm/neon"
    }
  }
}

provider "neon" {}

# --- Project ---
resource "neon_project" "my_app_project" {}

# --- Development Branch ---
# Requires project_id. We'll reference the project we're about to import.
# The actual value of neon_project.my_app_project.id will be known after its import.
resource "neon_branch" "dev_branch" {
  project_id = neon_project.my_app_project.id
  name       = "feature-x-development"
}

# --- Development Branch Endpoint ---
# Requires project_id and branch_id.
resource "neon_endpoint" "dev_endpoint" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id
}

# --- Application User Role on Development Branch ---
# Requires project_id, branch_id, and name.
resource "neon_role" "app_user" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id
  name       = "application_user"
}

# --- Service Database on Development Branch ---
# Requires project_id, branch_id, name, and owner_name.
resource "neon_database" "service_db" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id
  name       = "service_specific_database"
  owner_name = neon_role.app_user.name
}
```

Here's a breakdown of the minimal HCL and why certain attributes are included:

- **`neon_project.my_app_project`**:
  - This block defines the Terraform resource for your main Neon project.
  - No attributes are strictly required _in the HCL_ for the import command itself, as the project is imported using its unique Neon Project ID. Adding a `name` attribute matching the existing project can aid readability but isn't essential for the import operation.

- **`neon_branch.dev_branch`**:
  - This defines the Terraform resource for your development branch.
  - It requires `project_id` in the HCL to link it to the (to-be-imported) project resource within Terraform.
  - The `name` attribute should also be specified in the HCL, matching the existing branch's name, as it's a key identifier.
  - The branch is imported using its unique Neon Branch ID.

- **`neon_endpoint.dev_endpoint`**:
  - This block defines the Terraform resource for the endpoint on your development branch.
  - It requires both `project_id` and `branch_id` in the HCL to correctly associate it with the imported project and development branch resources within Terraform.
  - Other attributes like `type` (which defaults if unspecified) or autoscaling limits will be read from the live resource during import.
  - The endpoint is imported using its unique Neon Endpoint ID.

- **`neon_role.app_user`**:
  - This defines the Terraform resource for an application user role.
  - The HCL requires `project_id` and `branch_id` to link to the respective imported Terraform resources.
  - The `name` attribute must be specified in the HCL and match the existing role's name.

- **`neon_database.service_db`**:
  - This defines the Terraform resource for a service-specific database.
  - The HCL requires `project_id` and `branch_id` to link to the imported Terraform resources.
  - The `name` attribute must be specified in the HCL and match the existing database's name.
  - The `owner_name` should also be included, linking to the Terraform role resource (for example, `neon_role.app_user.name`) that owns this database.

All other configurable attributes will be populated into Terraform's state file from the live Neon resource during the `terraform import` process. You will then refine your HCL by reviewing the `terraform plan` output.

#### Run the import commands in order

1. **Import the project:**

   ```shell
   terraform import neon_project.my_app_project "actual_project_id_from_neon"
   ```

   You can retrieve the project ID via Neon Console/CLI/API. Learn more: [Manage projects](https://neon.com/docs/manage/projects#project-settings)

   Example output:

   ```shell
   terraform import neon_project.my_app_project damp-recipe-88779456
   ```

   ```text
   neon_project.my_app_project: Importing from ID "damp-recipe-88779456"...
   neon_project.my_app_project: Import prepared!
     Prepared neon_project for import
   neon_project.my_app_project: Refreshing state... [id=damp-recipe-88779456]

   Import successful!

   The resources that were imported are shown above. These resources are now in
   your Terraform state and will henceforth be managed by Terraform.
   ```

2. **Import the development branch:**

   ```shell
   terraform import neon_branch.dev_branch "actual_dev_branch_id_from_neon"
   ```

   You can retrieve the branch ID via Neon Console/CLI/API. Learn more: [Manage branches](https://neon.com/docs/manage/branches)

   The following image shows the branch ID in the Neon Console:
   ![Neon Console Branch ID](https://neon.com/docs/guides/neon-console-branch-id.png)

   Example output:

   ```shell
   terraform import neon_branch.dev_branch br-orange-bonus-a4v00wjl
   ```

   ```text
   neon_branch.dev_branch: Importing from ID "br-orange-bonus-a4v00wjl"...
   neon_branch.dev_branch: Import prepared!
     Prepared neon_branch for import
   neon_branch.dev_branch: Refreshing state... [id=br-orange-bonus-a4v00wjl]

   Import successful!

   The resources that were imported are shown above. These resources are now in
   your Terraform state and will henceforth be managed by Terraform.
   ```

3. **Import the development compute endpoint:**

   ```shell
   terraform import neon_endpoint.dev_endpoint "actual_dev_endpoint_id_from_neon"
   ```

   You can retrieve the endpoint ID via Neon Console/CLI/API. Learn more: [Manage computes](https://neon.com/docs/manage/computes).
   The following image shows the endpoint ID in the Neon Console:
   ![Neon Console Compute Endpoint ID](https://neon.com/docs/guides/neon-console-compute-endpoint-id.png)

   Example output:

   ```shell
   terraform import neon_endpoint.dev_endpoint ep-blue-cell-a4xzunwf
   ```

   ```text
   neon_endpoint.dev_endpoint: Importing from ID "ep-blue-cell-a4xzunwf"...
   neon_endpoint.dev_endpoint: Import prepared!
     Prepared neon_endpoint for import
   neon_endpoint.dev_endpoint: Refreshing state... [id=ep-blue-cell-a4xzunwf]

   Import successful!

   The resources that were imported are shown above. These resources are now in
   your Terraform state and will henceforth be managed by Terraform.
   ```

4. **Import the application user role:**

   ```shell
   terraform import neon_role.app_user "actual_project_id_from_neon/actual_dev_branch_id_from_neon/application_user"
   ```

   > Replace `application_user` with the actual name of the role you want to import.

   Example output:

   ```shell
   terraform import neon_role.app_user "damp-recipe-88779456/br-orange-bonus-a4v00wjl/application_user"
   ```

   ```text
   neon_role.app_user: Importing from ID "damp-recipe-88779456/br-orange-bonus-a4v00wjl/application_user"...
   neon_role.app_user: Import prepared!
     Prepared neon_role for import
   neon_role.app_user: Refreshing state... [id=damp-recipe-88779456/br-orange-bonus-a4v00wjl/application_user]

   Import successful!

   The resources that were imported are shown above. These resources are now in
   your Terraform state and will henceforth be managed by Terraform.
   ```

5. **Import the service database:**

   ```shell
   terraform import neon_database.service_db "actual_project_id_from_neon/actual_dev_branch_id_from_neon/service_specific_database"
   ```

   > Replace `service_specific_database` with the actual name of the database you want to import.

   Example output:

   ```shell
   terraform import neon_database.service_db "damp-recipe-88779456/br-orange-bonus-a4v00wjl/service_specific_database"
   ```

   ```text
   neon_database.service_db: Importing from ID "damp-recipe-88779456/br-orange-bonus-a4v00wjl/service_specific_database"...
   neon_database.service_db: Import prepared!
     Prepared neon_database for import
   neon_database.service_db: Refreshing state... [id=damp-recipe-88779456/br-orange-bonus-a4v00wjl/service_specific_database]

   Import successful!

   The resources that were imported are shown above. These resources are now in
   your Terraform state and will henceforth be managed by Terraform.
   ```

   After importing all resources, your Terraform state file (`terraform.tfstate`) will now contain the imported resources, and you can manage them using Terraform. Follow the [Reconcile your HCL with the imported state](https://neon.com/docs/reference/terraform#reconcile-your-hcl-with-the-imported-state) section to update your HCL files with the attributes that were populated during the import.

### Method 2: Using `import` Blocks (Terraform 1.5.0+)

Terraform version 1.5.0 and later introduced a more declarative way to import existing infrastructure using `import` blocks directly within your configuration files. This method keeps the import definition alongside your resource configuration and makes the import process part of your standard `plan` and `apply` workflow.

**The process with `import` Blocks:**

For each existing Neon resource you want to bring under Terraform management, you'll define two blocks in your `.tf` file:

- A standard `resource "resource_type" "resource_name" {}` block. For the initial import, this block can be minimal. It primarily tells Terraform the type and name of the resource in your configuration.
- An `import {}` block:
  - `to = resource_type.resource_name`: This refers to the Terraform address of the `resource` block you defined above.
  - `id = "neon_specific_id"`: This is the actual ID of the resource as it exists in Neon (for example, project ID, branch ID, or composite ID for roles/databases).

**Example using `import` blocks:**

In this example, we'll import the resources we defined earlier in the [Manage Neon Resources](https://neon.com/docs/reference/terraform#manage-neon-resources) section. This needs a project, a branch, an endpoint, a role, and a database already created in your Neon account. These resources will now be imported into a new Terraform configuration. Let's say we have the following existing Neon resources and their IDs:

- Project `my_app_project` ID: `damp-recipe-88779456`
- Branch `dev_branch` ID: `br-orange-bonus-a4v00wjl`
- Endpoint `dev_endpoint` ID: `ep-blue-cell-a4xzunwf`
- Role `application_user`
- Database `service_specific_database`

You would add the following to your `main.tf`:

```terraform
terraform {
  required_providers {
    neon = {
      source  = "kislerdm/neon"
    }
  }
}

provider "neon" {
  # API key configured via environment variable or directly
}

# --- Project Import ---
import {
  to = neon_project.my_app_project
  id = "damp-recipe-88779456" # Replace with your actual Project ID
}

resource "neon_project" "my_app_project" {
  # Minimal definition for import.
  # After import and plan, you'll populate this with actual/desired attributes.
}

# --- Development Branch Import ---
import {
  to = neon_branch.dev_branch
  id = "br-orange-bonus-a4v00wjl" # Replace with your actual Branch ID
}

resource "neon_branch" "dev_branch" {
  project_id = neon_project.my_app_project.id # Links to the TF resource
  name       = "feature-x-development"        # Should match existing branch name
}

# --- Development Branch Endpoint Import ---
import {
  to = neon_endpoint.dev_endpoint
  id = "ep-blue-cell-a4xzunwf" # Replace with your actual Endpoint ID
}

resource "neon_endpoint" "dev_endpoint" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id      # Links to the TF resource
}

# --- Application User Role on Development Branch Import ---
import {
  to = neon_role.app_user
  # ID format: project_id/branch_id/role_name
  id = "damp-recipe-88779456/br-orange-bonus-a4v00wjl/application_user"
}

resource "neon_role" "app_user" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id
  name       = "application_user"             # Must match existing role name
}

# --- Service Database on Development Branch Import ---
import {
  to = neon_database.service_db
  # ID format: project_id/branch_id/name
  id = "damp-recipe-88779456/br-orange-bonus-a4v00wjl/service_specific_database"
}

resource "neon_database" "service_db" {
  project_id = neon_project.my_app_project.id
  branch_id  = neon_branch.dev_branch.id
  name       = "service_specific_database"    # Must match existing database name
  owner_name = neon_role.app_user.name        # Links to the TF role resource
}
```

**Important:** You need to replace the IDs in the `import` blocks with the actual IDs of your existing Neon resources. The `to` field in each `import` block refers to the corresponding `resource` block defined in your configuration. The above configuration is a minimal example to get you started with the import process.

### Reconcile your HCL with the imported state

After importing your resources using either method, you need to ensure that your HCL configuration accurately reflects the current state of the imported resources. This is an iterative process where you will:

1. **Run `terraform plan`:**

   ```shell
   terraform plan
   ```

2. **Understanding the plan output:**
   The plan might show:
   - **Attributes to be added to your HCL:** Terraform will identify attributes present in the imported state (for example, `pg_version`, `region_id`, `default_endpoint_settings` for a project) that are not yet explicitly in your HCL `resource` blocks.
   - **"Update in-place" actions:** You might see actions like `~ update in-place` for some resources, even if no actual value in Neon is changing. For example, for `neon_endpoint`, you might see `+ branch_id = "your-branch-id"`. This is often because Terraform is now resolving a reference (like `neon_branch.dev_branch.id`) to its concrete value and wants to explicitly set this in its managed configuration. It's a reconciliation step and usually safe to apply.

3. **Update your HCL (`main.tf`):**
   Carefully review the output of `terraform plan`. Your primary goal is to update your HCL `resource` blocks to accurately match the actual, imported state of your resources, or to define your desired state if you intend to make changes. Copy the relevant attributes and their values from the plan output into your HCL.

4. **Repeat `terraform plan`:** After updating your HCL, run `terraform plan` again. Continue this iterative process-reviewing the plan and updating your HCL-until `terraform plan` shows "No changes. Your infrastructure matches the configuration." or only shows changes you intentionally want to make.

This iterative approach ensures your Terraform configuration accurately reflects either the current state or your intended desired state for the imported resources.

### Verify and reconcile

Once all attributes are set correctly, you can run `terraform plan` to see if any changes are needed. You should be seeing output similar to:

```text
No changes. Your infrastructure matches the configuration.

Terraform has compared your real infrastructure against your configuration and found no
differences, so no changes are needed.
```

We can now be sure that the resources are managed by Terraform. You can now proceed to make changes to your infrastructure using Terraform.

## Destroying resources

To remove the resources managed by Terraform:

```shell
terraform destroy
```

Terraform will ask for confirmation before deleting the resources.

## Example application

The following example application demonstrates how to set up Terraform, connect to a database, and perform a Terraform run that inserts data. It covers how to:

- Use Go's `os/exec` package to run Terraform commands
- Write a Go test function to validate Terraform execution
- Execute Terraform commands such as `init`, `plan`, and `apply`

* [Neon Postgres with Terraform and Go](https://github.com/mattmajestic/go-terraform): Run Terraform commands and test Terraform configurations with Go

View the **YouTube tutorial**: [Neon Postgres for Terraform with Go](https://www.youtube.com/watch?v=Pw38lgfbX0s).

--- [Document source](https://neon.com/docs/reference/typescript-sdk.md) ---

> Summary: @neon/sdk is the official TypeScript SDK for the Neon API, a modern, fetch-based replacement for @neondatabase/api-client. It exposes every platform resource through ergonomic namespaces on a single client (neon.projects, neon.branches, neon.postgres, neon.storage, neon.functions, neon.snapshots, neon.auth, and more), with one result contract, typed errors, automatic retries, readiness polling, and auto-pagination built in. A raw 1:1 layer exposes every endpoint and is generated from the Neon OpenAPI spec.

# Neon Management SDK

The official TypeScript SDK for the Neon API. Projects, branches, Postgres, storage, functions, and auth in one typed client.

Last updated: 2026-10-21

**What you will learn:**

- The one result contract every method shares
- Which namespaces and methods exist
- How pagination and async workflows work

**Related resources**

- [Neon API Reference](https://neon.com/docs/reference/api)
- [Migrate from @neondatabase/api-client](https://neon.com/docs/reference/migrate-api-client-to-sdk)
- [Neon CLI](https://neon.com/docs/cli)
- [@neon/tools (agent tools)](https://github.com/neondatabase/neon-pkgs/tree/main/packages/tools)

**Source code**

- [@neon/sdk on npm](https://www.npmjs.com/package/@neon/sdk)
- [OpenAPI spec](https://neon.com/api_spec/release/v2.json)

`@neon/sdk` wraps the entire Neon API in one typed, fetch-based client. You authenticate once, then reach every resource through a namespace on `neon.*`: projects, branches, the Postgres data plane, object storage, functions, and Managed Better Auth. Retries, readiness polling, auto-pagination, and typed errors are built in.

It replaces [`@neondatabase/api-client`](https://www.npmjs.com/package/@neondatabase/api-client), the deprecated Axios-based SDK. New projects should use `@neon/sdk`. See the [migration guide](https://neon.com/docs/reference/migrate-api-client-to-sdk) for method mapping and error-handling changes.

**Building for agents?:**

[`@neon/tools`](https://github.com/neondatabase/neon-pkgs/tree/main/packages/tools) wraps this same client and publishes selected methods as typed agent tools, with adapters for MCP, Mastra, and Eve. Use it when a model drives the operations; use `@neon/sdk` when your own code does.

**Note: Not every endpoint has an ergonomic wrapper**

`createNeonClient` namespaces cover common workflows (projects, branches, Postgres resources, snapshots, and more). They do **not** wrap every Platform API operation. For endpoints without a namespace method, use the [`raw` layer](https://neon.com/docs/reference/typescript-sdk#raw-layer) below or the [Neon API Reference](https://neon.com/docs/reference/api).

```bash
npm install @neon/sdk
```

```ts
import { createNeonClient } from "@neon/sdk";

const neon = createNeonClient({ apiKey: process.env.NEON_API_KEY! });

const { data, error } = await neon.projects.list().all();
if (error) throw error; // typed NeonError
data; // ProjectListItem[]
```

Every method follows this shape: select a namespace, call a method, and receive a `{ data, error }` result. The reference below documents each namespace and method against that single contract.

Each method takes a **single named-parameter object**: the path selectors (`projectId`, `branchId`, and any resource id such as `roleName` or `slug`) and any input or query fields are merged into one flat object, followed by an optional trailing options argument (`{ throwOnError?, waitForReadiness?, signal? }`, omitted from the tables for brevity).

**Important: Named parameters in v5 and later**

`@neon/sdk` v5 replaced positional arguments with a single named-parameter object, and v6 is the current major. For example, `neon.branches.get(projectId, branchId)` is now `neon.branches.get({ projectId, branchId })`. If you're upgrading from v4, update your calls to the object form shown throughout this page. See [Upgrading from v4](https://neon.com/docs/reference/typescript-sdk#upgrading-from-v4).

In the reference tables, the **Returns** column names the resolved resource, the type of `data` on success (or the value returned directly when `throwOnError` is set). A method resolving to `void` has no resource body; [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<T>` is the lazy, auto-paginated list described below.

Nearly every method needs a `projectId`, and branch-scoped methods also need a `branchId`. Get these from `neon.projects.list()` and `neon.branches.list({ projectId })` (or `neon.branches.getDefault({ projectId })` for the default branch), reading `.id` off each result.

## Client configuration

`createNeonClient(config)` accepts:

| Option             | Type                                        | Default                            | Purpose                                                                                                      |
| ------------------ | ------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `apiKey`           | `string \| () => string \| Promise<string>` | required                           | Bearer credential. A function is called per request, for short-lived tokens                                  |
| `throwOnError`     | `boolean`                                   | `false`                            | Throw a `NeonError` instead of returning `{ data, error }`. Overridable per call                             |
| `waitForReadiness` | `boolean`                                   | `false`                            | Poll provisioning operations to completion before resolving. Overridable per call                            |
| `wait`             | `{ pollIntervalMs?, timeoutMs? }`           | `1000` / `300000`                  | Tuning for the readiness poller                                                                              |
| `retries`          | `number`                                    | `2`                                | Automatic retries on safe statuses (423, 429, 503)                                                           |
| `baseUrl`          | `string`                                    | `https://console.neon.tech/api/v2` | Override the API base URL                                                                                    |
| `fetch`            | `typeof fetch`                              | global `fetch`                     | Custom fetch, for proxies, tests, or non-global runtimes                                                     |
| `orgId`            | `string`                                    | none                               | Default organization id, applied to project create/list and as the transfer source org. Overridable per call |

```ts
const neon = createNeonClient({
  apiKey: process.env.NEON_API_KEY!,
  orgId: "org-cool-forest-12345678",
  throwOnError: true,
});
```

## Core model

Four behaviors are shared by every method: the result envelope, typed errors, pagination, and async workflows.

### The result envelope

By default, no `try/catch`. Each call resolves to a discriminated `{ data, error }` envelope; check `error`, then `data` is narrowed:

```ts
const { data, error } = await neon.projects.get({ projectId: "late-frost-12345" });
if (error) return; // error: typed NeonError union
data; // narrowed to Project
```

To throw instead, set `throwOnError` on the client (or per call). The return type narrows to the bare resource:

```ts
const neon = createNeonClient({ apiKey, throwOnError: true });
const project = await neon.projects.get({ projectId: "my-project" }); // Project (throws on error)
const { data } = await neon.projects.get({ projectId: "my-project" }, { throwOnError: false }); // opt out per call
```

### Typed errors

The error channel, and what `throwOnError` throws, is one hierarchy of `Error` subclasses, discriminated on `kind`:

| kind         | Class                | Raised when                                                     |
| ------------ | -------------------- | --------------------------------------------------------------- |
| `api`        | `NeonApiError`       | Non-2xx response; carries `status`, `code`, `requestId`, `body` |
| `not_found`  | `NeonNotFoundError`  | 404 (extends `NeonApiError`)                                    |
| `auth`       | `NeonAuthError`      | 401 or 403                                                      |
| `rate_limit` | `NeonRateLimitError` | 429, after retries                                              |
| `operation`  | `NeonOperationError` | An awaited operation failed; carries `operationId`, `status`    |
| `timeout`    | `NeonTimeoutError`   | A readiness or wait deadline was exceeded                       |
| `network`    | `NeonNetworkError`   | Transport failure, no response received                         |
| `client`     | `NeonError`          | SDK-side error, such as ambiguous connection-string selection   |

```ts
const { error } = await neon.branches.get({ projectId, branchId: "nope" });
if (error?.kind === "not_found") {
  // handle the 404
}
```

### Lazy, auto-paginated lists

Methods labeled Paginated return a [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<T>`; the cursor is managed for you:

```ts
const { data: all } = await neon.projects.list().all(); // every page
const { data: one } = await neon.projects.list().page(); // just the first page
for await (const project of neon.projects.list()) {
  // stream item by item
}
```

### Async workflows

Neon mutations return operations that complete in the background. The client-wide `waitForReadiness` default is `false`. `projects.create`, `branches.create`, and both `createAndConnect` workflows turn polling on for that call.

`create` returns the resource. `createAndConnect` also waits, then returns `{ branch, endpoint, connectionString }` (or `{ project, connectionString }`). The primitive underneath is `neon.operations.waitFor({ operations })`.

Pick one. `create` uses REST field names (`parent_id`). `createAndConnect` uses `{ name?, parentId?, compute? }`. Both fold into the same params object alongside `projectId`.

```ts
const { data: branch, error } = await neon.branches.create({
  projectId,
  name: "preview",
});
if (error) throw error;

const { data, error: connectError } = await neon.branches.createAndConnect({
  projectId,
  name: "preview-uri",
});
if (connectError) throw connectError;
const { connectionString } = data;
```

On any other namespaced mutation, pass `{ waitForReadiness: true }` as the trailing options argument to poll before the call resolves. For raw API calls that return an `operations` array, use [`neon.operations.waitFor`](https://neon.com/docs/reference/typescript-sdk#neonoperations) instead.

## Namespaces

The client groups the API into resource namespaces. Projects and branches are the core surfaces: [`projects`](https://neon.com/docs/reference/typescript-sdk#neonprojects) create, manage, and share projects, and [`branches`](https://neon.com/docs/reference/typescript-sdk#neonbranches) branch a project's data and schema. The Postgres data plane lives under [`postgres`](https://neon.com/docs/reference/typescript-sdk#neonpostgres): compute endpoints, roles, databases, the Data API, and connection strings.

Branch-scoped platform services include [`storage`](https://neon.com/docs/reference/typescript-sdk#neonstorage) (S3-compatible object storage), [`functions`](https://neon.com/docs/reference/typescript-sdk#neonfunctions), [`credentials`](https://neon.com/docs/reference/typescript-sdk#neoncredentials), [`aiGateway`](https://neon.com/docs/reference/typescript-sdk#neonaigateway), and [`auth`](https://neon.com/docs/reference/typescript-sdk#neonauth) (Managed Better Auth, OAuth providers, and users). For data lifecycle and async work, use [`snapshots`](https://neon.com/docs/reference/typescript-sdk#neonsnapshots) for point-in-time snapshots and restore, and [`operations`](https://neon.com/docs/reference/typescript-sdk#neonoperations) to poll asynchronous operations.

Account-level surfaces round out the client: [`consumption`](https://neon.com/docs/reference/typescript-sdk#neonconsumption) for billing metrics, [`apiKeys`](https://neon.com/docs/reference/typescript-sdk#neonapikeys), and [`regions` / `user`](https://neon.com/docs/reference/typescript-sdk#neonregions--user).

## neon.projects

Create, manage, and share Neon projects. One API call per method; `list` is paginated. REST: [Projects API](https://neon.com/docs/reference/api/projects)

| Method                       | Returns                                                                                                    | Arguments                                                                                                                                                                                                                 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list(query?)`               | [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<ProjectListItem>` | `query`: `{ search?, org_id?, limit? }`                                                                                                                                                                                   |
| `get({ projectId })`         | `Project`                                                                                                  |                                                                                                                                                                                                                           |
| `create(input?)`             | `Project`                                                                                                  | Default-branch compute is always attached. No connection string. Readiness polling on by default. `input`: `{ name?, region_id?, pg_version?, org_id?, autoscaling_limit_min_cu?, autoscaling_limit_max_cu?, settings? }` |
| `createAndConnect(input?)`   | `{ project: Project, connectionString: string }`                                                           | Creates, then polls until ready. `input` also accepts `pooled?` (default `true`)                                                                                                                                          |
| `update({ projectId, ... })` | `Project`                                                                                                  | Additional fields: `{ name?, settings? }`                                                                                                                                                                                 |
| `delete({ projectId })`      | `Project`                                                                                                  |                                                                                                                                                                                                                           |
| `recover({ projectId })`     | `Project`                                                                                                  | Recover a soft-deleted project within its retention window                                                                                                                                                                |
| `transfer(input)`            | `void`                                                                                                     | `input`: `{ fromOrgId?, toOrgId, projectIds }` (`fromOrgId` defaults to the client `orgId`)                                                                                                                               |
| `transferFromUser(input)`    | `void`                                                                                                     | `input`: `{ toOrgId, projectIds }`                                                                                                                                                                                        |

```ts
// Provision a project, poll until ready, return a pooled connection string
const { data } = await neon.projects.createAndConnect({
  name: "tenant-42",
  region_id: "aws-us-east-1",
  pooled: true,
});
// data: { project, connectionString }
```

### neon.projects.permissions

Share a project with additional users by email.

| Method                                | Returns               |
| ------------------------------------- | --------------------- |
| `list({ projectId })`                 | `ProjectPermission[]` |
| `grant({ projectId, email })`         | `ProjectPermission`   |
| `revoke({ projectId, permissionId })` | `ProjectPermission`   |

## neon.branches

Branch a project's data and schema. `create` attaches a read-write endpoint by default. REST: [Branches API](https://neon.com/docs/reference/api/branches)

| Method                                            | Returns                                                                                           | Arguments                                                                                                                                                                                                                                                          |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list({ projectId, ...query })`                   | [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<Branch>` | `query`: `{ search?, sort_by?, sort_order?, include_deleted? }`                                                                                                                                                                                                    |
| `get({ projectId, branchId })`                    | `Branch`                                                                                          |                                                                                                                                                                                                                                                                    |
| `create({ projectId, ... })`                      | `Branch`                                                                                          | Read-write compute on by default; `noCompute: true` skips it. No connection string. Readiness polling on by default. Fields: `{ name?, parent_id?, parent_lsn?, parent_timestamp?, protected?, compute?: { minCu?, maxCu?, suspendTimeoutSeconds? }, noCompute? }` |
| `createAndConnect({ projectId, ... })`            | `{ branch: Branch, endpoint: Endpoint, connectionString: string }`                                | Creates, then polls until ready. Fields: `{ name?, parentId?, compute?: { minCu?, maxCu?, suspendTimeoutSeconds? }, pooled? }`                                                                                                                                     |
| `update({ projectId, branchId, ... })`            | `Branch`                                                                                          | Additional fields: `{ name?, protected?, expires_at? }`                                                                                                                                                                                                            |
| `delete({ projectId, branchId })`                 | `void`                                                                                            |                                                                                                                                                                                                                                                                    |
| `getDefault({ projectId })`                       | `Branch`                                                                                          | Resolve the project's default branch by flag, not by name                                                                                                                                                                                                          |
| `setDefault({ projectId, branchId })`             | `Branch`                                                                                          |                                                                                                                                                                                                                                                                    |
| `finalizeRestore({ projectId, branchId, name? })` | `void`                                                                                            | Commit a restore previewed with `snapshots.restore({ finalize: false })`                                                                                                                                                                                           |

Three modes: default compute, schema-only (`noCompute: true`), and create-plus-URI.

```ts
const { data: prod } = await neon.branches.getDefault({ projectId });

await neon.branches.create({
  projectId,
  name: "preview/pr-123",
  parent_id: prod?.id,
});

await neon.branches.create({
  projectId,
  name: "schema-only",
  parent_id: prod?.id,
  noCompute: true,
});

const { data, error } = await neon.branches.createAndConnect({
  projectId,
  name: "preview/pr-123-uri",
  parentId: prod?.id,
  compute: { minCu: 0.25, maxCu: 2 },
});
if (error) throw error;
const { connectionString } = data;
```

## neon.postgres

The Postgres data plane of a branch: compute endpoints, roles, databases, the Data API, and a connection-string helper. REST: [Endpoints](https://neon.com/docs/reference/api/endpoints), [Branches](https://neon.com/docs/reference/api/branches), [Data API](https://neon.com/docs/reference/api/dataapi)

| Method                     | Returns  | Arguments                                                                                                                                                                                                                                                                                    |
| -------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connectionString(params)` | `string` | `params`: `{ projectId, branchId?, endpointId?, databaseName?, roleName?, pooled? }`. Only `projectId` is required; branch defaults to the project default, endpoint to the read-write one, and role/database are auto-selected when the branch has exactly one. `pooled` defaults to `true` |

```ts
const { data: uri } = await neon.postgres.connectionString({ projectId });
```

### neon.postgres.endpoints

Compute endpoints, scoped to a project.

| Method                                   | Returns      | Arguments                                                                                                                                                              |
| ---------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list({ projectId })`                    | `Endpoint[]` |                                                                                                                                                                        |
| `listByBranch({ projectId, branchId })`  | `Endpoint[]` |                                                                                                                                                                        |
| `get({ projectId, endpointId })`         | `Endpoint`   |                                                                                                                                                                        |
| `create({ projectId, ... })`             | `Endpoint`   | Fields: `{ branch_id, type, autoscaling_limit_min_cu?, autoscaling_limit_max_cu?, suspend_timeout_seconds?, provisioner? }`. `type` is `"read_write"` \| `"read_only"` |
| `update({ projectId, endpointId, ... })` | `Endpoint`   |                                                                                                                                                                        |
| `delete({ projectId, endpointId })`      | `void`       |                                                                                                                                                                        |
| `start({ projectId, endpointId })`       | `Endpoint`   |                                                                                                                                                                        |
| `suspend({ projectId, endpointId })`     | `Endpoint`   |                                                                                                                                                                        |
| `restart({ projectId, endpointId })`     | `Endpoint`   |                                                                                                                                                                        |

### neon.postgres.roles

Postgres roles, scoped to a branch.

| Method                                             | Returns  | Arguments                                      |
| -------------------------------------------------- | -------- | ---------------------------------------------- |
| `list({ projectId, branchId })`                    | `Role[]` |                                                |
| `get({ projectId, branchId, roleName })`           | `Role`   |                                                |
| `create({ projectId, branchId, ... })`             | `Role`   | Fields: `{ name, no_login? }`                  |
| `delete({ projectId, branchId, roleName })`        | `void`   |                                                |
| `password({ projectId, branchId, roleName })`      | `string` | Reveals the current password                   |
| `resetPassword({ projectId, branchId, roleName })` | `Role`   | The returned `Role` carries the new `password` |

```ts
// Reveal a role's password, or rotate it
const { data: password } = await neon.postgres.roles.password({ projectId, branchId, roleName: "neondb_owner" });
const { data: role } = await neon.postgres.roles.resetPassword({ projectId, branchId, roleName: "neondb_owner" });
// role.password holds the new secret
```

### neon.postgres.databases

Databases, scoped to a branch.

| Method                                               | Returns      | Arguments                        |
| ---------------------------------------------------- | ------------ | -------------------------------- |
| `list({ projectId, branchId })`                      | `Database[]` |                                  |
| `get({ projectId, branchId, databaseName })`         | `Database`   |                                  |
| `create({ projectId, branchId, ... })`               | `Database`   | Fields: `{ name, owner_name }`   |
| `update({ projectId, branchId, databaseName, ... })` | `Database`   | Fields: `{ name?, owner_name? }` |
| `delete({ projectId, branchId, databaseName })`      | `void`       |                                  |

### neon.postgres.dataApi

The Neon Data API, scoped to a branch and database.

| Method                                               | Returns                 |
| ---------------------------------------------------- | ----------------------- |
| `get({ projectId, branchId, databaseName })`         | `DataApiResponse`       |
| `create({ projectId, branchId, databaseName, ... })` | `DataApiCreateResponse` |
| `update({ projectId, branchId, databaseName, ... })` | `void`                  |
| `delete({ projectId, branchId, databaseName })`      | `void`                  |

## neon.storage

Branch-scoped, S3-compatible object storage. `get` returns whether storage is enabled and the branch's S3 endpoint metadata; buckets and objects are nested underneath. REST: [Storage](https://neon.com/docs/reference/api/storage), [Buckets](https://neon.com/docs/reference/api/buckets)

| Method                         | Returns         |
| ------------------------------ | --------------- |
| `get({ projectId, branchId })` | `BranchStorage` |

### neon.storage.buckets

| Method                                        | Returns    | Arguments                                                                                 |
| --------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------- |
| `list({ projectId, branchId })`               | `Bucket[]` |                                                                                           |
| `create({ projectId, branchId, ... })`        | `Bucket`   | Fields: `{ name, access_level? }`, where `access_level` is `"private"` \| `"public_read"` |
| `delete({ projectId, branchId, bucketName })` | `void`     |                                                                                           |

### neon.storage.objects

| Method                                                         | Returns                     | Arguments                                                                                                    |
| -------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `list({ projectId, branchId, bucketName, ...query })`          | `BucketObjectsListResponse` | `query`: `{ prefix?, delimiter?, cursor?, limit? }`. Returns one page of `folders`, `objects`, `next_cursor` |
| `get({ projectId, branchId, bucketName, objectKey })`          | `Blob`                      | Raw object bytes                                                                                             |
| `delete({ projectId, branchId, bucketName, objectKey })`       | `void`                      |                                                                                                              |
| `deleteByPrefix({ projectId, branchId, bucketName, prefix })`  | `{ deleted: number }`       | `prefix` must end with `/`                                                                                   |
| `presign({ projectId, branchId, bucketName, objectKey, ... })` | `PresignResponse`           | Fields: `{ operation: "upload" \| "download", content_type?, expires_in_seconds? }`                          |

```ts
// Upload via a presigned PUT
const { data: presign } = await neon.storage.objects.presign({
  projectId,
  branchId,
  bucketName: "avatars",
  objectKey: "user-1.png",
  operation: "upload",
  content_type: "image/png",
});
if (!presign) throw new Error("presign failed");

await fetch(presign.url, {
  method: "PUT",
  headers: { ...presign.headers, "Content-Length": String(bytes.length) },
  body: bytes,
});
```

## neon.functions

Branch-scoped Neon Functions. REST: [Functions API](https://neon.com/docs/reference/api/functions)

| Method                                       | Returns                                                                                                 | Arguments                                                                                                                                               |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list({ projectId, branchId, ...query })`    | [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<NeonFunction>` | `query`: `{ limit? }`                                                                                                                                   |
| `get({ projectId, branchId, slug })`         | `NeonFunction`                                                                                          |                                                                                                                                                         |
| `update({ projectId, branchId, slug, ... })` | `NeonFunction`                                                                                          | Fields: `{ name? }`                                                                                                                                     |
| `delete({ projectId, branchId, slug })`      | `void`                                                                                                  |                                                                                                                                                         |
| `deploy({ projectId, branchId, slug, ... })` | `NeonFunctionDeployment`                                                                                | Multipart. Fields: `{ zip?: Blob \| File, runtime?: "nodejs24", environment?: string }`, where `environment` is a JSON-encoded `Record<string, string>` |

```ts
// Deploy a bundled index.mjs inside a zip (first deploy must include the zip)
const zip = await Bun.file("bundle.zip").arrayBuffer();
const { data: deployment } = await neon.functions.deploy({
  projectId,
  branchId,
  slug: "api",
  zip: new File([zip], "bundle.zip", { type: "application/zip" }),
  runtime: "nodejs24",
});
// Poll neon.functions.get until current_deployment.status is "completed"
```

## neon.credentials

Branch-scoped credentials with explicit scopes. Secrets (`api_token`, `s3_secret_access_key`) are returned by `create`, `reveal`, and `rotate`. REST: [Credentials API](https://neon.com/docs/reference/api/credentials)

| Method                                     | Returns                    | Arguments                                                                                                                             |
| ------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `list({ projectId, branchId })`            | `CredentialMeta[]`         |                                                                                                                                       |
| `create({ projectId, branchId, ... })`     | `CreateCredentialResponse` | Fields: `{ name?, scopes, principal_type: "user" }`. Scopes: `storage:read`, `storage:write`, `ai_gateway:invoke`, `functions:invoke` |
| `reveal({ projectId, branchId, tokenId })` | `CredentialSecret`         |                                                                                                                                       |
| `rotate({ projectId, branchId, tokenId })` | `RotateCredentialResponse` |                                                                                                                                       |
| `revoke({ projectId, branchId, tokenId })` | `void`                     |                                                                                                                                       |

## neon.aiGateway

Branch-scoped AI Gateway endpoint metadata. REST: [AI Gateway API](https://neon.com/docs/reference/api/ai-gateway)

| Method                         | Returns           | Arguments                                                |
| ------------------------------ | ----------------- | -------------------------------------------------------- |
| `get({ projectId, branchId })` | `BranchAiGateway` | Returns 404 when AI Gateway is not enabled on the branch |

## neon.snapshots

Point-in-time snapshots, restore, and backup schedules. REST: [Snapshots API](https://neon.com/docs/reference/api/snapshots)

| Method                                      | Returns          | Arguments                                                                          |
| ------------------------------------------- | ---------------- | ---------------------------------------------------------------------------------- |
| `list({ projectId })`                       | `Snapshot[]`     |                                                                                    |
| `create({ projectId, branchId, ... })`      | `Snapshot`       | Fields: `{ name?, timestamp?, lsn?, expiresAt? }`                                  |
| `update({ projectId, snapshotId, ... })`    | `Snapshot`       | Fields: `{ name? }`                                                                |
| `delete({ projectId, snapshotId })`         | `void`           |                                                                                    |
| `restore({ projectId, snapshotId, ... })`   | `Branch`         | Fields: `{ name?, targetBranchId?, finalize?, preview?, keepOnAbort? }`. See below |
| `getSchedule({ projectId, branchId })`      | `BackupSchedule` |                                                                                    |
| `setSchedule({ projectId, branchId, ... })` | `void`           |                                                                                    |

`restore` behaves differently depending on the target:

- As a new branch (no `targetBranchId`), it finalizes by default and is ready to use immediately.
- Onto an existing branch, it does not finalize by default, so you can preview first.
- Transaction-style with `preview`: it restores un-finalized, runs your callback against the restored branch, then commits if the callback returns `true` or aborts (deletes the preview branch) if `false`, unless `keepOnAbort` is set:

```ts
await neon.snapshots.restore({
  projectId,
  snapshotId,
  targetBranchId,
  preview: async (branch) => (await checks(branch)) === "ok", // true commits, false aborts
});
```

## neon.operations

Read operations and wait for them to finish. REST: [Operations API](https://neon.com/docs/reference/api/operations)

| Method                              | Returns                                                                                              | Arguments                                             |
| ----------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `list({ projectId })`               | [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<Operation>` |                                                       |
| `get({ projectId, operationId })`   | `Operation`                                                                                          |                                                       |
| `waitFor({ operations }, options?)` | `void`                                                                                               | `options`: `{ pollIntervalMs?, timeoutMs?, signal? }` |

```ts
// Wait on operations from a raw call (or when readiness polling is off)
const { data } = await raw.createProjectBranch({
  client: neon.client,
  path: { project_id: projectId },
  body: { branch: { name: "wip" } },
});
const { error } = await neon.operations.waitFor({ operations: data!.operations }, { timeoutMs: 120_000 });
```

## neon.auth

Branch-scoped Managed Better Auth. The legacy project-scoped endpoints are deprecated and remain raw-only. REST: [Authentication API](https://neon.com/docs/reference/api/auth)

| Method                                       | Returns                             | Arguments                 |
| -------------------------------------------- | ----------------------------------- | ------------------------- |
| `get({ projectId, branchId })`               | `NeonAuthIntegration`               |                           |
| `create({ projectId, branchId, ... })`       | `NeonAuthCreateIntegrationResponse` | Enable the integration    |
| `disable({ projectId, branchId, ... })`      | `void`                              | Fields: `{ deleteData? }` |
| `updateConfig({ projectId, branchId, ... })` | `NeonAuthConfigResponse`            |                           |

### neon.auth.oauthProviders

OAuth providers (Google, GitHub, and others).

| Method                                             | Returns                   |
| -------------------------------------------------- | ------------------------- |
| `list({ projectId, branchId })`                    | `NeonAuthOauthProvider[]` |
| `add({ projectId, branchId, ... })`                | `NeonAuthOauthProvider`   |
| `update({ projectId, branchId, providerId, ... })` | `NeonAuthOauthProvider`   |
| `delete({ projectId, branchId, providerId })`      | `void`                    |

### neon.auth.trustedDomains

The redirect-URI whitelist.

| Method                                 | Returns                                |
| -------------------------------------- | -------------------------------------- |
| `list({ projectId, branchId })`        | `NeonAuthRedirectUriWhitelistDomain[]` |
| `add({ projectId, branchId, ... })`    | `void`                                 |
| `delete({ projectId, branchId, ... })` | `void`                                 |

### neon.auth.users

| Method                                                   | Returns                          |
| -------------------------------------------------------- | -------------------------------- |
| `create({ projectId, branchId, ... })`                   | `NeonAuthCreateNewUserResponse`  |
| `delete({ projectId, branchId, authUserId })`            | `void`                           |
| `updateRole({ projectId, branchId, authUserId, roles })` | `UpdateNeonAuthUserRoleResponse` |

## neon.consumption

Cursor-paginated billing metrics. Each method takes `{ from, to, granularity, org_id, project_ids? }`, where `from`/`to` are ISO timestamps, `granularity` is `"hourly"` | `"daily"` | `"monthly"`, and `org_id` names the org to report on; `perBranchV2` also requires `project_ids`. `org_id` defaults to the client `orgId` when set. Consumption requires a Scale plan or above. REST: [Consumption API](https://neon.com/docs/reference/api/consumption)

| Method                | Returns                                                                                                                   |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `perProject(query)`   | [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<ConsumptionHistoryPerProject>`   |
| `perProjectV2(query)` | [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<ConsumptionHistoryPerProjectV2>` |
| `perBranchV2(query)`  | [`Paginated`](https://neon.com/docs/reference/typescript-sdk#lazy-auto-paginated-lists)`<ConsumptionHistoryPerBranchV2>`  |

```ts
// Stream every project's daily usage across a range
for await (const project of neon.consumption.perProject({
  from: "2026-06-01T00:00:00Z",
  to: "2026-06-30T00:00:00Z",
  granularity: "daily",
  org_id: "org-...", // the org to report on; consumption requires a Scale plan or above
})) {
  console.log(project);
}
```

## neon.apiKeys

Manage account-level API keys. REST: [API Keys API](https://neon.com/docs/reference/api/api-keys)

| Method                | Returns                     | Arguments                     |
| --------------------- | --------------------------- | ----------------------------- |
| `list()`              | `ApiKeysListResponseItem[]` |                               |
| `create({ keyName })` | `ApiKeyCreateResponse`      | The `key` token is shown once |
| `revoke({ keyId })`   | `ApiKeyRevokeResponse`      |                               |

## neon.regions / neon.user

Active regions and the current account. REST: [Regions](https://neon.com/docs/reference/api/regions), [Users](https://neon.com/docs/reference/api/users)

| Method                 | Returns                   |
| ---------------------- | ------------------------- |
| `regions.list()`       | `RegionResponse[]`        |
| `user.me()`            | `CurrentUserInfoResponse` |
| `user.organizations()` | `Organization[]`          |

## Upgrading from v4

`@neon/sdk` v5 introduced one breaking change that runs through every namespace: resource methods take a **single named-parameter object** instead of positional arguments. Path selectors and input fields are merged into one flat object, followed by the same optional call-options argument.

```ts
// v4 (positional)
await neon.branches.get(projectId, branchId);
await neon.postgres.roles.password(projectId, branchId, "neondb_owner");
await neon.storage.objects.presign(projectId, branchId, "avatars", "user-1.png", {
  operation: "upload",
});

// v5 and later (named parameters)
await neon.branches.get({ projectId, branchId });
await neon.postgres.roles.password({ projectId, branchId, roleName: "neondb_owner" });
await neon.storage.objects.presign({
  projectId,
  branchId,
  bucketName: "avatars",
  objectKey: "user-1.png",
  operation: "upload",
});
```

The `{ pooled }` option on `projects.createAndConnect` and `branches.createAndConnect`, and the `operations` argument to `operations.waitFor`, also move into the params object. `postgres.connectionString` and the `consumption.*` methods were already object-shaped and are unchanged.

v6 is the current major. It extends the triggers surface (`storage_object_created` alongside `schedule`) and does not change the named-parameter shape introduced in v5.

## Raw layer

Anything not wrapped above is available as a raw, 1:1 function. Pass `neon.client` to reuse the client's auth and base URL:

```ts
import { raw } from "@neon/sdk";
// or, for guaranteed tree-shaking: import { getProjectBranchSchema } from "@neon/sdk/raw";

const { data, error } = await raw.getProjectBranchSchema({
  client: neon.client,
  path: { project_id, branch_id },
  query: { db_name: "neondb" }, // db_name is required
});
```

The raw layer speaks the same result contract as the ergonomic client: `{ data, error }` by default, or the bare resource (throwing the typed `NeonError`) with `throwOnError: true`. There is no `responseStyle` switch. Every request, response, and error type is re-exported flat from `@neon/sdk` for `import type { Project, Branch }` and the rest.

## How this SDK is built

The raw layer and all request, response, and error types are generated from the [Neon OpenAPI spec](https://neon.com/api_spec/release/v2.json) using [`@hey-api/openapi-ts`](https://heyapi.dev). The ergonomic namespaces documented above are hand-written on top of that generated layer. When the API adds an endpoint, it appears in the raw layer automatically; the namespace wrappers are added deliberately. The source lives in [`neondatabase/neon-pkgs`](https://github.com/neondatabase/neon-pkgs/tree/main/packages/sdk).

--- [Document source](https://neon.com/docs/security/acceptable-use-policy.md) ---

> Summary: Neon's Acceptable Use Policy defers to the Databricks Acceptable Use Policy, which governs lawful and ethical use of the platform. For Neon-specific rules on resource abuse, unauthorized modifications, and security compliance, see the Neon Security overview.

# Acceptable Use Policy

Last updated: 2026-07-30

Neon is part of the Databricks Platform. Please refer to the [Databricks Acceptable Use Policy](https://www.databricks.com/legal/acceptable-use-policy).

For Neon-specific expectations on abuse of resources, unauthorized modifications, and other security and compliance topics, see [Security overview](https://neon.com/docs/security/security-overview).

--- [Document source](https://neon.com/docs/security/ai-use-in-neon.md) ---

> Summary: Neon integrates AI in two places. The SQL Editor uses Amazon Bedrock to write, optimize, and name SQL queries by sharing only your database schema (no row data). AI chat assistants draw on public sources such as Neon docs and GitHub repos without ingesting PII. Review what data each integration can access before enabling these features.

# AI use in Neon

How Neon integrates AI into its platform

Last updated: 2026-06-05

Neon integrates AI to enhance user experience across different parts of the platform. Below is an overview of where and how AI is used in Neon.

## AI in the Neon SQL Editor

The Neon SQL Editor includes AI-powered features to assist with writing, optimizing, and generating names for SQL queries. To enable these capabilities, we share your database schema with the AI agent, but **no actual data is shared**.

Neon currently uses [Amazon Bedrock](https://aws.amazon.com/bedrock/) as the LLM provider for the Neon SQL Editor. All requests are processed within AWS's secure infrastructure, where other Neon resources are also managed.

For more details, see [AI features in the Neon SQL Editor](https://neon.com/docs/get-started/query-with-neon-sql-editor#ai-features).

## AI chat assistance

Neon provides AI-powered chat assistance across multiple platforms to help users with documentation, troubleshooting, and best practices. These AI chat assistants are developed by third-party companies under contract with Neon.

Neon AI chat assistance is built on publicly available sources, including Neon documentation, public 3rd party vendor documentation, Neon GitHub repositories, the Neon public OpenAPI specification, and other publicly available content. It does not process or incorporate personally identifiable information (PII) or private user data.

For details on where to access Neon AI chat assistants, see [Neon AI chat assistance](https://neon.com/docs/introduction/support#neon-ai-chat-assistance).

## Questions about AI use in Neon?

If you have questions about Neon's AI integrations, please reach out to [Neon Support](https://console.neon.tech/app/projects?modal=support).

--- [Document source](https://neon.com/docs/security/compliance.md) ---

> Summary: Neon holds SOC 2 Type 1 and Type 2, SOC 3, ISO 27001, ISO 27701, GDPR, CCPA, and HIPAA certifications. Each is validated by independent audits or regulatory adherence. HIPAA compliance is available on the Scale plan. Neon isn't PCI DSS compliant. Audit reports for all certifications can be requested through the Neon Trust Center at trust.neon.com.

# Compliance

Last updated: 2026-10-30

At Neon, we prioritize data security and privacy, and we have achieved several key compliances that validate our efforts. We have completed audits for SOC 2 Type 1 and Type 2, SOC 3, ISO 27001, and ISO 27701, and we adhere to GDPR and CCPA regulations.

## SOC 2

We have successfully attained SOC 2 Type 1 and Type 2 compliance. These compliances, validated by independent auditors, confirm that our systems adhere to the American Institute of Certified Public Accountants (AICPA) trust service criteria for security, availability, processing integrity, confidentiality, and privacy.

## SOC 3

The SOC 3 report is a public-facing version of the SOC 2 report, providing assurance to external parties about our system's ability to meet the trust service criteria without disclosing sensitive details. If available on your plan, you can request the report through our [Trust Center](https://trust.neon.com/).

## ISO 27001

ISO 27001 is an internationally recognized standard for information security management systems (ISMS). Our compliance with this standard demonstrates that we follow a systematic and risk-based approach to managing sensitive information, ensuring its security.

## ISO 27701

ISO 27701 extends ISO 27001 to include data privacy requirements, helping organizations establish, implement, and maintain a privacy information management system (PIMS) in accordance with GDPR and other privacy laws.

## GDPR

The General Data Protection Regulation (GDPR) is the European Union's regulation designed to protect individuals' privacy and personal data. Neon adheres to GDPR requirements, ensuring the rights and data privacy of our users across the EU.

## CCPA

The California Consumer Privacy Act (CCPA) grants California residents new rights regarding their personal data. Neon is committed to complying with CCPA, ensuring transparency and control for users over their personal information.

## HIPAA

Neon offers HIPAA compliance as part of our Scale plan, enabling applications that handle Protected Health Information (PHI) to meet compliance requirements. more information and how to get started, refer to our [Neon HIPAA Compliance Guide](https://neon.com/docs/security/hipaa).

A copy of Neon's HIPAA compliance report can be requested through our [Trust Center](https://trust.neon.com/).

## PCI DSS

Neon isn't PCI DSS compliant at this time. Don't store or process payment cardholder data in Neon.

If you need a PCI DSS compliant Postgres database, [Lakebase](https://docs.databricks.com/aws/en/oltp/), Databricks-managed Postgres, supports [PCI DSS](https://docs.databricks.com/aws/en/security/privacy/pci) in supported AWS regions.

## Questions?

To learn more about how we protect your data and uphold the highest standards of security and privacy, please visit our [Trust Center](https://trust.neon.com/), where you can also request and download audit reports.

For privacy-related questions, reach out to [privacy@databricks.com](mailto:privacy@databricks.com).

--- [Document source](https://neon.com/docs/security/hipaa.md) ---

> Summary: HIPAA compliance on Neon is a self-serve feature on the Scale plan. Customers can accept a Business Associate Agreement (BAA) and enable PHI protection at the organization and project level via the Console, API, or CLI. Enabling HIPAA on a project is irreversible and triggers a compute restart. Breach notifications are issued within five business days.

# HIPAA Compliance

Last updated: 2026-10-30

Neon offers HIPAA compliance as a self-serve feature available to customers on the [Scale](https://neon.com/docs/introduction/plans) plan.

**Note:** HIPAA support is currently available at no additional cost. When we begin charging for HIPAA support, a 15% surcharge will be added to your monthly invoice. We'll notify you in advance before this change takes effect.

We take the security and privacy of health information seriously. This guide explains how Neon supports HIPAA compliance and what it means for you as a customer. HIPAA features are available to customers who have accepted our Business Associate Agreement (BAA) through the self-serve enablement process. The BAA is an agreement between you and Databricks, Neon's parent company. It sets out each party's responsibilities for protecting Protected Health Information (PHI).

If anything on this page differs from the BAA, the BAA applies.

## Business Associate Agreement (BAA)

The BAA sets out each party's responsibilities for protecting PHI. Accepting it is part of the self-serve HIPAA enablement process: you review and accept the BAA when you enable HIPAA for your organization. If you need a counter-signed (executed) copy of the BAA for your records, you can request one.

- [Read the BAA](https://neon.com/baa)
- [Request a counter-signed copy of the BAA](https://neon.com/baa/signed)

## What is HIPAA?

HIPAA is a federal law that sets national standards for the protection of health information. It requires businesses handling PHI to implement safeguards to ensure privacy and security.

## Enable HIPAA

HIPAA compliance is available as a self-serve feature on supported plans. To enable HIPAA support, follow these steps:

1. **Enable HIPAA for your Organization**: First, you must enable HIPAA compliance at the organization level and accept the Business Associate Agreement (BAA).
2. **Enable HIPAA for your projects**: After HIPAA is enabled for your organization, you can create HIPAA-compliant projects or enable HIPAA for existing projects.

### Step 1: Enable HIPAA for your Organization

To enable HIPAA compliance for your organization:

1. In the Neon Console, navigate to your **Organization settings**.
2. Locate the **HIPAA support** section.
3. Enable HIPAA compliance for your organization.
4. Read and accept the Business Associate Agreement (BAA).

Once HIPAA is enabled for your organization, you can proceed to enable HIPAA compliance for your projects.

### Step 2: Enable HIPAA for your projects

**Important:** Once HIPAA compliance is enabled on a project, it cannot be disabled. Enabling HIPAA will also restart all computes, temporarily interrupting database connections.

**New project**

For Neon project creation steps, see [Create a project](https://neon.com/docs/manage/projects#create-a-project).

When you create a project, select the **Enable HIPAA compliance for this project** checkbox on the **Create Project** form. This option is available after HIPAA has been enabled for your organization.

![Enable HIPAA option during project creation](https://neon.com/docs/security/enable_hipaa.png)

**Existing project**

To enable HIPAA compliance for an existing Neon project:

1. In the Neon Console, navigate to your project's **Settings** page.
2. Select the **HIPAA compliance** tab.
3. Click **Enable**.

**API**

To create a new HIPAA-compliant Neon project via the Neon API, set `audit_log_level` to `hipaa` in the `project settings` object, as shown below.

```bash
curl --request POST \
     --url https://console.neon.tech/api/v2/projects \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "project": {
    "settings": {
      "hipaa": true
    },
    "pg_version": 18
  }
}
'
```

To enable HIPAA for an existing project, set `hipaa` to `true` in the `project settings` object using the [Update project API](https://neon.com/docs/reference/api/projects/update-project):

```bash
curl --request PATCH \
     --url https://console.neon.tech/api/v2/projects/YOUR_PROJECT_ID \
     --header 'accept: application/json' \
     --header 'authorization: Bearer $NEON_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "project": {
    "settings": {
      "hipaa": true
    }
  }
}
'
```

**Important:** Enabling HIPAA on an existing project will force a restart of all computes to apply the new setting. This will temporarily interrupt database connections.

**CLI**

To create a new HIPAA-compliant Neon project via the [Neon CLI](https://neon.com/docs/cli), use the `--hipaa` option with the `neon projects create` command, as shown below.

```bash
neon projects create --hipaa
```

To enable HIPAA for an existing project, use the `--hipaa` option with the `neon projects update` command, as shown below:

```bash
neon projects update my-project --hipaa
```

**Important:** Enabling HIPAA on an existing project will force a restart of all computes to apply the new setting. This will temporarily interrupt database connections.

If you have trouble enabling HIPAA, [raise a Support request](https://console.neon.tech/app/projects?modal=support).

**Note:** For information about disabling HIPAA compliance, see [Disabling HIPAA](https://neon.com/docs/security/hipaa#disabling-hipaa).

## Key HIPAA terms

- Protected Health Information (PHI): Any identifiable health-related data.
- Covered Entity: Healthcare providers, plans, or clearinghouses that handle PHI.
- Business Associate: A service provider (like Neon) that handles PHI on behalf of a Covered Entity.
- Breach: Unauthorized access, use, or disclosure of PHI.
- Security Rule: Safeguards to protect electronic PHI.
- Privacy Rule: Rules governing how PHI is used and disclosed.

## How Neon protects your data

1. Use and disclosure of PHI
   - We use and disclose PHI only as permitted by the BAA, as required by your agreement with us, or as required by law.
   - Unless you request it, we don't de-identify your PHI or create statistical analyses or reports from aggregated data derived from it.

2. Safeguards
   - We use commercially reasonable and appropriate safeguards and comply, where applicable, with the HIPAA Security Rule.
   - Administrative: Policies and training to ensure compliance.
   - Physical: Secure access controls to data storage areas.
   - Technical: Encryption and access controls for electronic PHI.

3. Incident reporting
   - We report any security breach to you promptly, and no later than five business days after we become aware of it. See [Security incidents](https://neon.com/docs/security/hipaa#security-incidents).

4. Subcontractors and agents
   - Any subcontractors that handle PHI on our behalf are bound by restrictions and conditions that provide the same material level of protection for PHI as the BAA.
   - We provide transparency by listing our subcontractors at [https://neon.com/hipaa-contractors](https://neon.com/hipaa-contractors).

5. Customer responsibilities
   - Customers are responsible for configuring and using Neon in a way that complies with HIPAA.
   - Customers are responsible for obtaining any consents, authorizations, or permissions required under HIPAA before storing PHI in Neon.
   - Customers must ensure that PHI is only stored in data rows as intended for sensitive data and should never be included in metadata, column names, table names, schema descriptions, or system-generated logs such as audit trails, query logs, or error logs.
   - Customers have the responsibility to configure a session timeout.
   - Customers need to avoid including PHI in support tickets or metadata fields.

6. PHI access and amendments
   - Customers can request access to audit logs by [raising a Support request](https://console.neon.tech/app/projects?modal=support).
   - Customers are responsible for the PHI they store in Neon, including any updates or corrections. We make PHI available to you so you can meet individuals' rights of access and amendment.

## Your rights and what to expect

- Transparency: You can request the information you need to provide an individual with an accounting of disclosures of their PHI.
- Security: Our technical safeguards are designed to prevent unauthorized access.
- Data Control: You retain ownership of your data; we are custodians ensuring its protection.

## Availability of audit events

Audit events may not be logged if database endpoints experience exceptionally heavy load, as we prioritize database availability over capturing log events.

## Logged events

Neon maintains a comprehensive audit trail to support HIPAA compliance. This includes the following categories of logged events:

1. [Neon Console and API audit logs](https://neon.com/docs/security/hipaa#neon-console-and-api-audit-logs): Captures user actions in the Neon Console and via the Neon API.
2. [Postgres audit logs](https://neon.com/docs/security/hipaa#postgres-audit-logs-pgaudit): Logged using the [pgAudit](https://www.pgaudit.org/) extension (`pgaudit`) for Postgres.

> Self-serve access to HIPAA audit logs is currently not supported. Access to audit logs can be requested by [raising a Support request](https://console.neon.tech/app/projects?modal=support).

### Neon console and API audit logs

Neon logs operations performed via the Neon Console interface and the Neon API. Examples of logged operations may include these, among other operations:

- **Project management**: creating, deleting, listing projects
- **Branch management**: creating, deleting, listing branches
- **Compute management**: starting and stopping of compute instances
- **Database and role management**: creating or deleting databases and roles

To protect sensitive information, Neon filters data in audit logs using the following approach:

- Sensitive fields (such as `connection_uri` and `password`) are excluded from logs wherever possible.
- `GET` requests: Only query parameters are logged; response payloads are not recorded.
- Mutation requests (`PATCH`, `PUT`, `POST`, `DELETE`): Request and response bodies are logged with sensitive fields redacted.

#### Neon console and API audit log example

The following example shows how a `List project branches` operation is captured in Neon's audit logs. The table provides a description of the log record's parts.

**Audit log record:**

```ini
fb7c2e2f-cb09-4405-b543-dbe1b88614b6 2025-05-25 10:18:45.340 +0000 `{ "changes": [], "sync_id": 57949 }` e640c32c-0387-4fc2-8ca5-f823f7ebc4b6 GET `{}` /projects/misty-breeze-49601234/branches a92b3088-7f92-4871-bf91-0aac64edc4b6 b8c58a4b-0a33-4d54-987e-4155e95a64b6 2025-05-24 15:42:39.088 +0000 misty-breeze-49601234 keycloak 200 `{}` ListProjectBranches 0
```

**Field descriptions:**

| **Field position** | **Example value**                        | **Description**                                          |
| ------------------ | ---------------------------------------- | -------------------------------------------------------- |
| 1                  | fb7c2e2f-cb09-4405-b543-dbe1b88614b6     | Unique ID for the raw log event                          |
| 2                  | 2025-05-25 10:18:45.340 +0000            | Timestamp when Airbyte extracted the record              |
| 3                  | `{ "changes": [], "sync_id": 57949 }`    | Metadata from the ingestion tool                         |
| 4                  | e640c32c-0387-4fc2-8ca5-f823f7ebc4b6     | Unique identifier for the API event                      |
| 5                  | GET                                      | HTTP method used in the request                          |
| 6                  | `{}`                                     | Request body payload (if present)                        |
| 7                  |                                          | Reserved for future metadata fields (empty in this case) |
| 8                  | /projects/misty-breeze-49601234/branches | URL path of the API call                                 |
| 9                  | a92b3088-7f92-4871-bf91-0aac64edc4b6     | Internal ID for the response object                      |
| 10                 | b8c58a4b-0a33-4d54-987e-4155e95a64b6     | Internal ID representing the auth/session context        |
| 11                 | 2025-05-24 15:42:39.088 +0000            | Actual time when the API call was made                   |
| 12                 | misty-breeze-49601234                    | Project identifier targeted by the API call              |
| 13                 | keycloak                                 | Authentication mechanism used                            |
| 14                 | 200                                      | HTTP status code of the response                         |
| 15                 | `{}`                                     | Resource identifiers returned (if any)                   |
| 16                 | ListProjectBranches                      | Operation name associated with the endpoint              |
| 17                 | 0                                        | Internal sync batch identifier                           |

### Postgres audit logs (pgAudit)

When HIPAA audit logging is enabled for a Neon project, Neon configures pgAudit with the following settings by default:

| Setting                      | Value        | Description                                                                                          |
| ---------------------------- | ------------ | ---------------------------------------------------------------------------------------------------- |
| `pgaudit.log`                | `all, -misc` | Logs all classes of SQL statements except low-risk miscellaneous commands.                           |
| `pgaudit.log_parameter`      | `off`        | Parameters passed to SQL statements are not logged to avoid capturing sensitive values.              |
| `pgaudit.log_catalog`        | `off`        | Queries on system catalog tables (for example, `pg_catalog`) are excluded from logs to reduce noise. |
| `pgaudit.log_statement`      | `on`         | The full SQL statement text is included in the log.                                                  |
| `pgaudit.log_relation`       | `off`        | Only a single log entry is generated per statement, not per table or view.                           |
| `pgaudit.log_statement_once` | `off`        | SQL statements are logged with every entry, not just once per session.                               |

#### What does `pgaudit.log = 'all, -misc'` include?

This configuration enables logging for all major classes of SQL activity while excluding less relevant statements in the `misc` category. Specifically, it includes:

- **READ**: `SELECT` statements and `COPY` commands that read from tables or views.
- **WRITE**: `INSERT`, `UPDATE`, `DELETE`, `TRUNCATE`, and `COPY` commands that write to tables.
- **FUNCTION**: Function calls and `DO` blocks.
- **ROLE**: Role and permission changes, including `GRANT`, `REVOKE`, `CREATE ROLE`, `ALTER ROLE`, and `DROP ROLE`.
- **DDL**: Schema and object changes like `CREATE TABLE`, `ALTER INDEX`, `DROP VIEW` (all DDL operations not included in the `ROLE` class).
- **MISC_SET**: Miscellaneous `SET` commands, for example `SET ROLE`.

Excluded:

- **MISC**: Low-impact commands such as `DISCARD`, `FETCH`, `CHECKPOINT`, `VACUUM`, and `SET`.

**Note:** In some cases, audit logs may include SQL statements that contain plain-text passwords (for example, in a `CREATE ROLE ... LOGIN PASSWORD` command). This is due to limitations in the Postgres `pgaudit` extension, which may log full statements without redacting sensitive values.

This behavior is a known issue. We recommend avoiding the inclusion of raw credentials in SQL statements where possible.

For more details, see the [pgAudit documentation](https://github.com/pgaudit/pgaudit).

#### Audit log storage and forwarding

- Logs are written using the standard [PostgreSQL logging facility](https://www.postgresql.org/docs/current/runtime-config-logging.html).
- Logs are sent to a dedicated Neon audit collector endpoint and securely stored.
- Each log entry includes metadata such as the timestamp of the activity, the Neon compute ID (`endpoint_id`), Neon project ID (`project_id`), the Postgres role, the database accessed, and the method of access (for example, `neon-internal-sql-editor`), etc. See the following log record example and field descriptions:

#### Postgres audit log example

The following example shows how a simple SQL command (`CREATE SCHEMA IF NOT EXISTS healthcare`) is captured in Neon's audit logs. The table provides a description of the log record's parts.

**Query:**

`CREATE SCHEMA IF NOT EXISTS healthcare;`

**Audit log record:**

```ini
2025-05-05 20:23:01.277	 <134>May 6 00:23:01 vm-compute-shy-waterfall-w2cn1o3t-b6vmn young-recipe-29421150/ep-calm-da 2025-05-06 00:23:01.277 GMT,neondb_owner,neondb,1405,10.6.42.155:13702,68195665.57d,1,CREATE SCHEMA, 2025-05-06 00:23:01 GMT,16/2,767,00000,SESSION,1,1,DDL,CREATE SCHEMA,,,CREATE SCHEMA IF NOT EXISTS healthcare,<not logged>,,,,,,,,,neon-internal-sql-editor
```

**Field descriptions:**

| **Field position** | **Example value**                       | **Description**                                                                        |
| ------------------ | --------------------------------------- | -------------------------------------------------------------------------------------- |
| 1                  | 2025-05-05 20:23:01.277                 | Timestamp when the log was received by the logging system.                             |
| 2                  | `<134>`                                 | Syslog priority code (facility + severity).                                            |
| 3                  | May 6 00:23:01                          | Syslog timestamp (when the message was generated on the source host).                  |
| 4                  | vm-compute-shy-waterfall-w2cn1o3t-b6vmn | Hostname or compute instance where the event occurred.                                 |
| 5                  | young-recipe-29421150/ep-calm-da        | Project and endpoint name in the format `<project>/<endpoint>`.                        |
| 6                  | 2025-05-06 00:23:01.277 GMT             | Timestamp of the database event in UTC.                                                |
| 7                  | neondb\_owner                           | Database role (user) that executed the statement.                                      |
| 8                  | neondb                                  | Database name.                                                                         |
| 9                  | 1405                                    | Process ID (PID) of the PostgreSQL backend.                                            |
| 10                 | 10.6.42.155:13702                       | Client IP address and port that issued the query.                                      |
| 11                 | 68195665.57d                            | PostgreSQL virtual transaction ID.                                                     |
| 12                 | 1                                       | Backend process number.                                                                |
| 13                 | CREATE SCHEMA                           | Command tag.                                                                           |
| 14                 | 2025-05-06 00:23:01 GMT                 | Statement start timestamp.                                                             |
| 15                 | 16/2                                    | Log sequence number (LSN).                                                             |
| 16                 | 767                                     | Statement duration in milliseconds.                                                    |
| 17                 | 00000                                   | SQLSTATE error code (00000 = success).                                                 |
| 18                 | SESSION                                 | Log message level.                                                                     |
| 19                 | 1                                       | Session ID.                                                                            |
| 20                 | 1                                       | Subsession or transaction ID.                                                          |
| 21                 | DDL                                     | Statement type: Data Definition Language.                                              |
| 22                 | CREATE SCHEMA                           | Statement tag/type.                                                                    |
| 23–26              | _(empty)_                               | Reserved/unused fields.                                                                |
| 27                 | CREATE SCHEMA IF NOT EXISTS healthcare  | Full SQL text of the statement.                                                        |
| 28                 | `<not logged>`                          | Parameter values (redacted or disabled by settings like `pgaudit.log_parameter`).      |
| 29–35              | _(empty)_                               | Reserved/unused fields.                                                                |
| 36                 | neon-internal-sql-editor                | Application name or source of the query (for example, SQL Editor in the Neon Console). |

#### Extension configuration

The `pgaudit` extension is preloaded on HIPAA-enabled Neon projects. For extension version information, see [Supported Postgres extensions](https://neon.com/docs/extensions/pg-extensions).

## Non-HIPAA-compliant features

The following feature is not currently HIPAA-compliant and should not be used in projects containing HIPAA-protected data:

- [Data API](https://neon.com/docs/data-api/get-started) – Not covered under Neon's HIPAA compliance.

## Security incidents

If a security breach occurs, Neon will:

1. Notify you promptly, and no later than five business days after becoming aware of it.
2. Follow up with the information required by HIPAA (45 C.F.R. § 164.410) without unreasonable delay, and no later than 60 calendar days after discovering the breach.
3. Mitigate any harmful effects of the breach caused by Neon, to the extent commercially practicable.

You won't receive separate notifications for unsuccessful attempts at unauthorized access or interference with Neon systems. The BAA serves as notice of these.

## Disabling HIPAA

Once HIPAA compliance is enabled for a Neon project, it cannot be disabled.

### Delete a HIPAA-compliant project

You can delete a HIPAA-compliant project using the same self-serve flow as any other Neon project: in the Console (**Settings** → **General** → **Delete project**), via the [Neon API](https://neon.com/docs/manage/projects#delete-a-project-with-the-api), or with the [Neon CLI](https://neon.com/docs/cli/projects#delete). Deleting a project is permanent and removes all computes, branches, databases, and roles in that project.

**Important:** Before deleting a HIPAA project, export any audit logs or data you may need.

For step-by-step instructions, see [Delete a project](https://neon.com/docs/manage/projects#delete-a-project).

### Disable HIPAA for your organization

If you want to disable HIPAA for your Neon organization entirely, you need to [submit a support request](https://console.neon.tech/app/projects?modal=support). This can only be done after all HIPAA-enabled projects have been deleted.

## Frequently asked questions

### Can I request Neon to delete my PHI?

You can delete PHI yourself at any time, for example by deleting the data or the project. When the BAA ends, Neon returns or destroys your PHI. If that isn't feasible, the BAA's protections continue to apply to any PHI Neon retains.

### How does Neon ensure compliance with HIPAA?

We conduct regular internal audits and provide training to our employees to ensure adherence to HIPAA requirements.

### What should I do if I suspect a data breach?

Contact our security team immediately at [security@databricks.com](mailto:security@databricks.com).

## Contact information

For any questions regarding our HIPAA compliance or to report an issue, please [raise a Support request](https://console.neon.tech/app/projects?modal=support).

_This guide provides a high-level overview of Neon's HIPAA compliance efforts. For more details, please refer to your Business Associate Agreement (BAA) or contact us directly via our [support channels](https://neon.com/docs/introduction/support)._

--- [Document source](https://neon.com/docs/security/security-overview.md) ---

> Summary: Neon enforces SSL/TLS encryption (verify-full mode), 60-bit entropy passwords, AES-256 data-at-rest encryption, IP allowlists (Scale plan), and AWS PrivateLink private networking. A connection proxy blocks unauthorized login attempts. The page also covers GitHub secret scanning, protected branches, vulnerability management, and the HackerOne bug bounty program.

# Security overview

Last updated: 2026-11-05

At Neon, security is our highest priority. We are committed to implementing best practices and earning the trust of our users. A key aspect of earning this trust is by ensuring that every touchpoint in our system, from connections, to data storage, to our internal processes, adheres to the highest security standards.

## Secure connections

Neon supports a variety of protections related to database connections:

- **SSL/TLS encryption**: Neon requires that all connections use SSL/TLS encryption to ensure that data sent over the Internet cannot be viewed or manipulated by third parties.

  Neon supports the `verify-full` SSL mode for client connections, which is the strictest SSL mode provided by PostgreSQL. When set to `verify-full`, a PostgreSQL client verifies that the server's certificate is issued by a trusted certificate authority (CA), and that the server host name matches the name stored in the certificate. This helps prevent man-in-the-middle attacks. For information about configuring `verify-full` SSL mode for your connections, see [Connect securely](https://neon.com/docs/connect/connect-securely).

- **Secure password enforcement**: Neon requires a 60-bit entropy password for all Postgres roles. This degree of entropy ensures that passwords have a high level of randomness. Assuming a perfect distribution of choices for every bit of entropy, a password with 60 bits of entropy has 2^60 (or about 1.15 quintillion) possible combinations, which makes it computationally infeasible for attackers to guess the password through brute-force methods. For Postgres roles created via the Neon Console, API, and CLI, passwords are generated with 60-bit entropy. For Postgres roles created via SQL, user-defined passwords are validated at creation time to ensure 60-bit entropy.

- **The Neon Proxy**: Neon places a proxy in front of your database, which helps safeguard it from unauthorized login attempts. For example, in Postgres, each login attempt spawns a new process, which can pose a security risk. The [Neon Proxy](https://neon.com/docs/reference/glossary#neon-proxy) mitigates this by monitoring connection attempts and preventing misuse. The Neon Proxy also allows us to authenticate connections before they ever reach your Postgres database.

- **IP Allow**: For additional connection security, the Neon Scale plan offers [IP allowlist support](https://neon.com/docs/security/security-overview#ip-allowlist-support), which lets you to limit access to trusted IPs.

- **Private Networking**: This feature enables connections to your Neon databases via AWS PrivateLink, bypassing the open internet entirely. See [Private Networking](https://neon.com/docs/guides/neon-private-networking).

## IP allowlist support

Neon's [IP Allow](https://neon.com/docs/introduction/ip-allow) feature ensures that only trusted IP addresses can connect to the project where your database resides, preventing unauthorized access and helping maintain overall data security. You can limit access to individual IP addresses, IP ranges, or IP addresses and ranges defined with [CIDR notation](https://neon.com/docs/reference/glossary#cidr-notation). To learn more, see [Configure IP Allow](https://neon.com/docs/manage/projects#configure-ip-allow).

## Protected branches

You can designate any branch as a "protected branch", which implements a series of protections:

- Protected branches cannot be deleted.
- Protected branches cannot be [reset](https://neon.com/docs/manage/branches#reset-a-branch-from-parent).
- Projects with protected branches cannot be deleted.
- Computes associated with a protected branch cannot be deleted.
- New passwords are automatically generated for Postgres roles on branches created from protected branches.
- With additional configuration steps, you can apply IP Allow restrictions to protected branches only.
- Protected branches are not [archived](https://neon.com/docs/guides/branch-archiving) due to inactivity.

The protected branches feature is available on all Neon paid plans. Typically, the protected branch status is given to a branch or branches that hold production data or sensitive data. For information about how to configure a protected branch, refer to our [Protected branches guide](https://neon.com/docs/guides/protected-branches).

## Private Networking

The [Neon Private Networking](https://neon.com/docs/guides/neon-private-networking) feature enables secure connections to your Neon databases via [AWS PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html), bypassing the open internet for enhanced security. This feature is available to Neon [Organization](https://neon.com/docs/manage/organizations) accounts. It's not accessible to Personal Neon accounts.

## Data-at-rest encryption

Data-at-rest encryption is a method of storing inactive data that converts plaintext data into a coded form or cipher text, making it unreadable without an encryption key. Neon stores inactive data in [NVMe SSD volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ssd-instance-store.html#nvme-ssd-volumes). The data on NVMe instance storage is encrypted using an `AES-256` block cipher implemented in a hardware module on the instance.

## Secure data centers

Neon's infrastructure is hosted and managed within either Amazon's or Azure's secure data centers, depending on the cloud service provider you select when setting up your project.

Amazon's secure data centers backed by [AWS Cloud Security](https://aws.amazon.com/security/). Amazon continually manages risk and undergoes recurring assessments to ensure compliance with industry standards. For information about AWS data center compliance programs, refer to [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/).

The Microsoft cloud data centers that power Azure focus on high reliability, operational excellence, cost-effectiveness, and a trustworthy online experience for Microsoft customers and partners worldwide. Microsoft regularly tests data center security through both internal and third-party audits. To learn more, refer to [Microsoft's Datacenter security overview](https://learn.microsoft.com/en-us/compliance/assurance/assurance-datacenter-security).

## Compliance-relevant security measures

At Neon, we implement robust technical controls to secure customer and sensitive data in alignment with SOC2, ISO27001, ISO27701 standards and GDPR and CCPA regulations. To learn more about these standards and regulations, see [Compliance](https://neon.com/docs/security/compliance).

All systems are hosted on AWS and Azure, where we have implemented specific security measures to protect data. Below is a detailed breakdown of these compliance-relevant security measures for access control, encryption, network security, event logging, vulnerability management, backups, data deletion and retention:

- **Customer and Sensitive Data Encryption (AWS KMS and Azure Key Vault)**

  All customer and sensitive data is encrypted using AES-256 encryption at rest. For data in transit, encryption is enforced using TLS 1.2/1.3 protocols across various services. Encryption keys are managed using AWS Key Management Service (KMS) and Azure Key Vault with key rotation policies in place. Only services and users with specific IAM roles can access the decryption keys, and all access is logged via AWS CloudTrail and Azure Monitor for auditing and compliance purposes.

- **Fine-Grained Access Control via IAM**

  Access to PII and customer or sensitive data is controlled through AWS Identity and Access Management (IAM) policies and Microsoft Entra ID permissions. Broad access is limited to the infrastructure and security teams, while other roles operate under least-privilege principles. When additional access needed, access requests to production systems are received via Teleport, where all sessions are recorded. Only managers and on-call personnel are permitted to access production or approve production access requests.

  Additionally, all infrastructure is managed through Terraform, ensuring that any changes to access controls or resources are fully auditable and version-controlled. Regular access reviews and audits are conducted to verify that access rights remain aligned with security best practices.

- **Data Segmentation and Isolation Using VPCs and Security Groups**

  In our AWS and Azure environments, workloads are segmented using Virtual Private Clouds (VPCs) and Azure Virtual Networks (VNets) to separate sensitive data environments from other systems. We control network access between services by using security groups, Network Access Control Lists (NACLs) and Azure Network Security Groups (NSGs), restricting access to only the necessary traffic. This ensures a clear separation of environments, minimizing the risk of unauthorized access or lateral movement between services.

- **Event-Based Data Anomaly Detection via AWS GuardDuty and Logz.io**

  Customer data access attempts and other anomalies are continuously monitored via Logzio integration on both infrastructures. All alerts are ingested into our Logz.io SIEM for centralized logging, analysis, and correlation with other security data. This allows our Security Operations Center (SOC) to quickly detect, investigate, and respond to potential security threats.

- **Data Access Logging and Auditing (AWS CloudTrail & Logz.io)**

  All data access actions, including those involving sensitive operations, are logged using AWS CloudTrail and Azure Monitor, and forwarded to Logz.io for centralized logging and analysis. This provides full traceability of who accessed which resources, when, and from where. Logs are secured and retained for audit purposes, while any anomalies or suspicious activity trigger real-time alerts through our Security Operations Center (SOC) for immediate investigation and response.

- **PII Backup, Retention, and Deletion Policies with S3 Versioning**

  Customer data backups are stored in cloud object storage, such as Amazon S3 and Azure Blob Storage, with versioning enabled, allowing recovery from accidental deletions or modifications. Data is encrypted using server-side encryption (SSE) and is retained for 30 days. Data deletion is followed to ensure compliance with SOC2, ISO, GDPR and CCPA requirements, including data subject requests.

- **Vulnerability Management with Orca and Oligo**

  Our vulnerability management program, integrated with Orca and Oligo, continuously scans all AWS and Azure environments for security issues, including misconfigurations, unpatched software, and exposed credentials. We use tagging to classify certain data types, enabling focused monitoring and scanning based on the sensitivity of the data. Automated alerts allow us to address vulnerabilities before they pose a risk to PII or other sensitive information. The vulnerabilities are remediated according to the defined SLAs to reduce the risk.

- **Annual Audits and Continuous Penetration Testing**

  We undergo annual audits for SOC2 and ISO by two independent firms to verify the integrity and security of our systems. In addition, bi-annual penetration tests with Hackerone are performed, with results feeding into our vulnerability management program. The vulnerabilities are remediated according to the defined SLAs to reduce the risk.

To learn more about how we protect your data and uphold the highest standards of security and privacy, please visit our [Trust Center](https://trust.neon.com/).

## GitHub secret scanning

Neon is a [GitHub Secret Scanning Partner](https://docs.github.com/en/code-security/secret-scanning/secret-scanning-partner-program). If a Neon database credential or API key is detected in a GitHub repository, GitHub alerts Neon through an automated system. This system validates the credential and notifies our security team.

By integrating with GitHub Secret Scanning, Neon helps users quickly identify and mitigate exposed credentials, reducing the risk of unauthorized access.

To avoid leaking secrets, follow these security best practices:

- Use environment variables instead of hardcoding credentials.
- Store sensitive information in secret management tools like AWS Secrets Manager or HashiCorp Vault.
- Regularly rotate database credentials and API keys.

If you have questions about this integration or need help securing your credentials, reach out on our [Discord server](https://neon.com/discord) or [submit a support ticket](https://neon.com/docs/introduction/support).

## Rotate credentials

Rotate your database credentials regularly, and immediately if one is exposed. A Neon connection string is built from a role and its password, so you rotate it by resetting the role's password. See [Reset a password](https://neon.com/docs/manage/roles#reset-a-password) for the Console, CLI, API, and SQL methods.

After you reset a password, the old one stops working on the next connection. Copy the new connection string from the **Connect** modal (**Connect** in the Console nav) and roll it out everywhere it is stored, including deployment platform environment variables, CI/CD secrets, secret managers, and local `.env` files, before clients reconnect.

### Rotate after a leak or breach

If a credential is exposed, for example through a leaked `.env` file, a compromised deployment target, or a stolen device, rotate every affected credential rather than just one:

1. Reset the password for every role that can log in, starting with the default role (often `neondb_owner`). Roles are branch-scoped, so reset the role on every branch where it can log in.
2. Roll the new connection strings out to every secret store, then watch your application logs for `password authentication failed` errors, which flag a location you missed.
3. Revoke any exposed Neon API keys and create new ones. See [Manage API keys](https://neon.com/docs/manage/api-keys).
4. Tighten your [IP allowlist](https://neon.com/docs/security/security-overview#ip-allowlist-support) to limit which addresses can connect.
5. Audit your roles and remove any you do not recognize.

Neon has no single command to rotate everything at once. To rotate many roles, list every project, branch, and role, then loop the [reset-password API](https://neon.com/docs/manage/roles#reset-a-password).

### Rotate without downtime

Resetting a password cuts over all consumers at once. To rotate gradually, create a parallel role, grant it the access the old role had, and migrate consumers one service at a time, since both connection strings keep working during the migration. Reset the old role's password at the end to invalidate it. In most projects the original role owns database objects and cannot be dropped while it does, so resetting its password is what closes the leak. To remove the role later, [reassign ownership](https://www.postgresql.org/docs/current/sql-reassign-owned.html) of its objects, then [delete the role](https://neon.com/docs/manage/roles#delete-a-role).

## Abuse of resources

Users must not engage in activities that result in unintended or non-permitted use of Neon resources, or that disrupt or degrade the service for other users. Prohibited activities include, but are not limited to, intentional or unintentional denial-of-service attacks, exceeding [rate limits](https://neon.com/docs/reference/api#rate-limiting), using Neon for distributed computing projects, using Neon as general-purpose file storage, or other usage that falls outside the intended resource usage and limits of the applicable [Neon plan](https://neon.com/docs/introduction/plans).

## Unauthorized modifications

Tampering with Neon's infrastructure, configurations, or any restricted settings is prohibited. Doing so will be considered a violation of our terms. This includes attempts to alter Neon-managed serverless configurations or storage settings without proper authorization.

## Security reporting

Neon adheres to the [securitytxt.org](https://securitytxt.org/) standard for transparent and efficient security reporting. For details on how to report potential vulnerabilities, please visit our [Security reporting](https://neon.com/docs/security/security-reporting) page or refer to our [security.txt](https://neon.com/security.txt) file.

Neon also has a [public bug bounty program with HackerOne](https://neon.com/docs/security/security-reporting#bug-bounty-program-with-hackerone).

## Questions about our security measures?

If you have any questions about our security protocols or would like a deeper dive into any aspect, our team is here to help. Explore our documentation in the [Neon Trust Center](https://trust.neon.com/), or [submit a support ticket](https://neon.com/docs/introduction/support).

--- [Document source](https://neon.com/docs/security/security-reporting.md) ---

> Summary: Neon accepts vulnerability reports through its HackerOne bug bounty program or at security@databricks.com. Neon commits to responding within three business days with strict confidentiality and public credit in security.txt. Report suspected vulnerabilities here, review responsible disclosure rules, or submit through Neon's bug bounty program on HackerOne.

# Security reporting

Last updated: 2026-10-30

We have established the following security reporting procedure to address security issues quickly.

**Important:** If you have a security concern or believe you have found a vulnerability in any part of our infrastructure, please contact us at [security@databricks.com](mailto:security@databricks.com).

## Our commitment to solving security issues

- We will respond to your report within three business days with an evaluation and expected resolution date.
- We will handle your report with strict confidentiality and not share any personal details with third parties without your permission.
- We will keep you informed of the progress towards resolving the problem.
- After the report has been resolved, we will credit the finding to you in our public `security.txt` document, unless you prefer to stay anonymous.
- If we need to access proprietary information or personal data stored in Neon to investigate or respond to a security report, we shall act in good faith and in compliance with applicable confidentiality, personal data protection, and other obligations.

We strive to resolve all problems quickly and publicize any discoveries after their resolution.

## Bug bounty program with HackerOne

Neon offers a public bug bounty program. If you discover a vulnerability, report it through our [bug bounty program](https://hackerone.com/neon_bbp).

## How to disclose vulnerabilities

Neon pays close attention to the proper security of its information and communication systems. Despite these efforts, it is not possible to entirely exclude the existence of security vulnerabilities.

If you identify a security vulnerability, please proceed as follows under the principle of responsible disclosure:

- Report the security vulnerability to Neon by contacting us at [security@databricks.com](mailto:security@databricks.com). Provide as much information about the security vulnerability as possible.
- Do not exploit the security vulnerability; for example, by using it to breach data, change the data of third parties, or deliberately disrupt the availability of the service.
- All activities relating to the discovery of the security vulnerability should be performed within the framework of the law.
- Do not inform any third parties about the security vulnerability. All communication regarding the security vulnerability will be coordinated by Neon and our partners.
- If the above conditions are respected, Neon will not take any legal steps against the party that reported the security vulnerability.
- In the event of a non-anonymous report, Neon will inform the party that submitted the report of the steps it intends to take and the progress toward closing the security vulnerability.

--- [Document source](https://neon.com/docs/serverless/serverless-driver-configuration.md) ---

> Summary: Configuration reference for the Neon serverless driver (`@neondatabase/serverless`): `arrayMode`, `fullResults`, and `fetchOptions` for the HTTP `neon()` function; individual and function-valued connection parameters (1.2.0+); `transaction()` options (`isolationLevel`, `readOnly`, `deferrable`); setting JWT claims for Row-Level Security in a transaction; and `neonConfig` options for `Pool` and `Client`. For installation and basic usage, see the Neon serverless driver page.

# Neon serverless driver configuration

Result formats, fetch options, connection parameters, and transaction options for the Neon serverless driver

Last updated: 2026-10-05

This page covers configuration options for the Neon serverless driver. The driver works with its defaults, so all of these options are optional. For installation, a quick start, and basic HTTP and WebSocket usage, see [Neon serverless driver](https://neon.com/docs/serverless/serverless-driver).

## Query result and fetch options

The examples in this section assume a query function created with `neon()`:

```javascript
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);
const postId = 12;
```

By default, the query function returns only the rows resulting from the provided SQL query, and it returns them as an array of objects where the keys are column names. For example:

```javascript
const rows = await sql`SELECT * FROM posts WHERE id = ${postId}`;
// -> [{ id: 12, title: "My post", ... }]
```

You can customize the return format using the configuration options `fullResults` and `arrayMode`. These options are available both on the `neon(...)` function and on the query function it returns.

- `arrayMode: boolean`, `false` by default

  The default `arrayMode` value is `false`. When it is true, rows are returned as an array of arrays instead of an array of objects:

  ```javascript
  const sql = neon(process.env.DATABASE_URL, { arrayMode: true });
  const rows = await sql`SELECT * FROM posts WHERE id = ${postId}`;
  // -> [[12, "My post", ...]]
  ```

  Or, with the same effect when using query():

  ```javascript
  const sql = neon(process.env.DATABASE_URL);
  const rows = await sql.query('SELECT * FROM posts WHERE id = $1', [postId], { arrayMode: true });
  // -> [[12, "My post", ...]]
  ```

- `fullResults: boolean`

  The default `fullResults` value is `false`. When it is `true`, additional metadata is returned alongside the result rows, which are then found in the `rows` property of the return value. The metadata matches what would be returned by `node-postgres`:

  ```javascript
  const sql = neon(process.env.DATABASE_URL, { fullResults: true });
  const results = await sql`SELECT * FROM posts WHERE id = ${postId}`;
  /* -> {
    rows: [{ id: 12, title: "My post", ... }],
    fields: [
      { name: "id", dataTypeID: 23, ... },
      { name: "title", dataTypeID: 25, ... },
      ...
    ],
    rowCount: 1,
    rowAsArray: false,
    command: "SELECT"
  }
  */
  ```

  Or, with the same effect when using query():

  ```javascript
  const sql = neon(process.env.DATABASE_URL);
  const results = await sql.query('SELECT * FROM posts WHERE id = $1', [postId], {
    fullResults: true,
  });
  // -> { ... same as above ... }
  ```

- `fetchOptions: Record<string, any>`

  The `fetchOptions` option can also be passed to either `neon(...)` or the `query` function. This option takes an object that is merged with the options to the `fetch` call.

  For example, to increase the priority of every database `fetch` request:

  ```javascript
  import { neon } from '@neondatabase/serverless';
  const sql = neon(process.env.DATABASE_URL, { fetchOptions: { priority: 'high' } });
  const rows = await sql`SELECT * FROM posts WHERE id = ${postId}`;
  ```

  Or to implement a `fetch` timeout:

  ```javascript
  import { neon } from '@neondatabase/serverless';
  const sql = neon(process.env.DATABASE_URL);
  const abortController = new AbortController();
  const timeout = setTimeout(() => abortController.abort('timed out'), 10000);
  const rows = await sql.query('SELECT * FROM posts WHERE id = $1', [postId], {
    fetchOptions: { signal: abortController.signal },
  }); // throws an error if no result received within 10s
  clearTimeout(timeout);
  ```

For additional details, see [Options and configuration](https://github.com/neondatabase/serverless/blob/main/CONFIG.md#options-and-configuration).

## Connection parameters

The usual way to configure the connection is a full connection string:

```javascript
const sql = neon(process.env.DATABASE_URL);
```

You can also pass individual connection parameters in the options object. The supported parameters are `user` (or `username`), `password`, `host` (or `hostname`), `port`, `database`, and `connectionString`. They can supplement a connection string, override parts of it, or fully replace it:

```javascript
// No connection string: pass the parts individually
const sql = neon({ user, password, host, database });

// Override part of a connection string
const sql = neon(process.env.DATABASE_URL, { host: readReplicaHost });
```

Each parameter can be a string (or a number, for `port`), or a **sync or async function that's resolved on every query**. Resolving on every query is useful for short-lived credentials that must be fetched fresh, such as an OIDC token used as the password:

```javascript
const sql = neon(DATABASE_URL_WITHOUT_PASSWORD, {
  password: async () => await getAccessToken(),
});
```

The same connection parameters are accepted by the `query` and `transaction` functions.

The `Client` and `Pool` classes also accept a sync or async `password` function. To combine one with a connection string, use the exported `parseIntoClientConfig` helper:

```javascript
import { Pool, parseIntoClientConfig } from '@neondatabase/serverless';

const pool = new Pool({
  ...parseIntoClientConfig(process.env.DATABASE_URL),
  password: async () => await getAccessToken(),
});
```

**Note:** Connection parameters, password functions with `pipelineConnect` enabled (the default), and `parseIntoClientConfig` require `@neondatabase/serverless` 1.2.0 or later.

## Transaction options

For how to run queries with `transaction()`, see [Issue multiple queries with the transaction() function](https://neon.com/docs/serverless/serverless-driver#issue-multiple-queries-with-the-transaction-function).

The optional second argument to `transaction()`, `options`, has the same keys as the options to the ordinary query function (`arrayMode`, `fullResults` and `fetchOptions`) plus three additional keys that concern the transaction configuration. These transaction-related keys are: `isolationLevel`, `readOnly` and `deferrable`.

Pass query and transaction options as the second argument of `transaction()`, not on the individual queries inside it. The TypeScript types don't accept options on individual queries, and `fetchOptions` can't apply per query because the whole transaction is sent as a single `fetch` request. For example:

```javascript
const [rows] = await sql.transaction([sql`SELECT now()`], { arrayMode: true });
```

- `isolationLevel`

  This option selects a Postgres [transaction isolation mode](https://www.postgresql.org/docs/current/transaction-iso.html). If present, it must be one of `ReadUncommitted`, `ReadCommitted`, `RepeatableRead`, or `Serializable`.

- `readOnly`

  If `true`, this option ensures that a `READ ONLY` transaction is used to execute the queries passed. This is a boolean option. The default value is `false`.

- `deferrable`

  If `true` (and if `readOnly` is also `true`, and `isolationLevel` is `Serializable`), this option ensures that a `DEFERRABLE` transaction is used to execute the queries passed. This is a boolean option. The default value is `false`.

For additional details, see [transaction(...) function](https://github.com/neondatabase/serverless/blob/main/CONFIG.md#transaction-function).

## Using transactions with JWT self-verification

When using Row-Level Security (RLS) to secure backend SQL with the Neon serverless driver, you may need to set JWT claims within a transaction context. Use this for custom JWT verification flows in backend APIs, where you want to ensure user-specific access to rows according to RLS policies.

Here's an example of how to use the `transaction()` function with self-verified JWT claims:

```javascript
import { neon } from '@neondatabase/serverless';

// Example JWT verification function, typically in a separate auth utilitiy file (implement according to your auth provider)
async function verifyJWT(jwtToken, jwksURL) {
  // Your JWT verification logic here
  // This should return the decoded payload
  return { payload: { sub: 'user123', email: 'user@example.com' } };
}

const sql = neon(process.env.DATABASE_URL);

// Get JWT token from request headers or context
const jwtToken = req.headers.authorization?.replace('Bearer ', '');
const jwksURL = process.env.JWKS_URL; // Your JWKS endpoint

// Verify the JWT and extract claims
const { payload } = await verifyJWT(jwtToken, jwksURL);
const claims = JSON.stringify(payload);

// Use transaction to set JWT claims and query data
const [, my_table] = await sql.transaction([
  sql`SELECT set_config('request.jwt.claims', ${claims}, true)`,
  sql`SELECT * FROM my_table`,
]);
```

**Important:** When using JWT self-verification with RLS, ensure your database connection string uses a role that does **not** have the `BYPASSRLS` attribute. Avoid using the `neondb_owner` role in your connection string, as it bypasses Row-Level Security policies.

This pattern allows you to:

- Verify JWTs using your own authentication logic
- Set the JWT claims in the database session context
- Access JWT claims in your RLS policies
- Execute multiple queries within a single transaction while maintaining the auth context

## neonConfig options

The `neonConfig` object configures `Pool` and `Client` connections over WebSockets, for example to supply a WebSocket constructor on Node.js 21 and earlier, or to change pipelining and proxy settings. For the full list, see [neonConfig configuration](https://github.com/neondatabase/serverless/blob/main/CONFIG.md#neonconfig-configuration) in the driver repository.

--- [Document source](https://neon.com/docs/serverless/serverless-driver.md) ---

> Summary: The Neon serverless driver (`@neondatabase/serverless`) is a JavaScript and TypeScript Postgres driver that queries Neon over HTTP or WebSockets instead of TCP, so it works in serverless and edge runtimes. Use the `neon()` function over HTTP by default, for single queries and non-interactive transactions. Use `Pool` or `Client` over WebSockets only for interactive transactions, sessions, or node-postgres (`pg`) compatibility. Includes a runnable quick start, how to load `DATABASE_URL`, and troubleshooting for common errors. Optional settings are on the Neon serverless driver configuration page. Install with `npm install @neondatabase/serverless`; TypeScript types are bundled.

# Neon serverless driver

Connect to Neon from serverless environments over HTTP or WebSockets

Last updated: 2026-10-05

Pre-built prompt for setting up the Neon serverless driver (JS/TS) [View prompt](https://neon.com/prompts/serverless-driver-prompt.md)

The [Neon serverless driver](https://github.com/neondatabase/serverless) is a low-latency Postgres driver for JavaScript and TypeScript that allows you to query data from serverless and edge environments over **HTTP** or **WebSockets** in place of TCP. The driver's low-latency capability is due to [message pipelining and other optimizations](https://neon.com/blog/quicker-serverless-postgres).

Use the driver over **HTTP** by default. The `neon()` function sends each query as an HTTP [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) request, which is the fastest option for single queries and for [multiple queries in one non-interactive transaction](https://neon.com/docs/serverless/serverless-driver#issue-multiple-queries-with-the-transaction-function). See [Use the driver over HTTP](https://neon.com/docs/serverless/serverless-driver#use-the-driver-over-http).

Switch to **WebSockets**, with the `Pool` or `Client` constructors, only if you need interactive transactions, sessions, or compatibility with [node-postgres](https://node-postgres.com/) (the `pg` package). See [Use the driver over WebSockets](https://neon.com/docs/serverless/serverless-driver#use-the-driver-over-websockets).

The driver works with its defaults. For optional settings such as result formats, `fetch` timeouts, connection parameters, and transaction options, see [Neon serverless driver configuration](https://neon.com/docs/serverless/serverless-driver-configuration).

**Tip: AI assistant support**

Neon's [Agent Skills](https://neon.com/docs/ai/agent-skills) give AI coding assistants context about the Neon Serverless Driver, general connection advice, and other Neon features. Install them for more accurate code suggestions.

## Install the Neon serverless driver

You can install the driver with your preferred JavaScript package manager. For example:

```shell
npm install @neondatabase/serverless
```

The driver includes TypeScript types (the equivalent of `@types/pg`). No additional installation is required. In Node.js, the driver requires version 19 or later.

**Important: Install from npm, not JSR**

The driver is no longer published to the [JavaScript Registry (JSR)](https://jsr.io/@neon/serverless). The JSR package, `@neon/serverless`, stays at version 1.0.1 and won't get new releases. This only affects JSR: the driver itself is actively maintained on npm as `@neondatabase/serverless`.

If you installed the JSR package (for example, with `deno add jsr:@neon/serverless`), switch to the npm package:

```shell
deno add npm:@neondatabase/serverless
```

Then change your imports from `@neon/serverless` to `@neondatabase/serverless`.

## Configure your Neon database connection

You can obtain a connection string for your database by clicking the **Connect** button in the Console nav. Your Neon connection string will look something like this:

```shell
DATABASE_URL=postgresql://[user]:[password]@[neon_hostname]/[dbname]
```

The examples that follow assume that your database connection string is assigned to a `DATABASE_URL` variable in your application's environment file (for example, `.env`). Frameworks such as Next.js load `.env` automatically. For a plain Node.js script, load it with `node --env-file=.env index.js`, or add `import 'dotenv/config';` at the top of the script after installing the `dotenv` package. If `DATABASE_URL` isn't loaded, you'll see [this error](https://neon.com/docs/serverless/serverless-driver#wrong-url-scheme-or-missing-user-host-or-database).

## Quick start

This complete example creates a table, writes rows over HTTP, and reads them back over WebSockets. Save it as `index.js` in a project with `"type": "module"` in its `package.json`, then run it with `node --env-file=.env index.js`.

```javascript filename="index.js"
import { neon, Pool } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL);

// HTTP: one-shot queries
await sql`CREATE TABLE IF NOT EXISTS posts (id serial PRIMARY KEY, title text NOT NULL)`;
await sql`INSERT INTO posts (title) VALUES (${'First post'})`;

// HTTP: multiple queries in one non-interactive transaction
await sql.transaction([
  sql`INSERT INTO posts (title) VALUES (${'Second post'})`,
  sql`INSERT INTO posts (title) VALUES (${'Third post'})`,
]);

// WebSockets: a node-postgres-compatible Pool (Node.js 22 and later have a built-in WebSocket)
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const { rows } = await pool.query('SELECT * FROM posts ORDER BY id');
console.log(rows);
await pool.end();
```

On the first run, the output is:

```text
[
  { id: 1, title: 'First post' },
  { id: 2, title: 'Second post' },
  { id: 3, title: 'Third post' }
]
```

The sections that follow explain each part in more detail.

## Use the driver over HTTP

The Neon serverless driver uses the [neon](https://github.com/neondatabase/serverless/blob/main/CONFIG.md#neon-function) function for queries over HTTP. The function returns a query function that can only be used as a template function for improved safety against SQL injection vulnerabilities.

For example:

```javascript
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);
const id = 1;
const useArchive = false;

// Safe and convenient template function usage
const rows = await sql`SELECT * FROM posts WHERE id = ${id}`;

// For manually parameterized queries, use the query() function
const queryRows = await sql.query('SELECT * FROM posts WHERE id = $1', [id]);

// For interpolating trusted strings (like column or table names), use the unsafe() function
const tableName = useArchive ? 'archived_posts' : 'posts'; // known-safe string values
const unsafeRows = await sql`SELECT * FROM ${sql.unsafe(tableName)} WHERE id = ${id}`;

// Alternatively, use template literals for known-safe values
const table = useArchive ? sql`archived_posts` : sql`posts`;
const templateRows = await sql`SELECT * FROM ${table} WHERE id = ${id}`;
```

SQL template queries are fully composable, including those with parameters:

```javascript
const title = 'My post';
const limit = 1;
const whereClause = sql`WHERE title = ${title}`;
const limitClause = sql`LIMIT ${limit}`;

// Parameters are numbered appropriately at query time
const rows = await sql`SELECT * FROM posts ${whereClause} ${limitClause}`;
```

You can use raw SQL queries or tools such as [Drizzle-ORM](https://orm.drizzle.team/docs/quick-postgresql/neon), [kysely](https://github.com/kysely-org/kysely), [Zapatos](https://jawj.github.io/zapatos/), and others for type safety.

**Node.js**

```javascript
import { neon } from '@neondatabase/serverless';

const sql = neon(process.env.DATABASE_URL);
const postId = 12;

await sql`INSERT INTO posts (id, title) VALUES (${postId}, ${'My post'})`;
const posts = await sql`SELECT * FROM posts WHERE id = ${postId}`;
// or using query() for parameterized queries:
// const posts = await sql.query('SELECT * FROM posts WHERE id = $1', [postId]);
// `posts` is now [{ id: 12, title: 'My post' }]
```

**Drizzle-ORM**

```typescript
import { neon } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-http';
import { pgTable, serial, text } from 'drizzle-orm/pg-core';
import { eq } from 'drizzle-orm';

// Schema (usually in its own file, such as schema.ts)
export const posts = pgTable('posts', {
  id: serial('id').primaryKey(),
  title: text('title').notNull(),
});

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle(sql);

const postId = 12;
const [onePost] = await db.select().from(posts).where(eq(posts.id, postId));
```

**Next.js on Vercel**

```typescript
// app/api/posts/route.ts (Next.js App Router route handler)
import { neon } from '@neondatabase/serverless';

export async function GET(request: Request) {
  const postId = new URL(request.url).searchParams.get('id');
  const sql = neon(process.env.DATABASE_URL!);
  const posts = await sql`SELECT * FROM posts WHERE id = ${postId}`;
  return Response.json(posts);
}
```

**Vercel Functions**

```typescript
// api/posts.ts (Vercel Function, no framework)
import { neon } from '@neondatabase/serverless';

export async function GET(request: Request) {
  const postId = new URL(request.url).searchParams.get('id');
  const sql = neon(process.env.DATABASE_URL!);
  const posts = await sql`SELECT * FROM posts WHERE id = ${postId}`;
  return Response.json(posts);
}
```

**Note:** The maximum request size and response size for queries over HTTP is 64 MB.

To change the result format, set `fetch` options such as a timeout, or pass individual connection parameters, see [Neon serverless driver configuration](https://neon.com/docs/serverless/serverless-driver-configuration).

### Issue multiple queries with the transaction() function

The `transaction(queriesOrFn, options)` function is exposed as a property on the query function. It allows multiple queries to be executed within a single, non-interactive transaction.

The first argument to `transaction()`, `queriesOrFn`, is either an array of queries or a non-async function that receives a query function as its argument and returns an array of queries.

The array-of-queries case looks like this:

```javascript
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);
const showLatestN = 10;

const [posts, tags] = await sql.transaction(
  [sql`SELECT * FROM posts ORDER BY posted_at DESC LIMIT ${showLatestN}`, sql`SELECT * FROM tags`],
  {
    isolationLevel: 'RepeatableRead',
    readOnly: true,
  }
);
```

Or as an example of the function case:

```javascript
const [authors, tags] = await neon(process.env.DATABASE_URL).transaction((txn) => [
  txn`SELECT * FROM authors`,
  txn`SELECT * FROM tags`,
]);
```

To set the isolation level, read-only mode, or result format for a transaction, see [Transaction options](https://neon.com/docs/serverless/serverless-driver-configuration#transaction-options). To set JWT claims for Row-Level Security inside a transaction, see [Using transactions with JWT self-verification](https://neon.com/docs/serverless/serverless-driver-configuration#using-transactions-with-jwt-self-verification).

## Use the driver over WebSockets

The Neon serverless driver supports the [Pool and Client](https://github.com/neondatabase/serverless?tab=readme-ov-file#pool-and-client) constructors for querying over WebSockets.

The `Pool` and `Client` constructors, provide session and transaction support, as well as `node-postgres` compatibility. You can find the API guide for the `Pool` and `Client` constructors in the [node-postgres](https://node-postgres.com/) documentation.

Consider using the driver with `Pool` or `Client` in the following scenarios:

- You already use `node-postgres` in your code base and would like to migrate to using `@neondatabase/serverless`.
- You are writing a new code base and want to use a package that expects a `node-postgres-compatible` driver.
- Your backend service uses sessions / interactive transactions with multiple queries per connection.

You can use the Neon serverless driver in the same way you would use `node-postgres` with `Pool` and `Client`. Where you usually import `pg`, import `@neondatabase/serverless` instead.

**Node.js**

```javascript
import { Pool } from '@neondatabase/serverless';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const postId = 12;
const { rows } = await pool.query('SELECT * FROM posts WHERE id = $1', [postId]);
await pool.end();
```

**Prisma**

```typescript
// Prisma ORM 7, with the default `prisma-client` generator (output = "../generated/prisma")
// and a `Post` model in prisma/schema.prisma
import 'dotenv/config';
import { PrismaNeon } from '@prisma/adapter-neon';
import { PrismaClient } from './generated/prisma/client';

const adapter = new PrismaNeon({ connectionString: process.env.DATABASE_URL });
const prisma = new PrismaClient({ adapter });

const posts = await prisma.post.findMany();
```

**Drizzle-ORM**

```typescript
import { Pool } from '@neondatabase/serverless';
import { drizzle } from 'drizzle-orm/neon-serverless';
import { pgTable, serial, text } from 'drizzle-orm/pg-core';
import { eq } from 'drizzle-orm';

// Schema (usually in its own file, such as schema.ts)
export const posts = pgTable('posts', {
  id: serial('id').primaryKey(),
  title: text('title').notNull(),
});

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const db = drizzle(pool);

const postId = 12;
const [onePost] = await db.select().from(posts).where(eq(posts.id, postId));
await pool.end();
```

**Next.js on Vercel**

```typescript
// app/api/posts/route.ts (Next.js App Router route handler)
import { Pool } from '@neondatabase/serverless';
import { after } from 'next/server';

export async function GET(request: Request) {
  const postId = new URL(request.url).searchParams.get('id');
  if (!postId) return new Response('Missing id', { status: 400 });

  // Create, use, and close the pool inside the request handler
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const { rows } = await pool.query('SELECT * FROM posts WHERE id = $1', [postId]);
  after(() => pool.end());

  if (!rows[0]) return new Response('Not found', { status: 404 });
  return Response.json(rows[0]);
}
```

**Vercel Functions**

```typescript
// api/posts.ts (Vercel Function, no framework)
import { Pool } from '@neondatabase/serverless';
import { waitUntil } from '@vercel/functions';

export async function GET(request: Request) {
  const postId = new URL(request.url).searchParams.get('id');
  if (!postId) return new Response('Missing id', { status: 400 });

  // Create, use, and close the pool inside the request handler
  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
  const { rows } = await pool.query('SELECT * FROM posts WHERE id = $1', [postId]);
  waitUntil(pool.end());

  if (!rows[0]) return new Response('Not found', { status: 404 });
  return Response.json(rows[0]);
}
```

For a complete Prisma setup, including `schema.prisma`, `prisma.config.ts`, and generating the client, see [Connect from Prisma to Neon](https://neon.com/docs/guides/prisma).

### Pool and Client usage notes

- Node.js 21 and earlier, and some other environments, have no built-in WebSocket support. In these cases, supply a WebSocket constructor function, such as the one from the [ws](https://www.npmjs.com/package/ws) package. Node.js 22 and later include a built-in `WebSocket`, so this step is optional.

  ```javascript
  import { Pool, neonConfig } from '@neondatabase/serverless';
  import ws from 'ws';
  neonConfig.webSocketConstructor = ws;
  ```

- In edge runtimes such as Cloudflare Workers and the Vercel Edge runtime, WebSocket connections can't outlive a single request. That means `Pool` or `Client` objects must be connected, used and closed within a single request handler. Don't create them outside a request handler; don't create them in one handler and try to reuse them in another; and to avoid exhausting available connections, don't forget to close them.

For examples that demonstrate these points, see [Pool and Client](https://github.com/neondatabase/serverless?tab=readme-ov-file#pool-and-client).

### Advanced configuration options

For `Pool` and `Client` settings such as a custom WebSocket constructor, pipelining, and proxy options, see [neonConfig options](https://neon.com/docs/serverless/serverless-driver-configuration#neonconfig-options).

## Configuration options

The driver works with its defaults, so these options are optional. They're documented on the [Neon serverless driver configuration](https://neon.com/docs/serverless/serverless-driver-configuration) page:

- [Query result and fetch options](https://neon.com/docs/serverless/serverless-driver-configuration#query-result-and-fetch-options): return rows as arrays or with full metadata, and pass `fetch` options such as a timeout
- [Connection parameters](https://neon.com/docs/serverless/serverless-driver-configuration#connection-parameters): pass the user, password, host, or database individually, including as functions for short-lived credentials
- [Transaction options](https://neon.com/docs/serverless/serverless-driver-configuration#transaction-options): set the isolation level, read-only mode, and deferrable mode
- [Using transactions with JWT self-verification](https://neon.com/docs/serverless/serverless-driver-configuration#using-transactions-with-jwt-self-verification): set JWT claims for Row-Level Security inside a transaction
- [neonConfig options](https://neon.com/docs/serverless/serverless-driver-configuration#neonconfig-options): configure `Pool` and `Client` WebSocket connections

## Developing locally with the Neon serverless driver

The Neon serverless driver enables you to query data over **HTTP** or **WebSockets** instead of TCP, even though Postgres does not natively support these connection methods. To use the Neon serverless driver locally, you must run a local instance of Neon's proxy and configure it to connect to your local Postgres database.

For a step-by-step guide to setting up a local environment, refer to this community guide: [Local Development with Neon](https://neon.com/guides/local-development-with-neon). The guide demonstrates how to use a [community-developed Docker Compose file](https://github.com/TimoWilhelm/local-neon-http-proxy) to configure a local Postgres database and a Neon proxy service. This setup allows connections over both WebSockets and HTTP.

## Handling transient connection drops

Like any cloud database service, Neon may occasionally experience brief connection drops during maintenance, updates, or network interruptions. When using the Neon serverless driver, especially over HTTP, you should implement retry logic to handle these transient errors gracefully.

Here's a minimal retry example using the `async-retry` library with the HTTP driver:

```javascript
import { neon } from '@neondatabase/serverless';
import retry from 'async-retry';

const sql = neon(process.env.DATABASE_URL);
const userId = 1;

const result = await retry(
  async () => {
    return await sql`SELECT * FROM users WHERE id = ${userId}`;
  },
  {
    retries: 5,
    factor: 2,
    minTimeout: 1000,
    randomize: true,
  }
);
```

## Troubleshooting

### This function can now be called only as a tagged-template function

```text
This function can now be called only as a tagged-template function: sql`SELECT ${value}`, not sql("SELECT $1", [value], options). For a conventional function call with value placeholders ($1, $2, etc.), use sql.query("SELECT $1", [value], options).
```

Since version 1.0.0, the query function returned by `neon()` only works as a tagged template, which protects against SQL injection. Code written for earlier versions that calls it as a conventional function, such as `sql('SELECT * FROM posts WHERE id = $1', [postId])`, throws this error. Use a tagged template or `sql.query()` instead:

```javascript
const rows = await sql`SELECT * FROM posts WHERE id = ${postId}`;
// or
const rows = await sql.query('SELECT * FROM posts WHERE id = $1', [postId]);
```

For details, see the [1.0.0 release notes](https://github.com/neondatabase/serverless/blob/main/CHANGELOG.md#100-2025-03-25).

### Wrong URL scheme or missing user, host or database

```text
Wrong URL scheme or missing user, host or database in connection parameters
```

```text
Database connection string provided to neon() is not a valid URL (connection string: )
```

The connection string passed to `neon()` is missing or malformed. This usually means the `DATABASE_URL` environment variable isn't set where your code runs, so `neon()` receives `undefined` or an empty string. Check that the variable is defined in that environment (for example, in your hosting platform's environment settings), and that its value is a full connection string that starts with `postgresql://`.

### No database host or connection string was set

```text
No database host or connection string was set, and key parameters have default values (host: localhost, user: ..., db: ..., password: null). Is an environment variable missing?
```

This is the `Pool` and `Client` version of the previous error. The `connectionString` you passed is `undefined`, usually because `DATABASE_URL` isn't set in that environment.

### All attempts to open a WebSocket to connect to the database failed

```text
All attempts to open a WebSocket to connect to the database failed. Please refer to https://github.com/neondatabase/serverless/blob/main/CONFIG.md#websocketconstructor-typeof-websocket--undefined.
```

`Pool` and `Client` connect over WebSockets, and your runtime has no built-in `WebSocket`. This happens in Node.js 21 and earlier. Upgrade to Node.js 22 or later, or supply a WebSocket constructor, as described in [Pool and Client usage notes](https://neon.com/docs/serverless/serverless-driver#pool-and-client-usage-notes). If you only need one-shot queries or non-interactive transactions, you can use the [HTTP](https://neon.com/docs/serverless/serverless-driver#use-the-driver-over-http) `neon()` function instead, which doesn't need WebSockets.

### Security warning in the browser console

```text
WARNING: Running SQL directly from the browser can have security implications.
```

The driver prints this warning when it connects from a web browser, because running SQL from client-side code can expose your database to misuse. If you've assessed the risks (for example, you're prototyping, or your data is protected by [Row-Level Security](https://neon.com/docs/guides/row-level-security)), you can suppress the warning:

```javascript
// HTTP
const sql = neon(process.env.DATABASE_URL, { disableWarningInBrowsers: true });

// WebSockets
neonConfig.disableWarningInBrowsers = true;
```

## Neon serverless driver GitHub repository and changelog

The GitHub repository and [changelog](https://github.com/neondatabase/serverless/blob/main/CHANGELOG.md) for the Neon serverless driver are found [here](https://github.com/neondatabase/serverless).

## References

- [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
- [node-postgres](https://node-postgres.com/)
- [Drizzle-ORM](https://orm.drizzle.team/docs/quick-postgresql/neon)
- [Schema migration with Lakebase Postgres and Drizzle ORM](https://neon.com/docs/guides/drizzle-migrations)
- [kysely](https://github.com/kysely-org/kysely)
- [Zapatos](https://jawj.github.io/zapatos/)
- [Vercel Functions](https://vercel.com/docs/functions)
- [Cloudflare Workers](https://developers.cloudflare.com/workers/)
- [Use Neon with Cloudflare Workers](https://neon.com/docs/guides/cloudflare-workers)

--- [Document source](https://neon.com/docs/storage/authentication.md) ---

> Summary: Neon Object Storage uses Neon credentials with storage:read and storage:write scopes. Each credential maps to an S3 Access Key ID and Secret Access Key. Credentials are scoped to a branch and valid for that branch and all its descendants.

# Object storage authentication

How Neon credentials map to S3 access keys

Last updated: 2026-10-21

Neon Object Storage uses the same scoped-credential system as [AI Gateway](https://neon.com/docs/ai-gateway/authentication): one credential API mints branch-scoped tokens that differ by scope (Object Storage uses `storage:read` and `storage:write`). You create a scoped credential via the Neon API, and it maps directly to the S3 Access Key ID and Secret Access Key your SDK expects. No AWS account or IAM configuration required.

## Creating a credential

An object storage credential requires at minimum one of:

- [`storage:read`](https://neon.com/docs/storage/authentication#read-vs-write-scopes): allows GetObject, HeadObject, ListObjects, and ListBuckets
- [`storage:write`](https://neon.com/docs/storage/authentication#read-vs-write-scopes): allows all read operations plus PutObject and DeleteObject

**CLI**

Create a credential with the [Neon CLI](https://neon.com/docs/cli/credentials):

```bash
neon credentials create --scope storage:read --scope storage:write --name my-app-credential
```

The `api_token` and `s3_secret_access_key` are printed once, so store them right away. Map `token_id` to `AWS_ACCESS_KEY_ID` and `s3_secret_access_key` to `AWS_SECRET_ACCESS_KEY` (see [Mapping to your S3 SDK](https://neon.com/docs/storage/authentication#mapping-to-your-s3-sdk)). Run it in a directory [linked](https://neon.com/docs/cli/link) to your project, or pass `--project-id` and `--branch`.

**Console**

In the Neon Console, click **Connect** at the top of the sidebar and open the **Storage** tab. Use the client selector to pick **S3 client**, **Files SDK**, or **Python** for a ready-to-run snippet, or **Parameters only** for the raw `.env`. Click **Reveal credential** to show `AWS_SECRET_ACCESS_KEY`, **Copy credentials** to copy it, or **Rotate credentials** to issue new keys.

![Connect to your branch modal with the Storage tab open](https://neon.com/docs/connect/connect_to_branch_storage_tab.png)

To create a separate credential with only the scopes you need, open your project's **Settings** > **Credentials**, select **Create credential**, enter a name, and choose `storage:read`, `storage:write`, or both. Copy the secret right away.

```text
AWS_ENDPOINT_URL_S3=https://br-cool-darkness-a1b2c3d4.storage.c-1.us-east-2.aws.neon.tech
AWS_ACCESS_KEY_ID=nak_live_...
AWS_SECRET_ACCESS_KEY=nsk_live_...
AWS_REGION=us-east-2
```

The Connect dialog reveals and rotates the current credential. To list all credentials for the branch or revoke one, use the [Neon CLI](https://neon.com/docs/cli/credentials) or the API (below).

**API**

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["storage:read", "storage:write"], "principal_type": "user", "name": "my-app-credential"}'
```

The `name` and `expires_at` fields are optional.

**Warning:** `expires_at` is not currently enforced. A credential created with an `expires_at` value in the past still authenticates successfully. Don't rely on it for access control; revoke credentials explicitly instead. See [Revoking credentials](https://neon.com/docs/storage/authentication#revoking-credentials).

The response includes these fields:

```json
{
  "token_id": "nak_live_...",
  "token_id_short": "9043e374b584...",
  "name": "my-app-credential",
  "api_token": "nt_live_...",
  "s3_secret_access_key": "nsk_live_...",
  "scopes": ["storage:read", "storage:write"],
  "branch_id": "br-winter-pond-aptw82ef",
  "created_at": "2026-06-08T00:00:00Z",
  "expires_at": null
}
```

## Mapping to your S3 SDK

| Neon credential field  | S3 SDK parameter  |
| ---------------------- | ----------------- |
| `token_id`             | Access Key ID     |
| `s3_secret_access_key` | Secret Access Key |
| `us-east-2`            | Region            |

**Warning:** Store `api_token` and `s3_secret_access_key` in a secrets manager or environment variables right away. If you lose them, you can [show them again or rotate the credential](https://neon.com/docs/storage/authentication#listing-credentials).

Configure your S3 client using these values:

**TypeScript**

```typescript
import { S3Client } from '@aws-sdk/client-s3';

const client = new S3Client({
  region: process.env.AWS_REGION,
  endpoint: process.env.AWS_ENDPOINT_URL_S3,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,   // token_id
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!, // s3_secret_access_key
  },
  forcePathStyle: true,
});
```

**Python**

```python
import boto3, os

client = boto3.client(
    's3',
    region_name=os.environ['AWS_REGION'],
    endpoint_url=os.environ['AWS_ENDPOINT_URL_S3'],
    aws_access_key_id=os.environ['AWS_ACCESS_KEY_ID'],         # token_id
    aws_secret_access_key=os.environ['AWS_SECRET_ACCESS_KEY'], # s3_secret_access_key
)
```

**AWS CLI**

```bash
# These env vars are already in AWS-standard form; no remapping needed.
export AWS_ACCESS_KEY_ID=nak_live_...
export AWS_SECRET_ACCESS_KEY=nsk_live_...
export AWS_REGION=us-east-2
```

**Note:** `forcePathStyle: true` is required for the AWS SDK for JavaScript when using a custom S3 endpoint.

## Pull credentials with neon

For local development, `neon env pull` writes storage credentials to your `.env` file automatically. No manual copy-paste from the API response:

```bash
neon env pull --file .env.local
```

This populates `AWS_ENDPOINT_URL_S3`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` for the current branch alongside your database connection string. To check the current credential status:

```bash
neon config status
```

For production deployments, use the [API-based workflow](https://neon.com/docs/storage/authentication#creating-a-credential) to create named, scoped credentials.

## Read vs write scopes

Issue separate credentials for read and write access when you want to limit exposure:

- **Server-side code** that uploads files: `storage:write` (includes read)
- **Client-side or CDN code** that only fetches: `storage:read`
- **Presigned URLs**: generate these server-side from a `storage:write` credential. The URL itself requires no credential in the browser.

The S3 data plane enforces scope on every request. A credential without a storage scope returns `403 AccessDenied` on all S3 operations. Server-side COPY requires both `storage:read` and `storage:write`.

## Credentials in Neon Functions

When your code runs inside Neon Functions, Neon injects storage credentials automatically. You don't need to create a credential:

| Variable                | Value                                    |
| ----------------------- | ---------------------------------------- |
| `AWS_ACCESS_KEY_ID`     | S3 Access Key ID                         |
| `AWS_SECRET_ACCESS_KEY` | S3 Secret Access Key                     |
| `AWS_ENDPOINT_URL_S3`   | Branch S3 endpoint URL                   |
| `AWS_REGION`            | Object storage region (e.g. `us-east-2`) |

See [Environment variables](https://neon.com/docs/compute/functions/environment-variables) for the full list of variables Neon injects into a function.

Credentials are branch-scoped and tied to the function's serving branch. Injected values are defaults, not reserved names: a user-supplied environment variable with the same name (set via `--env` or in `neon.ts`) overrides the injected credential, same as any other Neon-injected variable. See [Environment variables](https://neon.com/docs/compute/functions/environment-variables#user-defined-variables). Because the credentials use AWS-standard names, the AWS SDK picks them up automatically when you don't override them. Only `forcePathStyle` needs explicit configuration:

```typescript
import { S3Client } from '@aws-sdk/client-s3';

const client = new S3Client({
  region: process.env.AWS_REGION,
  endpoint: process.env.AWS_ENDPOINT_URL_S3,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  forcePathStyle: true,
});
```

## How branch binding works

Each credential is tied to the branch it was created on. It is valid for:

- That branch (the anchor branch)
- Any branch descended from it: preview branches, feature branches, CI branches

It's **not** valid for branches outside that lineage.

```
main  ──── credential valid here
  └── preview/feature-x  ──── and here
        └── preview/sub-branch  ──── and here
staging  ──── credential NOT valid here (different lineage)
```

## Listing credentials

To list all credentials for the current branch (name, key ID, creation date, and last used time), use the [Neon CLI](https://neon.com/docs/cli/credentials) (`neon credentials list`) or the API:

```bash
curl "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

This returns credential metadata, without secrets. To show a credential's secrets again, use `neon credentials reveal <token_id>` or the [reveal API](https://neon.com/docs/reference/api/credentials/reveal-credential). A credential created before reveal was available returns `409`; [rotate it](https://neon.com/docs/storage/authentication#revoking-credentials) instead.

## Revoking credentials

To revoke, use the [Neon CLI](https://neon.com/docs/cli/credentials) (`neon credentials revoke <token_id>`) or the API:

```bash
curl -X DELETE "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials/{token_id}" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

With the [Neon CLI](https://neon.com/docs/cli/credentials), run `neon credentials list` to find a credential, then revoke it by its `token_id`:

```bash
neon credentials revoke <token_id>
```

To rotate a credential in place, run `neon credentials rotate <token_id>` or use the [rotate API](https://neon.com/docs/reference/api/credentials/rotate-credential). This mints a new `s3_secret_access_key` while keeping the `token_id` (your `AWS_ACCESS_KEY_ID`) the same, so you only update the secret. Otherwise, create a new credential, update your environment variables, then revoke the old one.

## Common errors

| Error                       | Cause                               | Fix                                                                                                                                                              |
| --------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403 InvalidAccessKeyId`    | `token_id` is wrong or revoked      | Check `AWS_ACCESS_KEY_ID` is set correctly. If you rotated the credential, update the value.                                                                     |
| `403 SignatureDoesNotMatch` | Wrong secret access key             | Check `AWS_SECRET_ACCESS_KEY` is the value from credential creation. If lost, [show it again](https://neon.com/docs/storage/authentication#listing-credentials). |
| `403 AccessDenied`          | Credential lacks the required scope | Recreate with `storage:write` for uploads/deletes                                                                                                                |
| `403 AccessDenied`          | Branch not in credential lineage    | Use a credential created on this branch or an ancestor                                                                                                           |

--- [Document source](https://neon.com/docs/storage/buckets.md) ---

> Summary: Neon Object Storage buckets hold your objects and branch with your database. Create buckets via the Neon Console, the Neon API, or the S3 API. Set the access level to private or public_read to control who can read objects.

# Buckets

Create and manage storage buckets

Last updated: 2026-09-24

A bucket is a named container for objects in Neon Object Storage. Buckets are scoped to a branch and inherit from parent branches when a new branch is created. No data is copied on fork.

For object size and storage limits, see [Limits](https://neon.com/docs/storage/overview#limits).

## Create a bucket

You can create a bucket from the Neon Console, the Neon CLI, the Neon API, or directly via the S3 API.

**Neon Console**

In the Neon Console, navigate to your project, select a branch, and open the **Object storage** tab. Click **New bucket**, enter a name, choose an access level, and click **Create**.

**neon**

```bash
neon buckets create my-bucket
```

**Neon API**

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/buckets" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-bucket", "access_level": "private"}'
```

**TypeScript**

```typescript
import { S3Client, CreateBucketCommand } from '@aws-sdk/client-s3';

const client = new S3Client({
  region: process.env.AWS_REGION,
  endpoint: process.env.AWS_ENDPOINT_URL_S3,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  forcePathStyle: true,
});

await client.send(new CreateBucketCommand({ Bucket: 'my-bucket' }));
```

**Python**

```python
import boto3, os

client = boto3.client(
    's3',
    region_name=os.environ['AWS_REGION'],
    endpoint_url=os.environ['AWS_ENDPOINT_URL_S3'],
    aws_access_key_id=os.environ['AWS_ACCESS_KEY_ID'],
    aws_secret_access_key=os.environ['AWS_SECRET_ACCESS_KEY'],
)

client.create_bucket(Bucket='my-bucket')
```

**AWS CLI**

```bash
aws s3api create-bucket \
  --bucket my-bucket \
  --region us-east-2 \
  --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

To create a `public_read` bucket with neon:

```bash
neon buckets create my-public-bucket --access-level public_read
```

**Note:** `AWS_ENDPOINT_URL_S3` is your branch's storage endpoint. See [Get started](https://neon.com/docs/storage/get-started) for how to obtain it.

## Access levels

Every bucket has an access level that controls who can read objects in it.

| Access level  | Reads                                 | Writes                     |
| ------------- | ------------------------------------- | -------------------------- |
| `private`     | Require a valid credential            | Require a valid credential |
| `public_read` | Open to anyone (no credential needed) | Require a valid credential |

The default is `private`. Set the access level when creating a bucket via the Neon API, or change it from the **Object storage** tab in the Console.

**Note:** Access level is set through the Neon Console or API, not through the S3 API. S3 ACL and bucket policy mutation requests (PutBucketAcl, PutBucketPolicy) return `501 Not Implemented`. If you need to change access level on an existing bucket, use the Console or Neon API.

**public_read example**

Objects in a `public_read` bucket are accessible at:

```
https://<branch-id>.storage.c-<N>.us-east-2.aws.neon.tech/my-public-bucket/<object-key>
```

## List buckets

**neon**

```bash
neon buckets list
```

**TypeScript**

```typescript
import { S3Client, ListBucketsCommand } from '@aws-sdk/client-s3';

const { Buckets } = await client.send(new ListBucketsCommand({}));
console.log(Buckets);
```

**Python**

```python
response = client.list_buckets()
print(response['Buckets'])
```

**AWS CLI**

```bash
aws s3api list-buckets --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

## Delete a bucket

Buckets must be empty before deletion. [Delete all objects](https://neon.com/docs/storage/objects#delete-objects) first, then delete the bucket.

**neon**

```bash
neon buckets delete my-bucket
```

**TypeScript**

```typescript
import { S3Client, DeleteBucketCommand } from '@aws-sdk/client-s3';

await client.send(new DeleteBucketCommand({ Bucket: 'my-bucket' }));
```

**Python**

```python
client.delete_bucket(Bucket='my-bucket')
```

**AWS CLI**

```bash
aws s3api delete-bucket \
  --bucket my-bucket \
  --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

## Bucket branching

When you create a new branch, it inherits all buckets from its parent, including the objects already in them at the moment of forking — the same copy-on-write model Neon uses for branching Postgres data, so nothing is duplicated upfront. From that point on:

- Creating or deleting a bucket on a child branch does not affect the parent.
- New uploads, overwrites, and deletes on a child branch are only visible on that branch and its descendants, even for objects that existed at fork time.
- The parent branch continues to see its own state unchanged.

This makes it safe to test bucket changes in a preview branch without affecting production.

When you [reset a branch from its parent](https://neon.com/docs/guides/reset-from-parent), its buckets and objects reset along with the database. The branch returns to the parent's current state, and any bucket changes you made on it are discarded. A [restore](https://neon.com/docs/postgres/backup-restore/branch-restore) behaves differently: it rolls back Postgres but leaves buckets and objects as they are.

## Next steps

- [Objects](https://neon.com/docs/storage/objects): upload, download, list, and delete objects
- [Authentication](https://neon.com/docs/storage/authentication): credential scopes and branch binding
- [Limits](https://neon.com/docs/storage/overview#limits): object size and usage limits

--- [Document source](https://neon.com/docs/storage/get-started.md) ---

> Summary: This quickstart walks you through creating a storage credential, configuring a client, creating a bucket, and uploading and downloading your first file. Use the Files SDK or any AWS S3-compatible SDK. Just point it at your branch endpoint.

# Get started with Object Storage

Upload your first file in minutes

Last updated: 2026-10-09

To set up Neon Object Storage with an AI coding assistant, install the Neon Platform (`neon`) and Neon Object Storage skills with the [Neon CLI](https://neon.com/docs/cli):

```bash
neon skills -s neon -s neon-object-storage
```

Without the Neon CLI, run `npx skills add neondatabase/agent-skills -s neon -s neon-object-storage` instead.

To follow this guide, you need:

- A Neon project in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward [all regions](https://neon.com/docs/introduction/regions).
- The Neon CLI installed and authenticated if you use the recommended `neon.ts` flow
- A Neon API key in `NEON_API_KEY` if you use the manual API flow

## Recommended: enable storage with neon.ts

The recommended way to enable storage and get credentials is via `neon.ts`, Neon's infrastructure-as-code config file. Install the config package, link your local app to the Neon project and branch you want to target, declare buckets under the top-level `buckets` key, then run `neon deploy` to provision them on the linked branch and pull credentials into `.env.local` automatically:

```bash
npm install @neon/config
neon link           # choose the project and branch for this app
neon branches list  # confirm the linked target branch before deploy
```

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

export default defineConfig({
  buckets: {
    'my-bucket': {},                          // private (default)
    'public-assets': { access: 'public_read' },
  },
});
```

To declare a bucket without editing `neon.ts` by hand, run `neon config add bucket my-bucket` (add `--access public_read` for anonymous reads). See [`neon config add`](https://neon.com/docs/cli/config#add).

```bash
neon deploy          # provisions buckets and writes AWS_* vars to .env.local
```

After deploy, your `.env.local` contains `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, and `AWS_REGION`. Skip to [Configure your client](https://neon.com/docs/storage/get-started#configure-your-client) below.

Already deployed? Pull the vars again with:

```bash
neon env pull
```

---

If you prefer to manage credentials manually (for example, for CI or production deployments), follow the steps below. Replace `{project_id}` and `{branch_id}` in the API examples with your own IDs. You can find them in the Neon Console URL, or with `neon projects list` and `neon branches list`.

If you need a new branch, [create it first](https://neon.com/docs/manage/branches#create-a-branch), then wait until the branch is ready before calling object storage APIs. Branch creation is asynchronous, so a freshly-created branch can still be initializing even after the create request returns.

## Find your branch endpoint

Fetch your branch's storage state from the Neon API. Do this before creating credentials so you know the branch is ready for Storage calls. The response includes the full S3 endpoint URL, the region, and whether path-style addressing is required:

```bash
curl "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/storage" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

```json
{
  "enabled": true,
  "s3_endpoint": "https://br-winter-pond-aptw82ef.storage.c-2.us-east-2.aws.neon.tech",
  "region": "us-east-2",
  "force_path_style": true
}
```

Set these as environment variables:

```bash
export AWS_ENDPOINT_URL_S3=https://br-winter-pond-aptw82ef.storage.c-2.us-east-2.aws.neon.tech
export AWS_REGION=us-east-2
```

A `404` response means object storage is not available for that branch. There is no separate manual enable API call: use the recommended `neon.ts` flow above, or make sure your project is in a supported region: AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), or AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`).

## Create a credential

Create a credential with storage access. With the [Neon CLI](https://neon.com/docs/cli/credentials):

```bash
neon credentials create --scope storage:read --scope storage:write
```

Or use the Neon API:

```bash
curl -X POST "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
  -H "Authorization: Bearer $NEON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scopes": ["storage:read", "storage:write"], "principal_type": "user"}'
```

The response includes your S3 credentials. Store them immediately. You'll only get them once. See [Authentication](https://neon.com/docs/storage/authentication#mapping-to-your-s3-sdk) for how each field maps to your S3 client.

```json
{
  "token_id": "nak_live_...",
  "s3_secret_access_key": "nsk_live_...",
  ...
}
```

Set these as environment variables:

```bash
export AWS_ACCESS_KEY_ID=nak_live_...   # token_id
export AWS_SECRET_ACCESS_KEY=nsk_live_...   # s3_secret_access_key
```

## Install dependencies

**Files SDK**

```bash
# files-sdk uses @aws-sdk/* packages as peer dependencies; install them alongside it
npm install files-sdk @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner @aws-sdk/s3-presigned-post dotenv
```

**S3 Client**

```bash
npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner dotenv
```

**Python**

```bash
pip install boto3 python-dotenv
```

## Configure your client

The `neon` adapter is a subpath export (`files-sdk/neon`) that reads `AWS_*` environment variables and configures the Files SDK for Neon's S3-compatible endpoint automatically.

**Files SDK**

```typescript
import { Files } from 'files-sdk';
import { neon } from 'files-sdk/neon';

export const files = new Files({ adapter: neon({ bucket: 'my-bucket' }) });
```

**S3 Client**

```typescript
import { S3Client } from '@aws-sdk/client-s3';
import 'dotenv/config';

export const client = new S3Client({
  region: process.env.AWS_REGION,
  endpoint: process.env.AWS_ENDPOINT_URL_S3,
  credentials: {
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  },
  forcePathStyle: true,
  // Recent SDK versions default to embedding a checksum in presigned PUT
  // URLs computed from an empty body (since no body exists at presign
  // time), which rejects any upload with real content. This restores the
  // upload/download behavior below and the presigned PUT URL in
  // Objects (/docs/storage/objects#presigned-urls).
  requestChecksumCalculation: 'WHEN_REQUIRED',
});
```

**Python**

```python
import boto3
import os
from dotenv import load_dotenv

load_dotenv()

client = boto3.client(
    's3',
    region_name=os.environ['AWS_REGION'],
    endpoint_url=os.environ['AWS_ENDPOINT_URL_S3'],
    aws_access_key_id=os.environ['AWS_ACCESS_KEY_ID'],
    aws_secret_access_key=os.environ['AWS_SECRET_ACCESS_KEY'],
)
```

**AWS CLI**

```bash
# The AWS CLI reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION
# from the environment automatically. Pass --endpoint-url on each command
# (shown below) rather than running `aws configure set endpoint_url`, which
# would overwrite your default profile's endpoint for all AWS CLI usage,
# not just Neon.
```

**Note:** If you're using [Neon Functions](https://neon.com/docs/compute/functions/overview), the `AWS_*` credentials are injected automatically when a bucket is declared in `neon.ts`. No `.env` setup is needed inside a function.

## Create a bucket

Create the bucket before uploading, or declare it in `neon.ts` and run `neon deploy`:

```bash
neon buckets create my-bucket
```

See [Buckets](https://neon.com/docs/storage/buckets#create-a-bucket) for Neon API, S3 SDK, Python, and AWS CLI examples.

## Upload a file

**Files SDK**

```typescript
import { files } from './client';

await files.upload('hello.txt', 'Hello from Neon Object Storage!', {
  contentType: 'text/plain',
});

console.log('Uploaded!');
```

**S3 Client**

```typescript
import { PutObjectCommand } from '@aws-sdk/client-s3';
import { client } from './client';

await client.send(new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: 'hello.txt',
  Body: 'Hello from Neon Object Storage!',
  ContentType: 'text/plain',
}));

console.log('Uploaded!');
```

**Python**

```python
client.put_object(
    Bucket='my-bucket',
    Key='hello.txt',
    Body='Hello from Neon Object Storage!',
    ContentType='text/plain',
)

print('Uploaded!')
```

**AWS CLI**

```bash
aws s3 cp hello.txt s3://my-bucket/hello.txt \
  --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

## Download a file

**Files SDK**

```typescript
import { files } from './client';

const result = await files.download('hello.txt');
const text = await result.text();
console.log(text); // Hello from Neon Object Storage!
```

**S3 Client**

```typescript
import { GetObjectCommand } from '@aws-sdk/client-s3';
import { client } from './client';

const response = await client.send(new GetObjectCommand({
  Bucket: 'my-bucket',
  Key: 'hello.txt',
}));

const text = await response.Body?.transformToString();
console.log(text); // Hello from Neon Object Storage!
```

**Python**

```python
response = client.get_object(Bucket='my-bucket', Key='hello.txt')
print(response['Body'].read().decode('utf-8'))  # Hello from Neon Object Storage!
```

**AWS CLI**

```bash
aws s3 cp s3://my-bucket/hello.txt ./downloaded.txt \
  --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

## Next steps

- [Buckets](https://neon.com/docs/storage/buckets): access levels, bucket branching, and the Console UI
- [Objects](https://neon.com/docs/storage/objects): list, delete, multipart uploads, and presigned URLs
- [Authentication](https://neon.com/docs/storage/authentication): credential scopes, branch binding, and rotation
- [with-files-sdk](https://github.com/neondatabase/examples/tree/main/with-files-sdk): working example showing how to upload files to a branch-scoped bucket using the Files SDK and its `neon` adapter

--- [Document source](https://neon.com/docs/storage/logs.md) ---

> Summary: View Object Storage bucket logs in the Neon Console: S3 request logs (GET, PUT, DELETE, and more) and Console/API bucket and object changes, with levels derived from HTTP status. Covers scope_name values and common patterns that look like a problem but aren't.

# Object storage logs

View, search, and download logs for a bucket

Last updated: 2026-11-06

Every S3 request against a bucket streams a log line to the Neon Console. So does any bucket or object change made through the Console or Neon API (creating a bucket, deleting a bucket, deleting an object or prefix):

```text
service_name:  neon-storage/my-bucket
scope_name:    neon.storage.s3.put
severity_text: INFO
body: {
  "operation": "PUT",
  "object_key": "path/to/object.parquet",
  "http_status": 200,
  "bytes": 4096,
  "duration_ms": 9.5,
  "request_id": "req-777",
  "remote_ip": "203.0.113.9"
}
```

Two kinds of requests don't appear. S3 requests rejected before they reach your branch aren't logged: an invalid signature, or a credential without access to this branch or without the storage scope the operation needs. Reads through the Console or Neon API, such as downloading an object, aren't logged either; only changes are.

## View logs

Bucket logs live on the branch's [Monitoring page, in the **Storage** tab](https://neon.com/docs/introduction/monitor-logs). To jump straight to one bucket's logs, open the bucket list, open that bucket's menu, and select **View logs**. Or go to **Monitoring** and open the **Storage** tab to see every bucket's logs together.

Expand a row to see its full context: `timestamp`, `severity`, `entity_type` (`storage`), `scope_name`, and `service_name` (`neon-storage/<bucket>`). The message body carries per-request detail: `operation` (the HTTP method), `object_key`, `http_status`, `bytes`, `duration_ms`, `request_id`, and `remote_ip`. The access key ID that made the request isn't shown in the Console or returned by `neon logs`.

`scope_name` identifies what generated the line:

- `neon.storage.s3.<method>` (`get`, `put`, `delete`, `head`, `post`): an S3 API request, named for its HTTP method rather than the semantic S3 operation. Multipart upload calls (`UploadPart`, `CompleteMultipartUpload`, `AbortMultipartUpload`) also surface under their HTTP method, not a dedicated multipart scope.
- `neon.storage.api.<operation>` (`create_bucket`, `delete_bucket`, `delete_object`, `delete_prefix`): a bucket or object change made through the Console or Neon API, not an S3 client. These appear in the same stream as S3 traffic, distinguished only by this `api` vs `s3` segment.

## Log levels

A bucket's log level comes from the HTTP status code of the request, not from anything the client sets:

| Level   | HTTP status                                                     |
| ------- | --------------------------------------------------------------- |
| `INFO`  | Everything else (successful requests)                           |
| `WARN`  | 4xx                                                             |
| `ERROR` | 5xx, including `501 Not Implemented` for unsupported operations |

`DEBUG`, `NOTICE`, and `FATAL` also appear as filters in the log viewer but aren't currently emitted by Object Storage; they're part of the Neon Console's shared log-level set.

## Common log entries

Most of what shows up here is routine S3 traffic. A few entries look worse than they are, and one common request type doesn't show up at all.

`403` and `404` lines are expected client-side errors, not incidents. Wrong or revoked credentials, a missing scope, or a bucket-scoped credential used from the wrong branch all return a `403` and log at `WARN`, same as any other 4xx. See [Authentication errors](https://neon.com/docs/storage/troubleshooting#authentication-errors) for the specific error codes and fixes.

**Seeing `503 SlowDown` logged as `ERROR`? It's a healthy rate limit, not a server failure.** `SlowDown` is a rate-limit signal returned when a request exceeds the per-IP or per-tenant limit; the storage service is otherwise healthy. It logs at `ERROR` only because the level is derived purely from the 5xx status code. Treat it as a signal to back off and retry. See [Connection and performance errors](https://neon.com/docs/storage/troubleshooting#connection-and-performance-errors).

Calls to `ListBuckets` or the bucket list root don't appear here. Bucketless requests are deliberately excluded from the log stream, since there's no single bucket to attribute them to. If you're looking for that traffic, it isn't missing: it was never exported.

**Seeing a `501` for an operation you expected to work? It's an unsupported operation, not a server failure, even though it logs at `ERROR`.** Calls like `PutBucketAcl`, `PutBucketPolicy`, or `PutBucketNotificationConfiguration` return `501 Not Implemented` because Neon Object Storage doesn't support them. See [Not supported](https://neon.com/docs/storage/s3-compatibility#not-supported) for the full list.

## Filter and search

For details on filtering by level or service name, searching log bodies, live tail, and downloading logs, see [Monitor logs](https://neon.com/docs/introduction/monitor-logs).

You can also read storage logs from the terminal with [`neon logs query`](https://neon.com/docs/cli/logs), scoped with `--source storage`:

```bash
neon logs query --source storage --since 1h
```

--- [Document source](https://neon.com/docs/storage/objects.md) ---

> Summary: Work with objects in Neon Object Storage using the Files SDK, any S3-compatible SDK, or the AWS CLI. Supports single-part and multipart uploads, range requests, batch deletes, and presigned URLs for browser-side access.

# Objects

Upload, download, list, and delete files

Last updated: 2026-10-23

Objects in Neon Object Storage are files stored inside a bucket. Every object has a key (its path within the bucket), a body, a content type, and optional metadata. Objects branch with your database. Each branch inherits the parent's objects at the moment of forking without copying any data.

The examples below show both the [Files SDK](https://files-sdk.dev) and the AWS S3 client. See [Get started](https://neon.com/docs/storage/get-started) to configure either client, or [Authentication](https://neon.com/docs/storage/authentication) if you need to create a credential.

## Upload

**Files SDK**

```typescript
import { files } from './client';

await files.upload('images/photo.jpg', fileBuffer, {
  contentType: 'image/jpeg',
  metadata: { 'uploaded-by': 'user-123' },
});
```

**neon**

```bash
neon buckets object put my-bucket/images/photo.jpg --file ./photo.jpg
neon buckets object put my-bucket/images/photo.jpg --file ./photo.jpg --content-type image/jpeg
```

**S3 Client**

```typescript
import { PutObjectCommand } from '@aws-sdk/client-s3';
import { client } from './client';

await client.send(new PutObjectCommand({
  Bucket: 'my-bucket',
  Key: 'images/photo.jpg',
  Body: fileBuffer,
  ContentType: 'image/jpeg',
  Metadata: {
    'uploaded-by': 'user-123',
  },
}));
```

**Python**

```python
client.put_object(
    Bucket='my-bucket',
    Key='images/photo.jpg',
    Body=file_bytes,
    ContentType='image/jpeg',
    Metadata={'uploaded-by': 'user-123'},
)
```

**AWS CLI**

```bash
aws s3 cp ./photo.jpg s3://my-bucket/images/photo.jpg \
  --content-type image/jpeg \
  --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

**Note:** `neon buckets object put` uploads via a presigned URL and supports files up to the presign size limit. For large or streaming uploads use the AWS SDK with [multipart upload](https://neon.com/docs/storage/objects#multipart-upload).

## Multipart upload

A single-request upload can be up to 5 GiB. With multipart upload, an object can be up to 10 GiB, so use multipart upload for objects larger than 5 GiB (AWS recommends it above 100 MB). Higher limits are planned: paid plans will follow standard [S3 limits](https://aws.amazon.com/s3/faqs/), with objects up to 5 TB. For large files, the AWS SDK automatically uses multipart upload above a configurable threshold. You can also initiate multipart upload manually for fine-grained control. Multipart upload makes large uploads more reliable because each part is retried independently. For all size and capacity limits, see [Limits](https://neon.com/docs/storage/overview#limits).

**TypeScript**

```typescript
import { Upload } from '@aws-sdk/lib-storage';
import { client } from './client';
import { createReadStream } from 'fs';

const upload = new Upload({
  client,
  params: {
    Bucket: 'my-bucket',
    Key: 'large-file.zip',
    Body: createReadStream('./large-file.zip'),
  },
  partSize: 10 * 1024 * 1024, // 10 MiB per part
});

await upload.done();
```

**Python**

```python
import boto3

# boto3 handles multipart automatically via upload_file/upload_fileobj
client.upload_file(
    './large-file.zip',
    'my-bucket',
    'large-file.zip',
    Config=boto3.s3.transfer.TransferConfig(
        multipart_threshold=10 * 1024 * 1024,
        multipart_chunksize=10 * 1024 * 1024,
    ),
)
```

## Download

**Files SDK**

```typescript
import { files } from './client';

const result = await files.download('images/photo.jpg');
const buffer = await result.arrayBuffer();
```

**neon**

```bash
# Downloads to ./photo.jpg by default; use --file to specify a different path
neon buckets object get my-bucket/images/photo.jpg
neon buckets object get my-bucket/images/photo.jpg --file ./downloads/photo.jpg
```

**S3 Client**

```typescript
import { GetObjectCommand } from '@aws-sdk/client-s3';
import { client } from './client';

const response = await client.send(new GetObjectCommand({
  Bucket: 'my-bucket',
  Key: 'images/photo.jpg',
}));

// Stream to a file
const stream = response.Body as NodeJS.ReadableStream;
stream.pipe(fs.createWriteStream('./photo.jpg'));
```

**Python**

```python
response = client.get_object(Bucket='my-bucket', Key='images/photo.jpg')
with open('./photo.jpg', 'wb') as f:
    f.write(response['Body'].read())
```

**AWS CLI**

```bash
aws s3 cp s3://my-bucket/images/photo.jpg ./photo.jpg \
  --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

You can use range requests for partial downloads:

```typescript
const response = await client.send(new GetObjectCommand({
  Bucket: 'my-bucket',
  Key: 'video.mp4',
  Range: 'bytes=0-1048575', // first 1 MiB
}));
```

## List objects

Use a prefix to filter results. The Files SDK returns a flat array of items; the S3 client supports a delimiter to simulate folder structure.

**Files SDK**

```typescript
import { files } from './client';

const { items } = await files.list({ prefix: 'images/' });
for (const item of items) {
  console.log(item.key, item.size);
}
```

**neon**

```bash
# Folder-collapsed view by default (same as aws s3 ls)
neon buckets object list my-bucket

# List objects under a prefix
neon buckets object list my-bucket/images/

# Flat listing of every key, no folder collapsing
neon buckets object list my-bucket --recursive
```

**S3 Client**

```typescript
import { ListObjectsV2Command } from '@aws-sdk/client-s3';
import { client } from './client';

const response = await client.send(new ListObjectsV2Command({
  Bucket: 'my-bucket',
  Prefix: 'images/',
  Delimiter: '/',
}));

// Objects in images/
console.log(response.Contents);

// Sub-folders (common prefixes)
console.log(response.CommonPrefixes);
```

**Python**

```python
response = client.list_objects_v2(
    Bucket='my-bucket',
    Prefix='images/',
    Delimiter='/',
)

# Objects in images/
print(response.get('Contents', []))

# Sub-folders
print(response.get('CommonPrefixes', []))
```

**AWS CLI**

```bash
aws s3 ls s3://my-bucket/images/ \
  --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

For buckets with more than 1,000 objects, paginate using `ContinuationToken`:

```typescript
let token: string | undefined;
do {
  const response = await client.send(new ListObjectsV2Command({
    Bucket: 'my-bucket',
    ContinuationToken: token,
  }));
  for (const obj of response.Contents ?? []) {
    console.log(obj.Key);
  }
  token = response.NextContinuationToken;
} while (token);
```

## Delete objects

**Single object:**

**Files SDK**

```typescript
import { files } from './client';

await files.delete('images/photo.jpg');
```

**neon**

```bash
neon buckets object delete my-bucket/images/photo.jpg
```

**S3 Client**

```typescript
import { DeleteObjectCommand } from '@aws-sdk/client-s3';

await client.send(new DeleteObjectCommand({
  Bucket: 'my-bucket',
  Key: 'images/photo.jpg',
}));
```

**Python**

```python
client.delete_object(Bucket='my-bucket', Key='images/photo.jpg')
```

**AWS CLI**

```bash
aws s3 rm s3://my-bucket/images/photo.jpg \
  --endpoint-url "$AWS_ENDPOINT_URL_S3"
```

**Batch delete (up to 1,000 objects per request):**

**Files SDK**

```typescript
import { files } from './client';

await files.delete(['images/photo1.jpg', 'images/photo2.jpg']);
```

**S3 Client**

```typescript
import { DeleteObjectsCommand } from '@aws-sdk/client-s3';

await client.send(new DeleteObjectsCommand({
  Bucket: 'my-bucket',
  Delete: {
    Objects: [
      { Key: 'images/photo1.jpg' },
      { Key: 'images/photo2.jpg' },
    ],
  },
}));
```

**Python**

```python
client.delete_objects(
    Bucket='my-bucket',
    Delete={
        'Objects': [
            {'Key': 'images/photo1.jpg'},
            {'Key': 'images/photo2.jpg'},
        ]
    },
)
```

**Delete a folder (all objects under a prefix):**

**neon**

```bash
# The prefix must end with /
neon buckets object delete my-bucket/images/ --recursive
```

**Neon API**

```bash
curl -X DELETE \
  "https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/buckets/my-bucket/objects-by-prefix?prefix=images/" \
  -H "Authorization: Bearer $NEON_API_KEY"
```

## Presigned URLs

Generate a time-limited URL that allows a browser or unauthenticated client to upload or download a specific object, without exposing your credentials.

**Presigned GET (download):**

**Files SDK**

```typescript
import { files } from './client';

const url = await files.url('report.pdf', { expiresIn: 3600 }); // 1 hour
console.log(url); // share this URL — no credentials needed
```

**S3 Client**

```typescript
import { GetObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { client } from './client';

const url = await getSignedUrl(
  client,
  new GetObjectCommand({ Bucket: 'my-bucket', Key: 'report.pdf' }),
  { expiresIn: 3600 }, // 1 hour
);

console.log(url); // share this URL — no credentials needed
```

**Python**

```python
url = client.generate_presigned_url(
    'get_object',
    Params={'Bucket': 'my-bucket', 'Key': 'report.pdf'},
    ExpiresIn=3600,  # 1 hour
)
print(url)
```

To set the filename the browser saves the download under, sign the URL with a `ResponseContentDisposition` override. The override is covered by the URL's signature, so it can't be changed after signing.

**S3 Client**

```typescript
const url = await getSignedUrl(
  client,
  new GetObjectCommand({
    Bucket: 'my-bucket',
    Key: 'report.pdf',
    ResponseContentDisposition: 'attachment; filename="report.pdf"',
  }),
  { expiresIn: 3600 }, // 1 hour
);
```

**Python**

```python
url = client.generate_presigned_url(
    'get_object',
    Params={
        'Bucket': 'my-bucket',
        'Key': 'report.pdf',
        'ResponseContentDisposition': 'attachment; filename="report.pdf"',
    },
    ExpiresIn=3600,  # 1 hour
)
```

**Presigned PUT (upload from browser):**

**Files SDK**

```typescript
import { files } from './client';

// Returns { url, method, headers } — pass all three to fetch on the client side
const { url, method, headers } = await files.signedUploadUrl('uploads/user-avatar.png', {
  contentType: 'image/png',
  expiresIn: 300, // 5 minutes
});

// On the client side:
// await fetch(url, { method, headers, body: file });
```

**S3 Client**

```typescript
import { PutObjectCommand } from '@aws-sdk/client-s3';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { client } from './client';

const url = await getSignedUrl(
  client,
  new PutObjectCommand({
    Bucket: 'my-bucket',
    Key: 'uploads/user-avatar.png',
    ContentType: 'image/png',
  }),
  { expiresIn: 300 }, // 5 minutes
);

// On the client side:
// await fetch(url, { method: 'PUT', body: file, headers: { 'Content-Type': 'image/png' } });
```

**Python**

```python
url = client.generate_presigned_url(
    'put_object',
    Params={
        'Bucket': 'my-bucket',
        'Key': 'uploads/user-avatar.png',
        'ContentType': 'image/png',
    },
    ExpiresIn=300,
)
print(url)
```

## Object branching

Objects branch with your database. When you fork a branch, the child can immediately read every object that existed in the parent's buckets at that point in time, using the same copy-on-write model Neon uses for branching Postgres data, so nothing is duplicated upfront. From that point:

- Uploading a new object to a child branch, or overwriting or deleting one that existed at fork time, is only visible on that branch and its descendants.
- Deleting an object on a child branch does not affect the parent.
- The parent's objects remain unchanged regardless of what happens on child branches.

## Next steps

- [Buckets](https://neon.com/docs/storage/buckets): set access levels, understand bucket branching
- [Authentication](https://neon.com/docs/storage/authentication): credential scopes and read vs write access
- [Trigger on an object upload](https://neon.com/docs/compute/functions/triggers/object-storage): run a function when an object is created

--- [Document source](https://neon.com/docs/storage/overview.md) ---

> Summary: Neon Object Storage is S3-style object storage built into your Neon project. Files branch and fork copy-on-write with your database, so every branch gets its own view of storage. Point an S3 SDK at your branch endpoint and authenticate with your Neon credential.

# Neon Object Storage

Branch-aware object storage in the Neon backend

Last updated: 2026-10-23

Store images, video, and user uploads in S3-style object storage that lives in your backend, so your files branch with your data.

[View prompt](https://neon.com/prompts/object-storage-landing.md)

## Get started

- [Quickstart](https://neon.com/docs/storage/get-started): Create a credential, configure a client, and upload your first file.
- [Buckets](https://neon.com/docs/storage/buckets): Create and manage buckets, set access levels, and understand how buckets branch.
- [Objects](https://neon.com/docs/storage/objects): Upload, download, list, delete, and generate presigned URLs for objects.
- [Authentication](https://neon.com/docs/storage/authentication): Understand how Neon credentials map to S3 access keys.

## Explore features

- [Triggers](https://neon.com/docs/compute/functions/triggers/object-storage): Run a function when an object is uploaded to a bucket.
- [S3 API support](https://neon.com/docs/storage/s3-compatibility): See which S3 operations Neon supports and point any S3 SDK at your bucket.
- [Logs](https://neon.com/docs/storage/logs): View, search, and download a bucket's logs in the Console.

## About Neon Object Storage

Neon Object Storage is file storage built into your Neon project, reached through an S3-style API. Key capabilities include:

- **Branches with your database.** Each branch has its own view of storage, so you can test uploads and deletes in a preview branch without touching production files. [Reset a branch from its parent](https://neon.com/docs/guides/reset-from-parent) to return its storage to the parent's state.
- **Copy-on-write forking.** Branches inherit the parent's objects at the moment of forking, with no data copied.
- **S3-style access.** Point the AWS SDKs, boto3, the AWS CLI, or the [Files SDK](https://files-sdk.dev) at your branch endpoint. Neon implements a subset of the S3 API.
- **One credential system.** The same Neon credential system used by AI Gateway and Functions.
- **Event-driven.** Run a function when an object is uploaded with [Function Triggers](https://neon.com/docs/compute/functions/triggers/object-storage).

## Starter templates

The [examples repository](https://github.com/neondatabase/examples) includes templates that use Neon Object Storage. Each declares its bucket in `neon.ts` and provisions it with `neon deploy`, which also injects the S3 credentials, so there are no secrets to copy. A couple to start with:

[files-sdk](https://github.com/neondatabase/examples/tree/main/with-files-sdk) is a standalone script that uploads local files to a `public_read` bucket with the [Files SDK](https://files-sdk.dev) and its `neon` adapter, then prints presigned URLs. A minimal example of the storage API on its own:

```bash
neon bootstrap --template files-sdk
```

[ai-sdk](https://github.com/neondatabase/examples/tree/main/with-ai-sdk) is a chat agent on a Neon Function that generates images, stores each one in a private bucket with the AWS S3 SDK, records its key and metadata in Postgres, and serves it back through a presigned URL. Shows object storage and the database branching together:

```bash
neon bootstrap --template ai-sdk
```

## Limits

The following limits apply:

| Limit                                                                                             | Value                                                                               |
| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Object size, single-request upload (maximum)                                                      | 5 GiB                                                                               |
| Object size, [multipart upload](https://neon.com/docs/storage/objects#multipart-upload) (maximum) | 10 GiB                                                                              |
| Free plan object storage                                                                          | 5 GB per project ([rates](https://neon.com/docs/introduction/plans#object-storage)) |

Two limits are behavioral rather than fixed numbers:

- **Region**: object storage is available in AWS US East (Ohio) (`aws-us-east-2`), AWS US East (N. Virginia) (`aws-us-east-1`), AWS Europe (Frankfurt) (`aws-eu-central-1`), and AWS Asia Pacific (Singapore) (`aws-ap-southeast-1`). Support is expanding toward all regions.
- **Rate limiting**: requests may be throttled during heavy use, returning a `503 SlowDown` response. Back off and retry. See [Connection and performance errors](https://neon.com/docs/storage/troubleshooting#connection-and-performance-errors).

To see how much Object Storage your project uses, check the **Object storage** row in the **Project** panel on your branch's **Overview** page. The value covers all branches in the project.

Storage-volume limits apply to the Free plan only. Paid plans have no fixed limit on total storage or number of objects; storage is metered per GB (see [plans and pricing](https://neon.com/docs/introduction/plans#object-storage)). For large objects, use [multipart upload](https://neon.com/docs/storage/objects#multipart-upload), which AWS recommends for anything over 100 MB.

For S3 API and feature limitations (as opposed to usage limits), see [Known limitations](https://neon.com/docs/storage/s3-compatibility#known-limitations).

--- [Document source](https://neon.com/docs/storage/s3-compatibility.md) ---

> Summary: Neon Object Storage implements core S3 operations. It is compatible with the AWS SDK for JavaScript, boto3, and the AWS CLI. Not all S3 operations are supported. This page lists what works, what returns 501, and known limitations.

# S3 compatibility

Which S3 operations Neon Object Storage supports

Last updated: 2026-09-16

Neon Object Storage is compatible with the S3 API for core operations. It works with the AWS SDK for JavaScript (`@aws-sdk/client-s3`), boto3, the AWS CLI, and other S3-compatible tools. Not all S3 API operations are available.

**Note:** Configure your S3 client with `forcePathStyle: true` (JavaScript) or `endpoint_url` (Python/CLI). Neon Object Storage uses path-style addressing only. See [Get started](https://neon.com/docs/storage/get-started) for setup details.

## Supported operations

### Buckets

| Operation                                                                   | Notes                                                            |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `ListBuckets`                                                               | Lists all buckets on the current branch                          |
| `CreateBucket`                                                              | Creates a bucket on the current branch                           |
| `HeadBucket`                                                                | Checks if a bucket exists                                        |
| `DeleteBucket`                                                              | Bucket must be empty first                                       |
| `ListObjectsV2`                                                             | Supports `prefix`, `delimiter`, `max-keys`, `continuation-token` |
| `GetBucketLocation`                                                         | Returns the configured region                                    |
| `GetBucketCors` / `PutBucketCors` / `DeleteBucketCors`                      | CORS configuration                                               |
| `GetBucketAcl`                                                              | Read-only; returns the stored ACL                                |
| `GetBucketPolicy`                                                           | Read-only; returns the stored policy                             |
| `GetBucketTagging` / `PutBucketTagging` / `DeleteBucketTagging`             | Tag management                                                   |
| `GetBucketVersioning`                                                       | Returns stored config; versioning is not enforced                |
| `GetBucketLifecycle` / `PutBucketLifecycle` / `DeleteBucketLifecycle`       | Config is stored but rules are not enforced                      |
| `GetObjectLockConfiguration` / `PutObjectLockConfiguration`                 | Config is stored; enforcement is limited                         |
| `GetPublicAccessBlock` / `PutPublicAccessBlock` / `DeletePublicAccessBlock` | Supported                                                        |

### Objects

| Operation                                                       | Notes                                                                                                                                               |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GetObject`                                                     | Supports `Range` header for partial reads, and `response-*` header overrides (e.g. `response-content-disposition`) on signed and presigned requests |
| `HeadObject`                                                    | Returns object metadata; honors `response-*` overrides on signed requests                                                                           |
| `CopyObject`                                                    | Server-side copy; `x-amz-copy-source` may be fully URL-encoded                                                                                      |
| `PutObject`                                                     | Supports `Content-Type`, `Content-Disposition`, `Cache-Control`, custom `x-amz-meta-*` headers                                                      |
| `DeleteObject`                                                  | Soft-deletes the object on the current branch                                                                                                       |
| `DeleteObjects`                                                 | Batch delete up to 1,000 keys per request                                                                                                           |
| `GetObjectAcl`                                                  | Read-only                                                                                                                                           |
| `GetObjectTagging` / `PutObjectTagging` / `DeleteObjectTagging` | Tag management                                                                                                                                      |
| `GetObjectAttributes`                                           | Returns ETag, size, and checksum                                                                                                                    |

### Multipart upload

| Operation                 | Notes                                          |
| ------------------------- | ---------------------------------------------- |
| `CreateMultipartUpload`   | Initiates a multipart upload                   |
| `UploadPart`              | Uploads a single part                          |
| `UploadPartCopy`          | Copies a part from another object              |
| `CompleteMultipartUpload` | Finalises the upload                           |
| `AbortMultipartUpload`    | Cancels and cleans up                          |
| `ListMultipartUploads`    | Lists in-progress uploads                      |
| `ListParts`               | Lists uploaded parts for an in-progress upload |

### Presigned requests

| Operation                   | Notes                                                             |
| --------------------------- | ----------------------------------------------------------------- |
| Presigned GET / PUT         | Supported via `X-Amz-Algorithm=AWS4-HMAC-SHA256` query parameters |
| Browser form uploads (POST) | Supported                                                         |
| Presigned URL expiry        | Configurable via `X-Amz-Expires`                                  |

### CORS

| Operation                                              | Notes                     |
| ------------------------------------------------------ | ------------------------- |
| `OPTIONS` preflight                                    | Handled automatically     |
| `GetBucketCors` / `PutBucketCors` / `DeleteBucketCors` | Full CORS rule management |

## Not supported

The following operations return `501 Not Implemented`:

| Operation                                                                  | Category                      |
| -------------------------------------------------------------------------- | ----------------------------- |
| `PutBucketAcl`, `PutBucketPolicy`, `PutObjectAcl`                          | ACL/policy writes via S3 wire |
| `GetBucketNotificationConfiguration`, `PutBucketNotificationConfiguration` | Event notifications           |
| `GetBucketLogging`, `PutBucketLogging`                                     | Server-side logging           |
| `GetBucketEncryption`, `PutBucketEncryption`                               | Encryption configuration      |
| `GetBucketReplication`, `PutBucketReplication`                             | Cross-region replication      |
| `GetBucketWebsite`, `PutBucketWebsite`                                     | Static website hosting        |
| `GetBucketAccelerateConfiguration`, `PutBucketAccelerateConfiguration`     | Transfer acceleration         |
| `SelectObjectContent`                                                      | S3 Select queries             |
| `RestoreObject`                                                            | Glacier restore               |
| `GetObjectTorrent`                                                         | BitTorrent                    |

**Note:** To set a bucket's access level (`private` or `public_read`), use the [Neon Console or API](https://neon.com/docs/storage/buckets#access-levels) instead of `PutBucketAcl` or `PutBucketPolicy`.

## Known limitations

- **Path-style addressing only.** Virtual-hosted-style requests (`bucket.host/key`) are not supported. Always set `forcePathStyle: true` in the AWS SDK for JavaScript, or use `endpoint_url` in boto3.
- **SigV4 only.** AWS Signature Version 2 (SigV2) is not supported.
- **`response-*` overrides are ignored on anonymous requests.** Unsigned requests to public-read objects always return the stored headers, while AWS S3 returns `400 InvalidRequest`. Use a presigned URL to set a download filename or content type.
- **Lifecycle rules stored but not enforced.** `PutBucketLifecycle` accepts and stores configuration, but expiration and transition rules do not run.
- **Versioning stored but not enforced.** Versioning configuration is stored and echoed. Objects always return `x-amz-version-id: null`.
- **No bucket notifications.** SNS/SQS integration is not available.
- **Branches, not regions.** Buckets are scoped to a branch, not an AWS region. `GetBucketLocation` returns the configured region string but bucket selection is always branch-based.

--- [Document source](https://neon.com/docs/storage/troubleshooting.md) ---

> Summary: Solutions for common errors when using Neon Object Storage, including authentication failures, access denied errors, SDK configuration issues, and S3 compatibility limitations.

# Object storage troubleshooting

Common errors and how to fix them

Last updated: 2026-10-23

Every error described below also appears as a log line in the Console. See [Object storage logs](https://neon.com/docs/storage/logs) for how to view, filter, and search them.

## Authentication errors

### `403 InvalidAccessKeyId`

The Access Key ID is wrong, missing, or the credential has been revoked.

**Fix:** Check that `AWS_ACCESS_KEY_ID` is set to the `token_id` from the credential response, not `token_id_short`. See [Authentication](https://neon.com/docs/storage/authentication#mapping-to-your-s3-sdk) for the correct field mapping. If you no longer have it, [list your credentials](https://neon.com/docs/storage/authentication#listing-credentials).

### `403 SignatureDoesNotMatch`

The Secret Access Key is wrong.

**Fix:** Check that `AWS_SECRET_ACCESS_KEY` is set to the `s3_secret_access_key` field from the credential response. This is the full value, `nsk_live_` followed by 64 hex characters, not the `api_token`. Keep the `nsk_live_` prefix. If you no longer have the `s3_secret_access_key`, [show it again](https://neon.com/docs/storage/authentication#listing-credentials).

### `403 AccessDenied`: missing scope

The credential does not have the required scope for the operation.

**Fix:** Check which scopes the credential was created with:

- `storage:read` allows GetObject, HeadObject, ListBuckets, and ListObjectsV2
- `storage:write` allows all reads plus PutObject, DeleteObject, CreateBucket, and DeleteBucket

To add write access, create a new credential with `storage:write`. You can't add scopes to an existing credential.

### `403 AccessDenied`: wrong branch

The credential was issued on a branch that is not an ancestor of the branch you are making requests against.

**Fix:** Use a credential issued on the target branch or one of its ancestor branches. See [Authentication](https://neon.com/docs/storage/authentication#how-branch-binding-works) for how branch binding works.

## SDK configuration errors

### Requests go to AWS instead of Neon

If you forget to set the custom endpoint, the SDK will route requests to AWS S3 and fail with a credentials error or bucket-not-found.

**Fix:** Always set the `endpoint` (JavaScript) or `endpoint_url` (Python/CLI) to your branch storage host:

```typescript
const client = new S3Client({
  endpoint: process.env.AWS_ENDPOINT_URL_S3,
  // ...
});
```

### `NoSuchBucket` on every request

Without `forcePathStyle: true`, the SDK treats the bucket name as a subdomain instead of a path segment.

**Fix:** Add `forcePathStyle: true` to your `S3Client` configuration:

```typescript
const client = new S3Client({
  forcePathStyle: true, // required for Neon Object Storage
  // ...
});
```

Without this, the AWS SDK for JavaScript uses virtual-hosted-style addressing (`my-bucket.storage.example.com/key`) which Neon Object Storage doesn't support.

### SigV2 errors

If you see signature-related errors mentioning `AWS2` or `AWSAccessKeyId`, your client is using the older AWS Signature Version 2.

**Fix:** Use AWS Signature Version 4 (SigV4). The AWS SDK v3 for JavaScript and boto3 use SigV4 by default. If you're using an older SDK or a custom HTTP client, update it or configure it to use SigV4 explicitly.

## Access level errors

### Anonymous GET returns `403 AccessDenied`

The bucket's access level is `private` (the default), which requires authentication for all reads.

**Fix:** If the bucket should allow public reads, set its access level to `public_read` using the Neon Console or API. See [Access levels](https://neon.com/docs/storage/buckets#access-levels).

**Note:** You cannot change access level via the S3 API. `PutBucketAcl` returns `501 Not Implemented`.

## S3 operation errors

### `501 Not Implemented`

You are calling an S3 operation that Neon Object Storage does not support.

**Common causes:**

- `PutBucketAcl` or `PutBucketPolicy`: use the Neon Console or API to set bucket access level instead
- `PutBucketNotificationConfiguration`: event notifications are not supported
- `PutBucketLogging`: server-side access logging is not supported

See [S3 compatibility](https://neon.com/docs/storage/s3-compatibility#not-supported) for the full list of unsupported operations.

### Lifecycle rules not running

`PutBucketLifecycle` succeeds and the configuration is stored, but expiration and transition rules do not execute.

**Status:** Lifecycle enforcement isn't available yet. The API accepts and echoes the configuration so tools that read lifecycle rules will work, but the rules have no effect.

### `EntityTooLarge`

The object exceeds the maximum size. Neon Object Storage allows objects up to 5 GiB in a single request and up to 10 GiB with [multipart upload](https://neon.com/docs/storage/objects#multipart-upload). A single-request `PutObject` over 5 GiB fails immediately; a multipart upload fails at `CompleteMultipartUpload` once the assembled object would exceed 10 GiB.

**Fix:** For an object between 5 GiB and 10 GiB, use multipart upload. For anything larger, split the data across multiple objects, or confirm the upload isn't unexpectedly large. [Contact support](https://neon.com/docs/introduction/support) if you need to store larger objects.

## Connection and performance errors

### `503 Service Unavailable` (SlowDown)

The request exceeded a rate limit. The S3 error code is `SlowDown`. This is a rate limit signal, not a server error. The storage service is healthy.

**Fix:** Implement exponential backoff and retry. Don't treat `SlowDown` as a fatal error. The response may include a `Retry-After` header indicating how long to wait. AWS SDKs handle this automatically when retry logic is enabled. If you're hitting this consistently, [let us know](https://neon.com/docs/introduction/support) and we can look into raising your limit.

### Large downloads timing out mid-stream

The connection drops during a large object download.

**Fix:** Use range requests to download large objects in chunks:

```typescript
// Download in 10 MiB chunks
const chunkSize = 10 * 1024 * 1024;
let start = 0;
let totalSize: number | undefined;

// ContentLength is the size of each chunk, not the whole object, so parse
// the object's total size from Content-Range ("bytes start-end/total")
// instead and stop once start reaches it.
while (totalSize === undefined || start < totalSize) {
  const response = await client.send(new GetObjectCommand({
    Bucket: 'my-bucket',
    Key: 'large-file.zip',
    Range: `bytes=${start}-${start + chunkSize - 1}`,
  }));
  // process response.Body
  totalSize = Number(response.ContentRange?.split('/')[1]);
  start += chunkSize;
}
```

--- [Document source](https://neon.com/docs/workflows/claimable-database-integration.md) ---

> Summary: The Neon project transfer API lets you provision a Postgres database, generate a time-limited transfer request, and send the user a claim URL. The user takes full ownership without losing the original connection string. Use this pattern for SaaS onboarding flows, agency handoffs, or demo environments where instant database access must precede account creation. The feature is in private preview and does not support transferring projects into Vercel-managed Neon organizations.

# Claimable database integration guide

Manage Neon projects for users with the project database claim API

Last updated: 2026-08-25

## Overview

The project transfer functionality enables you to provision fully-configured Postgres databases on behalf of your users and transfer ownership when ready. This capability eliminates the technical overhead of database setup while ensuring your users maintain complete control of their database resources.

> **Availability Status**
>
> This feature is available in private preview only. To enable this functionality for your account, [contact our partnership team](https://neon.com/partners#partners-apply).

## Simplified workflow

1. **Create a Neon project** on behalf of your user in your account or organization
   - This provides them with a Postgres connection string for their application immediately

2. **Create a transfer request** for the project
   - This generates a unique, time-limited transfer request ID

3. **Share a claim URL** with your user
   - This URL contains the project ID and transfer request ID

4. **User claims the project**
   - When they click the URL, Neon prompts them to transfer the project to their account

## Step-by-step guide

## Create a Neon project

Use the Neon [create project API](https://neon.com/docs/reference/api/projects/create-project) to create a new project that you intend to transfer to your user.

The minimum request body is `project: {}` as all settings are optional.

### API endpoint

```http
POST https://console.neon.tech/api/v2/projects
```

### Example request

```bash
curl -X POST 'https://console.neon.tech/api/v2/projects' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {your_api_key_here}' \
  --header 'Content-Type: application/json' \
  --data '{
    "project": {
      "name": "new-project-name",
      "region_id": "aws-us-east-1",
      "pg_version": 17,
      "org_id": "org-cool-breeze-12345678"
    }
  }'
```

This creates a new project with:

- A default branch named `main`
- A default database named `neondb`
- A default database role named `neondb_owner`
- A project named `new-project-name` (defaults to the project ID if not specified)
- The project in the `org-cool-breeze-12345678` organization
- PostgreSQL version 17 in the `aws-us-east-1` region (these settings are permanent)

### Example response

Below is an abbreviated example of the response. For brevity, this documentation shows only key fields. For the complete response structure and all possible fields, see the [API documentation](https://neon.com/docs/reference/api/projects/create-project).

```json
{
  "project": {
    "id": "your-project-id",
    "name": "new-project-name",
    "owner_id": "org-the-owner-id",
    "org_id": "org-the-owner-id"
  },
  "connection_uris": [
    {
      "connection_uri": "postgresql://neondb_owner:{password}@ep-cool-shape-123456.us-east-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require"
    }
  ],
  "branch": {},
  "databases": [{}],
  "endpoints": [{}],
  "operations": [{}],
  "roles": [{}]
}
```

Your user will need the connection string from the response (`connection_uri`) to [connect to the Neon database](https://neon.com/docs/get-started/connect-neon). The `{password}` placeholder represents the actual password generated for the database. You'll also use the project `id` to create a transfer request.

## Create a transfer request

With your project created, use the Neon [project transfer request API](https://neon.com/docs/reference/api/projects/create-project-transfer-request) to generate a transfer request. You can create this request immediately or at a later time when you're ready to transfer the project. Each transfer request has a configurable expiration period, specified by the `ttl_seconds` parameter.

### API endpoint

```http
POST https://console.neon.tech/api/v2/projects/{project_id}/transfer_requests
```

### Example request

```bash
curl -X POST 'https://console.neon.tech/api/v2/projects/{project_id}/transfer_requests' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {your_api_key_here}' \
  --header 'Content-Type: application/json' \
  --data '{
    "ttl_seconds": 604800
  }'
```

This example sets a one-week expiration (604,800 seconds). The default is 86,400 seconds (24 hours).

### Example response

```json
{
  "id": "389ad814-9514-1cac-bc04-2f194815db76",
  "project_id": "your-project-id",
  "created_at": "2025-05-18T19:35:23Z",
  "expires_at": "2025-05-25T19:35:23Z"
}
```

If transfer requests are not enabled for your account, you'll receive:

```json
{
  "request_id": "cb1e1228-19f9-4904-8bd5-2dbf17d911a2",
  "code": "",
  "message": "project transfer requests are not enabled for this account"
}
```

## Share the claim URL

Construct a claim URL to share with your user using the following format:

```http
https://console.neon.tech/app/claim?p={project_id}&tr={transfer_request_id}&ru={redirect_url}
```

Where:

- `p={project_id}` - The project ID being transferred
- `tr={transfer_request_id}` - The transfer request `id` from the previous step
- `ru={redirect_url}` (optional) - A URL-encoded destination where the user is redirected after successfully claiming the project
  - Without this parameter, users remain on the Neon project page after claiming
  - This allows your application to detect successful claims when users return to your site, enabling you to trigger next steps in your onboarding flow

### User communication

When sharing the claim URL, inform your user that:

- They'll need a Neon account to claim the project (they can create one during the claim process)
- The link will expire at the time shown in the `expires_at` field
- After claiming, they'll have full ownership of the project
- The database connection string remains unchanged (though they should update the password for security)

## User claims the project

### Via browser (recommended)

When your user clicks the claim URL:

1. Neon prompts them to log in or create an account
2. After authentication, Neon displays a confirmation screen
3. They select their destination Neon organization
4. Upon confirmation, Neon transfers the project
5. The user is then:
   - Redirected to your application if `ru` parameter was provided, allowing you to detect the successful claim and continue your onboarding flow
   - Kept on the Neon project page if no redirect URL was specified

### Via API

Alternatively, users can accept the transfer request programmatically using the [accept project transfer request API](https://neon.com/docs/reference/api/projects/accept-project-transfer-request).

#### API endpoint

```http
PUT https://console.neon.tech/api/v2/projects/{project_id}/transfer_requests/{request_id}
```

#### Example request (transfer to organization)

```bash
curl -X PUT 'https://console.neon.tech/api/v2/projects/{project_id}/transfer_requests/{request_id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {users_api_key_here}' \
  --header 'Content-Type: application/json' \
  --data '{
    "org_id": "org-cool-breeze-12345678"
  }'
```

Without the `org_id` parameter, the project transfers to the user's personal account. With it, the project transfers to the specified organization where the user has membership.

## Important notes

### Transfer request behavior

- **Expiration**: Requests expire after the specified `ttl_seconds` (default: 24 hours). Once expired, you must create a new transfer request
- **One-time use**: Each transfer request can only be used once
- **Already claimed**: If a project has already been claimed, subsequent attempts will fail with an error
- **Vercel orgs not supported**: Transferring a project into a Vercel-managed Neon [organization](https://neon.com/docs/reference/glossary#organization) via the claim flow is not supported, meaning that if you created your Neon account through the [Vercel-managed integration](https://neon.com/docs/guides/vercel-managed-integration), you cannot claim projects into the Neon organization created by that integration.

### Security considerations

- **URL security**: Share claim URLs through secure channels as anyone with the URL can claim the project
- **Password rotation**: Instruct users to change their database password immediately after claiming
- **Access revocation**: Once transferred, you lose all access to the project unless the new owner grants permissions

### Technical details

- **Connection persistence**: Database connection strings remain valid after transfer
- **Organization transfers**: Users must be members of the target organization
- **Organization ID format**: `org-[descriptive-term]-[numeric-id]` (for example, `org-cool-breeze-12345678`)
- **Vercel organization limitation**: Projects cannot be claimed into Vercel organizations

## Example use cases

- **SaaS applications** - Provision databases for your SaaS users that they can later claim and manage
- **Development agencies** - Create database projects for clients and transfer ownership upon project completion
- **Educational platforms** - Set up pre-configured database environments for students
- **Demo environments** - Create ready-to-use demo databases that prospects can claim
- **Team environments** - Provision project databases for team members to claim into their organization

For a working implementation, try [Claimable Neon](https://neon.com/claimable-neon). Agents fetch [`auth.md`](https://neon.com/auth.md), receive project-scoped credentials, and hand a claim link to a human. The registration response provides the project expiration time. See the [Claimable Neon reference](https://neon.com/docs/reference/claimable-neon) for CLI commands.

## Troubleshooting

| Issue                                 | Solution                                                                                                        |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Claim URL expired                     | Create a new transfer request and generate a new claim URL                                                      |
| User receives error when claiming     | Verify the project exists and the transfer request hasn't been used                                             |
| Project doesn't appear after claiming | Refresh the Neon Console or log out and back in                                                                 |
| "Transfer requests not enabled" error | [Contact our partnership team](https://neon.com/partners#partners-apply) to enable this private preview feature |
| Organization transfer fails           | Verify user membership in the target organization and correct `org_id` format                                   |
| Already claimed error                 | The transfer request has been used; create a new one if needed                                                  |

## Further resources

- [Create project API reference](https://neon.com/docs/reference/api/projects/create-project)
- [Create project transfer request API reference](https://neon.com/docs/reference/api/projects/create-project-transfer-request)
- [Accept project transfer request API reference](https://neon.com/docs/reference/api/projects/accept-project-transfer-request)
- [Neon API documentation](https://neon.com/docs/reference/api)
- [Managing projects](https://neon.com/docs/manage/projects)
- [Managing API keys](https://neon.com/docs/manage/api-keys)
- [Managing organizations](https://neon.com/docs/manage/organizations)

--- [Document source](https://neon.com/docs/workflows/data-anonymization-api.md) ---

> Summary: The Neon data anonymization REST API provides endpoints for creating PostgreSQL Anonymizer-backed branches and managing per-column masking rules via `masking_function` or `masking_value` parameters. Use this reference when automating PII redaction in CI/CD pipelines or scripting sensitive-data workflows. The PATCH masking-rules endpoint replaces all rules atomically, so callers must include every existing rule when adding one. Anonymized branches cannot be restored or have their read-write endpoint deleted.

# Data anonymization API reference

API endpoints for managing anonymized branches and masking rules

Last updated: 2026-07-15

This page provides detailed API documentation for data anonymization. For conceptual overview and usage instructions, see [Data Anonymization](https://neon.com/docs/workflows/data-anonymization).

The Neon API provides comprehensive control over anonymized branches, including access to all PostgreSQL Anonymizer masking functions and the ability to export/import masking rules for management outside of Neon.

## Create anonymized branch

[→ API Reference](https://neon.com/docs/reference/api/branches/create-project-branch-anonymized)

```
POST /projects/{project_id}/branch_anonymized
```

Creates a new branch with anonymized data using PostgreSQL Anonymizer for static masking.

**Request body parameters:**

- `masking_rules` (optional): Array of masking rules to apply to the branch. Each rule specifies:
  - `database_name`: Target database
  - `schema_name`: Target schema (typically `public`)
  - `table_name`: Table containing sensitive data
  - `column_name`: Column to mask
  - `masking_function` (optional): Dynamic PostgreSQL expression (for example, `anon.fake_email()` or `pg_catalog.concat(anon.dummy_uuidv4(), '@example.com')`). Use for realistic test data. You can combine `pg_catalog.*` functions with PostgreSQL Anonymizer functions for custom expressions. Mutually exclusive with `masking_value`.
  - `masking_value` (optional): Static literal value (for example, `'REDACTED'`, `0`, `NULL`). Use for simple redaction. Mutually exclusive with `masking_function`.
- `start_anonymization` (optional): Set to `true` to automatically start anonymization after creation

**Example request:**

```bash
curl -X POST \
  'https://console.neon.tech/api/v2/projects/{project_id}/branch_anonymized' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "masking_rules": [
      {
        "database_name": "neondb",
        "schema_name": "public",
        "table_name": "users",
        "column_name": "email",
        "masking_function": "pg_catalog.concat(anon.dummy_uuidv4(), '@example.com')"
      },
      {
        "database_name": "neondb",
        "schema_name": "public",
        "table_name": "users",
        "column_name": "age",
        "masking_function": "anon.random_int_between(25,65)"
      }
    ],
    "start_anonymization": true
  }'
```

<details>

<summary>Response body</summary>

Returns the created branch object with `restricted_actions` indicating operations not allowed on anonymized branches (restore and delete read-write endpoint).

```json
{
  "branch": {
    "id": "br-divine-feather-a1b2c3d4",
    "project_id": "purple-moon-12345678",
    "parent_id": "br-plain-hill-e5f6g7h8",
    "parent_lsn": "0/1C3C998",
    "name": "br-divine-feather-a1b2c3d4",
    "current_state": "init",
    "pending_state": "ready",
    "state_changed_at": "2025-10-16T02:58:58Z",
    "creation_source": "console",
    "primary": false,
    "default": false,
    "protected": false,
    "cpu_used_sec": 0,
    "compute_time_seconds": 0,
    "active_time_seconds": 0,
    "written_data_bytes": 0,
    "data_transfer_bytes": 0,
    "created_at": "2025-10-16T02:58:58Z",
    "updated_at": "2025-10-16T02:58:58Z",
    "init_source": "parent-data",
    "restricted_actions": [
      {
        "name": "restore",
        "reason": "cannot restore anonymized branches"
      },
      {
        "name": "delete-rw-endpoint",
        "reason": "cannot delete read-write endpoints for anonymized branches"
      }
    ]
  },
  "endpoints": [
    {
      "host": "ep-fragrant-breeze-a1b2c3d4.us-east-1.aws.neon.tech",
      "id": "ep-fragrant-breeze-a1b2c3d4",
      "project_id": "purple-moon-12345678",
      "branch_id": "br-divine-feather-a1b2c3d4",
      "autoscaling_limit_min_cu": 1,
      "autoscaling_limit_max_cu": 4,
      "region_id": "aws-us-east-1",
      "type": "read_write",
      "current_state": "init",
      "pending_state": "active",
      "settings": {
        "preload_libraries": {
          "use_defaults": false,
          "enabled_libraries": ["anon"]
        }
      },
      "pooler_enabled": false,
      "pooler_mode": "transaction",
      "disabled": false,
      "passwordless_access": true,
      "creation_source": "console",
      "created_at": "2025-10-16T02:58:58Z",
      "updated_at": "2025-10-16T02:58:58Z",
      "proxy_host": "us-east-1.aws.neon.tech",
      "suspend_timeout_seconds": 0,
      "provisioner": "k8s-neonvm"
    }
  ],
  "operations": [
    {
      "id": "262dc2ba-4d78-4b7b-bb9a-e29532385f3a",
      "project_id": "purple-moon-12345678",
      "branch_id": "br-divine-feather-a1b2c3d4",
      "action": "create_branch",
      "status": "running",
      "failures_count": 0,
      "created_at": "2025-10-16T02:58:58Z",
      "updated_at": "2025-10-16T02:58:58Z",
      "total_duration_ms": 0
    },
    {
      "id": "f9f52b52-9828-47e4-9842-c08c2a9c14d3",
      "project_id": "purple-moon-12345678",
      "branch_id": "br-divine-feather-a1b2c3d4",
      "endpoint_id": "ep-fragrant-breeze-a1b2c3d4",
      "action": "start_compute",
      "status": "scheduling",
      "failures_count": 0,
      "created_at": "2025-10-16T02:58:58Z",
      "updated_at": "2025-10-16T02:58:58Z",
      "total_duration_ms": 0
    }
  ],
  "roles": [
    {
      "branch_id": "br-divine-feather-a1b2c3d4",
      "name": "neondb_owner",
      "protected": false,
      "created_at": "2025-09-12T13:47:59Z",
      "updated_at": "2025-09-12T13:47:59Z"
    }
  ],
  "databases": [
    {
      "id": 21560101,
      "branch_id": "br-divine-feather-a1b2c3d4",
      "name": "neondb",
      "owner_name": "neondb_owner",
      "created_at": "2025-09-12T13:47:59Z",
      "updated_at": "2025-09-12T13:47:59Z"
    }
  ],
  "connection_uris": [
    {
      "connection_uri": "postgresql://neondb_owner:somepass@ep-fragrant-breeze-a1b2c3d4.us-east-1.aws.neon.tech/neondb?sslmode=require",
      "connection_parameters": {
        "database": "neondb",
        "password": "somepass",
        "role": "neondb_owner",
        "host": "ep-fragrant-breeze-a1b2c3d4.us-east-1.aws.neon.tech",
        "pooler_host": "ep-fragrant-breeze-a1b2c3d4-pooler.us-east-1.aws.neon.tech"
      }
    }
  ]
}
```

</details>

## Get anonymization status

[→ API Reference](https://neon.com/docs/reference/api/branches/get-anonymized-branch-status)

```
GET /projects/{project_id}/branches/{branch_id}/anonymized_status
```

Retrieves the current status of an anonymized branch, including state and progress information.

**Example request:**

```bash
curl -X GET \
  'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/anonymized_status' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Accept: application/json'
```

<details>

<summary>Response body</summary>

**State values:** `created`, `initialized`, `initialization_error`, `anonymizing`, `anonymized`, `error`. Response may include `failed_at` timestamp if operation failed.

```json
{
  "branch_id": "br-aged-salad-637688",
  "project_id": "simple-truth-637688",
  "state": "anonymizing",
  "status_message": "Anonymizing table mydb.public.users (3/5)",
  "created_at": "2022-11-30T18:25:15Z",
  "updated_at": "2022-11-30T18:30:22Z"
}
```

</details>

## Start anonymization

[→ API Reference](https://neon.com/docs/reference/api/branches/start-anonymization)

```
POST /projects/{project_id}/branches/{branch_id}/anonymize
```

Starts or restarts the anonymization process for branches in `initialized`, `error`, or `anonymized` state. Applies all defined masking rules.

**Example request:**

```bash
curl -X POST \
  'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/anonymize' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Accept: application/json'
```

<details>

<summary>Response body</summary>

```json
{
  "branch_id": "br-shiny-butterfly-w4393738",
  "project_id": "wild-sky-00366102",
  "state": "anonymized",
  "status_message": "Anonymization completed successfully (2 tables, 3 masking rules applied)",
  "created_at": "2025-11-01T14:01:39Z",
  "updated_at": "2025-11-01T14:01:41Z"
}
```

</details>

## Get masking rules

[→ API Reference](https://neon.com/docs/reference/api/branches/get-masking-rules)

```
GET /projects/{project_id}/branches/{branch_id}/masking_rules
```

Retrieves all masking rules defined for the specified anonymized branch.

**Example request:**

```bash
curl -X GET \
  'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/masking_rules' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Accept: application/json'
```

<details>

<summary>Response body</summary>

```json
{
  "masking_rules": [
    {
      "database_name": "neondb",
      "schema_name": "public",
      "table_name": "users",
      "column_name": "age",
      "masking_function": "anon.random_int_between(25,65)"
    },
    {
      "database_name": "neondb",
      "schema_name": "public",
      "table_name": "users",
      "column_name": "email",
      "masking_function": "anon.dummy_free_email()"
    }
  ]
}
```

</details>

## Update masking rules

[→ API Reference](https://neon.com/docs/reference/api/branches/update-masking-rules)

```
PATCH /projects/{project_id}/branches/{branch_id}/masking_rules
```

Updates masking rules for the specified anonymized branch. After updating, use the start anonymization endpoint to apply changes.

**Important:** The API replaces all masking rules with the provided array. To add a new rule, include all existing rules in your request.

**Example request:**

```bash
curl -X PATCH \
  'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/masking_rules' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "masking_rules": [
      {
        "database_name": "neondb",
        "schema_name": "public",
        "table_name": "users",
        "column_name": "email",
        "masking_function": "anon.dummy_free_email()"
      }
    ]
  }'
```

<details>

<summary>Response body</summary>

Returns the updated list of masking rules for the branch.

```json
{
  "masking_rules": [
    {
      "database_name": "neondb",
      "schema_name": "public",
      "table_name": "users",
      "column_name": "email",
      "masking_function": "anon.dummy_free_email()"
    }
  ]
}
```

</details>

--- [Document source](https://neon.com/docs/workflows/data-anonymization-github-actions.md) ---

> Summary: The Neon Create Branch GitHub Action (`neondatabase/create-branch-action`) creates an anonymized Postgres branch in a single step by accepting a `masking_rules` JSON array that maps columns to PostgreSQL Anonymizer masking functions. Use this when you need to provision a masked branch automatically on pull request events, rather than configuring masking rules manually in the Neon Console. The workflow requires `NEON_PROJECT_ID` and `NEON_API_KEY` secrets, and a companion `delete-branch-action` workflow can clean up anonymized branches when PRs close.

# Data anonymization with GitHub Actions

Automate anonymized branch creation in your CI/CD pipeline

Last updated: 2026-06-05

This page shows how to automate data anonymization with GitHub Actions. For conceptual overview and usage instructions, see [Data Anonymization](https://neon.com/docs/workflows/data-anonymization).

Automate anonymized branch creation using the [Neon Create Branch Action](https://github.com/neondatabase/create-branch-action). The `masking_rules` input lets you define masking rules directly in your workflow, creating an anonymized branch in a single step.

## Requirements

Before setting up the workflow:

- A **Neon project** with a populated parent branch
- The following GitHub repository secrets:
  - `NEON_PROJECT_ID`
  - `NEON_API_KEY`

**Tip:** The Neon GitHub integration configures these secrets automatically. See [Neon GitHub integration](https://neon.com/docs/guides/neon-github-integration).

## Set up the workflow

Create a file at `.github/workflows/create-anon-branch.yml` with the following content:

```yaml
name: Create Anonymized Branch for PR

on:
  pull_request:
    types: [opened, reopened]

jobs:
  create-anon-branch:
    runs-on: ubuntu-latest
    steps:
      - name: Create anonymized branch
        uses: neondatabase/create-branch-action@v6
        id: create-branch
        with:
          project_id: ${{ secrets.NEON_PROJECT_ID }}
          branch_name: anon-pr-${{ github.event.number }}
          api_key: ${{ secrets.NEON_API_KEY }}
          masking_rules: |
            [
              {
                "database_name": "neondb",
                "schema_name": "public",
                "table_name": "users",
                "column_name": "email",
                "masking_function": "anon.dummy_free_email()"
              },
              {
                "database_name": "neondb",
                "schema_name": "public",
                "table_name": "users",
                "column_name": "first_name",
                "masking_function": "anon.fake_first_name()"
              },
              {
                "database_name": "neondb",
                "schema_name": "public",
                "table_name": "users",
                "column_name": "last_name",
                "masking_function": "anon.fake_last_name()"
              }
            ]

      - name: Output branch details
        run: |
          echo "Branch ID: ${{ steps.create-branch.outputs.branch_id }}"
          echo "Database URL: ${{ steps.create-branch.outputs.db_url }}"
```

The `masking_rules` input accepts a JSON array where each rule specifies:

| Field              | Description                             |
| ------------------ | --------------------------------------- |
| `database_name`    | Target database (for example, `neondb`) |
| `schema_name`      | Target schema (typically `public`)      |
| `table_name`       | Table containing sensitive data         |
| `column_name`      | Column to mask                          |
| `masking_function` | PostgreSQL Anonymizer function to apply |

For available masking functions, see [PostgreSQL Anonymizer documentation](https://postgresql-anonymizer.readthedocs.io/en/latest/masking_functions/) or the [Manage masking rules](https://neon.com/docs/workflows/data-anonymization#manage-masking-rules) section of the main guide.

**Note:** The `masking_rules` input creates a new anonymized branch. Masking rules cannot be applied to existing branches.

## Testing the workflow

1. Customize and push the workflow file to your repository
2. Open a new pull request
3. Check the **Actions** tab to monitor workflow execution
4. Verify the anonymized branch in the Neon Console or connect to it to confirm data is masked

## Clean up branches

Clean up anonymized branches when no longer needed. Automate this with the [delete-branch-action](https://github.com/neondatabase/delete-branch-action) when PRs close:

```yaml
name: Delete Branch on PR Close

on:
  pull_request:
    types: closed

jobs:
  delete-branch:
    runs-on: ubuntu-latest
    steps:
      - name: Delete anonymized branch
        uses: neondatabase/delete-branch-action@v3
        with:
          project_id: ${{ secrets.NEON_PROJECT_ID }}
          branch: anon-pr-${{ github.event.number }}
          api_key: ${{ secrets.NEON_API_KEY }}
```

--- [Document source](https://neon.com/docs/workflows/data-anonymization.md) ---

> Summary: Anonymized branches permanently replace PII in a branch copy using static masking via the PostgreSQL Anonymizer extension. The parent branch data remains unchanged. Use this when you need production-realistic test data without exposing sensitive information in development or CI/CD pipelines. Masking rules are configured per branch through the Console, REST API, or SQL SECURITY LABEL commands. Foreign key columns cannot be masked directly, and the branch is unavailable while anonymization runs.

# Data anonymization

Mask sensitive data in development branches using PostgreSQL Anonymizer

Last updated: 2026-09-25

**Note: Beta**

This feature is in beta. Please give us [Feedback](https://console.neon.tech/app/projects?modal=feedback) from the Neon Console or by connecting with us on [Discord](https://neon.com/discord). For more ways to reach us, see [Send feedback](https://neon.com/docs/introduction/feedback).

Need to test against production data without exposing sensitive information? Anonymized branches let you create development copies with masked personally identifiable information (PII) - such as emails, phone numbers, and other sensitive data.

Neon uses [PostgreSQL Anonymizer](https://postgresql-anonymizer.readthedocs.io/) for static data masking, and applies masking rules when you create or update the branch. This approach gives you realistic test data while protecting user privacy and supporting compliance requirements like GDPR.

**Key characteristics:**

- **Static masking**: Data is masked once during branch creation or when you rerun anonymization
- **PostgreSQL Anonymizer integration**: Uses the [PostgreSQL Anonymizer extension's](https://neon.com/docs/extensions/postgresql-anonymizer) masking functions
- **Branch-specific rules**: You can define different masking rules for each anonymized Neon branch

**Info: Static versus dynamic masking**

This feature uses **static masking**, which permanently transforms data in the branch when anonymization runs. Unlike dynamic masking (which masks data during queries), static masking creates an actual masked copy of the data. To get fresh data from the parent, create a new anonymized branch.

## Create a branch with anonymized data

**Console**

To create a branch with anonymized data from the Neon Console:

1. Select your project.
2. Select **Branches** in the sidebar.
3. Click **New branch** to open the branch creation dialog.
   ![Neon Console 'Create new branch' dialog with 'Anonymized data' selected](https://neon.com/docs/workflows/anon-create-a-new-branch.png)
4. Select a **Parent branch**. This determines the origin of the schema and data for your new branch. By default, your project's default branch (named `main` if the project was created with the CLI or API, or `production` if created in the Console) is selected, but you can choose any existing branch in your project.
5. Specify a branch name, or leave it blank to use the default generated name.
6. Select the **Anonymized data** option.
7. Configure auto-deletion: By default, **Automatically delete branch after** is checked with 1 day selected to help prevent unused branches from accumulating. You can choose 1 hour, 1 day, or 7 days, or uncheck to disable expiration entirely. This is useful for CI/CD pipelines and short-lived development environments. Note: This default only applies when creating branches through the Console; API branches have no expiration by default. Refer to our [Branch expiration guide](https://neon.com/docs/guides/branch-expiration) for details.
8. Click **Create** to create your anonymized branch.

After creation, the Console loads the [Data Masking](https://neon.com/docs/workflows/data-anonymization#manage-masking-rules) page where you define and execute anonymization rules for your branch.

**API**

Use the [Create anonymized branch](https://neon.com/docs/reference/api/branches/create-project-branch-anonymized) endpoint, for example:

```bash
curl -X POST \
  'https://console.neon.tech/api/v2/projects/{project_id}/branch_anonymized' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "masking_rules": [
      {
        "database_name": "neondb",
        "schema_name": "public",
        "table_name": "users",
        "column_name": "email",
        "masking_function": "anon.dummy_free_email()"
      }
    ],
    "start_anonymization": true
  }'
```

For complete parameter documentation and additional examples, see [Create anonymized branch](https://neon.com/docs/workflows/data-anonymization-api#create-anonymized-branch) in the API reference. The API supports all PostgreSQL Anonymizer masking functions, providing more options than the Console UI. You can also export and import masking rules to manage them outside of Neon.

## How anonymization works

When you create a branch with anonymized data:

1. Neon creates a new branch with the schema and data from the parent branch.
2. You define masking rules for tables and columns containing sensitive data. You can use any combination of these methods:
   - **Console**: The Data Masking page opens automatically after branch creation.
   - **API**: Include masking rules in the creation request or add them later via the masking rules endpoint.
   - **SQL**: Connect to the branch (after initial anonymization) and use `SECURITY LABEL` commands.
3. You apply the masking rules (in Console, click **Apply masking rules**; via API, call the [start anonymization endpoint](https://neon.com/docs/workflows/data-anonymization-api#start-anonymization)), and the PostgreSQL Anonymizer extension masks the branch data.
4. You can update rules and rerun anonymization on the branch as needed.

The parent branch data remains unchanged. Rerunning anonymization applies rules to the branch's current (already masked) data, not fresh data from the parent.

**Note:** The branch is unavailable for connections while anonymization is in progress.

## Manage masking rules

You can create and manage masking rules via the Console, API, or SQL. All three methods are interchangeable and produce equivalent results.

**Console**

From the **Data Masking** page:

1. Select the schema, table, and column you want to mask.
2. Choose a masking function from the dropdown list (for example, **Dummy Free Email** to execute `anon.dummy_free_email()`). The Console provides a curated list of common functions. For the full set of PostgreSQL Anonymizer functions, you must use the API or SQL.

**Tip:** For email columns with unique constraints, use **Random Unique Email**, which generates UUID-based emails that maintain uniqueness while preserving the email format.

**Note: usage notes**

- Foreign key columns cannot be masked directly to maintain referential integrity. If you attempt to mask a foreign key column, the Console will display an alert with a "Go to primary key" action that navigates to the corresponding primary key column where you can apply masking rules. Primary key columns can be anonymized. Neon automatically handles foreign key constraints during the anonymization process to maintain referential integrity across related tables.
- If you've defined custom masking rules via the API or SQL (such as custom PostgreSQL expressions like `pg_catalog.concat(anon.dummy_uuidv4(), '@customdomain.com')` that aren't available in the Console's dropdown), these rules will display as text in the Console showing the underlying expression. The Console preserves these custom rules when you run anonymization. You can safely mix Console, API, and SQL workflows.

3. Repeat for all sensitive columns.
4. When you are ready, click **Apply masking rules** to start the anonymization job. You can monitor its progress on this page or via the [API](https://neon.com/docs/workflows/data-anonymization-api#get-anonymization-status).

![Neon Console 'data masking' dialog with example masking functions configured](https://neon.com/docs/workflows/anon-data-masking.png)

**Important:** Rerunning the anonymization process on the anonymized branch applies rules to previously anonymized data, not fresh data from the parent branch. To start from the parent's original data, create a new anonymized branch.

**API**

For complete API documentation with request/response examples, see the [Data anonymization API reference](https://neon.com/docs/workflows/data-anonymization-api). Note that the Console uses friendly labels for masking functions (for example, **Random Unique Email**), but the API returns and accepts the underlying PostgreSQL expressions (for example, `pg_catalog.concat(anon.dummy_uuidv4(), '@example.com')`).

**Update masking rules**

```bash
PATCH /projects/{project_id}/branches/{branch_id}/masking_rules
```

Example request to mask an email column:

```bash
curl -X PATCH \
  'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/masking_rules' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "masking_rules": [{
      "database_name": "neondb",
      "schema_name": "public",
      "table_name": "users",
      "column_name": "email",
      "masking_function": "anon.dummy_free_email()"
    }]
  }'
```

**Important:** The API replaces all masking rules with the provided array. To add a new rule, include all existing rules in your request.

**Start anonymization**

```bash
POST /projects/{project_id}/branches/{branch_id}/anonymize
```

**Get anonymization status**

```bash
GET /projects/{project_id}/branches/{branch_id}/anonymized_status
```

**SQL**

You can create masking rules directly using PostgreSQL Anonymizer's `SECURITY LABEL` syntax. This requires connecting to your anonymized branch after it has reached the `anonymized` state (create and run initial rules via Console or API first).

Example creating a masking rule for an email column:

```sql
SECURITY LABEL FOR anon ON COLUMN users.email
IS 'MASKED WITH FUNCTION anon.dummy_free_email()';
```

Remove a masking rule:

```sql
SECURITY LABEL FOR anon ON COLUMN users.email IS NULL;
```

**Note:** After creating or modifying rules via SQL, use the Console or API to run anonymization. Rules using standard functions appear normally in the Console; custom functions appear as text.

## Retrieve masking rules

You can view existing masking rules via the Console, API, or SQL.

**Console**

From the **Data Masking** page, all defined masking rules are displayed for each table and column. Rules using standard functions appear as dropdown selections, while custom rules (functions not available in the Console dropdown) appear as text showing the underlying PostgreSQL expression.

**API**

Use the [Get masking rules](https://neon.com/docs/reference/api/branches/get-masking-rules) endpoint:

```bash
curl -X GET \
  'https://console.neon.tech/api/v2/projects/{project_id}/branches/{branch_id}/masking_rules' \
  -H 'Authorization: Bearer $NEON_API_KEY' \
  -H 'Accept: application/json'
```

Example response:

```json
{
  "masking_rules": [
    {
      "database_name": "neondb",
      "schema_name": "public",
      "table_name": "users",
      "column_name": "email",
      "masking_function": "anon.dummy_free_email()"
    },
    {
      "database_name": "neondb",
      "schema_name": "public",
      "table_name": "users",
      "column_name": "phone",
      "masking_function": "anon.partial(phone, 2, 'XXX-XXXX', 2)"
    },
    {
      "database_name": "neondb",
      "schema_name": "public",
      "table_name": "users",
      "column_name": "address",
      "masking_value": "'CONFIDENTIAL'"
    }
  ]
}
```

The API returns all rules regardless of how they were created (Console, API, or SQL). Rules can use either `masking_function` (for dynamic masking) or `masking_value` (for static values).

**SQL**

Connect to your anonymized branch and query the `anon.pg_masking_rules` view:

```sql
SELECT relnamespace, relname, attname, masking_function, masking_value
FROM anon.pg_masking_rules
ORDER BY relname, attname;
```

Example result:

```
 relnamespace | relname | attname |       masking_function        | masking_value
--------------+---------+---------+-------------------------------+---------------
 public       | users   | address |                               | 'CONFIDENTIAL'
 public       | users   | email   | anon.dummy_free_email()       |
 public       | users   | phone   | anon.partial(phone, 2, 'XXX-XXXX', 2) |
```

This query returns all rules regardless of how they were created (Console, API, or SQL). Rules defined with `MASKED WITH FUNCTION` populate `masking_function`, while rules defined with `MASKED WITH VALUE` populate `masking_value`.

## Common workflow

1. Create an anonymized branch from your production branch.
2. Define masking rules for sensitive columns (emails, names, addresses, etc.).
3. Apply the masking rules.
4. [Connect](https://neon.com/docs/connect/connect-from-any-app) your development environment to the anonymized branch.
5. When you need fresh data, create a new anonymized branch.

## Limitations

- Currently cannot reset to parent, restore, or delete the read-write endpoint for anonymized branches.
- Branch is unavailable during anonymization.
- Masking does not fully enforce database constraints, but improvements are ongoing. For example, use **Random Unique Email** for columns with unique constraints on emails.
- **Foreign key columns cannot be masked directly.** To maintain referential integrity, mask the corresponding primary key column instead. Neon automatically handles foreign key constraints during anonymization, temporarily modifying them to cascade updates and restoring them to their original state after the process completes. The Console displays an alert with a "Go to primary key" action that navigates to the relevant primary key column.
- The Console provides a curated subset of masking functions for creation. Use the API or SQL for all [PostgreSQL Anonymizer masking functions](https://postgresql-anonymizer.readthedocs.io/en/latest/masking_functions/).

## Related resources

- [Data Anonymization API Reference](https://neon.com/docs/workflows/data-anonymization-api) - Complete API documentation with request/response examples
- [Data Anonymization with GitHub Actions](https://neon.com/docs/workflows/data-anonymization-github-actions) - Automate anonymized branch creation in CI/CD
- [PostgreSQL Anonymizer documentation](https://postgresql-anonymizer.readthedocs.io/)
- [Neon branching overview](https://neon.com/docs/introduction/branching)
- [Neon API Reference](https://neon.com/docs/reference/api)

---

For all past changelog entries, see [changelog](https://neon.com/docs/changelog.md)