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.

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"

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 \
    --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, therefore --format=custom in the example above. 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 \
    --host={your-hostname} \
    --port=5432 \
    --dbname={database-uuid} \
    --single-transaction \
    --no-owner \
    --clean \
    --if-exists \
    --no-acl \
    --verbose \
    path/to/backup.psql

Make sure the version of pg_restore matches the version of pg_dump that was used to create the backup. Some GUI tools (like Table Plus) make it possible to choose the version when using binary backups.

When dumping and restoring, the --password flag forces a password prompt—you do not need to provide a value as part of the original command. If you need to perform either operation in an automated or non-interactive environment, you can set a temporary PGPASSWORD variable: PGPASSWORD=abc123 && pg_restore ...

Backups #

Your production environment’s database is automatically backed up nightly. You can capture a manual backup (or download a past backups) at any time, from the Backups screen of an environment.

Backups are retained for 30 days, and can be downloaded until they expire.

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.