Databases

Databases

Currently supported databases:

• MySQL
• PostgreSQL
• MongoDB
• Redis

Examples

Below are examples you can copy/paste in to your "Backup" configuration file. These blocks should be placed between Backup::Model.new(:my_backup, 'My Backup') do and end.

MySQL

database MySQL do |db|
  db.name               = "my_database_name"
  db.username           = "my_username"
  db.password           = "my_password"
  db.host               = "localhost"
  db.port               = 3306
  db.socket             = "/tmp/mysql.sock"
  db.skip_tables        = ['skip', 'these', 'tables']
  db.only_tables        = ['only', 'these' 'tables']
  db.additional_options = ['--quick', '--single-transaction']
end

PostgreSQL

database PostgreSQL do |db|
  db.name               = "my_database_name"
  db.username           = "my_username"
  db.password           = "my_password"
  db.host               = "localhost"
  db.port               = 5432
  db.socket             = "/tmp/pg.sock"
  db.skip_tables        = ['skip', 'these', 'tables']
  db.only_tables        = ['only', 'these' 'tables']
  db.additional_options = ['--quick', '--single-transaction']
end

MongoDB

database MongoDB do |db|
  db.name               = "my_database_name"
  db.username           = "my_username"
  db.password           = "my_password"
  db.host               = "localhost"
  db.port               = 27017
  db.ipv6               = false
  db.only_collections   = ['only', 'these' 'collections']
  db.additional_options = []
  db.lock               = false
end

Additional Notes

The db.lock is set to false by default. This is a new feature (introduced in version 3.0.15) which will first lock and fsync your database before it performs the actual dump. This removes the chance of having "out of sync" data. Dumping data without locking the database won't lead to corruption, but imagine that you have some kind of association between two collections with a foreign key. It could be that one of the associated objects are not dumped, while the other is, meaning a "broken" association. If you restore this, the data that was actually dumped will be restored, but the association doesn't exist anymore. So, setting the db.lock = true would first lock the database, preventing all write operations, then it'll fsync (flush) the data to the database physical database files to ensure everything is 100% in-sync, then it'll perform the dump as usual, and finally it'll unlock the database so data can be written to it again.

Redis

database Redis do |db|
  db.name               = "my_database_name"
  db.path               = "/usr/local/var/db/redis"
  db.password           = "my_password"
  db.host               = "localhost"
  db.port               = 5432
  db.socket             = "/tmp/redis.sock"
  db.additional_options = []
  db.invoke_save        = true
end

Additional Notes

The db.name represents the database dump file on the filesystem in /usr/local/var/db/redis/. It'll be concatenated and it'll append the .rdb (Redis dump extension). So the above example will try to look for the database dump file in /usr/local/var/db/redis/my_database_name.rdb. The default name for the Redis dump file is just dump.rdb unless you change it in the configuration file youself.

The db.invoke_save, when set to true, it'll perform a SAVE command on the Redis process before backing up the dump file, so that the dump file is at it's most recent state.

Utility Path

If for some reason Backup cannot detect the path to your utility (e.g. mysqldump, pgdump, mongodump etc) then you can specify the utility_path manually and force Backup to use that path.

database MySQL do |db|
  db.utility_path = '/usr/bin/mysqldump'
end

If you're dealing with multiple databases, and you find yourself re-defining the utility_path multiple times, consider DRY-ing this up by adding the utility_path to the default MySQL database configuration like so:

Backup::Configuration::Database::MySQL.defaults do |db|
  db.utility_path = '/usr/bin/mysqldump'
end

With this in place, you'll no longer have to specify the utility_path for each database block. If you're not sure where the utility is located, try running which <utility_name>, for example: which pgdump or which mongodump. It may return the path to the utility. If it does, you can most likely use that path as the db.utility_path.

Default Configuration for each database

If you are backing up multiple databases, you may want to specify default configuration so that you don't have to rewrite the same lines of code for each of the same database types. For example, say that the MySQL database always has the same username, password and additional_options. You could write this above the Model configurations.

Backup::Configuration::Database::MySQL.defaults do |db|
  db.username           = "my_username"
  db.password           = "my_password"
  db.additional_options = ["--single-transaction"]
end

So now for every MySQL database you wish to back up that requires the username, password and additional_options to be filled in with the defaults we just specified above, you may omit them in the actual database block, like so:

database MySQL do |db|
  db.name = "my_database_name"
  # no need to specify username
  # no need to specify password
  # no need to specify additional_options
end

You can set defaults for MongoDB, by changing the Backup::Configuration::Database::MySQL.defaults to Backup::Configuration::Database::MongoDB.defaults, and so forth for every supported database.