PackageDescription: GlorpMigration

Glorp Migration

Last published: August 4, 2010 by 'jkott'

Defines 26 Classes
Extends 42 Classes

The package allows migrating from one schema version to another. The migration steps include
- creating a new database schema descriptor
- calculating changes between database schema versions
- applying changes to a database

Creating a new version of a database descriptor system.

MyDescriptorSystem newDatabaseSchema: 'MyDescriptorSystem_V1'.
The MyDescriptorSystem_V1 class will include all methods that describe tables from MyDescriptorSystem and a new method #migrationAncestor that returns the MyDescriptorSystem. This method is used to calculate the migration path.

For example.
Load the WVExample-BlogServer package and execute:
BlogDatabaseSchema newDatabaseSchema: ' MyBlogDatabaseSchema_v1'.
There is MyBlogDatabaseSchema_v1 created in the WVExample-BlogServer package.


In the new cloned version you can do some changes in the database schema and then migrate your database to a new version.

Let's do some changes in your new class MyBlogDatabaseSchema_v1. For example you can add the new #filler column to your database table POSTS:
tableForPOSTS: aTable

(aTable createFieldNamed: 'id' type: platform serial) bePrimaryKey.
aTable createFieldNamed: 'title' type: (platform varchar: 200).
aTable createFieldNamed: 'content' type: platform text.
aTable createFieldNamed: 'created' type: platform timestamp.
aTable createFieldNamed: 'filler' type: ( platform varchar: 20 )

Now we can migrate to the new database schema.
The migration API allows you to generate a migration script, review and update it before applying the schema changes to a database.

To run our example now we need a database connection.
Glorp.GlorpDatabaseLoginResource defaultLogin:
((Login new)
database: PostgreSQLPlatform new;
username: 'user';
password: 'xxxx';
connectString: 'localhost:5432_postgres').
DatabaseAccessor loggingEnabled: true. <-- it helps to see the SQL statements in the system transcript.

Initialize the source description system:
session := BlogDatabaseSchema sessionForLogin: GlorpDatabaseLoginResource current login.
sourceDescriptorSystem := session system.

If your database doesn't have the POSTS and COMMENTS tables to run the example you need the create tables from the descriptor system.
session recreateTables.
Create an instance of the database descriptor we are going to migrate to:
sourceDescriptorSystem := (MyBlogDatabaseSchema_v1 sessionForLogin: GlorpDatabaseLoginResource current login) system.

Create a migration script to migrate from BlogDatabaseSchema to MyBlogDatabaseSchema_v1:
sourceDescriptorSystem createDefaultMigrationScriptFor: destinationDescriptorSystem.

There is a new method in BlogDatabaseSchema:
migrationScriptTo MyBlogDatabaseSchema_v1: aMigrationChangeSet

aMigrationChangeSet addFieldNamed: 'filler' toTableNamed: 'posts'.

You can modify the script before applying the schema changes to a database. Additional script API can be found in the MigrationChangeSet class in protocols such as 'api - add/drop field', 'api - add/drop foreign key' and etc.

Having the migration script you can migrate to a new version:
sourceDescriptorSystem migrateTo: destinationDescriptorSystem.