<p align="center">
<img src="./.imgs/logo.png" align="center" width="50%">
</p>
<p align="center">
<img src="https://img.shields.io/github/license/mstjr/migro?style=default&logo=opensourceinitiative&logoColor=white&color=0080ff" alt="license">
<img src="https://img.shields.io/github/last-commit/mstjr/migro?style=default&logo=git&logoColor=white&color=0080ff" alt="last-commit">
<img src="https://img.shields.io/github/languages/top/mstjr/migro?style=default&color=0080ff" alt="repo-top-language">
<img src="https://img.shields.io/github/languages/count/mstjr/migro?style=default&color=0080ff" alt="repo-language-count">
</p>
<p align="center">
</p>
<p align="center">
</p>
<br>
## Table of Contents
- [ Overview](#-overview)
- [ Features](#-features)
- [ Project Structure](#-project-structure)
- [ Project Index](#-project-index)
- [ Getting Started](#-getting-started)
- [ Prerequisites](#-prerequisites)
- [ Installation](#-installation)
- [ Usage](#-usage)
- [ Project Roadmap](#-project-roadmap)
- [ Contributing](#-contributing)
- [ License](#-license)
- [ Acknowledgments](#-acknowledgments)
---
## Overview
Migro is a lightweight CLI tool for managing PostgreSQL database migrations in Rust projects. It provides a simple and intuitive way to:
- Create and manage migration files with automatically versioned naming (not using timestamps)
- Run migrations in both up and down directions
- Seed databases with test or initial data
- Organize custom SQL queries (for syntax highlighting and better readability)
- The tool follows a structured approach to database versioning, allowing teams to track schema changes and maintain consistency across development, testing, and production environments.
Migro creates and manages a directory structure with migrations, seeders, and custom queries, and automatically tracks applied migrations in a database table to ensure idempotent operations. This makes it easy to bring new environments up to date or roll back changes when needed.
With a simple command-line interface, Migro integrates easily into development workflows and CI/CD pipelines, providing essential database management capabilities for Rust applications that use PostgreSQL.
/!\ This project is in its early stages and is not yet production-ready, it does not have any last migration rollback feature yet /!\
---
## Features
- **Versioned Migrations**: Automatically generates sequential version numbers for migrations, ensuring they run in the correct order
- **Bidirectional Migrations**: Support for both up (applying) and down (reverting) migrations
- **Database Seeding**: Built-in functionality to populate your database with test or initial data
- **SQL Query Organization**: Create and manage custom SQL queries with proper directory structure
- **Idempotent Operations**: Tracks applied migrations in a database table to ensure they're only run once
- **Simple CLI Interface**: Intuitive commands for creating, running, and reverting migrations
- **Library Integration**: Use as both a CLI tool or a library in your Rust projects
- **PostgreSQL Support**: Designed specifically for PostgreSQL databases
- **Environment Variable Configuration**: Uses standard DATABASE_URL environment variable for connections
- **Error Handling**: Robust error handling with detailed context to help troubleshoot issues
- **Logging**: Structured logging with tracing library for better visibility into migration operations
- **Simple Project Structure**: Creates a clean, organized directory structure for your database files
The tool supports the following commands:
- `init`: Initialize the migrations, seeders, and queries directories
- `create`: Create new migration, seeder, or query files with automatic versioning
- `up`: Run all pending migrations (with optional seeding)
- `down`: Revert all applied migrations
- `seed`: Manually run all seeders
---
## Project Structure
```sh
└── migro/
├── Cargo.lock
├── Cargo.toml
├── LICENSE
├── README.md
└── src
├── lib.rs
└── main.rs
```
---
## Getting Started
### Prerequisites
Before getting started with migro, ensure your runtime environment meets the following requirements:
- **Programming Language:** Rust (to use the library)
- **Package Manager:** Cargo
### Installation
Install migro using one of the following methods:
**Install using crates.io:**
1. Install the migro CLI tool using Cargo:
```sh
cargo install migro
```
**Build from source:**
1. Clone the migro repository:
```sh
git clone https://github.com/mstjr/migro
```
2. Navigate to the project directory:
```sh
cd migro
```
3. Install the project dependencies:
**Using `cargo`** [<img align="center" src="https://img.shields.io/badge/Rust-000000.svg?style={badge_style}&logo=rust&logoColor=white" />](https://www.rust-lang.org/)
```sh
cargo build
```
### Usage
Run migro using the following command:
**Using `cargo`** [<img align="center" src="https://img.shields.io/badge/Rust-000000.svg?style={badge_style}&logo=rust&logoColor=white" />](https://www.rust-lang.org/)
```sh
cargo run
```
---
## Contributing
- **🐛 [Report Issues](https://github.com/mstjr/migro/issues)**: Submit bugs found or log feature requests for the `migro` project.
- **💡 [Submit Pull Requests](https://github.com/mstjr/migro/pulls)**: Review open PRs, and submit your own PRs.
<details closed>
<summary>Contributing Guidelines</summary>
1. **Fork the Repository**: Start by forking the project repository to your github account.
2. **Clone Locally**: Clone the forked repository to your local machine using a git client.
```sh
git clone https://github.com/mstjr/migro
```
3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name.
```sh
git checkout -b new-feature-x
```
4. **Make Your Changes**: Develop and test your changes locally.
5. **Commit Your Changes**: Commit with a clear message describing your updates.
```sh
git commit -m 'Implemented new feature x.'
```
6. **Push to github**: Push the changes to your forked repository.
```sh
git push origin new-feature-x
```
7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. **Review**: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!
</details>
<details closed>
<summary>Contributor Graph</summary>
<br>
<p align="left">
<a href="https://github.com{/mstjr/migro/}graphs/contributors">
<img src="https://contrib.rocks/image?repo=mstjr/migro">
</a>
</p>
</details>
---
## License
This project is protected under the MIT License. For more details, refer to the LICENSE file.
---