Documentation
¶
Overview ¶
Package libdbexec provides driver-agnostic interfaces (DBManager, Exec, QueryRower) for SQL access, implemented for PostgreSQL (lib/pq) and SQLite. WithTransaction pairs a CommitTx with a ReleaseTx meant for defer, and low-level driver errors are translated to package-level sentinels (ErrNotFound, ErrUniqueViolation, ErrDeadlockDetected, ...).
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrNotFound is returned by Scan when sql.ErrNoRows is encountered. ErrNotFound = errors.New("libdb: not found") // ErrTxFailed indicates a failure during transaction finalization (Commit or Rollback). ErrTxFailed = errors.New("libdb: transaction failed") // ErrMaxRowsReached indicates a table's configured maximum row count would be exceeded. ErrMaxRowsReached = errors.New("max row count reached") // ErrUniqueViolation corresponds to unique key constraint errors (e.g., PostgreSQL code 23505). ErrUniqueViolation = errors.New("libdb: unique constraint violation") // ErrForeignKeyViolation corresponds to foreign key constraint errors (e.g., PostgreSQL code 23503). ErrForeignKeyViolation = errors.New("libdb: foreign key violation") // ErrNotNullViolation corresponds to not-null constraint errors (e.g., PostgreSQL code 23502). ErrNotNullViolation = errors.New("libdb: not null constraint violation") // ErrCheckViolation corresponds to check constraint errors (e.g., PostgreSQL code 23514). ErrCheckViolation = errors.New("libdb: check constraint violation") // ErrConstraintViolation is a generic error for constraint violations not specifically mapped. ErrConstraintViolation = errors.New("libdb: constraint violation") // ErrDeadlockDetected corresponds to deadlock errors (e.g., PostgreSQL code 40P01). ErrDeadlockDetected = errors.New("libdb: deadlock detected") // ErrSerializationFailure corresponds to serialization failures (e.g., PostgreSQL code 40001). ErrSerializationFailure = errors.New("libdb: serialization failure") // ErrLockNotAvailable corresponds to lock acquisition failures (e.g., PostgreSQL code 55P03). ErrLockNotAvailable = errors.New("libdb: lock not available") // ErrQueryCanceled corresponds to query cancellation (e.g., PostgreSQL code 57014 or context cancellation). ErrQueryCanceled = errors.New("libdb: query canceled") // ErrDataTruncation corresponds to data truncation errors (e.g., PostgreSQL code 22001). ErrDataTruncation = errors.New("libdb: data truncation error") // ErrNumericOutOfRange corresponds to numeric overflow errors (e.g., PostgreSQL code 22003). ErrNumericOutOfRange = errors.New("libdb: numeric value out of range") // ErrInvalidInputSyntax corresponds to syntax errors in data representation (e.g., PostgreSQL code 22P02). ErrInvalidInputSyntax = errors.New("libdb: invalid input syntax") // ErrUndefinedColumn corresponds to referencing an unknown column (e.g., PostgreSQL code 42703). ErrUndefinedColumn = errors.New("libdb: undefined column") // ErrUndefinedTable corresponds to referencing an unknown table (e.g., PostgreSQL code 42P01). ErrUndefinedTable = errors.New("libdb: undefined table") )
Predefined errors, checkable with errors.Is without relying on driver-specific error types or codes.
Functions ¶
func SetupLocalInstance ¶
func SetupLocalInstance(ctx context.Context, dbName, dbUser, dbPassword string) (string, *postgres.PostgresContainer, func(), error)
SetupLocalInstance starts an ephemeral PostgreSQL container for tests via testcontainers-go. It returns a ready-to-use connection string, the underlying container, and a cleanup func that stops the container. The cleanup func is always safe to call (even on error paths) except when SetupLocalInstance itself fails to start the container, in which case it returns a no-op cleanup.
Types ¶
type CommitTx ¶
CommitTx commits a transaction; call only on the success path. Returns nil, a wrapped ErrTxFailed, or a context error if ctx is done before the attempt.
type DBManager ¶
type DBManager interface {
// WithoutTransaction returns an executor operating directly on the connection
// group, outside any transaction; each operation may run on a different connection.
WithoutTransaction() Exec
// WithTransaction starts a transaction and returns an Exec bound to it, a
// CommitTx, and a ReleaseTx (idempotent, safe for defer, rolls back if not
// committed). onRollback handlers run only after a successful rollback and
// must not touch the transaction.
WithTransaction(ctx context.Context, onRollback ...func()) (Exec, CommitTx, ReleaseTx, error)
// Close terminates the underlying database connection group.
Close() error
}
DBManager is the main entry point for database interactions: obtaining executors and managing the connection lifecycle. Typical usage starts a transaction with WithTransaction, defers the returned ReleaseTx immediately, does work through the returned Exec, then calls CommitTx on the success path.
func NewPostgresDBManager ¶
NewPostgresDBManager creates a new DBManager for PostgreSQL. It opens a connection group using the provided DSN, pings the database to verify connectivity, and optionally executes an initial schema setup query. Note: For production schema management, using dedicated migration tools is recommended over passing a simple schema string here.
func NewSQLiteDBManager ¶
NewSQLiteDBManager creates a new DBManager for SQLite. path is the database file path (e.g. "./.contenox/local.db" or "file:local.db"). The parent directory is created if missing. schema is applied on open (e.g. runtimetypes.SchemaSQLite).
type Exec ¶
type Exec interface {
ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
// QueryContext executes a query returning rows. Callers must check rows.Err() after iterating.
QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
// QueryRowContext always returns a non-nil QueryRower; errors surface from its Scan.
QueryRowContext(ctx context.Context, query string, args ...any) QueryRower
// DriverName returns the database driver name ("postgres", "sqlite").
DriverName() string
}
Exec is the common interface for executing database operations, whether within a transaction or directly on the connection group. Implementations must translate driver errors into the package's Err* sentinels.
type QueryRower ¶
type QueryRower interface {
// Scan returns ErrNotFound if no row matched; other errors are translated too.
Scan(dest ...any) error
}
QueryRower wraps *sql.Row so Scan errors (like sql.ErrNoRows) are translated consistently.
Source Files