Customise generation with a preset

Use a preset when an embedded generator needs its own directive vocabulary, generated names or type defaults. Start from DefaultPreset and change only the fields your integration needs.

Choose the vocabulary

Construct the preset before creating the generator. DefaultPreset, WithPreset and the preset's field types are in the root package, seagull.sh/seagull; the dialect comes from its provider, here seagull.sh/seagull/sdk/dialect/dialect_engine_sqlite:

preset := seagull.DefaultPreset()
preset.Directives = seagull.Directives{Canonical: "acme", Aliases: []string{"sgl"}}
preset.Header = "// Code generated by acme. DO NOT EDIT."
preset.HelperPrefix = "acme"
preset.ErrorPrefix = "acme"
preset.QueryNames = seagull.QueryNames{Enabled: true, File: "query_names.go", Function: "QueryName"}

generator, err := seagull.New(dialect_engine_sqlite.New(), seagull.WithPreset(preset))
if err != nil {
    return err
}

The aliases accept existing directives during the transition. To rewrite them to the new canonical prefix, call FormatDirectivesFor(engine, source, "acme", "sgl") and review the resulting SQL comments before saving. Never rewrite an applied migration without accounting for its recorded checksum.

Use the generation workflow to handle operational errors, diagnostics and publication. The working preset example demonstrates vocabulary changes and the resulting helper names.

Adopt output with an earlier header

When deliberately moving an existing generated directory to the new header, publish with the earlier header included for stale-file pruning:

err := seagull.WriteFiles("internal/store", result,
    seagull.WithLegacyHeaders("// Code generated by sgl. DO NOT EDIT."),
)

Legacy headers govern stale deletion. Files whose names the new result contains are replaced regardless of their existing headers, so review the directory before publishing.

Keep an earlier generator's output stable

An integration can preserve earlier names and mappings with additional preset settings:

preset.SQLConstantSuffix = ""
preset.SQLConstantLowerCase = true
preset.Types.Enum = seagull.Slot{NotNull: seagull.GoType{Name: "string"}}
preset.KeepStars = true
preset.NonNullElements = true
preset.ModernIdioms = false

An empty suffix removes the default SQL suffix. SQLConstantLowerCase keeps an earlier constant-casing rule, and the enum slot uses plain strings instead of generated enum types. NonNullElements selects plain collection elements where the default may use pointers. ModernIdioms, on in DefaultPreset, makes stream methods return iter.Seq2 and separates top-level declarations with blank lines; turning it off keeps the earlier stream type and layout.

To make every error a generated method returns name the method, set preset.WrapErrors = true (go.wrap_errors: true in sgl.yaml). A failed GetUser then returns acme: GetUser: ... with your error prefix, and errors.Is(err, sql.ErrNoRows) still matches. It is off by default, so existing callers that compare error text are unaffected; see labelled errors.

KeepStars preserves stars in SQL. The default expands them into columns, protecting existing scan methods when a later migration adds a column; enabling KeepStars opts out of that protection. Use type overrides for any other mappings you need to preserve.

These choices do not guarantee compatibility with arbitrary earlier output. Regenerate into a temporary directory, inspect the diff and compile the existing callers before adopting it. The preset reference lists the fields and their configuration equivalents; compatibility describes upgrade contracts.