database

Documentation

Index

• Variables
• type Collection
  • func Manage[E any](db *Database, model *E, opts ...ManageOption[E]) *Collection[E]
  • func (c *Collection[E]) All() ([]*E, error)
  • func (c *Collection[E]) Count(where string, args ...any) (int, error)
  • func (c *Collection[E]) DB() *Database
  • func (c *Collection[E]) Delete(entity *E) error
  • func (c *Collection[E]) DeleteByID(id string) error
  • func (c *Collection[E]) First(where string, args ...any) (*E, error)
  • func (c *Collection[E]) Get(id string) (*E, error)
  • func (c *Collection[E]) Insert(entity *E) (string, error)
  • func (c *Collection[E]) Search(where string, args ...any) ([]*E, error)
  • func (c *Collection[E]) Table() string
  • func (c *Collection[E]) Update(entity *E) error
• type Column
• type Database
  • func (db *Database) AddColumn(table string, col Column) error
  • func (db *Database) CreateTable(name string, columns []Column) error
  • func (db *Database) GenerateID() string
  • func (db *Database) GetColumns(table string) []string
  • func (db *Database) TableExists(name string) bool
  • func (db *Database) Transaction(fn func(tx *sql.Tx) error) error
• type ManageOption
  • func WithIndex[E any](columns ...string) ManageOption[E]
  • func WithUniqueIndex[E any](columns ...string) ManageOption[E]
• type Model
• type Syncer

Variables

var (
	// ErrNotFound is returned when a record doesn't exist
	ErrNotFound = errors.New("record not found")

	// ErrDuplicate is returned when a unique constraint is violated
	ErrDuplicate = errors.New("duplicate record")
)

Types

type Collection

type Collection[E any] struct {
	// contains filtered or unexported fields
}

Collection is a generic repository for type-safe CRUD operations.

func Manage

func Manage[E any](db *Database, model *E, opts ...ManageOption[E]) *Collection[E]

Manage creates a new Collection for the given entity type. The table name is derived from the struct name. Tables are automatically created if they don't exist, and missing columns are added.

func (*Collection[E]) All

func (c *Collection[E]) All() ([]*E, error)

All returns all entities in the collection

func (*Collection[E]) Count

func (c *Collection[E]) Count(where string, args ...any) (int, error)

Count returns the number of records matching the query.

func (*Collection[E]) DB

func (c *Collection[E]) DB() *Database

DB returns the underlying database connection

func (*Collection[E]) Delete

func (c *Collection[E]) Delete(entity *E) error

Delete removes a record

func (*Collection[E]) DeleteByID

func (c *Collection[E]) DeleteByID(id string) error

DeleteByID removes a record by ID without requiring a full entity. Returns ErrNotFound if no record with the given ID exists.

func (*Collection[E]) First

func (c *Collection[E]) First(where string, args ...any) (*E, error)

First returns the first entity matching the query

func (*Collection[E]) Get

func (c *Collection[E]) Get(id string) (*E, error)

Get retrieves an entity by ID

func (*Collection[E]) Insert

func (c *Collection[E]) Insert(entity *E) (string, error)

Insert creates a new record and returns the generated ID

func (*Collection[E]) Search

func (c *Collection[E]) Search(where string, args ...any) ([]*E, error)

Search returns all entities matching the query

func (*Collection[E]) Table

func (c *Collection[E]) Table() string

Table returns the table name

func (*Collection[E]) Update

func (c *Collection[E]) Update(entity *E) error

Update saves changes to an existing record

type Column

type Column struct {
	Name    string
	Type    string // SQL type: TEXT, INTEGER, REAL, DATETIME, BLOB
	Primary bool
	Default string // Default value as SQL literal: ”, 0, CURRENT_TIMESTAMP
}

Column describes a database column for table creation and migration.

type Database

type Database struct {
	*sql.DB
	Sync Syncer
}

Database wraps a sql.DB connection with its engine for lifecycle management. It embeds *sql.DB so all standard database methods are available directly.

func (*Database) AddColumn

func (db *Database) AddColumn(table string, col Column) error

AddColumn adds a column to an existing table with a default value. SQLite requires constant defaults for ALTER TABLE ADD COLUMN, so non-constant defaults like CURRENT_TIMESTAMP are replaced.

func (*Database) CreateTable

func (db *Database) CreateTable(name string, columns []Column) error

CreateTable creates a table with the given columns.

func (*Database) GenerateID

func (db *Database) GenerateID() string

GenerateID creates a new UUID string

func (*Database) GetColumns

func (db *Database) GetColumns(table string) []string

GetColumns returns the names of all columns in a table.

func (*Database) TableExists

func (db *Database) TableExists(name string) bool

TableExists checks if a table exists in the database.

func (*Database) Transaction

func (db *Database) Transaction(fn func(tx *sql.Tx) error) error

Transaction executes a function within a database transaction. If the function returns an error, the transaction is rolled back. If the function completes successfully, the transaction is committed.

type ManageOption

type ManageOption[E any] func(*Collection[E])

ManageOption configures a Collection during creation.

func WithIndex

func WithIndex[E any](columns ...string) ManageOption[E]

WithIndex creates a non-unique index on the specified columns. Panics on failure — this is a declarative startup-time operation.

func WithUniqueIndex

func WithUniqueIndex[E any](columns ...string) ManageOption[E]

WithUniqueIndex creates a unique index on the specified column(s). Pass multiple columns for a composite unique constraint (e.g., WithUniqueIndex("UserID", "TileID")). Panics on failure — this is a declarative startup-time operation.

type Model

type Model struct {
	ID        string
	CreatedAt time.Time
	UpdatedAt time.Time
}

Model is the base type for all database entities. Embed this in your structs to get ID, CreatedAt, and UpdatedAt fields.

IDs are auto-generated on Insert, timestamps are auto-set on Insert/Update.

type Syncer

type Syncer interface {
	Sync() error
}

Syncer is an optional interface for databases that support syncing with a remote.