الإعداد | ClickHouse Docs

إعدادات الاتصال

عند فتح اتصال، يمكن استخدام البنية Options للتحكم في سلوك العميل. الإعدادات التالية متاحة:

Parameter	Type	Default	Description
`Protocol`	`Protocol`	`Native`	بروتوكول النقل: `Native` ‏(TCP) أو `HTTP`. راجع TCP مقابل HTTP.
`Addr`	`[]string`	—	قائمة بعناوين `host:port`. للاتصال بعدة عُقد، راجع الاتصال بعدة عقد.
`Auth`	`Auth`	—	بيانات اعتماد المصادقة (`Database` و`Username` و`Password`). راجع المصادقة.
`TLS`	`*tls.Config`	`nil`	إعداد TLS. تؤدي القيمة غير `nil` إلى تفعيل TLS. راجع TLS.
`DialContext`	`func(ctx, addr) (net.Conn, error)`	—	دالة اتصال مخصصة للتحكم في كيفية إنشاء اتصالات TCP.
`DialTimeout`	`time.Duration`	`30s`	الحد الأقصى للوقت الذي يجب انتظاره عند فتح اتصال جديد. ارفعه إلى `1m`–`2m` عند الاتصال بخدمة ClickHouse Cloud قد تكون خاملة — راجع المهل.
`MaxOpenConns`	`int`	`MaxIdleConns + 5`	الحد الأقصى لعدد الاتصالات المفتوحة في أي وقت.
`MaxIdleConns`	`int`	`5`	عدد الاتصالات الخاملة التي يجب الاحتفاظ بها في pool الاتصالات.
`ConnMaxLifetime`	`time.Duration`	`1h`	الحد الأقصى لعمر الاتصال ضمن pool الاتصالات. راجع تجميع الاتصالات.
`ConnOpenStrategy`	`ConnOpenStrategy`	`ConnOpenInOrder`	الاستراتيجية المستخدمة لاختيار عقدة من `Addr`. راجع الاتصال بعدة عقد.
`BlockBufferSize`	`uint8`	`2`	عدد الكتل التي تُفك شيفرتها بالتوازي. تؤدي القيم الأعلى إلى زيادة معدل النقل على حساب الذاكرة. ويمكن تجاوزها لكل استعلام عبر السياق.
`Settings`	`Settings`	—	خريطة بإعدادات ClickHouse تُطبَّق على كل استعلام. ويمكن لكل استعلام على حدة تجاوزها عبر السياق.
`Compression`	`*Compression`	`nil`	ضغط على مستوى الكتلة. راجع الضغط.
`ReadTimeout`	`time.Duration`	—	الحد الأقصى للوقت الذي يجب انتظاره لعملية قراءة من الخادم في استدعاء واحد.
`FreeBufOnConnRelease`	`bool`	`false`	إذا كانت القيمة `true`، فسيُعاد المخزن المؤقت للذاكرة الخاص بالاتصال إلى الـ pool مع كل استعلام. يقلل ذلك من استهلاك الذاكرة مقابل تكلفة طفيفة على المعالج.
`Logger`	`*slog.Logger`	`nil`	مسجل منظَّم (Go `log/slog`). راجع التسجيل.
`Debug`	`bool`	`false`	مهمل. استخدم `Logger` بدلاً منه. يفعّل مخرجات debug القديمة إلى stdout.
`Debugf`	`func(string, ...any)`	—	مهمل. استخدم `Logger` بدلاً منه. دالة سجل debug مخصصة. تتطلب `Debug: true`.
`GetJWT`	`GetJWTFunc`	—	دالة callback تُرجع رمز JWT لمصادقة ClickHouse Cloud (HTTPS فقط).
`HttpHeaders`	`map[string]string`	—	رؤوس HTTP إضافية تُرسل مع كل طلب (لنقل HTTP فقط).
`HttpUrlPath`	`string`	—	مسار URL إضافي يُلحَق بطلبات HTTP (لنقل HTTP فقط).
`HttpMaxConnsPerHost`	`int`	—	يتجاوز `MaxConnsPerHost` في `http.Transport` الأساسي (لنقل HTTP فقط).
`TransportFunc`	`func(*http.Transport) (http.RoundTripper, error)`	—	دالة مصنع مخصصة لنقل HTTP. يُمرَّر النقل الافتراضي لإجراء تجاوزات انتقائية (لنقل HTTP فقط).
`HTTPProxyURL`	`*url.URL`	—	عنوان URL لوكيل HTTP لجميع الطلبات (لنقل HTTP فقط).

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    DialContext: func(ctx context.Context, addr string) (net.Conn, error) {
        dialCount++
        var d net.Dialer
        return d.DialContext(ctx, "tcp", addr)
    },
    Debug: true,
    Debugf: func(format string, v ...interface{}) {
        fmt.Printf(format, v)
    },
    Settings: clickhouse.Settings{
        "max_execution_time": 60,
    },
    Compression: &clickhouse.Compression{
        Method: clickhouse.CompressionLZ4,
    },
    DialTimeout:      time.Duration(10) * time.Second,
    MaxOpenConns:     5,
    MaxIdleConns:     5,
    ConnMaxLifetime:  time.Duration(10) * time.Minute,
    ConnOpenStrategy: clickhouse.ConnOpenInOrder,
    BlockBufferSize: 10,
})
if err != nil {
    return err
}

