database

func ConstraintName ¶ added in v0.40.0

func ConstraintName(err error) (string, bool)

ConstraintName returns the violated constraint name when the driver exposes it. PostgreSQL populates this for constraint violations; Oracle does not, so ConstraintName returns ("", false) for Oracle errors.

func ExecuteInsert ¶ added in v0.55.0

func ExecuteInsert(ctx context.Context, exec Executor, q SQLProvider, op string) error

ExecuteInsert runs an INSERT. It does not inspect RowsAffected: a successful INSERT is success, and vendor differences around LastInsertId/RETURNING are out of scope here.

func ExecuteQueryMany ¶ added in v0.55.0

func ExecuteQueryMany(ctx context.Context, exec Executor, q SQLProvider, op string, scan func(rows *sql.Rows) error) error

ExecuteQueryMany runs q and invokes scan once per row. Zero rows is not an error (the caller sees an empty result). A scan callback error aborts iteration and is wrapped at StageScan. A nil scan is rejected up front at StageBuild rather than left to panic once a row arrives: unlike a nil q or exec (which fail loudly at the call site, in the caller's own frame), a nil scan is data-dependent — it only panics once the query returns a row, so a zero-row result would let the mistake pass silently in dev and blow up later in prod.

func ExecuteQuerySingle ¶ added in v0.55.0

func ExecuteQuerySingle(ctx context.Context, exec Executor, q SQLProvider, op string, dest ...any) error

ExecuteQuerySingle runs q and scans the first row into dest. It returns an op-labeled ErrNoRows wrap when the query matches no rows, and *ExecError for infrastructure failures. Extra rows beyond the first are ignored (sql.Row parity): after a successful scan, the rows are closed explicitly (mirroring sql.Row.Scan) so a driver error that only surfaces at Close — a truncated result, a connection fault mid-statement — is not silently swallowed; that failure is reported at StageClose. op labels errors only — it does not feed metrics or tracing; use database.WithRepositoryMethod(ctx, ...) for attribution. Typical mapping in an app:

err := database.ExecuteQuerySingle(ctx, tx, q, "ownership", &row.ID, &row.Name)
switch {
case errors.Is(err, database.ErrNoRows):
	return domain.ErrResourceNotFound // business 404
case err != nil:
	return fmt.Errorf("load ownership: %w", err) // infra 500
}

func ExecuteUpdate ¶ added in v0.55.0

func ExecuteUpdate(ctx context.Context, exec Executor, q SQLProvider, op string) (int64, error)

ExecuteUpdate runs an UPDATE/DELETE and returns the affected-row count. It does not interpret zero: a legitimately-zero write (e.g. an UPDATE guarded by a WHERE clause that may match nothing, such as an idempotent state transition, or a bulk statement with no matching rows) returns (0, nil). Use ExecuteUpdateOne when zero affected rows should surface as ErrNoRows.

func ExecuteUpdateOne ¶ added in v0.55.0

func ExecuteUpdateOne(ctx context.Context, exec Executor, q SQLProvider, op string) error

ExecuteUpdateOne runs an UPDATE/DELETE expected to match exactly one row and enforces that cardinality: zero rows affected returns an op-labeled ErrNoRows wrap, so "not found" surfaces uniformly with ExecuteQuerySingle; more than one row affected returns *ExecError at StageRowsAffected instead of silently reporting success, because a broader-than-intended WHERE predicate updating several rows is a data-integrity failure, not a "found it" outcome; exactly one row affected returns nil. Use ExecuteUpdate when a non-singular match is legitimate (bulk or idempotent writes), or when only the caller can tell "absent" from "already in the target state".

func GetSupportedDatabaseTypes ¶

func GetSupportedDatabaseTypes() []string

GetSupportedDatabaseTypes returns a list of supported database types

func IsForeignKeyViolation ¶ added in v0.40.0

func IsForeignKeyViolation(err error) bool

IsForeignKeyViolation reports whether err is a foreign-key constraint violation (PostgreSQL SQLSTATE 23503, Oracle ORA-02291).

func IsNotFound ¶ added in v0.40.0

func IsNotFound(err error) bool

IsNotFound reports whether err is a no-rows result (sql.ErrNoRows). Scan paths produce it natively; on the write path, ExecuteUpdateOne surfaces it via ErrNoRows (which wraps sql.ErrNoRows) when an UPDATE/DELETE expected to match exactly one row matches none, so IsNotFound matches that too. ExecuteUpdate does not produce it — zero rows affected is (0, nil) there.

func IsUniqueViolation ¶ added in v0.40.0

func IsUniqueViolation(err error) bool

IsUniqueViolation reports whether err is a unique or primary-key constraint violation (PostgreSQL SQLSTATE 23505, Oracle ORA-00001). It traverses the framework's error wrap chain via errors.As, so callers must wrap driver errors with %w (not %v) for it to work.

func ValidateDatabaseType ¶

func ValidateDatabaseType(dbType string) error

ValidateDatabaseType reports an error when dbType is not among the supported database types.

func WithTx ¶ added in v0.40.0

func WithTx(ctx context.Context, db Interface, fn func(ctx context.Context, tx Tx) error) error

WithTx runs fn inside a database transaction. It commits when fn returns nil, rolls back and returns fn's original error when fn returns an error, and rolls back then re-panics if fn panics. After a successful commit the deferred rollback is skipped (a committed flag guards it), so there is no post-commit rollback noise on the happy path.

fn must use the provided tx for all database work; using the outer db handle inside fn escapes the transaction.

func WithTxOptions ¶ added in v0.40.0

func WithTxOptions(ctx context.Context, db Interface, opts *sql.TxOptions, fn func(ctx context.Context, tx Tx) error) error

WithTxOptions behaves like WithTx but begins the transaction with the given options (isolation level, read-only mode) via BeginTx. A nil opts is equivalent to WithTx.