diff

Documentation

Index

• Variables
• type MigrationHazard
  • func (p MigrationHazard) String() string
• type MigrationHazardType
• type Plan
  • func Generate(ctx context.Context, fromDB sqldb.Queryable, targetSchema SchemaSource, ...) (Plan, error)
  • func GeneratePlan(ctx context.Context, queryable sqldb.Queryable, tempdbFactory tempdb.Factory, ...) (Plan, error)
  • func (p Plan) ApplyLockTimeoutModifier(regex *regexp.Regexp, timeout time.Duration) Plan
  • func (p Plan) ApplyStatementTimeoutModifier(regex *regexp.Regexp, timeout time.Duration) Plan
  • func (p Plan) InsertStatement(index int, statement Statement) (Plan, error)
• type PlanOpt
  • func WithDataPackNewTables() PlanOpt
  • func WithDoNotValidatePlan() PlanOpt
  • func WithExcludeSchemas(schemas ...string) PlanOpt
  • func WithGetSchemaOpts(getSchemaOpts ...externalschema.GetSchemaOpt) PlanOpt
  • func WithIncludeSchemas(schemas ...string) PlanOpt
  • func WithLogger(logger log.Logger) PlanOpt
  • func WithRespectColumnOrder() PlanOpt
  • func WithTempDbFactory(factory tempdb.Factory) PlanOpt
• type SchemaSource
  • func DBSchemaSource(queryable sqldb.Queryable) SchemaSource
  • func DDLSchemaSource(stmts []string) SchemaSource
  • func DirSchemaSource(dirs []string) (SchemaSource, error)
• type Statement
  • func (s Statement) MarshalJSON() ([]byte, error)
  • func (s Statement) ToSQL() string

Variables

var (
	// ErrColumnOrderingChanged is returned when the ordering of columns changes and column ordering is not ignored.
	// It is recommended to ignore column ordering changes to column order
	ErrColumnOrderingChanged = fmt.Errorf("column ordering changed: %w", ErrNotImplemented)
)

var ErrNotImplemented = fmt.Errorf("not implemented")

Types

type MigrationHazard

type MigrationHazard struct {
	Type    MigrationHazardType `json:"type"`
	Message string              `json:"message"`
}

MigrationHazard represents a hazard that a statement poses to a database

func (MigrationHazard) String

func (p MigrationHazard) String() string

type MigrationHazardType

type MigrationHazardType = string

const (
	MigrationHazardTypeAcquiresAccessExclusiveLock   MigrationHazardType = "ACQUIRES_ACCESS_EXCLUSIVE_LOCK"
	MigrationHazardTypeAcquiresShareLock             MigrationHazardType = "ACQUIRES_SHARE_LOCK"
	MigrationHazardTypeAcquiresShareRowExclusiveLock MigrationHazardType = "ACQUIRES_SHARE_ROW_EXCLUSIVE_LOCK"
	MigrationHazardTypeCorrectness                   MigrationHazardType = "CORRECTNESS"
	MigrationHazardTypeDeletesData                   MigrationHazardType = "DELETES_DATA"
	MigrationHazardTypeHasUntrackableDependencies    MigrationHazardType = "HAS_UNTRACKABLE_DEPENDENCIES"
	MigrationHazardTypeIndexBuild                    MigrationHazardType = "INDEX_BUILD"
	MigrationHazardTypeIndexDropped                  MigrationHazardType = "INDEX_DROPPED"
	MigrationHazardTypeImpactsDatabasePerformance    MigrationHazardType = "IMPACTS_DATABASE_PERFORMANCE"
	MigrationHazardTypeIsUserGenerated               MigrationHazardType = "IS_USER_GENERATED"
	MigrationHazardTypeExtensionVersionUpgrade       MigrationHazardType = "UPGRADING_EXTENSION_VERSION"
	MigrationHazardTypeAuthzUpdate                   MigrationHazardType = "AUTHZ_UPDATE"
)

type Plan

type Plan struct {
	// Statements is the set of statements to be executed in order to migrate a database from schema A to schema B
	Statements []Statement `json:"statements"`
	// CurrentSchemaHash is the hash of the current schema, schema A. If you serialize this plans somewhere and
	// plan on running them later, you should verify that the current schema hash matches the current schema hash.
	// To get the current schema hash, you can use schema.GetPublicSchemaHash(ctx, conn)
	CurrentSchemaHash string `json:"current_schema_hash"`
}

Plan represents a set of statements to be executed in order to migrate a database from schema A to schema B

func Generate

func Generate(
	ctx context.Context,
	fromDB sqldb.Queryable,
	targetSchema SchemaSource,
	opts ...PlanOpt,
) (Plan, error)

Generate generates a migration plan to migrate the database to the target schema

