استخدام 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. يفعّل Rails العبارات المُعدّة مسبقاً في production، لكنها تكون معطّلة افتراضياً في development لأن query_log_tags_enabled مفعّل.
• عمليات الترحيل تحصل على قفل استشاري على مستوى الـ session ‏(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 لإجراء التحليلات.