Metadata-Version: 2.1
Name: xtmigrations
Version: 1.0.3
Summary: Fast and easy to use database migration tool for Postgresql, written in Python
Home-page: https://github.com/startechm/xtmigrations
Author: Startech M
Author-email: startechm@proton.me
License: Apache license 2.0
Keywords: XTMigrations migration sql db upgrade
Description-Content-Type: text/markdown
License-File: LICENSE

# XTMigrations
A fast and easy to use database migration tool for Postgresql, written in Python.
This tool helps you keep track of changes in your database.
---

### Let's assume you have an `employees` table with the fields `id` and `first_name`.
### You would create a new "migration" as follow:

```bash
$ migrate new my first migration
Migration file generated sql/20221012_234403_996058_my_first_migration.sql
```

### You would edit the file `sql/20221012_234403_996058_my_first_migration.sql` as follow:
```text
# Autogenerated: sql/20221012_234403_996058_my_first_migration.sql

@Up
# Your Up migration goes here (this section describes the database changes you want to apply)
CREATE TABLE employees (id BIGSERIAL, first_name VARCHAR(100));

@Down
# Your Down migration goes here (this section is to "undo" the change in the "Up" section above)
DROP TABLE employees;
```

### To apply your changes you would just run
```
$ migrate up
$ migrate status   # to show your changes
----------------------------------------------- - --------------------
| Name                                          |   Status           |
----------------------------------------------- - --------------------
| init                                          |   Applied          |
| 20221012_234403_996058_my_first_migration     |   Applied.         |
----------------------------------------------- - --------------------
```

### On your next software release, you decide that you want to add an `email` field, you would just do the following
```bash
$ migrate new adding email field
Migration file generated sql/20221012_234936_024571_adding_email_field.sql
```

### You just edit the file `sql/20221012_234936_024571_adding_email_field.sql`
```text
# Autogenerated: sql/20221012_234936_024571_adding_email_field.sql

@Up
# Your Up migration goes here
ALTER TABLE employees ADD COLUMN email VARCHAR(255) DEFAULT NULL;

@Down
# Your Down migration goes here
ALTER TABLE employees DROP COLUMN email;
```

### Before applying the change, you can check the state of your database:
```
$ migrate status
----------------------------------------------- - --------------------
| Name                                          |   Status           |
----------------------------------------------- - --------------------
| init                                          |   Applied          |
| 20221012_234403_996058_my_first_migration     |   Applied          |
| 20221012_234936_024571_adding_email_field     |   Pending...       |
----------------------------------------------- - --------------------
```

### You then apply the new change
```
$ migrate up
```

### If for some reason, you decide to remove the change, you can *undo* the migration
```
$ migrate down
```

### You can also undo multiple migrations.  For example, if you want to undo 2 migrations, you would simply run
```
$ migrate down 2
```
---

### Installation

Via [`pip`](https://pypi.org/project/xtmigrations/)(python 3+ supported)
```
$ pip install xtmigrations
```

If you have virtualenv, make sure to run source ~/<virtualenv_folder/bin/activate to be able to have access to the "migrate" command.

### To initialize a new migrations directory structure
Go to your project folder (e.g. /Users/myuser/Projects/my_project/) and run
```
$ migrate init
```
### this will create a new migrations/ directory structure.

### Now go inside migrations/ folder
```
$ cd migrations
```

###  Configure config/db.cnf with your database settings
Once it is configured, try to run the following command to make sure that xtmigrations is able to connect to your database.
```
migrate status
```

### To create a new migration, run the following (no quotes needed)
```
$ migrate new my first feature
```
This will create a new migration SQL file under sql/ folder.

### Make sure to edit the new sql file.  There is a @Up and a @Down section.
### Keep in mind that your SQL inside @Down section should *undo* the database change defined in the @Up section.

###  Apply the migration
```
$ migrate up
```

### To unapply a migration, run the following:
```
$ migrate down
```
---

### Usage
```
migrate <init | status | new <title> | up [number of migrations to apply] | down [number of migrations to unapply]
```
    
Note: [number of migrations to apply/unapply can be 0 which means "all"]
    

### No warranty is implied or expressed. This software is provided "AS-IS".  Use at your own risk.

### For any question or support, please contact me at startechm@proton.me

