What this template is for
Schema migrations are the single most common cause of avoidable production incidents. The DDL is often trivial; the operational details around it - deployment order, lock time, backfill safety, rollback - are where outages live.
This template makes those operational details explicit fields on the ticket. The DBA can review the DDL. The implementer can see the rollback plan before starting. The on-call has a written reference if something goes wrong during the backfill.
When to use it
Use this template for any DDL or large-volume DML against a production database:
- Adding, removing, or renaming columns
- Adding or dropping indexes (especially on large tables)
- Adding constraints (NOT NULL, FK, UNIQUE)
- Data backfills that touch a non-trivial fraction of a table
- Cross-database moves and table renames
Routine application-level data changes (admin updating a row through the app) do not need a migration ticket. The trigger is DDL or bulk DML.
How to set it up in Jira
Configure the Database Migration issue type on the Create Issue screen so DDL, deployment order, backfill plan, rollback, and estimated lock time are required. Use STM Issue Templates to auto-create the standard sub-task checklist on every new Database Migration ticket. If the project already has Custom Fields for DDL or rollback plan, reuse them so reporting stays consistent across migrations.
Fields to add to your Jira create screen
These are the fields a project admin should make sure exist on the Create Issue screen for this issue type (Project settings → Screens). Without these on the screen, reporters can't provide the information triage needs - and STM can't reference them either.
| Field | Example value | Required |
|---|---|---|
Summary | Add nullable customer_tier column to accounts | Yes |
Database/Schema | payments.accounts | Yes |
Migration Type (custom) | Add column / Drop column / Index / Constraint / Data backfill | Yes |
DDL Statement (custom) | ALTER TABLE accounts ADD COLUMN customer_tier text; | Yes |
Deployment Order (custom) | Migration before code; code reads if-present | Yes |
Backfill Plan (custom) | Chunked update, 10k rows/batch, ~4h total | Yes |
Rollback Plan (custom) | DROP COLUMN; safe because no code reads required | Yes |
Estimated Lock Time (custom) | < 50ms (PG add-column nullable is instant) | Yes |
Affected Services | payments-api, billing-worker | No |
Reviewer (DBA) | @dba-on-call | No |
Maintenance Window | Online; no window required | No |
Linked Code PR | https://github.com/org/repo/pull/1399 | No |
Note on custom fields. STM currently supports up to 5 custom fields per template. You can add as many custom fields as you like to your Jira Create Issue screen - the 5-field limit only applies if you want STM to set or update those custom fields itself.
Sub-tasks STM creates automatically
Build an STM sub-task template containing the items below, then wire it to an On Create Issue Executor scoped to this issue type. Whenever a new issue of this type is created in the project, STM creates the full sub-task set in one step - with assignee, due date, and components inherited from the parent unless you override them.
- DBA review of DDL and lock-time estimate
- Stage the migration in a non-prod environment with prod-scale data
- Confirm the migration is reversible or that an additive-only path exists
- Deploy migration before the code that depends on it
- Run backfill (chunked, monitored, resumable)
- Deploy code that reads the new schema
- Verify queries on the new schema and remove if-present compatibility code
Common questions
What is the safest way to run a database migration through Jira?
Treat the migration as a change ticket with explicit fields for DDL, deployment order, backfill plan, rollback, and estimated lock time. Always deploy schema before code that depends on it, prefer additive-only changes (add column nullable, then backfill, then enforce), and run backfills in chunks small enough to resume safely if interrupted.
How do you avoid downtime when adding a NOT NULL column in Postgres?
Three steps. First, add the column as nullable - this is metadata-only and instant. Second, backfill in chunks while the application writes the value for new rows. Third, once the table is fully populated, add the NOT NULL constraint. Doing all three in one DDL statement on a large table is what causes long locks and downtime.
Should every schema migration require a Jira ticket?
Every production schema migration, yes. The ticket is your audit trail, your rollback runbook, and your post-incident reference. Routine local-dev migrations do not need tickets, but the moment a migration ships to a shared environment, the rollback plan needs to be written down somewhere - and a Jira ticket is the lowest-friction place to put it.
Can you automate the migration sub-task checklist in Jira?
Yes - use an [STM Issue Templates](/stm/) Executor that fires on creation of a Database Migration ticket and lays down the DBA-review / stage / deploy-schema-first / backfill / deploy-code / verify sub-tasks. The implementer never has to remember the order; it is the ticket's structure.
Automate the sub-tasks with STM
STM Issue Templates saves the sub-task list above as a reusable template and creates them on every new issue of this type - via an Executor on issue creation, on status transition, or triggered manually from the issue's "Create bulk sub-tasks" menu. STM does not change the parent issue's create screen (that's a Jira project-settings job) but it removes the manual work of creating the sub-tasks every time.
Try STM on the Atlassian Marketplace ↗ See how STM templates are built →