# Database Management DDEV provides lots of flexibility for managing your databases between your local, staging and production environments. You may commonly use the [`ddev import-db`]() and [`ddev export-db`]() commands, but there are plenty of other adaptable ways to work with your databases. If your project does *not* require a database, you can exclude it with the the [`omit_containers` configuration option](). > [!TIP] > > You can run `ddev [command] --help` for more info on many of the topics below. ## Database Imports Import a database with one command, from one of the following file formats: **`.sql`, `.sql.gz`, `.sql.bz2`, `.sql.xz`, `.sql.zst`, `.mysql`, `.mysql.gz`, `.tar`, `.tar.gz`, `.tar.zst`, and `.zip`**. Here’s an example of a database import using DDEV: ``` ddev import-db --file=dumpfile.sql.gz ``` You can also: - Use [`ddev mysql`]() or `ddev psql` or the `mysql` and `psql` commands inside the `web` and `db` containers. - Use a [database client](<#database-clients>) or [database GUI](<#database-guis>) to import and browse data. ## Database Backends and Defaults You can use a [variety of different database types](), including MariaDB (5.5–10.8, 11.4, 11.8, 12.3), MySQL (5.5–8.0, 8.4, 9.7), and PostgreSQL (9–18). If you want to *change* database type, you need to export your database, run [`ddev delete`]() to remove the project (and its existing database), change to a new database type, run [`ddev start`]() again, and [import your data](). (For very old database types see [Using DDEV to spin up a legacy PHP application]().) DDEV creates a default database named `db` and default permissions for the `db` user with password `db`, and it’s on the (inside Docker) hostname `db`. ## Extra Databases You can easily create and populate additional databases. For example, `ddev import-db --database=backend --file=backend.sql.gz` will create the database named `backend` with permissions for that same `db` user and import from the `backend.sql.gz` dumpfile. You can export in the same way: `ddev export-db -f mysite.sql.gz` will export your default database (`db`). The compression type comes from the file extension (`.gz`, `.zst`, `.xz`, `.bz2`, or `.sql` for none), or set it with `--compression`. `ddev export-db --database=backend -f backend-export.sql.gz` will dump the database named `backend`. ## Snapshots Snapshots let you easily save the entire status of all of your databases, which can be great when you’re working incrementally on migrations or updates and want to save state so you can start right back where you were. Snapshots can be named for easier reference later on. For example, [`ddev snapshot --name=two-dbs`]() would make a snapshot named `two-dbs` in the `.ddev/db_snapshots` directory. It includes the entire state of the db server, so in the case of our two databases above, both databases and the system level `mysql` or `postgres` database will all be snapshotted. Then if you want to delete everything with `ddev delete -O` (omitting the snapshot since we have one already), and then [`ddev start`]() again, we can `ddev snapshot restore two-dbs` and we’ll be right back where we were. Use the [`ddev snapshot restore`]() command to interactively choose among snapshots, or append `--latest` to restore the most recent snapshot: `ddev snapshot restore --latest`. It also accepts the path to a snapshot file outside the project: `ddev snapshot restore ~/tmp/mysnapshot-mariadb_11.8.zst`. Snapshots are stored as compressed (zstd, or gzip on very old database versions) files in the project’s `.ddev/db_snapshots` directory, and any or all snapshots can be removed with the `ddev snapshot --cleanup` command or by manually deleting the files when you want to save disk space or have no further use for them. ### Sharing Snapshots Between Git Worktrees If a project is a [Git worktree](), `ddev snapshot restore` also offers snapshots belonging to the same project checked out in the repository’s other worktrees, so a snapshot taken in one working copy doesn’t have to be manually copied to restore it in another. This works whether you pick interactively, restore by name, or use `--latest`, and `ddev snapshot --list` shows the other worktrees’ snapshots too, each labeled with the worktree it came from: ``` # In ~/repo/web ddev snapshot --name=before-migration # In ~/repo-feature-branch/web, a worktree of the same repository ddev snapshot restore # 'before-migration' from ~/repo/web is offered alongside this project's own snapshots ddev snapshot restore before-migration # also works directly by name, without the interactive picker ``` Only worktrees of the same repository are considered — a separate clone at the same relative path is not, even if it happens to have the same project name. If more than one sibling worktree has a snapshot with the same name, the most recently created one is used, without asking which. This is a convenience on top of the path-based restore above: `ddev snapshot restore ` and `ddev start --seed-snapshot=` already work with a snapshot from anywhere on disk, worktree or not. ### Uncompressed Snapshots `ddev snapshot`, `ddev snapshot restore`, and the reserved `seed` snapshot all compress the database backup by default, which is the right trade-off for almost everyone. Decompression still costs real time, though — routinely 30-40% of a restore or first `ddev start`, and it competes for the same CPU cores the database restore itself needs right after. `--uncompressed` skips it: ``` ddev snapshot --uncompressed ``` This is an unusual, deliberate trade-off, not a general recommendation: an uncompressed snapshot can be roughly as large as the database’s uncompressed datadir — many times bigger than the same snapshot compressed with zstd. It’s worth it mainly when disk space is cheap relative to CPU time, for example a low-core-count host, or a seed that’s read straight off fast local disk and never crosses a network (so compression buys nothing on the transfer side either). `ddev snapshot --list` shows each snapshot’s compression (`zstd`, `gzip`, or `none`) so you can tell which kind you’re looking at. Restoring an uncompressed snapshot with `ddev snapshot restore` needs no extra flag — the file’s extension (`.mbstream`/`.xbstream` instead of `.zst`/`.gz`) already tells DDEV there’s nothing to decompress. Not available for PostgreSQL projects. The reserved `seed` snapshot honors the same flag, and a `dbimage` built with a baked-in seed (see [Seeding a Custom Starter Database]()) can use an uncompressed seed the same way. ### Seeding a Fresh Database from a Snapshot The first time a project’s database volume is created — a brand-new project, or after `ddev delete` and [`ddev start`]() — DDEV can restore a snapshot into it instead of using its normal empty starter database. This is a direct restore of the database files, much quicker than importing a SQL dump on every fresh start. `seed` is a reserved snapshot name used for this. If a snapshot named `seed` exists in `.ddev/db_snapshots`, it’s used automatically, with nothing to remember at start time: ``` ddev snapshot --name=seed ddev delete -Oy ddev start ``` To use a different snapshot for one start, name it with `--seed-snapshot`, which takes either a snapshot name from `.ddev/db_snapshots` or the path to a snapshot file elsewhere on disk: ``` ddev start --seed-snapshot=large-dataset ddev start --seed-snapshot=~/datasets/production-mariadb_11.8.zst ``` `--seed-snapshot` applies to that command only and is never written to `config.yaml`. It only seeds a brand-new database volume; if the project already has a database, DDEV says so rather than silently ignoring the flag. Use [`ddev start --reset-database`](<#starting-over-with-a-new-database>) to throw the existing database away first, or [`ddev snapshot restore`]() to restore over it. A snapshot can only seed the database type and version it was made from, which is why the standard `-_.{zst,gz}` suffix `ddev snapshot` gives it has to stay on the filename. You can choose to commit the resulting `seed-*` file in `.ddev/db_snapshots` to your repository if you want teammates and CI to get the same starting dataset on their first `ddev start`, but it may be large and you may want to use another distribution technique. A `seed` snapshot is listed as [custom configuration](), so `ddev start` and [`ddev utility check-custom-config`]() both show it. When `ddev start` actually seeds a fresh database volume, it says so, naming the snapshot and its size and warning that a large one may take a while: ``` Initializing new database volume from the 'seed' snapshot /path/to/project/.ddev/db_snapshots/seed-mariadb_11.8.zst (2.2 GiB)... A large database may take a while; the 600s timeout is set by default_container_timeout. ``` ### Starting Over with a New Database `ddev start --reset-database` removes the project’s database and starts over with a new one. It snapshots the existing database first, unless you add `--omit-snapshot`/`-O`, and asks for confirmation unless you add `--skip-confirmation`/`-y`. The same flags work on [`ddev restart`](). Use it when you want a clean database, or when you’ve changed `database:` in `config.yaml` and `ddev start` refuses because the existing database was created by a different database server. The snapshot it takes is made with the database version that’s actually in the volume, so you can still restore it after you put the configuration back. ``` ddev config --database=postgres:17 ddev start --reset-database ``` To combine it with a seed, so the new database starts out with a dataset of your choosing rather than empty: ``` ddev start --reset-database --seed-snapshot=large-dataset ``` ## Database Clients The `ddev mysql` and `ddev psql` commands give you direct access to the `mysql` and `psql` clients in the database container, which can be useful for quickly running commands while you work. You might run `ddev mysql` to use interactive commands like `DROP DATABASE backend;` or `SHOW TABLES;`, or do things like `echo "SHOW TABLES;" | ddev mysql` or `ddev mysql -udb -pdb` to run with `db` user privileges. The `web` and `db` containers are each ready with MySQL/PostgreSQL clients, so you can [`ddev ssh`]() or `ddev ssh -s db` and use `mysql` or `psql`. ## `mysqldump` and `pg_dump` The `web` and `db` containers come with `mysqldump`. You could run [`ddev ssh`]() to enter the web container, for example, then `mkdir /var/www/html/.tarballs` and run `mysqldump db >/var/www/html/.tarballs/db.sql` or run `mysqldump db | gzip >/var/www/html/.tarballs/db.sql.gz` to create database dumps. Because `/var/www/html` is mounted into the container from your project root, the `.tarballs` directory will also show up in the root of the project on your host machine. The PostgreSQL database container includes normal `pg` commands like `pg_dump`. ## Database GUIs If you’d like to use a GUI database client, you’ll need the right connection details and there may even be a command to launch it for you: - phpMyAdmin, formerly built into DDEV core, can be installed by running `ddev add-on get ddev/ddev-phpmyadmin`. - Adminer can be installed with `ddev add-on get ddev/ddev-adminer` - The [`ddev describe`]() command displays the `Host:` details you’ll need to connect to the `db` container externally, for example if you’re using an on-host database browser like SequelAce. - macOS users can use [`ddev sequelace`]() to launch the free [Sequel Ace]() database browser, [`ddev tableplus`]() to launch [TablePlus](), [`ddev tablepro`]() to launch [TablePro](), [`ddev querious`]() to launch [Querious](), [`ddev dbeaver`]() to launch [DBeaver](). (Each must be installed for the command to exist.) - WSL2 and Linux users can use [`ddev dbeaver`]() to launch [DBeaver](). (Must be installed for the command to exist.) - PhpStorm (and all JetBrains tools) have a nice database browser. (If you use the [DDEV Integration plugin]() this is all done for you.) - Choose a static [`host_db_port`]() setting for your project. For example `host_db_port: 59002` (each project’s database port should be different if you’re running more than one project at a time). Use [`ddev start`]() for it to take effect. - Use the “database” tool to create a source from “localhost”, with the proper type `mysql` or `postgresql` and the port you chose, username `db` + password `db`. - Explore away! - VS Code or any of its forks (Cursor, Windsurf, etc.) has [DevDb](), an extension that lets you access your database directly inside the editor. - There’s a sample custom command that will run the free MySQL Workbench on macOS, Windows or Linux. To use it, run: - `cp $HOME/.ddev/commands/host/mysqlworkbench.example $HOME/.ddev/commands/host/mysqlworkbench` - `ddev mysqlworkbench` ## Database Query Examples You can query, update, or alter databases in DDEV like you would do on a regular server, using `ddev mysql`, `ddev mariadb`, or `ddev psql` or using those command-line tools inside the web or DB containers. Some examples are given below. - Create a new empty database named `newdatabase`: ``` ddev mysql -e 'CREATE DATABASE newdatabase; GRANT ALL ON newdatabase.* TO "db"@"%";' ``` - Show tables whose name begins with `node` : ``` ddev mysql -e 'SHOW TABLES LIKE "node%";' ``` - Use `ddev mysql` or `ddev mariadb` and issue interactive queries: ``` ddev mariadb Reading table information for completion of table and column names You can turn off this feature to get a quicker startup with -A Welcome to the MariaDB monitor. Commands end with ; or \g. Your MariaDB connection id is 28 Server version: 10.11.10-MariaDB-ubu2204-log mariadb.org binary distribution Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement. MariaDB [db]> SELECT * FROM node WHERE type="article"; +-----+------+---------+--------------------------------------+----------+ | nid | vid | type | uuid | langcode | +-----+------+---------+--------------------------------------+----------+ | 11 | 56 | article | 8af917ea-b150-4006-aeb9-877b53ebf289 | en | | 12 | 54 | article | 27a53763-9fd8-4813-853b-b476f0a73849 | en | +-----+------+---------+--------------------------------------+----------+ 2 rows in set (0.007 sec) ```