Norman Vision v. 0.1.0

[moigagoo]

Norman is CLI to generate and apply migrations for Norm ORM.

Migrations

In Norman terms, migration is a Nim file that contains imperative code that changes the state of the DB. This code is written using Norm ORM.

There are schema migrations and data migrations.

Migrations must be applied in order, therefore the names of the files start with UTC timestamps of their generation.

Migration must contain the code to apply and revert the change.

Migration Structure

There are two code blocks that can be in a migration: apply and revert.

apply block contains the code to apply the migration:

apply:
   import models

   MyModel.renameTableFrom "oldName"

revert block contains the code to revert the migration:

revert:
  import models

  MyModel.renameTableFrom "newName"

The Near and the Far Future

In the first version, Norman will not generate the migration code. It will just create properly named files for the programmer to fill in and focus on migration application.

In the future iterations, Norman will generate both apply and revert block by analyzing model diffs.

Project Structure

In order to generate any code, Norman must know where to look for the model definitions. By default, src/models.nim is assumed.

The DB credentials are stored in norman.nims.

Commands

• norman init generates migrations folder and a file to set up the DB:

import models

apply:
  withDb(dbHost, dbUser, dbPassword, dbDatabase):
    createTables(force=true)

revert:
  discard

• norman new generates a file in migrations with placeholder code:

import modes

apply:
  discard

revert:
  discard

• norman migrate applies all unapplied migrations one by one by calling their apply blocks. If any migration fails, the entire process is reverted by calling revert blocks in the reverse order.

A special table is created by Norman under the hood to keep track of the applied migrations in the DB itself.

• norman revert <migration> reverts all migrations up to the given one including it.