API Reference

Complete API reference for the github.com/zoobz-io/edamame package.

Executor

The main execution context for a model type.

New

func New[T any](db *sqlx.DB, tableName string, renderer astql.Renderer) (*Executor[T], error)

Creates a new executor for type T bound to the given table with the specified SQL renderer. The db parameter can be nil for testing statement rendering without database access.

Supported renderers via astql:

github.com/zoobz-io/astql/pkg/postgres - PostgreSQL
github.com/zoobz-io/astql/pkg/mariadb - MariaDB
github.com/zoobz-io/astql/pkg/sqlite - SQLite
github.com/zoobz-io/astql/pkg/mssql - SQL Server

import "github.com/zoobz-io/astql/pkg/postgres" // or mariadb, sqlite, mssql

exec, err := edamame.New[User](db, "users", postgres.New())

Statement Constructors

NewQueryStatement

func NewQueryStatement(name, description string, spec QuerySpec, tags ...string) QueryStatement

Creates a typed query statement for multi-record retrieval. Parameters are automatically derived from the spec.

NewSelectStatement

func NewSelectStatement(name, description string, spec SelectSpec, tags ...string) SelectStatement

Creates a typed select statement for single-record retrieval.

NewUpdateStatement

func NewUpdateStatement(name, description string, spec UpdateSpec, tags ...string) UpdateStatement

Creates a typed update statement for modifications.

NewDeleteStatement

func NewDeleteStatement(name, description string, spec DeleteSpec, tags ...string) DeleteStatement

Creates a typed delete statement for deletions.

NewAggregateStatement

func NewAggregateStatement(name, description string, fn AggregateFunc, spec AggregateSpec, tags ...string) AggregateStatement

Creates a typed aggregate statement for COUNT, SUM, AVG, MIN, MAX operations.

Statement Types

All statement types share common methods:

func (s Statement) ID() uuid.UUID      // Unique identifier
func (s Statement) Name() string       // Human-readable name
func (s Statement) Description() string // What the statement does
func (s Statement) Params() []ParamSpec // Required parameters
func (s Statement) Tags() []string     // Optional categorization tags

QueryStatement

For multi-record retrieval operations.

SelectStatement

For single-record retrieval operations.

UpdateStatement

For modification operations.

DeleteStatement

For deletion operations.

AggregateStatement

For aggregate operations (COUNT, SUM, AVG, MIN, MAX).

Executor Methods

Builder Access

Query

func (e *Executor[T]) Query(stmt QueryStatement) (*soy.Query[T], error)

Returns a soy Query builder for the statement.

Select

func (e *Executor[T]) Select(stmt SelectStatement) (*soy.Select[T], error)

Returns a soy Select builder for the statement.

Update

func (e *Executor[T]) Update(stmt UpdateStatement) (*soy.Update[T], error)

Returns a soy Update builder for the statement.

Delete

func (e *Executor[T]) Delete(stmt DeleteStatement) (*soy.Delete[T], error)

Returns a soy Delete builder for the statement.

Aggregate

func (e *Executor[T]) Aggregate(stmt AggregateStatement) *soy.Aggregate[T]

Returns a soy Aggregate builder for the statement.

Insert

func (e *Executor[T]) Insert() *soy.Create[T]

Returns a soy Create builder for inserts.

Compound

func (e *Executor[T]) Compound(spec CompoundQuerySpec) (*soy.Compound[T], error)

Returns a soy Compound builder for set operations (UNION, INTERSECT, EXCEPT).

Execution Methods

ExecQuery / ExecQueryTx

func (e *Executor[T]) ExecQuery(ctx context.Context, stmt QueryStatement, params map[string]any) ([]*T, error)
func (e *Executor[T]) ExecQueryTx(ctx context.Context, tx *sqlx.Tx, stmt QueryStatement, params map[string]any) ([]*T, error)

Executes a query statement, returning multiple records.

ExecSelect / ExecSelectTx

func (e *Executor[T]) ExecSelect(ctx context.Context, stmt SelectStatement, params map[string]any) (*T, error)
func (e *Executor[T]) ExecSelectTx(ctx context.Context, tx *sqlx.Tx, stmt SelectStatement, params map[string]any) (*T, error)

Executes a select statement, returning a single record.

ExecUpdate / ExecUpdateTx

func (e *Executor[T]) ExecUpdate(ctx context.Context, stmt UpdateStatement, params map[string]any) (*T, error)
func (e *Executor[T]) ExecUpdateTx(ctx context.Context, tx *sqlx.Tx, stmt UpdateStatement, params map[string]any) (*T, error)

Executes an update statement, returning the updated record.

ExecDelete / ExecDeleteTx

func (e *Executor[T]) ExecDelete(ctx context.Context, stmt DeleteStatement, params map[string]any) (int64, error)
func (e *Executor[T]) ExecDeleteTx(ctx context.Context, tx *sqlx.Tx, stmt DeleteStatement, params map[string]any) (int64, error)

