How to Import and Export Databases in DDEV Using `ddev import-db` and `ddev export-db`

DDEV provides the ddev import-db and ddev export-db commands to stream SQL dumps into and out of project containers, supporting automatic compression handling, multiple database targets, and stdin/stdout piping for automated workflows.

DDEV simplifies database management for local development environments through high-level CLI commands that wrap Docker container operations. This guide explains how to import and export databases in DDEV using these built-in commands, based on the implementation in the ddev/ddev open-source repository. Both commands execute inside DDEV-managed containers to ensure compatibility with the correct database client versions for MySQL, MariaDB, or PostgreSQL.

Overview of DDEV Database Commands

DDEV offers two complementary commands for database migration. These are thin wrappers around native database utilities that handle container detection, file streaming, and compression automatically.

• ddev import-db – Loads SQL dumps from the host filesystem or stdin into the project database container. Located in cmd/ddev/cmd/import-db.go, this command uses the Cobra framework with NewImportDBCmd and executes the core logic via importDBRun.

• ddev export-db – Dumps the current database state from the container to the host filesystem or stdout, optionally compressed. Located in cmd/ddev/cmd/export-db.go, this command uses NewExportDBCmd with exportDBRun as its execution handler.

Both commands support .sql, .gz, .bz2, and .xz file extensions, automatically applying the appropriate compression or decompression algorithms.

Importing Databases with ddev import-db

The import command streams data directly into the container's database server, handling schema drops and recreates by default unless specified otherwise.

Basic Import from File or Stdin

To import a standard SQL file into the default database configured in .ddev/config.yaml:

ddev import-db --file=./sql/dump.sql

Alternatively, pipe data directly from stdin, which is useful for chaining commands or importing from remote sources:

cat ./sql/dump.sql | ddev import-db
gzip -dc ./sql/dump.sql.gz | ddev import-db

Working with Compressed Dumps

DDEV automatically detects compression formats based on file extensions. When using the --file flag, the importDBRun function handles decompression transparently:

ddev import-db --file=./sql/dump.sql.gz
ddev import-db --file=./sql/dump.sql.bz2
ddev import-db --file=./sql/dump.sql.xz

Targeting Non-Default Databases

Use the --database flag to import into a specific database rather than the project default. This is essential when working with multiple databases or isolated test schemas:

ddev import-db --database=drupal8_test --file=./sql/test-data.sql

Preserving Existing Schema with --no-drop

By default, ddev import-db executes a DROP DATABASE command before importing to ensure a clean state. To preserve existing tables and perform incremental imports, include the --no-drop flag:

ddev import-db --no-drop --file=./sql/incremental-updates.sql

Exporting Databases with ddev export-db

The export command creates portable SQL backups from running containers, with built-in support for compression and automated directory creation.

Creating Standard SQL Backups

Export the default database to a specific file path:

ddev export-db --file=./backups/production-backup.sql

If the target directory does not exist, DDEV creates it automatically during the exportDBRun execution.

Compressed Exports

Use the --gzip flag to compress output files automatically, reducing storage requirements for large databases:

ddev export-db --gzip --file=./backups/production-backup.sql.gz

The command detects the .gz extension and streams output through the gzip compressor within the container before writing to the host filesystem.

CI-Friendly Exporting with --no-progress

For automated pipelines and scripts where visual progress bars interfere with log output, use the --no-progress flag:

ddev export-db --no-progress --gzip --file=./artifacts/db-dump.sql.gz

This suppresses the progress indicator while maintaining full functionality for container detection and file streaming.

Implementation Details

The import and export functionality is implemented in Go using the Cobra CLI framework. The importDBRun function in cmd/ddev/cmd/import-db.go prepares the input stream, validates the target database exists, and executes the import via the container's database client. Similarly, exportDBRun in cmd/ddev/cmd/export-db.go manages temporary file creation within the container, streams the dump output, and handles compression before transferring the final file to the host.

Both functions are container-aware, meaning they automatically locate the correct database container based on the project's configuration and execute the appropriate native utilities (mysql, mariadb, or psql/pg_dump) inside that environment. This ensures version compatibility between the dump file format and the database server.

Summary

• ddev import-db loads SQL dumps into containers via importDBRun in cmd/ddev/cmd/import-db.go, supporting stdin piping and compressed files.
• ddev export-db creates backups via exportDBRun in cmd/ddev/cmd/export-db.go, with automatic directory creation and compression options.
• Both commands support .gz, .bz2, and .xz compression formats through automatic format detection.
• Use --database to target specific databases and --no-drop for incremental imports without schema deletion.
• Use --no-progress in CI/CD environments to suppress visual output while maintaining full functionality.

Frequently Asked Questions

Can I import a database without dropping the existing tables first?

Yes. Use the --no-drop flag with ddev import-db to skip the DROP DATABASE step. This preserves existing schemas and data, allowing you to perform incremental updates or append operations rather than full replacements.

Does DDEV automatically handle compressed database dumps?

Yes. DDEV automatically detects compression based on file extensions (.gz, .bz2, .xz) and handles decompression/compression transparently during the import or export process. You can also pipe compressed streams directly into ddev import-db using tools like gzip -dc.

How do I export a database without the progress bar for CI environments?

Add the --no-progress flag to ddev export-db. This disables the visual progress indicator while maintaining full export functionality, making it ideal for automated scripts, GitHub Actions, or other CI/CD pipelines where clean log output is required.

Can I import a database into a specific database rather than the default?

Yes. Use the --database flag followed by the target database name. For example: ddev import-db --database=myproject_test --file=test.sql. If omitted, the command uses the default database specified in your project's .ddev/config.yaml file.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}