Managing databases with Cloud 66

About deploying databases

We currently support the following databases, with no need for additional configuration after deployment.

For Rack-based stacks, Cloud 66 automatically detects whether your application relies on a database or not during your code analysis. This is based on a combination of your Gemfile and your database.yml or mongoid.yml files.

After you have analyzed your code, ensure that your desired database type is displayed in the About your app section of the analysis results.

Cloud 66 supports multiple databases for Rails (i.e. multiple databases with Active Record). Please read our MultiDB for Rails guide to learn how to configure this feature.

Database authentication

When we deploy a database we automatically generate the required users and passwords to allow authentication. You can find these values via your Dashboard in the detail page of any database server. They will be available as environment variables and your application will be configured to use them.

MySQL and PostgreSQL databases managed by Cloud 66 automatically have the following users created:

The Application and Replication users always have the same password. The associated Linux users for these will differ depending on database type.

If you switch to managing your passwords manually, be sure to update all of these users whenever you change passwords. Remember that the Application and Replication users must use the same password.

If you’d prefer to manage your users and password manually (i.e. your config files), you can prevent your configs from being modified.

⚠️ The info above does not apply to external (self-managed) databases. See the dedicated section below for more details.

Managing YAML configs

A Rails app must have either a config/database.yml file or config/mongoid.yml in order to work on Cloud 66. We will create these files automatically if they don’t exist. We will update any existing files with new values (for example passwords) as required. You can turn this feature off if needed. (See below for more on env vars)

If you want to specify a different DB config per environment, you can name the files config/database.yml.environment-name (e.g. config/database.yml.dev)

If you don’t want to use the standard config setup, you can also add a config/database.yml.cloud66 or config/mongoid.yml.cloud66 file instead.

We will prioritise these configs as follows:

  1. Files ending .cloud66
  2. Files ending with a .environment-name
  3. The standard YAML config file

⚠️ The info above does not apply to external (self-managed) databases. See the dedicated section below for more details.

External databases

If you are using an external database (i.e. one not managed by Cloud 66), then we won’t set any of the database variables (such as username and password) the way we would normally do. You will need to set these yourself - either in your YAML config file, or by manually adding environment variables (see below).

If your database.yml file has a url defined, we will assume that you are using an external (self-managed) database, and will follow that URL accordingly.

External databases do not natively support multiple database config files (e.g. per environment), or files with the .cloud66 suffix. If you need to maintain separate config files for your external databases, you can achieve the same thing using a deploy hook. For example:

after_checkout:
command: mv $STACK_PATH/config/database.yml.cloud66 $STACK_PATH/config/database.yml
target: rails
run_on: all_servers
execute: true

This hook simply overwrites the standard config file with the config file of your choice at the start of the deployment process. Please read our full guide to deploy hooks to learn how to implement this hook.

Environment variables during deployment

When you set up an application on Cloud 66, we detect its database type(s) (from your code) and generate a set of variables for things like username and password and URL. We only generate these “analyzed variables” after you have confirmed that we will be managing the database(s).

You can see a list of these variables during application creation by clicking on the Add Environment Variables button (in the yellow Review your Rails application box) . You will see the list of analyzed variables for your database(s) at the top of the panel.

For databases that we manage, we will generate all of these variables, and replace any existing variables you have in your YAML config files unless you turn the auto-replacement feature off. (You can also override the values of these variables manually, one by one, if you wish - see below)

If your application uses an externally hosted (self-managed) database, we will not generate any of the analysed variables. If your config files rely on environment variables, you will need to set these manually before you deploy, or we will not be able to connect to your database.

Setting variables manually (overriding)

To add your own values to the analyzed variables, click on the Add Environment Variables button and then click the Override link next to each of the variables you wish to update. Remember, for external databases, we will discard any variables which do not have values set manually.

Database deployment types

No database (external)

This option allows you to deploy your application without a database managed by Cloud 66, and is ideal for externally hosted databases.

