Documentation
¶
Overview ¶
Package seed implements the DB seeding fixtures system for nSelf projects. Seeds are SQL files organized by environment and fixture type, with support for idempotent and destructive headers, dependency ordering, and verification.
Index ¶
- Constants
- func FirstComposeService(fragmentPath string) (string, error)
- func FixtureDir(projectDir, fixture string) string
- func ListFixtures(projectDir string) ([]string, error)
- func PrintMatrix(matrix EnvMatrix) string
- func RunPluginSeed(ctx context.Context, rt PluginRuntime, t PluginTarget) (string, error)
- func SeedDir(projectDir string) string
- func ValidatePluginArgv(plugin string, argv []string) error
- func VerifyFixture(projectDir, fixtureName string, expectedManifest *FixtureManifest) (changed []string, err error)
- func WriteFixtureManifest(projectDir string, manifest FixtureManifest) error
- type EnvMatrix
- type FixtureFile
- type FixtureManifest
- type FixtureRunResult
- type GraphNode
- type PluginRuntime
- type PluginTarget
- type SQLRunner
- type SeedFile
Constants ¶
const ( HeaderIdempotent = "-- +seed:idempotent" HeaderDestructive = "-- +seed:destructive" HeaderDependsOn = "-- +seed:depends-on " )
SeedHeader directives parsed from SQL comments.
Variables ¶
This section is empty.
Functions ¶
func FirstComposeService ¶ added in v1.4.13
FirstComposeService returns the first service key (document order) of a plugin's docker-compose.plugin.yml.
func FixtureDir ¶
FixtureDir returns the directory for a specific fixture.
func ListFixtures ¶
ListFixtures returns available fixture names.
func PrintMatrix ¶ added in v1.0.9
PrintMatrix prints the env matrix in a human-readable table format.
func RunPluginSeed ¶ added in v1.4.13
func RunPluginSeed(ctx context.Context, rt PluginRuntime, t PluginTarget) (string, error)
RunPluginSeed runs t.Argv in the container of t.Service. The argv reaches docker exec as separate arguments; nothing is interpolated or shell-parsed.
func ValidatePluginArgv ¶ added in v1.4.13
ValidatePluginArgv returns E127 when the plugin declares no usable seed argv: none at all, or an empty program or empty argument element.
func VerifyFixture ¶ added in v1.0.9
func VerifyFixture(projectDir, fixtureName string, expectedManifest *FixtureManifest) (changed []string, err error)
VerifyFixture checks that a fixture's files match their expected checksums. If expectedManifest is nil, it computes fresh checksums (always passes). Returns a list of files that have changed since expectedManifest was recorded.
func WriteFixtureManifest ¶ added in v1.0.9
func WriteFixtureManifest(projectDir string, manifest FixtureManifest) error
WriteFixtureManifest writes a fixture manifest to .nself/seed-manifests/{fixture}.json.
Types ¶
type EnvMatrix ¶ added in v1.0.9
EnvMatrix maps seed files to the environments they should run in. Key: environment name (dev, staging, prod, test, _common) Value: list of seed file names for that environment
func BuildEnvMatrix ¶ added in v1.0.9
BuildEnvMatrix reads the seed directory and builds the environment matrix. Reads subdirectory names as environment names. Fixtures directory is excluded (fixtures are run explicitly).
type FixtureFile ¶ added in v1.0.9
type FixtureFile struct {
Name string
Path string
Checksum string // SHA256 of file contents
Size int64
}
FixtureFile describes a single SQL file within a fixture.
type FixtureManifest ¶ added in v1.0.9
type FixtureManifest struct {
Name string // fixture name (e.g. "demo", "load-test")
Files []FixtureFile // SQL files in this fixture
TotalHash string // SHA256 of all file checksums concatenated
}
FixtureManifest describes a fixture set with checksums for deterministic verification.
func LoadFixtureManifest ¶ added in v1.0.9
func LoadFixtureManifest(projectDir, fixtureName string) (FixtureManifest, error)
LoadFixtureManifest reads all SQL files in a fixture directory and computes checksums for verification purposes.
func LoadStoredManifest ¶ added in v1.0.9
func LoadStoredManifest(projectDir, fixtureName string) (*FixtureManifest, error)
LoadStoredManifest reads a previously stored manifest from disk. Returns nil, nil if no stored manifest exists.
type FixtureRunResult ¶ added in v1.0.9
type FixtureRunResult struct {
FixtureName string
FilesRun int
Duration time.Duration
Errors []error
}
FixtureRunResult describes the result of running a fixture.
func RunFixture ¶ added in v1.0.9
func RunFixture(projectDir, fixtureName string, runner SQLRunner) (FixtureRunResult, error)
RunFixture executes all SQL files in a fixture in dependency order. It calls the provided runner function for each file.
type GraphNode ¶
GraphNode represents a seed file in the dependency graph.
func DependencyGraph ¶
DependencyGraph returns the seed files with their dependency relationships as a printable adjacency list.
type PluginRuntime ¶ added in v1.4.13
type PluginRuntime interface {
FindContainer(ctx context.Context, service string) (string, error)
Exec(ctx context.Context, container string, argv []string) (stdout, stderr string, err error)
}
PluginRuntime is the container seam: find the running container of a compose service, and run an argv in it.
func DockerRuntime ¶ added in v1.4.13
func DockerRuntime(projectDir, projectName string) PluginRuntime
DockerRuntime returns the runtime that finds the plugin service container by compose labels (project working dirs or project name) and execs through internal/docker.
type PluginTarget ¶ added in v1.4.13
type PluginTarget struct {
Name string // plugin name, for messages
Service string // compose service whose container runs the argv
Argv []string // manifest seed.command
}
PluginTarget identifies one plugin seed to run.
type SQLRunner ¶ added in v1.0.9
SQLRunner is the function called for each SQL file when running a fixture.
type SeedFile ¶
type SeedFile struct {
Path string
Name string
Env string // _common, dev, staging, prod, or fixture name
Idempotent bool
Destructive bool
DependsOn []string
}
SeedFile describes a single seed SQL file with parsed metadata.
func CollectForRun ¶
CollectForRun returns the ordered list of seed files to execute for a given environment and optional fixture. Order: _common first, then env-specific, then fixture if specified.
func FilterForEnv ¶ added in v1.0.9
FilterForEnv returns the seeds that should run in the given environment. Seeds in _common run in all environments. Seeds in {env} only run in that environment. Seeds in fixtures/ are excluded (run explicitly via fixture commands).
func ParseHeader ¶
ParseHeader reads a seed file and extracts its metadata headers.
func ResolveDependencyOrder ¶ added in v1.0.9
ResolveDependencyOrder returns seeds in topologically sorted execution order (dependencies first). Returns an error if there are circular dependencies.