michtio/craftcms-claude-skills / skills/craft-cloud
craft-cloud
UnverifiedCraft Cloud — Pixel & Tonic's serverless hosting platform for Craft CMS. Covers craft-cloud.yaml configuration, the Build → Migrate → Release deploy pipeline, the craftcms/cloud extension package, edge image transforms via Cloudflare, edge static caching with cache.rules + ESI, Cloud-managed S3 filesystem, MySQL 8 / Postgres 15 databases (no MariaDB, no tablePrefix), Console-based command runner and scheduled cron (once-per-hour minimum), auto-handled queue jobs, custom domains and SSL, preview environments per branch, Cloud limitations (ephemeral filesystem, no SSH, no .htaccess, no built-in mail), plugin development requirements for Cloud compatibility, and self-hosted → Cloud migration.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 18.8 KB |
| references/assets-and-transforms.md | markdown | 5.5 KB |
| references/caching-and-edge.md | markdown | 23.4 KB |
| references/commands-and-cron.md | markdown | 7.0 KB |
| references/config-file.md | markdown | 6.9 KB |
| references/database.md | markdown | 6.0 KB |
| references/deploy-pipeline.md | markdown | 16.6 KB |
| references/domains.md | markdown | 5.4 KB |
| references/extension.md | markdown | 15.6 KB |
| references/headless.md | markdown | 8.0 KB |
| references/limitations.md | markdown | 17.3 KB |
| references/local-dev.md | markdown | 6.8 KB |
| references/migration.md | markdown | 8.6 KB |
| references/plugin-development.md | markdown | 14.5 KB |
references/database.md
View on GitHub# Database on Cloud
Cloud provisions and manages your database — you don't run it, configure `db.php`, or set `CRAFT_DB_*` env vars. The Cloud extension auto-wires the connection. You get MySQL 8.0 or Postgres 15; nothing else is supported.
## Documentation
- Databases reference: https://craftcms.com/docs/cloud/databases
## Common Pitfalls
- Committing a `config/db.php` with hardcoded credentials. Cloud's auto-wiring won't override file-based config in all cases, and stale credentials in `db.php` will fight the platform. Remove `db.php` entirely or wrap its contents in an `App::env('CRAFT_CLOUD')` check that no-ops on Cloud.
- Setting `CRAFT_DB_*` env vars on Cloud. Same root cause as above — the Cloud extension injects connection details automatically; manual overrides break the wiring.
- Using `tablePrefix`. Unsupported. Run `php craft db/drop-table-prefix` locally before importing, and remove the setting from both `db.php` and `.env` before deploying.
- Choosing MariaDB. Cloud only supports MySQL 8.0 and Postgres 15. New projects should default to MySQL 8.0 — Postgres is supported but Craft's Postgres surface has fewer plugins tested against it.
- Setting a custom `backupCommand` to work around the Cloud-managed backup format. The docs explicitly warn: "[A custom `backupCommand`] can cause unreliable backups." Use Cloud's backup interface instead.
- Restoring a Postgres backup with `psql` instead of `pg_restore`. Cloud captures Postgres backups in `custom` format (Craft defaults to plaintext). `psql < backup.sql` fails on the custom format. You need `pg_restore` with specific flags.
## Supported engines
| Engine | Version | Notes |
|---|---|---|
| MySQL | 8.0 | Recommended for new projects |
| Postgres | 15 | Supported; smaller plugin compatibility surface |
| MariaDB | — | Not supported |
Both engines are available in every region. The engine is chosen at project creation and can't be changed afterward (along with region — see `limitations.md`).
## Configuration: there isn't any
Once your Cloud project is provisioned, you don't configure the database connection. The Cloud extension reads the platform-supplied credentials at boot and wires `Craft::$app->db` automatically.
Things to **remove or leave unset** when deploying to Cloud:
- `config/db.php` — delete it, or wrap in `if (!App::env('CRAFT_CLOUD'))` so it only applies locally.
- `CRAFT_DB_DRIVER`, `CRAFT_DB_SERVER`, `CRAFT_DB_USER`, `CRAFT_DB_PASSWORD`, `CRAFT_DB_DATABASE`, `CRAFT_DB_PORT`, `CRAFT_DB_TABLE_PREFIX` — Cloud sets all of these automatically. Leave them unset in the Console env vars.
- `db.php` `tableSchema` / `port` / `socket` overrides — same reason.
For local development you still need these — see `local-dev.md` for the recommended pattern.
## Backups
Cloud captures automated nightly backups of the **production** environment's database (schedule fixed by project region, not configurable), and lets you capture a manual backup of **any** environment on demand from Console (with an optional description). Automated and manual backups are both **retained for 30 days**, unless deleted sooner. Any Cloud backup can be restored with `php craft db/restore` (Craft 4.10+), to any environment or a local install.
Fine print (from https://craftcms.com/docs/cloud/backups):
- Single backups are limited to **200GB**; backups do **not** count against the storage quota.
- Deleting an environment or project deletes its backups with it — download before destroying an environment.
- Console-visible backups are a convenience, **not part of Cloud's durability architecture** — Pixel & Tonic can't recover an environment for which no automated or manual backup exists. For anything you can't lose, download backups off-platform on a schedule.
The CP's Database Backup utility is **disabled** on Cloud — backups happen at the platform level, not via the Craft application. Plugins that depend on the CP utility (rare) won't work; use Cloud's backup interface instead.
## Restoring a backup
Download the backup from Console (Databases → Backups → Download), then restore against the target database.
### MySQL
Client version must match the dump version (ideally minor version). Use the `mysql` CLI:
```sh
mysql --host={hostname} --port=3306 --user={username} \
--password={password} --database={database} < backup.sql
```
For a local DDEV environment, Craft's built-in restore command works:
```sh
ddev craft db/restore /path/to/backup.sql
```
### Postgres
Cloud captures Postgres backups in `custom` format. You need `pg_restore`, not `psql`:
```sh
pg_restore --host={hostname} --username={username} \
--dbname={database} \
--no-owner --clean --single-transaction --if-exists --no-acl \
backup.dump
```
The flag set matters:
- `--no-owner` strips ownership metadata that doesn't apply on the destination.
- `--clean` drops existing objects before recreating.
- `--single-transaction` makes the restore atomic.
- `--if-exists` prevents errors on missing objects during the drop phase.
- `--no-acl` strips ACL/grant statements.
For plaintext-format Postgres dumps (e.g. from a self-hosted Craft project), use `psql`:
```sh
psql --host={hostname} --username={username} \
--dbname={database} --password < backup.sql
```
## Connection access for external tools
Database credentials are available in the Cloud Console under **Access** for each environment. These let you connect a desktop client (TablePlus, Sequel Ace, pgAdmin) or run scripts against the live DB.
Treat these credentials as production secrets — they bypass the application's permission model entirely.
## Migrating an existing database
The end-to-end migration sequence (export, schema cleanup, table-prefix removal, import) lives in `migration.md`. The short version for the DB step alone:
1. Locally: `php craft db/drop-table-prefix` if you ever used a table prefix.
2. Locally: export your DB.
3. Provision the Cloud project with the matching engine and version.
4. Import the dump using the engine-specific command above.
Last verified against https://craftcms.com/docs/cloud/databases on 2026-05-28.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |