استخدام Laravel مع ClickHouse Managed Postgres

Laravel هو إطار عمل ويب بلغة PHP يتضمن أداة مدمجة لربط الكائنات بقواعد البيانات (Eloquent)، ونظامًا لعمليات الترحيل (migrations)، وأداة سطر الأوامر artisan. في هذا الدليل، ستربط تطبيق Laravel جديدًا بخدمة ClickHouse Managed Postgres، وتنشئ جدول tasks عبر عملية ترحيل، ثم تعرض صفوفه من خلال مسار (route). تستخدم جميع الاتصالات بروتوكول TLS مع تحقق كامل من الشهادة.

المتطلبات الأساسية

PHP 8.3 أو إصدار أحدث، وهو ما يتطلبه Laravel 13، مع تثبيت الامتداد pdo_pgsql. شغّل الأمر php -m وتحقّق من ظهور pdo_pgsql في القائمة.
Composer
حساب على ClickHouse Cloud
psql، لإنشاء قاعدة البيانات. ويمكنك بدلًا من ذلك تشغيل عبارة CREATE DATABASE في SQL console.

إنشاء خدمة ClickHouse Managed Postgres

في وحدة تحكم ClickHouse Cloud، انقر على New service ثم اختر Postgres. سيصبح المثيل جاهزًا في غضون دقائق قليلة. للاطلاع على شرح تفصيلي للخطوات، راجع دليل البدء السريع.

الحصول على بيانات الاتصال

انقر على Connect في الشريط الجانبي الأيسر لخدمتك. تعرض النافذة المنبثقة اسم المستخدم وكلمة المرور والخادم والمنفذ، وتتضمن مفتاح تبديل بين Directly وvia PgBouncer. لا يحتفظ تطبيق PHP بمجمّع اتصالات بين الطلبات، إذ يفتح كل طلب افتراضيًا اتصالًا جديدًا بـ Postgres ويغلقه عند انتهائه. يربط هذا الدليل التطبيق عبر PgBouncer المضمَّن على المنفذ 6432، لكي تتشارك هذه الاتصالات قصيرة العمر عددًا محدودًا من عمليات Postgres الخلفية. أما عمليات الترحيل فتتصل بـ Postgres مباشرةً على المنفذ 5432، لأنها تنفّذ أوامر DDL وقد تُبقي معاملات طويلة مفتوحة. اختر via PgBouncer لعرض بيانات الاتصال عبر المجمّع. سيتغير المنفذ إلى 6432، وستتضمن سلاسل الاتصال sslmode=verify-full. في النافذة المنبثقة نفسها، انقر على Download CA certificate. ويمكنك أيضًا تنزيلها من Settings → CA Certificate. هذه الشهادة فريدة لمثيلك، ما يتيح للمشغّل استخدامها للتحقق من أنه يتصل بخادمك فعلًا.

إعداد المشروع

أنشئ مشروع Laravel:

composer create-project laravel/laravel laravel-managed-postgres
cd laravel-managed-postgres

هل تضيف إلى تطبيق موجود؟تخطَّ composer create-project. في مشروعك، تحقّق من أن pdo_pgsql يظهر ضمن مخرجات php -m، ثم اتبع بقية هذا القسم وانتقل بعدها إلى تهيئة الاتصال، إذ تنقل هذه الخطوة التطبيق من SQLite إلى Postgres. بعد ذلك، ينشئ الأمر php artisan migrate جداولك الحالية في Postgres، لكنه لا ينسخ البيانات من SQLite.

انقل شهادة CA التي نزّلتها إلى دليل المشروع، وأعد تسميتها إلى ca-certificate.pem. أنشئ قاعدة بيانات للتطبيق. استبدل <PASSWORD> والمضيف بالقيم الظاهرة في نافذة Connect:

psql "postgresql://postgres:<PASSWORD>@your-instance.pg.clickhouse.cloud:5432/postgres?sslmode=verify-full&sslrootcert=ca-certificate.pem" -c "CREATE DATABASE guide_laravel;"

CREATE DATABASE

تهيئة الاتصال

يستخدم Laravel قاعدة بيانات SQLite افتراضيًا. افتح الملف .env واستبدل السطر DB_CONNECTION=sqlite وأسطر DB_ المعطَّلة بعلامة التعليق أسفله بما يلي:

.env

DB_CONNECTION=pgsql
DB_HOST=your-instance.pg.clickhouse.cloud
DB_PORT=6432
DB_DATABASE=guide_laravel
DB_USERNAME=postgres
DB_PASSWORD=<PASSWORD>
DB_SSLMODE=verify-full
DB_SSLROOTCERT=/absolute/path/to/your-project/ca-certificate.pem

