Custom generation

Defaults

Every target has a generation profile. Omitting the generation block preserves historical output: dependency ordering, schema and comment generation, automatic quoting, and the semicolon terminator.

Target settings

An explicit block records every setting: drops, IF NOT EXISTS, schema creation, quoting, terminator, comments, and ordering. Terminators are limited to 16 bytes and cannot contain a newline or NUL.

Drop before create

Destructive drops run after model pre-hooks and before schema pre-hooks, in reverse dependency order. Review them before execution.

IF NOT EXISTS

The generator uses it only for supported dialect/object pairs. Unsupported pairs keep ordinary CREATE syntax and produce a deterministic note.

Schema creation

Disabling schema creation suppresses only CREATE SCHEMA; qualification and schema hooks remain.

Quoting

Automatic delegates to the dialect, always quotes every model identifier, and never fails on identifiers that cannot legally be rendered bare.

Terminators

Normal statements use the target terminator; hook bodies and batch separators are raw. Templates must omit the effective terminator.

Comments

Generated comments can be omitted without changing hook or template text.

Ordering

Dependency order is the default. Kind/name ordering sorts only within dependency-safe bands.

Model/schema/table hooks

Hooks are local SQL fragments assigned to a dialect and position at model, schema, or table scope. Names are unique within a slot, bodies are non-empty, and library hooks remain private.

Exact hook order

Model pre-hooks run first, then optional drops. Schema pre-hooks precede schema objects; each table pre-hook is immediately before its table. Deferred table objects precede table post-hooks, then schema post-hooks and model post-hooks. Hooks in one slot sort by name and appear once.

Migration and deploy

Migration includes model hooks and hooks for touched schemas/tables. Deploy preserves the attached script and refuses duplicate attachment.

Template discovery

Templates are read only from the requested directory and its dialect child. Dialect files override generic files; unknown names, non-UTF-8 files, and symlinks are errors.

Template context

Templates receive statement, dialect, target, schema, table, and canonical typed object JSON. They use the report-template language and cannot access files or processes.

Inline templates

Column and table-constraint templates return inline fragments. Other templates return statement bodies without a terminator; empty output and NUL are rejected.

CLI

Use bluep generate ddl <dir> --target <name> --template-dir <dir>. Template paths are CLI-only and are not stored in models; migrate and deploy do not template ALTER.

Browser preview

Preview settings are not persisted unless saved, and the browser API never accepts a template directory.

Errors

Invalid profiles, hooks, quote choices, templates, and duplicate hook attachment report explicit errors.

Safety

Templates do not execute programs or access arbitrary files. Hooks are raw SQL, so review dry-run output carefully.

Limitations

ALTER statements, whole-file templates, includes, conditional hooks, and document-target templates are out of scope.