Skip to main content

Include static scripts

Static scripts are hand-written SQL files that run around your generated components, typically to prepare the database (disable a constraint, populate a temp table) or clean up after (re-enable, rebuild indexes). They're not generated from templates; they're checked in alongside them and referenced by path.

Looking to write SQL that replaces a component for a one-off change, rather than wrapping one? See custom scripts.

When to use a static script​

  • Disable / re-enable constraints around a data deployment that would otherwise violate a FK.
  • Pre-populate a temporary table the deployment reads from.
  • Run a one-off DDL migration (rename a column, back-fill data, drop a deprecated table) that a reusable template can't express.
  • Post-deployment cleanup. Rebuild statistics, refresh a materialised view, reset an audit flag.

If the change is reusable (it applies to many rows or to many environments the same way), a data or object component is the better fit. Static scripts are for one-off or wrapper work.

Wrapping a component with pre/post scripts​

Add <Script> children to the <Deployment> element of the component that needs them:

<DataComponent Category="orders" Name="initial-load" DeleteEnabled="true">
  <Table Id="1" Name="ORDERS">
    <Column Name="ID" PrimaryKey="true"/>
  </Table>
  <Deployment Weight="500">
    <Script Path="templates/scripts/disable-order-fk.sql" Weight="-1"/>
    <Script Path="templates/scripts/enable-order-fk.sql"  Weight="+1"/>
  </Deployment>
</DataComponent>
  • Path. Relative to the workspace root. The script file must be committed to source control alongside the template.
  • Negative weight runs before the component.
  • Positive weight runs after the component.
  • Weights are ordered across the whole deployment, so you can sequence several pre- or post-scripts.

The script file​

Just SQL. No XML wrapper, no special headers required. The contents are run verbatim as part of the deployment transaction.

templates/scripts/disable-order-fk.sql
ALTER TABLE ORDER_LINES NOCHECK CONSTRAINT ALL;
templates/scripts/enable-order-fk.sql
ALTER TABLE ORDER_LINES WITH CHECK CHECK CONSTRAINT ALL;

Tagging for reversal​

If the deployment may be reversed (reversal generates a rollback script), static scripts need a hint about where they belong in the reversed order. Add a metadata comment at the top of the script:

-- Metadata: {"static":"true","rollbackShift":"start"}
ALTER TABLE ORDER_LINES NOCHECK CONSTRAINT ALL;
rollbackShiftMeaning
"start"Always runs first in the reversed deployment
"end"Always runs last in the reversed deployment
(omitted)Mirrored from the forward position

"start" and "end" are the right choice for constraint-enable/disable scripts: you want them to bracket the reversed data changes the same way they bracket the forward ones.

One-off migration scripts​

For a migration that runs once and then is never re-applied, create a static script outside of any template's <Deployment> block and add it to a deployment manifest manually. DataStar's re-runnable script guarantees don't apply; you're explicitly declaring this is a one-shot.

If you need a static script to only run once, include an idempotency guard in the SQL itself:

IF NOT EXISTS (SELECT 1 FROM sys.columns
               WHERE object_id = OBJECT_ID('ORDERS') AND name = 'LEGACY_FLAG')
BEGIN
    ALTER TABLE ORDERS ADD LEGACY_FLAG BIT NULL;
END

Keeping static scripts organised​

Recommended layout:

workspace/
├── templates/
│   ├── orders.xml
│   └── scripts/
│       ├── disable-order-fk.sql
│       ├── enable-order-fk.sql
│       └── backfill-legacy-flag.sql
└── …

All scripts under one folder, named for what they do, path referenced from whichever template uses them. Commit the SQL alongside the template that references it, so pulling the repo gives you a coherent set.

See also​

Last updated on