Documentation
¶
Overview ¶
Package jobs implements RelSpec declarative job files.
A job file is a small YAML manifest that names one or more jobs and, for each job, the RelSpec command to run plus its inputs, output and options. It lets users run "relspec job run build-schema" instead of repeating long command lines.
The job-file system is deliberately NOT a shell: "command" is a closed enum of vetted RelSpec workflows, every path is resolved relative to the directory holding the job file and may not escape it, and remote database credentials are referenced by environment-variable name only - never embedded in the manifest. All discovery, parsing and validation in this package is side-effect free; nothing here reads input schemas, opens database connections or writes output. Execution lives in the CLI layer and only runs after Validate and the caller's pre-flight checks pass.
Index ¶
Constants ¶
const ( CommandConvert = "convert" // read one or more schema files, optionally merge, write one output CommandMerge = "merge" // additive merge of two or more schema files into one output CommandScriptsList = "scripts-list" // deterministically list SQL scripts across one or more directories )
Command names are a closed allow-list. Arbitrary strings are rejected.
const SchemaVersion = 1
SchemaVersion is the only job-file schema version this build understands.
Variables ¶
var SupportedCommands = []string{CommandConvert, CommandMerge, CommandScriptsList}
SupportedCommands lists every accepted command, in help order.
Functions ¶
Types ¶
type Input ¶
type Input struct {
Path string `yaml:"path"`
// Format is the RelSpec reader format (dbml, json, yaml, pgsql, ...).
Format string `yaml:"format"`
// ConnEnv is the NAME of an environment variable holding a connection
// string, used with database formats. The value is never stored here.
ConnEnv string `yaml:"conn_env"`
}
Input is one declared input schema.
type Job ¶
type Job struct {
// Name and SourceFile are populated by Load, not parsed from YAML.
Name string `yaml:"-"`
SourceFile string `yaml:"-"`
Command string `yaml:"command"`
Description string `yaml:"description"`
DependsOn []string `yaml:"depends_on"`
Inputs []Input `yaml:"inputs"`
ScriptDirs []string `yaml:"script_dirs"`
Output *Output `yaml:"output"`
Options Options `yaml:"options"`
Logfile string `yaml:"logfile"`
}
Job is one named job within a job file.
type Options ¶
type Options struct {
FlattenSchema bool `yaml:"flatten_schema"`
Schema string `yaml:"schema"`
Package string `yaml:"package"`
ContinueOnError bool `yaml:"continue_on_error"`
SkipRelations bool `yaml:"skip_relations"`
SkipEnums bool `yaml:"skip_enums"`
SkipViews bool `yaml:"skip_views"`
SkipDomains bool `yaml:"skip_domains"`
SkipSequences bool `yaml:"skip_sequences"`
}
Options carries the subset of command flags a job file may set.
type Output ¶
type Output struct {
Format string `yaml:"format"`
Path string `yaml:"path"`
ConnEnv string `yaml:"conn_env"`
Overwrite bool `yaml:"overwrite"`
}
Output is the declared output target.
type Set ¶
type Set struct {
// Files is the sorted list of job files that contributed jobs.
Files []string
// Jobs is keyed by job name.
Jobs map[string]*Job
}
Set is the merged view of all discovered/selected job files.
func Load ¶
Load parses every path, rejects unknown fields and unsupported versions, and merges all jobs into one Set. A job name defined by more than one file is a hard error. Load performs structural checks only; call Validate for full semantic validation.
func (*Set) Plan ¶
Plan returns the jobs to execute for name in dependency order. When includeDeps is false only the named job is returned (its declared dependencies are still validated to exist and be acyclic by Validate).
func (*Set) Validate ¶
Validate runs full semantic validation over the whole set and returns a single error describing every problem found. It never touches the filesystem beyond what Load already read; existence of input files and environment variables is checked by the caller immediately before execution.
Source Files