مثال متكامل

TLS

على المستوى الأدنى، ستستخدم جميع طرائق اتصال العميل (DSN/OpenDB/Open) حزمة Go tls لإنشاء اتصال آمن. ويعرف العميل أنه يجب استخدام TLS إذا كانت بنية Options تحتوي على مؤشّر tls.Config غير nil.

env, err := GetNativeTestEnvironment()
if err != nil {
    return err
}
cwd, err := os.Getwd()
if err != nil {
    return err
}
t := &tls.Config{}
caCert, err := ioutil.ReadFile(path.Join(cwd, "../../tests/resources/CAroot.crt"))
if err != nil {
    return err
}
caCertPool := x509.NewCertPool()
successful := caCertPool.AppendCertsFromPEM(caCert)
if !successful {
    return err
}
t.RootCAs = caCertPool
conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.SslPort)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    TLS: t,
})
if err != nil {
    return err
}
v, err := conn.ServerVersion()
if err != nil {
    return err
}
fmt.Println(v.String())

مثال كامل

عادةً ما يكون الحد الأدنى من إعداد TLS.Config كافيًا للاتصال بالمنفذ الأصلي الآمن (عادةً 9440) على خادم ClickHouse. إذا لم تكن لدى خادم ClickHouse شهادة صالحة (منتهية الصلاحية، أو باسم مضيف غير صحيح، أو غير موقَّعة من قِبل سلطة شهادات جذرية معترف بها علنًا)، فيمكن ضبط InsecureSkipVerify على true، لكن لا يُنصح بذلك بشدة.

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.SslPort)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    TLS: &tls.Config{
        InsecureSkipVerify: true,
    },
})
if err != nil {
    return err
}
v, err := conn.ServerVersion()

المثال الكامل

إذا كانت هناك حاجة إلى معلمات TLS إضافية، فينبغي أن تضبط شيفرة التطبيق الحقول المطلوبة في بنية tls.Config. وقد يشمل ذلك تحديد حِزم تشفير معيّنة، أو فرض إصدار محدد من TLS (مثل 1.2 أو 1.3)، أو إضافة سلسلة شهادات CA داخلية، أو إضافة شهادة عميل (والمفتاح الخاص بها) إذا كان خادم ClickHouse يتطلب ذلك، بالإضافة إلى معظم الخيارات الأخرى المرتبطة بإعدادات أمان أكثر تخصصًا.

المصادقة

