Резюме

Полные руководства и лучшие практики для Neon Serverless Postgres, охватывающие настройку, методы подключения, аутентификацию и API платформы.

• Охватывает начало работы, настройку локальной разработки, выбор метода подключения (TCP, HTTP, WebSocket) и установку драйверов для любого языка или фреймворка

• Включает специфичные для Neon возможности: автомасштабирование, ветвление (мгновенные copy-on-write клонирование), масштабирование до нуля, мгновенное восстановление и реплики чтения

• Предоставляет инструменты CLI (neonctl), SDK для TypeScript/Python и документацию REST API для программного управления ресурсами и автоматизации CI/CD

• Руководства по интеграции Neon Auth, пулингу подключений для serverless-окружений, спискам разрешённых IP и рабочим процессам логической репликации

СНАЧАЛА: Используйте родительский skill neon для обзора Neon, начала работы с Neon, лучших практик разработки на Neon и многого другого.

Если skill neon не установлен, получите его по адресу https://neon.com/docs/ai/skills/neon/SKILL.md или установите его командой:

neon skills -s neon -y

Lakebase Postgres

Lakebase Postgres — это база данных, стоящая в основе Neon. Она работает на архитектуре lakebase — OLTP, построенный непосредственно на облачном объектном хранилище, который разделяет хранение и вычисления для обеспечения автомасштабирования, ветвления, мгновенного восстановления и масштабирования до нуля. Она полностью совместима с Postgres и работает с любым языком, фреймворком или ORM, которые поддерживают Postgres.

Это одна и та же база данных, будь то доступ через Neon или через Databricks; этот skill охватывает путь доступа через Neon.

Вход в систему, пользователи, сессии и @neondatabase/auth относятся к neon-auth.

Процесс настройки

1. Выбор организации и проекта

Если DATABASE_URL уже задан (в промпте, окружении или репозитории) или файл .neon указывает на проект, используйте его. Не перечисляйте организации и не создавайте второй проект для работы со схемой.

В противном случае используйте CLI (по умолчанию) или MCP-сервер для перечисления организаций и проектов. Позвольте пользователю выбрать существующий проект или создать новый.

2. Получение строки подключения

Если DATABASE_URL уже задан, используйте его. Не запрашивайте другой через CLI или MCP.

В противном случае используйте CLI (по умолчанию), neon env pull или MCP-сервер для получения строки подключения. Сохраните её в .env как DATABASE_URL. Сначала прочитайте файл перед его изменением, чтобы не перезаписать существующие значения.

Когда использовать pooled- и direct-подключения

Сценарий использования	Тип подключения
Веб-приложения, serverless-функции	Pooled (-pooler)
Миграции схемы	Direct
pg_dump / pg_restore	Direct
Логическая репликация	Direct
Долгие аналитические запросы с временными таблицами	Direct
Административные задачи, требующие SET или состояния сессии	Direct
LISTEN / NOTIFY	Direct

3. Выбор метода подключения и драйвера

Сохраните существующие ORM и драйвер. Для новых проектов работы со схемой на TypeScript без установленного выбора Drizzle является рекомендацией: https://neon.com/docs/guides/drizzle.md. Обратитесь к руководству по методам подключения, чтобы выбрать правильный драйвер в зависимости от того, как рантайм обрабатывает ваш код: https://neon.com/docs/connect/choose-connection.md.

Заметки о драйверах:

• На Vercel используйте node-postgres (npm install pg) с Vercel Fluid compute и import { attachDatabasePool } from "@vercel/functions";

• На Cloudflare используйте node-postgres с Cloudflare Hyperdrive

• На Neon Functions используйте node-postgres, так как функции работают долго и переиспользуют пул между запросами.

• Используйте драйвер @neondatabase/serverless для serverless- и edge-окружений (например, при использовании Netlify) — HTTP-транспорт для одноразовых запросов, WebSocket для поддержки транзакций. Ссылка: https://neon.com/docs/serverless/serverless-driver.md

4. Настройка схемы

Управляйте схемами и миграциями как кодом. Избегайте выполнения ad hoc миграций схемы на вашей базе данных, поскольку ими трудно управлять.

Если вы используете ORM, следуйте лучшим практикам вашей ORM для управления схемами и миграциями. Например, при использовании Drizzle используйте только Drizzle для управления схемой и миграциями, если не указано иное.

