sqlist

README

Built upon the excellent squirrel SQL builder.

Sqlist

Build dynamic SQL queries for list views with filters, sorting, and cursor-based pagination for Go.

Features

• 🔍 Dynamic filters — build WHERE clauses from HTTP query parameters
• 📊 Sorting — multiple sort fields with direction
• 📄 Pagination — offset/limit and cursor-based
• 🔗 Joins — support for all JOIN types
• 🎯 Field mapping — map request fields to database columns
• 🏗️ Based on squirrel — reliable and tested foundation

Installation

go get github.com/glevap/sqlist

Quick Start

package main

import (
    "github.com/glevap/sqlist"
)

func main() {
    builder := sqlist.NewSQLBuilder().
        WithFrom("users u").
        WithFields("u.id", "u.name", "u.email").
        WithFieldConfig("name", "u.name", sqlist.ILike)

    // Apply filters from request
    builder.ApplyFilter("name", "john")
    
    // Counting the number of lines for pagination
    rowsCount := builder.BuildCount()

    // Build query
    result := builder.BuildSelect()
    sql, args := result.SQL, result.Args
    
    // Use with database
    // db.Query(sql, args...)
}

License

MIT License - see LICENSE.

Documentation

Index

• Variables
• type BuildResult
• type FieldConfig
• type Op
• type SQLBuilder
  • func NewSQLBuilder() *SQLBuilder
  • func (b *SQLBuilder) ApplyFilter(field string, value string, args ...any) *SQLBuilder
  • func (b *SQLBuilder) ApplySort(field, order string) *SQLBuilder
  • func (b *SQLBuilder) BuildCount() (string, []any, error)
  • func (b *SQLBuilder) BuildSelect() (string, []any, error)
  • func (b *SQLBuilder) Limit(limit uint64) *SQLBuilder
  • func (b *SQLBuilder) Offset(offset uint64) *SQLBuilder
  • func (b *SQLBuilder) Page(page, pageSize uint64) *SQLBuilder
  • func (b *SQLBuilder) Sort(field, order string) *SQLBuilder
  • func (b *SQLBuilder) SortIf(field, order string) *SQLBuilder
  • func (b *SQLBuilder) Where(op Op, field string, value any, args ...any) *SQLBuilder
  • func (b *SQLBuilder) WithCTE(name string, alias string) *SQLBuilder
  • func (b *SQLBuilder) WithEstimate(table string) *SQLBuilder
  • func (b *SQLBuilder) WithField(field string) *SQLBuilder
  • func (b *SQLBuilder) WithFieldConfig(field string, dbField string, op Op) *SQLBuilder
  • func (b *SQLBuilder) WithFrom(table string) *SQLBuilder
  • func (b *SQLBuilder) WithFullJoin(table, condition string, args ...interface{}) *SQLBuilder
  • func (b *SQLBuilder) WithInnerJoin(table, condition string, args ...interface{}) *SQLBuilder
  • func (b *SQLBuilder) WithJoin(joinType, table, condition string, args ...interface{}) *SQLBuilder
  • func (b *SQLBuilder) WithLeftJoin(table, condition string, args ...interface{}) *SQLBuilder
  • func (b *SQLBuilder) WithPlaceholder(placeholder squirrel.PlaceholderFormat) *SQLBuilder
  • func (b *SQLBuilder) WithRightJoin(table, condition string, args ...interface{}) *SQLBuilder
  • func (b *SQLBuilder) WithSortFieldConfig(field string, sortField string) *SQLBuilder
• type SortConfig

Variables

var (
	// плейсхолдер, используемый в MySQL: ?
	Question = sq.Question

	// плейсхорлдер, используемый в PostgreSQL: $1, $2, $3
	Dollar = sq.Dollar

	// Позиционный плейсхолдер (:1, :2, :3).
	// Является промежуточным вариантом между $1 и ? и применяется для совместимости с некоторыми драйверами.
	Colon = sq.Colon

	// AtP is a PlaceholderFormat instance that replaces placeholders with
	// "@p"-prefixed positional placeholders (e.g. @p1, @p2, @p3).
	AtP = sq.AtP
)

Types

type BuildResult

type BuildResult struct {
	SQL  string
	Args []interface{}
	Err  error
}

BuildResult результат построения запроса

type FieldConfig

type FieldConfig struct {
	DBField   string // имя поля в БД
	Operator  Op     // "eq", "like", "ilike", "gt", "lt"
	SortField string // настройка имени поля для сортировки
}

FieldConfig описывает, как обрабатывать поле

type Op

type Op string

