migrate-env

Django-style migrations for environment files.

Your .env.example is the source of truth (like models.py). When it changes, makemigrations detects what was added and writes a numbered, reviewable migration. Each developer runs migrate against their own .env, which gains the new blocks and variables without ever touching the values they already have.

pip install migrate-env

Quick start

# Detect changes in .env.example and write env_migrations/0001_initial.py
migrate_env makemigrations

# Apply pending migrations to your local .env (creates it if missing)
migrate_env migrate .env

# See what's applied
migrate_env showmigrations .env

Later, someone adds a Postgres section to .env.example:

migrate_env makemigrations --name postgres
# Created env_migrations/0002_postgres.py
#   - Create assignment block [WHYHC_POSTGRES_DB, WHYHC_POSTGRES_USER, ...]

Everyone else pulls and runs migrate_env migrate .env. Their custom secret keys, hosts, and passwords are untouched; the new block is appended.

The data model

An env file is a sequence of blocks, and is byte-for-byte reconstructible from them:

• CommentBlock — leading blank lines + comment lines.
• AssignmentBlock — leading blank lines + comment lines + assignments.

An Assignment is (Key, Value, Comment | Blank) — the third element is the inline trailing comment (' # like this') or ''. A commented-out assignment such as # WHYHC_CONN_MAX_AGE=0 is parsed as an assignment with enabled=False, representing an optional variable. Prose comments that merely mention FOO=bar mid-sentence, or use spaces around =, remain comments.

from migrate_env import parse

env = parse(open(".env.example").read())
env.render() == open(".env.example").read()  # True, always

Migrations

Migrations are plain Python modules, ordered by numeric prefix with validated dependencies:

# env_migrations/0002_postgres.py
from migrate_env import migrations, ops

class Migration(migrations.Migration):
    dependencies = ['0001_initial']
    operations = [
        ops.CreateAssignmentBlock(
            comments=['# PostgreSQL database connection'],
            assignments=[
                ops.Assignment(key='WHYHC_POSTGRES_DB', value='whyhc'),
                ops.Assignment(key='WHYHC_POSTGRES_PORT', value='5432'),
            ],
        ),
    ]

Operations are additive and idempotent:

• CreateAssignmentBlock / CreateCommentBlock — append a block (skipped if its content already exists).
• AddAssignments — append variables to an existing block, located by an anchor key= or comment=. Keys the user already has anywhere in their file are skipped, so values are never overwritten.
• AddComments — append documentation comments to an existing block.

Value changes and removals in .env.example are reported as warnings by makemigrations but never auto-migrated — users own their values, and destructive changes deserve a hand-written migration.

Applied state per target file lives in a sidecar (.env.migrations, the analog of Django's django_migrations table). Add it to .gitignore alongside .env.

Commands

Development

To contribute to this library, first checkout the code. Then create a new virtual environment:

cd migrate-env
python -m venv venv
source venv/bin/activate

Now install the dependencies and test dependencies:

python -m pip install -e '.[dev]'

To run the tests:

python -m pytest

License

Apache 2.0