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.


Migration.

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.