FAQ по ClickHouse Managed Postgres

Мониторинг и метрики

Как получить доступ к метрикам моего экземпляра ClickHouse Managed Postgres?

Вы можете отслеживать использование CPU, памяти, IOPS и хранилища напрямую в консоли ClickHouse Cloud на вкладке Мониторинг вашего экземпляра ClickHouse Managed Postgres. Кроме того, вы можете ознакомиться с Query Performance Insights для подробного анализа ваших запросов на вкладке Query Insights.

Резервное копирование и восстановление

Какие варианты резервного копирования доступны?

ClickHouse Managed Postgres включает автоматическое ежедневное резервное копирование с непрерывным архивированием WAL, что позволяет выполнять восстановление на определённый момент времени на любой момент в пределах 7-дневного периода хранения. Резервные копии хранятся в объектном хранилище. Подробные сведения о частоте резервного копирования, сроках хранения и выполнении восстановления на определённый момент времени см. в документации Backup and restore.

Инфраструктура и автоматизация

Какие облачные провайдеры поддерживаются?

ClickHouse Managed Postgres доступен на AWS в статусе публичной беты. Для GCP доступна закрытая предварительная версия. Записаться в лист ожидания закрытой предварительной версии для GCP можно здесь, а узнать больше — из анонса. Подробности см. в разделе Поддерживаемые облачные провайдеры.

Доступна ли поддержка Terraform для ClickHouse Managed Postgres?

Да. Вы можете создавать сервисы ClickHouse Managed Postgres и управлять ими с помощью Terraform-провайдера ClickHouse, используя ресурс clickhouse_postgres_service. Подробности см. в справочнике по Terraform. Также вы можете использовать консоль ClickHouse Cloud или OpenAPI для создания экземпляров и управления ими.

Расширения и конфигурация

Какие расширения поддерживаются?

ClickHouse Managed Postgres включает более 90 расширений PostgreSQL, в том числе популярные PostGIS, pgvector, pg_cron и многие другие. Полный список доступных расширений и инструкции по установке см. в документации Расширения.

Можно ли настраивать параметры конфигурации PostgreSQL?

Да, параметры конфигурации PostgreSQL и PgBouncer можно изменять на вкладке Настройки в консоли. Подробнее о доступных параметрах и о том, как их изменять, см. в документации Настройки.

Если вам нужен параметр, который пока недоступен, обратитесь в поддержку, чтобы запросить его.

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

Почему через PgBouncer возникают ошибки `prepared statement does not exist`?

ClickHouse Managed Postgres запускает PgBouncer в режиме пулинга транзакций. В этом режиме backend-соединение Postgres закрепляется за вашим клиентом только на время одной транзакции, после чего возвращается в пул, поэтому следующая транзакция того же клиента может попасть на другое backend-соединение. PgBouncer отслеживает подготовленные операторы на уровне протокола, которые большинство драйверов отправляют по расширенному протоколу запросов (сообщения Parse, Bind и Execute). Если оператор выполняется на backend-соединении, которое ещё не встречало его, PgBouncer сначала подготавливает его там. Каждое backend-соединение хранит до max_prepared_statements таких операторов (по умолчанию — 200). Поэтому большинство драйверов работают через PgBouncer с настройками по умолчанию. Через PgBouncer не работает следующее:

Подготовленные операторы на уровне SQL. PgBouncer не отслеживает команды PREPARE и EXECUTE, отправленные в виде SQL, поэтому EXECUTE может попасть на backend-соединение, на котором PREPARE не выполнялся.
Освобождение операторов через SQL-команду DEALLOCATE. PgBouncer переименовывает операторы на backend-соединении, поэтому DEALLOCATE с именем оператора, заданным клиентом, завершается ошибкой. Если это происходит внутри транзакции, она прерывается, и все последующие операторы завершаются ошибкой current transaction is aborted. Драйверы на основе libpq 17 и новее освобождают операторы с помощью сообщения Close на уровне протокола, которое PgBouncer обрабатывает корректно.
Безымянные операторы, разнесённые на несколько обменов с сервером. В некоторых режимах драйверы отправляют Parse безымянного оператора в одном обмене, а его Bind — в следующем. PgBouncer может выполнить второй обмен на другом backend-соединении: в результате либо возникает ошибка unnamed prepared statement does not exist, либо молча выполняется оператор другого клиента и возвращаются его результаты.

В этих случаях возникают ошибки вида:

ERROR:  prepared statement "..." does not exist
ERROR:  unnamed prepared statement does not exist
ERROR:  prepared statement did not exist

Симптомы, которые часто вызваны той же первопричиной:

Всплески ошибок prepared statement does not exist, особенно во время дозагрузки или при записи с высоким параллелизмом
Вставки, которые словно «молча не выполняются»: оператор завершается ошибкой, драйвер повторяет попытку, и в итоге батч может быть применён лишь частично или вовсе потерян
Транзакции, завершающиеся ошибкой current transaction is aborted после освобождения оператора
Строки, относящиеся к другому запросу

