seed

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 FixtureDir(projectDir, fixture string) string
• func ListFixtures(projectDir string) ([]string, error)
• func PrintMatrix(matrix EnvMatrix) string
• func SeedDir(projectDir string) string
• func VerifyFixture(projectDir, fixtureName string, expectedManifest *FixtureManifest) (changed []string, err error)
• func WriteFixtureManifest(projectDir string, manifest FixtureManifest) error
• type EnvMatrix
  • func BuildEnvMatrix(projectDir string) (EnvMatrix, error)
• type FixtureFile
• type FixtureManifest
  • func LoadFixtureManifest(projectDir, fixtureName string) (FixtureManifest, error)
  • func LoadStoredManifest(projectDir, fixtureName string) (*FixtureManifest, error)
• type FixtureRunResult
  • func RunFixture(projectDir, fixtureName string, runner SQLRunner) (FixtureRunResult, error)
• type GraphNode
  • func DependencyGraph(projectDir string) ([]GraphNode, error)
• type SQLRunner
• type SeedFile
  • func CollectForRun(projectDir, env, fixture string) ([]SeedFile, error)
  • func FilterForEnv(seeds []SeedFile, env string) []SeedFile
  • func ListSeeds(projectDir string) ([]SeedFile, error)
  • func ParseHeader(path string) (SeedFile, error)
  • func ResolveDependencyOrder(seeds []SeedFile) ([]SeedFile, error)

Constants

const (
	HeaderIdempotent  = "-- +seed:idempotent"
	HeaderDestructive = "-- +seed:destructive"
	HeaderDependsOn   = "-- +seed:depends-on "
)

SeedHeader directives parsed from SQL comments.

Functions

func FixtureDir

func FixtureDir(projectDir, fixture string) string

FixtureDir returns the directory for a specific fixture.

func ListFixtures

func ListFixtures(projectDir string) ([]string, error)

ListFixtures returns available fixture names.

func PrintMatrix

func PrintMatrix(matrix EnvMatrix) string

PrintMatrix prints the env matrix in a human-readable table format.

func SeedDir

func SeedDir(projectDir string) string

SeedDir returns the base seeds directory for a project.

func VerifyFixture

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

func WriteFixtureManifest(projectDir string, manifest FixtureManifest) error

WriteFixtureManifest writes a fixture manifest to .nself/seed-manifests/{fixture}.json.

Types

type EnvMatrix

type EnvMatrix map[string][]string

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

func BuildEnvMatrix(projectDir string) (EnvMatrix, error)

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

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

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

func LoadFixtureManifest(projectDir, fixtureName string) (FixtureManifest, error)

LoadFixtureManifest reads all SQL files in a fixture directory and computes checksums for verification purposes.

func LoadStoredManifest

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

type FixtureRunResult struct {
	FixtureName string
	FilesRun    int
	Duration    time.Duration
	Errors      []error
}

FixtureRunResult describes the result of running a fixture.

func RunFixture

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

type GraphNode struct {
	Name      string
	Env       string
	DependsOn []string
}

GraphNode represents a seed file in the dependency graph.

func DependencyGraph

func DependencyGraph(projectDir string) ([]GraphNode, error)

DependencyGraph returns the seed files with their dependency relationships as a printable adjacency list.

type SQLRunner

type SQLRunner func(filePath string) error

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

func CollectForRun(projectDir, env, fixture string) ([]SeedFile, error)

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

func FilterForEnv(seeds []SeedFile, env string) []SeedFile

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 ListSeeds

func ListSeeds(projectDir string) ([]SeedFile, error)

ListSeeds returns all available seed files grouped by category.

func ParseHeader

func ParseHeader(path string) (SeedFile, error)

ParseHeader reads a seed file and extracts its metadata headers.

func ResolveDependencyOrder

func ResolveDependencyOrder(seeds []SeedFile) ([]SeedFile, error)

ResolveDependencyOrder returns seeds in topologically sorted execution order (dependencies first). Returns an error if there are circular dependencies.