Databases on Craft Cloud

Craft Cloud supports multiple versions of MySQL and Postgres databases. You will pick a database engine when creating a new Cloud project: if you are starting a new project, we recommend MySQL 8.0; existing projects should use the same engine and version used by their current infrastructure.

Both engines support automated and manual backups via Craft Console.

Using a tablePrefix from an earlier version of Craft? Follow these instructions to make your database Cloud-compatible.

Connecting to your Database #

Each environment gets its own database. Connection details are automatically provided to your application via the Cloud extension, so no configuration is necessary!

MySQL #

We support MySQL version 8.0. We do not guarantee access to a specific minor or patch release.

Making a Backup #

You can capture a backup of your database by visiting the Backups screen of any environment and clicking Create Backup.

Importing/Restoring a Backup #

If you are migrating to Craft Cloud, run this command in an existing project to capture a Cloud-compatible backup:

php craft db/backup

Craft will print the path to the backup file. To restore the backup to Cloud, get the connection details from the Access screen of the target environment, and run this command (substituting your credentials):

mysql \
    --host={your-hostname} \
    --port=3306 \
    --user={username} \
    --password={password} \
    --database={database-uuid} \
    < "path/to/backup.sql"

Due to idiosyncrasies with the MySQL backup format, your mysql client binary should match the server version the dump was created with—ideally down to the minor version. For example, if a MySQL dump is created from a server running 8.0.28, then it should be restored with the 8.0.28 mysql client version. Some GUI tools (like Table Plus) allow you to specify a version when performing a restore.

Postgres #

We support Postgres version 14. We do not guarantee access to a specific minor or patch release.

Making a Backup #

You can capture a backup of your database by visiting the Backups screen of any environment and clicking Create Backup. Postgres database backups are captured in the “Custom” binary format for interoperability.

Importing/Restoring a Backup #

With access to an existing Craft project’s database, run this command to create a Cloud-compatible backup (substituting the project’s connection details):

pg_dump \
    --username=db \
    --password=db \
    --host=db \
    --port=5432 \
    --dbname=db \
    --format=custom \
    --exclude-table=public.cache \
    --exclude-table=public.phpsessions \
    --exclude-table-data=public.assetindexdata \
    --exclude-table-data=public.imagetransformindex \
    --exclude-table-data=public.resourcepaths \
    --exclude-table-data=public.sessions \
    --no-owner \
    --clean \
    --if-exists \
    --no-acl \
    --schema=public \
    --column-inserts \
    --file=backup.psql

Cloud only supports “custom” binary backups—in the above command, --format=custom handles this. To restore a backup, get the connection details from the Access screen of the target environment, and run this command (substituting your Cloud database’s credentials):

pg_restore \
    --username={username} \
    --password={password} \
    --host={your-hostname} \
    --port=5432 \
    --dbname={database-uuid} \
    --single-transaction \
    --no-owner \
    --clean \
    --if-exists \
    --no-acl \
    --verbose \
    path/to/backup.psql

The version of pg_restore you use should be the same as the version used to create the backup. Some GUI tools (like Table Plus) make it possible to choose the version when using binary backups.

This command will perform a “clean” import, erasing any existing content in the environment’s database!

Backups #

Every environment gets automated nightly backups. Backups are retained for 30 days.

You can capture a fresh backup any time (or download any past backups) from the Backups screen of an environment.

Table Prefixes #

The tablePrefix setting (and the corresponding CRAFT_DB_TABLE_PREFIX environment variable) are not supported on Cloud.

Run php craft db/drop-table-prefix in a local environment before importing your data into Cloud to rename the tables. After doing so, you should unset tablePrefix in db.php and remove CRAFT_DB_TABLE_PREFIX from your .env.

Applies to Craft Cloud.