Executes a delete statement, returning the count of deleted rows.

ExecAggregate / ExecAggregateTx

func (e *Executor[T]) ExecAggregate(ctx context.Context, stmt AggregateStatement, params map[string]any) (float64, error)
func (e *Executor[T]) ExecAggregateTx(ctx context.Context, tx *sqlx.Tx, stmt AggregateStatement, params map[string]any) (float64, error)

Executes an aggregate statement, returning the result.

ExecInsert / ExecInsertTx

func (e *Executor[T]) ExecInsert(ctx context.Context, record *T) (*T, error)
func (e *Executor[T]) ExecInsertTx(ctx context.Context, tx *sqlx.Tx, record *T) (*T, error)

Inserts a record, returning it with generated fields populated.

ExecCompound / ExecCompoundTx

func (e *Executor[T]) ExecCompound(ctx context.Context, spec CompoundQuerySpec, params map[string]any) ([]*T, error)
func (e *Executor[T]) ExecCompoundTx(ctx context.Context, tx *sqlx.Tx, spec CompoundQuerySpec, params map[string]any) ([]*T, error)

Executes a compound query (UNION, INTERSECT, EXCEPT), returning multiple records.

Batch Execution

ExecInsertBatch / ExecInsertBatchTx

func (e *Executor[T]) ExecInsertBatch(ctx context.Context, records []*T) (int64, error)
func (e *Executor[T]) ExecInsertBatchTx(ctx context.Context, tx *sqlx.Tx, records []*T) (int64, error)

Inserts multiple records, returning the count.

ExecUpdateBatch / ExecUpdateBatchTx

func (e *Executor[T]) ExecUpdateBatch(ctx context.Context, stmt UpdateStatement, batchParams []map[string]any) (int64, error)
func (e *Executor[T]) ExecUpdateBatchTx(ctx context.Context, tx *sqlx.Tx, stmt UpdateStatement, batchParams []map[string]any) (int64, error)

Executes an update statement with multiple parameter sets.

ExecDeleteBatch / ExecDeleteBatchTx

func (e *Executor[T]) ExecDeleteBatch(ctx context.Context, stmt DeleteStatement, batchParams []map[string]any) (int64, error)
func (e *Executor[T]) ExecDeleteBatchTx(ctx context.Context, tx *sqlx.Tx, stmt DeleteStatement, batchParams []map[string]any) (int64, error)

Executes a delete statement with multiple parameter sets.

Type-Erased Execution (Atom)

These methods return results as atom.Atom types, enabling type-erased execution where the concrete type T is not known at consumption time. Useful for dynamic query handling and LLM-driven database operations.

ExecQueryAtom

func (e *Executor[T]) ExecQueryAtom(ctx context.Context, stmt QueryStatement, params map[string]any) ([]*atom.Atom, error)

Executes a query statement and returns results as Atoms.

ExecSelectAtom

func (e *Executor[T]) ExecSelectAtom(ctx context.Context, stmt SelectStatement, params map[string]any) (*atom.Atom, error)

Executes a select statement and returns the result as an Atom.

ExecInsertAtom

func (e *Executor[T]) ExecInsertAtom(ctx context.Context, params map[string]any) (*atom.Atom, error)

Executes an insert using parameter map and returns the result as an Atom.

Rendering

RenderCompound

func (e *Executor[T]) RenderCompound(spec CompoundQuerySpec) (string, error)

Renders a compound query to SQL for inspection or debugging.

Other

Soy

func (e *Executor[T]) Soy() *soy.Soy[T]

Returns the underlying soy instance for direct builder access.

TableName

func (e *Executor[T]) TableName() string

Returns the table name.

Spec Types

QuerySpec

type QuerySpec struct {
    Fields      []string
    SelectExprs []SelectExprSpec  // Expression-based SELECT (functions, aggregates)
    Where       []ConditionSpec
    OrderBy     []OrderBySpec
    GroupBy     []string
    Having      []ConditionSpec
    HavingAgg   []HavingAggSpec
    Limit       *int
    LimitParam  string            // Parameterized LIMIT
    Offset      *int
    OffsetParam string            // Parameterized OFFSET
    Distinct    bool
    DistinctOn  []string
    ForLocking  string
}

SelectSpec

type SelectSpec struct {
    Fields      []string
    SelectExprs []SelectExprSpec  // Expression-based SELECT (functions, aggregates)
    Where       []ConditionSpec
    OrderBy     []OrderBySpec
    GroupBy     []string
    Having      []ConditionSpec
    HavingAgg   []HavingAggSpec
    Limit       *int
    LimitParam  string            // Parameterized LIMIT
    Offset      *int
    OffsetParam string            // Parameterized OFFSET
    Distinct    bool
    DistinctOn  []string
    ForLocking  string
}

UpdateSpec

