sql

func DecorateInput ¶ added in v0.12.0

func DecorateInput[Req any](
	fn func(context.Context, Req) error,
	codec codex.Codec[Req],
	opts ValidateOptions,
) func(context.Context, Req) error

DecorateInput wraps an exec-style sqlc-generated function (a `:exec` query, shaped `func(context.Context, Req) error`) with pre-query validation: arg is validated via codec BEFORE fn is called — fn is never invoked on invalid input. Returns a function with the identical signature, callable in place of the sqlc method everywhere:

insertUser := sqladapter.DecorateInput(queries.InsertUser, insertParamsCodec,
    sqladapter.ValidateOptions{Table: "users", Op: "insert_user"})
err := insertUser(ctx, params) // codec-validated automatically

This is the declare-once counterpart to calling Validate by hand before every sqlc call (sql.md's "pre-query validation" usage mode) — it bundles the codec, Table, and Op into one reusable value the same way ports.Cache/ports.NewCache bundle a cache's key/format/TTL, so callers don't repeat them at every call site.

Unlike bare Validate (which has no ctx parameter), the returned closure resolves stats.ObserverFromContext when opts.Observer is nil, since it wraps a ctx-taking function.

Returns RowValidationError without calling fn when validation fails.

// Stand-in for an sqlc-generated ":exec" method.
insertUserSQL := func(ctx context.Context, u testUser) error {
	fmt.Println("INSERT user:", u.Name)
	return nil
}

insertUser := sqladapter.DecorateInput(insertUserSQL, userCodec,
	sqladapter.ValidateOptions{Table: "users", Op: "insert_user"})

// Call in place of the sqlc method everywhere — validated automatically.
valid := testUser{ID: "f47ac10b-58cc-4372-a567-0e02b2c3d479", Name: "Ada", Email: "ada@example.com", Role: "user"}
if err := insertUser(context.Background(), valid); err != nil {
	fmt.Println("unexpected error:", err)
}

// Invalid input never reaches the sqlc method.
invalid := testUser{ID: "not-a-uuid", Name: "Ada", Email: "ada@example.com", Role: "user"}
if err := insertUser(context.Background(), invalid); err != nil {
	fmt.Println("rejected before insert:", err != nil)
}

Output:
INSERT user: Ada
rejected before insert: true

func DecorateOutput ¶ added in v0.12.0

func DecorateOutput[Req, Resp any](
	fn func(context.Context, Req) (Resp, error),
	codec codex.Codec[Resp],
	opts ValidateOptions,
) func(context.Context, Req) (Resp, error)

DecorateOutput wraps a query-style sqlc-generated function (a `:one`/ `:many` query, shaped `func(context.Context, Req) (Resp, error)`) with post-query validation: fn's returned Resp is validated via codec AFTER fn returns — defense in depth against rows written by other clients that bypassed the codec. Returns a function with the identical signature, callable in place of the sqlc method everywhere:

getUser := sqladapter.DecorateOutput(queries.GetUser, userCodec,
    sqladapter.ValidateOptions{Table: "users", Op: "get_user"})
u, err := getUser(ctx, id) // codec-validated automatically

This is the declare-once counterpart to calling Validate by hand after every sqlc call (sql.md's "post-query validation" usage mode).

Unlike bare Validate (which has no ctx parameter), the returned closure resolves stats.ObserverFromContext when opts.Observer is nil, since it wraps a ctx-taking function.

fn's own error (e.g. sql.ErrNoRows) is returned unchanged — validation only runs on a successful call. Returns RowValidationError when fn succeeds but the returned value fails validation.

// Stand-in for an sqlc-generated ":one" method.
getUserSQL := func(ctx context.Context, id string) (testUser, error) {
	return testUser{ID: id, Name: "Ada", Email: "ada@example.com", Role: "user"}, nil
}

getUser := sqladapter.DecorateOutput(getUserSQL, userCodec,
	sqladapter.ValidateOptions{Table: "users", Op: "get_user"})

u, err := getUser(context.Background(), "f47ac10b-58cc-4372-a567-0e02b2c3d479")
if err != nil {
	fmt.Println("unexpected error:", err)
	return
}
fmt.Println("validated:", u.Name)

Output:
validated: Ada

func DrainInsertAdapter ¶

func DrainInsertAdapter[T any](
	codec codex.Codec[T],
	insertFn func(context.Context, T) error,
	opts DrainInsertOptions,
) ports.SinkAdapter[T]

DrainInsertAdapter returns a ports.SinkAdapter that validates and inserts each item via insertFn. Use with ports.SinkPort.Bind:

domain.Readings.Bind(ctx, sql.DrainInsertAdapter(readingCodec,
    func(ctx context.Context, r Reading) error { return db.Insert(ctx, r) },
    sql.DrainInsertOptions{}))

func QueryAdapter ¶

func QueryAdapter[T any](
	codec codex.Codec[T],
	queryFn func(context.Context) ([]T, error),
	interval time.Duration,
	opts QueryStreamOptions,
) ports.SourceAdapter[T]

QueryAdapter returns a ports.SourceAdapter that polls a SQL query at interval, emitting each validated row. Use with ports.SourcePort.Bind:

domain.Configs.Bind(ctx, sql.QueryAdapter(configCodec,
    func(ctx context.Context) ([]Config, error) { return db.ListConfigs(ctx) },
    5*time.Minute, sql.QueryStreamOptions{}))

func QueryEachAdapter ¶

func QueryEachAdapter[In, T any](
	codec codex.Codec[T],
	queryFn func(context.Context, In) ([]T, error),
	opts QueryEachStreamOptions,
) ports.IOAdapter[In, T]

QueryEachAdapter returns a ports.IOAdapter that performs a parameterized SQL query for each In item, emitting each result row as a T item (1:N). Use with ports.IOPort.Bind:

domain.Calibration.Bind(ctx, sql.QueryEachAdapter(thresholdCodec,
    func(ctx context.Context, s SensorReading) ([]Threshold, error) {
        return db.GetThresholdBySensor(ctx, s.SensorID)
    }, sql.QueryEachStreamOptions{Table: "thresholds", Op: "get_by_sensor"}))

func Validate ¶

func Validate[T any](c codex.Codec[T], v T, opts ValidateOptions) (T, error)

Validate runs v through c's encode→decode round trip, applying every Refine and RefineFunc constraint declared on c.

The returned T is the normalized value — the result of Decode after Encode. This may differ from v when a Refine step normalizes values (e.g. trimming whitespace). This matches the behaviour of [format.JSON.Read] and is the same round-trip semantics used throughout go-codex.

Use Validate to validate a struct returned by a sqlc query method (post-query defence in depth against rows written by other clients) or a struct about to be passed into a sqlc insert or update method (pre-query, so invalid data never reaches the database).

Codec failures are wrapped in RowValidationError. Per-field constraint failures are additionally reported via stats.Observer.RecordValidationError with location "sql_row". If opts.Observer also implements stats.SQLObserver, RecordValidation is called after every Validate call, success or failure.

package main

import (
	"fmt"

	sqladapter "github.com/DaniDeer/go-codex/adapters/sql"
	"github.com/DaniDeer/go-codex/codex"
	"github.com/DaniDeer/go-codex/validate"
)

func main() {
	type Item struct {
		ID   string
		Name string
	}
	itemCodec := codex.Struct(
		codex.RequiredField("id",
			codex.String(),
			func(i Item) string { return i.ID },
			func(i *Item, v string) { i.ID = v }),
		codex.RequiredField("name",
			codex.String().Refine(validate.NonEmptyString),
			func(i Item) string { return i.Name },
			func(i *Item, v string) { i.Name = v }),
	)

	// Pre-query: validate before writing to the database.
	params := Item{ID: "1", Name: "Widget"}
	validated, err := sqladapter.Validate(itemCodec, params, sqladapter.ValidateOptions{
		Table: "items", Op: "insert_item",
	})
	if err != nil {
		fmt.Println("invalid:", err)
		return
	}
	fmt.Println("validated:", validated.Name)
}

Output:
validated: Widget