Transporter
Transporter is a database migration tool (CLI), it helps you keep your databases in order by creating migration files, those migration files are Go files that run SQL commands on your database to keep multiple environments databases in sync on its structure.
Features:
- Allows you to keep your database environments sync'ed
- You can run your migrations up and down as needed
- Supports multiple DBMS
- Provides functions for common database operations
- You can run your own SQL
Installation
To install Transporter please run go get -u github.com/wawandco/transporter
, with that, the transporter command should be available.
Supported DBMS
Transporter supports the following DBMS's
-
postgresql
development:
driver: postgres
url: "user=username dbname=my_db_development sslmode=disable"
-
mysql
development:
driver: mysql
url: "transporter:password@tcp(mysql.local:3306)/ttest"
-
mariadb
development:
driver: mariadb
url: "transporter:password@tcp(mariadb.local:3306)/ttest"
Commands
-
transporter init
init
checks for db
folder and creates this one and the migrations
folder inside if these doesn't exist, also generates a config.yml
file inside db
.
-
transporter create
generate
creates a migration inside the db/migrations
folder.
-
transporter up
up
runs all pending migrations inside the db/migrations
folder.
-
transporter down
down
runs last migration down.
Migrations
Migrations are simple .go
files generated by transporter, these define a struct that implements 2 functions Up
and Down
which will be called according to the command you're calling from the CLI.
This is an example of a transporter Migration.
package migrations
import transporter "github.com/wawandco/transporter/core"
func init(){
transporter.Register(&Migration{
Identifier: 20151119112619,
Up: func (txn *transporter.Tx) {
txn.Exec("ALTER TABLE my_table ADD COLUMN new_column varchar(255);")
},
Down: func (txn *transporter.Tx) {
txn.Exec("ALTER TABLE my_table DROP COLUMN new_column;")
},
})
}
Common operation functions
As you may have noticed, there are some database operations we do frequently when creating and maintaining database migrations, we've added some functions to make your life easier :), you can use these as the following example shows:
package migrations
import transporter "github.com/wawandco/transporter/core"
func init(){
transporter.Register(&Migration{
Identifier: 20151119112619,
Up: func (txn *transporter.Tx) {
//Instead of doing it this way:
txn.Exec("ALTER TABLE my_table ADD COLUMN new_column varchar(255);")
//You could simply do:
tx.AddColumn("my_table", "new_column", "varchar(255)") // And is equivalent
},
Down: func (txn *transporter.Tx) {
txn.Exec("ALTER TABLE my_table DROP COLUMN new_column;")
},
})
}
We have provided the following other functions you could use the same manner
tx.CreateTable("my_table", transporter.Table{
"old_column": "varchar(12)",
}) // We will need to add this transporter.Table struct.
tx.DropTable("my_table")
tx.AddColumn("my_table", "new_column", "varchar(12)")
tx.DropColumn("my_table", "new_column")
tx.ChangeColumnType("my_table", "new_column", "varchar(12)")
tx.RenameColumn("my_table", "new_column", "varchar(12)")
tx.RenameTable("my_table", "other_table_name")
As usual, we're open to suggestions on common database operations, please let us know!.
Multiple Environment support
Transporter supports you to have multiple environments on the same application, these could be used to run tests against different databases.
By default is only ships with the development
environment, which will run if you invoke the up
and down
commands without any other argument.
if you need to have multiple environments you could change your db/config.yml
file as in this example:
development:
driver: postgres
url: "user=username dbname=my_db_development sslmode=disable"
staging:
driver: postgres
url: "user=username dbname=my_db_staging"
production:
driver: postgres
url: "user=username dbname=my_db_production"
And call transporter up staging
or transporter down staging
or any other environment's database you would like to run the migrations against.
### Flags Support
In some scenarios you won't want to persist credentials to your database inside the source code, in that case you can specify the database url and driver by using parameters for the transporter command.
transporter --database="user=username dbname=my_db_development sslmode=disable" --driver=postgres up
Developer Setup
To work on this we've set a docker-compose file, you will need to instal docker toolkit in order to run our tests against the docker images.
- Install docker, docker-compose
- run
docker-compose build
- run
./dbsetup.sh
to setup testing databases.
- run
docker-compose run lib go test ./... -v
to run the tests.
Ensure you have all the tests passing on the docker-compose machines before pushing into master.
Copyright
Transporter is Copyright © 2008-2015 Wawandco SAS. It is free software, and may be redistributed under the terms specified in the LICENSE file.