query

query — SQL query/clause builder

import "github.com/downsized-devs/sdk-go/query"

Stability: Stable. See STABILITY.md.

Dynamic SQL clause builder driven by struct tags. Builds WHERE, ORDER BY, LIMIT, and OFFSET from typed parameter structs.

Features

• Struct-tag-driven WHERE clause builder (matches db/param/field tags)
• Sort param normalisation (sort_by, sort-by, sortBy, sortby all accepted)
• Typed converters for int/int8/.../uint64, float, string, bool, time, plus their *Arr variants

Cursor pagination: the Cursor interface is present as a placeholder for a future implementation; the builder does not yet apply cursor filtering automatically. Callers that need keyset pagination today must append the cursor predicate manually via AddPrefixQuery (or equivalent) on the parameter struct before handing it to the builder.

Installation

go get github.com/downsized-devs/sdk-go/query

Quick Start

type ProductParam struct {
    Name     string `db:"name"     param:"name"     field:"Name"`
    IsActive bool   `db:"is_active" param:"is_active" field:"IsActive"`
    SortBy   string `param:"sort_by"`
    Page     int64  `param:"page"`
    Limit    int64  `param:"limit"`
}

// (Use the SQL builder via the package's exported helpers — see source for the
// current API shape; the builder is reflected into sql.Interface queries.)

Bulk insert

For bulk inserts, use the sql package's NamedExec with a slice of structs (sqlx expands the named placeholders automatically):

type Event struct {
    Name    string `db:"name"`
    Payload string `db:"payload"`
}
events := []Event{{"login", "{}"}, {"logout", "{}"}}
_, err := db.Leader().NamedExec(ctx, "insert-events",
    "INSERT INTO events (name, payload) VALUES (:name, :payload)", events)

API Reference

Error Handling

• Empty rows or columns → coded error from codes (CodeSQLPrepareStmt).

Dependencies

• Internal: codes, errors, null, sql
• External: github.com/jmoiron/sqlx

Testing

go test ./query/...

Test files cover the clause builder, converters, sort normalisation, and cursor encoding.

Contributing

See CONTRIBUTING.md.

Related Packages

• sql — provides the connection/transaction the builder ultimately runs against.
• null — nullable types in parameter structs.