-
Notifications
You must be signed in to change notification settings - Fork 7
Quick Start Guide
DBdeployer is written entirely as a bash shell script, therefore Bash is a requirement to run it. Initially for Windows servers we were using DBdeployer through cygwin and we had success with that, but do not actively support this implementation. We have not tested DBdeployer with other shells.
If you are using DBdeployer to manage mssql, it will use sqlcmd to deploy to the sql server. Sqlcmd is a free, but licensed Microsoft product and can not be packaged with DBdeployer. If you are using DBdeployer with cygwin, you can use the sqlcmd program available from Windows. If you are using Linux, you will need to download sqlcmd for linux at http://www.microsoft.com/en-us/download/details.aspx?id=28160
Additionally, there are a few bugs that we have found with the sqlcmd program running on Linux. Since we do our deployments from Linux, we carefully document these issues and develop workarounds for them.
If you are using DBdeployer to manage Postgres, we use the psql client program.
Currently we do not have any rpm's available. To deploy you can download a tagged version or clone our repo. Once you have the repo downloaded, you can run the installation script as root or with appropriate sudo permissions.
./dbdeployer_install.sh
This installs all of the files to their appropriate locations on the filesystem. The installer does not actually setup your tracking database as it is unaware of what type of database platform you are planning to use with DBdeployer.
Once the software is installed, you must create a "deployments" database on the server you wish to track database deployments. You must also create a user to manage the deployments or use an existing user. This user should be a superuser in the database if you would like to utilize all of the features of DBdeployer (DBdeployer can drop databases, create databases, and should be able to connect to all databases with full permissions to manage deployments). We recommend a database name of "deployments" as that is what we use for our default value. If you choose another database name you will have to update it in the /etc/dbdeployer/config.sh file.
The global config file is located at /etc/dbdeployer/config.sh. It is just a shell script that gets sourced, so make sure when you set variables that you do not include any spaces between the variable name and the equal sign.
You can also set a user specific configuration file by creating ~/.dbdeployer and setting variables there to override the global.
By default the location recommended for storing your databases is /var/lib/dbdeployer/databases. Whatever user you are deploying things as must have write privileges to this directory unless you would like to change the location. DBdeployer will generate an error and not allow deployments if it can not write log information to the databases directories. You can change the locate where you would like your database folder to be by updating the db_basedir in the global config file, or you can also override the value just for your own user in the file ~/.dbdeployer and setting the bash variable for db_basedir equal to the location of your choice.
The default install sets things up for Postgres. It does this because that's what I use on most of my installs. If you are using mssql or extending this for another database, you will need to change the global config file variable dbtype to reflect the appropriate name.
In the default global config there is also a run_as user that is set to postgres. If you are not using Postgres, or you do not want to be the postgres user when deploying things to Postgres, you can either comment out this line in the global config, or you can type unset run_as in your user specific configuration file.
The other variable you will want to consider is deployment_report_argnum. This is currently set for the way that bash works with linux. Basically we are listing out the files with an alpha sort and need to get the column that contains the filename. In linux this is the 8th column. On mac, this is the 1st column. If running on a mac, change this value to 1. In the future we will probably make the script auto-detect the correct column so this variable is not needed. Example outputs below:
# linux
ls -o1 deployments/schema/
total 8
-rw-r--r-- 1 root 3843 Jul 20 17:58 1000_schema.sql
-rw-r--r-- 1 root 1119 Jul 20 17:58 README
# mac
ls -o1 deployments/schema/
1000_schema.sql
README
output
Once the deployments database is created and you have an appropriate user to connect to it, we can deploy the appropriate schema for your database server type to it with DBdeployer.
# example Postgres
dbdeployer -D /var/lib/dbdeployer -d deployments -e postgres -u
# example mssql
dbdeployer -D /var/lib/dbdeployer -d deployments -e mssql -u
Explanation of flags:
the -D flag denotes the directory we want to use as the source for our databases. The -d denotes the name of the database to deploy, and the -e denotes the "environment" we are deploying. We are actually overloading the functionality of the server environments for the deployments database to contain the sql specific to our database server types. The -u flag specifies to bring the database up to date with all of the files that it has that are not yet deployed. You could see what files will be deployed by substituting the -u with a -r which is the report flag.
The above examples assume that you have things setup to use an already authenticated user. If this is not the case, you can type dbdeployer -h for the help to see flags that you can use to set username, password, host, and port.
Your deployment tracking database is now up to date and you should be able to deploy your databases and updates to your databases with DBdeployer going forward.
Once you have the location you will be using to deploy database changes from setup, you can clone your companies database repo to that location. You should have a single folder for each database, and the database folder should contain folders for schema, seed, changes, archive, and rollback. You can copy the sample_structure from /var/lib/dbdeployer/sample_structure when creating new databases or setting up your database for the first time. You can read more about how to use these folders here
Once you have your location set and a repository checked out into the location, you can use DBdeployer to install the changes. DBdeployer has a lot of options, but the basic ones are listed below. We typically use Git to review changes, and we deploy from features branches to test servers, and then once changes are ironed out we merge them to master and roll them out on all of the servers.
# run a report for a database
dbdeployer -d [database] -r
# deploy a database to current
dbdeployer -d [database] -u
# deploy a particular file as a one-of deployment
dbdeployer -f /full/path/to/file.sql
# mark a deployment as skipped (this can be useful if you deploy manually for some reason)
dbdeployer -k -f /full/path/to/file.sql
A Dockerfile has been added to this repository to facilitate running from a container. This approach can eliminate the need for installing drivers and other dependencies on your workstation / server. Once the container is built custom configs can be volume-mounted to the container. The entry point of this container is the dbdeployer script itself, so args can be passed directly to the container.
# build the dbdeployer container
docker build . -t dbdeployer
# example run with custom configs mounted in
docker run --rm -it -e DBNAME=development -v ~/containers/dbdeployer/.dbdeployer:/root/.dbdeployer dbdeployer -c -d devdb -r
Running out of a container is strictly optional, but may be useful for some portability.