استخدم المسار المطلق للملف ca-certificate.pem، إذ تحلّ libpq المسار النسبي انطلاقًا من دليل العمل الخاص بعملية PHP، وهذا الدليل يتوقف على طريقة تشغيل PHP لتطبيقك. إذا كانت كلمة المرور تحتوي على مسافات أو على الرمز #، فضعها بين علامتي اقتباس مزدوجتين. واحرص على إبقاء الملف .env خارج نظام التحكم في الإصدارات. يقرأ اتصال pgsql الافتراضي في config/database.php القيمة DB_SSLMODE، لكنه لا يقرأ مسار شهادة CA. لذا افتح config/database.php وأضف العنصرين sslrootcert وoptions إلى الاتصال pgsql:

config/database.php

        'pgsql' => [
            'driver' => 'pgsql',
            'url' => env('DB_URL'),
            'host' => env('DB_HOST', '127.0.0.1'),
            'port' => env('DB_PORT', '5432'),
            'database' => env('DB_DATABASE', 'laravel'),
            'username' => env('DB_USERNAME', 'root'),
            'password' => env('DB_PASSWORD', ''),
            'charset' => env('DB_CHARSET', 'utf8'),
            'prefix' => '',
            'prefix_indexes' => true,
            'search_path' => 'public',
            'sslmode' => env('DB_SSLMODE', 'prefer'),
            'sslrootcert' => env('DB_SSLROOTCERT'),
            'options' => [
                PDO::ATTR_EMULATE_PREPARES => true,
            ],
        ],

يُلحق Laravel المعاملين sslmode وsslrootcert بسلسلة DSN الخاصة بـ PDO، ثم يمرّرهما الامتداد pdo_pgsql إلى libpq، الذي يتحقق بدوره من سلسلة الشهادات ومن اسم المضيف. يجعل الخيار PDO::ATTR_EMULATE_PREPARES مكتبة PDO ترسل كل استعلام وقيمه مربوطة به مسبقًا، بدلًا من إنشاء عبارة مُعدّة مسبقًا على جانب الخادم. فعّل هذا الخيار عند الاتصال عبر PgBouncer؛ إذ عندما يكون pdo_pgsql مبنيًا على الإصدار 16 من libpq أو ما قبله، كما هو الحال في Debian 12، تحرّر PHP كل عبارة مُعدّة مسبقًا باستخدام عبارة SQL DEALLOCATE. ولأن PgBouncer يعيد تسمية العبارات المُعدّة مسبقًا على الخادم، تفشل عبارة DEALLOCATE. وإذا وقع ذلك داخل معاملة، أُلغيت المعاملة، وفشل الاستعلام التالي مع الخطأ current transaction is aborted. أما مع الإصدار 17 من libpq أو ما بعده، فتعمل الإعدادات الافتراضية كذلك. نفّذ الأمر php -i | grep libpq لمعرفة الإصدار المثبّت لديك. تحقّق من الاتصال:

php artisan db:show

  PostgreSQL ................................ 18.6 (Ubuntu 18.6-1.pgdg22.04+2)  
  Connection ........................................................... pgsql  
  Database ..................................................... guide_laravel  
  Host ..................................... your-instance.pg.clickhouse.cloud  
  Port .................................................................. 6432  
  Username .......................................................... postgres  
  URL ........................................................................  
  Open Connections ........................................................ 44  
  Tables ................................................................... 0  

في غياب السطر sslrootcert، يفشل الوضع verify-full بالرسالة root certificate file ".../.postgresql/root.crt" does not exist، لأن libpq يلجأ إلى موقع CA الافتراضي الخاص به. أما عند استخدام CA غير صحيحة، فيفشل الاتصال بالرسالة SSL error: certificate verify failed.

إنشاء نموذج وملف ترحيل

أنشئ نموذج Eloquent وملف ترحيل للجدول tasks:

php artisan make:model Task -m

افتح ملف الترحيل الجديد في database/migrations/ (ينتهي اسمه بـ _create_tasks_table.php)، ثم أضف العمودين title وdone إلى الدالة up:

database/migrations/xxxx_xx_xx_xxxxxx_create_tasks_table.php

    public function up(): void
    {
        Schema::create('tasks', function (Blueprint $table) {
            $table->id();
            $table->string('title');
            $table->boolean('done')->default(false);
            $table->timestamps();
        });
    }

استبدل محتوى الملف app/Models/Task.php بما يلي، بحيث يمكن تعيين قيم الأعمدة دفعةً واحدة (mass assignment) وتُعاد قيمة done كقيمة منطقية (boolean):

app/Models/Task.php

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Fillable;
use Illuminate\Database\Eloquent\Model;

#[Fillable(['title', 'done'])]
class Task extends Model
{
    protected function casts(): array
    {
        return [
            'done' => 'boolean',
        ];
    }
}

شغّل عمليات الترحيل عبر الاتصال المباشر. تُقدَّم قيمة متغير البيئة على القيمة الموجودة في .env، لذا يكفي أن تغيّر المنفذ فقط:

DB_PORT=5432 php artisan migrate

   INFO  Preparing database.  

  Creating migration table ..................................... 289.95ms DONE

   INFO  Running migrations.  

  0001_01_01_000000_create_users_table ............................... 1s DONE
  0001_01_01_000001_create_cache_table ......................... 949.69ms DONE
  0001_01_01_000002_create_jobs_table ................................ 1s DONE
  2026_09_30_165735_create_tasks_table ......................... 240.59ms DONE

