# 🛠️ Migropy
**Migropy** is a lightweight and extensible Python library for managing **database migrations**.
Designed for simplicity and flexibility, it helps teams apply, track, and version-control schema changes across multiple
environments.
---
## 📚 Table of Contents
- [🚀 Features](#-features)
- [📦 Installation](#-installation)
- [📖 How to use - CLI](#-how-to-use---cli)
- [1. Initialize a new migration project](#1-initialize-a-new-migration-project)
- [2. Fill the config.ini file](#2-fill-the-configini-file)
- [3. Create a new migration](#3-create-a-new-migration)
- [4. Apply the migrations](#4-apply-the-migrations)
- [5. Downgrade the migrations](#5-downgrade-the-migrations)
- [6. Rollback the migrations](#6-rollback-the-migrations)
- [🐍 How to use - Python](#-how-to-use---python)
- [📄 Migration example](#-migration-example)
- [⚙️ Available commands](#-available-commands)
- [🧪 Running Unit Tests](#-running-unit-tests)
- [📝 Changelog](#-changelog)
- [🤝 Contributing](#-contributing)
- [📫 Support](#-support)
- [📄 License](#-license)
---
## 🚀 Features
- ✅ Versioned migrations with up/down support
- ✅ Compatible with PostgreSQL & MySQL
- ✅ CLI for common migration operations
- ✅ Safe and idempotent execution
- ✅ Customizable migration directory structure
---
## 📦 Installation
```bash
pip install migropy
```
---
## 📖 How to use - CLI
### 1. Initialize a new migration project
This command will create a new directory called `migropy` with the necessary files to manage your migrations & db
parameters.
```bash
migropy init
```
### 2. Fill the config.ini file
This file is generated in your current directory and contains the database connection parameters and the path to the migration
```ini
[database]
# database connection parameters
# available types: postgres, mysql
host = localhost
port = 5432
user = postgres
password = postgres
dbname = my_database
type = postgres # or mysql
[migrations]
# path to migration scripts
# use forward slashes (/) also on windows to provide an os agnostic path
script_location = migropy
[logger]
# available levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
level = DEBUG
```
### 3. Create a new migration
This command will create a new migration file in the `migropy/versions` directory with the following template:
```bash
migropy generate 'migration name'
```
```sql
-- Up migration
-- Down migration
```
### 4. Apply the migrations
This command will apply all the migrations in the `migrations` directory. Please note the migrations are applied in
the prefix order.
```bash
migropy upgrade
```
### 5. Downgrade the migrations
This command will downgrade all the migrations in the `migrations` directory. Please note the migrations are
downgraded in
the prefix order.
```bash
migropy downgrade
```
### 6. Rollback the migrations
This command will rollback the last n migrations in the `migrations` directory, starting from the last one executed.
```bash
migropy rollback <n>
```
---
## 🐍 How to use - Python
You can also use **Migropy** as a library in your Python code. Here is an example of how to use it:
```python
# Importing the function to load the migration configuration
from migropy.configuration_parser import load_config
# Importing the Postgres database adapter
from migropy.databases.postgres import Postgres
# Importing the common database configuration structure
from migropy.databases.commons import DbConfig
# Importing the migration engine responsible for applying migrations
from migropy.migration_engine import MigrationEngine
# Create a database configuration object with connection parameters
db_config = DbConfig(
host="localhost", # Database server hostname or IP
port=5432, # Default PostgreSQL port
user="user", # Username to connect to the database
password="password", # Password for the given user
database="test" # Name of the target database
)
# Instantiate a Postgres database connection using the provided configuration
db = Postgres(db_config)
# Create a MigrationEngine instance with:
# - the database connection
# - the loaded configuration (usually from a file like migropy.ini)
engine = MigrationEngine(db=db, config=load_config())
# Initialize the migropy environment and create the necessary tables
# use it just once!!!
engine.init()
# Generate a new migration revision with a descriptive name
engine.generate_revision(revision_name='first revision')
# Apply all pending migrations to upgrade the database schema
engine.upgrade()
```
---
## 📄 Migration example
```sql
-- Up migration
CREATE TABLE users
(
id SERIAL PRIMARY KEY,
name VARCHAR(100) NOT NULL,
email VARCHAR(100) NOT NULL
);
-- Down migration
DROP TABLE users;
```
---
## ⚙️ Available commands
| Comando | Descrizione |
|-------------------------------|-------------------------------|
| `migropy init` | Init migratron environment |
| `migropy generate <name:str>` | Generate a new sql migration |
| `migropy upgrade` | Apply all the migration |
| `migropy downgrade` | Rollback all revisions |
| `migropy rollback <n:int>` | Rollback n revisions |
| `migropy list ` | Show current migration status |
---
## 🧪 Running Unit Tests
To run the unit tests using poetry, you can use the following command:
```bash
poetry run pytest --rootdir=tests
```
---
## 📝 Changelog
See the full [CHANGELOG.md](https://github.com/fredimatteo/migratron/blob/main/CHANGELOG.md)
### Latest Changes
- **0.3.1** - Code refactor to improve readability and maintainability
- **0.3.0** - Add rollback command
- **0.2.2** – Commands refactor & usage from python code
- **0.2.1** – Increase minimum python version to 3.10 & refactor MigrationEngine
- **0.2.0** – MySQL database support
- **0.1.1** – Initial project setup with PostgreSQL
---
## 🤝 Contributing
We welcome contributions!
To get started:
1. Fork the repository
2. Create a new branch (`git checkout -b feature/your-feature`)
3. Commit your changes
4. Open a pull request 🚀
---
## 📫 Support
For issues, feature requests or general questions, open an issue on [GitHub Issues](https://github.com/fredimatteo/migratron/issues).
---
## 📄 License
MIT License © 2025 — teoxy
Raw data
{
"_id": null,
"home_page": "https://github.com/fredimatteo/migropy/blob/develop/README.md",
"name": "migropy",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.10.0",
"maintainer_email": null,
"keywords": "database, migrations, postgresql, mysql, sql, cli",
"author": "fredimatteo",
"author_email": "matteofredi.developer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/71/02/ce389287effa260fb82ada49239601eb6343e00aba36b318347841902b3f/migropy-0.3.1.tar.gz",
"platform": null,
"description": "\n\n\n\n# \ud83d\udee0\ufe0f Migropy\n\n**Migropy** is a lightweight and extensible Python library for managing **database migrations**. \nDesigned for simplicity and flexibility, it helps teams apply, track, and version-control schema changes across multiple\nenvironments.\n\n---\n\n## \ud83d\udcda Table of Contents\n\n- [\ud83d\ude80 Features](#-features)\n- [\ud83d\udce6 Installation](#-installation)\n- [\ud83d\udcd6 How to use - CLI](#-how-to-use---cli)\n - [1. Initialize a new migration project](#1-initialize-a-new-migration-project)\n - [2. Fill the config.ini file](#2-fill-the-configini-file)\n - [3. Create a new migration](#3-create-a-new-migration)\n - [4. Apply the migrations](#4-apply-the-migrations)\n - [5. Downgrade the migrations](#5-downgrade-the-migrations)\n - [6. Rollback the migrations](#6-rollback-the-migrations)\n- [\ud83d\udc0d How to use - Python](#-how-to-use---python)\n- [\ud83d\udcc4 Migration example](#-migration-example)\n- [\u2699\ufe0f Available commands](#-available-commands)\n- [\ud83e\uddea Running Unit Tests](#-running-unit-tests)\n- [\ud83d\udcdd Changelog](#-changelog)\n- [\ud83e\udd1d Contributing](#-contributing)\n- [\ud83d\udceb Support](#-support)\n- [\ud83d\udcc4 License](#-license)\n\n\n---\n\n## \ud83d\ude80 Features\n\n- \u2705 Versioned migrations with up/down support\n- \u2705 Compatible with PostgreSQL & MySQL\n- \u2705 CLI for common migration operations\n- \u2705 Safe and idempotent execution\n- \u2705 Customizable migration directory structure\n\n---\n\n## \ud83d\udce6 Installation\n\n```bash\npip install migropy\n```\n\n---\n\n## \ud83d\udcd6 How to use - CLI\n\n### 1. Initialize a new migration project\n\nThis command will create a new directory called `migropy` with the necessary files to manage your migrations & db\nparameters.\n```bash\nmigropy init\n```\n\n### 2. Fill the config.ini file\nThis file is generated in your current directory and contains the database connection parameters and the path to the migration\n```ini\n[database]\n# database connection parameters\n# available types: postgres, mysql\nhost = localhost\nport = 5432\nuser = postgres\npassword = postgres\ndbname = my_database\ntype = postgres # or mysql\n\n[migrations]\n# path to migration scripts\n# use forward slashes (/) also on windows to provide an os agnostic path\nscript_location = migropy\n\n[logger]\n# available levels: DEBUG, INFO, WARNING, ERROR, CRITICAL\nlevel = DEBUG\n```\n\n### 3. Create a new migration\n\nThis command will create a new migration file in the `migropy/versions` directory with the following template:\n\n```bash\nmigropy generate 'migration name'\n```\n\n```sql\n-- Up migration\n\n-- Down migration\n```\n\n### 4. Apply the migrations\n\nThis command will apply all the migrations in the `migrations` directory. Please note the migrations are applied in\nthe prefix order.\n```bash\nmigropy upgrade\n```\n\n### 5. Downgrade the migrations\n\nThis command will downgrade all the migrations in the `migrations` directory. Please note the migrations are \ndowngraded in\nthe prefix order.\n```bash\nmigropy downgrade\n```\n\n### 6. Rollback the migrations\n\nThis command will rollback the last n migrations in the `migrations` directory, starting from the last one executed.\n```bash\nmigropy rollback <n>\n```\n\n---\n\n## \ud83d\udc0d How to use - Python\n\nYou can also use **Migropy** as a library in your Python code. Here is an example of how to use it:\n\n```python\n# Importing the function to load the migration configuration\nfrom migropy.configuration_parser import load_config\n\n# Importing the Postgres database adapter\nfrom migropy.databases.postgres import Postgres\n\n# Importing the common database configuration structure\nfrom migropy.databases.commons import DbConfig\n\n# Importing the migration engine responsible for applying migrations\nfrom migropy.migration_engine import MigrationEngine\n\n# Create a database configuration object with connection parameters\ndb_config = DbConfig(\n host=\"localhost\", # Database server hostname or IP\n port=5432, # Default PostgreSQL port\n user=\"user\", # Username to connect to the database\n password=\"password\", # Password for the given user\n database=\"test\" # Name of the target database\n)\n\n# Instantiate a Postgres database connection using the provided configuration\ndb = Postgres(db_config)\n\n# Create a MigrationEngine instance with:\n# - the database connection\n# - the loaded configuration (usually from a file like migropy.ini)\nengine = MigrationEngine(db=db, config=load_config())\n\n# Initialize the migropy environment and create the necessary tables\n# use it just once!!!\nengine.init()\n\n# Generate a new migration revision with a descriptive name\nengine.generate_revision(revision_name='first revision')\n\n# Apply all pending migrations to upgrade the database schema\nengine.upgrade()\n\n```\n\n---\n\n## \ud83d\udcc4 Migration example\n\n```sql\n-- Up migration\nCREATE TABLE users\n(\n id SERIAL PRIMARY KEY,\n name VARCHAR(100) NOT NULL,\n email VARCHAR(100) NOT NULL\n);\n\n-- Down migration\nDROP TABLE users;\n```\n\n---\n\n## \u2699\ufe0f Available commands\n\n| Comando | Descrizione |\n|-------------------------------|-------------------------------|\n| `migropy init` | Init migratron environment |\n| `migropy generate <name:str>` | Generate a new sql migration |\n| `migropy upgrade` | Apply all the migration |\n| `migropy downgrade` | Rollback all revisions |\n| `migropy rollback <n:int>` | Rollback n revisions |\n| `migropy list ` | Show current migration status |\n\n---\n\n## \ud83e\uddea Running Unit Tests\n\nTo run the unit tests using poetry, you can use the following command:\n\n```bash\npoetry run pytest --rootdir=tests\n```\n\n---\n\n## \ud83d\udcdd Changelog\n\nSee the full [CHANGELOG.md](https://github.com/fredimatteo/migratron/blob/main/CHANGELOG.md)\n\n### Latest Changes\n\n- **0.3.1** - Code refactor to improve readability and maintainability\n- **0.3.0** - Add rollback command\n- **0.2.2** \u2013 Commands refactor & usage from python code\n- **0.2.1** \u2013 Increase minimum python version to 3.10 & refactor MigrationEngine\n- **0.2.0** \u2013 MySQL database support\n- **0.1.1** \u2013 Initial project setup with PostgreSQL\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! \nTo get started:\n\n1. Fork the repository\n2. Create a new branch (`git checkout -b feature/your-feature`)\n3. Commit your changes\n4. Open a pull request \ud83d\ude80\n\n---\n\n## \ud83d\udceb Support\n\nFor issues, feature requests or general questions, open an issue on [GitHub Issues](https://github.com/fredimatteo/migratron/issues).\n\n\n---\n\n## \ud83d\udcc4 License\n\nMIT License \u00a9 2025 \u2014 teoxy\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Lightweight and extensible Python library for managing database migrations",
"version": "0.3.1",
"project_urls": {
"Homepage": "https://github.com/fredimatteo/migropy/blob/develop/README.md",
"Repository": "https://github.com/fredimatteo/migropy.git"
},
"split_keywords": [
"database",
" migrations",
" postgresql",
" mysql",
" sql",
" cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c6a73bf0c1af56d33c3f58ad4b184b96f9b11e8d2406de15f51f9de9f73caf03",
"md5": "96991449b56f2ac93bea7b37cd5b617e",
"sha256": "bdeba7ad5fe49421aeafd3ece26afd7503e48515c61ab52ea421777233c28d62"
},
"downloads": -1,
"filename": "migropy-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "96991449b56f2ac93bea7b37cd5b617e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.10.0",
"size": 14812,
"upload_time": "2025-07-15T09:12:19",
"upload_time_iso_8601": "2025-07-15T09:12:19.521258Z",
"url": "https://files.pythonhosted.org/packages/c6/a7/3bf0c1af56d33c3f58ad4b184b96f9b11e8d2406de15f51f9de9f73caf03/migropy-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "7102ce389287effa260fb82ada49239601eb6343e00aba36b318347841902b3f",
"md5": "35ecacfdb603a3efb07fe9c5d3311bc1",
"sha256": "01feb495def38527dbddea424d8253f8e7aee52825760bd9d510482708bb88fa"
},
"downloads": -1,
"filename": "migropy-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "35ecacfdb603a3efb07fe9c5d3311bc1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.10.0",
"size": 12607,
"upload_time": "2025-07-15T09:12:20",
"upload_time_iso_8601": "2025-07-15T09:12:20.861410Z",
"url": "https://files.pythonhosted.org/packages/71/02/ce389287effa260fb82ada49239601eb6343e00aba36b318347841902b3f/migropy-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 09:12:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fredimatteo",
"github_project": "migropy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "migropy"
}
JSON
