> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
> تتيح لك مكتبات عميل Go الخاصة بـ ClickHouse الاتصال بـ ClickHouse باستخدام واجهة Go القياسية database/sql أو الواجهة الأصلية المحسّنة.
# ClickHouse Go
## البدء السريع
لنبدأ بمثال بسيط. سيؤدي هذا إلى الاتصال بـ ClickHouse وتنفيذ استعلام على قاعدة بيانات النظام. للبدء، ستحتاج إلى تفاصيل الاتصال الخاصة بك.
### تفاصيل الاتصال
للاتصال بـ ClickHouse باستخدام native TCP، ستحتاج إلى المعلومات التالية:
| المعلمات | الوصف |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| `HOST` and `PORT` | يكون المنفذ عادةً 9440 عند استخدام TLS، أو 9000 عند عدم استخدام TLS. |
| `DATABASE NAME` | توجد افتراضيًا قاعدة بيانات باسم `default`؛ استخدم اسم قاعدة البيانات التي تريد الاتصال بها. |
| `USERNAME` and `PASSWORD` | يكون اسم المستخدم افتراضيًا هو `default`. استخدم اسم المستخدم المناسب لحالة الاستخدام الخاصة بك. |
تتوفر تفاصيل خدمة ClickHouse Cloud الخاصة بك في ClickHouse Cloud console.
حدّد الخدمة التي ستتصل بها، ثم انقر على **Connect**:
اختر **Native**، وستتوفر التفاصيل ضمن مثال لأمر `clickhouse-client`.
إذا كنت تستخدم ClickHouse مُدارًا ذاتيًا، فسيحدّد مسؤول ClickHouse لديك تفاصيل الاتصال.
### تهيئة وحدة
```bash theme={null}
mkdir clickhouse-golang-example
cd clickhouse-golang-example
go mod init clickhouse-golang-example
```
### انسخ بعض الشيفرة النموذجية
انسخ هذه الشيفرة إلى الدليل `clickhouse-golang-example` واحفظها باسم `main.go`.
```go title=main.go theme={null}
package main
import (
"context"
"crypto/tls"
"fmt"
"log"
"github.com/ClickHouse/clickhouse-go/v2"
"github.com/ClickHouse/clickhouse-go/v2/lib/driver"
)
func main() {
conn, err := connect()
if err != nil {
panic(err)
}
ctx := context.Background()
rows, err := conn.Query(ctx, "SELECT name, toString(uuid) as uuid_str FROM system.tables LIMIT 5")
if err != nil {
log.Fatal(err)
}
defer rows.Close()
for rows.Next() {
var name, uuid string
if err := rows.Scan(&name, &uuid); err != nil {
log.Fatal(err)
}
log.Printf("name: %s, uuid: %s", name, uuid)
}
// NOTE: Do not skip rows.Err() check
if err := rows.Err(); err != nil {
log.Fatal(err)
}
}
func connect() (driver.Conn, error) {
var (
ctx = context.Background()
conn, err = clickhouse.Open(&clickhouse.Options{
Addr: []string{":9440"},
Auth: clickhouse.Auth{
Database: "default",
Username: "default",
Password: "",
},
ClientInfo: clickhouse.ClientInfo{
Products: []struct {
Name string
Version string
}{
{Name: "an-example-go-client", Version: "0.1"},
},
},
Debugf: func(format string, v ...interface{}) {
fmt.Printf(format, v)
},
TLS: &tls.Config{
InsecureSkipVerify: true,
},
})
)
if err != nil {
return nil, err
}
if err := conn.Ping(ctx); err != nil {
if exception, ok := err.(*clickhouse.Exception); ok {
fmt.Printf("Exception [%d] %s \n%s\n", exception.Code, exception.Message, exception.StackTrace)
}
return nil, err
}
return conn, nil
}
```
### نفّذ go mod tidy
```bash theme={null}
go mod tidy
```
### عيّن تفاصيل الاتصال الخاصة بك
سبق أن اطّلعت على تفاصيل الاتصال الخاصة بك. عيّنها في `main.go` داخل الدالة `connect()`:
```go highlight={5,7-9} theme={null}
func connect() (driver.Conn, error) {
var (
ctx = context.Background()
conn, err = clickhouse.Open(&clickhouse.Options{
Addr: []string{":9440"},
Auth: clickhouse.Auth{
Database: "default",
Username: "default",
Password: "",
},
```
### نفّذ المثال
```bash theme={null}
go run .
```
```response theme={null}
2023/03/06 14:18:33 name: COLUMNS, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: SCHEMATA, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: TABLES, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: VIEWS, uuid: 00000000-0000-0000-0000-000000000000
2023/03/06 14:18:33 name: hourly_data, uuid: a4e36bd4-1e82-45b3-be77-74a0fe65c52b
```
### تعرّف على المزيد
تغطي بقية الوثائق في هذه الفئة تفاصيل عميل Go الخاص بـ ClickHouse.
## نظرة عامة
يدعم ClickHouse مكتبتَي عملاء رسميتين للغة Go. وهاتان المكتبتان متكاملتان ومصممتان عمدًا لدعم حالات استخدام مختلفة.
* [clickhouse-go](https://github.com/ClickHouse/clickhouse-go) - مكتبة عملاء عالية المستوى للغات البرمجة تدعم إما واجهة `database/sql` القياسية في Go أو واجهة برمجة تطبيقات ClickHouse الأصلية.
* [ch-go](https://github.com/ClickHouse/ch-go) - عميل منخفض المستوى. يدعم الواجهة الأصلية فقط.
يوفّر clickhouse-go واجهة عالية المستوى تتيح للمستخدمين تنفيذ الاستعلامات وإدراج البيانات باستخدام دلالات موجّهة للصفوف، مع التجميع على دفعات بمرونة فيما يتعلق بأنواع البيانات — إذ تُحوَّل القيم ما دام ذلك لا يترتب عليه احتمال فقدانٍ في الدقة. أمّا ch-go فيوفّر واجهة محسّنة موجّهة للأعمدة تتيح تدفّقًا سريعًا لكتل البيانات مع حمل منخفض على CPU والذاكرة، وذلك على حساب الصرامة في الأنواع وزيادة تعقيد الاستخدام.
اعتبارًا من الإصدار 2.3، يستخدم clickhouse-go مكتبة ch-go للوظائف منخفضة المستوى مثل الترميز وفك الترميز والضغط. ويستخدم كلا العميلين التنسيق الأصلي في الترميز لتوفير أفضل أداء ممكن، كما يمكنهما الاتصال عبر بروتوكول ClickHouse الأصلي. ويدعم clickhouse-go أيضًا HTTP كآلية نقل في الحالات التي يحتاج فيها المستخدمون إلى استخدام proxy أو موازنة الحمل لحركة المرور.
### أربع طرق للاتصال
يمنحك `clickhouse-go` خيارين مستقلين: **أي واجهة برمجة تطبيقات** تستخدم و**أي وسيلة نقل** تستخدم. ويؤدي الجمع بينهما إلى أربعة أوضاع اتصال:
| | **TCP** (البروتوكول الأصلي، المنفذ 9000/9440) | **HTTP** (المنفذ 8123/8443) |
| :------------------------------------------------------------- | :-------------------------------------------: | :------------------------------: |
| **واجهة برمجة تطبيقات ClickHouse** (`clickhouse.Open`) | الافتراضي — أفضل أداء | عيّن `Protocol: clickhouse.HTTP` |
| **واجهة برمجة تطبيقات `database/sql`** (`OpenDB` / `sql.Open`) | `clickhouse://host:9000` | `http://host:8123` |
**اختيار واجهة برمجة تطبيقات:** اختر واجهة برمجة تطبيقات ClickHouse للحصول على أعلى أداء ومجموعة الميزات الكاملة (استدعاءات التقدم، وعمليات insert العمودية، ودعم غني للأنواع). واختر `database/sql` عندما تحتاج إلى التكامل مع ORMs أو مع أدوات تتوقع واجهة قاعدة بيانات قياسية لـ Go.
**اختيار وسيلة النقل:** TCP أسرع وهو الخيار الافتراضي. انتقل إلى HTTP عندما تتطلب البنية التحتية لديك ذلك — على سبيل المثال، عند الاتصال عبر موازن تحميل أو proxy خاص بـ HTTP، أو عندما تحتاج إلى ميزات خاصة بـ HTTP مثل الجلسات مع الجداول المؤقتة، أو خوارزميات ضغط إضافية (`gzip`, `deflate`, `br`).
تستخدم كلتا واجهتي برمجة التطبيقات الترميز الثنائي الأصلي بغض النظر عن وسيلة النقل، لذلك لا يضيف HTTP أي عبء serialization.
| | التنسيق الأصلي | النقل عبر TCP | النقل عبر HTTP | كتابة مجمّعة | تنظيم `struct` | الضغط | استدعاءات التقدم |
| :--------------------------------: | :------------: | :-----------: | :------------: | :----------: | :------------: | :---: | :--------------: |
| واجهة برمجة تطبيقات ClickHouse | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| واجهة برمجة تطبيقات `database/sql` | ✅ | ✅ | ✅ | ✅ | | ✅ | |
### اختيار عميل
يعتمد اختيار مكتبة العميل على أنماط استخدامك وحاجتك إلى أفضل أداء ممكن. في حالات الاستخدام كثيفة `insert`، حيث يلزم تنفيذ ملايين عمليات الإدراج في الثانية، نوصي باستخدام العميل منخفض المستوى [ch-go](https://github.com/ClickHouse/ch-go). يتجنب هذا العميل الكلفة الإضافية المرتبطة بتحويل البيانات من تنسيق موجّه للصفوف إلى تنسيق موجّه للأعمدة، كما يتطلب التنسيق الأصلي لـ ClickHouse. بالإضافة إلى ذلك، فهو يتجنب أي استبطان (reflection) أو استخدام النوع `interface{}` (`any`) لتبسيط الاستخدام.
أما بالنسبة إلى أعباء عمل الاستعلام التي تركز على التجميعات، أو أعباء عمل الإدراج ذات معدل النقل الأقل، فإن [clickhouse-go](https://github.com/ClickHouse/clickhouse-go) يوفّر واجهة `database/sql` مألوفة ودلالات صفوف أبسط. ويمكنك أيضًا، عند الحاجة، استخدام HTTP كبروتوكول نقل والاستفادة من الدوال المساعدة لتحويل الصفوف من البُنى (`structs`) وإليها.
| | التنسيق الأصلي | البروتوكول الأصلي | بروتوكول HTTP | واجهة برمجة تطبيقات موجّهة للصفوف | واجهة برمجة تطبيقات موجّهة للأعمدة | مرونة الأنواع | الضغط | العناصر النائبة في الاستعلام |
| :-----------: | :------------: | :---------------: | :-----------: | :-------------------------------: | :--------------------------------: | :-----------: | :---: | :--------------------------: |
| clickhouse-go | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ch-go | ✅ | ✅ | | | ✅ | | ✅ | |
## التثبيت
تم إهمال الإصدار v1 من برنامج التشغيل، ولن يتلقى تحديثات للميزات أو دعمًا لأنواع ClickHouse الجديدة. ينبغي لك الترحيل إلى v2، إذ يوفّر أداءً أفضل.
لتثبيت الإصدار 2.x من العميل، أضف الحزمة إلى ملف go.mod:
`require github.com/ClickHouse/clickhouse-go/v2 main`
أو استنسخ المستودع:
```bash theme={null}
git clone --branch v2 https://github.com/clickhouse/clickhouse-go.git $GOPATH/src/github
```
لتثبيت إصدار آخر، عدّل المسار أو اسم الفرع بما يتناسب مع ذلك.
```bash theme={null}
mkdir my-clickhouse-app && cd my-clickhouse-app
cat > go.mod <<-END
module my-clickhouse-app
go 1.21
require github.com/ClickHouse/clickhouse-go/v2 main
END
cat > main.go <<-END
package main
import (
"fmt"
"github.com/ClickHouse/clickhouse-go/v2"
)
func main() {
conn, _ := clickhouse.Open(&clickhouse.Options{Addr: []string{"127.0.0.1:9000"}})
v, _ := conn.ServerVersion()
fmt.Println(v.String())
}
END
go mod tidy
go run main.go
```
### الإصدارات
يُطرح العميل بإصدارات مستقلة عن ClickHouse. ويمثّل 2.x الإصدار الرئيسي الحالي قيد التطوير. ويجب أن تكون جميع إصدارات 2.x متوافقةً مع بعضها البعض.
#### توافق ClickHouse
يدعم العميل ما يلي:
* جميع إصدارات ClickHouse المدعومة حاليًا كما هو موضح [هنا](https://github.com/ClickHouse/ClickHouse/blob/master/SECURITY.md). وعندما تتوقف إصدارات ClickHouse عن تلقي الدعم، تتوقف أيضًا اختبارات توافقها النشطة مع إصدارات العميل.
* جميع إصدارات ClickHouse ضمن فترة سنتين من تاريخ إصدار العميل. لاحظ أن إصدارات LTS فقط هي التي تخضع لاختبارات نشطة.
#### التوافق مع Golang
| إصدار العميل | إصدارات Golang |
| :-------------: | :------------: |
| => 2.0 \<= 2.2 | 1.17, 1.18 |
| >= 2.3, \< 2.41 | 1.18+ |
| >= 2.41 | 1.21+ |
| >= 2.43 | 1.24+ |
## أفضل الممارسات
* استخدم واجهة برمجة تطبيقات ClickHouse حيثما أمكن، خاصةً مع الأنواع البدائية. فهذا يجنبك قدرًا كبيرًا من الاستبطان وعدم المباشرة.
* إذا كنت تقرأ مجموعات بيانات كبيرة، ففكّر في تعديل [`BlockBufferSize`](/ar/integrations/language-clients/go/configuration#connection-settings). سيزيد ذلك من استهلاك الذاكرة، لكنه يتيح فك ترميز المزيد من الكتل بالتوازي أثناء التكرار على الصفوف. القيمة الافتراضية 2 متحفظة وتقلل من الحمل الإضافي على الذاكرة. وتعني القيم الأعلى وجود المزيد من الكتل في الذاكرة. ويتطلب هذا الاختبار، لأن الاستعلامات المختلفة قد تنتج أحجام كتل مختلفة. لذلك يمكن ضبطه على [مستوى الاستعلام](/ar/integrations/language-clients/go/clickhouse-api#using-context) عبر Context.
* كن دقيقًا في تحديد الأنواع عند إدراج البيانات. فمع أن العميل مصمم ليكون مرنًا، مثل السماح بتحليل السلاسل النصية إلى UUIDs أو عناوين IP، فإن ذلك يتطلب التحقق من صحة البيانات ويترتب عليه تكلفة وقت الإدراج.
* استخدم عمليات الإدراج الموجّهة بالأعمدة حيثما أمكن. ومرة أخرى، ينبغي أن تكون محددة الأنواع بوضوح لتجنب حاجة العميل إلى تحويل قيمك.
* اتبع توصيات ClickHouse [المتعلقة بالأداء](/ar/reference/statements/insert-into#performance-considerations) لتحقيق أفضل أداء عند الإدراج.
## الخطوات التالية
* [الإعداد](/ar/integrations/language-clients/go/configuration) — إعدادات الاتصال وTLS والمصادقة وتسجيل الأحداث والضغط
* [واجهة برمجة تطبيقات ClickHouse](/ar/integrations/language-clients/go/clickhouse-api) — واجهة برمجة تطبيقات Go الأصلية للاستعلامات والإدراج
* [واجهة برمجة تطبيقات Database/SQL](/ar/integrations/language-clients/go/database-sql-api) — واجهة `database/sql` القياسية
* [أنواع البيانات](/ar/integrations/language-clients/go/data-types) — تعيينات أنواع Go ودعم الأنواع المعقدة