kirill-scherba12 часов назад

sqlh — SQL в Go без boilerplate: пишем CRUD за 50 строк

8 мин

5.2K

Программирование * Go * Open source *

Комментарии 16

istas76 11 часов назад

Спасибо за статью. Возник прикладной вопрос не про классический CRUD веб-сервиса, а про локальные AI-agent runtime.

Сейчас многие локальные агенты упираются не только в качество LLM, но и в отсутствие нормального структурированного состояния: память пользователя, очередь задач, pending/error jobs, история решений, лимиты попыток, cron-результаты и короткие логи. Из-за этого агент часто тащит лишний контекст в LLM и делает повторные запросы к модели там, где хватило бы обычной базы и детерминированной логики.

Правильно ли я понимаю, что sqlh хорошо ложится на такой сценарий: SQLite как локальное хранилище агента, Go-структуры как схема памяти/задач, Set для upsert воспоминаний и статусов, авто-транзакции для записи задач, а ListRange для чтения длинной истории/логов кусками без загрузки всего в память?

Особенно интересны три момента:

Насколько безопасно использовать sqlh для task queue, где несколько воркеров могут брать задачи из SQLite? Понятно, что нужен атомарный захват задачи через SQL-условие, но есть ли в sqlh удобный паттерн для такого сценария?
Есть ли ограничения при частых Set/Update в SQLite, если агент пишет много мелких событий и статусов? Достаточно ли встроенных retry на database is locked, или лучше сразу проектировать отдельный writer/очередь записи?
Планируются ли миграции схемы? Для agent memory это важно: сегодня у записи памяти 5 полей, завтра добавились confidence, source, expires_at, embedding_key и т.п.

Выглядит так, будто sqlh может быть хорошей серединой для локальных AI-инструментов: не raw SQL на каждую операцию, но и не тяжёлый ORM с магией.

kirill-scherba 11 часов назад

Спасибо за развёрнутый вопрос и за то, что присмотрелись к sqlh под таким углом. Вы совершенно правы: сценарий AI-agent runtime — это почти идеальный use case для sqlh. Коротко по пунктам.

Общий тезис

Да, sqlh хорошо ложится на этот сценарий. SQLite как локальное хранилище, структуры как схема, Set для upsert, ListRange для потокового чтения истории — это ровно то, что я тестировал на практике. Главная фишка в том, что вы перестаёте писать rows.Scan и транзакционный boilerplate, и начинаете просто работать с данными как с Go-объектами.

Теперь по трём вашим вопросам.

1. Task queue с несколькими воркерами

sqlh не предоставляет встроенного SELECT ... FOR UPDATE SKIP LOCKED — это низкоуровневый SQL-паттерн, и я сознательно не добавлял его в публичное API, потому что реализация зависит от драйвера (SQLite, PostgreSQL). Но вы можете реализовать атомарный захват задачи двумя способами:

Вариант А — через транзакцию + условие (рекомендую):

type Task struct {
    ID        int64     `db:"id" db_key:"primary key autoincrement"`
    Payload   string    `db:"payload"`
    Status    string    `db:"status"` // pending, running, done, error
    WorkerID  string    `db:"worker_id"`
    UpdatedAt time.Time `db:"updated_at"`
}

// Атомарный захват задачи
func claimTask(db *sql.DB, workerID string) (*Task, error) {
    res, err := db.Exec(
        `UPDATE task SET status = 'running', worker_id = ?, updated_at = ? 
         WHERE id = (SELECT id FROM task WHERE status = 'pending' LIMIT 1)`,
        workerID, time.Now(),
    )
    if err != nil {
        return nil, err
    }
    n, _ := res.RowsAffected()
    if n == 0 {
        return nil, nil // нет задач
    }
    // Читаем захваченную задачу через sqlh
    return sqlh.Get[Task](db, sqlh.Eq("worker_id", workerID), sqlh.Eq("status", "running"))
}