حدِّد بنية Auth ضمن تفاصيل الاتصال لتعيين اسم المستخدم وكلمة المرور.

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
})
if err != nil {
    return err
}

v, err := conn.ServerVersion()

المثال الكامل

الاتصال بعدة عُقد

يمكن تحديد عدة عناوين عبر البنية Addr.

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{"127.0.0.1:9001", "127.0.0.1:9002", fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
})
if err != nil {
    return err
}
v, err := conn.ServerVersion()
if err != nil {
    return err
}
fmt.Println(v.String())

مثال كامل

تتوفر ثلاث استراتيجيات للاتصال:

ConnOpenInOrder (الافتراضي) - تُجرَّب العناوين بالترتيب. ولا تُستخدم العناوين اللاحقة إلا إذا تعذّر الاتصال باستخدام العناوين السابقة في القائمة. وهذه فعليًا استراتيجية تجاوز عند الفشل.
ConnOpenRoundRobin - يُوزَّع الحمل على العناوين باستخدام استراتيجية round-robin.
ConnOpenRandom - تُختار عقدة عشوائيًا من قائمة العناوين.

يمكن التحكم في ذلك من خلال الخيار ConnOpenStrategy

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr:             []string{"127.0.0.1:9001", "127.0.0.1:9002", fmt.Sprintf("%s:%d", env.Host, env.Port)},
    ConnOpenStrategy: clickhouse.ConnOpenRoundRobin,
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
})
if err != nil {
    return err
}
v, err := conn.ServerVersion()
if err != nil {
    return err
}

مثال كامل

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

يحافظ العميل على مجموعة من الاتصالات ويعيد استخدامها عبر الاستعلامات عند الحاجة. ولن يُستخدم في أي وقت أكثر من MaxOpenConns، بينما يتحكم MaxIdleConns في الحد الأقصى لحجم المجموعة. يحصل العميل على اتصال من المجموعة عند تنفيذ كل استعلام، ثم يعيده إليها لإعادة استخدامه. ويظل الاتصال مستخدمًا طوال مدة الـ Batch، ثم يُحرَّر عند Send().

لا يوجد ما يضمن استخدام الاتصال نفسه من المجموعة في الاستعلامات اللاحقة ما لم يضبط المستخدم MaxOpenConns=1. ونادرًا ما تكون هناك حاجة إلى ذلك، لكنه قد يكون مطلوبًا في الحالات التي يستخدم فيها المستخدمون الجداول المؤقتة.

لاحظ أيضًا أن القيمة الافتراضية لـ ConnMaxLifetime هي ساعة واحدة. وقد يؤدي ذلك إلى حالات يصبح فيها الحمل على ClickHouse غير متوازن إذا غادرت بعض العقد الـ cluster. ويمكن أن يحدث هذا عندما تصبح إحدى العقد غير متاحة، فتتوزع الاتصالات على العقد الأخرى. وستظل هذه الاتصالات قائمة ولن تُجدَّد لمدة ساعة واحدة افتراضيًا، حتى إذا عادت العقدة التي كانت بها المشكلة إلى الـ cluster. فكّر في خفض هذه القيمة في حالات أعباء العمل الكبيرة.

استقصاء الاتصالات مفعّل لكلٍّ من Native (TCP) وبروتوكول HTTP.

التسجيل

يدعم العميل التسجيل المُهيكل عبر الحزمة القياسية log/slog في Go باستخدام الحقل Logger ضمن Options. أما الحقلان الأقدمان Debug وDebugf فهما مهملان، لكنهما لا يزالان يعملان حفاظًا على التوافق مع الإصدارات السابقة (الأولوية: Debugf > Logger > عدم تنفيذ أي إجراء).

import (

    "log/slog"
    "os"
)

// JSON structured logging
logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelDebug,
}))

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    Logger: logger,
})

يمكنك أيضًا إثراء الـ logger بسياق على مستوى التطبيق:

baseLogger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelInfo,
}))
enrichedLogger := baseLogger.With(
    slog.String("service", "my-service"),
    slog.String("environment", "production"),
)

