libdbexec

type CommitTx func(ctx context.Context) error

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
}

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
}

type QueryRower interface {
	// Scan returns ErrNotFound if no row matched; other errors are translated too.
	Scan(dest ...any) error
}

type ReleaseTx func() error

type SQLiteJournalMode string

type SQLiteOptions struct {
	// JournalMode selects PRAGMA journal_mode. The zero value selects WAL.
	// Journal mode is a persistent property of the database file, so changing
	// it converts the file on open.
	JournalMode SQLiteJournalMode

	// Synchronous selects PRAGMA synchronous. The zero value emits no pragma
	// and leaves SQLite's FULL default. SQLiteSynchronousNormal trades an
	// fsync per commit for durability of the most recent transactions across
	// a power loss; in WAL mode it cannot corrupt the database, which is why
	// it is refused outside WAL.
	Synchronous SQLiteSynchronous

	// BusyTimeout sets PRAGMA busy_timeout, how long SQLite retries a locked
	// database before returning SQLITE_BUSY. Nil means the 5000ms default. A
	// pointer to zero disables waiting and fails contended writes immediately.
	// Sub-millisecond precision is not representable and is refused.
	BusyTimeout *time.Duration

	// DisableForeignKeys turns off PRAGMA foreign_keys. The zero value keeps
	// foreign keys enforced. The sense is inverted so that the zero value
	// matches the enforced default.
	DisableForeignKeys bool

	// CacheSize sets PRAGMA cache_size. Nil emits no pragma. A negative value
	// is a size in KiB, a positive value is a count of pages -- this is
	// SQLite's own sign convention and it is easy to invert, so prefer
	// SQLiteCacheKiB or SQLiteCachePages over a bare literal. A pointer to
	// zero is refused: it would disable the page cache, and it is far more
	// often a zero value leaking through than a deliberate choice.
	CacheSize *int

	// MaxOpenConns caps total open connections via sql.DB.SetMaxOpenConns.
	// Nil leaves the pool unbounded, which is Go's default. A pointer to zero
	// is also unbounded, stated explicitly. See NewSQLiteDBManagerWithOptions
	// for what capping this to 1 costs.
	MaxOpenConns *int

	// MaxIdleConns caps retained idle connections via
	// sql.DB.SetMaxIdleConns. Nil leaves Go's default of 2. A pointer to zero
	// retains none, reopening the file on every acquisition. database/sql
	// silently clamps this to MaxOpenConns when it is larger.
	MaxIdleConns *int

	// ConnMaxLifetime bounds how long a connection may be reused via
	// sql.DB.SetConnMaxLifetime. The zero value means unlimited, matching
	// database/sql, so unset and zero are indistinguishable here.
	ConnMaxLifetime time.Duration

	// ConnMaxIdleTime bounds how long a connection may sit idle via
	// sql.DB.SetConnMaxIdleTime. The zero value means unlimited, matching
	// database/sql, so unset and zero are indistinguishable here.
	ConnMaxIdleTime time.Duration
}

type SQLiteSynchronous string