Решение: используйте для своего драйвера настройку, указанную ниже. Если вашего драйвера нет в списке, обновите его до версии, использующей libpq 17 или новее, или отключите в нём серверные подготовленные операторы.

Драйвер	Через PgBouncer
node-postgres / pg (Node.js)	Изменения не требуются.
Bun.sql (Bun)	Изменения не требуются. Если появляется ошибка `prepared statement does not exist`, установите `prepare: false`.
Prisma с `@prisma/adapter-pg`	Изменения не требуются. Параметр URL `pgbouncer=true` в Prisma 7 ни на что не влияет.
psycopg 3 (Python, Django)	Изменения не требуются при использовании `psycopg[binary]` или libpq версии 17 и новее. Со старыми версиями libpq установите `prepare_threshold=None`. Django по умолчанию подставляет параметры на стороне клиента, поэтому его настраивать не нужно.
asyncpg (Python, SQLAlchemy)	Изменения не требуются. Если в SQLAlchemy вы отключаете кэш операторов с помощью `statement_cache_size=0`, также укажите `prepared_statement_cache_size=0` в URL.
pgjdbc (Java)	Изменения не требуются. Используйте pgjdbc 42.7.5 или новее: более старые версии не могут подключиться через PgBouncer. См. `unsupported startup parameter`.
Npgsql (.NET)	Изменения не требуются: автоматическая подготовка по умолчанию отключена. Не включайте `Max Auto Prepare` и не вызывайте `Prepare` через PgBouncer; если без этого не обойтись, также установите `No Reset On Close=true`.
pgx (Go)	Установите `default_query_exec_mode=cache_describe` (или `exec`). Никогда не используйте `describe_exec`: в этом режиме безымянные операторы разбиваются на несколько обменов с сервером.
Postgrex / Ecto (Elixir)	Установите `prepare: :unnamed` в конфигурации репозитория. С именованными операторами запрос размером около 4 КБ может зависнуть при работе через PgBouncer.
sqlx (Rust)	Настраивать подготовленные операторы не нужно. Не используйте `.persistent(false)` или `statement_cache_capacity(0)`. Чтобы соединение вообще устанавливалось, задайте `extra_float_digits(None)`; см. `unsupported startup parameter`.
Active Record (Ruby on Rails)	Изменения не требуются при использовании gem `pg` версии 1.6 или новее и libpq версии 17 или новее. В противном случае установите `prepared_statements: false` в `config/database.yml`.
PDO (PHP, Laravel)	Изменения не требуются, если `pdo_pgsql` скомпилирован с libpq версии 17 или новее. В противном случае установите `PDO::ATTR_EMULATE_PREPARES => true`.

Если ваша рабочая нагрузка зависит от PREPARE на уровне SQL, подключайтесь напрямую к PostgreSQL (порт 5432), а не через пулер PgBouncer. Подробнее о выборе между конечной точкой с пулом соединений и прямой конечной точкой см. в разделе Подключение.

Почему после миграции запросы завершаются ошибкой `cached plan must not change result type`?

PgBouncer хранит подготовленные операторы в своих соединениях с Postgres и повторно использует их для одного и того же текста SQL. Если после изменения схемы меняется тип столбца, возвращаемого запросом (например, с integer на bigint), такой запрос через PgBouncer продолжает завершаться ошибкой cached plan must not change result type. Ошибка возникает даже в новых клиентских соединениях — до тех пор, пока PgBouncer не заменит свои соединения с Postgres. Некоторые драйверы вместо ошибки декодируют результат по устаревшим типам и молча возвращают неверные значения. При прямом соединении каждое соединение завершается ошибкой не более одного раза, после чего работает нормально. Чтобы устранить проблему, закройте соединения PgBouncer с Postgres для этой базы данных — PgBouncer откроет новые. PgBouncer подключается к Postgres локально, поэтому у его соединений нет client_addr. Выполните следующий запрос через прямое соединение (порт 5432) от имени того же пользователя, под которым подключается ваше приложение. Запрос завершает только соединения PgBouncer для пользователя вашего приложения: транзакции, выполняющиеся через PgBouncer в этот момент, завершатся ошибкой, а прямые соединения затронуты не будут:

SELECT pg_terminate_backend(pid) FROM pg_stat_activity
WHERE datname = '<your_database>' AND usename = current_user
  AND client_addr IS NULL AND backend_type = 'client backend'
  AND pid <> pg_backend_pid();

Драйверы, использующие безымянные операторы, например Npgsql с настройками по умолчанию, Postgrex с prepare: :unnamed и pgx с cache_describe, эта проблема не затрагивает.