إلى جانب tasks، يُنشئ هذا الأمر جداول users وsessions وcache وjobs التي يستخدمها أي تطبيق Laravel جديد افتراضيًا. ويسجّل Laravel عمليات الترحيل المُطبَّقة في الجدول migrations، فلا يشغّل في الاستدعاءات اللاحقة إلا عمليات الترحيل الجديدة.

الاستعلام من قاعدة البيانات

أضف بضعة صفوف باستخدام Eloquent من خلال artisan tinker:

php artisan tinker --execute="App\Models\Task::create(['title' => 'Create a Managed Postgres service', 'done' => true]); App\Models\Task::create(['title' => 'Connect Laravel with verify-full TLS', 'done' => true]); App\Models\Task::create(['title' => 'Ship the app']); echo App\Models\Task::count();"

أضف في نهاية الملف routes/web.php مسارًا يُعيد جميع المهام بتنسيق JSON:

routes/web.php

Route::get('/tasks', function () {
    return App\Models\Task::orderBy('id')->get();
});

يطبّق Laravel خيارات الاتصال search_path وtimezone وisolation_level عند الاتصال باستخدام عبارات SET على مستوى الـ session، ولا تُحفَظ هذه الإعدادات بين المعاملات عند المرور عبر PgBouncer. لذا أبقِ هذه الخيارات على قيمها الافتراضية، أو اتصل مباشرةً عبر المنفذ 5432 إذا كنت بحاجة إليها. كذلك لا تعمل عبر PgBouncer الميزاتُ المعتمدة على الـ session، مثل LISTEN والأقفال الاستشارية (advisory locks) على مستوى الـ session. راجع الأسئلة الشائعة.

التشغيل والتحقق

شغّل خادم التطوير:

php artisan serve --port=3104

   INFO  Server running on [http://127.0.0.1:3104].  

  Press Ctrl+C to stop the server

افتح http://localhost:3104/tasks في متصفحك، وستظهر لك استجابة مشابهة لما يلي:

[
  {
    "id": 1,
    "title": "Create a Managed Postgres service",
    "done": true,
    "created_at": "2026-09-30T17:10:28.000000Z",
    "updated_at": "2026-09-30T17:10:28.000000Z"
  },
  {
    "id": 2,
    "title": "Connect Laravel with verify-full TLS",
    "done": true,
    "created_at": "2026-09-30T17:10:29.000000Z",
    "updated_at": "2026-09-30T17:10:29.000000Z"
  },
  {
    "id": 3,
    "title": "Ship the app",
    "done": false,
    "created_at": "2026-09-30T17:10:29.000000Z",
    "updated_at": "2026-09-30T17:10:29.000000Z"
  }
]

لعرض البيانات في وحدة التحكم، افتح SQL console من الشريط الجانبي الأيسر لخدمتك، ثم وسّع guide_laravel ثم public، وانقر على الجدول tasks. يتضمن المخطط public أيضًا جداول Laravel الافتراضية، مثل users وsessions وmigrations:

id	title	done	created_at	updated_at
1	Create a Managed Postgres service	true	2026-09-30 17:10:28	2026-09-30 17:10:28
2	Connect Laravel with verify-full TLS	true	2026-09-30 17:10:29	2026-09-30 17:10:29
3	Ship the app	false	2026-09-30 17:10:29	2026-09-30 17:10:29

الخطوات التالية

الاتصال: سلاسل الاتصال وPgBouncer وTLS
الإعدادات: معلمات Postgres وPgBouncer، مثل max_connections
النسخ المتماثلة للقراءة: توجيه عمليات القراءة إلى نسخة متماثلة باستخدام اتصالات القراءة والكتابة في Laravel
الأمان: قوائم التحكم في الوصول بعناوين IP والشبكات الخاصة

بدء الاستخدام

الميزات

أدلة إرشادية

الأسعار

تكامل ClickHouse

عمليات الترحيل

المراقبة

الأسئلة الشائعة

استخدام Laravel مع ClickHouse Managed Postgres

المتطلبات الأساسية

إنشاء خدمة ClickHouse Managed Postgres

الحصول على بيانات الاتصال

إعداد المشروع

تهيئة الاتصال

إنشاء نموذج وملف ترحيل

الاستعلام من قاعدة البيانات

التشغيل والتحقق

الخطوات التالية

​المتطلبات الأساسية

​إنشاء خدمة ClickHouse Managed Postgres

​الحصول على بيانات الاتصال

​إعداد المشروع

​تهيئة الاتصال

​إنشاء نموذج وملف ترحيل

​الاستعلام من قاعدة البيانات

​التشغيل والتحقق

​الخطوات التالية

المتطلبات الأساسية

إنشاء خدمة ClickHouse Managed Postgres

الحصول على بيانات الاتصال

إعداد المشروع

تهيئة الاتصال

إنشاء نموذج وملف ترحيل

الاستعلام من قاعدة البيانات

التشغيل والتحقق

الخطوات التالية