Использование Ruby on Rails с ClickHouse Managed Postgres

​

Предварительные требования

• Ruby 3.2 или новее. Это руководство протестировано с Ruby 4.0.7, Rails 8.1.4 и pg 1.6.3.
• Аккаунт ClickHouse Cloud.

​

Создание сервиса ClickHouse Managed Postgres

​

Получение сведений о подключении

​

Создание приложения Rails

gem install rails
rails new blog --database=postgresql
cd blog

​

Настройка соединения с базой данных

mv ~/Downloads/your-service-ca-certificate.pem config/ca-certificate.pem

development:
  <<: *default
  url: <%= ENV["DATABASE_URL"] %>
  sslmode: verify-full
  sslrootcert: <%= Rails.root.join("config/ca-certificate.pem") %>

export DATABASE_URL="postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/guide_rails"

bin/rails db:create

Created database 'guide_rails'

​

Создание модели и выполнение миграции

bin/rails generate scaffold Post title:string body:text
bin/rails db:migrate

== 20260930165011 CreatePosts: migrating ======================================
-- create_table(:posts)
   -> 0.0973s
== 20260930165011 CreatePosts: migrated (0.0973s) =============================

​

Выполнение запросов к базе данных

post = Post.create!(title: "Hello from Rails", body: "Stored in ClickHouse Managed Postgres.")
Post.create!(title: "Second post", body: "Created with Active Record.")
post.update!(body: "Updated with Active Record.")
Post.create!(title: "Temporary post", body: "Deleted right away.").destroy

Post.order(:id).each { |p| puts "#{p.id}: #{p.title} - #{p.body}" }

tls = ActiveRecord::Base.connection.select_one(
  "SELECT version, cipher FROM pg_stat_ssl WHERE pid = pg_backend_pid()"
)
puts "Connected with #{tls["version"]} (#{tls["cipher"]})"

bin/rails runner script/posts_demo.rb

1: Hello from Rails - Updated with Active Record.
2: Second post - Created with Active Record.
Connected with TLSv1.3 (TLS_AES_256_GCM_SHA384)

​

Запуск приложения

bin/rails server

​

Использование PgBouncer

• Подготовленные операторы работают с настройками Rails по умолчанию, если используется gem pg версии 1.6 или новее с libpq 17 или новее. Предкомпилированные gem-пакеты pg 1.6 поставляются с libpq 18. С этими версиями Rails, вытесняя оператор из своего кэша, освобождает его сообщением Close на уровне протокола, и встроенный PgBouncer корректно его обрабатывает. Более старые версии pg или libpq вместо этого отправляют SQL-команду DEALLOCATE, которая при работе через PgBouncer завершается ошибкой prepared statement "a1" does not exist. Если это происходит внутри транзакции, транзакция прерывается (PG::InFailedSqlTransaction). Чтобы проверить версии, выполните:
  bin/rails runner 'puts PG::VERSION, PG.library_version'
  
  Требуются версии не ниже 1.6.0 и 170000 соответственно. Если обновиться невозможно, добавьте prepared_statements: false в раздел development. В production Rails включает подготовленные операторы, а в development они по умолчанию отключены, поскольку включён параметр query_log_tags_enabled.
• Миграции захватывают advisory-блокировку уровня сеанса (pg_try_advisory_lock), чтобы исключить одновременный запуск. При пулинге транзакций запрос на снятие блокировки может попасть в другое соединение Postgres: он завершается ошибкой Failed to release advisory lock, а блокировка остаётся удерживаемой, поэтому последующие запуски завершаются ошибкой Cannot run migrations because another migration process is currently running. Либо запускайте bin/rails db:migrate с прямым DATABASE_URL на порту 5432, либо отключите блокировку:

development:
  <<: *default
  url: <%= ENV["DATABASE_URL"] %>
  sslmode: verify-full
  sslrootcert: <%= Rails.root.join("config/ca-certificate.pem") %>
  advisory_locks: false

​

Устранение неполадок

• SSL error: certificate verify failed: параметр sslrootcert не указывает на CA‑сертификат вашего сервиса. Скачайте его заново в разделе Settings → CA Certificate. У каждого сервиса собственный CA, поэтому публичные наборы CA не подойдут.
• root certificate file "..." does not exist: в sslrootcert указан неверный путь. Проверьте, что файл config/ca-certificate.pem существует.

​

Дальнейшие шаги

• Используйте те же параметры sslmode и sslrootcert в конфигурации production.
• Подключение: строки подключения, PgBouncer и TLS.
• Настройки: изменение параметров Postgres и PgBouncer, например max_connections.
• Реплики для чтения: масштабирование нагрузки на чтение, например с помощью нескольких баз данных в Rails.
• Sync to ClickHouse: репликация таблиц Rails в ClickHouse для аналитики.