Parameters: fromDB: The target database to generate the diff for. It is recommended to pass in *sql.DB of the db you wish to migrate. If using a connection pool, it is RECOMMENDED to set a maximum number of connections. targetSchema: The (source of the) schema you want to migrate the database to. Use DDLSchemaSource if the new schema is encoded in DDL. opts: Additional options to configure the plan generation

func GeneratePlan

func GeneratePlan(ctx context.Context, queryable sqldb.Queryable, tempdbFactory tempdb.Factory, newDDL []string, opts ...PlanOpt) (Plan, error)

deprecated: GeneratePlan generates a migration plan to migrate the database to the target schema. This function only diffs the public schemas.

Use Generate instead with the DDLSchemaSource(newDDL) and WithIncludeSchemas("public") and WithTempDbFactory options.

Parameters: queryable: The target database to generate the diff for. It is recommended to pass in *sql.DB of the db you wish to migrate. If using a connection pool, it is RECOMMENDED to set a maximum number of connections. tempDbFactory: used to create a temporary database instance to extract the schema from the new DDL and validate the migration plan. It is recommended to use tempdb.NewOnInstanceFactory, or you can provide your own. newDDL: DDL encoding the new schema opts: Additional options to configure the plan generation

func (Plan) ApplyLockTimeoutModifier

func (p Plan) ApplyLockTimeoutModifier(regex *regexp.Regexp, timeout time.Duration) Plan

ApplyLockTimeoutModifier applies the given timeout to all statements that match the given regex

func (Plan) ApplyStatementTimeoutModifier

func (p Plan) ApplyStatementTimeoutModifier(regex *regexp.Regexp, timeout time.Duration) Plan

ApplyStatementTimeoutModifier applies the given timeout to all statements that match the given regex

func (Plan) InsertStatement

func (p Plan) InsertStatement(index int, statement Statement) (Plan, error)

InsertStatement inserts the given statement at the given index. If index is equal to the length of the statements, it will append the statement to the end of the statement in the plan

type PlanOpt

type PlanOpt func(opts *planOptions)

func WithDataPackNewTables

func WithDataPackNewTables() PlanOpt

WithDataPackNewTables configures the plan generation such that it packs the columns in the new tables to minimize padding. It will help minimize the storage used by the tables

func WithDoNotValidatePlan

func WithDoNotValidatePlan() PlanOpt

WithDoNotValidatePlan disables plan validation, where the migration plan is tested against a temporary database instance.

func WithExcludeSchemas

func WithExcludeSchemas(schemas ...string) PlanOpt

func WithGetSchemaOpts

func WithGetSchemaOpts(getSchemaOpts ...externalschema.GetSchemaOpt) PlanOpt

func WithIncludeSchemas

func WithIncludeSchemas(schemas ...string) PlanOpt

func WithLogger

func WithLogger(logger log.Logger) PlanOpt

WithLogger configures plan generation to use the provided logger instead of the default

func WithRespectColumnOrder

func WithRespectColumnOrder() PlanOpt

WithRespectColumnOrder configures the plan generation to respect any changes to the ordering of columns in existing tables. You will most likely want this disabled, since column ordering changes are common

func WithTempDbFactory

func WithTempDbFactory(factory tempdb.Factory) PlanOpt

type SchemaSource

type SchemaSource interface {
	GetSchema(ctx context.Context, deps schemaSourcePlanDeps) (schema.Schema, error)
}

func DBSchemaSource

func DBSchemaSource(queryable sqldb.Queryable) SchemaSource

DBSchemaSource returns a SchemaSource that returns a schema based on the provided queryable. It is recommended that the sqldb.Queryable is a *sql.DB with a max # of connections set.

func DDLSchemaSource

func DDLSchemaSource(stmts []string) SchemaSource

DDLSchemaSource returns a SchemaSource that returns a schema based on the provided DDL. You must provide a tempDBFactory via the WithTempDbFactory option.

func DirSchemaSource

func DirSchemaSource(dirs []string) (SchemaSource, error)

DirSchemaSource returns a SchemaSource that returns a schema based on the provided directories. You must provide a tempDBFactory via the WithTempDbFactory option.

type Statement

type Statement struct {
	DDL string
	// Timeout is the statement_timeout to apply to this statement. If implementing your own plan executor, be sure to set
	// the session-level statement_timeout to this value before executing the statement. A transaction-level statement_timeout
	// will not work since building indexes concurrently cannot be done in a transaction
	Timeout time.Duration
	// LockTimeout is the lock_timeout to apply to this statement. If implementing your own plan executor, be sure to set
	// the session-level lock_timeout to this value before executing the statement. A transaction-level lock_timeout
	// will not work since building indexes concurrently cannot be done in a transaction
	LockTimeout time.Duration
	// The hazards this statement poses
	Hazards []MigrationHazard
}

func (Statement) MarshalJSON

func (s Statement) MarshalJSON() ([]byte, error)

func (Statement) ToSQL

func (s Statement) ToSQL() string