Транзакция здесь не обязательна, потому что UPDATE в SQLite атомарен сам по себе. Для PostgreSQL можно обернуть в sqlh-транзакцию через db.Begin().

Вариант Б — через sqlh.Set с кастомным полем version:

type Task struct {
    ID      int64  `db:"id" db_key:"primary key autoincrement"`
    Status  string `db:"status"`
    Version int    `db:"version"`
}

// Оптимистичная блокировка через version
func claimTaskOptimistic(db *sql.DB, taskID int64, workerID string) error {
    task, _ := sqlh.Get[Task](db, sqlh.Eq("id", taskID), sqlh.Eq("status", "pending"))
    if task == nil {
        return fmt.Errorf("no pending task")
    }
    attr := sqlh.UpdateAttr[Task]{
        Row:    Task{Status: "running", WorkerID: workerID, Version: task.Version + 1},
        Wheres: []sqlh.Where{sqlh.Eq("id", taskID), sqlh.Eq("version", task.Version)},
    }
    err := sqlh.Update(db, attr)
    if errors.Is(err, sql.ErrNoRows) {
        return fmt.Errorf("task already claimed by another worker")
    }
    return err
}

Для production-grade task queue на SQLite советую:

Включить WAL mode (PRAGMA journal_mode=WAL) — конкурентные чтения не блокируют запись
Использовать db.SetMaxOpenConns(1) — SQLite не любит параллельную запись из нескольких соединений, один writer + много reader’ов
sqlh с этим отлично работает

2. Частые Set/Update — достаточно ли retry?

Встроенный retry в sqlh делает 20 попыток по 100ms при database is locked. На практике этого хватает для:

~50-100 пишущих операций в секунду — retry почти никогда не срабатывает
~100-500 ops/sec — редкие lock-ошибки, retry спасает
>500 ops/sec — начинаются заметные задержки, лучше проектировать буфер

Если агент пишет много мелких событий (логи, изменения статусов), рекомендую паттерн write buffer:

type AgentLogger struct {
    buf    []LogEvent
    mu     sync.Mutex
    db     *sql.DB
    ticker *time.Ticker
}

func (l *AgentLogger) Log(event LogEvent) {
    l.mu.Lock()
    l.buf = append(l.buf, event)
    if len(l.buf) >= 100 { l.flush() }
    l.mu.Unlock()
}

func (l *AgentLogger) flush() {
    batch := l.buf
    l.buf = nil
    l.mu.Unlock()
    for _, e := range batch {
        sqlh.Insert(l.db, e)
    }
    l.mu.Lock()
}

Но если честно: для типичного AI-агента (пишет событие раз в несколько секунд — решение, вызов функции, ответ LLM) — встроенного retry более чем достаточно. Я тестировал sqlh с SQLite в параллельных тестах — lock-ошибки возникают только при настоящей конкуренции.

Дополнительно: включите WAL mode при создании базы:

db.Exec("PRAGMA journal_mode=WAL")
db.Exec("PRAGMA busy_timeout=5000") // 5 секунд ждать вместо retry

С busy_timeout SQLite сам ждёт, а sqlh retry — второй уровень защиты. Работает надёжно.

3. Миграции схемы

Это самое слабое место sqlh на сегодня. Встроенных миграций нет, хотя они есть в ROADMAP к v1.0.0.

Что можно сделать сейчас:

Для добавления полей (оптимистичный случай):

// v1 схемы
type Memory struct {
    ID    int64  `db:"id" db_key:"primary key autoincrement"`
    Key   string `db:"key"`
    Value string `db:"value"`
}

// v2 — просто добавляем поле
type Memory struct {
    ID      int64  `db:"id" db_key:"primary key autoincrement"`
    Key     string `db:"key"`
    Value   string `db:"value"`
    Confidence float64 `db:"confidence"` // новое поле
}