Ветвление

Используйте это, когда пользователь планирует изолированные окружения, тестирование миграций схемы, preview-развёртывания или автоматизацию жизненного цикла веток.

Ключевые моменты:

• Ветки — это мгновенные copy-on-write клони (без полного копирования данных).

• Каждая ветка имеет собственный compute endpoint.

• Используйте neon CLI или MCP-сервер для создания, инспекции и сравнения веток.

Ссылка: https://neon.com/docs/introduction/branching.md

Для детальных рабочих процессов создания веток (обычные ветки vs схемо-ориентированные, сброс от родителя, выбор CLI/MCP) используйте skill neon-postgres-branches. Если он не установлен, получите его по адресу https://neon.com/docs/ai/skills/neon-postgres-branches/SKILL.md или установите его командой:

neon skills -s neon-postgres-branches -y

Миграции

Протестируйте миграцию на ветке production с production-подобными данными перед применением к production.

Используйте direct (non-pooled) строку подключения при запуске миграции, а не pooled. neon connection-string по умолчанию возвращает direct-строку; убедитесь, что имя хоста не содержит суффикс -pooler.

Устранение неполадок и специфичная для Neon производительность

Используйте предопределённые read-only диагностики Neon перед написанием catalog-запросов вручную. Подкоманды Neon CLI neon inspect db и инструмент inspect_database Neon MCP-сервера выполняют одни и те же проверки.

Этот раздел охватывает инструменты диагностики, специфичные для Neon, поведение compute-кэша и сигналы платформы. Когда данные указывают на общие задачи по Postgres, такие как переписывание запроса, выбор индекса, изменение схемы или интерпретация узлов плана, загрузите skill postgres-best-practices и перенесите результаты диагностики в этот рабочий процесс.

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

• CLI: https://neon.com/docs/cli/inspect.md

• Производительность запросов: https://neon.com/docs/postgresql/query-performance.md

• pg_stat_statements: https://neon.com/docs/extensions/pg_stat_statements.md

• Neon Local File Cache: https://neon.com/docs/extensions/neon.md

Выбор CLI или MCP

Предпочитайте Neon CLI, когда доступны терминал и аутентификация:

neon inspect db <check>

CLI определяет проект и ветку из текущего контекста Neon. Используйте --project-id, --branch и --database-name для переопределения. Опустите --database-name, чтобы проверить все базы данных на ветке. Используйте --db-url только при инспекции базы данных Postgres напрямую вместо её разрешения через Neon API.

При использовании Neon MCP вызывайте inspect_database с projectId и одним check. Передавайте branchId, databaseName или computeId только при необходимости. Опустите databaseName, чтобы проверить все базы данных на ветке. Увеличивайте limit только когда результат сообщает об обрезке.

Выбор диагностики

Симптом или вопрос	Проверки
Какие релации занимают хранилище?	table-sizes, index-sizes
Неиспользуется ли индекс или таблица сканируется интенсивно?	unused-indexes, seq-scans
Что выполняется более 5 минут или удерживает блокировки?	long-running-queries, locks
Какие запросы потребляют наибольшее общее время?	outliers
Какие запросы выполняются чаще всего?	calls
Помещаются ли активные данные в compute-кэш?	lfc-hit-rate, working-set
Отстаёт ли autovacuum или пространство тратится впустую?	vacuum-stats, bloat
Здорова ли логическая репликация?	replication-slots, subscriptions

Не путайте эти проверки:

• long-running-queries сообщает о операторах, выполняющихся прямо сейчас более пяти минут.

• outliers ранжирует запросы по накопленному времени выполнения с момента последнего сброса статистики. Не ранжирует по средней задержке.

• calls ранжирует по количеству выполнений за тот же период статистики.

outliers и calls требуют pg_stat_statements. lfc-hit-rate и working-set требуют расширения neon. Если проверка сообщает об отсутствии расширения, спросите перед запуском предложенной команды CREATE EXTENSION, поскольку установка расширения изменяет базу данных.

Безопасная интерпретация результатов

• Рассматривайте unused-indexes как список кандидатов, а не разрешение на удаление индексов. Подтвердите период наблюдения, ограничения и нагрузку перед удалением.

