الإعداد

إعداد عميل clickhouse-go: إعدادات الاتصال، وTLS، والمصادقة، وتجميع الاتصالات، والتسجيل، والضغط.

​

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

للاطلاع على شرح تفصيلي كامل لكل خيار، بما في ذلك القيم الافتراضية ومعلمات DSN وأفضل الممارسات واستكشاف الأخطاء وإصلاحها، راجع مرجع الإعدادات.

عند فتح اتصال، يمكن استخدام البنية 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")