schema

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Sep 11, 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 (
	TableOrganizations  = DefaultPrefix + baseOrganizations
	TableOrgMembers     = DefaultPrefix + baseOrgMembers
	TableOrgInvitations = DefaultPrefix + baseOrgInvites
	TableOrgRoles       = DefaultPrefix + baseOrgRoles
	TableOrgTeams       = DefaultPrefix + baseOrgTeams
	TableOrgTeamMembers = DefaultPrefix + baseOrgTeamMember
)

Organization table names with the default prefix.

View Source
const (
	VersionOrganizations = "20261101000001"
	VersionOrgMembers    = "20261101000002"
	VersionOrgInvites    = "20261101000003"
	VersionOrgRoles      = "20261101000004"
	VersionOrgTeams      = "20261101000005"
	VersionOrgColumns    = "20261101000006"
)

Versions of the organization migration units. A released unit never changes.

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 SessionOrganizationExtension added in v0.4.0

func SessionOrganizationExtension(o Options) Extension

SessionOrganizationExtension returns the column that carries the active organization of one session. The column is nullable, so the unit applies to a database that already holds rows.

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
	// OrgFields are host-owned columns on the organizations table. They apply
	// only when the organizations plugin is enabled.
	OrgFields []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 OrganizationNames added in v0.4.0

type OrganizationNames struct {
	Organizations string
	Members       string
	Invitations   string
	Roles         string
	Teams         string
	TeamMembers   string
}

OrganizationNames returns the physical names of the organization tables.

func OrgTableNames added in v0.4.0

func OrgTableNames(o Options) OrganizationNames

OrgTableNames returns the physical organization table names for the options.

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.

func OrganizationTables added in v0.4.0

func OrganizationTables(o Options) []Table

OrganizationTables returns the tables of the organizations plugin. The plugin contributes them, so an application that enables no organization gets no table.

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 ExtensionUnit added in v0.4.0

func ExtensionUnit(version, owner, name string, d []Dialect, extensions []Extension) (Unit, error)

ExtensionUnit returns one unit that adds the columns and the indexes of the given extensions. A plugin uses it for a column on a table that another owner declared.

func OrganizationUnits added in v0.4.0

func OrganizationUnits(owner string, o Options) ([]Unit, error)

OrganizationUnits returns the migration units of the organization tables. One unit creates one table, so a host applies them in the order of the design document.

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