Neon Serverless Postgres

Руководство по всем задачам, связанным с Neon: настройка, подключения, ветвление и расширенные функции. Neon — это serverless Postgres платформа с разделением вычислений и хранилища: автомасштабирование, ветвление, мгновенное восстановление и масштабирование до нуля. Полная совместимость с Postgres и любым языком, фреймворком или ORM.

Документация Neon

Официальная документация — первичный источник истины. Всегда проверяйте утверждения перед ответом. Функции и API Neon эволюционируют — лучше получить актуальную документацию, чем полагаться на обучающие данные.

Получение документации как Markdown

Любую страницу документации Neon можно получить как markdown двумя способами:

1. Добавить .md к URL: https://neon.com/docs/introduction/branching.md
2. Запросить text/markdown: curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching

Индекс всех доступных страниц: https://neon.com/docs/llms.txt — не угадывайте URL.

Начало работы

Проверка существующей конфигурации

Перед настройкой проверьте кодовую базу и окружение:

• Существующий код подключения к БД
• Конфигурацию Neon MCP server или Neon CLI
• Наличие файла .env и переменной DATABASE_URL
• Конфигурацию ORM (Prisma, Drizzle, TypeORM)

Автоматическая настройка через Neon CLI или MCP Server

Предложите проверить существующие Neon-проекты или создать новые через Neon CLI или MCP server. Если ничего не настроено — запустите init с флагом --agent:

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

Поддерживаемые значения --agent: cursor, copilot, claude, claude-desktop, codex, opencode, cline, gemini-cli, goose, zed.

Команда устанавливает расширение (Cursor/VS Code) или MCP server (остальные агенты), создаёт API-ключ и добавляет скилл neon-postgres в проект.

Отдельные шаги без интерактивного режима:

# Расширение
cursor --install-extension databricks.neon-local-connect

# MCP server
npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>

# Скилл агента
npx skills add neondatabase/agent-skills --skill neon-postgres --agent <agent-name> -y

Последовательность настройки

1. Выбрать организацию и проект — через MCP server или CLI; выбрать существующий или создать новый
2. Получить строку подключения — сохранить в .env как DATABASE_URL
3. Выбрать метод подключения и драйвер — по платформе деплоя
4. Аутентификация пользователей через Neon Auth (при необходимости) — пропустить для CLI-инструментов и скриптов без аккаунтов
5. Настройка ORM (опционально) — Prisma, Drizzle, TypeORM
6. Настройка схемы — проверить существующие миграции или схемы ORM

Методы подключения и драйверы

Выбирайте транспорт и драйвер по условиям среды выполнения (TCP, HTTP, WebSocket, edge, serverless, long-running).

Рекомендация: Drizzle + правильный драйвер для вашей среды

• Long-running / shared-runtime → node-postgres (pg). Neon Functions и хосты, где процесс runtime существует между запросами (например, Vercel с Fluid compute) — создайте pg-пул на уровне модуля и переиспользуйте его.
• Полностью изолированный serverless (Lambda-style) → serverless-драйвер Neon (@neondatabase/serverless). Хосты типа Netlify создают новый изолированный экземпляр на каждый запрос — serverless-драйвер работает через HTTP.

Neon Functions / Vercel / fluid compute — Drizzle + node-postgres:

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, max: 5 });
const db = drizzle({ client: pool, schema });

На Vercel (Fluid compute) дополнительно присоедините пул через attachDatabasePool:

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { attachDatabasePool } from "@vercel/functions";
import * as schema from "./schema";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
attachDatabasePool(pool);
const db = drizzle({ client: pool, schema });

Netlify и другие полностью изолированные serverless — Drizzle + Neon serverless driver:

import { drizzle } from "drizzle-orm/neon-http";
import { neon } from "@neondatabase/serverless";

const sql = neon(process.env.DATABASE_URL!);
const db = drizzle({ client: sql });

Инструменты разработчика

Инструмент	URL
CLI Init Command	https://neon.com/docs/reference/cli-init.md
VSCode Extension	https://neon.com/docs/local/vscode-extension.md
MCP Server	https://neon.com/docs/ai/neon-mcp-server.md
Neon CLI	https://neon.com/docs/reference/neon-cli.md

Admin API

• REST API — прямая HTTP-автоматизация, управление endpoint-ами, аутентификация по API-ключу: https://neon.com/docs/reference/api-reference.md
• TypeScript SDK — типизированный программный контроль через @neondatabase/api-client: https://neon.com/docs/reference/typescript-sdk.md
• Python SDK — управление Neon из Python через пакет neon-api: https://neon.com/docs/reference/python-sdk.md

Neon Auth

Управляемая аутентификация пользователей, UI-компоненты, методы аутентификации и интеграция с Next.js и React: https://neon.com/docs/auth/overview.md

Neon Auth также встроен в Neon JS SDK. Выбор зависит от сценария: https://neon.com/docs/connect/choose-connection.md

Neon Infrastructure as Code (neon.ts)

neon.ts — конфигурационный файл ветки и IaC-файл Neon: декларируйте сервисы, получайте типизированные env-переменные, управляйте вычислениями на уровне ветки. Postgres всегда существует на каждой ветке; здесь кодируется сопряжённая поверхность — Neon Auth, Data API и настройки compute.

npm i @neondatabase/config

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

export default defineConfig({
  auth: true,    // Neon Auth
  dataApi: true, // Data API (требует auth: true)
  branch: (branch) => {
    if (branch.exists) return {};
    if (branch.isDefault) return { protected: true };
    return {
      ttl: "7d",
      postgres: {
        computeSettings: {
          autoscalingLimitMinCu: 0.25,
          autoscalingLimitMaxCu: 1,
          suspendTimeout: "5m",
        },
      },
    };
  },
});

neonctl config status   # текущая конфигурация ветки
neonctl config plan     # dry-run изменений
neonctl config apply    # применить декларацию
neonctl deploy          # псевдоним для config apply

Ветвление (Branching)

Мгновенные copy-on-write клоны без полного копирования данных. Каждая ветка имеет собственный compute endpoint. Используйте neonctl CLI или MCP server для создания, просмотра и сравнения веток.

Документация: https://neon.com/docs/introduction/branching.md

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

Автомасштабирование

Автоматическое масштабирование compute под нагрузку. Документация: https://neon.com/docs/introduction/autoscaling.md

Scale to Zero

Неактивные compute приостанавливаются автоматически (по умолчанию через 5 минут). Первый запрос после приостановки имеет задержку cold-start (~сотни мс). Хранилище остаётся активным.

Документация: https://neon.com/docs/introduction/scale-to-zero.md

Instant Restore

Point-in-time восстановление без традиционных процедур резервного копирования. Создание веток из исторических точек. Time Travel запросы для исторического анализа.

Документация: https://neon.com/docs/introduction/branch-restore.md

Read Replicas

Реплики только для чтения, разделяющие общее хранилище. Быстрое создание, независимое масштабирование. Типичные сценарии: аналитика, отчёты, read-heavy API.

Документация: https://neon.com/docs/introduction/read-replicas.md

Connection Pooling

Neon использует PgBouncer. Добавьте -pooler к hostname endpoint для пулированных подключений. Особенно важно в serverless среде с пиковыми нагрузками.

Документация: https://neon.com/docs/connect/connection-pooling.md