quick_crud

README

Quick CRUD

Библиотека для упрощения CRUD-операций со структурами на Go с использованием дженериков.

English version

Возможности

• CRUD-операции: вставка, обновление, выборка по PK, удаление, выборка с фильтром
• Поддержка БД: PostgreSQL, SQLite (обе с поддержкой RETURNING)
• Система тегов: настройка поведения полей через struct tag tbl
• Фильтры: дерево условий с операторами (AND, OR, NOT, =, <>, >, >=, <, <=, LIKE, ILIKE, IN, IS NULL, IS NOT NULL)
• Пагинация: OFFSET / LIMIT
• Адаптеры: для pgx и database/sql
• Генератор кода: типизированные реализации таблиц без reflection

Установка

go get github.com/mirrorru/quick-crud

Быстрый старт

package main

import (
    "context"
    qc "github.com/mirrorru/quick-crud"
)

type UserRow struct {
    ID   int64  `tbl:"pk,auto"`
    Name string `tbl:"col=name"`
}

func main() {
    // Создание таблицы с диалектом PostgreSQL
    userTable := qc.NewTable[UserRow](qc.PostgresSQL)

    // Вставка
    user := &UserRow{Name: "Alice"}
    inserted, _, err := userTable.Ins(context.Background(), tx, user)

    // Выборка по первичному ключу
    found, err := userTable.One(context.Background(), tx, 1)

    // Обновление
    inserted.Name = "Bob"
    updated, _, err := userTable.Upd(context.Background(), tx, inserted)

    // Удаление
    _, err = userTable.Del(context.Background(), tx, 1)
}

Алиасы диалектов

В корневом пакете доступны пакетные переменные для удобного доступа к диалектам:

• qc.PostgresSQL — PostgreSQL диалект
• qc.SQLite — SQLite диалект

Теги struct полей (tbl:"...")

Тег	Описание
pk	Первичный ключ
ro	Read-only (только SELECT)
auto	Автогенерируемое поле
embed	Встраивание структуры
omit	Игнорирование поля
col=<name>	Имя колонки в БД
ins	Принудительная вставка
upd	Принудительное обновление
rskip	Пропуск при SELECT
prefix=<prefix>	Префикс для вложенных колонок
ref=<table>,<field>	Внешний ключ
sort=<pos>[:desc]	Сортировка

Структура пакетов

Пакет	Описание
dialect	SQL-диалекты (PostgreSQLDialect, SQLiteDialect)
filter	Система фильтрации
struct_info	Метаданные таблиц и полей
tx_adapter	Адаптеры для pgx и database/sql
defs	SQL-константы
helpers	Вспомогательные функции
cmd/qcgen	Генератор типизированных реализаций

Генератор кода (qcgen)

Генератор создаёт типизированные реализации таблиц без reflection:

go install ./cmd/qcgen
qcgen -src=path/to/models:*Row -dest=path/to/repo -pkg=repo

Сборка и тесты

# Стандартная проверка
go vet ./... && go build ./... && go test ./... && task lint

# Все тесты
task test

# Линтер
task lint

Лицензия

См. файл LICENSE.

Documentation

Index

• Variables
• type Query
  • func NewQuery[T any](d dialect.SQLDialect) *Query[T]
  • func NewQueryVal[T any](d dialect.SQLDialect) Query[T]
  • func (q *Query[T]) Internals() queryInternals
  • func (q *Query[T]) Many(ctx context.Context, tx TxProcessor, filter *filter.Filter) ([]*T, error)
  • func (q *Query[T]) One(ctx context.Context, tx TxProcessor, keys ...any) (*T, error)
• type Result
• type Row
• type Rows
• type Table
  • func NewTable[ROW any](d dialect.SQLDialect) *Table[ROW]
  • func NewTableVal[ROW any](d dialect.SQLDialect) Table[ROW]
  • func (t *Table[ROW]) Del(ctx context.Context, tx TxProcessor, keys ...any) (Result, error)
  • func (t *Table[ROW]) Ins(ctx context.Context, tx TxProcessor, row *ROW) (*ROW, Result, error)
  • func (t *Table[ROW]) Internals() tableInternals
  • func (t *Table[ROW]) Many(ctx context.Context, tx TxProcessor, filter *filter.Filter) (result []*ROW, err error)
  • func (t *Table[ROW]) One(ctx context.Context, tx TxProcessor, keys ...any) (*ROW, error)
  • func (t *Table[ROW]) Upd(ctx context.Context, tx TxProcessor, row *ROW) (*ROW, Result, error)