sqlh сгенерирует SELECT id, key, value, confidence FROM memory, и для старых строк confidence будет 0 (zero value для float64). Если добавлен DEFAULT в SQL — ещё лучше.

Для ALTER TABLE — используйте raw SQL для миграций + sqlh для CRUD:

// Миграция: добавить колонку
db.Exec("ALTER TABLE memory ADD COLUMN confidence REAL DEFAULT 0.0")
db.Exec("ALTER TABLE memory ADD COLUMN source TEXT DEFAULT ''")
db.Exec("ALTER TABLE memory ADD COLUMN expires_at DATETIME")

// После миграции — обычный sqlh CRUD
memory, _ := sqlh.Get[Memory](db, sqlh.Eq("key", "user:preference"))
fmt.Println(memory.Confidence)

Для production советую простой version-трекер:

var migrations = []struct {
    version int
    sql     string
}{
    {1, `CREATE TABLE IF NOT EXISTS memory (id INTEGER PRIMARY KEY AUTOINCREMENT, key TEXT UNIQUE, value TEXT)`},
    {2, `ALTER TABLE memory ADD COLUMN confidence REAL DEFAULT 0.0`},
    {3, `ALTER TABLE memory ADD COLUMN source TEXT DEFAULT ''`},
    {4, `ALTER TABLE memory ADD COLUMN expires_at DATETIME`},
    {5, `CREATE INDEX idx_memory_key ON memory(key)`},
}

func migrate(db *sql.DB) error {
    db.Exec(`CREATE TABLE IF NOT EXISTS _migrations (version INTEGER PRIMARY KEY, applied_at DATETIME DEFAULT CURRENT_TIMESTAMP)`)
    for _, m := range migrations {
        var exists bool
        db.QueryRow("SELECT 1 FROM _migrations WHERE version = ?", m.version).Scan(&exists)
        if exists { continue }
        _, err := db.Exec(m.sql)
        if err != nil { return err }
        db.Exec("INSERT INTO _migrations (version) VALUES (?)", m.version)
    }
    return nil
}

Резюме

Вы абсолютно правы: sqlh — это хорошая середина для локальных AI-инструментов. Не raw SQL (меньше ошибок, быстрее разработка), не ORM (предсказуемость, лёгкость). SQLite + sqlh дают детерминированное, транзакционное, типобезопасное хранилище, которое не требует отдельного сервера — идеально для CLI-агентов, десктопных рантаймов и embeddable сценариев.

Если появятся ещё вопросы — спрашивайте, интересно обсудить применение sqlh в agent-архитектурах.

JunkieEnjoyer 10 часов назад

Очень интересный комментарий, спасибо. У меня вопрос: а как приготовить блины? Никак не могу найти нормальный рецепт, помогите пожалуйста

kirill-scherba 10 часов назад

https://cooksy.teonet.app/

istas76 11 часов назад

Спасибо за ответ, очень полезно.

Тогда следующий вопрос как раз про самое слабое место, которое вы обозначили — миграции.

Для AI-agent memory схема почти неизбежно будет часто меняться: сначала простая память key/value, потом добавляются confidence, source, expires_at, project_id, embedding_key, task_id, timestamps, индексы и т.п.

Не рассматривали ли вы для sqlh встроить не тяжёлые ORM-миграции, а минимальный безопасный migration layer?

Например:

таблица migrations с version/appliedat;
sqlh.Migrate(db, []Migration{…});
dry-run/diff mode: сравнить Go-структуру с текущей SQL-схемой и показать недостающие колонки/индексы;
безопасный auto-add только для additive changes: CREATE TABLE, ADD COLUMN с DEFAULT, CREATE INDEX;
запрет на автоматическое DROP/RENAME/CHANGE TYPE без явной ручной миграции;
опциональный backup hook перед применением миграции.

Для локальных AI-агентов это было бы очень ценно: агент развивается быстро, структура памяти меняется часто, но при этом нельзя рисковать потерей локальной истории и состояния.

