مرجع إعدادات عميل Go - ClickHouse Documentation

توثّق هذه الصفحة جميع الخيارات القابلة للإعداد في clickhouse-go v2.x. للاطلاع على دليل يتضمن أمثلة شيفرة، راجع الإعدادات.

تعليقات توضيحية للإصدارتُميَّز الخيارات التي أُضيفت في clickhouse-go v2.35.0 أو الإصدارات الأحدث بوسم (منذ vX.Y.Z) بجانب وصفها. أما الخيارات التي لا تتضمن وسم “منذ”، فهي متاحة منذ v2.0 وموجودة في جميع الإصدارات المدعومة.

كيفية تعيين الخيارات

تتوفر الخيارات على ثلاثة مستويات:

النطاق	كيفية التعيين	مدة الاستخدام
الاتصال	`clickhouse.Options` struct أو سلسلة DSN	جميع الاستعلامات على الاتصال
الاستعلام	`clickhouse.Context()` مع دوال `WithXxx`	تنفيذ استعلام واحد
الدفعة	دوال الخيارات في `PrepareBatch()`	عملية دفعة واحدة

عند تداخل المستويات، تكون الأولوية للمستوى الأكثر تحديدًا: الدفعة > الاستعلام > الاتصال. بالنسبة إلى Settings، تُدمج المفاتيح على مستوى الاستعلام مع المفاتيح على مستوى الاتصال، وتُحسم الأفضلية لمستوى الاستعلام عند التعارض. عبر struct Options:

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default", Password: ""},
    DialTimeout: 10 * time.Second,
    Compression: &clickhouse.Compression{Method: clickhouse.CompressionLZ4},
})

باستخدام سلسلة DSN:

db, err := sql.Open("clickhouse", "clickhouse://user:pass@localhost:9000/default?dial_timeout=10s&compress=lz4")

عبر Connector ‏(database/sql مع Options struct):

db := sql.OpenDB(clickhouse.Connector(&clickhouse.Options{
    Addr:        []string{"localhost:9000"},
    Auth:        clickhouse.Auth{Database: "default", Username: "default"},
    DialTimeout: 10 * time.Second,
}))
// Set database/sql-only pool settings after creation
db.SetConnMaxIdleTime(5 * time.Minute)

عبر السياق (لكل استعلام):

ctx := clickhouse.Context(context.Background(),
    clickhouse.WithQueryID("my-query-123"),
    clickhouse.WithSettings(clickhouse.Settings{"max_execution_time": 60}),
)
rows, err := conn.Query(ctx, "SELECT ...")

خيارات الاتصال

البروتوكول والاتصال

الخيار	النوع	الافتراضي	معامل DSN	الوصف	أفضل الممارسات	عند سوء الإعداد
`Protocol`	`Protocol` (int)	`Native`	Scheme: `clickhouse://`=Native, `http://`=HTTP	بروتوكول الاتصال: ‏`Native` (0) لـ TCP، و`HTTP` (1) لـ HTTP	استخدم Native للحصول على أداء أفضل بنحو ~30%. واستخدم HTTP لدعم الـ proxy، وتجاوز firewall (المنفذ 80/443)، أو الضغط المتاح عبر HTTP فقط (`gzip`/`br`). راجع TCP vs HTTP.	استخدام scheme الخاص بـ HTTP مع منفذ Native ‏(9000): رفض الاتصال. حظر Native بواسطة firewall: حالات timeout.
`Addr`	`[]string`	`["localhost:9000"]` (Native) `["localhost:8123"]` (HTTP)	hosts مفصولة بفواصل في URL	قائمة بعناوين `"host:port"` للاتصال وfailover	حدّد عدة عناوين في بيئات production لتحقيق التوافر العالي. المنافذ الصحيحة: 9000 ‏(Native)، و8123 ‏(HTTP)، و9440 ‏(Native+TLS)، و8443 ‏(HTTP+TLS).	عنوان واحد: لا يوجد failover. منفذ خاطئ: `"connection refused"`. قيمة فارغة/nil: يُستخدم localhost افتراضيًا، ما يؤدي إلى الفشل في عمليات النشر الموزعة.
`ConnOpenStrategy`	`ConnOpenStrategy` (uint8)	`ConnOpenInOrder` (0)	`connection_open_strategy` (`in_order`, `round_robin`, `random`)	استراتيجية لاختيار server من `Addr`. ‏`InOrder` (0)=failover، و`RoundRobin` (1)=موازنة حمل، و`Random` (2)=عشوائي.	استخدم `InOrder` لنمط active-standby. واستخدم `RoundRobin` لنمط active-active/K8s. واستخدم `Random` لتجنّب اندفاع الطلبات الجماعي.	عند استخدام `InOrder` مع active-active: يتلقى server الأول كل الحمل، وتبقى البقية idle. تحاول جميع الاستراتيجيات كل الخوادم عند الفشل — ويؤثر ذلك فقط على الخادم الذي تتم تجربته أولًا.

المصادقة

