database

type Client ¶

type Client interface {
	// Reader returns an executor for the read database. It exposes no transaction
	// control by design; use WithTransaction for anything transactional.
	Reader() SQLQueryExecutor
	// Writer returns an executor for the write database, for single, non-transactional
	// statements. Multi-statement work belongs in WithTransaction.
	Writer() SQLQueryExecutor
	// WithTransaction begins a transaction on the write database, invokes fn with it as
	// the sole executor, commits on a nil return, and rolls back on error or panic.
	WithTransaction(ctx context.Context, fn func(tx SQLQueryExecutorAndTransactionManager) error) error
	Close() error
	CurrentTime() time.Time
}

Client is the safe surface for database access. It deliberately does not expose a raw *sql.DB: reads and single-statement writes go through the narrow executors returned by Reader and Writer (which cannot begin a transaction), and all transactional work goes through WithTransaction. A transaction is therefore unreachable except via WithTransaction, so statements cannot accidentally run outside a transaction or against the read replica.

Callers that genuinely need the concrete pool (migrations, session-pinned advisory locks, driver features off this seam) can obtain it via the RawAccess capability.

type ClientConfig ¶

type ClientConfig interface {
	GetReadConnectionString() string
	GetWriteConnectionString() string
	GetMaxPingAttempts() uint64
	GetPingWaitPeriod() time.Duration
	GetMaxIdleConns() int
	GetMaxOpenConns() int
	GetConnMaxLifetime() time.Duration
}

ClientConfig provides the configuration needed by database clients. This interface allows the config package to provide configuration without creating an import cycle.

type Manager ¶

type Manager interface {
	CreateUser(ctx context.Context, username, password string) error
	DeleteUser(ctx context.Context, username string) error

	CreateDatabase(ctx context.Context, dbName, owner string) error
	DeleteDatabase(ctx context.Context, dbName string) error

	UserExists(ctx context.Context, username string) (bool, error)
	DatabaseExists(ctx context.Context, dbName string) (bool, error)

	GrantUserAccessToTable(ctx context.Context, username, schema, table, privilege string) error
	UserCanAccessDatabase(ctx context.Context, username, dbName string) (bool, error)
}

type Migrator ¶

type Migrator interface {
	Migrate(ctx context.Context, db *sql.DB) error
}

Migrator is an interface for running database migrations. Implementations handle the specifics of migration execution (e.g., darwin, goose, etc.)

type RawAccess ¶

type RawAccess interface {
	ReadDB() *sql.DB
	WriteDB() *sql.DB
}

RawAccess is an optional capability exposing the concrete *sql.DB pools for callers that genuinely need them — schema migrations, session-pinned advisory locks, or driver features outside the executor seam. A caller obtains it by asserting on a Client:

raw, ok := client.(database.RawAccess)

Reaching for RawAccess is a deliberate step outside the safe Client surface; prefer Reader, Writer, and WithTransaction wherever they suffice.

type ResultIterator ¶

type ResultIterator interface {
	Next() bool
	Err() error
	Scanner
	io.Closer
}

ResultIterator represents any iterable database response (i.e. sql.Rows).

type SQLQueryExecutor ¶

type SQLQueryExecutor interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	PrepareContext(context.Context, string) (*sql.Stmt, error)
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

SQLQueryExecutor is a subset interface for sql.{DB|Tx} objects.

type SQLQueryExecutorAndTransactionManager ¶

type SQLQueryExecutorAndTransactionManager interface {
	SQLQueryExecutor
	SQLTransactionManager
}

SQLQueryExecutorAndTransactionManager is a subset interface for sql.{DB|Tx} objects.

type SQLTransactionManager ¶

type SQLTransactionManager interface {
	Rollback() error
}

SQLTransactionManager is a subset interface for sql.{DB|Tx} objects.

type Scanner ¶

type Scanner interface {
	Scan(dest ...any) error
}

Scanner represents any database response (i.e. sql.Row[s]).