Skip to content

Latest commit

 

History

History
69 lines (51 loc) · 2.93 KB

GUIDE.md

File metadata and controls

69 lines (51 loc) · 2.93 KB
Raw

Guide for dbump

Database support

To make maintainers & users life easier dbump keeps database-specific migrators in submobules. This makes go.mod clean or even empty and simplifies security audit.

To find what database are supported see dbump_* directories in root:

Database Go module Link
ClickHouse github.com/cristalhq/dbump/dbump_ch dbump_ch
Mongo github.com/cristalhq/dbump/dbump_mongo dbump_mongo
MySQL github.com/cristalhq/dbump/dbump_mysql dbump_mysql
MS SQL github.com/cristalhq/dbump/dbump_mssql dbump_mssql
Postgres github.com/cristalhq/dbump/dbump_pg dbump_pg
Postgres (pgx) github.com/cristalhq/dbump/dbump_pgx dbump_pgx
GCP Spanner github.com/cristalhq/dbump/dbump_spanner dbump_spanner

Just do: go get github.com/cristalhq/dbump/dbump_XXX with a specific XXX and you will be able to run migrations for this database.

Migration modes

Mode Description
ModeNotSet Default value in config, should not be used.
ModeApplyAll Apply all the migrations that weren't applied yet.
ModeApplyN Apply only 1 migration.
ModeRevertN Revert only current migration.
ModeRevertAll Revert all the migrations that were applied.
ModeRedo Revert and apply again current migration.
ModeDrop Revert all migrations and remove dbump table.

ZigZag mode

This mode is made to heavily test uses migrations but doing apply-revert-apply of each migration (assuming going up). In a such way every migration is truly verified and minimizes potential problems in a real world.

Detailed example, assuming we start with empty database (version 0):

  1. Apply migration 1
  2. Revert migration 1
  3. Apply migration 1
  4. Apply migration 2
  5. Revert migration 2
  6. Apply migration 2 ...

Steps 1 is obvious but doing 2,3 verifies that migration can clean after itself and can be applied again.

Credits goes to Postgres.ai mentioning this feature at conference.

Do not take database locks

If for some reason you don't want or you can't take lock on database there is Config.NoDatabaseLock field to achieve this:

// let's take Postgres for example 
m := dbump_pg.NewMigrator(...)

cfg := dbump.Config{
	NoDatabaseLock: true,
	// set other fields
}

dbump.Run(context.Background(), cfg)

However, lock prevents from running few migrators at once, possible creating bad situations that's is hard to fix.

Also, not all migrators support locks.