sqlcompose

package module
v0.0.29 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 4, 2026 License: AGPL-3.0 Imports: 6 Imported by: 0

README

go-compose-sql

Transform Go structs into simple SQL queries.

This project uses github.com/kisielk/sqlstruct to map struct fields to database columns when executing queries.

Future plans

  • Allow configure how the name to table translations (Take in account the posibilityfor define a interface with methods)
  • Define a ComposeFactory (engine?) like in sqlalchemy to pass the default options and build from the engine

Drivers

Statements are rendered by a Driver implementation. If no driver is provided, SQLiteDriver{} is used, which emits ? placeholders and appends a semicolon. For PostgreSQL, pass PostgresDriver{} in SqlOpts to generate $1-style placeholders and omit the trailing semicolon:

stmt := Select[User](&SqlOpts{Driver: PostgresDriver{}}).Where("id=?", 10)
sql, _ := stmt.Write()
// SELECT id, first_name FROM user WHERE id=$1

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Exec 

func Exec(db *sql.DB, stmt SQLStatement, models ...any) (sql.Result, error)

Exec executes the INSERT, UPDATE, or DELETE statement against the provided database using context.Background(). It delegates to ExecContext.

func ExecContext 

func ExecContext(ctx context.Context, db *sql.DB, stmt SQLStatement, models ...any) (sql.Result, error)

ExecContext executes the INSERT, UPDATE, or DELETE SQLStatement against the provided database using the supplied context. The models' exported fields are mapped to column names in the first clause and passed as arguments to the INSERT statement.

The first clause must be built using Insert[T] so that ModelType and ColumnNames match the fields in the model. ExecContext returns an error if the first clause is not an INSERT, UPDATE, or DELETE clause. It executes the statement once for each provided model and returns the result of the final execution. For DELETE statements, models are optional; if none are provided the statement is executed once using only the arguments supplied in the builder (e.g., WHERE clause).

If the statement contains a RETURNING clause, ExecContext returns an error because Exec cannot retrieve returned values. Use Query instead.

func NewErrInvalidClause added in v0.0.16 

func NewErrInvalidClause(clause string) error

NewErrInvalidClause constructs a new ErrInvalidClause for the given clause name.

func NewErrInvalidCoalesceArgs added in v0.0.19 

func NewErrInvalidCoalesceArgs(count int) error

NewErrInvalidCoalesceArgs constructs a new ErrInvalidCoalesceArgs with the provided argument count.

func NewErrMisplacedClause added in v0.0.16 

func NewErrMisplacedClause(clause string) error

NewErrMisplacedClause constructs a new ErrMisplacedClause for the given clause name.

func QueryOne added in v0.0.15 

func QueryOne[T any](db *sql.DB, stmt SQLStatement) (T, error)

QueryOne executes the SELECT SQLStatement against the provided database using context.Background(). It delegates to QueryOneContext.

func QueryOneContext added in v0.0.15 

func QueryOneContext[T any](ctx context.Context, db *sql.DB, stmt SQLStatement) (T, error)

QueryOneContext executes the SELECT SQLStatement against the provided database using the supplied context and returns exactly one row. If the query returns zero or more than one row, it returns an error.

Types

type ClauseType 

type ClauseType string

ClauseType represents a SQL operation like INSERT or UPDATE. 

const (
	ClauseInsert    ClauseType = "INSERT"
	ClauseSelect    ClauseType = "SELECT"
	ClauseUpdate    ClauseType = "UPDATE"
	ClauseDelete    ClauseType = "DELETE"
	ClauseWhere     ClauseType = "WHERE"
	ClauseJoin      ClauseType = "JOIN"
	ClauseOrderBy   ClauseType = "ORDER BY"
	ClauseLimit     ClauseType = "LIMIT"
	ClauseOffset    ClauseType = "OFFSET"
	ClauseCoalesce  ClauseType = "COALESCE"
	ClauseReturning ClauseType = "RETURNING"
	ClauseDesc      ClauseType = "DESC"
	ClauseAsc       ClauseType = "ASC"
	ClauseValues    ClauseType = "VALUES"
)

