database

Documentation

Index

• Variables
• type Dialect
  • func MySQLDialect() Dialect
  • func PostgresDialect() Dialect
  • func SQLiteDialect() Dialect
• type Driver
• type DriverRegistry
  • func NewDriverRegistry() *DriverRegistry
  • func (r *DriverRegistry) Get(name string) (Driver, error)
  • func (r *DriverRegistry) Names() []string
  • func (r *DriverRegistry) Register(driver Driver) error
• type OpenOptions
• type UnknownDriverError
  • func (e *UnknownDriverError) Error() string

Variables

var (
	ErrDuplicateDriver = errors.New("kernel: duplicate database driver")
	ErrEmptyUpsertKeys = errors.New("kernel: upsert requires at least one key column")
)

Types

type Dialect

type Dialect interface {
	// Name is the migration subdir and registry key ("sqlite", ...).
	Name() string
	// Placeholder renders the bind placeholder for the 0-based parameter
	// index ("?" on SQLite/MySQL, "$N" with N=index+1 on PostgreSQL).
	Placeholder(index int) string
	// SupportsReturning reports whether INSERT/UPDATE ... RETURNING works.
	SupportsReturning() bool
	// Upsert renders an insert-or-update statement for the given table,
	// conflict key columns, and value columns. Empty keyColumns fails with
	// ErrEmptyUpsertKeys — every dialect needs a conflict target.
	Upsert(table string, keyColumns, valueColumns []string) (string, error)
	// IsDuplicateError reports whether err is a unique-constraint violation
	// (duplicate key entry) on this driver. Stores map it to domain
	// duplicate sentinels instead of generic persistence errors.
	IsDuplicateError(err error) bool
}

Dialect abstracts the SQL differences between drivers so module repositories stay single-source: one implementation against *sql.DB plus this shim, with per-dialect escapes only where SQL truly diverges.

Table and column names are trusted identifiers (schema-defined, never user input): Upsert interpolates them verbatim.

func MySQLDialect

func MySQLDialect() Dialect

MySQLDialect returns the MySQL dialect.

func PostgresDialect

func PostgresDialect() Dialect

PostgresDialect returns the PostgreSQL dialect.

func SQLiteDialect

func SQLiteDialect() Dialect

SQLiteDialect returns the SQLite dialect.

type Driver

type Driver interface {
	// Name matches DB_DRIVER values ("sqlite", "postgres", "mysql").
	Name() string
	Open(dsn string, opts OpenOptions) (*sql.DB, error)
	Dialect() Dialect
	// MigrationDir is the subdir inside every module's migration FS
	// holding this driver's files.
	MigrationDir() string
}

Driver opens a database and describes its SQL dialect. One implementation exists per supported database (sqlite, postgresql, mysql).

type DriverRegistry

type DriverRegistry struct {
	// contains filtered or unexported fields
}

DriverRegistry maps driver names to implementations. DB_DRIVER selects an entry; an unknown name fails with UnknownDriverError.

func NewDriverRegistry

func NewDriverRegistry() *DriverRegistry

NewDriverRegistry creates an empty driver registry.

func (*DriverRegistry) Get

func (r *DriverRegistry) Get(name string) (Driver, error)

Get returns the driver for name, or UnknownDriverError listing installed drivers when the name was not compiled in.

func (*DriverRegistry) Names

func (r *DriverRegistry) Names() []string

Names returns every registered driver name in sorted order.

func (*DriverRegistry) Register

func (r *DriverRegistry) Register(driver Driver) error

Register adds a driver under its Name. Duplicates are rejected.

type OpenOptions

type OpenOptions struct {
	MaxOpenConns int
}

OpenOptions tunes Driver.Open. MaxOpenConns configures the pool for server databases; embedded drivers ignore it.

type UnknownDriverError

type UnknownDriverError struct {
	Name      string
	Installed []string
}

UnknownDriverError is returned when DB_DRIVER names a driver that was not compiled in. It lists installed drivers so the fix is obvious ("did you forget to import the driver module?").

func (*UnknownDriverError) Error

func (e *UnknownDriverError) Error() string