Support

PHP has up to two methods to connect to a MySQL–compatible database server:

mysqli is the older of the two methods, provided by the mysqli PHP extension.

PDO MySQL is the more modern method, provided by the pdo_mysql PHP extension. We strongly recommend it for all site types, except WordPress. Do note that this option is not even offered in BRS for WordPress since WordPress itself only supports mysqli.

	Note
	There used to be a much older, much slower option called mysql. This PHP extension was removed in PHP 5.5.0 released on June 2013. What Joomla confusingly calls "MySQL" is actually "PDO MySQL". Keep that in mind if you think that your favourite option in Joomla is not available; it is available in BRS, but only shown with its CORRECT name!

The database server's host name. Usually it's localhost, but this is not always the case. If unsure, please ask your host, or consult your hosting account control panel.

Important

localhost and 127.0.0.1 are not the same thing! They mean two entirely different things. localhost tries to connect over shared memory (Windows), or UNIX pipe (Linux, macOS). 127.0.0.1 tries to connect over TCP/IP networking. If you tried one of these when restoring to a local server (e.g. MAMP, XAMPP, WAMPserver, etc), try the other one before assuming the restoration script is broken. You will be surprised.

If your host gave you a specific TCP/IP port to connect to, enter the hostname, a colon, and TCP/IP port. For example, if your host told you to connect to TCP/IP port 4242 on db.example.com you need to enter db.example.com:4242. If no port is specified, the default TCP/IP port 3306 will be used; this is what the vast majority of database servers uses.

If your host gave you the path to a UNIX socket to connect to, enter localhost, a colon, and the absolute path to the UNIX socket. For example, if your host told you to use the UNIX socket /var/run/db.sock you need to enter localhost:/var/run/db.sock.

The username of the database server user.

Please make sure that the database user you are using has all privileges for the database you are restoring to. By far the most common mistake restoring a site is that you created a database and a database user, but forgot to give your database user full privileges to the database you created. Go back to your hosting control panel and do that before assuming there is a bug; millions of successful restorations say that there is no bug, and hundreds of support tickets with this common issue say that it's very likely this simple step was accidentally forgotten. Don't worry, everyone has made that mistake at some point, even us.

Also keep in mind that when creating a database user you can either create a user able to connect from any IP address (defined as username@%), or a user who's only able to connect from a specific IP or hostname (defined as [email protected] or [email protected]). In the latter case, the hostname/IP address must match where the connection is coming from which might not be the web server's public IP address. In all cases, the user name you enter in this field is just username. The rest of it is how you tell your database server where the connection is expected to come from, not a part of the username itself.

Finally, note that commercial hosts usually apply a prefix to your username. If you see an entry box for a username prefixed by something like abcd12_ and you enter the username alice in the text box next to it then your database username is abcd12_alice. This is especially important on hosts using cPanel or Plesk which exhibit this behaviour by default.

The password of the database server user.

The actual name of the database you want to restore to. If you choose a database which already has tables in them, existing tables with the same name as the ones being restored will be overwritten (replaced) by default. You may want to ask your host for the correct value of this setting.

As noted above, when restoring to a new subdirectory, subdomain, domain, or server you must create a new database before the restoration. For detailed instructions on creating new databases, take a look at the relevant troubleshooting page.

Please note that commercial hosts usually apply a prefix to your database name. If you see an entry box for a database name prefixed by something like abcd12_ and you enter the database name storage in the text box next to it then your database name is abcd12_storage. This is especially important on hosts using cPanel or Plesk which exhibit this behaviour by default.

Important

While it is possible to store the database tables of multiple sites in the same database it is very strongly not recommended. First of all, the performance will be degraded for all sites, as it depends on the total size of the entire database (especially when using InnoDB tables, like most modern PHP software tends to do). Second, it makes it far more likely that you will accidentally end up leaving unused tables behind or, at worst, deleting the tables of another site. If your host restricts the number of database you can create under a user account beyond a reasonable limit, go to another host.

Especially applicable to Joomla! and WordPress. Most modern PHP software puts a common prefix in front of all database table names. It's usually two to four letters and numbers, followed by an underscore.

Important

Do NOT use any uppercase letters here. This has to do with the way MySQL–compatible servers handle table names on Windows and macOS when using case-insensitive filesystems such as FAT32, exFAT, NTFS, HFS+, and APFS. The details are complicated, but what you should keep in mind is that if you use UPPERCASE or MixedCase prefixes you will very likely have a problem restoring your site to a different server.

Warning

Always end your database prefix with an underscore. While it's not enforced by most PHP scripts (including Joomla and WordPress), if your prefix does not end with an underscore you can reasonably expect many things to break in unexpected ways on your restored site. For best results, stick with 2 to 4 basic alphanumeric characters (lowercase letters a to z without accents or diacritics excluding compound or calligraphic characters such as ß or æ, and numbers 0-9) followed by exactly one underscore.

You can enter the database port instead of including it with the hostname.

If you are connecting to your database server using a UNIX socket (e.g. unix:/tmp/mysql.sock) or a Windows Named Pipe (e.g. \\.\MySQL) you can enter it here instead of with the hostname.

Do you want to connect to MySQL using SSL/TLS? This can be used to encrypt the database connection and optionally to log you into it without using a password. You will need to supply the path of the MySQL client key and certificate file. This is a very uncommon option, practically only ever used with cloud-based database servers, or hardened corporate environments.

