edhctl db
edhctl db helps you monitor and maintain the database used by your EDH environment. EDH stores its data (users, desktops, software stacks, settings and more) on Amazon Aurora PostgreSQL, running in Serverless v2 mode so capacity scales automatically with demand.
With edhctl db you can check the health of the database, see how busy it is, clean it up, take backups, recover to a past point in time, and copy all your data to another EDH cluster.
Run edhctl db --help to display the help message.
./edhctl db --help
Usage: app.py db [OPTIONS] COMMAND [ARGS]...
Aurora database management commands.
Commands:
bloat Show tables with dead tuples (bloat candidates for VACUUM).
capacity Show Aurora Serverless ACU utilization over time.
connections Show active database connections grouped by state and user.
export Export cluster tables to CSV for migration.
import Import an export produced by 'edhctl db export'.
locks Show blocking lock chains (if any).
pitr Point-in-time recovery for the Aurora cluster.
schema Show database schema summary (tables, version).
snapshot Manage Aurora cluster snapshots.
status Show Aurora cluster status and database summary.
table-sizes Show largest tables by total size.
vacuum Run VACUUM on database tables to reclaim dead tuples.
Run from the controller
edhctl db commands must run on the EDH controller host. EDH retrieves the database credentials automatically, so you never have to enter a password.
JSON output
Every edhctl db command accepts --output json. Use it when you want to feed the result to a script or a monitoring tool.
Check database health¶
db status¶
Display a one-page summary of your database: its status, engine version, capacity range, backup settings, size and number of active connections. Start here whenever you want to know whether the database is healthy.
./edhctl db status
Cluster: edh-demo-aurorapg
Status: available
Engine: aurora-postgresql 17.4
Writer: edh-demo-aurorapg.cluster-abcdefghijkl.us-east-1.rds.amazonaws.com
Reader: edh-demo-aurorapg.cluster-ro-abcdefghijkl.us-east-1.rds.amazonaws.com
ACU range: 0.5 - 16.0
Deletion prot: enabled
Encrypted: yes
Backup retention: 7 days
PITR window: 2026-10-27T09:12:44 -> 2026-11-03T09:05:12
Database size: 48.3 MB
Connections: 12
Tables: 64
Instances:
edh-demo-aurorapg-writer db.serverless us-east-1a available
The main fields are:
ACU range: the minimum and maximum capacity the database can scale between. An ACU (Aurora Capacity Unit) is a measure of database compute and memory.Backup retention: how many days of automated backups Aurora keeps.PITR window: the period you can restore to with db pitr.
db capacity¶
Show how much capacity (ACU) your database used over the last hours. This helps you decide whether the capacity range fits your workload. Use --hours to change the period (default 6).
./edhctl db capacity --hours 2
ACU utilization for edh-demo-aurorapg (last 2h, 900s intervals):
Time Avg ACU Max ACU
------------------------------------
07:15 0.50 0.50
07:30 0.52 0.61
07:45 0.55 1.50 <- burst
08:00 0.50 0.50
...
------------------------------------
Period avg: 0.52
Period max: 1.50
A <- burst marker highlights intervals where the peak was much higher than the average. If the maximum regularly reaches the top of your ACU range, consider raising it.
db connections¶
List the open database connections, grouped by state and user. Use --idle-threshold to only show connections idle for longer than a number of seconds.
./edhctl db connections
STATE USER COUNT MAX_IDLE
------------------------------------------------
idle edh_app 10 412s
active edh_app 2 0s
------------------------------------------------
Total connections: 12
db locks¶
Show queries that are blocked waiting for another query to finish. On a healthy cluster there is nothing to report.
./edhctl db locks
No blocking locks.
If the web interface feels stuck or slow, run this command to check whether one long-running operation is holding up others.
db schema¶
Display the PostgreSQL version, the schema version, and the list of tables in the database.
./edhctl db schema
PostgreSQL: PostgreSQL 17.4 on x86_64-pc-linux-gnu, compiled by ...
Schema version (alembic): 3f2a1c9d8b7e
Tables (64):
...
Keep the database clean¶
db table-sizes¶
List the largest tables. Use --top to choose how many to display (default 15).
./edhctl db table-sizes --top 5
Table Live Dead Size
--------------------------------------------------------------
...
Live is the number of current rows. Dead is the number of old row versions left behind by updates and deletes, which still take space until they are cleaned up.
db bloat¶
List the tables with the most dead rows. These are the tables that benefit most from db vacuum. Use --top to choose how many to display (default 10).
./edhctl db bloat
Table Live Dead Ratio
------------------------------------------------------------
...
Run 'edhctl db vacuum' to clean up dead tuples.
When there is nothing to clean up, the command returns No dead tuples detected. Database is clean.
db vacuum¶
Clean up dead rows so the database stays fast. By default, vacuum processes every table that has dead rows and refreshes the statistics the database uses to plan queries.
Preview what would run first with --dry-run:
./edhctl db vacuum --dry-run
[dry-run] VACUUM ANALYZE "table_a"
[dry-run] VACUUM ANALYZE "table_b"
Then run it for real:
./edhctl db vacuum
OK VACUUM ANALYZE "table_a"
OK VACUUM ANALYZE "table_b"
Vacuumed 2/2 table(s).
The available options are:
--table: vacuum a single table instead of all of them.--full: also give the freed disk space back. See the warning below.--no-analyze: skip the statistics refresh.--dry-run: show what would run without changing anything.
VACUUM FULL locks tables
--full locks each table while it is processed, so EDH cannot read or write that table until it finishes. Users may see errors or delays in the web interface during that time. EDH asks you to confirm before it starts. Run it during a maintenance window.
A regular vacuum (without --full) does not block the cluster and is safe to run at any time.
Back up the database¶
Aurora takes automated backups of your database every day and keeps them for the backup retention period shown by db status. Use db snapshot to take an extra, manual backup at a moment you choose, for example before an upgrade or a large configuration change. Manual snapshots are kept until you delete them.
db snapshot create¶
Create a manual snapshot. The --name you provide is appended to the database identifier.
./edhctl db snapshot create --name before-upgrade
Creating snapshot edh-demo-aurorapg-before-upgrade...
Waiting for snapshot to become available... done.
Snapshot: edh-demo-aurorapg-before-upgrade
Status: available
Cluster: edh-demo-aurorapg
The command waits until the snapshot is ready. Add --no-wait to return immediately and let the snapshot complete in the background.
db snapshot list¶
List all snapshots of the database, both automated and manual.
./edhctl db snapshot list
Snapshot ID Type Created Status
--------------------------------------------------------------------------------------------------
rds:edh-demo-aurorapg-2026-11-02-04-10 automated 2026-11-02 04:10:31 available
edh-demo-aurorapg-before-upgrade manual 2026-11-03 09:20:07 available
Total: 2 snapshot(s)
db snapshot delete¶
Delete a manual snapshot. Pass the full snapshot ID as shown by db snapshot list. EDH asks you to confirm before deleting; add --confirm to skip the prompt.
./edhctl db snapshot delete --name edh-demo-aurorapg-before-upgrade
Delete snapshot 'edh-demo-aurorapg-before-upgrade'? (Yes, No): yes
Deleted snapshot: edh-demo-aurorapg-before-upgrade
Automated snapshots
You can only delete manual snapshots. Automated snapshots are removed by Aurora when they reach the end of the backup retention period.
Snapshot costs
Manual snapshots are billed for the storage they use. Delete the ones you no longer need.
Recover to a point in time¶
Point-in-time recovery (PITR) lets you get back your data as it was at any second within the backup retention period. This is useful if data was deleted or changed by mistake.
Aurora cannot rewind a running database. Instead, db pitr restore creates a new, separate database containing your data as it was at the time you choose. Your live database is never modified, so EDH keeps running normally while you inspect the copy.
db pitr window¶
Display the time range you can restore to.
./edhctl db pitr window
Cluster: edh-demo-aurorapg
Retention: 7 day(s)
Earliest restore: 2026-10-27T09:12:44 UTC
Latest restore: 2026-11-03T09:05:12 UTC
Window: 167.9 hour(s)
Any second within this window is restorable. Use 'edhctl db pitr restore' to restore to a new cluster.
db pitr restore¶
Restore the database to a point in time, as a new database. The --name you provide is appended to the database identifier to name the copy.
Choose the restore point with one of:
--to: a date and time in ISO 8601 format, for example2026-11-02T14:30:00. Times are treated as UTC unless you include an offset such as+02:00.--latest: the most recent restorable time.
./edhctl db pitr restore --name recovery-nov02 --to 2026-11-02T14:30:00
Source cluster: edh-demo-aurorapg
Restored as: edh-demo-aurorapg-recovery-nov02
Restore point: 2026-11-02T14:30:00+00:00
Restore type: full-copy
The live cluster is not modified. The restored cluster is billed separately
and is NOT tagged with this cluster's edh:ClusterId, so edhctl db commands
continue to target the live cluster.
Restore 'edh-demo-aurorapg' into new cluster 'edh-demo-aurorapg-recovery-nov02'? (Yes, No): yes
Restoring cluster edh-demo-aurorapg-recovery-nov02...
Creating writer instance edh-demo-aurorapg-recovery-nov02-writer (db.serverless)...
Waiting for the writer instance to become available... done.
Restored cluster: edh-demo-aurorapg-recovery-nov02
Writer: edh-demo-aurorapg-recovery-nov02-writer
Endpoint: edh-demo-aurorapg-recovery-nov02.cluster-abcdefghijkl.us-east-1.rds.amazonaws.com:5432
Status: available
The restored database uses the same network settings, capacity range and credentials as your live database. A restore usually takes several minutes or more, depending on the size of your data.
Other options:
--restore-type:full-copy(default) creates a fully independent copy.copy-on-writeis faster to create and shares unchanged data with your live database, which can lower storage costs for short-lived copies.--no-wait: return as soon as the restore has started.--confirm: skip the confirmation prompt.
Delete the copy when you are done
The restored database is billed separately from your live database, and edhctl does not delete it for you. When you have recovered the data you need, delete it from the Amazon RDS console.
edhctl db commands always keep targeting your live database, never the copy. To make EDH use the restored database instead, update the database endpoint in your EDH configuration to point at the new database and restart the web interface.
Copy your data to another cluster¶
db export and db import copy the contents of your database from one EDH cluster to another. Use them when you move to new infrastructure, for example a new EDH cluster built with a newer version.
The overall flow is:
- Run
db exporton the controller of the cluster you are moving from. - Copy the export folder to the controller of the cluster you are moving to.
- Run
db importon the destination controller. - Restart the web interface on the destination cluster.
db export¶
Export every table to a folder on the controller.
./edhctl db export
Exporting 64 table(s) from edh-demo to /opt/edh/edh-demo/cluster_manager/web_interface/db_exports/20261103T093000Z
...
Tables: 64
Rows: 18452
Location: /opt/edh/edh-demo/cluster_manager/web_interface/db_exports/20261103T093000Z
Manifest: /opt/edh/edh-demo/cluster_manager/web_interface/db_exports/20261103T093000Z/manifest.json
Import into another cluster with:
edhctl db import --src /opt/edh/edh-demo/cluster_manager/web_interface/db_exports/20261103T093000Z
By default, the export is saved under /opt/edh/<cluster_id>/cluster_manager/web_interface/db_exports/ with a timestamp. The available options are:
--dest: save the export to a different folder.--tables: comma-separated list of tables to export, instead of all of them.--exclude: comma-separated list of tables to leave out.
The export folder contains one CSV file per table, plus a manifest.json file that describes the export (source cluster, Region, EDH version and row counts).
Exports contain sensitive data
An export is a full copy of your EDH data, including user activity history and API token hashes. EDH saves it on the controller's local disk with access restricted to the owner, not on the shared filesystem.
When you copy it to another controller, use a secure method such as scp, keep the same restricted permissions, and delete the export once the import is done.
db import¶
Load an export into the database of the cluster you are running the command on. Always preview the import first with --dry-run:
./edhctl db import --src /root/db_exports/20261103T093000Z --dry-run
Source export: edh-demo (us-east-1)
Target cluster: edh-new (us-east-1)
EDH version: 26.4.0 -> 26.8.0
Mode: upsert
Tables: 64
...
Dry run, nothing was written.
Then run the import:
./edhctl db import --src /root/db_exports/20261103T093000Z
...
Import 64 table(s) into 'edh-new'? (Yes, No): yes
...
Rows loaded: 18452
Sequences reset: 41
Restart the web interface so cached configuration reflects the imported rows.
Restart the web interface once the import completes:
/opt/edh/$EDH_CLUSTER_ID/cluster_manager/web_interface/socawebui.sh restart
The available options are:
--src: the export folder to import (required).--mode: how to handle data that already exists on the destination.upsert(default): merge the export into the existing data. Rows that already exist are updated, new rows are added, and nothing is removed.replace: empty each destination table first, then load the export. Existing data in those tables is lost.
--tables/--exclude: import only some tables, or skip some tables.--dry-run: show what would be imported without changing anything.--confirm: skip the confirmation prompt.--allow-region-mismatch: allow an import from a different AWS Region. See below.
The import is all or nothing. If any table fails to load, every change is rolled back and the destination database stays as it was.
replace mode deletes existing data
--mode replace permanently removes the existing rows of every imported table on the destination cluster before loading the export. Take a snapshot with db snapshot create first so you can go back if needed.
Importing into a newer EDH version
You can import an export taken on an older EDH version into a newer one. Any new information added in the newer version receives its default value.
Importing into a different AWS Region
Software stacks, base images and saved desktop images refer to Amazon Machine Images (AMIs), which only exist in the Region where they were created. For this reason, db import refuses an export from a different Region by default.
You can either:
- Skip the Region-specific tables with
--exclude software_stacks,base_image_registry,vdi_saved_images, then recreate those items on the new cluster. - Import everything anyway with
--allow-region-mismatch, then update the affected items to use AMIs available in the new Region.