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 \
--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 ...
This command will perform a “clean” import, erasing any existing content in the environment’s database!
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
.