GitHub

Database Migrations in PormG

PormG provides a simple way to manage database schema changes through migrations, inspired by Django but tailored for Julia and PostgreSQL workflows.

What Are Migrations?

Migrations are version-controlled scripts that describe changes to your database schema. They allow you to:

  • Create new tables and fields
  • Alter or remove existing fields
  • Apply incremental changes
  • Keep your database schema in sync with your Julia models

Main differences from Django

PormG analyzes your PostgreSQL database, compares it to your Julia models directly, and generates a migration plan. This approach ensures your database and models stay in sync, but always review the plan for safety. If this approach works fine, the advantage is that you can directly see the differences between your models and the database schema, making it easier work with a large number of developers and changes.

Migration Workflow

  1. Define Your Connection
  • By default, PormG uses the db as folder to store connection.yml, migration files, and models, but you can specify a different folder by different data base, for example db_2.
  • For more information on configuring your connection, see the Configuration Documentation.
  1. Define Your Models
  • If you add the information about your database in folder db_2, in file db_2/connection.yml, you should also edit your models in db_2/models.jl (or your chosen models file).
  1. Generate Migrations
  • Run the migration generator to detect changes and create migration scripts:
    PormG.Migrations.makemigrations("db_2")
  • This will generate migration files in db_2/migrations/pending_migrations.jl.
  1. Review Pending Migrations
  • Always review the generated migration plan before applying it, especially in production environments.
  • Remember, PormG.jl is in initial stages, so some features may not be fully implemented or tested.
  1. Apply Migrations
    • Apply the migrations to your database:
      PormG.Migrations.migrate("db_2")
    • Applied migrations are moved to db_2/migrations/applied_migrations/.

Example: Full Migration Script

Below is an example script to create and migrate your database:

using Pkg
Pkg.activate(".")
using PormG
PormG.Configuration.load("db_2")
PormG.Migrations.makemigrations("db_2")
PormG.Migrations.migrate("db_2")

Best Practices

  • Incremental Changes: Make small, incremental changes to your models and run migrations frequently.
  • Review Plans: Always review pending migrations before applying.
  • Version Control: Commit your migration files to version control for reproducibility.
  • Backups: Back up your database before applying migrations in production.

For more details, see the PormG Documentation or the example scripts in the test/pg/ folder.