الخيار	النوع	الافتراضي	DSN param	الوصف	أفضل الممارسات	عند سوء الإعداد
`Auth.Username`	`string`	`"default"`	`username` or URL user portion	اسم المستخدم لمصادقة ClickHouse	لا تستخدم `default` مطلقًا في بيئة الإنتاج. أنشئ مستخدمين مخصصين بأقل الأذونات اللازمة.	اسم مستخدم غير صحيح: `"Code: 516. DB::Exception: Authentication failed"`. سلسلة فارغة: يُستخدم `"default"` بصمت.
`Auth.Password`	`string`	`""`	`password` or URL password portion	كلمة المرور لمصادقة ClickHouse	استخدم متغيرات البيئة أو مديري الأسرار في بيئة الإنتاج. شفّر الأحرف الخاصة في DSN بترميز URL.	كلمة مرور غير صحيحة: `"Code: 516. DB::Exception: Authentication failed"`. إذا لم تُرمَّز الأحرف الخاصة بترميز URL: أخطاء parsing.
`Auth.Database`	`string`	`""` (server default)	`database` or URL path (`/mydb`)	قاعدة البيانات الافتراضية للاتصال	حدّدها دائمًا بشكل صريح. استخدم قواعد بيانات مخصصة لكل تطبيق في بيئة الإنتاج.	غير موجودة: `"Code: 81. DB::Exception: Database xyz doesn't exist"`. إذا تُركت فارغة في إعداد متعدد المستأجرين: تُنفَّذ الاستعلامات على قاعدة بيانات خاطئة.
`GetJWT`	`func(ctx) (string, error)`	`nil`	(programmatic only)	دالة callback تُرجع JWT لمصادقة ClickHouse Cloud. يمكن تجاوزها لكل استعلام باستخدام `WithJWT(token)`. (منذ v2.35.0)	نفّذ تخزينًا مؤقتًا/تحديثًا للرمز المميز — إذ تُستدعى لكل اتصال/طلب.	رمز مميز منتهي الصلاحية: أخطاء مصادقة. callback حاجب: timeout. تكون لـ JWT أولوية على المستخدم/كلمة المرور. ويتطلب TLS — ومن دونه يعود إلى المستخدم/كلمة المرور بصمت.

GetJWT: func(ctx context.Context) (string, error) {
    return getTokenFromVault(ctx)
}

المهلات الزمنية

الخيار	النوع	القيمة الافتراضية	DSN param	الوصف	أفضل الممارسات	عند سوء الإعداد
`DialTimeout`	`time.Duration`	`30s`	`dial_timeout`	الحد الأقصى للوقت المسموح لإنشاء اتصال جديد. ويتحكم أيضًا في مدة انتظار الحصول على اتصال من المجمّع عند بلوغ `MaxOpenConns`.	من 5 إلى 10 ثوانٍ على LAN، ومن 15 إلى 30 ثانية على WAN/Cloud، ومن 1 إلى 2 دقيقة عند الاتصال بخدمة ClickHouse Cloud كانت في حالة خمول. لا تضبطه مطلقًا على أقل من ثانية واحدة.	إذا كان قصيرًا جدًا: قد يظهر `"clickhouse: acquire conn timeout"` أثناء الازدحام، أو يفشل الاتصال قبل أن تنتهي خدمة Cloud الخاملة من الاستيقاظ. وإذا كان طويلًا جدًا (> 60s): قد يبدو التطبيق معلّقًا أثناء الانقطاعات.
`ReadTimeout`	`time.Duration`	`5m` (300s)	`read_timeout`	الحد الأقصى لانتظار استجابة من الخادم لكل استدعاء قراءة. يُطبَّق على كل block، وليس على الاستعلام بالكامل. تكون الأولوية لـ context deadline.	من 10 إلى 30 ثانية للاستعلامات التفاعلية القصيرة؛ ومن 5 إلى 30 دقيقة للاستعلامات التحليلية الطويلة.	إذا كان قصيرًا جدًا: قد يظهر `"i/o timeout"` أو `"read: connection reset by peer"` في منتصف الاستعلام؛ بينما يواصل الخادم التنفيذ. وإذا كان طويلًا جدًا: فلن تُكتشف الاتصالات الميتة.

تُوضَع خدمة ClickHouse Cloud التي ظلت خاملة في حالة إيقاف مؤقت، ثم تستيقظ عند أول اتصال وارد. تستغرق عملية الاستيقاظ عادةً بضع عشرات من الثواني، وخلال هذه الفترة يظل طلب الاتصال معلّقًا. إذا كانت قيمة DialTimeout أقل من مدة الاستيقاظ، فسيفشل أول استعلام بعد فترة الخمول بسبب dial timeout بدلًا من أن يُنفَّذ.اضبط DialTimeout على 1m–2m للعملاء الذين قد يكونون أول من يصل إلى خدمة خاملة. والمقابل هو بطء اكتشاف الفشل عند حدوث انقطاع فعلي — إذ يظل طلب الاتصال معلّقًا حتى تنقضي المهلة بالكامل قبل ظهور الخطأ — لذا يُفضَّل قصر المهلة الأعلى على الاتصال الأول، أو استخدام context deadlines على الاستعلامات الفردية لتحديد latency من البداية إلى النهاية.

مجمع الاتصالات