For Rails apps, if you have a url set in your database.yml then we will assume that you are using an external DB. You will need to set your own env vars during deployment, to ensure we can connect to it.

You can also configure an external database via your Manifest file by specifying the server node as external.

Please note that if there is no connectivity to your external database, or your external database host is not configured correctly, the deployment will fail.

Local database

This option deploys your chosen database to the same server as your web server - this is intended primarily for development, as running your database locally in production is not advised. In this case, your application database configuration will be amended to target your local database server. If you scale up your web server, these settings will also be amend automatically to reflect your database configuration.

Dedicated database

This option will automatically create a new server for your database and configure your application accordingly.

Upgrading your database

Cloud 66 will not do in-place database upgrades, because this process may cause your application to stop working or may not be possible automatically. To upgrade your database through Cloud 66, we recommend that you create a new application (at which point Cloud 66 will deploy the newer database version).

Once the new application is created, you can migrate data from your old application to your new application.

Control your Rails database migrations

Cloud 66 chooses a server to perform the migrations - all other servers will wait until the migrations are finished before continuing with deployment. You can see which server performs the migrations in the Application Overview, and change it using the c66.migrations.run reserved tag.

You can control your Rails database migrations by setting the run.deploy.command option through application settings via Toolbelt which gives you the option of running migrations or not.

$ cx settings set -s my_stack run.deploy.command true

When you have disabled run.deploy.command in Application settings, you still have the option to run migrations on a one-off deployment by clicking Deploy -> Deploy with options and selecting Run database migrations.

The Strong Migration gem

Sometimes operations can cause database migrations to lock the entire database for minutes at a time - even if the structural change is simple, or made to a relatively small table. If you’d like to understand the mechanisms behind this, we recommend reading this excellent blog post.

To mitigate the potential for this to happen, we recommend including the Strong Migration gem in your application. This will catch any potentially unsafe migrations and suggest how to avoid or reduce the risk.

Customize your database configuration

You can customize the database configuration on your servers using CustomConfig. CustomConfig is available for MySQL, PostgreSQL, Redis and MongoDB.

Editing and committing your database CustomConfig will perform the following steps on every database server in your application, one by one, sequentially:

🚨 A bad database configuration might stop your database from working. Take extra care to make sure the configuration is correct.

Database customization variables

There are a number of variables available for use in your database CustomConfig. Some are general for all database types, while others are database specific.

Global variables

The following variables are available to any database CustomConfig.

Variable Name Type Description
server Hash Hash containing information about your server
cloud string Application cloud
memory integer Server memory size (bytes)
core integer Server core count

MySQL variables

The following variables are only available in the MySQL CustomConfig.

Variable Name Type Description
server_state string Value can be stand_alone, mysql_master or mysql_slave based on your server status
server_id integer An ID used by MySQL replication to identify your server*
db_name string Database name

*It is 0 for standalone servers, 1 for master servers and a number greater than 1 for slave servers

PostgreSQL variables

The following variables are only available in the PostgreSQL CustomConfig.

Variable Name Type Description
server_state string Value can be stand_alone, pg_master or pg_slave based on your server status

Redis variables

The following variables are only available in the Redis CustomConfig.

Variable Name Type Description
server_state string Value can be stand_alone, redis_master or redis_slave based on your server status
master_address string IP address of replication master (empty string if server is stand alone or master)
master_port integer Will be 6379 when server is redis_slave , otherwise it is 0

Migrating to an external database

If you need to migrate a database managed by Cloud 66 to an external provider, you should bear in mind the following:

The exact migration process will differ widely depending on both the database used, and the host to which you are migrating your data, but all of them share the following steps:

  1. Switch off your application (maintenance mode is useful here)
  2. Migrate your data to the new host
  3. Set up authentication credentials and connection details
  4. Add a firewall rule to allow your app to reach the new data host (and vice versa)
  5. Turn your application back on
  6. Delete your defunct Cloud 66 database servers