Documentation
¶
Index ¶
- Variables
- func CoerceBool(v any) (any, error)
- func CoerceBoolValue(v any) (bool, error)
- func CoerceBytes(v any) (any, error)
- func CoerceBytesValue(v any) ([]byte, error)
- func CoerceEnumKeyMap[K ~uint8, V any](v any, parseKey func(string) (K, error)) (map[K]V, error)
- func CoerceEnumKeyMapAsAny[K ~uint8, V any](parseKey func(string) (K, error)) func(any) (any, error)
- func CoerceJSON[T any](v any) (any, error)
- func CoerceJSONValue[T any](v any) (T, error)
- func CoerceNumber[E Number](v any) (any, error)
- func CoerceNumberValue[E Number](v any) (E, error)
- func CoerceSlice[T any](v any, coerceElem func(any) (T, error)) ([]T, error)
- func CoerceSliceAsAny[T any](coerceElem func(any) (T, error)) func(any) (any, error)
- func CoerceString(v any) (any, error)
- func CoerceStringValue(v any) (string, error)
- func CoerceTime(v any) (any, error)
- func CoerceTimeValue(v any) (time.Time, error)
- func DialectKeysForEnv() []string
- func MustRegisterDefaultDialect(dialect Dialect)
- func MustRegisterDialect(name string, decoder DialectDecoder)
- func NewCheckError(table, constraint string, original error) error
- func NewForeignKeyError(table, constraint string, original error) error
- func NewMultipleRowsFoundError(original error) error
- func NewNoRowFoundError(original error) error
- func NewNotNullError(table, constraint string, original error) error
- func NewPermissionError(original error) error
- func NewScanError(original error) error
- func NewUnavailableError(original error) error
- func NewUnimplementedError(original error) error
- func NewUniqueError(table, constraint string, original error) error
- func NewUnknownError(original error) error
- func NullableValue[V any](p *V) any
- func RegisterDialect(name string, decoder DialectDecoder) error
- type AndFilter
- type ArrayContainsFilter
- type CheckError
- type Column
- type CompareFilter
- func Compare[F ~uint8](op CompareOp, terms ...CompareTerm[F]) *CompareFilter[F]
- func CompareEqual[F ~uint8](terms ...CompareTerm[F]) *CompareFilter[F]
- func CompareGreater[F ~uint8](terms ...CompareTerm[F]) *CompareFilter[F]
- func CompareLess[F ~uint8](terms ...CompareTerm[F]) *CompareFilter[F]
- func Equal[F ~uint8](column Column[F], value any) *CompareFilter[F]
- func GreaterThan[F ~uint8](column Column[F], value any) *CompareFilter[F]
- func GreaterThanOrEqual[F ~uint8](column Column[F], value any) *CompareFilter[F]
- func LessThan[F ~uint8](column Column[F], value any) *CompareFilter[F]
- type CompareOp
- type CompareTerm
- type Config
- type CorrelatedFilter
- type Dialect
- type DialectDecoder
- type Error
- func ErrCoerceEnumMapKey(key string, parent error) Error
- func ErrCoerceExpectedSlice(got any) Error
- func ErrCoerceExpectedType(want string, got any) Error
- func ErrCoerceParse(message string, parent error) Error
- func ErrCoerceSliceElement(index int, parent error) Error
- func ErrCursorLengthMismatch() Error
- func ErrCursorOrderMismatch() Error
- func ErrDecodeDialect(name string, parent error) Error
- func ErrDialectAlreadyRegistered(name string) Error
- func ErrInvalidCursor() Error
- func ErrInvalidDialectConfig(details any) Error
- func ErrInvalidEnumKey(key string) Error
- func ErrMissingFieldCoerce(field any) Error
- func ErrMultipleDialectsConfigured(count int, keys []string) Error
- func ErrNoDialectConfigured() Error
- func ErrUnsupportedDialect(name string) Error
- func NewError(code string, message string, details any, parent error) Error
- type FieldBinding
- type Filter
- type ForeignKeyError
- type Identity
- type IntegrityType
- type IntegrityViolationError
- type ListOptions
- type ListResult
- type MultipleRowsFoundError
- type NoRowFoundError
- type NotNullError
- type Number
- type OrFilter
- type OrderBy
- type OrderDirection
- type Page
- type PermissionError
- type Pool
- type ScanError
- type Schema
- func (s Schema[F, T]) CoerceCursorValues(cols []Column[F], raw []any) ([]any, error)
- func (s Schema[F, T]) ColumnNullability() map[string]bool
- func (s Schema[F, T]) MustSQLName(field F) string
- func (s Schema[F, T]) Nullable(col Column[F]) bool
- func (s Schema[F, T]) ParamCast(col Column[F]) string
- func (s Schema[F, T]) SQLName(col Column[F]) string
- func (s Schema[F, T]) SQLSuffix(col Column[F]) string
- func (s Schema[F, T]) ValuesFrom(entity *T, cols []Column[F]) []any
- type StringFilter
- func StringContains[F ~uint8](col Column[F], substr string) *StringFilter[F]
- func StringContainsFold[F ~uint8](col Column[F], substr string) *StringFilter[F]
- func StringEndsWith[F ~uint8](col Column[F], suffix string) *StringFilter[F]
- func StringEndsWithFold[F ~uint8](col Column[F], suffix string) *StringFilter[F]
- func StringEqual[F ~uint8](col Column[F], value string) *StringFilter[F]
- func StringEqualFold[F ~uint8](col Column[F], value string) *StringFilter[F]
- func StringStartsWith[F ~uint8](col Column[F], prefix string) *StringFilter[F]
- func StringStartsWithFold[F ~uint8](col Column[F], prefix string) *StringFilter[F]
- type StringMatch
- type UnavailableError
- type UnimplementedError
- type UniqueError
- type UnknownError
Constants ¶
This section is empty.
Variables ¶
var ErrNoChanges = errors.New("update must contain a change")
ErrNoChanges is returned when an Update is called with no updates.
Functions ¶
func CoerceBool ¶
CoerceBool coerces a JSON-decoded value into a bool for SQL binding.
func CoerceBoolValue ¶
CoerceBoolValue coerces a JSON-decoded value into a bool.
func CoerceBytes ¶
CoerceBytes coerces a JSON-decoded value into []byte for SQL binding.
func CoerceBytesValue ¶
CoerceBytesValue coerces a JSON-decoded value into []byte.
func CoerceEnumKeyMap ¶
CoerceEnumKeyMap coerces JSON-decoded map shapes into map[K]V with parsed enum keys.
func CoerceEnumKeyMapAsAny ¶
func CoerceEnumKeyMapAsAny[K ~uint8, V any](parseKey func(string) (K, error)) func(any) (any, error)
CoerceEnumKeyMapAsAny adapts CoerceEnumKeyMap for FieldBinding.Coerce.
func CoerceJSON ¶
CoerceJSON coerces a JSON-decoded value into T for SQL binding.
func CoerceJSONValue ¶
CoerceJSONValue coerces a JSON-decoded value into T via marshal/unmarshal when needed.
func CoerceNumber ¶
CoerceNumber coerces a JSON-decoded value into a uint8-based enum for SQL binding.
func CoerceNumberValue ¶
CoerceNumberValue coerces a JSON-decoded value into a uint8-based enum.
func CoerceSlice ¶
CoerceSlice converts JSON-decoded slice shapes into []T. It accepts []T (identity) or []any (coerce each element).
func CoerceSliceAsAny ¶
CoerceSliceAsAny adapts CoerceSlice for FieldBinding.Coerce.
func CoerceString ¶
CoerceString coerces a JSON-decoded value into a string for SQL binding. JSON null becomes Go nil so nullable strings bind as SQL NULL.
func CoerceStringValue ¶
CoerceStringValue coerces a JSON-decoded value into a string.
func CoerceTime ¶
CoerceTime coerces a JSON-decoded value into a time.Time for SQL binding. JSON null becomes Go nil so nullable timestamps bind as SQL NULL.
func CoerceTimeValue ¶
CoerceTimeValue coerces a JSON-decoded value into a time.Time.
func DialectKeysForEnv ¶
func DialectKeysForEnv() []string
func MustRegisterDefaultDialect ¶
func MustRegisterDefaultDialect(dialect Dialect)
func MustRegisterDialect ¶
func MustRegisterDialect(name string, decoder DialectDecoder)
func NewCheckError ¶
func NewForeignKeyError ¶
func NewNoRowFoundError ¶
func NewNotNullError ¶
func NewPermissionError ¶
func NewScanError ¶
func NewUnavailableError ¶
func NewUnimplementedError ¶
func NewUniqueError ¶
func NewUnknownError ¶
func NullableValue ¶
NullableValue flattens a nil pointer to untyped nil so it binds as SQL NULL. Returning *p directly would box a typed nil that fails == nil checks.
func RegisterDialect ¶
func RegisterDialect(name string, decoder DialectDecoder) error
Types ¶
type ArrayContainsFilter ¶
ArrayContainsFilter matches when a SQL array column contains Value. Dialects compile this differently (Postgres ANY / Spanner UNNEST).
func ArrayContains ¶
func ArrayContains[F ~uint8](col Column[F], value any) *ArrayContainsFilter[F]
ArrayContains matches when the array column contains value.
type CheckError ¶
type CheckError struct {
IntegrityViolationError
}
CheckError is returned when a check constraint fails.
func (*CheckError) Is ¶
func (e *CheckError) Is(target error) bool
func (*CheckError) Unwrap ¶
func (e *CheckError) Unwrap() error
type Column ¶
type Column[F ~uint8] struct { // contains filtered or unexported fields }
Column identifies an entity field in portable filter, order-by, and cursor operations. F is the domain field enum for a single entity type.
func (Column[F]) Field ¶
func (c Column[F]) Field() F
Field returns the underlying domain field enum value.
func (Column[F]) MarshalJSON ¶
MarshalJSON encodes the column as its underlying uint8 field value.
func (*Column[F]) UnmarshalJSON ¶
UnmarshalJSON decodes a uint8 field value into the typed column.
type CompareFilter ¶
type CompareFilter[F ~uint8] struct { Op CompareOp Terms []CompareTerm[F] // Keyset marks cursor predicates built from OrderBy columns. Ordered // keyset compares over nullable columns must admit NULL rows beyond the // cursor; plain range filters keep standard SQL semantics and exclude NULL. Keyset bool }
func Compare ¶
func Compare[F ~uint8](op CompareOp, terms ...CompareTerm[F]) *CompareFilter[F]
Compare builds a comparison filter across one or more column/value terms.
A single term compares one column. Multiple terms compare lexicographically: the first term decides, and later terms only break ties. The SQL for that is dialect-specific, because GoogleSQL has no ordering over structs and so cannot use the row-value form postgres emits. Term order must match the corresponding OrderBy.Columns when used for keyset pagination.
func CompareEqual ¶
func CompareEqual[F ~uint8](terms ...CompareTerm[F]) *CompareFilter[F]
CompareEqual creates a tuple equality filter: every term must match. With one term this is equivalent to Equal.
func CompareGreater ¶
func CompareGreater[F ~uint8](terms ...CompareTerm[F]) *CompareFilter[F]
CompareGreater creates a greater-than filter for keyset pagination. Pass one term per OrderBy column; for example, three terms restrict rows after the cursor position in (col1, col2, col3) sort order.
func CompareLess ¶
func CompareLess[F ~uint8](terms ...CompareTerm[F]) *CompareFilter[F]
CompareLess creates a less-than filter for keyset pagination. Pass one term per OrderBy column; term order must match OrderBy.Columns.
func Equal ¶
func Equal[F ~uint8](column Column[F], value any) *CompareFilter[F]
Equal creates a single-column equality filter: "column = value".
func GreaterThan ¶
func GreaterThan[F ~uint8](column Column[F], value any) *CompareFilter[F]
GreaterThan creates a single-column greater-than filter: "column > value".
func GreaterThanOrEqual ¶
func GreaterThanOrEqual[F ~uint8](column Column[F], value any) *CompareFilter[F]
GreaterThanOrEqual creates a single-column inclusive lower-bound filter: "column >= value".
type CompareTerm ¶
type CorrelatedFilter ¶
type CorrelatedFilter[F ~uint8] struct { }
CorrelatedFilter matches rows for which the column's correlated predicate holds for Value. Unlike the other filters, the bound value lands *inside* the column's SQL: the binding is a FieldBinding.Computed expression split around it, so dialects compile SQLName, the value, then SQLSuffix.
It exists for predicates that reach another table and take a parameter — "this session's user is owned by team X" — which the fixed value-after-column shape of CompareFilter and ArrayContainsFilter cannot express.
func CorrelatedEqual ¶
func CorrelatedEqual[F ~uint8](col Column[F], value any) *CorrelatedFilter[F]
CorrelatedEqual matches when col's correlated predicate holds for value.
type Dialect ¶
type Dialect interface {
// Name returns the name of the dialect. e.g. "postgres", "mysql", "sqlite".
Name() string
// Connect creates a new connection pool for the dialect.
// The returned pool should be ready to use and connected to the database.
Connect(ctx context.Context) (Pool, error)
}
Dialect is a database dialect. e.g. postgres, mysql, sqlite.
type DialectDecoder ¶
type Error ¶
Error is a coded storage error. Services map it to domain.Error at the boundary.
func ErrCoerceEnumMapKey ¶
func ErrCoerceExpectedSlice ¶
func ErrCoerceExpectedType ¶
func ErrCoerceParse ¶
func ErrCoerceSliceElement ¶
func ErrCursorLengthMismatch ¶
func ErrCursorLengthMismatch() Error
func ErrCursorOrderMismatch ¶
func ErrCursorOrderMismatch() Error
func ErrDecodeDialect ¶
func ErrInvalidCursor ¶
func ErrInvalidCursor() Error
func ErrInvalidDialectConfig ¶
func ErrInvalidEnumKey ¶
func ErrMissingFieldCoerce ¶
func ErrNoDialectConfigured ¶
func ErrNoDialectConfigured() Error
func ErrUnsupportedDialect ¶
func (Error) WithParent ¶
WithParent returns a copy wrapping a lower-level cause. Code is unchanged so errors.Is still matches the original sentinel.
type FieldBinding ¶
type FieldBinding[T any] struct { SQLName string Accessor func(*T) any Coerce func(any) (any, error) // ParamCast is an optional Postgres type cast appended after bound // placeholders for this column (e.g. "::myschema.my_enum"). Empty means // no cast. Spanner ignores this field. ParamCast string // Nullable marks columns that can hold SQL NULL. Keyset compares over // nullable columns need null-aware SQL, and ORDER BY states their NULL // position explicitly (ASC NULLS FIRST / DESC NULLS LAST on every dialect). Nullable bool // Computed marks SQLName as a SQL expression rather than a column // reference, so it has no DDL nullability of its own. Computed bool // SQLSuffix closes a Computed expression that binds its value inline: // [CorrelatedEqual] writes SQLName, the bound value, then SQLSuffix. It // lets a correlated sub-query take a parameter, which the fixed // value-after-column shape of the other filters cannot express. Only // meaningful together with Computed. SQLSuffix string }
FieldBinding maps a domain field to its SQL column name and entity accessor.
type ForeignKeyError ¶
type ForeignKeyError struct {
IntegrityViolationError
}
ForeignKeyError is returned when a foreign key constraint fails.
func (*ForeignKeyError) Is ¶
func (e *ForeignKeyError) Is(target error) bool
func (*ForeignKeyError) Unwrap ¶
func (e *ForeignKeyError) Unwrap() error
type Identity ¶
type Identity string
Identity is a string resource identifier for SQL bind/scan helpers. Resource primary keys are dialect-minted prefixed opaque strings (ADR 047) stored as TEXT / STRING(MAX).
func (*Identity) DecodeSpanner ¶
DecodeSpanner implements the Cloud Spanner client's spanner.Decoder interface (structurally, without importing the spanner package).
type IntegrityType ¶
type IntegrityType string
const ( IntegrityTypeCheck IntegrityType = "check" IntegrityTypeUnique IntegrityType = "unique" IntegrityTypeForeign IntegrityType = "foreign" IntegrityTypeNotNull IntegrityType = "not null" )
type IntegrityViolationError ¶
type IntegrityViolationError struct {
// contains filtered or unexported fields
}
IntegrityViolationError represents a generic integrity violation error. It wraps the dialect specific original error to provide more context.
func (*IntegrityViolationError) Constraint ¶
func (e *IntegrityViolationError) Constraint() string
func (*IntegrityViolationError) Error ¶
func (e *IntegrityViolationError) Error() string
func (*IntegrityViolationError) Is ¶
func (e *IntegrityViolationError) Is(target error) bool
func (*IntegrityViolationError) Unwrap ¶
func (e *IntegrityViolationError) Unwrap() error
type ListOptions ¶
type ListResult ¶
func (*ListResult[T]) Iterate ¶
func (l *ListResult[T]) Iterate(fetchNext func(cursor []byte) (*ListResult[T], error)) iter.Seq2[T, error]
Iterate returns a sequence over all items across every page. It starts with the items already held by l and calls fetchNext with the previous page's NextCursor to load subsequent pages, stopping once a page reports an empty NextCursor.
If fetchNext returns an error, the sequence yields the zero value together with that error once and then stops. Callers should therefore check the error on each iteration:
for key, err := range result.Iterate(fetchNext) {
if err != nil {
// handle and break
}
// use key
}
type MultipleRowsFoundError ¶
type MultipleRowsFoundError struct {
// contains filtered or unexported fields
}
MultipleRowsFoundError is returned when QueryRow finds multiple rows. It wraps the dialect specific original error to provide more context.
func (*MultipleRowsFoundError) Error ¶
func (e *MultipleRowsFoundError) Error() string
func (*MultipleRowsFoundError) Is ¶
func (e *MultipleRowsFoundError) Is(target error) bool
func (*MultipleRowsFoundError) Unwrap ¶
func (e *MultipleRowsFoundError) Unwrap() error
type NoRowFoundError ¶
type NoRowFoundError struct {
// contains filtered or unexported fields
}
NoRowFoundError is returned when QueryRow does not find any row. It wraps the dialect specific original error to provide more context.
func (*NoRowFoundError) Error ¶
func (e *NoRowFoundError) Error() string
func (*NoRowFoundError) Is ¶
func (e *NoRowFoundError) Is(target error) bool
func (*NoRowFoundError) Unwrap ¶
func (e *NoRowFoundError) Unwrap() error
type NotNullError ¶
type NotNullError struct {
IntegrityViolationError
}
NotNullError is returned when a not null constraint fails.
func (*NotNullError) Is ¶
func (e *NotNullError) Is(target error) bool
func (*NotNullError) Unwrap ¶
func (e *NotNullError) Unwrap() error
type Number ¶
type Number interface {
constraints.Float | constraints.Integer | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64
}
type OrderBy ¶
type OrderBy[F ~uint8] struct { Columns []Column[F] Direction OrderDirection }
type Page ¶
type Page[F ~uint8] struct { // Limit is the maximum number of items to return. If Limit is 0, no limit is applied. Limit uint32 // OrderBy is the order in which to return the items. OrderBy OrderBy[F] // Cursor is the cursor to start the page from. If Cursor is nil, the page starts from the beginning. Cursor []byte }
type PermissionError ¶
type PermissionError struct {
// contains filtered or unexported fields
}
func (*PermissionError) Error ¶
func (e *PermissionError) Error() string
func (*PermissionError) Is ¶
func (e *PermissionError) Is(target error) bool
func (*PermissionError) Unwrap ¶
func (e *PermissionError) Unwrap() error
type Pool ¶
type Pool interface {
Close(ctx context.Context) error
Ping(ctx context.Context) error
// Migrate applies all pending database migrations. It is expected to be
// safe to call concurrently: implementations should serialize migration
// execution and run it once per process (and/or per database).
Migrate(ctx context.Context) error
}
type ScanError ¶
type ScanError struct {
// contains filtered or unexported fields
}
ScanError is returned when scanning rows into objects failed.
type Schema ¶
Schema resolves domain fields to SQL names and entity values for one entity type.
func NewSchema ¶
func NewSchema[F ~uint8, T any](bindings map[F]FieldBinding[T]) Schema[F, T]
NewSchema constructs a schema from per-field bindings. Every bindable field for list/filter/order operations must be present; unspecified enum values must not.
func (Schema[F, T]) CoerceCursorValues ¶
CoerceCursorValues restores JSON-decoded cursor values to SQL bind types.
func (Schema[F, T]) ColumnNullability ¶
ColumnNullability returns the Nullable flag per bound SQL column name, skipping computed bindings, which name no column.
func (Schema[F, T]) MustSQLName ¶
MustSQLName returns the SQL column name for field.
func (Schema[F, T]) SQLSuffix ¶
SQLSuffix returns the SQL that closes col's inline-bound computed expression.
func (Schema[F, T]) ValuesFrom ¶
ValuesFrom reads cursor values from entity for the given columns.
type StringFilter ¶
type StringFilter[F ~uint8] struct { Column Column[F] Match StringMatch Value string IgnoreCase bool }
func StringContains ¶
func StringContains[F ~uint8](col Column[F], substr string) *StringFilter[F]
StringContains matches when the column value contains substr.
func StringContainsFold ¶
func StringContainsFold[F ~uint8](col Column[F], substr string) *StringFilter[F]
StringContainsFold matches when the column value contains substr, ignoring case.
func StringEndsWith ¶
func StringEndsWith[F ~uint8](col Column[F], suffix string) *StringFilter[F]
StringEndsWith matches when the column value ends with suffix.
func StringEndsWithFold ¶
func StringEndsWithFold[F ~uint8](col Column[F], suffix string) *StringFilter[F]
StringEndsWithFold matches when the column value ends with suffix, ignoring case.
func StringEqual ¶
func StringEqual[F ~uint8](col Column[F], value string) *StringFilter[F]
StringEqual matches a string column with exact equality.
func StringEqualFold ¶
func StringEqualFold[F ~uint8](col Column[F], value string) *StringFilter[F]
StringEqualFold matches a string column with case-insensitive equality.
func StringStartsWith ¶
func StringStartsWith[F ~uint8](col Column[F], prefix string) *StringFilter[F]
StringStartsWith matches when the column value starts with prefix.
func StringStartsWithFold ¶
func StringStartsWithFold[F ~uint8](col Column[F], prefix string) *StringFilter[F]
StringStartsWithFold matches when the column value starts with prefix, ignoring case.
type StringMatch ¶
type StringMatch uint8
const ( StringMatchEqual StringMatch = iota StringMatchStartsWith StringMatchContains StringMatchEndsWith )
type UnavailableError ¶
type UnavailableError struct {
// contains filtered or unexported fields
}
UnavailableError is returned when the database could not complete an operation for a transient reason and the caller may retry: a transaction that exhausted its abort retries under contention, a deadline reached while retrying, a backend that went away. Distinct from UnknownError, which the caller has no reason to retry.
Unwrap must keep returning the original: on Spanner the dialect wraps errors that are still inside a retrying transaction, and ReadWriteTransaction only retries while it can still find the gRPC status on the error (#788).
func (*UnavailableError) Error ¶
func (e *UnavailableError) Error() string
func (*UnavailableError) Is ¶
func (e *UnavailableError) Is(target error) bool
func (*UnavailableError) Unwrap ¶
func (e *UnavailableError) Unwrap() error
type UnimplementedError ¶
type UnimplementedError struct {
// contains filtered or unexported fields
}
UnimplementedError is returned when a storage operation is not implemented for the active dialect.
func (*UnimplementedError) Error ¶
func (e *UnimplementedError) Error() string
func (*UnimplementedError) Is ¶
func (e *UnimplementedError) Is(target error) bool
func (*UnimplementedError) Unwrap ¶
func (e *UnimplementedError) Unwrap() error
type UniqueError ¶
type UniqueError struct {
IntegrityViolationError
}
UniqueError is returned when a unique constraint fails.
func (*UniqueError) Is ¶
func (e *UniqueError) Is(target error) bool
func (*UniqueError) Unwrap ¶
func (e *UniqueError) Unwrap() error
type UnknownError ¶
type UnknownError struct {
// contains filtered or unexported fields
}
UnknownError is returned when an unknown error occurs.
func (*UnknownError) Error ¶
func (e *UnknownError) Error() string
func (*UnknownError) Is ¶
func (e *UnknownError) Is(target error) bool
func (*UnknownError) Unwrap ¶
func (e *UnknownError) Unwrap() error