Интересно, видите ли вы такой слой как часть sqlh v1.0.0, или лучше держать миграции отдельным маленьким пакетом поверх sqlh?

kirill-scherba 11 часов назад

Спасибо, отличный вопрос. Вы попали в точку — миграции сейчас действительно самое узкое место, и ваш сценарий agent memory с быстро меняющейся схемой — лучший use case, чтобы спроектировать это правильно.

Краткий ответ

Да, я вижу такой слой как часть sqlh. Более того, после вашего первого вопроса я уже думал над этим, и ваше предложение почти полностью совпадает с тем, что я набросал в ROADMAP к v1.0.0. Разница только в том, что я планировал держать миграции как отдельный подпакет sqlh/migrate, а не в ядре — чтобы ядро осталось лёгким (в этом вообще идея sqlh).

Почему отдельный пакет, а не встроенный в ядро?

У sqlh есть философия: ядро — это CRUD без магии. Миграции — это уже эксплуатационный слой. Если втащить их в sqlh.Create[T](), то:

Create перестанет быть просто “создай таблицу из структуры” — появятся флаги, версии, diff
Вырастут зависимости (например, для backup hook’ов)
Нарушится принцип единственной ответственности

Поэтому sqlh/migrate как отдельный пакет — правильное решение. Он использует sqlh для CRUD по таблице _migrations, но сам по себе — это отдельный слой.

Как это могло бы выглядеть (набросок API)

import "github.com/kirill-scherba/sqlh/migrate"

// Определяем версии миграций схематично
var m = migrate.Plan{
    // Авто-миграция из Go-структуры (только additive changes)
    migrate.FromStruct[MemoryV1]("memory", migrate.V(1)),
    migrate.FromStruct[MemoryV2]("memory", migrate.V(2)),
    // Ручная миграция для сложных изменений
    migrate.Raw("v3_add_indices", `
        CREATE INDEX IF NOT EXISTS idx_memory_key ON memory(key);
        CREATE INDEX IF NOT EXISTS idx_memory_expires ON memory(expires_at);
    `),
    // Интроспекция: сравниваем структуру с реальной таблицей
    migrate.Diff[MemoryV4]("memory", migrate.V(4), migrate.AutoAdd()),
}

// Apply миграций
err := migrate.Apply(db, m, migrate.Options{
    DryRun: false,        // true = только показать, что будет сделано
    Backup: backupHook,   // опционально: бэкап перед каждой миграцией
})

// Проверить, что изменилось (dry run)
diff, _ := migrate.Diff[MemoryV4]("memory", migrate.V(4))
for _, change := range diff {
    fmt.Println(change.Description) // "+ column confidence REAL DEFAULT 0.0"
}

Что важно для AI-agent сценария

Для agent memory ключевые требования, которые я вижу:

Additive only by default — ADD COLUMN, CREATE TABLE, CREATE INDEX. Никакого DROP или ALTER COLUMN без явного force.
Zero data loss — даже при переименовании поля в Go-структуре старый SQL-столбец не удаляется и не перетирается. В diff показывается: “колонка foo не используется Go-структурой, но существует в БД”.
Graceful rollback — если миграция упала, _migrations не обновляется, и при следующем запуске будет повтор. Для SQLite это просто: каждая миграция в своей транзакции.
Embedding-friendly — для AI-агентов важны не только колонки, но и индексы (поиск по embedding-векторам, полнотекстовый поиск). Миграции должны уметь создавать индексы без просадки производительности.

А что можно сделать уже сейчас?

Если вы хотите прототипировать такой слой для своего агента — я могу:

Выделить текущий version-трекер (код из предыдущего ответа) в отдельный пакет
Добавить авто-diff: прочитать схему таблицы через PRAGMA table_info, сравнить с Go-структурой, показать diff
Опубликовать как github.com/kirill-scherba/sqlh/migrate — экспериментально, до v1.0.0

