Sequences#

What Are Sequences?#

A sequence is one executable initialization step. Sequences are small, ordered units of work that implement the common Sequence interface:

type Sequence interface {
    Execute(int) (int, error)
    GetDescription(int) string
}

The integer argument is the one-based sequence index used for logging and error reporting.

Why Sequences Exist#

Sequences keep startup logic modular and deterministic. Each step has a narrow responsibility, such as connecting to the database or applying one patch.

This structure avoids embedding all startup behavior in main.go and makes it easier to add new initialization steps without changing the initializer execution logic.

Relationship Between Sequences and Patches#

A patch is represented by a SchemaPatch sequence. The sequence owns the decision whether the patch file should run by comparing the current database version with the patch target version.

The patch SQL file owns the actual schema changes and must update basyxsystem.schema_version itself.

Ordering Semantics#

Sequences run in the exact order in which they are registered:

schemInit.Register(steps.NewDatabaseConnection(execCtx, configPath))
schemInit.Register(steps.NewSystemTable(execCtx))
schemInit.Register(steps.NewSchemaUpload(execCtx, databaseSchema))
schemInit.Register(steps.NewSchemaPatch(execCtx, filepath.Join(patchBasePath, "101.sql"), "v1.0.1"))

There is no automatic dependency resolver. If a sequence depends on state created by another sequence, it must be registered after that sequence.

Execution Guarantees#

The initializer guarantees:

Sequential execution in registration order.
Stop-on-first-error behavior.
Consistent logging before and after each successful sequence.

The initializer does not provide automatic rollback across multiple sequences. Individual sequences must define their own transactional behavior when needed.

Transaction and Rollback Considerations#

SchemaPatch executes the patch SQL inside a database transaction. If patch execution fails, the transaction is rolled back.

SchemaUpload executes the full base schema SQL through the database handle without an explicit transaction wrapper in Go. The SQL file itself should remain safe and repeatable for initialization scenarios.

Sequences

Contents