Documentation
¶
Overview ¶
Package db provides unified SQLite database management for bc CLI.
This package consolidates SQLite connection management, ensuring consistent configuration across all database operations. It provides:
- Connection pooling optimized for SQLite's single-writer model
- Consistent pragma settings for WAL mode and performance
- Automatic directory creation for database files
- Graceful shutdown handling
Usage ¶
db, err := db.Open("/path/to/database.db")
if err != nil {
return err
}
defer db.Close()
Configuration ¶
All connections use these settings:
- WAL journal mode for better concurrency
- Foreign keys enabled
- 30 second busy timeout
- Single connection pool (SQLite limitation)
- Optimized cache and synchronous settings
Index ¶
- Constants
- func BCDBPath(workspaceRoot string) string
- func CloseShared() error
- func DefaultPassword() string
- func IsPostgresEnabled() bool
- func OpenPostgres(dsn string) (*sql.DB, error)
- func OpenWorkspaceDB(workspaceRoot string) (*sql.DB, string, error)
- func OpenWorkspaceDBWithConfig(workspaceRoot string, cfg *StorageSettings) (*sql.DB, string, error)
- func PostgresDSN() string
- func SetShared(db *sql.DB, driver string)
- func Shared() *sql.DB
- func SharedDriver() string
- func TryOpenPostgres() (*sql.DB, error)
- type Config
- type DB
- type Registry
- type SQLiteSettings
- type StorageSettings
- type TimescaleSettings
Constants ¶
const DefaultBusyTimeout = 30000 // milliseconds
DefaultBusyTimeout is the default timeout for SQLite busy handling. Set to 30s to handle concurrent agent access; SQLite returns as soon as the lock is available — this is just the worst-case upper bound.
const DefaultCacheSize = 2000
DefaultCacheSize is the default SQLite page cache size in KB.
const DefaultPostgresDSN = "postgres://bc:bc@localhost:5432/bc"
DefaultPostgresDSN is the connection string for the bcdb (TimescaleDB) container.
Variables ¶
This section is empty.
Functions ¶
func DefaultPassword ¶
func DefaultPassword() string
DefaultPassword returns the database password from BC_DB_PASSWORD env var, falling back to "bc" for local development with a warning log. Production deployments should always set BC_DB_PASSWORD.
func IsPostgresEnabled ¶
func IsPostgresEnabled() bool
IsPostgresEnabled returns true if DATABASE_URL is set, indicating Postgres should be used.
func OpenPostgres ¶
OpenPostgres opens a connection pool to Postgres using the given DSN. The DSN should be a postgres:// URL (e.g. postgres://bc:bc@localhost:5432/bc).
func OpenWorkspaceDB ¶
OpenWorkspaceDB opens the workspace database based on configuration. Priority: DATABASE_URL env var > settings.json storage config > SQLite default.
func OpenWorkspaceDBWithConfig ¶
OpenWorkspaceDBWithConfig opens the workspace database using settings.json config. If DATABASE_URL env var is set, it takes priority (for Docker/CI). Otherwise, settings.json storage.default determines the backend.
func PostgresDSN ¶
func PostgresDSN() string
PostgresDSN returns the Postgres connection string from DATABASE_URL env var, or the default bcdb DSN if not set.
func SetShared ¶
SetShared sets the shared workspace database connection. Call once at startup (in cmd/bcd or CLI init).
func Shared ¶
Shared returns the shared workspace database connection. Returns nil if not set (stores should fall back to opening their own).
func TryOpenPostgres ¶
TryOpenPostgres attempts to open a Postgres connection. Returns (nil, nil) if DATABASE_URL is not set (Postgres not configured). Returns (nil, err) only when DATABASE_URL is set but connection fails.
Types ¶
type Config ¶
type Config struct {
// BusyTimeout is the SQLite busy timeout in milliseconds.
// Default: 30000 (30 seconds)
BusyTimeout int
// CacheSize is the SQLite page cache size in KB.
// Default: 2000 (2MB)
CacheSize int
// ReadOnly opens the database in read-only mode.
ReadOnly bool
}
Config holds database configuration options.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns the default database configuration.
type DB ¶
DB wraps a sql.DB with bc-specific functionality.
func Open ¶
Open opens a SQLite database at the given path with default configuration. The directory containing the database file is created if it doesn't exist.
func OpenWithConfig ¶
OpenWithConfig opens a SQLite database with custom configuration.
func SharedWrapped ¶
func SharedWrapped() *DB
SharedWrapped returns the shared database as a *DB wrapper. Returns nil if no shared connection is set.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages multiple named database connections. Use this when you need to share connections across packages.
type SQLiteSettings ¶
type SQLiteSettings struct {
Path string // base directory for bc.db (default: workspace .bc/ dir)
}
SQLiteSettings configures the SQLite database path.
type StorageSettings ¶
type StorageSettings struct {
Default string // "sqlite" or "timescale"
SQLite SQLiteSettings
Timescale TimescaleSettings
}
StorageSettings holds the storage configuration from settings.json. Used by OpenWorkspaceDB to determine the database backend.
type TimescaleSettings ¶
TimescaleSettings configures the TimescaleDB (Postgres) connection.
func (TimescaleSettings) DSN ¶
func (p TimescaleSettings) DSN() string
DSN builds a Postgres connection string from config fields.
Source Files