schema

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 10, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package schema describes the Auth-All database schema independently from a specific database engine. Core and plugins contribute tables. A dialect renderer turns the effective schema into deterministic SQL.

Index

Constants

View Source
const (
	TableUsers        = DefaultPrefix + baseUsers
	TableCredentials  = DefaultPrefix + baseCredentials
	TableAccounts     = DefaultPrefix + baseAccounts
	TableSessions     = DefaultPrefix + baseSessions
	TableTokens       = DefaultPrefix + baseTokens
	TableOAuthStates  = DefaultPrefix + baseOAuthStates
	TableTOTP         = DefaultPrefix + baseTOTP
	TableTOTPRecovery = DefaultPrefix + baseTOTPRecovery
)

Core table names. They hold the v1 names, which the default prefix produces. A schema with another prefix uses Schema.Names instead.

View Source
const DefaultPrefix = "auth_"

DefaultPrefix is the prefix of every Auth-All object when the host sets no other value. It keeps the v1 names.

View Source
const MigrationTable = DefaultPrefix + baseMigrations

MigrationTable holds the applied statement IDs. It is the v1 name. A schema with another prefix uses Names().Migrations instead.

View Source
const OwnerCore = "core"

OwnerCore names the owner of the core migration units.

Variables

This section is empty.

Functions

This section is empty.

Types

type Column

type Column struct {
	Name       string
	Type       Type
	Nullable   bool
	PrimaryKey bool
	// Default is the rendered SQL default. An empty value adds no default.
	Default string
}

Column describes one column.

type Dialect

type Dialect string

Dialect selects the SQL flavor of a renderer.

const (
	Postgres Dialect = "postgres"
	SQLite   Dialect = "sqlite"
)

Supported dialects.

type Extension added in v0.3.0

type Extension struct {
	// Table is the physical name of the target table.
	Table string
	// Columns are the added columns. An added column is nullable, or it has a
	// default, because the target table can already hold rows.
	Columns []Column
	// Indexes are the added indexes.
	Indexes []Index
}

Extension adds columns and indexes to a table that another owner declared.

func (Extension) Validate added in v0.3.0

func (e Extension) Validate() error

Validate reports an unusable extension.

type ForeignKey

type ForeignKey struct {
	Column    string
	RefTable  string
	RefColumn string
	OnDelete  string // CASCADE or SET NULL. Empty means no action.
}

ForeignKey describes one foreign key constraint.

type IDType added in v0.3.0

type IDType string

IDType selects the physical type of every primary key and foreign key.

const (
	// IDText stores an identifier as text. This is the v1 behavior.
	IDText IDType = "text"
	// IDUUID stores an identifier as a PostgreSQL uuid. SQLite keeps text.
	IDUUID IDType = "uuid"
)

Supported identifier types.

type Index

type Index struct {
	Name    string
	Columns []string
	Unique  bool
}

Index describes one index.

type Names added in v0.3.0

type Names struct {
	Users        string
	Credentials  string
	Accounts     string
	Sessions     string
	Tokens       string
	OAuthStates  string
	TOTP         string
	TOTPRecovery string
	APIKeys      string
	RateLimits   string
	Bootstrap    string
	Migrations   string
}

Names holds the physical name of every Auth-All table.

func DefaultNames added in v0.3.0

func DefaultNames() Names

DefaultNames returns the v1 table names.

func TableNames added in v0.3.0

func TableNames(o Options) Names

TableNames returns the physical table names for the options.

type Options added in v0.3.0

type Options struct {
	// Prefix starts every table name, index name, and record table name.
	Prefix string
	// IDType selects the physical type of the identifier columns.
	IDType IDType
	// UserFields are host-owned columns on the users table.
	UserFields []UserField
}

Options configure the physical schema.

func DefaultOptions added in v0.3.0

func DefaultOptions() Options

DefaultOptions returns the v1 physical schema.

func (Options) Name added in v0.3.0

func (o Options) Name(base string) string

Name returns the physical name of one base object name.

func (Options) Normalize added in v0.3.0

func (o Options) Normalize() (Options, error)

Normalize fills the empty fields and reports an invalid option.

type Schema

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

Schema is the effective set of tables.

func New

func New() *Schema

New returns an empty schema with the default options.

func NewCore

func NewCore() (*Schema, error)

NewCore returns a schema that already contains the core tables with the v1 physical options.

func NewCoreWithOptions added in v0.3.0

