Documentation
¶
Overview ¶
Package database opens supported GORM SQL drivers and exposes driver metadata.
MapLoadError and MapPersistError classify GORM errors into D10 categories (not_found, conflict, internal) so generated handlers, admin, and auth share one unique-violation detector instead of three copies.
Index ¶
- func FilterEq(ctx context.Context, q *gorm.DB, column string, kind FilterKind, raw string) (*gorm.DB, error)
- func IsForeignKeyViolation(err error) bool
- func IsNotNullViolation(err error) bool
- func IsUniqueViolation(err error) bool
- func MapDeleteError(ctx context.Context, err error, conflict, internal string) error
- func MapLoadError(ctx context.Context, err error, notFound, internal string) error
- func MapPersistError(ctx context.Context, err error, conflict, internal string) error
- func Ordering(ctx context.Context, q *gorm.DB, ordering string, allowed []string, ...) (*gorm.DB, error)
- func ParseOrdering(ordering string) (field string, desc bool)
- func Search(q *gorm.DB, columns []string, term string) *gorm.DB
- type Capabilities
- type DB
- type Driver
- type FilterKind
- type ValidationError
- type Validator
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FilterEq ¶ added in v0.1.11
func FilterEq(ctx context.Context, q *gorm.DB, column string, kind FilterKind, raw string) (*gorm.DB, error)
FilterEq adds an exact-match `column = <raw coerced to kind>` predicate. An empty (or whitespace-only) raw value is a no-op — the filter was not supplied — so callers can chain one FilterEq per declared filterable field. A raw value that does not parse as kind returns a D10 validation error (422) keyed on column. The column name is generator-controlled (a declared field's DB column); only raw is user input.
func IsForeignKeyViolation ¶ added in v0.1.5
IsForeignKeyViolation reports foreign-key constraint violations, such as a belongs_to reference to a row that does not exist. Same primary/fallback shape as IsUniqueViolation: all three supported dialectors translate their foreign-key error code to gorm.ErrForeignKeyViolated, with the driver error string as a fallback.
func IsNotNullViolation ¶ added in v0.1.5
IsNotNullViolation reports NOT NULL constraint violations. Unlike unique and foreign-key violations, none of the SQLite/Postgres/MySQL GORM dialectors translate this case to a gorm sentinel error (it is a gap in gorm itself, not something Open configures around), so detection is driver-message-only. The three drivers phrase it differently: SQLite ("NOT NULL constraint failed"), Postgres ("violates not-null constraint"), MySQL ("cannot be null").
func IsUniqueViolation ¶ added in v0.1.3
IsUniqueViolation reports duplicate-key errors. Open enables gorm.Config.TranslateError, so ErrDuplicatedKey is the primary signal on SQLite, Postgres, and MySQL (all three dialectors translate their unique- violation error code to it). The driver error string stays as a fallback for any dialect that does not implement translation.
func MapDeleteError ¶ added in v0.1.5
MapDeleteError maps a GORM delete error to a D10 category error. A foreign-key violation here means another row still references the one being deleted, which is a state conflict caused by other data, not an invalid value in the request (a delete has no body to validate) — the opposite meaning a foreign-key violation has on create/update, so this is deliberately not MapPersistError. Unique and NOT NULL violations cannot occur on delete, so there is no equivalent branch for them here.
func MapLoadError ¶ added in v0.1.3
MapLoadError maps a GORM read/load error to a D10 category error: record-not-found becomes not_found; any other driver failure becomes internal. Unique/duplicate is not treated as conflict on load.
func MapPersistError ¶ added in v0.1.3
MapPersistError maps a GORM write error to a D10 category error: unique/duplicate becomes conflict; a foreign-key or NOT NULL violation becomes validation, since both mean the client submitted a value that references or omits something invalid, not that the server failed; any other failure becomes internal.
func Ordering ¶ added in v0.1.11
func Ordering(ctx context.Context, q *gorm.DB, ordering string, allowed []string, fallback string) (*gorm.DB, error)
Ordering applies `ORDER BY` for a Django-style `?ordering=` value (optional leading '-' for DESC), validated against the allowed columns:
- empty ordering: order by fallback (the stable default, e.g. "id") when fallback is non-empty; otherwise no ORDER BY is added.
- ordering field not in allowed: a 422 validation error on "ordering".
allowed and fallback are generator-controlled (a resource's declared sortable columns); ordering is user input, matched by exact string equality so only a declared column can reach the query.
func ParseOrdering ¶ added in v0.1.11
ParseOrdering splits a Django-style `?ordering=` token into its field name and direction: a leading '-' means descending, e.g. "-created_at" → ("created_at", true). The admin data plane and generated list handlers share this spelling so the two contracts cannot drift.
func Search ¶ added in v0.1.11
Search adds a case-insensitive OR of `LOWER(col) LIKE LOWER(%term%)` across the given columns. An empty (or whitespace-only) term, or an empty column list, is a no-op. The term is treated as a literal: LIKE wildcards in it are escaped, so a user searching for "50%" matches the literal text, not a prefix. Columns are generator-controlled; only the term is user input.
Types ¶
type Capabilities ¶
type Capabilities struct {
Transactions bool
Savepoints bool
ForeignKeyConstraints bool
Returning bool
Upsert bool
AdvisoryLocks bool
ConcurrentIndexBuilds bool
}
Capabilities names behavior that differs across supported database drivers.
func CapabilitiesFor ¶
func CapabilitiesFor(driver Driver) Capabilities
CapabilitiesFor returns the capability model for driver.
type DB ¶
DB is an opened GORM database with Gombit driver metadata.
func Open ¶
func Open(cfg config.DatabaseConfig) (*DB, error)
Open opens a GORM database for a supported config.DatabaseConfig.
func (*DB) Capabilities ¶
func (db *DB) Capabilities() Capabilities
Capabilities returns the configured driver's capability flags.
type Driver ¶
type Driver string
Driver names a supported database driver.
const ( // DriverSQLite identifies SQLite. DriverSQLite Driver = Driver(config.DatabaseDriverSQLite) // DriverPostgres identifies PostgreSQL. DriverPostgres Driver = Driver(config.DatabaseDriverPostgres) // DriverMySQL identifies MySQL. DriverMySQL Driver = Driver(config.DatabaseDriverMySQL) )
type FilterKind ¶ added in v0.1.11
type FilterKind int
FilterKind is the column type an exact-match filter coerces its raw query string to before comparing. Filters arrive as strings (Huma does not support optional/pointer query params, so an empty string is the "absent" signal — the same convention the admin data plane uses), and the kind decides how the string is parsed and bound.
const ( FilterString FilterKind = iota FilterInt FilterInt64 FilterUint FilterBool )
type ValidationError ¶ added in v0.1.7
ValidationError is a domain validation failure raised by a model's Validate hook. MapPersistError maps it to a D10 422 validation_error, preserving the per-field messages.
func NewValidationError ¶ added in v0.1.7
func NewValidationError(message string, fields map[string][]string) *ValidationError
NewValidationError builds a domain ValidationError. Pass nil fields for a message-only error.
func (*ValidationError) Error ¶ added in v0.1.7
func (e *ValidationError) Error() string
Error satisfies the error interface.
type Validator ¶ added in v0.1.7
Validator is implemented by models that enforce domain invariants — rules that cross fields, rows, or models, such as "ownership windows must not overlap" or "confirm a rental only if every child resource is available".
The framework runs Validate inside the write transaction on BOTH the API (generated handler Create/Save) and the admin data-plane write paths, via a GORM callback registered in Open. An invariant therefore has exactly one home and neither write surface can bypass it. tx is the transaction the write runs in, so Validate can query committed-but-in-flight state consistently.
Return a *ValidationError (see NewValidationError) to surface field-level D10 422 responses; any other error aborts the write and maps to 500.
Source Files
Directories