Documentation ¶
Overview ¶
Package pgxschema provides tools to manage database schema changes ("migrations") as embedded functionality inside another application which is using jackc/pgx as its PostgreSQL driver.
Basic usage instructions involve creating a pgxschema.Migrator via the pgxschema.NewMigrator() function, and then passing your pgx.Conn or pgxpool.Pool to its .Apply() method.
See the package's README.md file for more usage instructions.
Index ¶
- Constants
- Variables
- func LockIdentifierForTable(tableName string) int64
- func MigrationIDFromFilename(filename string) string
- func QuotedIdent(ident string) string
- func QuotedTableName(schemaName, tableName string) string
- func SortMigrations(migrations []*Migration)
- type AppliedMigration
- type Connection
- type File
- type Logger
- type Migration
- func FSMigrations(filesystem fs.FS, glob string) (migrations []*Migration, err error)
- func MigrationFromFile(file File) (migration *Migration, err error)
- func MigrationFromFilePath(filename string) (migration *Migration, err error)
- func MigrationsFromDirectoryPath(dirPath string) (migrations []*Migration, err error)
- type Migrator
- type Option
- type Queryer
- type Transactor
Constants ¶
const DefaultTableName = "schema_migrations"
DefaultTableName defines the name of the database table which will hold the status of applied migrations
Variables ¶
var ErrNilDB = fmt.Errorf("Database connection is nil")
ErrNilDB is thrown when the database pointer is nil
var ErrNilTx = fmt.Errorf("Database transaction is nil")
ErrNilTx is thrown when a command is run against a nil transaction
Functions ¶
func LockIdentifierForTable ¶
LockIdentifierForTable computes a hash of the migrations table's name which can be used as a unique name for the Postgres advisory lock
func MigrationIDFromFilename ¶
MigrationIDFromFilename removes directory paths and extensions from the filename to make a friendlier Migration ID
func QuotedIdent ¶
QuotedIdent transforms the provided string into a valid, quoted Postgres identifier. This
func QuotedTableName ¶
QuotedTableName returns the string value of the name of the migration tracking table after it has been quoted for Postgres
func SortMigrations ¶
func SortMigrations(migrations []*Migration)
SortMigrations sorts a slice of migrations by their IDs
Types ¶
type AppliedMigration ¶
type AppliedMigration struct { Migration // Checksum is the MD5 hash of the Script for this migration Checksum string // ExecutionTimeInMillis is populated after the migration is run, indicating // how much time elapsed while the Script was executing. ExecutionTimeInMillis int // AppliedAt is the time at which this particular migration's Script began // executing (not when it completed executing). AppliedAt time.Time }
AppliedMigration represents a successfully-executed migration. It embeds Migration, and adds fields for execution results. This type is what records persisted in the schema_migrations table align with.
type Connection ¶
type Connection interface { Transactor Queryer }
Connection defines the interface for either a *pgxpool.Pool or a *pgx.Conn, both of which can start new transactions and execute queries.
type Logger ¶
type Logger interface {
Print(...interface{})
}
Logger is the interface for logging operations of the logger. By default the migrator operates silently. Providing a Logger enables output of the migrator's operations.
type Migration ¶
Migration is a yet-to-be-run change to the schema. This is the type which is provided to Migrator.Apply to request a schema change.
func FSMigrations ¶ added in v1.0.0
FSMigrations receives a filesystem (such as an embed.FS) and extracts all files matching the provided glob as Migrations, with the filename (without extension) being the ID and the file's contents being the Script.
Example usage:
FSMigrations(embeddedFS, "my-migrations/*.sql")
func MigrationFromFile ¶
MigrationFromFile builds a migration by reading from an open File-like object. The migration's ID will be based on the file's name. The file will *not* be closed after being read.
func MigrationFromFilePath ¶
MigrationFromFilePath creates a Migration from a path on disk
func MigrationsFromDirectoryPath ¶
MigrationsFromDirectoryPath retrieves a slice of Migrations from the contents of the directory. Only .sql files are read
type Migrator ¶
type Migrator struct { // Logger provides an optional way for the Migrator to report status // messages. It is nil by default which results in no output. Logger Logger // contains filtered or unexported fields }
Migrator is an instance customized to perform migrations on a particular against a particular tracking table and with a particular dialect defined.
func NewMigrator ¶
NewMigrator creates a new Migrator with the supplied options
func (*Migrator) Apply ¶
func (m *Migrator) Apply(db Connection, migrations []*Migration) error
Apply takes a slice of Migrations and applies any which have not yet been applied
func (Migrator) GetAppliedMigrations ¶
func (m Migrator) GetAppliedMigrations(db Queryer) (applied map[string]*AppliedMigration, err error)
GetAppliedMigrations retrieves all already-applied migrations in a map keyed by the migration IDs
func (*Migrator) QuotedTableName ¶ added in v1.0.0
QuotedTableName returns the dialect-quoted fully-qualified name for the migrations tracking table
type Option ¶
Option supports option chaining when creating a Migrator. An Option is a function which takes a Migrator and returns a Migrator with an Option modified.
func WithContext ¶
WithContext builds an option which will set the Migrator's context to the one provided.
func WithLogger ¶
WithLogger builds an Option which will set the supplied Logger on a Migrator. Usage: NewMigrator(WithLogger(logrus.New()))
func WithTableName ¶
WithTableName is an option which customizes the name of the schema_migrations tracking table. It can be called with either 1 or 2 string arguments. If called with 2 arguments, the first argument is assumed to be a schema qualifier (for example, WithTableName("public", "schema_migrations") would assign the table named "schema_migrations" in the the default "public" schema for Postgres)
type Queryer ¶
type Queryer interface { Exec(ctx context.Context, sql string, args ...interface{}) (pgconn.CommandTag, error) Query(ctx context.Context, sql string, args ...interface{}) (pgx.Rows, error) }
Queryer defines the interface for either a *pgxpool.Pool, a *pgx.Conn or a pgx.Tx, all of which can execute queries
type Transactor ¶
Transactor defines the interface for either a *pgxpool.Pool or a *pgx.Conn, both of which can start new transactions.