API Reference
Functions

API Reference

Complete reference for all lit functions and types.

Registration

RegisterModel

Registers a model with the default naming strategy.

func RegisterModel[T any](driver Driver)

Parameters:

  • driver: Database driver (lit.PostgreSQL, lit.MySQL, lit.SQLite, lit.DuckDB, or a custom driver)

Example:

lit.RegisterModel[User](lit.PostgreSQL)

RegisterDriver

Sets the default database driver for model registration.

func RegisterDriver(driver Driver)

Parameters:

  • driver: Database driver (lit.PostgreSQL, lit.MySQL, lit.SQLite, lit.DuckDB, or a custom driver)

Example:

lit.RegisterDriver(lit.PostgreSQL)

RegisterModelWithNaming

Registers a model with a custom naming strategy.

func RegisterModelWithNaming[T any](driver Driver, namingStrategy DbNamingStrategy)

Parameters:

  • driver: Database driver
  • namingStrategy: Implementation of DbNamingStrategy

Example:

lit.RegisterModelWithNaming[User](lit.PostgreSQL, MyNamingStrategy{})

Query Functions

Select

Executes a query and returns all matching rows.

func Select[T any](ex Executor, query string, args ...any) ([]*T, error)

Parameters:

  • ex: Database connection or transaction
  • query: SQL SELECT query
  • args: Query parameters

Returns:

  • []*T: Slice of pointers to results
  • error: Any error that occurred

Example:

users, err := lit.Select[User](db, "SELECT id, name, email FROM users WHERE active = $1", true)

SelectSingle

Executes a query and returns a single row or nil.

func SelectSingle[T any](ex Executor, query string, args ...any) (*T, error)

Parameters:

  • ex: Database connection or transaction
  • query: SQL SELECT query
  • args: Query parameters

Returns:

  • *T: Pointer to result, or nil if not found
  • error: Any error that occurred

Example:

user, err := lit.SelectSingle[User](db, "SELECT id, name, email FROM users WHERE id = $1", 123)

SelectNamed

Parses :name placeholders and executes a SELECT returning all matching rows.

func SelectNamed[T any](ex Executor, query string, params map[string]any) ([]*T, error)

Parameters:

  • ex: Database connection or transaction
  • query: SQL SELECT query with :name placeholders
  • params: Map of parameter names to values

Returns:

  • []*T: Slice of pointers to results
  • error: Any error (including missing parameters)

Example:

users, err := lit.SelectNamed[User](db,
    "SELECT * FROM users WHERE last_name = :last_name",
    lit.P{"last_name": "Doe"})

SelectSingleNamed

Parses :name placeholders and executes a SELECT returning a single row or nil.

func SelectSingleNamed[T any](ex Executor, query string, params map[string]any) (*T, error)

Parameters:

  • ex: Database connection or transaction
  • query: SQL SELECT query with :name placeholders
  • params: Map of parameter names to values

Returns:

  • *T: Pointer to result, or nil if not found
  • error: Any error (including missing parameters)

Example:

user, err := lit.SelectSingleNamed[User](db,
    "SELECT * FROM users WHERE id = :id",
    lit.P{"id": 123})

SelectMultipleNative

Executes a query with manual row scanning.

func SelectMultipleNative[T any](
    ex Executor,
    mapLine func(*interface{ Scan(...any) error }, *T) error,
    query string,
    args ...any,
) ([]*T, error)

Parameters:

  • ex: Database connection or transaction
  • mapLine: Function to scan each row
  • query: SQL SELECT query
  • args: Query parameters

Example:

results, err := lit.SelectMultipleNative[Result](db,
    func(scanner *interface{ Scan(...any) error }, r *Result) error {
        return (*scanner).Scan(&r.Name, &r.Value)
    },
    "SELECT name, value FROM items")

Mutation Functions

Insert

Inserts a record and returns the generated ID.

func Insert[T any](ex Executor, t *T) (int, error)

Parameters:

  • ex: Database connection or transaction
  • t: Pointer to the struct to insert

Returns:

  • int: Generated ID
  • error: Any error that occurred

Example:

id, err := lit.Insert(db, &user)

InsertUuid

Inserts a record with an auto-generated UUID.

func InsertUuid[T any](ex Executor, t *T) (string, error)

Parameters:

  • ex: Database connection or transaction
  • t: Pointer to the struct to insert (Id field will be set)

Returns:

  • string: Generated UUID
  • error: Any error that occurred

Example:

uuid, err := lit.InsertUuid(db, &session)

InsertExistingUuid

Inserts a record with a pre-existing UUID.

func InsertExistingUuid[T any](ex Executor, t *T) error

Parameters:

  • ex: Database connection or transaction
  • t: Pointer to the struct to insert (Id must be set)

Returns:

  • error: Any error that occurred

Example:

err := lit.InsertExistingUuid(db, &session)

InsertNative

Executes a manual INSERT query.

func InsertNative(ex Executor, query string, args ...any) (int, error)

Parameters:

  • ex: Database connection or transaction
  • query: SQL INSERT query
  • args: Query parameters

Returns:

  • int: Last inserted ID
  • error: Any error that occurred

Update

Updates a record with a WHERE clause.

func Update[T any](ex Executor, t *T, where string, args ...any) error

Parameters:

  • ex: Database connection or transaction
  • t: Pointer to the struct with updated values
  • where: WHERE clause (required, cannot be empty)
  • args: WHERE clause parameters

Returns:

  • error: Any error that occurred

Example:

err := lit.Update(db, &user, "id = $1", user.Id)

UpdateNamed

Updates a record with a named-parameter WHERE clause.

func UpdateNamed[T any](ex Executor, t *T, where string, params map[string]any) error

Parameters:

  • ex: Database connection or transaction
  • t: Pointer to the struct with updated values
  • where: WHERE clause with :name placeholders (required)
  • params: Map of parameter names to values

Returns:

  • error: Any error (including missing parameters)

Example:

user.Email = "jane@example.com"
err := lit.UpdateNamed(db, &user, "id = :id", lit.P{"id": user.Id})

UpdateNative

Executes a manual UPDATE query.

func UpdateNative(ex Executor, query string, args ...any) error

Parameters:

  • ex: Database connection or transaction
  • query: SQL UPDATE query
  • args: Query parameters

Delete

Executes a DELETE query.

func Delete(ex Executor, query string, args ...any) error

Parameters:

  • ex: Database connection or transaction
  • query: SQL DELETE query
  • args: Query parameters

Example:

err := lit.Delete(db, "DELETE FROM users WHERE id = $1", 123)

DeleteNamed

Parses :name placeholders and executes a DELETE query.

func DeleteNamed(driver Driver, ex Executor, query string, params map[string]any) error

Parameters:

  • driver: Database driver (required because Delete is non-generic)
  • ex: Database connection or transaction
  • query: SQL DELETE query with :name placeholders
  • params: Map of parameter names to values

Returns:

  • error: Any error (including missing parameters)

Example:

err := lit.DeleteNamed(lit.PostgreSQL, db,
    "DELETE FROM users WHERE id = :id",
    lit.P{"id": 123})

Named Parameter Parsing

ParseNamedQuery

Low-level parser that converts :name placeholders to driver-specific positional syntax.

func ParseNamedQuery(driver Driver, query string, params map[string]any) (string, []any, error)

Parameters:

  • driver: Any Driver implementation (lit.PostgreSQL, lit.MySQL, lit.SQLite, lit.DuckDB, or a custom driver)
  • query: SQL query with :name placeholders
  • params: Map of parameter names to values

Returns:

  • string: Transformed query with positional placeholders
  • []any: Ordered argument slice
  • error: Any error (unsupported driver, missing parameter)

Example:

query, args, err := lit.ParseNamedQuery(lit.PostgreSQL,
    "SELECT * FROM users WHERE id = :id AND name = :name",
    lit.P{"id": 1, "name": "John"})
// query = "SELECT * FROM users WHERE id = $1 AND name = $2"
// args = [1, "John"]

ParseNamedQueryForModel

Like ParseNamedQuery but infers the driver from the model's registration.