Почему при подключении через PgBouncer возникает ошибка `unsupported startup parameter`?

PgBouncer отклоняет параметры, задаваемые при подключении, если не может единообразно применить их ко всем соединениям Postgres в своем пуле, и завершается с ошибкой FATAL: unsupported startup parameter: ... или unsupported startup parameter in options: .... Чаще всего это происходит в следующих случаях:

extra_float_digits — этот параметр при каждом подключении передают pgjdbc версии 42.7.4 и более ранних (например, в составе Spring Boot 3), а также sqlx. Обновите pgjdbc до версии 42.7.5 или новее. В sqlx задайте extra_float_digits(None) в PgConnectOptions.
search_path и другие параметры в строке подключения, например currentSchema в JDBC URL, Search Path в строке подключения Npgsql, options=-c ... или OPTIONS["options"] в Django. Вместо этого задайте значение по умолчанию с помощью ALTER ROLE ... SET или ALTER DATABASE ... SET, используйте SET LOCAL внутри транзакции либо подключайтесь напрямую.

Параметры application_name и TimeZone поддерживаются.

Почему команды `SET` не сохраняются при работе через PgBouncer?

В режиме пулинга транзакций (transaction pooling) команда SET уровня сеанса действует для того соединения Postgres, в котором она была выполнена, а не для вашего клиента. Последующие транзакции вашего клиента могут выполняться в других соединениях, где этот параметр не задан, а другие клиенты, наоборот, могут попасть в соединение, где он задан. Это относится и к SET ROLE: роль, которую вы приняли, может применяться к запросам другого клиента. Используйте SET LOCAL внутри транзакции, задавайте значения по умолчанию с помощью ALTER ROLE ... SET или ALTER DATABASE ... SET либо подключайтесь напрямую, если рабочая нагрузка зависит от состояния сеанса.

Почему миграции зависают или не могут снять advisory-блокировку при работе через PgBouncer?

Многие инструменты миграции захватывают advisory-блокировку на уровне сеанса, чтобы в каждый момент выполнялась только одна миграция, а снимают её отдельным оператором. При работе через PgBouncer оператор снятия блокировки может выполниться в другом соединении Postgres, и блокировка так и остаётся на одном из соединений пула. В результате последующие миграции зависают в ожидании или завершаются с ошибками вида failed to release advisory lock — даже при работе через прямое соединение. Сеансовые advisory-блокировки используют, в частности, golang-migrate, sqlx, Migrator из Kysely, Rails, Flyway с transactional-lock=false и Ecto с migration_lock: :pg_advisory_lock. Выполняйте миграции через прямое соединение (порт 5432). Зависшую блокировку удерживает бездействующий сеанс, а блокировку ещё выполняющейся миграции — активный. Чтобы снять зависшие блокировки, завершите только бездействующие сеансы, удерживающие advisory-блокировки в вашей базе данных, — также через прямое соединение:

SELECT pg_terminate_backend(l.pid) FROM pg_locks l
JOIN pg_stat_activity a ON a.pid = l.pid
WHERE l.locktype = 'advisory' AND a.state = 'idle'
  AND l.database = (SELECT oid FROM pg_database WHERE datname = current_database());

Что означает параметр `max_client_conn` в PgBouncer и как он соотносится с `max_connections` в Postgres?

Они отвечают за разные вещи:

max_connections в Postgres ограничивает число backend-соединений с самим PostgreSQL. Это затратный показатель — каждое backend-соединение потребляет память и занимает слот процесса.
max_client_conn в PgBouncer ограничивает число клиентских соединений, которые могут быть одновременно открыты в пулере. PgBouncer мультиплексирует множество таких клиентских соединений на значительно меньшее число backend-соединений.

PgBouncer принимает в несколько раз больше клиентских соединений, чем есть backend-соединений Postgres. Например, инстанс, у которого max_connections равен 500, принимает на пулере 2500 клиентских соединений. Если вы видите ошибки соединения на стороне пулера, гораздо вероятнее, что вы упираетесь в лимит backend-соединений для конкретного пула (default_pool_size или max_db_connections для каждой базы данных), а не в основной лимит клиентских соединений. Чтобы посмотреть значения для вашего инстанса, подключитесь к специальной базе данных pgbouncer через PgBouncer (порт 6432) и выполните SHOW CONFIG:

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:6432/pgbouncer?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "SHOW CONFIG;"

Возможности базы данных

Могу ли я создать несколько баз данных и схем?

Да. ClickHouse Managed Postgres предоставляет всю нативную функциональность PostgreSQL, включая поддержку нескольких баз данных и схем в рамках одного экземпляра. Вы можете создавать базы данных и схемы и управлять ими с помощью стандартных команд PostgreSQL.

Поддерживается ли ролевое управление доступом (RBAC)?

