dbHydrateOverview & Installation
dbhydrate is the native command-line interface for dbHydrate. It is bundled directly with the desktop application for macOS and Windows, sharing the same local encrypted configuration store, connection definitions, and environment protection rules.
# Verify your installation and version$ dbhydrate --version
dbhydrate version 1.0.0 (darwin/arm64)
Configure Your dbHydrate Command
Build production-safe CLI commands for local terminals, automated cron jobs, or CI/CD pipelines.
dbhydrate compare --profile staging-to-prod --engine postgres Expected Exit Codes for dbhydrate compare
- Exit 0Clean: Schemas match perfectly with zero drift.
- Exit 1Drift Detected: Schema differences found. Review output diff.
- Exit 2Connection Error: Failed to reach or authenticate with database.
Working with Profiles
A profile contains your source connection, target connection, selected object filters, and environment protection rules. You can create profiles visually in the desktop application and execute them headlessly with dbHydrate.
# List all configured profiles stored locally$ dbhydrate profiles list
NAME ENGINE SOURCE TARGET PROTECTION
staging-to-prod PostgreSQL dev_db prod_db High
sandbox-refresh MySQL prod_replica sandbox_db Medium
dbhydrate compare
Inspects source and target schemas for drift according to the profile's filter rules. Outputs a human-readable diff summary and returns standard exit codes for automated testing.
Comparing [dev_db] → [prod_db] (PostgreSQL 16)
[+] 1 table modified: app.orders (+ status varchar(32))
[+] 1 index added: idx_orders_status
[=] 28 tables unchanged
Drift detected: 2 object differences found.
dbhydrate plan
Generates ordered, dependency-resolved DDL synchronization SQL without executing it against the target database. Use --out to save the script for auditing, code review, or storage in pull requests.
Plan written to ./migration-plan.sql (2 statements, ordered by FK dependency).
dbhydrate apply
Executes the planned migration against the target database. Respects the target's configured environment protection gates. High-protection targets require dry runs to pass before real execution is permitted.
# Perform a dry run rehearsal first$ dbhydrate apply --profile staging-to-prod --dry-run
✓ Dry run succeeded: Target schema valid. No constraint violations.
# Apply migration with target confirmation$ dbhydrate apply --profile staging-to-prod --confirm-target prod_db
Applying 2 changes to [prod_db]...
✓ 2/2 changes applied successfully. Snapshot saved to run history.
Protection Gate Notice: In high-protection environments, dbhydrate apply requires the --confirm-target <dbname> flag to prevent accidental execution against production.
Exit Codes & Error Messages
Every dbHydrate command ends with an exit code, so shell scripts, Git hooks, and CI jobs can react to the result. Errors are printed to standard error, starting with Error:.
| Code | Meaning |
|---|---|
| 0 | The command finished successfully. |
| 1 | The command stopped with an error: a connection or profile was not found, a database could not be reached, a protection gate blocked the change, the dry run failed, or applying a change failed. |
| 3 | License needed. Only dbhydrate apply uses this code: no license is activated, or the license is expired, revoked, or for another database. |
Common error messages
| Message | Code | What to do |
|---|---|---|
Connection not found: "…" | 1 | Check the name with dbhydrate list. |
Profile not found: "…" | 1 | Check the name with dbhydrate profiles. |
Please specify either --profile … or both --source … and --target … | 1 | Pass a saved profile, or both connections. |
Master password is required to decrypt connection credentials. | 1 | Pass --password, or set DBHYDRATE_MASTER_PASSWORD. |
Cross-engine comparison is not supported. | 1 | Source and target must be the same database type. |
Target connection "…" is in PRODUCTION. Applying changes requires the --yes flag. | 1 | Review the plan, then run again with --yes. |
Target connection "…" is marked as READ-ONLY. Applying migrations is blocked. | 1 | Choose another target, or change the connection in the desktop app. |
Applying changes needs a dbHydrate license (compare and dry-run are free). | 3 | Run dbhydrate license activate <key>, or set DBHYDRATE_LICENSE_KEY in pipelines. |
This license is for dbHydrate for … It can't apply changes to … databases. | 3 | Use a license for that database. |
This license has expired. | 3 | Renew or buy a license on the pricing page. |
Every seat on this license is in use (…). | 3 | Free a seat in your account, or buy another seat. |
Cannot reach the dbHydrate license server (…). | 3 | Applying changes needs an internet connection. |
Your clock is … minutes away from the license server's. | 3 | Synchronize your system clock. |
Comparing and dry runs are free. Only dbhydrate apply checks for a license. In pipelines, set your key as DBHYDRATE_LICENSE_KEY; pipeline runs don't use a seat.
GitHub Actions / CI Example
Fail a pull request build if unexpected schema drift is detected between your staging branch and the reference database:
# .github/workflows/schema-drift.ymlname: Check Schema Drift
on: [pull_request]
jobs:
verify:
runs-on: [self-hosted, macOS]
steps:
- uses: actions/checkout@v4
- name: Run dbhydrate drift check
run: |
dbhydrate compare --profile ci-staging-check || exit 1