MyBatis 3 – Schema Migration System Ur Guide
NOTE: This guide is not about migrating from older versions of MyBatis. It is a manual about a tool that will change the way you manage changes to your databa.
MyBatis 3 Migrations
Introduction
抒写和书写的区别
Evolving databas has been one of the major challenges for software development. Often times, regardless of our software development methodology, the databa follows a different change management process. Despite our best efforts, few tools and practices have been able to change that. The tools of the past have been GUI centric, proprietary for a particular databa and/or carried a steep licen cost. Yet, at the end of the day they suffered from the same challenges.
Recently, a few tools arrived and changed all of that. They did so by embracing simplicity and a few simple rules for databa evolution to follow. A couple of good examples are Rails Migrations and dbdeploy. Both tools are similar in purpo, but quite different in implementation. The MyBatis Schema Migration System draws from both and eks to be the best migration tool of its kind.
Goals
To achieve a good databa change management practice, we need to identify a few key goals.
Thus, the MyBatis Schema Migration System (or MyBatis Migrations for short) eks to:
•Work with any databa, new or existing
•Leverage the source control system (e.g. Subversion)
•Enable concurrent developers or teams to work independently
•Allow conflicts very visible and easily manageable
•Allow for forward and backward migration (evolve, devolve respectively)
•Make the current status of the databa easily accessible and comprehensible
•Enable migrations despite access privileges or bureaucracy
•Work with any methodology
•Encourages good, consistent practices
Installation
缂丝
Installation is simply a matter of unzipping the package to a directory of your choosing. There are generally two ways to work with this tool:
法海无边
•Unzip it to a central location. Add MIGRATIONS_HOME to your environment variables, and add MIGRATIONS_HOME to your path. This is a common option, popular among similar tools like
Ant or Maven.
•Unzip it into a directory in your workspace for a project that you’re currently working on, thus keeping all of the dependencies and the tool version isolated within the project. It’s a small
framework, and this option has the advantage of portability and zero tup for developers new to the project.
What’s Included?
The MyBatis Migrations package is small and simple. The following is the contents of the unzipped package:
新疆民俗
./lib/mybatis-3-core-3.0.0.188.jar
./migrate
.d
The single MyBatis JAR file is the only dependency that MyBatis Migrations has. The two script files do the same thing, but as you can e, one is for *nix shells and the other is for Windows (Note: cygwin urs should still call the .cmd version).
The ‘migrate’ Command
The entire Migrations system can be accesd through this one simple command. You can access the built-in help by typing: migrate --help
Calling the migrate command with no options or invalid options also produces the help message. Here’s the output of the help command:
Usage: migrate command [parameter] [--path=<directory>] [--env=<environment>]
--path=<directory> Path to repository. Default current working directory.
--env=<environment> Environment to configure. Default environment is 'development'.
--force Forces script to continue even if SQL errors are encountered.
--help Displays this usage message.
--trace Shows additional error details (if any).
Commands:
init Creates (if necessary) and initializes a migration path.
bootstrap Runs the bootstrap SQL script (e scripts/bootstrap.sql for more).
new <description> Creates a new migration with the provided description.
up Run all unapplied migrations.
down Undoes the last migration applied to the databa.
version <version> Migrates the databa up or down to the specified version.
pending Force executes pending migrations out of order (not recommended).
status Prints the changelog from the databa if the changelog table exists.
script <v1> <v2> Generates a delta migration script from version v1 to v2 (undo if v1 > v2).
We’ll go through each of the commands in detail, but first, let’s talk about lifecycle.
The MyBatis Migrations Lifecycle
Databa change management is difficult at the best of times, so to make the situation better, it’s important to have a good databa evolution strategy. That employed by MyBatis Migrations targets a few key goals:
•Consistent – The schema should be predictable on every machine it’s created on.
•Repeatable – The schema can be destroyed and recreated a predictable way.
•Reversible – Changes should be able to be rolled back, or undone.
•Versioned – The version of the schema should be identifiable (via query or tool).
•Auditable – The schema evolution should be auditable and the changes to it logged.
•Automated – The evolution (or devolution) of the schema should be fully automated.
•Serial – The evolution in the databa should never branch or evolve conditionally.
•Immutable Changes – No past applied alter or evolution of the databa should be modified, instead a new change should be created.
•Concurrently Modifiable – The schema should be safely modifiable by multiple people or teams in a way that encourages teamwork, communication and easy identification of conflicts, without depending on text comparisons (diff) or any particular source control feature (conflicts), but
should work very well with source control systems.
Thus, the lifecycle of a schema managed with MyBatis Migrations is as follows:
1.Initialize Repository
2.Bootstrap databa schema
3.Create a new migration (or many migrations)
4.Apply migrations
文韬武略的意思Optional steps include:
•Revert migrations if necessary to resolve conflicts
•Apply pending migrations out of order if it’s safe to do so
•Generate migration scripts to be run “offline” in environments that are beyond your control •Get the status of the system at any time
The following command discussions will provide more detail about how this lifecycle works.
init
The init command initializes a new ‘migration path’, also called a ‘repository’ (of migration scripts). Regardless of whether your working with a new databa or an existing one, you’ll run init to create the workspace in which you’ll place everything you need to manage databa change. Running this command will create the directory specified by the --path option (which is the current working directory by default).
小乌龟歌词Here’s an example of running the init command:
/$ migrate --path=/home/cbegin/testdb init
醉花间If I was already in the /home/cbegin/testdb directory, I could simply run:
/home/cbegin/testdb$ migrate init
When the command is completed, the directory will contain the following sub-directories:
./drivers
Place your JDBC driver .jar or .zip files in this directory. Upon running a migration, the drivers will be dynamically loaded.
./environments
In the environments folder you will find .properties files that reprent your databa instances. By default a development.properties file is created for you to configure your development time databa properties. You can also create test.properties and production.properties files. Details about the properties themlves follow later in this document. The environment can be specified when running a migration by using the --env=<environment> option (without the path or ".properties" part).
The default environment is "development". The properties file is lf documented, but here it is for reference:
## Ba time zone to ensure times are consistent across machines time_zone=GMT+0:00
## The character t that scripts are encoded with
# script_char_t=UTF-8
## JDBC connection properties.
driver=
url=
urname=
password=
# Name of the table that tracks changes to the databa
changelog=CHANGELOG
# If t to true, each statement is isolated
# in its own transaction. Otherwi the entire
# script is executed in one transaction.
auto_commit=fal
# This controls how statements are delimited.
# By default statements are delimited by an
# end of line micolon. Some databas may
# (e.g. MS SQL Server) may require a full line
# delimiter such as GO.
delimiter=;
full_line_delimiter=fal
# This ignores the line delimiters and
# simply nds the entire script at once.
# U with JDBC drivers that can accept large
# blocks of delimited text at once.
nd_full_script=fal
# Custom driver path to avoid copying your drivers
# driver_path=
./scripts
This directory contains your migration SQL files. The are the files that contain your DDL to both upgrade and downgrade your databa structure. By default, the directory will contain the script to create the changelog table, plus one empty example migration script. To create a new migration script, u the "new" command. To run all pending migrations, u the "up" command. To undo the last migration applied, u the "down" command etc.
兔子新娘
bootstrap
If you’re working from an existing databa, you need to start from a known state. There’s no point in trying to rewind time and shoehorn your existing databa into a ries of migration scripts. It’s more practical to just accept the current state of your databa schema and identify this as the starting point. The bootstrap script and command exist for this reason. In the scripts directory you’ll find bootstrap.sql. You can put your existing DDL script in this file. If you don’t have a DDL script, you can export your existing databa schema and put it in the bootstrap file. You’ll want to clean it up so that it doesn’t contain anything specific to any one environment, but otherwi almost any scri
pt should work. Watch out for DDL that contains conditional elements or branching logic that could generate multiple schemas. While this is sometimes necessary, it’s a really good idea to try to eliminate this aspect of your databa schema (put such conditional and branching logic in your code or stored procedures instead). If you have multiple DDL files, you’ll have to merge them into the single bootstrap file. But worry not, it’s the last time you’ll ever modify it. One of the rules above was immutable change scripts… the bootstrap is included in that rule.
Note: The bootstrap.sql is a plain text file and is not a valid “migration” that you’ll learn about later. It’s meant to be similar to the scripts you probably already u. Therefore you cannot rollback the bootstrap file, nor is it tracked in the audit logs… without exception, whatever you put in the bootstrap file cannot leverage the benefits of the other migration commands. But we have to start somewhere, and it’s best to look forward.
