ditto

module

v0.1.0 Latest Latest Go to latest Published: Apr 4, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/attaradev/ditto

Links

Open Source Insights

README ¶

ditto

Ephemeral database copies with real schema, real data shape, and no shared state

ditto provisions isolated Postgres and MySQL copies from a scheduled source dump. It is built for teams that want production-faithful database behavior in CI, migration dry-runs, and local development without sharing a mutable staging database.

One clean copy per run, job, or developer
PII scrubbed once during ditto reseed, then baked into every restored copy
Works as a local CLI or as a shared HTTP service for remote runners

Is ditto for you?

ditto is a good fit when:

you already have a Postgres or MySQL source database that the Docker runtime can reach
your tests or migrations need real constraints, triggers, and data shape
shared staging state is making CI or local development unreliable
you want to keep real production data out of developer laptops and CI logs

ditto is not a good fit when:

you only need synthetic fixtures or an in-memory test database
you cannot expose a network-reachable source host to the machine running ditto
you want a hosted service instead of operating a local or shared ditto host

How it works

ditto reseed writes a compressed dump from the configured source database.
ditto copy create or ditto copy run restores that dump into an ephemeral database container.
ditto daemon keeps the dump fresh and deletes expired copies.

See Architecture for the full lifecycle and trade-offs.

Choose your mode

Mode	Use it when	Main commands
Local host	The same machine can run Docker and owns the dump file	`reseed`, `copy create`, `copy run`, `daemon`
Shared server	CI runners or developers should request copies from a central host	`serve`, `copy create --server=...`, `copy run --server=...`

Install

Go install

go install github.com/attaradev/ditto/cmd/ditto@latest

Build from source

git clone https://github.com/attaradev/ditto
cd ditto
go build -o ./ditto ./cmd/ditto

The release workflow is configured to publish packaged binaries and OS packages. See Releases.

Quickstart

Prerequisites:

a Docker-compatible runtime on the same host as ditto
a Postgres or MySQL source host reachable from that runtime
a read-only dump user on that source database

If your source host is localhost, 127.0.0.1, or ::1, this quickstart will fail. Dump helpers run inside containers, so the source must be reachable from the Docker runtime by hostname or network address.

After installation, the shortest working path is four commands:

export DITTO_SOURCE_URL='postgres://ditto_dump:secret@db.example.com:5432/myapp'
export DITTO_DUMP_PATH="$PWD/.ditto/latest.gz"
ditto reseed
ditto copy run -- env | grep '^DATABASE_URL='

What you should see:

ditto reseed completes without replacing the previous dump on failure
ditto copy run prints a DATABASE_URL=... line, proving the copy was created and injected
the copy is destroyed automatically when the command exits

Useful next commands:

ditto status
ditto erd --output schema.mmd
ditto copy run -- go test ./...

For a repeatable file-based setup, move the environment variables into ditto.yaml. See Run Your First Copy and Configuration Reference.

Common workflows

Task	Command
Run one command against a throwaway copy	`ditto copy run -- go test ./...`
Start a shell session with a persistent copy	`eval "$(ditto env export)"`
Generate an ERD from a copy	`ditto erd --output schema.mmd`
Hold a copy across CI steps	`ditto copy create --format=json` and later `ditto copy delete <id>`
Serve copies to remote runners	`ditto serve`

Documentation

Section	Start here
Tutorials	Run your first copy
How-to guides	Local development, CI, Operate a host, Troubleshooting
Reference	Configuration, CLI
Explanation	Architecture

The docs landing page is at docs/README.md.

Trust and project health

CI, build, integration, and markdown checks run on every push and pull request
Security reports are handled privately; see SECURITY.md
Release history is tracked in CHANGELOG.md
Community expectations are in CODE_OF_CONDUCT.md
Contributor workflow is documented in CONTRIBUTING.md

License

MIT

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd Package cmd contains all cobra commands for the ditto CLI.	Package cmd contains all cobra commands for the ditto CLI.
ditto command Command ditto is the main entry point for the ditto CLI.	Command ditto is the main entry point for the ditto CLI.
engine
mysql Package mysql implements the ditto Engine interface for MySQL and MariaDB.	Package mysql implements the ditto Engine interface for MySQL and MariaDB.
postgres Package postgres implements the ditto Engine interface for PostgreSQL.	Package postgres implements the ditto Engine interface for PostgreSQL.
internal
config Package config loads and validates ditto.yaml configuration.	Package config loads and validates ditto.yaml configuration.
copy Package copy manages the lifecycle of ephemeral database copies.	Package copy manages the lifecycle of ephemeral database copies.
dockerutil
dump Package dump manages the scheduled dump of the source database.	Package dump manages the scheduled dump of the source database.
dumpfetch Package dumpfetch resolves a dump URI to a local file path, downloading remote sources (S3, HTTP/HTTPS) to a temp file when necessary.	Package dumpfetch resolves a dump URI to a local file path, downloading remote sources (S3, HTTP/HTTPS) to a temp file when necessary.
erd Package erd provides schema introspection and ERD rendering for Postgres and MySQL databases.	Package erd provides schema introspection and ERD rendering for Postgres and MySQL databases.
obfuscation Package obfuscation applies post-restore PII scrubbing rules to a database copy.	Package obfuscation applies post-restore PII scrubbing rules to a database copy.
secret Package secret resolves secret references to plaintext values.	Package secret resolves secret references to plaintext values.
server Package server implements the ditto HTTP API server.	Package server implements the ditto HTTP API server.
store Package store manages the SQLite metadata database for ditto.	Package store manages the SQLite metadata database for ditto.
version Package version holds build-time version information injected by GoReleaser via -ldflags.	Package version holds build-time version information injected by GoReleaser via -ldflags.
pkg
ditto Package ditto provides a Go client for provisioning ephemeral database copies from a running ditto server.	Package ditto provides a Go client for provisioning ephemeral database copies from a running ditto server.