• Последовательное сканирование может быть корректным для небольшой таблицы или запроса, читающего значительную часть таблицы. Проверьте размер таблицы, селективность и план запроса перед добавлением индекса.

• bloat — это статистическая оценка. Подтвердите влияние и запланируйте блокировки или обслуживание перед VACUUM FULL, REINDEX или аналогичными средствами исправления.

• Кэш и статистика Postgres сбрасываются при перезапуске compute, включая приостановку при масштабировании до нуля. Запустите репрезентативную нагрузку перед интерпретацией свежих результатов lfc-hit-rate, working-set, vacuum-stats или pg_stat_statements.

• Проверки на уровне compute (lfc-hit-rate, working-set и replication-slots) выполняются один раз, даже при инспекции каждой базы данных.

• Один неисправный база данных может привести к сбою инспекции всех баз данных; повторите relevantную проверку с явным databaseName, чтобы изолировать её.

Инспекция поведения Neon-кэша по запросу

Стандартный EXPLAIN (ANALYZE, BUFFERS) показывает активность shared-буферов Postgres, но не отображает Neon Local File Cache (LFC) или предварительную выборку страниц. Для безопасного read-only запроса добавьте опции FILECACHE и PREFETCH от Neon:

EXPLAIN (ANALYZE, BUFFERS, PREFETCH, FILECACHE)
SELECT ...;

• File cache: hits подсчитывает страницы, найденные в LFC compute.

• File cache: misses подсчитывает страницы, не найденные в LFC и полученные из хранилища базы данных.

• Prefetch: hits, misses, expired и duplicates показывают, насколько эффективно Neon извлекал страницы до того, как исполнитель их запросил.

FILECACHE и PREFETCH предоставляют метрики для этого запроса и не требуют расширения neon. В отличие от них, neon inspect db lfc-hit-rate и working-set предоставляют статистику на уровне compute и требуют это расширение.

MCP-инструмент explain_sql_statement может сгенерировать стандартный план, но не предоставляет опции FILECACHE или PREFETCH. Для сбора этих метрик, специфичных для Neon, через MCP используйте run_sql с явной read-only командой EXPLAIN выше.

Поскольку ANALYZE выполняет оператор, используйте его только когда выполнение безопасно; не запускайте его автоматически для мутирующего SQL. Тщательно сравнивайте запуски с холодным и тёплым кэшем, поскольку первое выполнение может заполнить кэш и существенно изменить последующие результаты.

Рабочий процесс по производительности

• Воспроизведите симптом и отметьте его временной интервал.

• Запустите наименьшие relevantные проверки inspect из таблицы выше.

• Идентифицируйте конкретный запрос перед изменением схемы или compute. Используйте MCP explain_sql_statement для стандартного плана или специфичный для Neon EXPLAIN выше, когда важно поведение LFC или предварительной выборки.

• Если узкое место — форма запроса, индексация, схема, блокировки или поведение vacuum, загрузите postgres-best-practices и перенесите результаты инспекции и план запроса. Решения по Neon compute, кэшу, подключению и платформе оставьте в этом skill.

• Перезапустите ту же проверку и нагрузку для подтверждения изменения.

Используйте MCP list_slow_queries вместо inspect_database, когда пользователю конкретно нужны запросы, ранжированные по среднему времени выполнения с пользовательским порогом и лимитом. Вне явного случая EXPLAIN выше, используйте run_sql только для read-only диагностического SQL, когда предопределённые проверки не отвечают на вопрос.

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

Используйте это, когда пользователю необходимо, чтобы compute автоматически масштабировался вместе с нагрузкой, и ему нужны рекомендации по определению размера CU и поведению рантайма.

Ссылка: https://neon.com/docs/introduction/autoscaling.md

Масштабирование до нуля

Используйте это при оптимизации расходов на простой и обсуждении поведения приостановки/возобновления, включая trade-offs холодного старта.

Ключевые моменты:

• Простаивающие compute автоматически приостанавливаются после 5 минут по умолчанию; таймаут настраивается, и приостановку можно отключить только на тарифах Launch и Scale.

• Первый запрос после приостановки обычно имеет штраф холодного старта (около сотен мс)

• Хранилище остаётся активным, пока compute приостановлен.