func ParseNamedQueryForModel[T any](query string, params map[string]any) (string, []any, error)

Parameters:

  • query: SQL query with :name placeholders
  • params: Map of parameter names to values

Returns:

  • string: Transformed query with positional placeholders
  • []any: Ordered argument slice
  • error: Any error (unregistered model, missing parameter)

Example:

query, args, err := lit.ParseNamedQueryForModel[User](
    "SELECT * FROM users WHERE id = :id",
    lit.P{"id": 1})

Helper Functions

JoinForIn

Creates a comma-separated string of integers for IN clauses.

func JoinForIn(ids []int) string

Example:

ids := []int{1, 2, 3}
query := "SELECT * FROM users WHERE id IN (" + lit.JoinForIn(ids) + ")"
// Result: SELECT * FROM users WHERE id IN (1,2,3)

JoinStringForIn

Creates parameterized placeholders for IN clauses.

func JoinStringForIn[T any](offset int, params []string) string

Parameters:

  • offset: Starting parameter number (for PostgreSQL)
  • params: Slice of values (used to determine count)

Example:

emails := []string{"a@test.com", "b@test.com"}
placeholders := lit.JoinStringForIn[User](0, emails)
// PostgreSQL: $1,$2
// MySQL: ?,?

JoinStringForInWithDriver

Creates parameterized placeholders for a specific driver.

func JoinStringForInWithDriver(driver Driver, offset int, count int) string

Example:

placeholders := lit.JoinStringForInWithDriver(lit.PostgreSQL, 2, 3)
// Result: $3,$4,$5

Types

P

Shorthand type alias for named parameter maps.

type P = map[string]any

P is a true alias (using =), so it is fully interchangeable with map[string]any — no conversion needed.

Example:

// Instead of map[string]any{"id": 1}
users, err := lit.SelectNamed[User](db,
    "SELECT * FROM users WHERE id = :id",
    lit.P{"id": 1})

Driver

Interface that database drivers must implement. lit provides four built-in drivers: lit.PostgreSQL, lit.MySQL, lit.SQLite, and lit.DuckDB. You can also implement your own — see Custom Drivers.

type Driver interface {
    Name() string
    InsertUpdateQueryGenerator
    InsertAndGetId(ex Executor, query string, args ...any) (int, error)
    Placeholder(argIndex int) string
    SupportsBackslashEscape() bool
    RenumberWhereClause(where string, offset int) string
    JoinStringForIn(offset int, count int) string
}

The embedded InsertUpdateQueryGenerator interface adds two additional methods:

type InsertUpdateQueryGenerator interface {
    GenerateInsertQuery(tableName string, columnKeys []string, hasIntId bool) (string, []string)
    GenerateUpdateQuery(tableName string, columnKeys []string) string
}

Built-in drivers:

var PostgreSQL Driver = &pgDriver{}
var MySQL      Driver = &mysqlDriver{}
var SQLite     Driver = &sqliteDriver{}
var DuckDB     Driver = &duckdbDriver{}

Executor

Interface for database operations (implemented by *sql.DB and *sql.Tx).

type Executor interface {
    Exec(query string, args ...any) (sql.Result, error)
    Query(query string, args ...any) (*sql.Rows, error)
    QueryRow(query string, args ...any) *sql.Row
}

DbNamingStrategy

Interface for custom naming conventions.

type DbNamingStrategy interface {
    GetTableNameFromStructName(string) string
    GetColumnNameFromStructName(string) string
}

DefaultDbNamingStrategy

Built-in naming strategy (CamelCase → snake_case).

type DefaultDbNamingStrategy struct{}

FieldMap

Cached metadata for a registered model.

type FieldMap struct {
    ColumnsMap    map[string]int  // Column name → field index
    ColumnKeys    []string        // Ordered column names
    HasIntId      bool            // Whether id is an integer
    InsertQuery   string          // Pre-built INSERT query
    UpdateQuery   string          // Pre-built UPDATE query (without WHERE)
    InsertColumns []string        // Columns used in INSERT
    Driver        Driver          // Database driver
}
AI Agent SetupCRUD Repository