type UpdateSpec struct {
    Set   map[string]string  // field -> param
    Where []ConditionSpec
}

DeleteSpec

type DeleteSpec struct {
    Where []ConditionSpec
}

AggregateSpec

type AggregateSpec struct {
    Field string
    Where []ConditionSpec
}

ConditionSpec

type ConditionSpec struct {
    Field      string
    Operator   string
    Param      string
    IsNull     bool
    Logic      string           // "AND" or "OR" for groups
    Group      []ConditionSpec  // Nested conditions
    Between    bool             // Use BETWEEN with LowParam/HighParam
    NotBetween bool             // Use NOT BETWEEN with LowParam/HighParam
    LowParam   string           // Lower bound param for BETWEEN
    HighParam  string           // Upper bound param for BETWEEN
    RightField string           // For field-to-field comparisons (WHERE a.field = b.field)
}

Helper Methods

func (c ConditionSpec) IsGroup() bool           // Returns true if this is a grouped condition
func (c ConditionSpec) IsBetween() bool         // Returns true if Between is set
func (c ConditionSpec) IsNotBetween() bool      // Returns true if NotBetween is set
func (c ConditionSpec) IsFieldComparison() bool // Returns true if RightField is set

OrderBySpec

type OrderBySpec struct {
    Field     string
    Direction string  // "asc" or "desc"
    Nulls     string  // "first" or "last"
    Operator  string  // For expressions (e.g., "<->")
    Param     string  // For expression parameters
}

ParamSpec

type ParamSpec struct {
    Name        string
    Type        string
    Required    bool
    Default     any
    Description string
}

SelectExprSpec

Defines expression-based SELECT columns (functions, aggregates, casts).

type SelectExprSpec struct {
    Func     string          // Function name (see supported functions below)
    Field    string          // Primary field for single-field functions
    Fields   []string        // Multiple fields for multi-field functions (concat)
    Params   []string        // Additional parameters (substring positions, power exponent)
    CastType string          // Target type for cast operations
    Filter   *ConditionSpec  // Filter clause for aggregate functions
    Alias    string          // Required: column alias in result
}

Supported Functions:

Category	Functions
String	`upper`, `lower`, `length`, `trim`, `ltrim`, `rtrim`, `substring`, `replace`, `concat`
Math	`abs`, `ceil`, `floor`, `round`, `sqrt`, `power`
Date/Time	`now`, `current_date`, `current_time`, `current_timestamp`
Type	`cast`
Aggregate	`count`, `count_star`, `count_distinct`, `sum`, `avg`, `min`, `max`
Conditional	`coalesce`, `nullif`

HavingAggSpec

Defines aggregate conditions for HAVING clauses.

type HavingAggSpec struct {
    Func     string  // Aggregate function: "count", "sum", "avg", "min", "max"
    Field    string  // Field to aggregate
    Operator string  // Comparison operator
    Param    string  // Parameter name for comparison value
}

CompoundQuerySpec

Defines compound queries using set operations (UNION, INTERSECT, EXCEPT).

type CompoundQuerySpec struct {
    Base     QuerySpec         // The base query
    Operands []CompoundOperand // Set operations with additional queries
    OrderBy  []OrderBySpec     // Final ORDER BY (applies to combined result)
    Limit    *int              // Final LIMIT
    Offset   *int              // Final OFFSET
}

CompoundOperand

Defines a set operation in a compound query.

type CompoundOperand struct {
    Operation string    // "union", "union_all", "intersect", "intersect_all", "except", "except_all"
    Query     QuerySpec // The query to combine
}

AggregateFunc

type AggregateFunc string

const (
    AggCount AggregateFunc = "COUNT"
    AggSum   AggregateFunc = "SUM"
    AggAvg   AggregateFunc = "AVG"
    AggMin   AggregateFunc = "MIN"
    AggMax   AggregateFunc = "MAX"
)

Event Keys

var (
    KeyTable    = capitan.NewStringKey("table")
    KeyError    = capitan.NewStringKey("error")
    KeyDuration = capitan.NewDurationKey("duration")
)

Signals

var (
    ExecutorCreated = capitan.NewSignal("edamame.executor.created", "Executor instance created")
)

Hook for monitoring:

capitan.Hook(edamame.ExecutorCreated, func(ctx context.Context, e *capitan.Event) {
    table, _ := edamame.KeyTable.From(e)
    log.Printf("Executor created for table: %s", table)
})

Struct Tags

Edamame uses struct tags to understand your model:

type User struct {
    ID    int    `db:"id" type:"integer" constraints:"primarykey"`
    Email string `db:"email" type:"text" constraints:"notnull,unique"`
    Name  string `db:"name" type:"text"`
    Age   *int   `db:"age" type:"integer"`
}

Tag	Purpose	Example
`db`	Column name	`db:"user_id"`
`type`	SQL type	`type:"text"`, `type:"integer"`
`constraints`	Column constraints	`constraints:"primarykey,notnull"`