У вас есть полный доступ с правами superuser к вашему экземпляру ClickHouse Managed Postgres, что позволяет создавать роли и управлять разрешениями с помощью стандартных команд PostgreSQL.

Расширенные возможности RBAC с интеграцией в консоль планируются в этом году.

Обновления

Как выполняются обновления версий PostgreSQL?

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

Миграция

Какие инструменты доступны при миграции в ClickHouse Managed Postgres?

ClickHouse Managed Postgres поддерживает несколько подходов к миграции:

pg_dump and pg_restore: Для небольших баз данных или разовых миграций. См. руководство pg_dump and pg_restore.
Logical replication: Для более крупных баз данных, где требуется минимальное время простоя. См. руководство Логическая репликация.
PeerDB: Для репликации на основе CDC из других экземпляров Postgres. См. руководство Миграция с PeerDB.

Полностью управляемый процесс миграции скоро станет доступен.

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

Возможности

Руководства

Цены

Интеграция с ClickHouse

Миграции

Мониторинг

Часто задаваемые вопросы

Мониторинг и метрики

Как получить доступ к метрикам моего экземпляра ClickHouse Managed Postgres?

Резервное копирование и восстановление

Какие варианты резервного копирования доступны?

Инфраструктура и автоматизация

Какие облачные провайдеры поддерживаются?

Доступна ли поддержка Terraform для ClickHouse Managed Postgres?

Расширения и конфигурация

Какие расширения поддерживаются?

Можно ли настраивать параметры конфигурации PostgreSQL?

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

Почему через PgBouncer возникают ошибки `prepared statement does not exist`?

Почему после миграции запросы завершаются ошибкой `cached plan must not change result type`?

Почему при подключении через PgBouncer возникает ошибка `unsupported startup parameter`?

Почему команды `SET` не сохраняются при работе через PgBouncer?

Почему миграции зависают или не могут снять advisory-блокировку при работе через PgBouncer?

Что означает параметр `max_client_conn` в PgBouncer и как он соотносится с `max_connections` в Postgres?

Возможности базы данных

Могу ли я создать несколько баз данных и схем?

Поддерживается ли ролевое управление доступом (RBAC)?

Обновления

Как выполняются обновления версий PostgreSQL?

Миграция

Какие инструменты доступны при миграции в ClickHouse Managed Postgres?

​Мониторинг и метрики

​Как получить доступ к метрикам моего экземпляра ClickHouse Managed Postgres?

​Резервное копирование и восстановление

​Какие варианты резервного копирования доступны?

​Инфраструктура и автоматизация

​Какие облачные провайдеры поддерживаются?

​Доступна ли поддержка Terraform для ClickHouse Managed Postgres?

​Расширения и конфигурация

​Какие расширения поддерживаются?

​Можно ли настраивать параметры конфигурации PostgreSQL?

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

​Почему через PgBouncer возникают ошибки prepared statement does not exist?

​Почему после миграции запросы завершаются ошибкой cached plan must not change result type?

​Почему при подключении через PgBouncer возникает ошибка unsupported startup parameter?

​Почему команды SET не сохраняются при работе через PgBouncer?

​Почему миграции зависают или не могут снять advisory-блокировку при работе через PgBouncer?

​Что означает параметр max_client_conn в PgBouncer и как он соотносится с max_connections в Postgres?

​Возможности базы данных

​Могу ли я создать несколько баз данных и схем?

​Поддерживается ли ролевое управление доступом (RBAC)?

​Обновления

​Как выполняются обновления версий PostgreSQL?

​Миграция

​Какие инструменты доступны при миграции в ClickHouse Managed Postgres?

Мониторинг и метрики

Как получить доступ к метрикам моего экземпляра ClickHouse Managed Postgres?

Резервное копирование и восстановление

Какие варианты резервного копирования доступны?

Инфраструктура и автоматизация

Какие облачные провайдеры поддерживаются?

Доступна ли поддержка Terraform для ClickHouse Managed Postgres?

Расширения и конфигурация

Какие расширения поддерживаются?

Можно ли настраивать параметры конфигурации PostgreSQL?

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

Почему через PgBouncer возникают ошибки `prepared statement does not exist`?

Почему после миграции запросы завершаются ошибкой `cached plan must not change result type`?

Почему при подключении через PgBouncer возникает ошибка `unsupported startup parameter`?

Почему команды `SET` не сохраняются при работе через PgBouncer?

Почему миграции зависают или не могут снять advisory-блокировку при работе через PgBouncer?

Что означает параметр `max_client_conn` в PgBouncer и как он соотносится с `max_connections` в Postgres?

Возможности базы данных

Могу ли я создать несколько баз данных и схем?

Поддерживается ли ролевое управление доступом (RBAC)?

Обновления

Как выполняются обновления версий PostgreSQL?

Миграция

Какие инструменты доступны при миграции в ClickHouse Managed Postgres?