type Driver added in v0.0.22 

type Driver interface {
	Write(SqlClause, int) (string, int, error)
}

Driver renders SQL clauses into dialect-specific strings. Implementations should render placeholders starting at the provided argument position and return how many placeholders were consumed. 

var DefaultDriver Driver = SQLiteDriver{}

DefaultDriver is used when no driver is provided on a statement.

func DriverByName added in v0.0.22 

func DriverByName(name string) (Driver, error)

DriverByName returns a Driver instance matching the provided name. Recognized names: "postgres"/"postgresql" for PostgresDriver. Any other value (including empty) returns DefaultDriver.

type ErrInvalidClause added in v0.0.16 

type ErrInvalidClause struct {
	Clause string
}

ErrInvalidClause is returned when a clause of an unknown type is encountered.

func (*ErrInvalidClause) Error added in v0.0.16 

func (e *ErrInvalidClause) Error() string

type ErrInvalidCoalesceArgs added in v0.0.19 

type ErrInvalidCoalesceArgs struct {
	Count int
}

ErrInvalidCoalesceArgs is returned when COALESCE is called with insufficient arguments.

func (*ErrInvalidCoalesceArgs) Error added in v0.0.19 

func (e *ErrInvalidCoalesceArgs) Error() string

type ErrMisplacedClause added in v0.0.16 

type ErrMisplacedClause struct {
	Clause string
}

ErrMisplacedClause is returned when a clause is used in an invalid position.

func (*ErrMisplacedClause) Error added in v0.0.16 

func (e *ErrMisplacedClause) Error() string

type PostgresDriver added in v0.0.22 

type PostgresDriver struct{}

PostgresDriver renders SQL using dollar-prefixed placeholders.

func (PostgresDriver) Write added in v0.0.22 

func (PostgresDriver) Write(clause SqlClause, argPosition int) (string, int, error)

Write renders the clause using dollar-prefixed placeholders.

type QueryRowIterator added in v0.0.9 

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

QueryRowIterator allows for iterating over the results of a query one by one.

func Query 

func Query[T any](db *sql.DB, stmt SQLStatement) (*QueryRowIterator[T], error)

func QueryContext added in v0.0.5 

func QueryContext[T any](ctx context.Context, db *sql.DB, stmt SQLStatement) (*QueryRowIterator[T], error)

QueryContext executes the SELECT SQLStatement against the provided database and returns a QueryRowIterator so the caller can iterate over the results.

func (*QueryRowIterator[T]) Close added in v0.0.9 

func (iter *QueryRowIterator[T]) Close() error

Close closes the iterator, releasing any underlying resources.

func (*QueryRowIterator[T]) Err added in v0.0.10 

func (iter *QueryRowIterator[T]) Err() error

Check if error happen

func (*QueryRowIterator[T]) Next added in v0.0.9 

func (iter *QueryRowIterator[T]) Next() bool

Next prepares the next result row for reading.

func (*QueryRowIterator[T]) Scan added in v0.0.9 

func (iter *QueryRowIterator[T]) Scan(dest *T) error

Scan scans the current row into the given destination.

type SQLStatement added in v0.0.6 

type SQLStatement struct {
	Clauses []SqlClause
	Driver  Driver
}

SQLStatement represents a sequence of SQL clauses forming a statement.

func Delete 

func Delete[T any](opts *SqlOpts) SQLStatement

Delete builds a DELETE statement for type T.

The table name defaults to the struct type name converted to snake_case when opts.TableName is empty. The reflected type is stored in the resulting clause.

func Insert 

func Insert[T any](opts *SqlOpts) SQLStatement

Insert builds an INSERT statement for type T using the provided options.

Fields are mapped to column names using the `db` struct tag; if absent, the field name is converted to snake_case. The table name defaults to the struct type name converted to snake_case when opts.TableName is empty. The reflected type is stored in the resulting clause.