الخيار	النوع	الافتراضي	معامل DSN	واجهة برمجة تطبيقات	الوصف	أفضل الممارسات	عند سوء الإعداد
`MaxIdleConns`	`int`	`5`	`max_idle_conns`	كلاهما	الحد الأقصى للاتصالات الخاملة (غير المستخدمة ولكنها ما تزال مفتوحة) في المجمع	50-80% من عدد الاستعلامات المتزامنة المتوقع. منخفض: 2-5، متوسط: 10-20، مرتفع: 20-50.	منخفض جدًا: كثرة إنشاء الاتصالات وإغلاقها، وارتفاع زمن الوصول. مرتفع جدًا: هدر في الذاكرة. ويُحدّ تلقائيًا بقيمة `MaxOpenConns`.
`MaxOpenConns`	`int`	`MaxIdleConns + 5` (الافتراضي: 10)	`max_open_conns`	كلاهما	الحد الأقصى لإجمالي الاتصالات (الخاملة + النشطة)	منخفض: 10-20، متوسط: 20-50، مرتفع: 50-100. الصيغة: الاستعلامات المتزامنة + الارتفاعات المفاجئة + مخزن مؤقت. راقب: `SELECT * FROM system.metrics WHERE metric='TCPConnection'`.	منخفض جدًا: `"clickhouse: acquire conn timeout"`. مرتفع جدًا: `"Too many connections"` على الخادم، وتجاوز حدود واصفات الملفات (FD). القيمة الافتراضية لـ `max_connections` في ClickHouse هي: 1024 (مشتركة).
`ConnMaxLifetime`	`time.Duration`	`1h`	`conn_max_lifetime`	كلاهما	الحد الأقصى لمدة إعادة استخدام الاتصال. ويُفحص عند إرجاعه إلى المجمع.	من 1 إلى 5 ساعات للبيئات المستقرة. من 5 إلى 15 دقيقة لعمليات النشر المتدرّج/K8s. لا تجعله غير محدود أبدًا.	قصير جدًا (< 1m): كثرة إنشاء الاتصالات وإغلاقها، وارتفاع زمن الوصول. طويل جدًا/غير محدود: اتصالات قديمة، وعدم التقاط تغييرات DNS، وعدم إعادة توزيع حركة المرور.
`ConnMaxIdleTime`	`time.Duration`	`0` (لا شيء)	—	`database/sql` فقط	الحد الأقصى للوقت الذي يمكن أن يظل فيه الاتصال خاملًا قبل إغلاقه. غير متاح في `Options` struct — اضبطه عبر `db.SetConnMaxIdleTime()`.	من 5 إلى 10 دقائق لـ K8s/أحمال العمل المتقطعة لتحرير الاتصالات الخاملة بعد ارتفاعات حركة المرور.	إذا لم يتم ضبطه: تستمر الاتصالات الخاملة حتى `ConnMaxLifetime`. قصير جدًا (< 30s): يُعاد إنشاء الاتصالات أثناء فترات الخمول المعتادة.

database/sql فقطConnMaxIdleTime هو إعداد قياسي لمجمع database/sql في Go. ولا يتوفر في clickhouse.Options struct أو عبر clickhouse.Open(). اضبطه بعد OpenDB():

db := clickhouse.OpenDB(&clickhouse.Options{...})
db.SetConnMaxIdleTime(5 * time.Minute)

راجع تجميع الاتصالات للحصول على تفاصيل الاستخدام.

إعدادات مجمّع `database/sql` القياسية

عند استخدام clickhouse.OpenDB() أو sql.Open("clickhouse", dsn)، فإن الكائن *sql.DB المُعاد يدعم طرق المجمّع القياسية في Go. يطبّق OpenDB() تلقائيًا أول ثلاثٍ منها من Options:

الطريقة	المكافئ في `Options`	ملاحظات
`db.SetMaxIdleConns(n)`	`MaxIdleConns`	يُطبَّق تلقائيًا بواسطة `OpenDB()`
`db.SetMaxOpenConns(n)`	`MaxOpenConns`	يُطبَّق تلقائيًا بواسطة `OpenDB()`
`db.SetConnMaxLifetime(d)`	`ConnMaxLifetime`	يُطبَّق تلقائيًا بواسطة `OpenDB()`
`db.SetConnMaxIdleTime(d)`	لا يوجد	يجب تعيينه يدويًا بعد الإنشاء

ClickHouse API (clickhouse.Open)هذه الطرق غير متاحة على الاتصال المُعاد من clickhouse.Open(). تدير ClickHouse API مجمّعها الداخلي باستخدام حقول struct ‏Options مباشرةً.

الضغط

Option	النوع	الافتراضي	معامل DSN	الوصف	أفضل الممارسات	عند سوء الإعداد
`Compression.Method`	`CompressionMethod` (byte)	None	`compress` (`lz4`, `zstd`, `lz4hc`, `gzip`, `deflate`, `br`, or `true` for LZ4)	خوارزمية الضغط المستخدمة في نقل البيانات. راجع مصفوفة دعم البروتوكولات أدناه.	LAN: None أو LZ4. WAN: ZSTD أو LZ4. عند محدودية CPU: ‏LZ4. لأقصى ضغط: ZSTD ‏(Native) أو Brotli ‏(HTTP). تخطَّه لعمليات الإدراج الأصغر من < 1 MB.	GZIP/Brotli على Native: فشل في المصافحة. ‏LZ4HC على HTTP: خطأ أو fallback صامت. بدون ضغط على الشبكات البطيئة: تصبح عمليات الإدراج أبطأ بمقدار 10-100x.
`Compression.Level`	`int`	`3`	`compress_level`	مستوى خاص بالخوارزمية. GZIP/Deflate: من -2 إلى 9. Brotli: من 0 إلى 11. ‏LZ4/ZSTD: يتم تجاهله.	GZIP متوازن: 3-6. Brotli متوازن: 4-6.	مستويات مرتفعة جدًا: استهلاك CPU كبير جدًا مقابل فائدة محدودة. قيمة غير صفرية لـ LZ4/ZSTD: يتم تجاهلها بصمت. تحديد المستوى بدون تمكين الضغط: بلا تأثير.
`MaxCompressionBuffer`	`int` (bytes)	`10485760` (10 MiB)	`max_compression_buffer`	الحد الأقصى لحجم مخزن الضغط المؤقت قبل التفريغ. لكل connection مخزنها المؤقت الخاص.	القيمة الافتراضية 10 MiB مناسبة. 20-50 MiB للصفوف العريضة. إجمالي الذاكرة = المخزن المؤقت × `MaxOpenConns`.	صغير جدًا (< 1 MiB): عمليات تفريغ متكررة وكفاءة ضعيفة. كبير جدًا (> 100 MiB): ‏OOM عند وجود عدد كبير من الاتصالات.

دعم طريقة الضغط حسب البروتوكول:

Method	Native	HTTP
`CompressionLZ4`	نعم	نعم
`CompressionLZ4HC`	نعم	لا
`CompressionZSTD`	نعم	نعم
`CompressionGZIP`	لا	نعم
`CompressionDeflate`	لا	نعم
`CompressionBrotli`	لا	نعم

