{"id":13536857,"url":"https://github.com/gavsidhu/miflo","last_synced_at":"2025-10-27T06:31:48.159Z","repository":{"id":213451867,"uuid":"733836259","full_name":"gavsidhu/miflo","owner":"gavsidhu","description":"A database schema migration tool. Supports SQLite, PostgreSQL, and libSQL.","archived":false,"fork":false,"pushed_at":"2024-02-02T05:36:49.000Z","size":60,"stargazers_count":18,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-01T03:14:52.111Z","etag":null,"topics":["cli","database-migrations","database-schema","go","golang","migrations","postgresql","sql","sqlite","sqlite3","turso"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gavsidhu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-12-20T08:37:29.000Z","updated_at":"2024-12-21T04:30:07.000Z","dependencies_parsed_at":"2024-02-02T06:44:57.607Z","dependency_job_id":null,"html_url":"https://github.com/gavsidhu/miflo","commit_stats":null,"previous_names":["gavsidhu/miflo"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavsidhu%2Fmiflo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavsidhu%2Fmiflo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavsidhu%2Fmiflo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gavsidhu%2Fmiflo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gavsidhu","download_url":"https://codeload.github.com/gavsidhu/miflo/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238455057,"owners_count":19475369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","database-migrations","database-schema","go","golang","migrations","postgresql","sql","sqlite","sqlite3","turso"],"created_at":"2024-08-01T09:00:50.657Z","updated_at":"2025-10-27T06:31:47.806Z","avatar_url":"https://github.com/gavsidhu.png","language":"Go","funding_links":[],"categories":["Tools"],"sub_categories":["Community"],"readme":"# Miflo\n\n[![Release](https://img.shields.io/github/release/gavsidhu/miflo.svg)](https://github.com/gavsidhu/miflo/releases) [![Miflo CI/CD](https://github.com/gavsidhu/miflo/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/gavsidhu/miflo/actions/workflows/ci-cd.yml) [![Go Report](https://goreportcard.com/badge/github.com/gavsidhu/miflo)](https://goreportcard.com/report/github.com/gavsidhu/miflo)\n\nMiflo is a database schema migration tool designed to simplify database schema changes for SQLite, PostgreSQL, and libSQL databases.\n\n## Motivation\nI often use [Turso](https://turso.tech/) (built on top of [libSQL](https://github.com/tursodatabase/libsql)) as my database for personal project. I wanted a way to keep track of my database changes as I developed my projects but couldn't find a tool that specifically worked with Turso so I created Miflo. I also made it work with PostgreSQL and SQLite since I use those databases aswell.\n\n## Table of Contents\n- [Installation](#installation)\n- [Commands](#commands)\n- [Usage](#usage)\n  - [Connect Your Database](#connect-your-database)\n    - [SQLite](#sqlite)\n    - [PostgreSQL](#postgresql)\n    - [libSQL](#libsql)\n      - [Turso](#connecting-to-a-turso-database-instance)\n      - [sqld](using-sqld)\n  - [Create a migration](#Create-a-migration)\n  - [Apply Migrations](#apply-migrations)\n  - [Revert Migrations](#revert-migrations)\n  - [List Migrations](#list-migrations)\n- [Migrations](#migrations)\n  - [Migration files](#migration-files)\n  - [Migrations table](#migrations-table)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Installation\n\n**Mac**\n\nInstall miflo on Mac by running the following command in your terminal:\n\n```sh\ncurl -sSL https://github.com/gavsidhu/miflo/raw/main/scripts/install-mac.sh | bash\n```\n\n**Linux**\n\nInstall miflo on Mac by running the following command in your terminal:\n\n```sh\ncurl -sSL https://github.com/gavsidhu/miflo/raw/main/scripts/install-linux.sh | bash\n```\n\n## Usage\n\n### Connect Your Database\n\nTo connect your database using miflo, you need to set the DATABASE_URL in your .env file. This URL specifies the database type and its connection details. The format of the DATABASE_URL varies based on the type of database you are connecting to. Here's how you can set it up for each supported database:\n\n#### SQLite\n\nFor SQLite, the DATABASE_URL is set using `sqlite:` followed by the path to your database file. Example:\n\n```env\nDATABASE_URL=sqlite:/path/to/your/databasefile.db\n```\n\n#### PostgreSQL\n\nFor connecting to a PostgreSQL database, the URL is formatted as `postgresql://username:password@host:port/database_name`. Replace the placeholders with your actual PostgreSQL database credentials. Example:\n\n```env\nDATABASE_URL=postgresql://user:password@localhost:5432/mydatabase\n```\n\n#### libSQL\n\nFor connecting to a libSQL database, miflo supports two protocols: HTTP and a custom libsql protocol. The appropriate protocol to use depends on your specific database setup.\n\n##### Connecting to a Turso Database Instance\n\n- If you are connecting to a Turso database instance, use the libsql protocol. The URL should be in the format `libsql://your_turso_database_url?authToken=your_auth_token`. Example:\n\n```env\nDATABASE_URL=libsql://your-db-instance.turso.io?authToken=yourActualAuthTokenHere\n```\n\n##### Using sqld\n\n- When using sqld, the connection URL should use the HTTP protocol. The format will be something like `http://your_sqld_host:port`. Example:\n\n```env\nDATABASE_URL=http://127.0.0.1:8080\n```\n\n### Create a migration\n\nCommand: `miflo create [migration_file_name]`\n\n- **Function**: The `create` command creates a new migration directory `[timestamp]_[migration_file_name]` in the migrations directory in the root of your project.\n- **Migration Folder**: If a `migrations` folder doesn't exist at the root, miflo will prompt you to create one.\n- **Genereated Files**: The command creates two SQL files in the new directory:\n  - `up.sql` for applying the migration.\n  - `down.sql` for reverting the migration.\n- **Valid Migration Name**:\n  - Migration names must adhere to a specific pattern. They should only contain letters (A-Z, a-z) and underscores (_).\n\nExample:\n\n```sh\nmiflo create add_users_table\n```\n\n### Apply migrations\nCommand: `miflo up`\n\n- **Function** The `up` command applies all pending migrations. The migrations are applied in order of creation.\n- **Execution**: miflo reads the `up.sql` files in each migration directory and executes the SQL statements contained within. These up.sql files define the changes to be made to the database schema.\n\n```sh\nmiflo up\n```\n\n### Revert migrations\nCommand: `miflo revert`\n\n- **Function**: The `revert` command is used to roll back applied migrations.\n- **Revert Order**: Migrations are reverted in reverse order meaning the last applied migration is the first to be reverted.\n- **Batch Operation**: This command uses batches. A batch is a group of migrations applied together during a single `miflo up` execution. `miflo revert` will only roll back the migrations of the last batch.\n- **Execution**: miflo reads the `down.sql` files in each migration directory of the latest batch. These `down.sql` files contain SQL statements that undo the changes made by the corresponding `up.sql` files.\n\n```sh\nmiflo revert\n```\n\n### List migrations\nCommand: `miflo list`\n\n- **Function**: The `list` command lists all pending migrations.\n\n```sh\nmiflo list\n```\n\n## Migrations \n\n### Migration Files\n\nWhen a new migration is created using the miflo create command, it generates two SQL files in a dedicated directory for that migration. \n\n`up.sql`\n- **Purpose**: The up.sql file is used for applying the migration. It contains SQL statements that modify the database schema, such as creating tables, adding columns, or other schema alterations.\n- **Usage**: When you run the `miflo up` command, miflo executes the SQL statements in the `up.sql` files of each pending migration, in the order they were created. This process updates your database schema to the new desired state.\n- **Content**: The content of an `up.sql` file typically includes `CREATE TABLE`, `ALTER TABLE`, `ADD COLUMN` statements, and other SQL commands that incrementally change the database structure.\n\n`down.sql`\n- **Purpose**: The down.sql file is used for reverting the migration. It contains SQL statements that undo the changes made by the up.sql file.\n- **Usage**: When you run the `miflo revert` command, miflo executes the SQL statements in the `down.sql` files of the most recent batch of applied migrations, in reverse order. This process rolls back the latest changes made to your database schema.\n- **Content**: The content of a `down.sql` file typically includes `DROP TABLE`, `DROP COLUMN`, and other SQL commands that reverse the changes made by the corresponding `up.sql`.\n\nExample:\nFor a migration named `create_users_table`, the directory structure would be something like this:\n\n```sh\n/migrations\n  /1704662056_create_users_table\n    - up.sql\n    - down.sql\n```\n\n### Migrations table\n\nWhen you first use miflo to connect to your database, a table named `miflo_migrations` is automatically created. This table helps manage and track the state of database migrations.\n\n**Table Columns**\n- **id**: Serves as a unique identifier for each migration entry.\n- **name**: Stores the name of the migration file. This is unique for each migration to prevent duplicate entries and to easily identify each migration.\n- **batch**: Indicates the batch number in which the migration was applied. Migrations applied together in a single miflo up execution share the same batch number.\n- **applied**: A boolean flag indicating whether the migration has been applied (true) or not (false).\n- **applied_at**: Timestamp of when the migration was applied. It defaults to the current timestamp at the time of migration application.\n\n## Contributing\n\nIf you want to contribute to miflo and make it better, your help is very welcome.\n\n**Reporting Bugs**: If you encounter any bugs, please report them by opening a new issue.\n\n**Suggesting Enhancements**: Got ideas to improve miflo? Feel free to open a new issue for discussion.\n\n**Code Contributions**: You're welcome to fork the repository and submit pull requests.\n\n**Testing with Databases**: To test miflo, you'll need to run Docker Compose, which will set up the necessary database environments for testing.\n\n## License\n\nCopyright 2023 Gavin Sidhu\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgavsidhu%2Fmiflo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgavsidhu%2Fmiflo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgavsidhu%2Fmiflo/lists"}