func Select 

func Select[T any](opts *SqlOpts) SQLStatement

Select builds a SELECT statement listing all exported fields of type T.

Column names and table name follow the same rules as Insert. The reflected type is stored in the resulting clause.

func Update added in v0.0.23 

func Update[T any](opts *SqlOpts) SQLStatement

Update builds an UPDATE statement for type T using the provided options.

Column names and table name follow the same rules as Insert. The reflected type is stored in the resulting clause.

func (SQLStatement) Args added in v0.0.6 

func (s SQLStatement) Args() []any

Args returns the collected arguments from all clauses in the statement.

func (SQLStatement) Asc added in v0.0.12 

func (s SQLStatement) Asc() SQLStatement

Asc appends an ASC clause ensuring it follows an ORDER BY clause.

func (SQLStatement) Coalesce added in v0.0.19 

func (s SQLStatement) Coalesce(values ...any) SQLStatement

Coalesce appends a COALESCE expression to the SELECT list.

func (SQLStatement) Desc added in v0.0.12 

func (s SQLStatement) Desc() SQLStatement

Desc appends a DESC clause ensuring it follows an ORDER BY clause.

func (SQLStatement) Join added in v0.0.24 

func (s SQLStatement) Join(stmt SQLStatement, identifier string, on string, args ...any) SQLStatement

Join appends a JOIN clause with a nested statement and identifier.

func (SQLStatement) Limit added in v0.0.12 

func (s SQLStatement) Limit(n int) SQLStatement

Limit appends a LIMIT clause to the statement.

func (SQLStatement) Offset added in v0.0.17 

func (s SQLStatement) Offset(n int) SQLStatement

Offset appends an OFFSET clause to the statement.

func (SQLStatement) OrderBy added in v0.0.12 

func (s SQLStatement) OrderBy(columns ...string) SQLStatement

OrderBy appends an ORDER BY clause to the statement.

func (SQLStatement) Returning added in v0.0.20 

func (s SQLStatement) Returning(columns ...string) SQLStatement

Returning appends a RETURNING clause to INSERT, UPDATE, or DELETE statements.

func (SQLStatement) Values added in v0.0.26 

func (s SQLStatement) Values(values ...any) SQLStatement

Values appends a VALUES clause to INSERT or UPDATE statements with explicit values. This allows specifying values directly instead of passing models to Exec.

If the first argument is a struct matching the statement's ModelType, its field values are automatically extracted in the same order as the clause's ColumnNames. Otherwise, all arguments are used as-is.

func (SQLStatement) Where added in v0.0.6 

func (s SQLStatement) Where(expr string, args ...any) SQLStatement

Where appends a WHERE clause to the statement.

func (SQLStatement) Write added in v0.0.6 

func (s SQLStatement) Write() (string, error)

Write renders the complete SQL statement by concatenating all clauses using the configured Driver (or DefaultDriver).

type SQLiteDriver added in v0.0.22 

type SQLiteDriver struct{}

SQLiteDriver renders SQL using question mark placeholders.

func (SQLiteDriver) Write added in v0.0.22 

func (SQLiteDriver) Write(clause SqlClause, argPosition int) (string, int, error)

Write renders the clause using positional question mark placeholders.

type SqlClause 

type SqlClause struct {
	Type          ClauseType
	TableName     string
	ColumnNames   []string
	Identifier    string
	JoinStatement SQLStatement
	ModelType     reflect.Type
	Expr          string
	Args          []any
}

SqlClause represents a SQL statement before rendering.

ModelType retains the generic type used when building the clause so that values can later be mapped to columns when executing the statement.

func (SqlClause) Write 

func (c SqlClause) Write() (string, error)

Write renders an individual SQL clause to a string.

type SqlOpts 

type SqlOpts struct {
	TableName string
	Fields    []string
	// Driver chooses the SQL dialect for rendering; defaults to DefaultDriver when nil.
	Driver Driver
}

SqlOpts contains optional settings for building SQL clauses.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.