storage

type BackgroundIndex ¶ added in v0.2.2

type BackgroundIndex struct {
	// Name is the index name, as to_regclass resolves it.
	Name string
	// Create builds the index: CREATE INDEX CONCURRENTLY IF NOT EXISTS ...
	Create string
	// Label names the index in log messages, e.g. "usage auth key".
	Label string
}

BackgroundIndex is a PostgreSQL index added to a table that may already hold years of history. It is built CONCURRENTLY off the startup path, so the table keeps accepting writes while the build scans it.

type BackgroundIndexBuilder ¶ added in v0.2.2

type BackgroundIndexBuilder struct {
	Pool *pgxpool.Pool
	// LockKey is the advisory lock key. Builders of one table share a key,
	// since PostgreSQL runs one concurrent build per table at a time.
	LockKey int64
	// Retry is the pause between attempts; BackgroundIndexRetry when zero.
	Retry time.Duration
}

BackgroundIndexBuilder builds BackgroundIndexes one at a time, and only while it holds a session advisory lock, so of all the replicas sharing a database one builds and the rest wait for it.

The lock is taken without waiting. A blocking wait would hold a snapshot that the other replica's concurrent build has to wait out, deadlocking the two. It also means an invalid index the lock holder finds is a failed or abandoned build, never one in progress, so it is safe to drop and rebuild.

func (b BackgroundIndexBuilder) Build(ctx context.Context, indexes ...BackgroundIndex) bool

func (b BackgroundIndexBuilder) Start(indexes ...BackgroundIndex) (stop func())

func (b BackgroundIndexBuilder) TryBuild(ctx context.Context, index BackgroundIndex) bool

type Config ¶

type Config struct {
	// Type specifies the storage backend: "sqlite", "postgresql", or "mongodb"
	Type string

	// SQLite configuration
	SQLite SQLiteConfig

	// PostgreSQL configuration
	PostgreSQL PostgreSQLConfig

	// MongoDB configuration
	MongoDB MongoDBConfig
}

Config holds storage configuration

type HealthChecker ¶

type HealthChecker interface {
	Ping(ctx context.Context) error
}

HealthChecker is implemented by storage backends that can verify connectivity to the underlying database. All concrete backends satisfy it; readiness checks type-assert against this interface.

type MongoDBConfig ¶

type MongoDBConfig struct {
	// URL is the connection string (e.g., mongodb://localhost:27017)
	URL string
	// Database is the database name (default: gomodel)
	Database string
}

MongoDBConfig holds MongoDB-specific configuration

type MongoDBStorage ¶

type MongoDBStorage interface {
	Storage
	Database() *mongo.Database
}

MongoDBStorage exposes a MongoDB database handle.

func NewMongoDB(ctx context.Context, cfg MongoDBConfig) (MongoDBStorage, error)

type PostgreSQLConfig ¶

type PostgreSQLConfig struct {
	// URL is the connection string (e.g., postgres://user:pass@localhost/dbname)
	URL string
	// MaxConns is the maximum connection pool size (default: 10)
	MaxConns int
}

PostgreSQLConfig holds PostgreSQL-specific configuration

type PostgreSQLStorage ¶

type PostgreSQLStorage interface {
	Storage
	Pool() *pgxpool.Pool
}

PostgreSQLStorage exposes a PostgreSQL connection pool.

func NewPostgreSQL(ctx context.Context, cfg PostgreSQLConfig) (PostgreSQLStorage, error)

type RecentWrite ¶ added in v0.2.2

type RecentWrite struct {
	ID        string
	WrittenAt int64
}

RecentWrite names one persisted row and when it was written: the writer's clock at the batch write that stored it, in unix microseconds.

type RowScanner ¶

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

RowScanner is the single-row result shape shared by database/sql and pgx.

type SQLiteConfig ¶

type SQLiteConfig struct {
	// Path is the database file path (default: DefaultSQLitePath())
	Path string
}

SQLiteConfig holds SQLite-specific configuration

type SQLiteStorage ¶

type SQLiteStorage interface {
	Storage
	DB() *sql.DB
}

SQLiteStorage exposes a SQLite database handle.

func NewSQLite(cfg SQLiteConfig) (SQLiteStorage, error)

type Storage ¶

type Storage interface {
	Close() error
}

Storage manages the lifecycle of a shared storage backend.

func New(ctx context.Context, cfg Config) (Storage, error)

type WriteStamp ¶ added in v0.2.2

type WriteStamp struct {
	WriterID  string `bson:"writer_id,omitempty"`
	WrittenAt int64  `bson:"written_at,omitempty"`
}

WriteStamp marks the batch write that persisted an audit or usage entry: the writing process (WriterID) and its clock in unix microseconds. Entries carry a pointer to it so an unstamped entry costs one word; the MongoDB stores inline it as the writer_id and written_at fields.

func (s *WriteStamp) SQLValues() (writerID, writtenAt any)