capsule

Documentation

Overview

Package capsule is the database usable from a script with no application around it: three lines of configuration, and a connection. It is for a one-off migration tool, a fixture loader or a test harness.

It is not how an application reaches its data. An application holds a Repository, which holds an auth.Grant and filters by auth.Tenant(g); the capsule's Connection and Table hold neither. A capsule call in a request path is a query nobody authorized, and it is the sort of thing that gets a module rejected in review.

Where database.default and database.connections come from is the argument the constructor takes; there is nothing else to configure and no registry to reach into. There is no fetch mode either, because there is one row shape here.

Index

• Variables
• func Connection(name string) (database.ConnectionInterface, error)
• func Schema(connection string) (any, error)
• func SetAsGlobal(m *Manager)
• func Table(table any, as, connection string) (*query.Builder, error)
• type Manager
  • func Instance() *Manager
  • func NewManager(config database.Configuration) *Manager
  • func (m *Manager) AddConnection(config map[string]any, name string)
  • func (m *Manager) BootModelLayer()
  • func (m *Manager) GetConfiguration() database.Configuration
  • func (m *Manager) GetConnection(name string) (database.ConnectionInterface, error)
  • func (m *Manager) GetDatabaseManager() *database.DatabaseManager
  • func (m *Manager) GetEventDispatcher() database.Dispatcher
  • func (m *Manager) SetEventDispatcher(dispatcher database.Dispatcher)
  • func (m *Manager) SetTransactionManager(manager *database.DatabaseTransactionsManager)

Variables

var BootModelLayerUsing func(resolver database.ConnectionResolverInterface, events database.Dispatcher)

BootModelLayerUsing is where an ORM registers the wiring BootModelLayer does.

Calling into an ORM's connection resolver and event dispatcher setters directly here would make the capsule import the ORM, and the capsule is the piece a script uses precisely because it wants the small half. So the ORM registers instead, from its own init, and a binary that never imported it has a BootModelLayer that does nothing -- which is the correct response to "boot the ORM I did not link".

Functions

func Connection

func Connection(name string) (database.ConnectionInterface, error)

Connection returns the named connection from the global capsule.

It fails with errNoCapsule rather than letting a nil instance panic four frames later, because a nil-pointer panic names nothing a person can act on.

func Schema

func Schema(connection string) (any, error)

Schema returns the schema builder for a named connection, from the global capsule.

It returns any because the schema builder lives in database/schema, which nothing here imports: a capsule needs to hand one over and never to call it. Nil means no schema builder was registered, which is what a binary that never imported the schema package has.

func SetAsGlobal

func SetAsGlobal(m *Manager)

SetAsGlobal makes this the capsule the package-level functions reach.

NewManager calls it, so a manager is usable that way as soon as it is built.

func Table

func Table(table any, as, connection string) (*query.Builder, error)

Table returns a query builder against a table on a named connection, from the global capsule.

It takes a context for the reason Connection.Table gives: a builder that cannot be cancelled holds a server connection for as long as the server likes.

Types

type Manager

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

Manager is the database, usable from a script that has no application around it.

It exists for a standalone script, a migration tool or a test harness, and it is not how an Arandu application reaches its data. An application holds a Repository, which holds a Grant. The package-level functions below hold neither, which is why the doc on every one of them says so and why nothing in a request path should be calling them.

func Instance

func Instance() *Manager

Instance answers the capsule the static methods use. It is nil before NewManager has run, and every static method below says so rather than dereferencing it.

func NewManager

func NewManager(config database.Configuration) *Manager

NewManager builds a Manager over the configuration it is given. Nil takes a fresh map.

func (*Manager) AddConnection

func (m *Manager) AddConnection(config map[string]any, name string)

AddConnection registers a connection configuration under name, or under "default" when name is empty.

func (*Manager) BootModelLayer

func (m *Manager) BootModelLayer()

BootModelLayer wires an ORM's connection resolver and event dispatcher to the capsule's manager, if BootModelLayerUsing was set.

func (*Manager) GetConfiguration

func (m *Manager) GetConfiguration() database.Configuration

GetConfiguration returns the configuration the capsule reads and writes connection settings through.

func (*Manager) GetConnection

func (m *Manager) GetConnection(name string) (database.ConnectionInterface, error)

GetConnection returns the named connection from this manager's DatabaseManager.

func (*Manager) GetDatabaseManager

func (m *Manager) GetDatabaseManager() *database.DatabaseManager

GetDatabaseManager returns the DatabaseManager the capsule wraps.

func (*Manager) GetEventDispatcher

func (m *Manager) GetEventDispatcher() database.Dispatcher

GetEventDispatcher returns the dispatcher put on every connection the capsule makes.

func (*Manager) SetEventDispatcher

func (m *Manager) SetEventDispatcher(dispatcher database.Dispatcher)

SetEventDispatcher replaces the dispatcher put on every connection the capsule makes; every connection made from here on carries it.

func (*Manager) SetTransactionManager

func (m *Manager) SetTransactionManager(manager *database.DatabaseTransactionsManager)

SetTransactionManager gives the capsule's connections a transactions manager, which is what makes AfterCommit work.

There is no container to read one from, so it is set directly.