Changes and scripts
deploy.sql, revert.sql, verify.sql, batches, transactions and the linter.
The three scripts
| Script | Runs | Purpose |
|---|---|---|
deploy.sql | bsm deploy | Make the change. |
revert.sql | bsm revert, rebase | Undo exactly what deploy did. |
verify.sql | After deploy, and in bsm verify | Raise an error if the change is not in effect. |
Batches
Scripts are split into batches on lines that contain only GO (optionally GO 5 to repeat, and a trailing -- comment), the way SSMS and sqlcmd do. GO inside comments (including nested /* */), strings and bracketed names is ignored.
Transactions
By default a change runs in one transaction: every batch of deploy.sql, then verify.sql, then the journal row. Any error rolls back all of it and records a fail event; the database is as it was.
Some statements cannot run in a transaction. Mark those changes !notx: batches then run one after another without a transaction, and the journal row is written only after the last succeeds. Write such scripts so they can be re-run (IF NOT EXISTS), because a failure can leave partial work.
Linter
On SQL Server, scripts are parsed with Microsoft's T-SQL parser before anything runs (PostgreSQL's checks are on its own page). plan check and deploy report:
| Code | Severity | Finding |
|---|---|---|
BSM001 | Error | Statement cannot run in a transaction (ALTER/CREATE/DROP DATABASE, BACKUP, RESTORE, full-text catalog and index DDL, RECONFIGURE, resumable online index) and the change is not !notx. |
BSM002 | Error | USE: bsm deploys to the environment's database; switching databases inside a script breaks that. |
BSM003 | Warning | Explicit BEGIN TRANSACTION inside a transactional change. A ROLLBACK there would abort bsm's transaction. |
BSM004 | Warning | SYSTEM_VERSIONING = OFF for a table that the same script neither turns back on nor drops, so it would stop recording history. |
BSM000 | Warning | The script did not parse; lint skipped (SQL Server may still accept it). |
Immutability
Once a change is deployed anywhere, treat its scripts as frozen. If its hash in your working copy differs from the hash a database recorded, status marks it edited after deploy and deploy refuses to continue. To change behaviour, add a new change. Whitespace counts; only BOMs and line endings are normalized.
Output
Messages from PRINT and low-severity RAISERROR appear with -v.