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 ( CurrentSchemaVersion = 1 MinSchemaVersion = 1 )
CurrentSchemaVersion is the highest job-file schema version this build was written for. MinSchemaVersion is the oldest it still accepts. A file that declares a version in between loads normally; a newer version loads best-effort with a warning (see Load); an older-than-minimum version is a hard error.
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 CommandScriptsExec = "scripts-exec" // execute SQL scripts across one or more directories against a live database CommandTempl = "templ" // apply a custom Go text template to one or more schemas CommandSplit = "split" // extract selected schemas/tables into a separate output CommandInspect = "inspect" // validate one or more schemas against rules and write a report CommandDiff = "diff" // compare exactly two schemas and write a differences report )
Command names are a closed allow-list. Arbitrary strings are rejected.
Variables ¶
var SupportedCommands = []string{ CommandConvert, CommandMerge, CommandScriptsList, CommandScriptsExec, CommandTempl, CommandSplit, CommandInspect, CommandDiff, }
SupportedCommands lists every accepted command, in help order.
Functions ¶
func Discover ¶
Discover returns the job files in dir in deterministic order. The default file "relspec.yml"/"relspec.yaml" sorts first, followed by named files "relspec.<name>.yml"/"relspec.<name>.yaml" in lexical order.
func SafeJoin ¶
SafeJoin resolves rel against root and guarantees the result stays inside root. It is the single choke point for turning a manifest path into a filesystem path.
func SingleFileOutputFormat ¶ added in v1.0.77
SingleFileOutputFormat reports whether format writes exactly one file.
Types ¶
type Defaults ¶ added in v1.0.77
type Defaults struct {
// LogMaxSize is a human-readable size ("5MB", "512KB", "1GB"). Empty
// means "use the built-in default".
LogMaxSize string `yaml:"log_max_size"`
// LogKeep is how many rotated logfiles to retain. Zero means "use the
// built-in default".
LogKeep int `yaml:"log_keep"`
}
Defaults carries file-wide settings that individual jobs may override.
type File ¶
type File struct {
Version int `yaml:"version"`
Defaults *Defaults `yaml:"defaults"`
Jobs map[string]*Job `yaml:"jobs"`
}
File is the on-disk shape of a single job file.
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"`
// FromJob names another job in the set whose file output is used as this
// input. It implies a dependency on that job. Path/Format/ConnEnv must be
// empty when FromJob is set; the format is inherited from the producer.
FromJob string `yaml:"from_job"`
}
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"`
Template string `yaml:"template"`
Mode string `yaml:"mode"`
FilenamePattern string `yaml:"filename_pattern"`
Output *Output `yaml:"output"`
Rules string `yaml:"rules"`
Report *Report `yaml:"report"`
Select *Select `yaml:"select"`
Options Options `yaml:"options"`
Logfile string `yaml:"logfile"`
LogMaxSize string `yaml:"log_max_size"`
LogKeep *int `yaml:"log_keep"`
// contains filtered or unexported fields
}
Job is one named job within a job file.
func (*Job) Dir ¶
Dir returns the directory that a job's relative paths resolve against: the directory containing the job file that declared it.
func (*Job) ResolvedLogPolicy ¶ added in v1.0.77
ResolvedLogPolicy returns the effective rotation policy: the job's own overrides win, then its file's defaults block, then the built-in default.
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 Report ¶ added in v1.0.77
type Report struct {
// Format is the report format: diff accepts summary|json|html, inspect
// accepts markdown|json. Empty means the command's default.
Format string `yaml:"format"`
Path string `yaml:"path"`
Overwrite bool `yaml:"overwrite"`
}
Report is the output target for the inspect and diff commands.
type Select ¶ added in v1.0.77
type Select struct {
Schemas []string `yaml:"schemas"`
Tables []string `yaml:"tables"`
ExcludeSchemas []string `yaml:"exclude_schemas"`
ExcludeTables []string `yaml:"exclude_tables"`
DatabaseName string `yaml:"database_name"`
}
Select carries the schema/table selection for the split command.
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
// Warnings holds non-fatal load-time messages (e.g. a newer-than-known
// schema version). Callers should surface these to the user.
Warnings []string
}
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