sqlc مع Go: توليد كود type-safe من SQL

sqlc هو مترجم يقوم بتوليد كود Go بناءً على استعلامات SQL الخاصة بك. بدلاً من كتابة دوال للتعامل مع قاعدة البيانات يدويًا، تكتب SQL نقيًا، ويقوم sqlc بإنشاء دوال مُنَمّطة وآمنة وفعالة لك. هذا نهج مختلف جوهريًا عن ORM: تحتفظ بالتحكم الكامل في SQL، لكنك تتخلص من كتابة الكود التكراري (boilerplate).

لماذا تحتاج هذا؟ أولاً، يضمن sqlc سلامة الأنواع (type-safety) على مستوى الترجمة. إذا قمت بتغيير هيكل الجدول أو الاستعلام، سيعيد sqlc توليد الكود، وسيشير مترجم Go فورًا إلى جميع الأماكن التي تحتاج إلى تعديل. ثانيًا، الأداء: الكود المُولَّد لا يستخدم الانعكاس (reflection) ولا يقوم بعمليات تخصيص غير ضرورية، مما يجعله بنفس سرعة كتابة الاستعلامات يدويًا عبر database/sql. ثالثًا، يبسط مراجعة الكود: استعلامات SQL تكون واضحة في ملفات .sql، وليست مخفية داخل دوال ORM.

sqlc مثالي للمشاريع التي تهم فيها الأداء والتحكم بالاستعلامات: واجهات برمجة التطبيقات عالية التحميل، الأنظمة المالية، منصات التحليل. كما يتناسب بشكل ممتاز مع الترحيلات (مثل golang-migrate) ولا يربطك بنظام إدارة قواعد بيانات محدد – فهو يدعم PostgreSQL وMySQL وSQLite.

التثبيت

sqlc ليس مكتبة، بل أداة سطر أوامر. يمكن تثبيتها بعدة طرق:

# عبر go install (موصى به)
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest

# عبر Homebrew (macOS/Linux)
brew install sqlc

# تحميل الملف التنفيذي من GitHub
# https://github.com/sqlc-dev/sqlc/releases

بعد التثبيت، تحقق من الإصدار:

sqlc version

البداية السريعة

لننشئ مشروعًا صغيرًا يوضح عمل sqlc.

1. هيكل المشروع

mkdir sqlc-demo && cd sqlc-demo
go mod init sqlc-demo

2. إعدادات sqlc

أنشئ ملف sqlc.yaml في جذر المشروع:

version: "2"
sql:
  - engine: "postgresql"
    queries: "queries.sql"
    schema: "schema.sql"
    gen:
      go:
        package: "db"
        out: "db"
        sql_package: "pgx/v5"

3. هيكل قاعدة البيانات

ملف schema.sql:

CREATE TABLE authors (
    id   BIGSERIAL PRIMARY KEY,
    name text NOT NULL,
    bio  text
);

4. استعلامات SQL

ملف queries.sql:

-- name: GetAuthor :one
SELECT * FROM authors
WHERE id = $1;

-- name: ListAuthors :many
SELECT * FROM authors
ORDER BY name;

-- name: CreateAuthor :one
INSERT INTO authors (name, bio)
VALUES ($1, $2)
RETURNING *;

-- name: DeleteAuthor :exec
DELETE FROM authors
WHERE id = $1;

5. توليد الكود

sqlc generate

بعد التنفيذ، ستظهر الملفات المُولَّدة في مجلد db/. يمكنك الآن استخدامها في الكود:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/jackc/pgx/v5/pgxpool"
    "sqlc-demo/db"
)

func main() {
    ctx := context.Background()
    pool, err := pgxpool.New(ctx, "postgres://user:pass@localhost:5432/testdb")
    if err != nil {
        log.Fatal(err)
    }
    defer pool.Close()

    queries := db.New(pool)

    // إنشاء مؤلف
    author, err := queries.CreateAuthor(ctx, db.CreateAuthorParams{
        Name: "Brian Kernighan",
        Bio:  "Co-author of The C Programming Language",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("تم إنشاء المؤلف: %+v\n", author)

    // الحصول على المؤلف بواسطة المعرف
    fetched, err := queries.GetAuthor(ctx, author.ID)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("تم جلب المؤلف: %+v\n", fetched)
}