conn, err := clickhouse.Open(&clickhouse.Options{
    // ...
    Logger: enrichedLogger,
})

المثال الكامل

الضغط

يعتمد دعم طرق الضغط على البروتوكول الأساسي المستخدم. بالنسبة إلى البروتوكول الأصلي، يدعم العميل الضغط باستخدام LZ4 وZSTD. ويُنفَّذ ذلك على مستوى الكتلة فقط. يمكن تمكين الضغط عبر تضمين إعداد Compression ضمن الاتصال.

conn, err := clickhouse.Open(&clickhouse.Options{
    Addr: []string{fmt.Sprintf("%s:%d", env.Host, env.Port)},
    Auth: clickhouse.Auth{
        Database: env.Database,
        Username: env.Username,
        Password: env.Password,
    },
    Compression: &clickhouse.Compression{
        Method: clickhouse.CompressionZSTD,
    },
    MaxOpenConns: 1,
})
ctx := context.Background()
defer func() {
    conn.Exec(ctx, "DROP TABLE example")
}()
conn.Exec(context.Background(), "DROP TABLE IF EXISTS example")
if err = conn.Exec(ctx, `
    CREATE TABLE example (
            Col1 Array(String)
    ) Engine Memory
    `); err != nil {
    return err
}
batch, err := conn.PrepareBatch(ctx, "INSERT INTO example")
if err != nil {
    return err
}
defer batch.Close()

for i := 0; i < 1000; i++ {
    if err := batch.Append([]string{strconv.Itoa(i), strconv.Itoa(i + 1), strconv.Itoa(i + 2), strconv.Itoa(i + 3)}); err != nil {
        return err
    }
}
if err := batch.Send(); err != nil {
    return err
}

المثال الكامل

تتوفر أيضًا تقنيات ضغط إضافية عند استخدام النقل عبر HTTP: ‏gzip وdeflate وbr. راجع قاعدة البيانات/واجهة برمجة تطبيقات SQL - الضغط لمزيد من التفاصيل.

TCP مقابل HTTP

بروتوكول النقل ليس سوى خيار واحد في الإعدادات — وكل ما عدا ذلك في هذا الدليل ينطبق على كليهما. إليك ما يتغيّر:

	TCP (البروتوكول الأصلي)	HTTP
المنفذ الافتراضي	9000 (عادي)، 9440 (TLS)	8123 (عادي)، 8443 (TLS)
التفعيل	افتراضي — اترك `Protocol` غير مذكور	`Protocol: clickhouse.HTTP` أو استخدم `http://` DSN
الضغط	`lz4`, `zstd`	`lz4`, `zstd`, `gzip`, `deflate`, `br`
الجلسات	مدمجة (نشطة دائمًا)	صريحة — مرّر `session_id` كإعداد
رؤوس HTTP	—	`HttpHeaders`, `HttpUrlPath`, `HttpMaxConnsPerHost`
آلية نقل مخصّصة	—	`TransportFunc`
مصادقة JWT	—	`GetJWT` (ClickHouse Cloud HTTPS)
OpenTelemetry (`WithSpan`)	✅	الخادم يدعمها؛ لكن العميل لا يرسل بعدُ رأس `traceparent`

لتحويل أيٍّ من واجهتَي برمجة التطبيقات إلى HTTP:

// ClickHouse API over HTTP
conn, err := clickhouse.Open(&clickhouse.Options{
    Addr:     []string{"host:8123"},
    Protocol: clickhouse.HTTP,
    // ... auth, etc.
})

// database/sql over HTTP — via Options
conn := clickhouse.OpenDB(&clickhouse.Options{
    Addr:     []string{"host:8123"},
    Protocol: clickhouse.HTTP,
    // ... auth, etc.
})

// database/sql over HTTP — via DSN
conn, err := sql.Open("clickhouse", "http://host:8123?username=user&password=pass")