func NewCoreWithOptions(o Options) (*Schema, error)

NewCoreWithOptions returns a schema that already contains the core tables for the given physical options.

func NewWithOptions added in v0.3.0

func NewWithOptions(o Options) (*Schema, error)

NewWithOptions returns an empty schema with the given physical options.

func (*Schema) Add

func (s *Schema) Add(t Table) error

Add registers a table. It reports an error when the name is already taken.

func (*Schema) AddUnit added in v0.3.0

func (s *Schema) AddUnit(u Unit) error

AddUnit registers one migration unit. A unit that creates a table must also name the table in Creates.

func (*Schema) Extend added in v0.3.0

func (s *Schema) Extend(e Extension) error

Extend adds columns and indexes to a table that another owner declared.

func (*Schema) Names added in v0.3.0

func (s *Schema) Names() Names

Names returns the physical table names of the schema.

func (*Schema) Options added in v0.3.0

func (s *Schema) Options() Options

Options returns the physical options of the schema.

func (*Schema) Table

func (s *Schema) Table(name string) (Table, bool)

Table returns one table by name.

func (*Schema) Tables

func (s *Schema) Tables() []Table

Tables returns every table sorted by name. The order is deterministic and does not depend on registration order.

func (*Schema) Units added in v0.3.0

func (s *Schema) Units() ([]Unit, error)

Units returns every migration unit in version order. A table that no unit covers gets a synthesized unit, so a third-party plugin that contributes only a table still exports a file.

type Statement

type Statement struct {
	ID  string
	SQL string
}

Statement is one identified DDL statement.

The ID is stable across runs and identifies the statement in the applied migration record.

func Render

func Render(d Dialect, s *Schema) ([]Statement, error)

Render returns the deterministic DDL for the schema in one dialect. The result is a pure function of the schema and needs no database connection.

type Table

type Table struct {
	Name        string
	Columns     []Column
	Indexes     []Index
	ForeignKeys []ForeignKey
}

Table describes one table.

func Core

func Core() []Table

Core returns the core Auth-All schema with the v1 physical options.

func CoreTables added in v0.3.0

func CoreTables(o Options) []Table

CoreTables returns the effective core Auth-All schema for the given physical options. It is the v1 tables plus every later core extension.

type Type

type Type string

Type is a database-independent column type.

const (
	TypeText      Type = "text"
	TypeTimestamp Type = "timestamp"
	TypeInt       Type = "int"
	TypeBool      Type = "bool"
	// TypeUUID is an identifier column. PostgreSQL uses uuid. SQLite uses
	// text, because SQLite has no uuid type.
	TypeUUID Type = "uuid"
)

Supported column types.

type Unit added in v0.3.0

type Unit struct {
	// Version is a 14-digit timestamp. It orders the units.
	Version string
	// Owner is OwnerCore or a plugin identifier.
	Owner string
	// Name is the unit name without the version.
	Name string
	// Up holds the forward statements of each dialect.
	Up map[Dialect][]Statement
	// Down holds the reverse statements of each dialect.
	Down map[Dialect][]Statement
	// Creates names the tables that the unit creates. The schema uses it to
	// find a table that no unit covers.
	Creates []string
}

Unit is one versioned and immutable set of DDL statements with one owner.

A released unit never changes. A later release adds a new unit instead, so a host that applied the earlier file keeps a valid database.

func CoreUnits added in v0.3.0

func CoreUnits(o Options) ([]Unit, error)

CoreUnits returns the core migration units in version order.

func TableUnit added in v0.3.0

func TableUnit(version, owner, name string, d []Dialect, tables []Table) (Unit, error)

TableUnit returns one unit that creates the given tables.

func UnitsFor added in v0.3.0

func UnitsFor(o Options, extra []Unit) ([]Unit, error)

UnitsFor returns the core units and one unit for each extra table that a plugin contributed. The units are sorted by version.

func (Unit) FileName added in v0.3.0

func (u Unit) FileName() string

FileName returns the version and the name, for example 20260101000000_authall_core.

type UserField added in v0.3.0

type UserField struct {
	// Name is the column name.
	Name string
	// Type is the column type.
	Type Type
	// Nullable allows a null value.
	Nullable bool
	// Default is the rendered SQL default. An empty value adds no default.
	Default string
	// Input allows an HTTP route to write the field. The default is false.
	Input bool
	// Returned allows a response to carry the field. The default is false.
	Returned bool
}

UserField is one host-owned column on the users table.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL