Most Backdrop sites have a single MySQL database to which they connect. If your site only needs to connect to a single database, it should be able to use the simple database configuration string at the top of the default settings.php file:

$database = 'mysql://user:pass@hostname/database_name';
$database_prefix = '';

Replace "user", "pass", "localhost", and "database_name" with the applicable information from your server. If you do not have a database, check with your hosting provider on how to create one.

The $database_prefix setting is optional. It allows you to install Backdrop on the same database as other pieces of software. Using a prefix such as "backdrop_" will prepend that string to all database tables so that they do not collide with other tables within the same database. Using a separate database for each Backdrop installation is recommended, but if you are limited in the number of databases on your server, the prefix setting may help you install more sites on a single server.

4-byte UTF-8 character support (Emoji, Mathematical symbols, and extended Chinese characters)

Starting in Backdrop 1.5.0, the installer within Backdrop will automatically attempt to determine if your server supports storing 4-byte characters in the database. Without enabling this ability, characters such as emoji may show up as an unknown character when viewed, or sometimes two separate characters. There are specific server requirements for supporting these characters:

  1. The MySQL server must support the utf8mb4 charset (5.5.3 and up).

    You can check your MySQL version by running the command mysql --version.

  2. The PHP MySQL driver must support the utf8mb4 charset (libmysqlclient 5.5.3 and up or mysqlnd 5.0.9 and up).

    The MySQL driver may be determined by visiting admin/reports/status/php on your site and searching for "Client API version" under the "pdo_mysql" section.

  3. In order to allow for large indexes, MySQL must be set up with the following my.cnf settings: 

    [mysqld]
    innodb_large_prefix=true
    innodb_file_format=barracuda
    innodb_file_per_table=true

    These settings are available as of MySQL 5.5.14, and are defaults in MySQL 5.7.7 and up.

  4. The following line must be present in your settings.php file:
    $database_charset = 'utf8mb4';

Upgrading an existing database to 4-byte UTF-8 encoding

If you are upgrading an existing Backdrop site, this feature may be enabled by doing the following:

  1. Add the $database_charset variable to your settings.php file:
    $database_charset = 'utf8mb4';
  2. Visit your site status report at admin/reports/status. An entry will be present showing the current status of your database under the "Database system 4 bit UTF-8 support" section. If an upgrade is possible, click the link for "Database tables need conversion". If your database does not support 4-byte UTF-8, check the server configuration as described above. If unable to upgrade, remove the line for $database_charset in settings.php to fallback to the default.
  3. Make a database backup. The upgrade process is irreversible and in the event of an error, you will want to restore a previous version.
  4. The link in the status report will take you to the database upgrade tool at admin/config/development/utf8mb4-upgrade. Click the button for "Upgrade database to 4 byte UTF-8". This process will put your site into offline mode during the upgrade. The time of the upgrade depends on the size of your database.

After upgrading the database, you should be able to insert Emoji into any value in Backdrop and it should be saved and displayed properly, including node titles, user names, any custom fields, block titles, etc.

Setting up a Primary/Secondary Database Configuration

Sites that experience heavy amounts of database queries or require redundancy to improve up-time may set up Backdrop to use multiple database servers. Most queries in Backdrop are done against the primary server, but when doing a query either in code or through the Views module, queries can be marked as "safe" for the secondary server, offloading a substantial amount of queries from the primary server onto the (read-only) secondary server.

To configure Backdrop to use a Primary/Secondary configuration, do not specify a simple $database string. Instead, specify an array of database configuration using the $databases (note the plural form) variable.

This configuration is equivalent to the single database string:

$databases['default']['default'] = array(
  'driver' => 'mysql',
  'database' => 'database_name',
  'username' => 'user',
  'password' => 'pass',
  'host' => 'dbserver1.example.com',
);

And a second (secondary) database may be added by additionally specifying:

$databases['default']['secondary'][] = array(
  'driver' => 'mysql',
  'database' => 'database_name',
  'username' => 'user',
  'password' => 'pass',
  'host' => 'dbserver2.example.com',
);

Note that the "secondary" property is a multiple value array. This allows setting up multiple secondary servers, over which secondary-safe queries will be distributed.

Non MySQL Databases

Backdrop only supports MySQL databases within core. This means that it may make assumptions about MySQL-specific syntax and use non-ANSI standard functions. Backdrop core also assumes MySQL DATETIME fields for its core date.module.

However, Backdrop may still connect to non-MySQL databases for specialized applications, such as using PostgreSQL for spatial searches or querying a corporate MS SQL server. To connect Backdrop to these databases, specify them as a separate "target" in the configuration:

$databases['other_server']['default'] = array(
  'driver' => 'pgsql',
  'database' => 'database_name',
  'username' => 'user',
  'password' => 'pass',
  'host' => 'dbserver3.example.com',
);

Then when executing queries, simply specify the target name ("other_server" in this example):

$result = db_query("SELECT * FROM custom_table", array('target' => 'other_server'));

Backdrop may be connected to any type of database so long as it is supported by a PHP PDO Driver (see the list of available drivers at PHP.net).

Pre-configuring Databases at the Server-Level

Some specialized applications of Backdrop may find it more convenient to configure the database connection information through a server environment variable rather than modifying settings.php. For example in Apache, environment variables may be set within virtual host configurations with:

SetEnv BACKDROP_SETTINGS {"databases":{"default":{"default":{"driver":"mysql","database":"database_name","username":"user","password":"password","host":"localhost"}}},}

These settings are specified as a JSON array. If these server-level settings are found, they will override the values in settings.php with the same keys. Other settings besides database configuration (such as $settings['config_directories'] may also be modified in this way.