Pygration is a powerful and easy-to-use database migration library, designed to simplify the process of managing and applying database schema changes. Whether you're working on a small project or a large-scale application, Pygration provides a robust solution for versioning and applying database migrations seamlessly.
To install Pygration, you will need to have Python and pip installed on your system. Run this command:
pip install -i https://test.pypi.org/simple/ pygration
It is important to note that this package is published on TestPyPI.
Right now Pygration allows to work only with PostgreSQL.
The first thing you need to do is to create a configuration file. This can be
either pygration.toml
or pyproject.toml
.
Pygration needs to know 3 things: where to store migrations, which database you use, and how to connect to it.
Example of configuration in pygration.toml with all options:
provider = "postgresql"
dir = "migrations"
[connection]
username = "..."
password = "..."
host = "..."
port = "..."
database = "..."
schema = "..." # by default it's `public`
If you have env variables with values to connect to the database, you can insert them directly into the configuration:
[connection]
username = "${DB_USER}"
password = "${DB_PASSWORD}"
host = "${DB_HOST}"
port = "${DB_PORT}"
database = "${DB_NAME}"
If you prefer to save the configuration in pyproject.toml, you can do so:
[tool.pygration]
provider = "postgresql"
dir = "migrations"
[tool.pygration.connection]
username = "${DB_USER}"
password = "${DB_PASSWORD}"
host = "${DB_HOST}"
port = "${DB_HOST}"
database = "${DB_PORT}"
If for some reason you need a different configuration file, you can
specify it with the optional --config
parameter:
pygration --config custom_config.toml
Pygration has four commands: create
, migrate
, rollback
and details
.
To create a migration file, use create
command:
pygration create <name>
It creates a SQL file for the migration. Inside this file you can find 2 sections: UP and DOWN. The UP section is responsible for creating something in the database, and the DOWN section is responsible for deleting:
-- UP
CREATE TABLE person
(
id BIGSERIAL PRIMARY KEY,
email TEXT UNIQUE NOT NULL,
first_name TEXT NOT NULL,
last_name TEXT NOT NULL,
date_of_birth DATE
);
-- DOWN
DROP TABLE person;
To execute all migrations, use migrate
command:
pygration migrate
With this command, you can execute a single migration or all migrations up to the specified ID. Learn more about this:
pygration migrate --help
To roll back all migrations, use rollback
command:
pygration rollback
With this command, you also can roll back only a single migration or all migrations up to the specified ID. Learn more about this:
pygration rollback --help
To see details about executed migrations, use details
command:
pygration details
The main purpose of this library is to be used as a CLI, but you can also use
parts of it in your code. All you need to do is import pygration
:
import pygration
provider = "postgresql"
directory = "migrations"
db_user = "..."
db_pass = "..."
db_host = "..."
db_port = "..."
db_name = "..."
db_schema = "..."
pygration.create("name", directory=directory)
pygration.migrate(
provider=provider,
directory=directory,
username=db_user,
password=db_pass,
host=db_host,
port=db_port,
database=db_name,
schema=db_schema,
one=False,
id_=None,
)
pygration.rollback(
provider=provider,
directory=directory,
username=db_user,
password=db_pass,
host=db_host,
port=db_port,
database=db_name,
schema=db_schema,
one=False,
id_=None,
)
pygration.print_details(
provider=provider,
username=db_user,
password=db_pass,
host=db_host,
port=db_port,
database=db_name,
schema=db_schema,
)