TLS

الخيار	النوع	الافتراضي	معامل DSN	الوصف	أفضل الممارسات	عند الإعداد الخاطئ
`TLS`	`*tls.Config`	`nil` (نص غير مشفّر)	`secure=true`, `skip_verify=true`	إعداد TLS/SSL. تؤدي القيمة غير `nil` إلى تفعيل TLS. المنافذ: Native ‏9000/9440، وHTTP ‏8123/8443.	فعِّله دائمًا في بيئة production وفي ClickHouse Cloud (إلزامي). استخدم `InsecureSkipVerify: false` في بيئة production. أضف شهادات CA مخصّصة عبر `RootCAs`.	منفذ غير صحيح: `"connection reset by peer"`. استخدام `skip_verify=true` في بيئة production: يعرّضك لهجمات MITM. شهادة منتهية الصلاحية: `"x509: certificate has expired"`. اسم مضيف غير صحيح: `"x509: certificate is valid for X, not Y"`. CA غير موثوقة: `"x509: certificate signed by unknown authority"`. عند استخدام HTTP DSN مع `secure=true`: استخدم المخطط `https://` بدلًا من ذلك.

راجع TLS للاطلاع على أمثلة الشيفرة.

تسجيل الأحداث

الخيار	النوع	الافتراضي	DSN param	الوصف	أفضل الممارسات	عند سوء الإعداد
`Logger`	`*slog.Logger`	`nil` (من دون تسجيل)	—	مُسجِّل منظَّم عبر `log/slog` في Go. الأولوية: `Debug`+`Debugf` > `Logger` > `no-op`. (منذ v2.43.0)	استخدم `slog` مع معالج JSON في بيئة الإنتاج. أضف سياق التطبيق باستخدام `logger.With(...)`.	—
`Debug` (مهمل)	`bool`	`false`	`debug`	مفتاح تبديل Debug قديم. استخدم `Logger` بدلًا منه. يكتب السجلات إلى stdout ما لم يتم تعيين `Debugf`.	—	عند تفعيله في بيئة الإنتاج: عبء إضافي على الأداء، سجلات تفصيلية، وبيانات حساسة في المخرجات.
`Debugf` (مهمل)	`func(string, ...any)`	`nil`	—	دالة مخصّصة لسجلّات التصحيح. استخدم `Logger` بدلًا منها. تتطلب `Debug: true`.	—	—

logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo}))
conn, err := clickhouse.Open(&clickhouse.Options{
    Logger: logger,
    // ...
})

راجع التسجيل للاطلاع على أمثلة كاملة.

المخازن المؤقتة والذاكرة

الخيار	النوع	الافتراضي	معامل DSN	لكل استعلام	الوصف	أفضل الممارسات	عند سوء الإعداد
`BlockBufferSize`	`uint8`	`2`	`block_buffer_size`	نعم (`WithBlockBufferSize`)	الكتل بعد فك ترميزها التي تُخزَّن مؤقتًا عند قراءة النتائج. يتيح القراءة وفك الترميز بالتوازي.	القيمة الافتراضية 2 مناسبة. استخدم 5-10 للنتائج المتدفقة الكبيرة. الذاكرة = المخزن المؤقت × حجم الكتلة × عدد الاستعلامات المتزامنة.	صغير جدًا (1): يعيق قارئ الكتل، ويزيد زمن الاستجابة. كبير جدًا (> 50): استهلاك مرتفع للذاكرة، مع فائدة متناقصة.
`FreeBufOnConnRelease`	`bool`	`false`	—	لا	حرّر المخزن المؤقت لذاكرة الاتصال بعد كل استعلام بدلًا من إعادة استخدامه.	استخدم `false` لمعدلات الاستعلام المرتفعة. واستخدم `true` في الحاويات محدودة الذاكرة أو للدفعات الكبيرة غير المتكررة.	`false` + ذاكرة محدودة: تتراكم المخازن المؤقتة (الذاكرة = المخزن المؤقت × الاتصالات الخاملة). `true` + معدل مرتفع: ضغط على GC، وزيادة في CPU.

خاص بـ HTTP

يُتجاهَل بصمت عند استخدام Nativeلا تؤثر هذه الخيارات إلا في Protocol: clickhouse.HTTP. وعند استخدام البروتوكول Native، تُتجاهَل بصمت من دون إصدار أي خطأ أو تحذير.

الخيار	النوع	الافتراضي	DSN param	الوصف	أفضل الممارسات	عند سوء الإعداد
`HttpHeaders`	`map[string]string`	`nil`	—	ترويسات HTTP إضافية مع كل طلب	استخدمه للتتبّع (`X-Request-ID`) وترويسات وكيل المصادقة. وأبقِه في الحد الأدنى.	تجاوز الترويسات الداخلية (`Content-Type`, `Authorization`): سلوك غير متوقع.
`HttpUrlPath`	`string`	`""`	`http_path`	مسار URL يُضاف إلى الطلبات. وتُضاف `/` في البداية تلقائيًا.	استخدمه عند العمل خلف خادم وكيل عكسي مع توجيه قائم على المسار.	مسار غير صحيح: HTTP 404 من الوكيل/LB.
`HttpMaxConnsPerHost`	`int`	`0` (غير محدود)	—	اتصالات TCP لكل مضيف على مستوى طبقة النقل (`http.Transport.MaxConnsPerHost`).	اتركه على 0 في معظم التطبيقات. ولا تضبطه إلا إذا كانت لدى الخادم حدود صارمة للاتصالات.	قيمة منخفضة جدًا (مثل 10 مع `MaxOpenConns`=50): اختناق في طبقة النقل، واستعلامات بطيئة رغم انخفاض حمل الخادم.
`HTTPProxyURL`	`*url.URL`	`nil` (يستخدم متغيرات البيئة)	`http_proxy` (مرمّز بصيغة URL)	وكيل HTTP لتوجيه الطلبات	اضبطه صراحةً إذا كان الوكيل مطلوبًا. ويتجاوز متغيرات البيئة `HTTP_PROXY`/`HTTPS_PROXY`.	عنوان غير صحيح: `"dial tcp: lookup proxy: no such host"`. إذا كان الوكيل يتطلب مصادقة: HTTP 407.
`TransportFunc`	`func(*http.Transport) (http.RoundTripper, error)`	`nil`	—	مُنشئ نقل HTTP مخصّص. يتلقى النقل الافتراضي لالتفافه. (منذ v2.41.0)	استخدمه مع برمجية وسيطة لـ observability. لا تستبدل `Proxy` أو `DialContext` أو `TLSClientConfig`.	إرجاع `nil`: panic. استبدال حقول client: يتم تجاهل TLS/الوكيل بصمت. `RoundTripper` حاجب: deadlocks.

