README
¶
pgroll
A minimal file-based migration library for PostgreSQL.
Installation
go get codefloe.com/binanary/pgroll
Usage
Follow the link below for usage instructions.
Support
If you encounter any issues or have a question that the documentation does not address, please open an issue.
When reporting a security vulnerability, please do not include details in the initial issue. A project maintainer will respond with further instructions.
Contributing
Pull requests that implement a feature approved by project maintainers or fix a known bug are encouraged. Other pull requests may be considered at the discretion of project maintainers.
Accepted contributions will be licensed under the Boost Software License 1.0 and may be relicensed under more permissive terms in the future.
License
This project is licensed under the Boost Software License 1.0. An online copy of the license is available at https://www.boost.org/LICENSE_1_0.txt
Documentation
¶
Overview ¶
Package pgroll implements support for file-based PostgreSQL schema migrations. Check the documentation for Migrations for details on file formats.
The current version is stored in the pgroll_migrations table and is updated atomically with each migration using a transaction.
Example ¶
// SPDX-License-Identifier: BSL-1.0
// Copyright 2025 Benjamin Winig
package main
import (
"embed"
"fmt"
"io/fs"
"codefloe.com/binanary/pgroll"
)
//go:embed "migrations"
var migrationFS embed.FS
func main() {
dsn := "postgres://user:pass@host/dbname"
migrations, err := fs.Sub(migrationFS, "migrations")
if err != nil {
// handle error
}
n, err := pgroll.Latest(dsn, migrations)
if err != nil {
// handle error
}
fmt.Printf("%d migrations applied", n)
}
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Current ¶
func Current(dsn string, m Migrations) (string, error)
Current returns the name of the current version as specified in the list file.
Types ¶
type Migrations ¶
Migrations must implement fs.FS and contain the following in its root:
- A text file named list (no extension) containing a newline-separated list of version names. It can have comments after # characters.
- For each migration, the files foo.up.sql and foo.down.sql containing upgrade and downgrade queries (replace foo with the version name).
Migrations will be performed in the order they appear in the list file. The version names in list and file names must match.
Source Files