Ссылка: https://neon.com/docs/introduction/scale-to-zero.md

Мгновенное восстановление

Используйте это, когда пользователю требуется восстановление в точке времени или он хочет восстановить состояние данных без традиционных процессов восстановления из резервных копий.

Ключевые моменты:

• Окна истории для мгновенного восстановления зависят от лимитов тарифа.

• Пользователи могут создавать ветки из исторических точек времени.

• Запросы Time Travel могут использоваться для исторической инспекции.

Ссылка: https://neon.com/docs/introduction/branch-restore.md

Реплики чтения

Используйте для нагруженных на чтение задач, когда пользователю нужны выделенные read-only compute без дублирования хранилища.

Ключевые моменты:

• Реплики — это read-only compute endpoints, разделяющие то же хранилище.

• Создание быстрое и масштабирование независимо от основного compute.

• Типичные сценарии использования: аналитика, отчётность и API с тяжёлой нагрузкой на чтение.

Ссылка: https://neon.com/docs/introduction/read-replicas.md

Пул соединений

Используйте, когда пользователь работает в serverless или высоко конкурентных средах и ему необходимо безопасное масштабируемое управление соединениями Postgres.

Ключевые моменты:

• Пул соединений Neon использует PgBouncer.

• Добавьте -pooler к хостнеймам endpoint'ов для использования соединений через пул.

• Пул соединений особенно важен в serverless средах с бурстной конкурентностью.

Ссылка: https://neon.com/docs/connect/connection-pooling.md

IP Allow Lists

Используйте, когда пользователю нужно ограничить доступ к базе данных по доверенным сетям, IP или диапазонам CIDR.

Ссылка: https://neon.com/docs/introduction/ip-allow.md

Логическая репликация

Используйте при интеграции CDC-пайплайнов, внешней синхронизации Postgres или перемещении данных на основе репликации.

Ключевые моменты:

• Neon поддерживает нативные процессы логической репликации.

• Полезно для репликации к/от внешних систем Postgres.

Ссылка: https://neon.com/docs/guides/logical-replication-guide.md

Поиск в Lakebase

Используйте Lakebase Search для семантического, полнотекстового и гибридного поиска:

• Для семантического поиска см. Векторный поиск.

• Для полнотекстового поиска с ранжированием BM25 см. Полнотекстовый поиск.

• Для комбинирования семантических и лексических результатов см. Гибридный поиск.

Ссылки:

• Начало работы с Lakebase Search

• Справочник lakebase_vector

• Справочник lakebase_text

Подводные камни

Подключённый через пул и прямые соединения: используйте прямой URL для миграций, дампов и репликации

Neon предоставляет две строки подключения для одной базы данных: подключённую через пул (хостнейм с суффиксом -pooler) и прямую/неподключённую через пул (без суффикса -pooler). neon env pull записывает их как DATABASE_URL и DATABASE_URL_UNPOOLED. Соединение через пул маршрутизируется через PgBouncer в транзакционном режиме, который не поддерживает операции на уровне сессии. Выберите правильный вариант:

• Через пул (DATABASE_URL) — обычный трафик запросов вашего приложения, особенно в serverless средах и при работе с одним соединением на запрос.

• Прямой (DATABASE_URL_UNPOOLED) — миграции схемы (Prisma Migrate, Drizzle Kit, Alembic и другие), pg_dump / pg_restore, логическая репликация, LISTEN/NOTIFY и всё, что полагается на SET или другое состояние сессии.

Запуск миграций, дампов или репликации через подключённое через пул соединение может привести к ошибкам, и ни одна из них не указывает на пул соединений: prepared statement "s0" уже существует от Prisma Migrate, SET search_path, которое не сохраняется за пределами своей транзакции, поэтому следующий запрос сообщает relation "mytable" does not exist, или запись, периодически попадающая в транзакцию только для чтения (SQLSTATE 25006), унаследованную подключённым через пул backend'ом от предыдущего клиента. Инструменты миграций обычно принимают обе строки одновременно — Prisma использует directUrl наряду с url — поэтому указывайте на прямую строку, а не меняйте DATABASE_URL местами, теряя пул соединений для приложения. См. https://neon.com/docs/connect/connection-pooling.md.

Установка

npx skills add https://github.com/neondatabase/agent-skills --skill neon-postgres