Documentation

Documentation

Getting started with FoxSchema

FoxSchema compares two databases, shows exactly what differs, and writes the SQL to make one match the other. It never changes your source database — it only writes to the target, and only when you explicitly apply a migration.

1. Install & run

Pick whichever fits your workflow — a shared web instance, a native desktop app, or the terminal.

Web app (Docker — recommended for teams)

# generate a key, then start the single container
cp .env.example .env
openssl rand -hex 32 # put this in APP_ENCRYPTION_KEY
docker compose -f docker-compose.app.yml up -d --build
# → http://localhost:3001

Change the port with PORT= in .env. Saved connections and history persist on a Docker volume.

Desktop app

A regular macOS / Windows / Linux application — nothing to configure, it stores data locally in your OS keychain. Download for your OS →

macOS: “app is damaged and can’t be opened”? It isn’t corrupted — the app is unsigned, so macOS Gatekeeper quarantines it. Clear the flag with xattr -cr "/Applications/Fox Schema.app", or right-click the app in Finder → Open.

CLI

$ fox setup --email you@example.com
$ fox compare --source prod --target staging
$ fox tui # full-screen interactive UI

2. First run & the encryption key

On first launch FoxSchema sets up an encryption key that protects the database passwords you save. In Docker that's the APP_ENCRYPTION_KEY from .env; on desktop it's created for you and kept in your OS keychain.

Keep that key stable. If it changes, previously saved passwords can no longer be read and you'll need to re-enter them.

3. Connect a database

  1. Click Add connection.
  2. Pick the type — PostgreSQL, MySQL, MariaDB, SQL Server, Azure SQL, Oracle, IBM Db2, SQLite, ClickHouse, or Amazon Redshift.
  3. Fill in host, port, database, username, password (and optionally a schema).
  4. Test the connection, then save. Passwords are encrypted at rest and never shown back to the browser.

Do this for both the source (compare from) and the target (compare to).

4. Compare & read the diff

Choose a source and target connection, then click Compare. Results are grouped by object type:

+ Added
in source, not target
~ Modified
differs in both
− Removed
in target, not source
= Unchanged
identical

Click any object to drill into its column, index, foreign-key, and trigger differences. Comparing two different database types (e.g. Postgres → MySQL)? FoxSchema is cross-dialect aware — equivalent types aren't flagged, and a readiness panel shows which object types translate cleanly vs. need a manual look.

5. Generate & apply a migration

  1. From the diff, choose Generate migration to get runnable DDL for the target's dialect. Nothing is applied yet.
  2. Review the SQL, then choose Deploy / Migrate. A pre-migration snapshot is taken first.
  3. Skip failures (optional): continue past any single object that fails instead of rolling back the whole run — the result then lists what was skipped.

You can always copy the generated SQL and run it yourself instead of applying it through FoxSchema. Every applied migration is recorded in History — status, script, snapshot, and per-object results (no passwords stored).

6. Troubleshooting

  • Connection failed / timeout. Check host and port. In Docker, localhost means inside the container — use the host's IP or a service name to reach a DB on your machine.
  • Port already in use. Change PORT in .env and restart with docker compose -f docker-compose.app.yml up -d.
  • "Driver not installed". Some drivers are optional/platform-specific (notably IBM Db2) — see the deployment docs.
Full User Guide → Deployment Guide → Architecture → GitHub Repository →
Scroll to Top