تجميع اتصالات HTTP على طبقتينعند استخدام HTTP، توجد مجموعتا اتصالات:

الطبقة 1 (التطبيق): MaxIdleConns / MaxOpenConns — تتحكم في كائنات httpConnect
الطبقة 2 (النقل): HttpMaxConnsPerHost — تتحكم في اتصالات TCP الأساسية

يملك البروتوكول Native تعيينًا بسيطًا بنسبة 1:1، ويتجاهل HttpMaxConnsPerHost.

TransportFunc: func(t *http.Transport) (http.RoundTripper, error) {
    return &loggingRoundTripper{transport: t}, nil
}

الاتصال المتقدم

الخيار	النوع	الافتراضي	معامل DSN	الوصف	أفضل الممارسات	عند سوء الإعداد
`DialContext`	`func(ctx, addr) (net.Conn, error)`	`nil` (dialer قياسي)	—	دالة dial مخصصة لاتصالات TCP. تعمل مع كلٍّ من Native وHTTP.	اتركها `nil` في 99% من الحالات. استخدمها لمقابس Unix، وبروكسي SOCKS، وDNS مخصص.	عدم مراعاة السياق: تعليق وتسرب للموارد. عند ضبط `TLS`: يجب أن يتولى الـdialer المخصص معالجة TLS بنفسه. `net.Conn` غير صالح: انهيار.
`DialStrategy`	`func(ctx, connID, options, dial) (DialResult, error)`	`DefaultDialStrategy`	—	استراتيجية مخصصة لاختيار الخادم والاتصال. تتجاوز `ConnOpenStrategy`.	استخدم الإعداد الافتراضي في 99.9% من الحالات. خصصها فقط للتوجيه المراعي للموقع الجغرافي، والاختيار الموزون، وفحوصات الحالة الصحية.	عدم تجربة جميع الخوادم: يؤدي إلى فشل رغم توفر خوادم سليمة. العمليات المكلفة داخله: تعرقل الحصول على اتصال من الـpool عند كل اتصال.

معلومات العميل

Option	Type	Default	DSN param	Per-query	Description	Best practice	When misconfigured
`ClientInfo`	`ClientInfo` struct	تلقائي: إصدار `clickhouse-go` + بيئة تشغيل Go	`client_info_product=myapp/1.0`	نعم (`WithClientInfo`، مع الإضافة)	معلومات تعريف التطبيق المُرسلة إلى ClickHouse. تحتوي على `Products` (`[]struct{Name,Version}`) و`Comment` (`[]string`). وتظهر في `system.query_log`.	احرص دائمًا على تعيين اسم التطبيق + الإصدار. لتتبّع مصدر الاستعلامات: `SELECT client_name FROM system.query_log WHERE client_name LIKE '%myapp%'`	عند عدم تعيينها: لا يمكن تحديد الخدمة التي أرسلت الاستعلامات في البيئات متعددة الخدمات.

ClientInfo: clickhouse.ClientInfo{
    Products: []struct{ Name, Version string }{
        {Name: "my-service", Version: "1.0.0"},
    },
}
// Appears as: clickhouse-go/2.x my-service/1.0.0 (lv:go/1.23; os:linux)

إعدادات خادم ClickHouse

الخيار	النوع	الافتراضي	معامل DSN	لكل استعلام	الوصف	أفضل الممارسات	عند سوء الإعداد
`Settings`	`map[string]any`	`nil`	أي معلمة غير معروفة (مثل `?max_execution_time=60`)	نعم (`WithSettings`، وتكون الأولوية للسياق عند التعارض)	إعدادات خادم ClickHouse التي تُطبَّق على كل استعلام. تحويل DSN: `"true"`→`1`، و`"false"`→`0`، والقيم الرقمية→`int`.	اضبط الحدود الشائعة على مستوى الاتصال، وخصّصها لكل استعلام عبر السياق.	الأخطاء الإملائية: تُتجاهل بصمت أو تتسبب في خطأ حسب الإصدار. الأنواع غير الصحيحة: `"Cannot parse string 'abc' as Int64"`. `max_execution_time=0` + no deadline: تستمر الاستعلامات إلى الأبد.
`CustomSetting`	`CustomSetting{Value string}`	—	—	نعم (عبر `WithSettings`)	يضع علامة على الإعداد باعتباره “مخصصًا” (غير مهم) لبروتوكول Native. لن ينتج عنه خطأ إذا لم يتعرّف عليه الخادم. ويتعامل HTTP مع جميع الإعدادات على أنها مخصصة افتراضيًا.	استخدمه مع الإعدادات Experimental أو الخاصة بإصدارات محددة.	إذا وُسِمت الإعدادات المهمة على أنها مخصصة، فقد تُتجاهل بصمت إذا كانت غير مدعومة.

إعدادات شائعة:

Setting	Type	Description
`max_execution_time`	int	مهلة الاستعلام بالثواني
`max_memory_usage`	int	حد الذاكرة لكل استعلام (بالبايت)
`max_block_size`	int	حجم block للمعالجة
`readonly`	int	1 = للقراءة فقط، 2 = للقراءة فقط + تغيير الإعدادات

Settings: clickhouse.Settings{
    "max_execution_time":  60,                                        // important -- errors if unknown
    "my_custom_setting":   clickhouse.CustomSetting{Value: "value"},  // custom -- ignored if unknown
}

خيارات الاستعلام على مستوى Context

يمكن ضبطها لكل استعلام باستخدام clickhouse.Context():

ctx := clickhouse.Context(context.Background(),
    clickhouse.WithQueryID("my-query"),
    clickhouse.WithSettings(clickhouse.Settings{"max_execution_time": 60}),
)

سلوك المهلة المرتبطة بالسياقإذا كانت للسياق مهلة نهائية > 1s، فسيُضبط max_execution_time تلقائيًا على seconds_remaining + 5. ويحلّ هذا محل أي قيمة مُعيّنة يدويًا.

الخيار	النوع	القيمة الافتراضية	البروتوكول	الوصف	أفضل الممارسات	عند سوء التهيئة
`WithQueryID`	`string`	يُولَّد تلقائيًا	كلاهما	معرّف مخصّص للاستعلام. يظهر في `system.query_log` و`system.processes`.	استخدم UUIDs. يفيد في `KILL QUERY WHERE query_id='...'`.	معرّفات مكررة: تُسبّب التباسًا في `system.query_log`.
`WithQuotaKey`	`string`	`""`	كلاهما	مفتاح Quota لفرض حدود الموارد في البيئات متعددة المستأجرين. يتطلب إعداد Quota على الخادم.	استخدمه لفرض حدود لكل عميل أو لكل مستخدم.	لم يُعَدّ QUOTA: يُتجاهَل بصمت.
`WithJWT`	`string`	`""`	HTTPS فقط	تجاوز JWT على مستوى كل استعلام في ClickHouse Cloud. (منذ الإصدار v2.35.0)	يُستخدم للمصادقة لكل طلب في الوكلاء متعددي المستأجرين.	من دون TLS: تُهمَل، ويُعاد الاعتماد على مصادقة الاتصال. منتهي الصلاحية: `"Token has expired"`.
`WithSettings`	`Settings`	يرث إعدادات connection	كلاهما	إعدادات الخادم لكل query. تُدمج مع إعدادات الاتصال؛ وعند التعارض، تكون الأولوية للسياق.	اضبط `max_execution_time` أو `max_rows_to_read` لكل نوع استعلام.	مثل `Settings` على مستوى الاتصال.
`WithParameters`	`المعاملات` (`map[string]string`)	`nil`	كلاهما	قيم الاستعلام ذي المعلمات من جهة الخادم. صياغة الاستعلام: `{param_name:Type}`.	استخدمه بدلًا من دمج السلاسل النصية لتفادي حقن SQL.	المعلَمة المفقودة: `"Substitution {param_name:Type} isn't set"`. النوع غير الصحيح: `"Cannot parse string 'abc' as UInt64"`.
`WithAsync`	`bool` (wait)	متزامن	كلاهما	وضع insert غير المتزامن. يضبط `async_insert=1`. تؤدي `wait=true` إلى إضافة `wait_for_async_insert=1`. يتطلب ClickHouse 21.11+. (منذ v2.41.0؛ ويحل محل `WithStdAsync` الأقدم.)	استخدمه لعمليات الإدراج عالية الإنتاجية.	`wait=false`: قد تظهر الأخطاء بشكل غير متزامن — تحقّق من `system.asynchronous_insert_log`. مع SELECT: يُتجاهل. في الخوادم القديمة: `"Unknown setting async_insert"`.
`WithLogs`	`func(*Log)`	`nil`	للبروتوكول الأصلي فقط	استدعاء عكسي لإدخالات سجل الخادم أثناء تنفيذ الاستعلام.	احرص على أن يكون سريعًا — لأنه يحظر التنفيذ. استخدم goroutines للمعالجة الثقيلة.	مع HTTP: لا يُستدعى مطلقًا من دون أي تنبيه.
`WithProgress`	`func(*Progress)`	`nil`	Native فقط	تحديثات تقدّم الاستعلام (الصفوف/البايتات التي تمت معالجتها).	اجعله سريعًا — فهو يعرقل التنفيذ.	مع HTTP: لا يُستدعى مطلقًا من دون أي تنبيه.
`WithProfileInfo`	`func(*ProfileInfo)`	`nil`	لبروتوكول Native فقط	دالة رد نداء لإحصاءات تنفيذ الاستعلام.	احرص على أن تكون سريعة — فهي تعيق التنفيذ.	مع HTTP: لا تُستدعى مطلقًا من دون أي تنبيه.
`WithProfileEvents`	`func([]ProfileEvent)`	`nil`	لبروتوكول Native فقط	دالة ردّ نداء لعدادات الأداء.	أبقِه سريعًا — لأنه يحجب التنفيذ.	مع HTTP: لا يُستدعى مطلقًا من دون أي تنبيه.
`WithoutProfileEvents`	—	يتم إرسال الأحداث	البروتوكول الأصلي فقط	تعطيل أحداث profile. تحسين الأداء للخوادم ≥ 25.11. (منذ v2.44.0)	استخدمه عندما لا تحتاج إلى أحداث profile.	على الخوادم الأقدم: يظهر خطأ بسبب إعداد غير معروف.
`WithExternalTable`	`...*ext.Table`	`nil`	كلاهما	إرفاق جداول بحث مؤقتة بالاستعلام. تُنقَل البيانات مع كل استعلام.	أبقِ حجم الجداول أقل من 10 MB. البروتوكول الأصلي أكثر كفاءة من HTTP (متعدد الأجزاء).	الجداول الكبيرة: حمل شبكي إضافي لكل استعلام.
`WithUserLocation`	`*time.Location`	المنطقة الزمنية للخادم	كلاهما	تجاوز المنطقة الزمنية المستخدمة في تحليل DateTime.	اضبطه صراحةً عند اختلاف المنطقة الزمنية بين العميل والخادم.	منطقة زمنية غير صحيحة: قد تنحرف قيم DateTime بصمت بعدة ساعات، مع احتمال تلف البيانات.
`WithColumnNamesAndTypes`	`[]ColumnNameAndType`	`nil` (ينفّذ DESCRIBE)	لـ HTTP فقط	تجنّب طلب `DESCRIBE TABLE` الإضافي في عمليات `insert` عبر HTTP من خلال توفير معلومات الأعمدة مسبقًا. (منذ v2.37.0)	استخدمه عندما يكون المخطط معروفًا ومستقرًا.	أنواع غير صحيحة: `"Cannot convert String to UInt64"`. انجراف المخطط بعد الترحيل: معلومات قديمة.
`WithBlockBufferSize`	`uint8`	على مستوى الاتصال (2)	كلاهما	تجاوز قيمة `BlockBufferSize` المحددة على مستوى الاتصال لاستعلام واحد.	زِد القيمة عند التعامل مع مجموعات نتائج كبيرة في استعلامات محددة.	—
`WithClientInfo`	`ClientInfo`	على مستوى الاتصال	كلاهما	ألحِق معلومات عميل إضافية باستعلام واحد. لا يستبدل المعلومات الحالية، بل يُلحقها. (منذ v2.42.0)	أضِف سياقًا خاصًا بكل طلب (مثل اسم نقطة النهاية).	—
`WithSpan`	`trace.SpanContext`	فارغ	الأصلي فقط	سياق span في OpenTelemetry للتتبّع الموزّع.	راجع OpenTelemetry.	—

