dialect

Documentation

Overview

Package dialect holds the per-database adaptors used by the lookup direct backend. An adaptor supplies only what differs between databases (placeholders, quoting, booleans, time and JSON handling, insert-returning-id); the backend builds queries from it. It imports only the standard library.

Index

• func Names() []string
• func Register(name string, f Factory)
• type Dialect
  • func Detect(db *sql.DB) (Dialect, error)
  • func DetectDriver(driver string) (Dialect, error)
  • func Get(name string) (Dialect, error)
• type Factory
• type Insert
  • func (i Insert) Run(ctx context.Context, q Querier, args ...any) (int64, error)
• type InsertStrategy
• type Querier

Functions

func Names

func Names() []string

Names lists the registered dialect names, sorted.

func Register

func Register(name string, f Factory)

Register adds a dialect under name. Registering a name twice replaces it, so applications can override a built-in. Adding a database = implementing Dialect and calling Register.

Types

type Dialect

type Dialect interface {
	// Name is the registry name, e.g. "postgres".
	Name() string
	// Matches reports whether a driver type identifier (lowercased "<pkgpath>.<Type>")
	// belongs to this database. Used by Detect.
	Matches(driver string) bool
	// Placeholder returns the bind placeholder for the n-th (1-based) argument.
	Placeholder(n int) string
	// Quote quotes an identifier. A dotted name is quoted per part ("schema.table").
	// Embedded quote characters are escaped, never interpolated raw.
	Quote(ident string) string
	// Bool converts a Go bool to the value bound as a boolean column argument.
	Bool(v bool) any
	// ScanBool reads a boolean column value that the driver returned as bool, integer, string or bytes.
	ScanBool(src any) (bool, error)
	// ScanTime reads a time column value that the driver returned as time.Time, string or bytes.
	// NULL (nil) yields the zero time.
	ScanTime(src any) (time.Time, error)
	// EncodeJSON converts a value to the argument bound to a JSON/TEXT column. A nil
	// value, map or slice yields nil (SQL NULL).
	EncodeJSON(v any) (any, error)
	// DecodeJSON reads a JSON/TEXT column value into dst. NULL and empty values leave dst untouched.
	DecodeJSON(src any, dst any) error
	// InsertReturningID builds an INSERT of cols into table and describes how to read the new id.
	// Arguments are bound positionally in cols order.
	InsertReturningID(table string, cols []string, idCol string) Insert
}

Dialect is the adaptor for one database type.

func Detect

func Detect(db *sql.DB) (Dialect, error)

Detect picks the dialect for db from its driver type.

func DetectDriver

func DetectDriver(driver string) (Dialect, error)

DetectDriver picks the dialect for a driver type identifier (see Dialect.Matches).

func Get

func Get(name string) (Dialect, error)

Get returns the dialect registered under name.

type Factory

type Factory func() Dialect

Factory creates a Dialect.

type Insert

type Insert struct {
	SQL      string
	Strategy InsertStrategy
}

Insert is a generated INSERT statement and how to read the id it creates.

func (Insert) Run

func (i Insert) Run(ctx context.Context, q Querier, args ...any) (int64, error)

Run executes the insert and returns the generated id.

type InsertStrategy

type InsertStrategy int

InsertStrategy tells how the generated id is read after an Insert.

const (
	// ReturningQuery means the statement returns the id as a single row (QueryRow + Scan).
	ReturningQuery InsertStrategy = iota
	// LastInsertID means the id is read from sql.Result.LastInsertId after Exec.
	LastInsertID
)

type Querier

type Querier interface {
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
}

Querier is implemented by *sql.DB, *sql.Tx and *sql.Conn.