const (
	EQ       Op = "eq"      // =
	NOT_EQ   Op = "neq"     // !=
	LIKE     Op = "like"    // like
	ILIKE    Op = "ilike"   // ilike
	GT       Op = "gt"      // >
	LT       Op = "lt"      // <
	GTE      Op = "gte"     // >=
	LTE      Op = "lte"     // <=
	EXPR     Op = "expr"    // expression
	EXPR_EQ  Op = "expr_eq" // expression equal (specified)
	IN       Op = "in"
	NOT_IN   Op = "not_in"
	BETWEEN  Op = "between"
	IS_NULL  Op = "is_null"
	NOT_NULL Op = "not_null"

	// мне не нравится, но это нужно для избавления от IF проверок
	// при вызове ApplyFilter, т.к. в динамике мы никак иначе не
	// можем задавать местоположение плейсхолдера в паттерне поиска
	// ApplyFilter работает исключительно с настройками полей WithFieldConfig
	// либо задавать настройки паттерна LIKE/ILIKE в WithFieldConfig,
	// либо при вызове ApplyFilter проверять, есть ли поле, и руками
	// менять передаваемый аргумент значения поля
	LIKE_WITH_START  Op = "like_with_start"
	LIKE_WITH_END    Op = "like_with_end"
	LIKE_WITH_FULL   Op = "like_with_full"
	ILIKE_WITH_START Op = "ilike_with_start"
	ILIKE_WITH_END   Op = "ilike_with_end"
	ILIKE_WITH_FULL  Op = "ilike_with_full"
)

type SQLBuilder

type SQLBuilder struct {
	// contains filtered or unexported fields
}

SQLBuilder строитель SQL запросов

func NewSQLBuilder

func NewSQLBuilder() *SQLBuilder

NewSQLBuilder создает новый билдер с squirrel

func (*SQLBuilder) ApplyFilter

func (b *SQLBuilder) ApplyFilter(field string, value string, args ...any) *SQLBuilder

ApplyFilter применяет фильтр. Удобно использовать для установки фильтров в цикле

func (*SQLBuilder) ApplySort

func (b *SQLBuilder) ApplySort(field, order string) *SQLBuilder

func (*SQLBuilder) BuildCount

func (b *SQLBuilder) BuildCount() (string, []any, error)

func (*SQLBuilder) BuildSelect

func (b *SQLBuilder) BuildSelect() (string, []any, error)

BuildSelect строит запрос для выборки данных

func (*SQLBuilder) Limit

func (b *SQLBuilder) Limit(limit uint64) *SQLBuilder

Limit устанавливает лимит

func (*SQLBuilder) Offset

func (b *SQLBuilder) Offset(offset uint64) *SQLBuilder

Offset устанавливает смещение

func (*SQLBuilder) Page

func (b *SQLBuilder) Page(page, pageSize uint64) *SQLBuilder

Page устанавливает номер страницы

func (*SQLBuilder) Sort

func (b *SQLBuilder) Sort(field, order string) *SQLBuilder

Sort устанавливает сортировку

func (*SQLBuilder) SortIf

func (b *SQLBuilder) SortIf(field, order string) *SQLBuilder

SortIf устанавливает сортировку, если поле не пустое todo: а подразумевается, что должно быть condition, по которому будет применяться сортировочное правило!

func (*SQLBuilder) Where

func (b *SQLBuilder) Where(op Op, field string, value any, args ...any) *SQLBuilder

Where добавляет произвольное условие

func (*SQLBuilder) WithCTE

func (b *SQLBuilder) WithCTE(name string, alias string) *SQLBuilder

возвращает настроенный экземпляр CTE билдера

func (*SQLBuilder) WithEstimate

func (b *SQLBuilder) WithEstimate(table string) *SQLBuilder

WithEstimate устанавливает таблицу для приблизительного подсчета

func (*SQLBuilder) WithField

func (b *SQLBuilder) WithField(field string) *SQLBuilder

WithField добавляет единичное поле

func (*SQLBuilder) WithFieldConfig

func (b *SQLBuilder) WithFieldConfig(field string, dbField string, op Op) *SQLBuilder

настройки поля: исходное имя (из http-запроса), имя поля (с алиасом) в итоговом SQL и операнд, который будет применяться в WHERE-условии

func (*SQLBuilder) WithFrom

func (b *SQLBuilder) WithFrom(table string) *SQLBuilder

WithFrom устанавливает основную таблицу

func (*SQLBuilder) WithFullJoin

func (b *SQLBuilder) WithFullJoin(table, condition string, args ...interface{}) *SQLBuilder

WithFullJoin добавляет FULL JOIN

func (*SQLBuilder) WithInnerJoin

func (b *SQLBuilder) WithInnerJoin(table, condition string, args ...interface{}) *SQLBuilder

WithInnerJoin добавляет INNER JOIN

func (*SQLBuilder) WithJoin

func (b *SQLBuilder) WithJoin(joinType, table, condition string, args ...interface{}) *SQLBuilder

WithJoin добавляет произвольный JOIN

func (*SQLBuilder) WithLeftJoin

func (b *SQLBuilder) WithLeftJoin(table, condition string, args ...interface{}) *SQLBuilder

WithLeftJoin добавляет LEFT JOIN

func (*SQLBuilder) WithPlaceholder

func (b *SQLBuilder) WithPlaceholder(placeholder squirrel.PlaceholderFormat) *SQLBuilder

WithPlaceholder устанавливает формат плейсхолдеров

func (*SQLBuilder) WithRightJoin

func (b *SQLBuilder) WithRightJoin(table, condition string, args ...interface{}) *SQLBuilder

WithRightJoin добавляет RIGHT JOIN

func (*SQLBuilder) WithSortFieldConfig

func (b *SQLBuilder) WithSortFieldConfig(field string, sortField string) *SQLBuilder

type SortConfig

type SortConfig struct {
	Field string
	Order string
}

SortConfig сортировка