Documentation
¶
Overview ¶
Package database owns every PostgreSQL connection and transaction in OpsGrid. It is the only package allowed to begin a transaction (enforced by lint), which guarantees that tenant-owned tables are only ever touched with a transaction-local tenant context (ADR-004).
Index ¶
- Constants
- Variables
- func ConstraintName(err error) string
- func IsExclusionViolation(err error, constraint string) bool
- func IsForeignKeyViolation(err error, constraint string) bool
- func IsNoRows(err error) bool
- func IsRetryable(err error) bool
- func IsUniqueViolation(err error, constraint string) bool
- func SQLState(err error) string
- type DB
- func (d *DB) CheckMigrations(ctx context.Context) error
- func (d *DB) Close()
- func (d *DB) InSystemTx(ctx context.Context, fn TxFunc) error
- func (d *DB) InTenantTx(ctx context.Context, s Scope, fn TxFunc) error
- func (d *DB) InUserTx(ctx context.Context, userID uuid.UUID, fn TxFunc) error
- func (d *DB) MigrationVersion(ctx context.Context) (int64, error)
- func (d *DB) Ping(ctx context.Context) error
- type Migrator
- type Options
- type Scope
- type TxFunc
Constants ¶
const ( SQLStateUniqueViolation = "23505" SQLStateForeignKeyViolation = "23503" SQLStateCheckViolation = "23514" SQLStateExclusionViolation = "23P01" SQLStateNotNullViolation = "23502" SQLStateSerializationFailure = "40001" SQLStateDeadlockDetected = "40P01" SQLStateLockNotAvailable = "55P03" SQLStateQueryCanceled = "57014" // includes statement_timeout SQLStateInsufficientPriv = "42501" // includes RLS WITH CHECK violations )
SQLSTATE codes OpsGrid reacts to.
Variables ¶
var ErrMissingTenant = errors.New("database: tenant transaction requires an organization id")
ErrMissingTenant is returned when InTenantTx is called without an organization. It is a programming error and fails closed.
Functions ¶
func ConstraintName ¶
ConstraintName returns the violated constraint, or "".
func IsExclusionViolation ¶
IsExclusionViolation reports an exclusion-constraint violation (for example overlapping technician assignments).
func IsForeignKeyViolation ¶
IsForeignKeyViolation reports an FK violation (including composite tenant FKs that reject cross-organization references).
func IsRetryable ¶
IsRetryable reports whether a transaction failed in a way that is safe to retry from the beginning.
func IsUniqueViolation ¶
IsUniqueViolation reports a unique/PK violation, optionally on a specific constraint (empty matches any).
Types ¶
type DB ¶
type DB struct {
// contains filtered or unexported fields
}
DB wraps a pgx pool. Callers never receive the pool for tenant work; they use InTenantTx / InUserTx.
func (*DB) CheckMigrations ¶
CheckMigrations reports an error unless the database schema is exactly at the version embedded in this binary.
func (*DB) InSystemTx ¶
InSystemTx runs fn without any tenant or user context. Under RLS it can only see non-tenant tables; it exists for identity bootstrap (user upsert at login, session lookup by hash) and maintenance jobs.
func (*DB) InTenantTx ¶
InTenantTx runs fn in a READ COMMITTED transaction whose tenant context (app.organization_id, app.user_id) is set with set_config(..., true): it is scoped to this transaction and can never leak to the next borrower of the pooled connection.
func (*DB) InUserTx ¶
InUserTx runs fn with only app.user_id set. It is for pre-tenant lookups (sessions, the caller's own memberships) whose RLS policies key on the acting user rather than an organization.
func (*DB) MigrationVersion ¶
MigrationVersion returns the highest applied goose migration version.
type Migrator ¶
type Migrator struct {
// contains filtered or unexported fields
}
Migrator applies the embedded migrations. It must connect as opsgrid_migrator (the schema owner), never as a runtime role.
func NewMigrator ¶
NewMigrator opens a dedicated connection for migrations.
type Options ¶
type Options struct {
URL string
MaxConns int32
MinConns int32
MaxConnLifetime time.Duration
HealthCheckPeriod time.Duration
// ApplicationName appears in pg_stat_activity.
ApplicationName string
}
Options configures Open.
Source Files