• type TxProcessor
• type TypedTable

Variables

var (
	// SQLite алиас для реализации диалекта SQLite
	SQLite dialect.SQLiteDialect

	// PostgresSQL алиас для реализации диалекта PostgresSQL
	PostgresSQL dialect.PostgreSQLDialect
)

Types

type Query

type Query[T any] struct {
	// contains filtered or unexported fields
}

Query мульти-табличный запрос для структур с полями-ROW. EN: Query multi-table query for structs with ROW fields.

func NewQuery

func NewQuery[T any](d dialect.SQLDialect) *Query[T]

NewQuery создает *Query[T]. EN: NewQuery creates *Query[T].

func NewQueryVal

func NewQueryVal[T any](d dialect.SQLDialect) Query[T]

NewQueryVal создает Query[T] по значению. EN: NewQueryVal creates Query[T] by value.

func (*Query[T]) Internals

func (q *Query[T]) Internals() queryInternals

Internals возвращает внутреннюю метадату Query. EN: Internals returns Query internal metadata.

func (*Query[T]) Many

func (q *Query[T]) Many(ctx context.Context, tx TxProcessor, filter *filter.Filter) ([]*T, error)

Many возвращает список записей с опциональным фильтром. EN: Many returns list of records with optional filter.

func (*Query[T]) One

func (q *Query[T]) One(ctx context.Context, tx TxProcessor, keys ...any) (*T, error)

One возвращает одну запись по PK. EN: One returns one record by PK.

type Result

type Result interface {
	LastInsertId() (int64, error)
	RowsAffected() (int64, error)
}

Result представляет результат выполнения ExecContext.

type Row

type Row interface {
	Scan(dest ...any) error
}

Row представляет одну строку результата запроса.

type Rows

type Rows interface {
	Next() bool
	Scan(dest ...any) error
	Close() error
	Err() error
}

Rows представляет курсор результатов запроса.

type Table

type Table[ROW any] struct {
	// contains filtered or unexported fields
}

func NewTable

func NewTable[ROW any](d dialect.SQLDialect) *Table[ROW]

func NewTableVal

func NewTableVal[ROW any](d dialect.SQLDialect) Table[ROW]

func (*Table[ROW]) Del

func (t *Table[ROW]) Del(ctx context.Context, tx TxProcessor, keys ...any) (Result, error)

func (*Table[ROW]) Ins

func (t *Table[ROW]) Ins(ctx context.Context, tx TxProcessor, row *ROW) (*ROW, Result, error)

func (*Table[ROW]) Internals

func (t *Table[ROW]) Internals() tableInternals

func (*Table[ROW]) Many

func (t *Table[ROW]) Many(ctx context.Context, tx TxProcessor, filter *filter.Filter) (result []*ROW, err error)

func (*Table[ROW]) One

func (t *Table[ROW]) One(ctx context.Context, tx TxProcessor, keys ...any) (*ROW, error)

func (*Table[ROW]) Upd

func (t *Table[ROW]) Upd(ctx context.Context, tx TxProcessor, row *ROW) (*ROW, Result, error)

type TxProcessor

type TxProcessor interface {
	ExecContext(ctx context.Context, query string, args ...any) (Result, error)
	QueryContext(ctx context.Context, query string, args ...any) (Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) Row
}

TxProcessor описывает интерфейс выполнения SQL-запросов.

type TypedTable

type TypedTable[ROW any] interface {
	Ins(ctx context.Context, tx TxProcessor, row *ROW) (*ROW, Result, error)
	Upd(ctx context.Context, tx TxProcessor, row *ROW) (*ROW, Result, error)
	One(ctx context.Context, tx TxProcessor, keys ...any) (*ROW, error)
	Del(ctx context.Context, tx TxProcessor, keys ...any) (Result, error)
	Many(ctx context.Context, tx TxProcessor, filter *filter.Filter) ([]*ROW, error)
}

TypedTable defines the interface for typed table implementations. Generated typed tables must implement this interface for compile-time verification.