ctx := clickhouse.Context(ctx,
    clickhouse.WithQueryID("query-123"),
    clickhouse.WithParameters(clickhouse.Parameters{
        "user_id": "12345",
    }),
    clickhouse.WithProgress(func(p *clickhouse.Progress) {
        log.Printf("Progress: %d rows, %d bytes", p.Rows, p.Bytes)
    }),
)
rows, err := conn.Query(ctx, "SELECT * FROM users WHERE id = {user_id:String}")

خيارات Batch

تُمرَّر إلى PrepareBatch(). الاستيراد: github.com/ClickHouse/clickhouse-go/v2/lib/driver.

الخيار	القيمة الافتراضية	الوصف	أفضل الممارسات	عند سوء الإعداد
`WithReleaseConnection`	يُحتفَظ بالاتصال حتى `Send()`	يحرّر الاتصال إلى المجمّع مباشرةً بعد `PrepareBatch()`. ويُعاد الحصول عليه عند `Send()`/`Flush()`.	استخدمه مع دفعات طويلة العمر (دقائق/ساعات) لمنع استنزاف المجمّع.	عدم استخدامه مع الدفعات الطويلة: `"acquire conn timeout"` إذا كان هناك عدد كبير من الاتصالات النشطة.
`WithCloseOnFlush`	يبقى Batch مفتوحًا	يُغلِق Batch تلقائيًا عند استدعاء `Flush()`.	استخدمه مع الدفعات أحادية الاستخدام. ويوفّر عليك استدعاء `Close()“ صراحةً.	استخدامه مع عدة استدعاءات `Flush()`: يؤدي التفريغ الأول إلى إغلاق Batch، وتفشل العمليات اللاحقة.

batch, err := conn.PrepareBatch(ctx, "INSERT INTO table",
    driver.WithReleaseConnection(),
    driver.WithCloseOnFlush(),
)

جداول للرجوع السريع

توصيات تحديد حجم مجمع الاتصالات

نوع التطبيق	MaxIdleConns	MaxOpenConns	ConnMaxLifetime
تطبيق ويب منخفض الحركة	5	10	1h
واجهة برمجة تطبيقات متوسطة الحركة	20	50	30m
خدمة عالية الحركة	50	100	15m
مهام دفعية في الخلفية	10	20	2h
عملية نشر على Kubernetes	10	20	10m
بدون خادم (Lambda)	1	5	5m

توصيات timeout

البيئة	DialTimeout	ReadTimeout
محلي / LAN	5s	30s
Cloud، نفس المنطقة	10s	2m
Cloud، عبر منطقة أخرى	30s	5m
عبء عمل OLAP	10s	30m
فوري / OLTP	5s	10s

مرجع سريع لمعلمات DSN

معامل DSN	حقل الخيارات	مثال
`username`	`Auth.Username`	`?username=admin`
`password`	`Auth.Password`	`?password=secret`
`database`	`Auth.Database`	`?database=mydb` أو `/mydb` في المسار
`dial_timeout`	`DialTimeout`	`?dial_timeout=10s`
`read_timeout`	`ReadTimeout`	`?read_timeout=5m`
`max_open_conns`	`MaxOpenConns`	`?max_open_conns=50`
`max_idle_conns`	`MaxIdleConns`	`?max_idle_conns=20`
`conn_max_lifetime`	`ConnMaxLifetime`	`?conn_max_lifetime=30m`
`connection_open_strategy`	`ConnOpenStrategy`	`?connection_open_strategy=round_robin`
`block_buffer_size`	`BlockBufferSize`	`?block_buffer_size=10`
`compress`	`Compression.Method`	`?compress=lz4`
`compress_level`	`Compression.Level`	`?compress_level=6`
`max_compression_buffer`	`MaxCompressionBuffer`	`?max_compression_buffer=20971520`
`secure`	`TLS`	`?secure=true`
`skip_verify`	`TLS.InsecureSkipVerify`	`?skip_verify=true`
`debug`	`Debug`	`?debug=true`
`client_info_product`	`ClientInfo.Products`	`?client_info_product=myapp/1.0`
`http_proxy`	`HTTPProxyURL`	`?http_proxy=http%3A%2F%2Fproxy%3A8080`
`http_path`	`HttpUrlPath`	`?http_path=/clickhouse`
(أي معلمة أخرى)	`Settings[key]`	`?max_execution_time=60`

استكشاف الأخطاء وإصلاحها

استُنفِد مجمع الاتصالات: “acquire conn timeout”

السبب: استُنفِد مجمع الاتصالات — فجميع اتصالات MaxOpenConns قيد الاستخدام، ولم تصبح أيٌّ منها متاحة خلال المهلة DialTimeout. الحل جرّب الخطوات التالية بالترتيب، وشخِّص السبب الجذري قبل ضبط الإعدادات:

تحقّق من وجود استعلامات طويلة التشغيل تحتفظ بالاتصالات: SELECT query_id, elapsed FROM system.processes ORDER BY elapsed DESC. إذا وُجدت، فابدأ بمعالجة الاستعلامات البطيئة أولًا.
إذا كنت تشغّل دفعات طويلة العمر (دقائق/ساعات بين PrepareBatch() وSend())، فاستخدم WithReleaseConnection() لإعادة الاتصال إلى مجمع الاتصالات مع بقاء الدفعة مفتوحة.
زِد MaxOpenConns ليتوافق مع مستوى التزامن المرصود.
زِد DialTimeout فقط إذا كانت الاندفاعات المفاجئة في الحمل متوقعة، وكان انتظار الحصول على اتصال هو عنق الزجاجة الفعلي.

أخطاء مهلة القراءة وإعادة تعيين الاتصال

السبب: تم تجاوز ReadTimeout أثناء انتظار استجابة من الخادم، أو أُغلِق الاتصال من جهة الخادم أو الشبكة. الحل:

زِد قيمة ReadTimeout للاستعلامات طويلة التنفيذ
استخدم context deadlines للتحكم في المهلة لكل استعلام
تحقّق من حدود max_execution_time على جهة خادم ClickHouse

”Code: 516. Authentication failed”

السبب: اسم المستخدم أو كلمة المرور غير صحيحَين، أو أن المستخدم غير موجود. الحل:

تحقّق من بيانات الاعتماد في جدول system.users
تحقّق من عدم وجود مشكلات في ترميز URL للأحرف الخاصة في كلمات مرور DSN
تأكّد من أن المستخدم لديه حق الوصول إلى قاعدة البيانات المحددة

أخطاء شهادة TLS

الخطأ	السبب	الحل
`x509: certificate has expired`	انتهت صلاحية شهادة الخادم	جدِّد شهادة الخادم
`x509: certificate is valid for X, not Y`	عدم تطابق اسم المضيف	استخدم اسم المضيف الصحيح أو أضِفه إلى SANs
`x509: certificate signed by unknown authority`	جهة إصدار الشهادات (CA) غير موثوقة	أضِف CA إلى `tls.Config.RootCAs`
`connection reset by peer`	عدم تطابق TLS/المنفذ	استخدم المنفذ 9440 ‏(Native) أو 8443 ‏(HTTP) مع TLS

الزيادة التدريجية في استهلاك الذاكرة

السبب: تراكم مخازن مؤقتة كبيرة لاتصالات غير النشطة. الحل:

اضبط FreeBufOnConnRelease: true في البيئات محدودة الذاكرة
قلّل MaxIdleConns للحد من الاتصالات غير النشطة
قلّل MaxCompressionBuffer إذا كنت تستخدم الضغط
خفّض ConnMaxLifetime لتجديد الاتصالات بوتيرة أكثر تكرارًا

​كيفية تعيين الخيارات

​خيارات الاتصال

​البروتوكول والاتصال

​المصادقة

​المهلات الزمنية

​مجمع الاتصالات

​إعدادات مجمّع database/sql القياسية

​الضغط

​TLS

​تسجيل الأحداث

​المخازن المؤقتة والذاكرة

​خاص بـ HTTP

​الاتصال المتقدم

​معلومات العميل

​إعدادات خادم ClickHouse

​خيارات الاستعلام على مستوى Context

​خيارات Batch

​جداول للرجوع السريع

​توصيات تحديد حجم مجمع الاتصالات

​توصيات timeout

​مرجع سريع لمعلمات DSN

​استكشاف الأخطاء وإصلاحها

​استُنفِد مجمع الاتصالات: “acquire conn timeout”

​أخطاء مهلة القراءة وإعادة تعيين الاتصال

​”Code: 516. Authentication failed”

​أخطاء شهادة TLS

​الزيادة التدريجية في استهلاك الذاكرة

كيفية تعيين الخيارات

خيارات الاتصال

البروتوكول والاتصال

المصادقة

المهلات الزمنية

مجمع الاتصالات

إعدادات مجمّع `database/sql` القياسية

الضغط

TLS

تسجيل الأحداث

المخازن المؤقتة والذاكرة

خاص بـ HTTP

الاتصال المتقدم

معلومات العميل

إعدادات خادم ClickHouse

خيارات الاستعلام على مستوى Context

خيارات Batch

جداول للرجوع السريع

توصيات تحديد حجم مجمع الاتصالات

توصيات timeout

مرجع سريع لمعلمات DSN

استكشاف الأخطاء وإصلاحها

استُنفِد مجمع الاتصالات: “acquire conn timeout”

أخطاء مهلة القراءة وإعادة تعيين الاتصال

”Code: 516. Authentication failed”

أخطاء شهادة TLS

الزيادة التدريجية في استهلاك الذاكرة