|
1 | | -# How to Upgrade the Database |
| 1 | +# Database Migrations |
2 | 2 |
|
3 | | -## General Guidelines |
4 | | -Migrations can be inconsistent. To avoid issues, we removed migrations from git repostory. To start the migration on your server, it is recomended reset the migration state on the server and run the migration based on the updated database models when switching application versions via Git. |
| 3 | +ExaFS uses [Flask-Migrate](https://flask-migrate.readthedocs.io/) (Alembic) for database schema management. Migration files are shipped inside the `flowapp` package (`flowapp/migrations/`) and are found automatically — no `flask db init` is needed. |
| 4 | + |
| 5 | +## New Installation |
| 6 | + |
| 7 | +For a fresh database, run the migrations to create all tables and seed data: |
| 8 | + |
| 9 | +```bash |
| 10 | +flask db upgrade |
| 11 | +``` |
| 12 | + |
| 13 | +Or use the init script (source install): |
| 14 | + |
| 15 | +```bash |
| 16 | +python scripts/db-init.py |
| 17 | +``` |
| 18 | + |
| 19 | +Or the installed command (PyPI install): |
5 | 20 |
|
6 | 21 | ```bash |
7 | | -rm -rf migrations/ |
| 22 | +exafs-db-init |
8 | 23 | ``` |
9 | 24 |
|
10 | | -```SQL |
11 | | -DROP TABLE alembic_version; |
| 25 | +## Upgrading Between Versions |
| 26 | + |
| 27 | +When upgrading ExaFS to a new version, apply any new migrations: |
| 28 | + |
| 29 | +```bash |
| 30 | +flask db upgrade |
| 31 | +``` |
| 32 | + |
| 33 | +This will apply only the migrations that haven't been applied yet. |
| 34 | + |
| 35 | +## Existing Installation (One-Time Setup) |
| 36 | + |
| 37 | +If you already have a running ExaFS database from any previous version, the baseline migration is idempotent — it will create missing tables, add missing columns, and skip anything that already exists. |
| 38 | + |
| 39 | +### Deployments that used `flask db init` (self-managed migrations) |
| 40 | + |
| 41 | +Some deployments previously ran `flask db init` to create a local `migrations/` directory and auto-generated migration files. Starting with v1.2.2, migration files are tracked in git and shipped with the project. To switch to the official migrations: |
| 42 | + |
| 43 | +1. **Delete the local migrations directory** created by `flask db init`: |
| 44 | + ```bash |
| 45 | + rm -rf migrations/ |
| 46 | + ``` |
| 47 | + Migrations are now bundled inside the `flowapp` pip package — no local directory needed. |
| 48 | + |
| 49 | +2. **Clear the old alembic_version** and **stamp the baseline** to register with the official migration track (your schema is already up to date): |
| 50 | + ```sql |
| 51 | + DELETE FROM alembic_version; |
| 52 | + ``` |
| 53 | + ```bash |
| 54 | + flask db stamp 001_baseline |
| 55 | + ``` |
| 56 | + |
| 57 | +3. From now on, just run `flask db upgrade` when updating ExaFS. |
| 58 | + |
| 59 | +### Deployments without any migration tracking |
| 60 | + |
| 61 | +If your database has an `alembic_version` table from a previous migration setup but no local `migrations/` directory, clear it first: |
| 62 | + |
| 63 | +```sql |
| 64 | +DELETE FROM alembic_version; |
12 | 65 | ``` |
13 | 66 |
|
| 67 | +Then run the upgrade: |
| 68 | + |
14 | 69 | ```bash |
15 | | -flask db init |
16 | | -flask db migrate -m "Initial migration based on current DB state" |
17 | 70 | flask db upgrade |
18 | 71 | ``` |
19 | 72 |
|
20 | | -## Steps for Upgrading to v1.0.x |
21 | | -Limits for number of rules were introduced. Some database engines (Mariadb 10.x for example) have issue to set Non Null foreigin key to 0 and automatic migrations fail. The solution may be in diferent version (Mariadb 11.x works fine), or to set limits in db manually later. |
| 73 | +The baseline migration will inspect your database and bring it up to the current schema without affecting existing data. |
| 74 | + |
| 75 | +## Upgrading from v0.x to v1.0+ |
22 | 76 |
|
23 | | -To set the limit to 0 for existing organizations run |
| 77 | +If you are upgrading from a pre-1.0 version, the baseline migration will add the missing `org_id` columns and organization limit columns automatically. However, existing rules still need to be linked to organizations. An optional helper script is provided for this: |
24 | 78 |
|
25 | | -```SQL |
26 | | -UPDATE organization |
27 | | -SET limit_flowspec4 = 0, limit_flowspec6 = 0, limit_rtbh = 0 |
28 | | -WHERE limit_flowspec4 IS NULL OR limit_flowspec6 IS NULL OR limit_rtbh IS NULL; |
| 79 | +```bash |
| 80 | +python scripts/migrate_v0x_to_v1.py |
29 | 81 | ``` |
30 | 82 |
|
31 | | -In all cases we need later assign rules to organizations. There's an admin endpoint for this: |
| 83 | +This script: |
| 84 | +1. Sets NULL organization limits to 0 |
| 85 | +2. Helps assign existing rules to organizations based on users' organizations |
| 86 | +3. Reports users with multiple organizations or ambiguous rule ownership that need manual assignment |
| 87 | + |
| 88 | +Feel free to contact [email protected] if you need help with the migration. |
| 89 | + |
| 90 | +## Creating New Migrations |
32 | 91 |
|
33 | | -`https://yourexafs.url/admin/set-org-if-zero` |
| 92 | +When you modify a database model, create a new migration: |
| 93 | + |
| 94 | +```bash |
| 95 | +flask db migrate -m "Description of changes" |
| 96 | +``` |
| 97 | + |
| 98 | +Review the generated file in `flowapp/migrations/versions/`, then apply it: |
| 99 | + |
| 100 | +```bash |
| 101 | +flask db upgrade |
| 102 | +``` |
| 103 | + |
| 104 | +Commit the migration file to git so other deployments can apply it. |
| 105 | + |
| 106 | +## Development Reset |
| 107 | + |
| 108 | +To completely reset the database during development: |
| 109 | + |
| 110 | +```bash |
| 111 | +python scripts/db-init.py --reset # source install |
| 112 | +exafs-db-init --reset # PyPI install |
| 113 | +``` |
34 | 114 |
|
35 | | -Or you can start with clean database and manually migrate data by SQL dump later. Feel free to contact [email protected] if you need help with the DB migration to 1.0.x. |
| 115 | +This drops all tables and recreates them from scratch. **Do not use in production.** |
0 commit comments