Only used when Use SSL/TLS is enabled. A colon separated list of the encryption ciphers to use for the SSL/TLS connection. The default list is AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-CBC-SHA256:AES256-CBC-SHA384:DES-CBC3-SHA.

Only used when Use SSL/TLS is enabled. The absolute filesystem path to the client certificate file in PEM format.

Only used when Use SSL/TLS is enabled. The absolute filesystem path to the client key file in PEM format.

Only used when Use SSL/TLS is enabled. The absolute filesystem path to the Certification Authority (CA) file for connecting to the server, in PEM format. This is only taken into account when Validate Server Certificate is enabled.

Only used when Use SSL/TLS is enabled. Verifies the server response against the Certification Authority (CA) file. You must provide the CA file for this option to work correctly. If your database restoration consistently fails try disabling this option.

What should BRS do with any tables already present in the database?

Enable this option to display a multi-select box where you can choose which tables, procedures, functions, triggers, and events you want to restore.

Select which database items in the backup should be restored. Make a multiple selection with CTRL-click (Windows, Linux) or CMD-click (macOS). Any database item you have not selected here will not be restored; it will be skipped over.

This allows you to only restore select database items. This might be desirable if you know exactly which tables are affected by the problem you want to solve, and you don't want to overwrite other data in other tables. For example, if an article's contents were accidentally overwritten and you want to restore that content, without breaking e-commerce orders placed on your site between the backup time and restoration time, you could choose to only restore the table #__articles (Joomla!) / #__posts (WordPress).

	Note
	You will notice that the restoration seems to proceed as normal, going through each SQL file. This is correct. The restoration engine does read each SQL file, but only executes the restoration commands for the database items you have selected. The data size appearing in the progress dialog is actually the amount of data read from the SQL files, not the amount of data written to the database.

A lot of software uses a database feature called “foreign key constraints” to keep track of relationships between records across multiple database tables. These constraints are enforced at the database level. You cannot delete a table with records referenced by another table. You cannot create database rows referencing records in another table which do not already exist.

For example, in an e-commerce software a user can typically have zero or more orders, each order having zero or more order lines, each order line having exactly one product; this would link the users, orders, order lines, and product tables using three foreign key constraints: users to orders, orders to order lines, order lines to product tables.

When restoring the database the constraints will most likely fail to validate. After all, the database tables may not exist at all, or they may exist but not have all the necessary records yet. This leads to a chicken and egg situation: you cannot restore the database unless all foreign key constraints are valid, but foreign key constraints will not be valid until you restore the database.

The solution to this chicken and egg situation is to disable the foreign key constraint checks at the database level for the duration of the restoration. This is what BRS does by default. If for whatever reason you do not want to do that (and you fully understand the consequences), you can enable this option here. That said, the most likely outcome is that your database restoration will fail. If that happens, please do not ask for support; instead, disable this option and try the restoration again, as it was intended all along.

A lot of database tables created by modern software have a column using a feature called auto-number. When no value, or a value of zero, is provided for this column it will automatically be assigned a monotonically increasing integer thereby automatically numbering each row added to the table.

Some software creates a special row where the auto-number column deliberately has the value of zero. Restoring that special row requires this option to be enabled. Having this option enabled when no such special row exists does not cause any problems, hence this option being enabled by default.

If you have a particular use case where you know the zero value in an autonumber column is wrong and would like to instead assign it a non-zero value you can disable this option. Please note that you must fully understand the consequences of doing so before disabling this option.

BRS will always try to delete or rename existing tables (see With existing tables), create the table afresh, then use INSERT statements to create new rows into the now-empty table.

There are use cases where deleting or renaming the table is not possible, but you are happy just overwriting existing data with that from the backup. If this is the case, you need to enable Use REPLACE instead of INSERT, Stop on CREATE error, and Stop on other error. The combination of these options will allow BRS to ignore the errors from being unable to delete and create afresh the database tables, then allow it to use REPLACE instead of INSERT to overwrite existing data instead of trying to add new records.

By default, BRS will not try to change the collation of your database. It is left to what is the default.

When this option is enabled, BRS will try to change the collation of the database. If Allow UTF8MB4 auto-detection is enabled and the database server allows UTF8MB4 data the collation will be set to utf8mb4. In any other case, it will be set to utf8 which is a three-byte UTF-8 collation.

By default, BRS will not try to change the collation of your tables. It is left to their defined collation (if any) at backup time.

When this option is enabled, BRS will try to change the default collation of the table and every column with a type which supports setting a collation (such as VARCHAR). If Allow UTF8MB4 auto-detection is enabled and the database server allows UTF8MB4 data the collation will be set to a four-byte UTF-8 collation. In any other case, it will be set to utf8_general_ci which is a three-byte UTF-8 collation.

See “Handling multi-byte data” below.

When enabled, BRS will detect if your database server supports 4-byte UTF-8 data. Otherwise, it will assume that your database server only allows legacy 3-byte UTF-8 data.

See “Handling multi-byte data” below.

Allows BRS to translate the character set explicitly set on a table or a column to what is appropriate for the database server you are restoring to. Enabled by default, and recommended to be left enabled when transferring a site between different database server types (e.g. MySQL to MariaDB, or vice versa), or different database server versions (e.g. MySQL 5.6 to 8.0).

See “Handling multi-byte data” below.

Should the restoration halt with an error if a CREATE TABLE / PROCEDURE / FUNCTION / TRIGGER / EVENT command fails?

See “Handling database errors” below.

Should the restoration halt with an error if a database command other than a CREATE fails?

See “Handling database errors” below.