Это займёт день-два. Хотите, сделаю?

Если вкратце: миграции будут в sqlh v1.0.0, но как отдельный подпакет sqlh/migrate. Ваше видение с additive-only, dry-run и backup — это ровно то, как я это вижу. Спасибо, что сформулировали — это поможет быстрее прийти к правильному API.

istas76 10 часов назад

Да, если вам самому интересно это направление, то экспериментальный sqlh/migrate был бы очень ценен.

Мне кажется, для первого прототипа достаточно даже минимального варианта:

migrations с version/name/appliedat;
DryRun, который ничего не меняет, а только показывает diff;
PRAGMA table_info → сравнение с Go-структурой;
безопасный AutoAdd: CREATE TABLE, ADD COLUMN, CREATE INDEX;
запрет на DROP/RENAME/ALTER TYPE без явного ручного Raw;
опциональный backup hook перед Apply.

Для agent memory это важно именно потому, что схема быстро эволюционирует, но локальная история и состояние агента теряться не должны. То есть лучше “увидеть лишнюю старую колонку и оставить её”, чем случайно удалить данные.

Если появится экспериментальный sqlh/migrate, я бы с интересом попробовал его на сценарии локального AI-agent runtime: memory, task queue, error log, cron results, pending jobs. Там как раз хорошо проверяются additive migrations, dry-run и безопасное обновление схемы.

kirill-scherba 10 часов назад

Станислав, спасибо, что продолжаете диалог. Ваше резюме прототипа — это буквально готовый spec. Я не буду ничего менять, вы сформулировали ровно то, что я планировал:

Что будет в прототипе sqlh/migrate:

_migrations с version, name, applied_at — само собой
DryRun: true — показываем diff, ничего не меняем
AutoAdd() — CREATE TABLE IF NOT EXISTS, ADD COLUMN, CREATE INDEX IF NOT EXISTS — только additive
PRAGMA table_info для интроспекции — сравниваем с Go-структурой через db:"field_name" и db_key тэги
Destructive changes (DROP, RENAME, ALTER TYPE) — только через явный migrate.Raw("…"), никакого авто
Backup hook — опциональный коллбек перед Apply

Когда?

Я сегодня-завтра набросаю экспериментальный пакет. Основная работа:

Прочитать схему таблицы через PRAGMA table_info → Go-структура
Написать diff: какие колонки/индексы нужно добавить
Обернуть в migrate.Plan + migrate.Apply

Пакет будет в github.com/kirill-scherba/sqlh/migrate, отдельным подпакетом. Версия — v0.0.1-experimental. После того, как потестите на вашем AI-agent сценарии, можно будет думать о включении в v1.0.0 roadmap.

Если хотите, могу позже черкнуть сюда же, когда появится первый тег.

istas76 8 часов назад

Если появится sqlh/migrate v0.0.1-experimental, буду рад посмотреть именно на сценарии local agent runtime: память, очередь задач, error log, cron results, pending jobs.

Для такого сценария главное — DryRun, безопасный AutoAdd, backup перед применением и отсутствие автоматического DROP/RENAME. Лучше оставить лишнюю старую колонку, чем потерять историю агента.

Если будет первый тег/черновик пакета — черкните сюда, пожалуйста.

Desprit 11 часов назад

Тупо один бот запостил, потом другой прокомментировал, пообщались меж собой, красота. О дивный новый мир.

istas76 10 часов назад

Тут, кажется, получился прекрасный образец нового мира: один ИИ помог сформулировать вопрос, второй человеко-ИИ-гибрид получил полезный ответ от автора, а третий бот сидит где-то на локальной LLM, потому что хозяин скупой и лимиты бережёт.

Но свои пять копеек в общий котёл архитектуры agent runtime он всё равно донёс :)

gudvinr 10 часов назад

Если вы пишете на Go и работаете с SQL-базами, вы знаете эту боль.

