Documentation
¶
Overview ¶
Package database provides database access layer.
WHY: Separate database package because: 1. Database concerns (pooling, transactions) are orthogonal to business logic 2. sqlc generated code needs a stable home independent of domain changes 3. Connection lifecycle management requires centralized control 4. Testing requires ability to swap real database for test fixtures
Package database provides database connection and management functionality. Uses pgx as PostgreSQL driver with pgvector extension support.
WHY: pgx chosen over database/sql because: 1. Native PostgreSQL protocol implementation is 3x faster 2. Built-in connection pooling with better control 3. Native support for PostgreSQL-specific types (arrays, JSONB) 4. pgvector extension requires custom type handling
Package database code generation directives
Index ¶
- Constants
- type Client
- type Config
- type DB
- func (db *DB) Acquire(ctx context.Context) (*pgxpool.Conn, error)
- func (db *DB) Begin(ctx context.Context) (pgx.Tx, error)
- func (db *DB) BeginTx(ctx context.Context, txOptions pgx.TxOptions) (pgx.Tx, error)
- func (db *DB) Close()
- func (db *DB) Exec(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
- func (db *DB) Ping(ctx context.Context) error
- func (db *DB) Pool() *pgxpool.Pool
- func (db *DB) Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)
- func (db *DB) QueryRow(ctx context.Context, sql string, args ...any) pgx.Row
- func (db *DB) RunMigration(ctx context.Context, migration string) error
- func (db *DB) RunMigrations() error
- func (db *DB) Stats() *pgxpool.Stat
- func (db *DB) WithTx(ctx context.Context, fn func(pgx.Tx) error) error
- type DBOption
Constants ¶
const ( // MaxInt32 safe conversion limit MaxInt32 = 2147483647 // DefaultBatchSize for batch operations DefaultBatchSize = 100 // MaxMemoriesPerQuery to prevent overload MaxMemoriesPerQuery = 1000 // MinMemoriesForConsolidation threshold MinMemoriesForConsolidation = 50 )
Database constants
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client provides unified database access.
WHY: Client wrapper pattern because: 1. sqlc.Queries alone doesn't manage connection lifecycle 2. Transaction coordination requires access to underlying pool 3. Metrics and logging need centralized interception point 4. Future sharding/read replicas need abstraction layer
func (*Client) Close ¶
func (c *Client) Close()
Close closes the database connection pool Note: pgxpool.Pool.Close() doesn't return an error in pgx v5
func (*Client) RunMigrations ¶
RunMigrations executes database migrations
type Config ¶
type Config struct {
// DSN is the database connection string
DSN string
// MaxConns limits concurrent database connections
MaxConns int32
// MinConns maintains minimum idle connections
MinConns int32
// MaxConnLifetime prevents connection staleness
MaxConnLifetime time.Duration
// MaxConnIdleTime closes idle connections
MaxConnIdleTime time.Duration
// HealthCheckPeriod defines how often to verify connections
HealthCheckPeriod time.Duration
}
Config defines database connection parameters
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB wraps the database connection pool.
WHY: Wrapper pattern because: 1. Abstracts pgx-specific details from business logic 2. Centralizes connection lifecycle management 3. Provides hook points for metrics and logging 4. Enables mock implementations for testing
func NewDB ¶
NewDB creates a new database connection pool. Automatically configures pool parameters and validates connectivity.
WHY: Constructor validates immediately because: 1. Fail fast on configuration errors 2. Prevents runtime connection failures 3. Database is required dependency - no graceful degradation
func (*DB) Acquire ¶
Acquire obtains a database connection from the pool. Must be released after use to avoid connection leaks
func (*DB) Pool ¶
Pool returns the underlying connection pool. Use only when direct pool access is required
func (*DB) RunMigration ¶
RunMigration executes a database migration. Runs the specified SQL script within a transaction
func (*DB) RunMigrations ¶
RunMigrations runs database migrations using golang-migrate
func (*DB) WithTx ¶
WithTx executes a function within a transaction. Automatically handles commit and rollback.
WHY: Transaction helper because: 1. Ensures transactions are always closed 2. Consistent error handling pattern 3. Panic recovery prevents connection leaks 4. Reduces boilerplate in business logic
Source Files
Directories