apimigrations

Migrations

Migrations are Coldfusion Components (CFCs) that describe a list of commands to build or modify the database structure (migrating up) along with commands to reverse those changes (migrating down).

Folder location

Migration files should be stored in a folder under your application root named /db/migrate. Once the migrations have been run, the generated SQL code will be saved in a folder named /db/sql. You will want to ensure these folders are not uploaded to your production server, or at least protected from public access.

File naming

Migration files should be labeled sequentially with either a numeric or timestamp (yyyymmddhhmmss) prefix followed by a description of the migration. (e.g. a migration file that creates a users table could be named 001_users.cfc or 20100101123000_users.cfc).

The sequential 3 digit numbering can be more readable, however timestamping migration files can be a better option when you have multiple developers working on the project at the same time and don't want conflicting version numbers when committing code.

Migration code

Migration CFCs need to extend plugins.dbmigrate.migration. Note that if your application is running in a sub folder beneath your webroot, you will need to provide a component path relative to your webroot, e.g. appname.plugins.dbmigrate.migration or create a Coldfusion mapping.

Provide a descriptive hint attribute for the tag to indicate what this migration does.

Each migration CFC needs to define an up function that modifies the database structure and a down function to reverse those changes, allowing you to migrate back to a previous version of the database.

Your migration CFC code will look something like this:

<cfcomponent extends="plugins.dbmigrate.migration" hint="migration description">
  <cffunction name="up">
    <cfscript>
    
    </cfscript>
  </cffunction>
  <cffunction name="down">
    <cfscript>
    
    </cfscript>
  </cffunction>
</cfcomponent>

Available functions

Here are the functions available to you to modify your database:

Table functions

• createTable
• changeTable
• renameTable
• dropTable

Column functions

• addColumn
• changeColumn
• renameColumn
• removeColumn

Foreign key functions

• dropReference
• dropForeignKey

Index functions

• addIndex
• removeIndex

Miscellaneous functions

• execute
• announce

Record functions

Note these may be removed later on in favor of direct access to CFWheels models or a Fixtures plugin.

• addRecord
• updateRecord
• removeRecord