ClickHouse Managed Postgres와 함께 Ruby on Rails 사용하기

​

사전 요구 사항

• 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 사용하기

• Prepared statement는 pg gem 1.6 이상이 libpq 17 이상을 사용하는 경우 Rails 기본 설정 그대로 동작합니다. 사전 컴파일된 pg 1.6 gem에는 libpq 18이 번들로 포함되어 있습니다. 이 버전에서는 Rails가 캐시에서 SQL 문을 제거할 때 프로토콜 수준의 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 이상이어야 합니다. 업그레이드할 수 없다면 development 섹션에 prepared_statements: false를 추가하십시오. Rails는 production에서 prepared statement를 활성화하지만, development에서는 query_log_tags_enabled가 켜져 있어 기본적으로 비활성화됩니다.
• **마이그레이션(Migrations)**은 동시 실행을 막기 위해 세션 수준의 advisory 잠금(pg_try_advisory_lock)을 획득합니다. 트랜잭션 풀링에서는 잠금 해제 요청이 다른 Postgres 연결로 전달될 수 있으며, 이 경우 Failed to release advisory lock 오류와 함께 실패하고 잠금은 그대로 유지됩니다. 그 결과 이후 실행이 Cannot run migrations because another migration process is currently running 오류로 실패합니다. 포트 5432를 사용하는 직접 연결 DATABASE_URL로 bin/rails db:migrate를 실행하거나, 다음과 같이 잠금을 비활성화하십시오.

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 파일이 있는지 확인하세요.

​

다음 단계

• production 구성에서도 동일한 sslmode 및 sslrootcert 설정을 사용하십시오.
• 연결: 연결 문자열(connection string), PgBouncer 및 TLS에 대해 설명합니다.
• 설정: max_connections 등 Postgres 및 PgBouncer 매개변수를 변경합니다.
• 읽기 레플리카(Read replica): 읽기 처리량을 확장합니다. 예를 들어 Rails의 다중 데이터베이스 기능과 함께 활용할 수 있습니다.
• Sync to ClickHouse: 분석을 위해 Rails 테이블을 ClickHouse로 복제합니다.