Configuration and assembly APIs

The configuration package decodes and validates sgl.yaml; assembly turns one selected database into generator options and a dialect. Command execution and output publication remain the caller's responsibility. The configuration how-to shows the complete sequence.

Reading configuration

Entry point	Input and behaviour
`config.Load(path)`	Reads a disk file, applies defaults and validation, resolves relative directories beside that file and expands environment references in connection strings. A reference to an unset variable is left as written.
`config.Parse(data, isJSON)`	Decodes YAML or JSON bytes, applies defaults and validation, and preserves environment references. Paths remain as written.
`config.ReadFS(files, name)`	Reads at most `config.MaxFileBytes` through an `fs.FS`, then behaves as `Parse`: it validates, preserves environment references and leaves relative directories relative.
`cfg.ExpandEnvironment(lookup)`	Expands `${env:NAME}` in `migrate.dsn` and `schema_from` through the supplied lookup. A name the lookup cannot resolve stays as written, and the returned error wraps `config.ErrUnsetVariable`, naming each database, key and variable.
`config.RequireExpanded(key, value)`	Returns an error wrapping `config.ErrUnsetVariable` when a connection string still holds a reference; `sgl` calls it where it uses `migrate.dsn` or `schema_from`.
`cfg.Database(name)`	Returns the selected database and whether it exists.
`config.FileNames()`, `config.DefaultPrefixes()`	Fresh copies of the file names `Discover` looks for, in order, and of the directive prefixes a file that sets none accepts.

Unknown keys are errors, a YAML file must hold one document and a JSON file one value, and a configuration may declare at most config.MaxDatabases (256) databases. A validation error wraps config.ErrInvalid and lists at most 50 problems, then how many more there are. Load wraps file failures in *config.FileError; errors.Is and errors.As preserve the underlying error contract. config.CurrentVersion is the configuration schema version the package reads, the one sgl version prints. Configuration keys and defaults are described in configuration.

Assembling a generator

assemble.Options(configuration, database, factories) returns []seagull.Option, the dialect and an error. The options include the emitter, preset, type overrides and custom functions. The caller passes them to seagull.New and supplies an Input.

Assembly does not connect to schema_from, run migrations or write files. A host using live schemas adds a schema source; a host choosing partial generation adds WithSkipFailingQueries. Factories supplies registered dialect and emitter implementations, with built-in factories used when absent.

assemble.NewGoIndex(files) parses the generated Go files once, for describing queries as sgl describe and the playground do: Signature(name) prints a query's method and the structs it uses, and SQLConst(name) finds the SQL constant it sends. A method on the querier type wins over a runtime builder's method of the same name, such as Count. assemble.SQLTypeName names a SQL type as they print it, such as text[], and assemble.LocalTypeNames lists the local types a type expression names, leaving out those a package qualifies, such as the row and parameter structs of a method's signature.

assemble.NewStageTimer(clock) makes the observe.ObserverPort behind sgl generate --timings and the playground's stage timings: pass it to seagull.WithObserver, then read Stages(), one StageTiming per stage in the order the stages first started, each with its summed Total, its Spans and its Failures. Stop stops it taking further spans. A timer is safe for concurrent use.

Command registration

cli.Main runs command arguments and returns an exit status. MainContext accepts caller-owned cancellation. Registration options add or replace dialects, emitters, runtime driver names and migration backends. A registration with an empty name or a nil factory makes the call return 2 before running anything, and a nil option is skipped. A panic during the command is recovered: the call returns 3 and the stack is logged once to the error stream. cli.WithName sets the program name the CLI prints in its help, usage, errors, hints and version line: sgl by default, seagull in cmd/seagull.

Importing cli does not register database drivers; the embedding binary must import them. drivers.Options(), from seagull.sh/seagull/cmd/sgl/drivers, imports the stock set, the pure-Go drivers sgl ships with, and returns the cli.WithDriver options that select them, so a custom binary that keeps the stock drivers passes drivers.Options()... to cli.Main.

See custom binaries for an executable example.

Exported package inventory

These declarations are generated from the current source with go doc -short. For field contracts and method details, run go doc -all for the named package in this checkout. Source comments remain the symbol-level reference.

cmd/sgl/config

Package source · Go package reference

const CurrentVersion = 1 ...
var ErrNotFound = errors.New("no sgl.yaml found in this directory or any parent") ...
func DefaultPrefixes() []string
func Discover(directory string) (string, error)
func FileNames() []string
func JSONSchema() []byte
func RequireExpanded(key, value string) error
type Config struct{ ... }
    func Load(path string) (*Config, error)
    func Parse(data []byte, isJSON bool) (*Config, error)
    func ReadFS(filesystem fs.FS, name string) (*Config, error)
type CustomFunction struct{ ... }
type Database struct{ ... }
type DialectOptions struct{ ... }
type Directives struct{ ... }
type FileError struct{ ... }
type Go struct{ ... }
type Interface struct{ ... }
type JSONTags struct{ ... }
type Migrate struct{ ... }
type Override struct{ ... }
type QueryNames struct{ ... }
type Types struct{ ... }

cmd/sgl/assemble

Package source · Go package reference

const BuilderQueryMethod = "buildQuery" ...
func Dialect(database *config.Database, factories map[string]DialectFactory) (dialect.Dialect, error)
func DialectNames(factories map[string]DialectFactory) []string
func Drivers(info dialect.Facts) []string
func LocalTypeNames(node ast.Node) []string
func Options(configuration *config.Config, database *config.Database, factories Factories) ([]seagull.Option, dialect.Dialect, error)
func SQLTypeName(sqlType dialect.SQLType) string
func SupportsPrepared(driver string) bool
type DialectFactory func(options dialect_registry.Options) (dialect.Dialect, error)
type EmitterFactory func(request *EmitterRequest) (emit.EmitterPort, error)
type EmitterRequest struct{ ... }
type Factories struct{ ... }
type GoIndex struct{ ... }
    func NewGoIndex(files []emit.GeneratedFile) *GoIndex
type StageTimer struct{ ... }
    func NewStageTimer(clock observe.Clock) *StageTimer
type StageTiming struct{ ... }

cmd/sgl/starter

Package source · Go package reference

var ErrNoStarter = errors.New("no starter files")
type File struct{ ... }
    func Files(dialectName, family string) ([]File, error)

cmd/sgl/cli

Package source · Go package reference

func Main(arguments []string, options ...Option) int
func MainContext(ctx context.Context, arguments []string, options ...Option) int
type DialectFactory = assemble.DialectFactory
type EmitterFactory = assemble.EmitterFactory
type EmitterRequest = assemble.EmitterRequest
type MigrationBackendFactory func(options ...migrate.BackendOption) migrate.Backend
type Option func(*settings)
    func WithDialect(name string, factory DialectFactory) Option
    func WithDirectory(directory string) Option
    func WithDriver(dialectName, driverName string) Option
    func WithEmitter(name string, factory EmitterFactory) Option
    func WithIO(stdin io.Reader, stdout, stderr io.Writer) Option
    func WithMigrationBackend(dialectName string, factory MigrationBackendFactory) Option
    func WithName(name string) Option

cmd/sgl/drivers

Package source · Go package reference

func Options() []cli.Option