Git Best Practices

A condensed summary of the 25 most important Git practices for PostgreSQL 18.4 database work - shared portable content; customize per org conventions.

main is integration truth: Every merged migration passes flyway validate on staging; never leave broken SQL on tip (Git for Database Work Basics).
Ticket IDs in migration filenames and commits: V20260709_128__orders_priority.sql and feat(db): ... [DB-128].
Never edit applied migration content: New forward file fixes mistakes; checksum drift breaks deploys.
Protect main with migration CI: flyway migrate + flyway validate required check.
Squash feature branches before merge: One ticket, one logical migration series on main.
Short-lived branches: Target 1-3 days; rebase main daily to avoid version number collisions.
Release branch for coordinated schema + app train: Migration merges to release/* before tag.
Cherry-pick migrations to release/*, never merge main blindly: Avoid pulling unvetted schema into release candidate.
Tag after staging migration + app sign-off: Tag message lists migration versions applied.
Merge release/* back to main after rollout: Preserve train boundary.
Hotfix migration branches from production tag: Schema hotfix matches prod starting point.
Backport hotfix migration SHA to main: Same day; drift creates impossible flyway states.
Never force-push main or release/*: History is audit evidence for SOX and SOC reviews.
PR template requires rollback SQL: Even forward-only prod policy stores down scripts in db/rollback/.
PR template requires lock risk label: low / medium / high from Migration Safety Skill.
EXPLAIN evidence for query changes: Attached in PR or linked CI artifact.
No prod psql DDL without git commit within 24h: Emergency script merged via hotfix branch.
Do not commit pg_dump data files: Schema SQL only; data via separate secure pipeline.
.sql files UTF-8 without BOM: Avoid flyway checksum surprises on Windows editors.
Monorepo: one migration sequence per database: Document if multiple databases use separate folders.
Repeatable migrations (R__) for views/functions: Versioned migrations for one-time DDL only.
Lockfile for tooling: Pin flyway Docker image tag in CI, not latest.
Branch protection requires DBA review on db/migrations/**: CODEOWNERS file enforced.
Document deploy order in release notes: migration → worker → API standard pattern.
Post-deploy verify query in runbook: SELECT version FROM flyway_schema_history matches tag notes.

FAQs

GitFlow develop branch for database?

Prefer trunk (main) + short release/* + hotfix/*. Long-lived develop drifts migration versions from production flyway history.

Solo developer minimum?

main + feature branches + flyway CI on staging + never edit merged migrations. Add release branches when staging QA joins.

How connect Git to migration runners?

PR triggers staging migrate; tag triggers prod migrate job before app deploy. See Flyway and Liquibase.

Git for Database Work Basics - trunk flow
Code Review for SQL - PR checklist
Migrations Best Practices - schema change rules
Migration Safety Skill - lock scoring

Stack versions: This page was written for PostgreSQL 18.4, Flyway 10+, and GitHub / GitLab PR workflows.

Git Best Practices

A condensed summary of the 25 most important Git practices for PostgreSQL 18.4 database work - shared portable content; customize per org conventions.

main is integration truth: Every merged migration passes flyway validate on staging; never leave broken SQL on tip (Git for Database Work Basics).

Ticket IDs in migration filenames and commits: V20260709_128__orders_priority.sql and feat(db): ... [DB-128].

Never edit applied migration content: New forward file fixes mistakes; checksum drift breaks deploys.

Protect main with migration CI: flyway migrate + flyway validate required check.

Squash feature branches before merge: One ticket, one logical migration series on main.

Short-lived branches: Target 1-3 days; rebase main daily to avoid version number collisions.

Release branch for coordinated schema + app train: Migration merges to release/* before tag.

Cherry-pick migrations to release/*, never merge main blindly: Avoid pulling unvetted schema into release candidate.

Tag after staging migration + app sign-off: Tag message lists migration versions applied.

Merge release/* back to main after rollout: Preserve train boundary.

Hotfix migration branches from production tag: Schema hotfix matches prod starting point.

Backport hotfix migration SHA to main: Same day; drift creates impossible flyway states.

Never force-push main or release/*: History is audit evidence for SOX and SOC reviews.

PR template requires rollback SQL: Even forward-only prod policy stores down scripts in db/rollback/.

PR template requires lock risk label: low / medium / high from Migration Safety Skill.

EXPLAIN evidence for query changes: Attached in PR or linked CI artifact.

No prod psql DDL without git commit within 24h: Emergency script merged via hotfix branch.

Do not commit pg_dump data files: Schema SQL only; data via separate secure pipeline.

.sql files UTF-8 without BOM: Avoid flyway checksum surprises on Windows editors.

Monorepo: one migration sequence per database: Document if multiple databases use separate folders.

Repeatable migrations (R__) for views/functions: Versioned migrations for one-time DDL only.

Lockfile for tooling: Pin flyway Docker image tag in CI, not latest.

Branch protection requires DBA review on db/migrations/**: CODEOWNERS file enforced.

Document deploy order in release notes: migration → worker → API standard pattern.

Post-deploy verify query in runbook: SELECT version FROM flyway_schema_history matches tag notes.

FAQs

GitFlow develop branch for database?

Prefer trunk (main) + short release/* + hotfix/*. Long-lived develop drifts migration versions from production flyway history.

Solo developer minimum?

main + feature branches + flyway CI on staging + never edit merged migrations. Add release branches when staging QA joins.

How connect Git to migration runners?

PR triggers staging migrate; tag triggers prod migrate job before app deploy. See Flyway and Liquibase.

Git Best Practices

FAQs

Related

Search Documentation

Git Best Practices

FAQs

Related