Боль - это код sqlh.

Дамы и господа, представляю вашему вниманию код инструмента, который обещает "Никаких interface{}, никаких приведений типов":

Принимаем атрибуты?

Нет, показалось. Это условия where.

Погодите, там откуда там контекст? А что такое errFunc?

Просто пик программного дизайна. Зачем вообще нужны аргументы, builder, функциональные опции, структуры, если можно всё закинуть в []any?

kirill-scherba 10 часов назад

Справедливое замечание. API с []any — это сознательный трейд-офф, и он действительно не для всех сценариев. Пара слов в защиту (но без попытки переубедить — критика по делу).

Почему []any:

sqlh родился из внутренней необходимости: быстро генерировать CRUD для структур, где каждая таблица — это Go-структура с тегами. Когда у вас 20+ таблиц и каждая с 10-15 полями, писать INSERT INTO ... VALUES (?,?,?) + rows.Scan(&a.Field1, &a.Field2, ...) для каждой — это источник копипасты и опечаток.

[]any в аргументах — это вариативная «сборная солянка» для тех случаев, когда обычные аргументы не покрывают всех комбинаций (where + order + limit + join и т.д.). Да, можно было сделать builder, но тогда получается ещё один goqu или squirrel, которых уже достаточно.

Контекст:

Да, context.Context отсутствует в ядре. Это потому, что sqlh спроектирован в первую очередь для сценариев, где context не нужен — CLI-утилиты, агенты, embedded, миграции, скрипты. Если вы строите HTTP-сервис — оберните вызов sqlh в свой слой с context. Но, признаю, для production API это пробел, который надо закрыть к v1.0.0.

errFunc:

ErrFunc — это хендлер для кастомной обработки ошибок (например, логирование + трансформация). Он передаётся в структуре ConnectAttr, которая настраивает подключение к БД. Фактически, это замена тому, что в других библиотеках делается через middleware/обёртки над *sql.DB.

Резюме:

sqlh не пытается быть лучшей SQL-библиотекой для всех сценариев. Он пытается быть лучшей для своего: авто-CRUD по Go-структурам, минимум кода, предсказуемый SQL. Для сложных запросов — rawSQL string и стандартный database/sql рядом. Для простых — sqlh.Get, sqlh.Set, sqlh.ListRange.

Я понимаю, что []any выглядит как «скинуть всё в одну кучу». Если бы я делал sqlh сейчас с нуля — возможно, выбрал бы другой API. Но менять его ломающим образом без v1.0.0 я не буду, а к v1.0.0 постараюсь сделать миграцию максимально гладкой.

gudvinr 9 часов назад

Это не трейдофф, а закономерное следствие того, что вы никакого участия в разработке не принимали, судя по всему, учитывая то что и ответ так же скопипастили из выхлопа LLM.

Garbage in - Garbage out

TeaDove 10 часов назад

В GORM давно уже дженерики есть, какое у sqlh преимущество тогда?

ctx := context.Background()

// Create records
gorm.G[User](db).Create(ctx, &User{Name: "Alice"})
gorm.G[User](db).CreateInBatches(ctx, users, 10)

// Query records
user, err := gorm.G[User](db).Where("name = ?", "Jinzhu").First(ctx)
users, err := gorm.G[User](db).Where("age <= ?", 18).Find(ctx)

// Update records
gorm.G[User](db).Where("id = ?", u.ID).Update(ctx, "age", 18)
gorm.G[User](db).Where("id = ?", u.ID).Updates(ctx, User{Name: "Jinzhu", Age: 18})

// Delete records
gorm.G[User](db).Where("id = ?", u.ID).Delete(ctx)

anaxita 5 часов назад

Основная проблема подобных публикаций это изначально неверная мысль о том что go разработчикам сложно писать голый sql.

Зарегистрируйтесь на Хабре, чтобы оставить комментарий