Configuration Reference

Configuration Reference

DeepDiff DB is configured via a YAML file (default: deepdiffdb.yaml).

---

Full Example

prod:
  driver: mysql
  host: prod-db.example.com
  port: 3306
  user: readonly_user
  password: ${PROD_DB_PASSWORD}
  database: myapp

dev:
  driver: mysql
  host: localhost
  port: 3306
  user: root
  password: root
  database: myapp

ignore:
  tables:
    - sessions
    - cache
    - jobs
  columns:
    - "*.updated_at"
    - "*.created_at"
    - "audit_log.*"

output:
  dir: ./diff-output

migration:
  allow_drop_column: false
  allow_drop_table: false
  allow_drop_index: false
  allow_drop_foreign_key: false
  allow_modify_primary_key: false
  confirm_destructive: true

conflict_resolution:
  default_strategy: manual
  tables:
    config:
      strategy: theirs
    feature_flags:
      strategy: theirs
    audit_log:
      strategy: ours

performance:
  hash_batch_size: 10000
  max_parallel_tables: 2

---

Reference

prod / dev — Database Connection

Field	Type	Required	Description
driver	string	✓	Database driver: mysql, postgres, postgresql, sqlite, mssql, oracle
host	string	✓ (not sqlite)	Database hostname or IP
port	int	—	Port (uses driver default if omitted)
user	string	✓ (not sqlite)	Database username
password	string	—	Database password
database	string	✓	Database name (or file path for SQLite)

Default ports:

Driver	Default Port
MySQL	3306
PostgreSQL	5432
MSSQL	1433
Oracle	1521
SQLite	N/A (file path)

---

ignore — Exclusions

Field	Type	Description
tables	[]string	Tables to skip entirely (no hashing, no diff)
columns	[]string	Columns to exclude from row hashing

Column pattern formats:

Pattern	Matches
updated_at	Column updated_at in any table
users.updated_at	Column updated_at in table users only
*.created_at	Column created_at in all tables
audit_log.*	All columns in table audit_log

---

output — Output Settings

Field	Type	Default	Description
dir	string	./diff-output	Directory for all output files

---

migration — Safety Gates

Field	Type	Default	Description
allow_drop_column	bool	false	Include DROP COLUMN statements in migration
allow_drop_table	bool	false	Include DROP TABLE statements in migration
allow_drop_index	bool	false	Include DROP INDEX statements in migration
allow_drop_foreign_key	bool	false	Include DROP FOREIGN KEY statements in migration
allow_modify_primary_key	bool	false	Include primary key modification statements
confirm_destructive	bool	true	Prefix destructive statements with a -- WARNING comment

When a flag is false, the corresponding SQL is commented out in the generated migration — it will not execute but is visible for review.

---

conflict_resolution — Conflict Strategies

Field	Type	Default	Description
default_strategy	string	manual	Strategy applied to all tables without explicit overrides
tables	map	—	Per-table strategy overrides

Strategies:

Strategy	Description
manual	Block pack generation until operator reviews and resolves
ours	Keep production value; omit conflicting row from migration pack
theirs	Use development value; include row in migration pack

---

performance — Tuning

Field	Type	Default	Description
hash_batch_size	int	10000	Rows fetched per page during keyset pagination. Set to 0 to disable batching (loads entire table into memory).
max_parallel_tables	int	1	Maximum number of tables to hash concurrently. Increase for faster performance on multi-core machines with responsive databases.

Tuning guidance:

• hash_batch_size: Larger values = fewer DB round-trips but more memory per table. Smaller values = more round-trips but lower memory. 10000 works well for most cases.
• max_parallel_tables: Start at 1. Increase to 2–4 if your database can handle concurrent connections without significant lock contention. Setting too high may slow down the database for other users.

---

Secrets Management

Do not hardcode passwords in the config file. Options:

Environment variable substitution (recommended):

prod:
  password: ${PROD_DB_PASSWORD}

Read from file:

PROD_DB_PASSWORD=$(cat /run/secrets/prod_db_password) deepdiff-db diff

Use a secrets manager: Fetch secrets before invoking DeepDiff DB and pass via environment variables.

The config file should be in .gitignore if it contains any credentials.