FathomDB documentation.

Getting started

Install

FathomDB is free, needs no account, and runs on macOS, Windows and Linux. Grab a build or run the one-line installer from the download page — the installer drops the app in place and puts the fathom and fdb commands on your PATH, per-user, no admin. Builds aren't code-signed yet, so the first launch may need a right-click → Open on macOS or More info → Run anyway on Windows; the download page has the exact steps per platform.

First launch

Nothing happens until FathomDB is pointed at a database, so that's step one: hit New connection, hand it a MongoDB URI — or wire up a DocumentDB cluster through a bastion, which is its own section — and you're in. Connections you save come back on this screen as cards; click one to reconnect.

Worth knowing before you touch anything: FathomDB starts read-only. Browse, query, aggregate, run Explain — none of it can change your data. When you actually mean to edit, flip the Read-only toggle in the title bar to Write. It's a deliberate seatbelt, enforced deep in the app rather than by greyed-out buttons — the safety model has the details.

The rest of the title bar takes about ten seconds to learn: Query log pulls up everything you've run, and the theme button loops dark → light → follow-your-OS and remembers where you left it. Esc backs out of any dialog.

Connections

Adding a database starts with New connection (or the + in the sidebar). What you're filling in is small: a Name, a Type — MongoDB or Amazon DocumentDB — and how to reach the server, either as separate form fields or as one connection string.

Form fields vs. connection string

If you already have a mongodb:// or mongodb+srv:// URI — from Atlas, a config file, a teammate — tick Use connection string and paste it. The string wins outright; while it's ticked the discrete fields are ignored. Otherwise leave it off and fill in the pieces:

Host / Port

The server address. Defaults to 127.0.0.1 and 27017.

Username / Password

SCRAM credentials. The password is sealed in the keychain, never written to the profile.

Auth source

The authentication database (often admin).

Default database

Optional — the database the URI points at.

Use TLS

Enable when your server requires TLS. (DocumentDB always uses TLS, so this appears only for MongoDB.)

Not sure you got it right? Test opens a throwaway session, tells you the server version (and whether it detected DocumentDB), and leaves any connection you already have open alone. Save keeps the profile, Duplicate clones it, and on an existing connection Delete removes the profile and its sealed password. Deleting a connection never touches the database it pointed at.

Secrets stay in the keychain

You shouldn't have to think about where passwords end up, so FathomDB doesn't give you a choice. Every secret — the database password, and any SSH password or key passphrase — is encrypted by the main process with Electron safeStorage (your OS keychain: Keychain on macOS, DPAPI on Windows, libsecret on Linux) and referenced by the connection's id, so connections.json holds only ciphertext. Paste a password inline in a connection string and it gets the same treatment: FathomDB pulls it out, seals it, and rewrites the stored string without it. The one caveat is a machine with no keychain at all. There the app falls back to a reversible base64 marker and keeps the file owner-only (chmod 0600) — enough to keep you working, but don't mistake it for protection; only the keychain is real.

DocumentDB & SSH bastions

Amazon DocumentDB speaks the MongoDB wire protocol, so the same driver gets you in — it just wants a few options set differently, and they're fiddly to get right by hand. Set the connection's Type to Amazon DocumentDB DocDB and FathomDB takes care of them:

• TLS on, and retryWrites off (DocumentDB rejects it).
• The Amazon RDS CA bundle ships inside the app, materialized to disk and used automatically — so a DocumentDB connection needs no .pem download and no tlsCAFile path.
• You can paste the connection string straight from the AWS console. Its tlsCAFile=global-bundle.pem — a relative path that wouldn't exist on your machine — is stripped, and the bundled CA validates the chain instead.

Through an SSH bastion

DocumentDB clusters only answer from inside their VPC, which in practice means you reach them the way you reach everything else in there: through a bastion. Tick SSH tunnel (bastion) and FathomDB opens a local port-forward through it, then points the driver at 127.0.0.1 — what you'd otherwise do by hand with ssh -L, minus the terminal window you have to keep open. The fields:

Bastion host / alias

A hostname, or a ~/.ssh/config alias (e.g. gbanker). An alias is resolved with ssh -G, honoring HostName, User, Port, IdentityFile, Include and Match — so you can leave the rest blank.

Port / SSH user

Optional overrides. Blank means "use the SSH config, then the defaults."

Auth

Private key or Password. For a key, give a Private key path (or let the config supply it); your ssh-agent is used too. A typed value always wins over the config.

Key passphrase / SSH password

Sealed in the keychain like the DB password.

None of this is DocumentDB-specific — a plain MongoDB that only answers inside a VPC opens over the same tunnel. Two things happen under the hood to make a tunnel actually work: the driver connects directly to the forwarded endpoint (directConnection), because replicaSet discovery would hand it member addresses a single forward can't reach; and the 127.0.0.1 hostname mismatch is allowed while the certificate chain is still validated against the CA. You give up the name check, not the trust check.

Explain on DocumentDB

One thing to expect: DocumentDB reports query plans in a different shape than MongoDB, so the summary fields FathomDB normally pulls out may not reflect index usage there. Rather than show you a confident-looking banner that might be wrong, the Explain view on a DocDB connection drops the plan summary and says so in a note. Read the raw plan underneath — it's authoritative.

Browsing

The tree

Everything you're connected to hangs off the sidebar: connections expand into databases, databases into collections, and each collection carries an estimated document count, so you can tell the big ones from the empty ones before you open anything. If you've lost track of which connection you're actually talking to, the status bar at the bottom of the window says.

Connection overview

Before you dig into a cluster you usually want a feel for its shape — how many collections, how much data, how heavy the indexes are. Select a connection (or a database) and that's what you get: collections, objects (documents), data size, storage size, indexes and index size, drawn from a single dbStats call per database — one round trip, not a crawl.

List, JSON, Table

Different questions want different views of the same documents, so a collection gives you three:

• List — each document as a field-by-field card, with a BSON type badge on every value. The one to read in.
• JSON — the raw Canonical Extended JSON, for when you want to see exactly what's stored.
• Table — a flattened grid, columns across the sampled fields, for scanning many documents at once.

Whichever you pick, the types are real, because documents cross into the app as BSON rather than re-parsed text: an ObjectId is an ObjectId, a Decimal128 keeps its precision, a Date is a date. Nested subdocuments and arrays expand inline, and when a row isn't enough, clicking it opens the whole document in full.

Querying

The filter bar

Type filters the way you'd type them in the shell. FathomDB uses the same relaxed mongo-shell parser Compass does, so unquoted keys, single quotes, ObjectId("…"), ISODate("…"), /regex/flags, NumberDecimal(…) and trailing commas all work — and they come out as real BSON, not strings that look like it:

{ status: "shipped", total: { $gte: NumberDecimal("50") } }

Options, sorting and paging

The filter is usually enough. When you need to shape the result — project a few fields, sort, pin an index — the rest of the query lives under Options ▾. Everything there is shell/EJSON, and blank means "not set":

Project

e.g. { "name": 1, "_id": 0 }.

Sort

e.g. { "createdAt": -1 }.

Collation

e.g. { "locale": "en", "strength": 2 }.

Index hint

An index name, or a key spec like { "status": 1 }.

Limit

A cap on the total documents the query returns (∞ = no cap) — distinct from the page size below.

Skip

Offset into the result set.

Max time (ms)

A server-side time budget for the query.

Paging happens beneath the results — Prev / Next, with Per page at 25, 50, 75 or 100 (default 50). The count you see is exact for a filtered query, and it's computed with the same collation and hint as the query itself, so it never disagrees with the rows in front of you. With no filter it's an estimate, which is the cheap path on a big collection.

Saved & recent queries

There are two ways to get a query back. If it's one you'll keep reaching for, save it: a saved query is a named favorite, tied to its db.collection and stored with your profiles. If you just want the thing you ran ten minutes ago, it's in the query bar's recent history — every run lands there, most-recent first, as the full query (filter, projection and sort), and the list persists across restarts. Picking from either restores the whole query, and both work in read-only mode. This is a convenience list for the query bar; the on-disk query log is a separate, fuller record.

Explain

When a query feels slow, don't guess — ask the server. One click runs explain("executionStats") and pulls out the parts you read first: the winning stage, the index an IXSCAN used, and documents returned, documents examined, keys examined and execution time. The full queryPlanner sits underneath for when the summary raises more questions than it answers.

Export to a language

Once a query does what you want, you usually need it in application code, not a GUI. The </> button hands it over as ready-to-paste code in nine languages — mongosh, Node.js, Python, Java, C#, Go, Ruby, PHP and Rust — with filter, projection, sort, limit and skip carried across, so you're not retyping the query you just got right.

Export the result set

Need the data itself — for a spreadsheet, a script, a colleague? Export ▾ in the toolbar writes the whole matching result set to a file, not just the page you're looking at. It replays the current filter with your projection, sort, collation, hint and any query-level Limit, and it streams straight to disk, so a collection that would never fit in memory still exports fine. Two formats:

Export as CSV

Compass-style dotted-path flattening — nested fields become columns like address.city and tags.0, and the header is the union of every leaf path — with RFC-4180 escaping and readable BSON scalars (an ObjectId as 24 hex, a Date as ISO-8601, a Decimal128 as its digits).

Export as JSON

A single, lossless Canonical Extended JSON array, so every BSON type round-trips exactly.

Exporting only reads, so it works in read-only mode; the only time it's disabled is before a query has produced anything to export. When it finishes, FathomDB tells you how many rows it wrote.

Aggregations

Pipelines use the same relaxed shell syntax as the filter bar, so anything you'd paste into mongosh works here as-is. There's one pipeline but two ways to edit it — Builder / Text — and you can flip between them whenever one suits the moment better. ▶ Run executes whichever you're in, with results below.

Text mode

When you already have the pipeline — from a script, a ticket, a teammate — Text mode is one editor for the whole thing. Paste it and run:

[
  { $match: { status: "shipped" } },
  { $group: { _id: "$status", n: { $sum: 1 }, revenue: { $sum: "$total" } } },
  { $sort: { revenue: -1 } }
]

Builder mode

When you're still working a pipeline out, Builder mode breaks it into a Compass-style column of stage cards, one per stage, so you can reason about each step on its own. A card is an operator — pick a common one from the dropdown or type any $stage — plus its EJSON body, checked for valid JSON as you type. Cards can be moved up or down, added below one another, or removed, but the one you'll lean on is enable or disable: a disabled stage is skipped, not deleted, so you can pull a $match out to see what it was hiding and put it back without retyping it. Builder and Text stay in sync — switching carries your edits across — so rough a pipeline out as text and refine it in cards, or the reverse.

Per-stage previews

The hard part of debugging a pipeline is working out which stage went wrong. So every Builder card shows the documents as of that stage: FathomDB runs the enabled stages up to and including it against a small sample and shows the first few results, and you can watch the data narrow card by card until it stops looking the way you expected. Leave Auto-preview on and they refresh as you edit; turn it off and hit ↻ Preview on a card when you want one. Previews are strictly reads — any $out or $merge stage is stripped before a preview runs, so watching a pipeline can never execute its side effects.

Export the pipeline

Same deal as a query: the </> button turns the pipeline into ready-to-paste code in the same nine languages — mongosh, Node.js, Python, Java, C#, Go, Ruby, PHP and Rust.

Query log

Sooner or later you'll want to know exactly what you ran against a database last Tuesday, and on which connection. Query log in the title bar answers that: every find and aggregation FathomDB has run, across all connections rather than just the one you have open, newest first, 50 per page. Each row is one query:

Time

When the query ran.

Connection

The saved connection's name.

Namespace

The db.collection it ran against.

Kind

find or agg.

Query

The filter (for a find) or the whole pipeline (for an aggregation) — enough to re-run.

Rows

How many documents came back.

ms

How long it took.

It's not just a record. Click any row to re-run that query — FathomDB reopens the collection and replays the filter or pipeline. Failed queries are kept too, since they're often the interesting ones: the row reads — for rows and carries the error in its tooltip.

Download the log

For an audit trail, or just to grep past queries from a terminal, Download ▾ writes the whole log to a file. Two formats:

Download as JSON

A single array of log entries.

Download as CSV

A table with a header row — time, connection, db, collection, kind, query, rows, ms, ok, error — RFC-4180 escaped.

On disk, with rollover

There's no database behind the log, and that's deliberate: it's a plain JSON-lines file at ~/Fathom/query-log.jsonl, one entry per line, so it survives restarts and anything from jq to grep reads it cleanly. It won't grow forever, either. Max log size in the viewer caps it — 100 MB by default, adjustable from 1 MB up to 1 GiB — and when the file would pass the cap it rolls over into a single query-log.1.jsonl and starts fresh, so the oldest entries fall off the end and disk use stays bounded. Clear log deletes both files.

Schema, indexes & validation

Schema sampler

A schemaless database won't tell you what a collection looks like, so FathomDB goes and looks. The Schema tab samples up to 200 documents (via $sample, falling back to a plain find) and reports each field, how many of the sampled documents carry it, and the BSON types it takes, with counts. That last part is the useful bit: a field that's a string in most documents and a number in a few shows up as exactly that, and so do nulls and optional fields — what's really there, not a guessed schema.

Knowing a field is a string is only half the question; you usually want to know what's in it. So each field also carries a small value distribution — its top values with counts and percentages (the five most common, then a “+N more values” line) — and numeric and date fields add the min…max range across the sample. A high-cardinality field whose distinct values outrun the tracking cap is flagged as approximate rather than passed off as exact.

Indexes

Every index on the collection is listed with its name, keys and direction, and the properties that change how it behaves — unique, sparse, TTL, partial and collation. When Explain shows you a COLLSCAN, this is where you fix it: + Create index opens the form below. drop removes an index by name (the built-in _id_ index can't be dropped). Both are writes, so both need Write mode.

Keys is the one thing you have to fill in, and it doubles as the index type: 1 / -1 for an ascending/descending field, or a string for a special index — e.g. { "location": "2dsphere", "body": "text", "sku": "hashed" }. Everything else on the form is optional:

Unique / Sparse

Reject duplicate keys, or index only the documents that carry the field.

Name

A custom index name; blank lets the driver derive one from the keys.

Expire after (s)

A TTL in seconds — makes an expiring index that reaps old documents.

Partial filter

An EJSON predicate (e.g. { "status": "active" }) so only matching documents are indexed.

Collation

An EJSON collation (e.g. { "locale": "en", "strength": 2 }) for language-aware ordering.

Validation

Validation rules are the one bit of schema MongoDB does enforce, and the Validation tab shows you what the server holds: the collection's $jsonSchema validator, its level (off, moderate or strict) and its action (error or warn). Edit the rules, press Apply, and FathomDB writes them back with collMod. That's a write, so it sits behind Write mode — in read-only mode the tab says “Read-only — enable Write mode to edit validation rules.” instead.

Editing documents

Once you've flipped to Write mode, a collection gives you the full set: insert a new document, edit / replace an existing one, duplicate one, delete one. Inserts and edits happen in an Extended JSON editor — the document as it's actually stored, types and all. None of it is available until Write mode is on.

For a quick one-field fix you don't need the editor. In List view, click a scalar value, type, press Enter. If what you typed isn't valid, the field stays open and turns red rather than quietly reverting to the old value. Under the hood each inline edit is a confirmed full-document replace, not a partial patch, and _id is never inline-editable.

EJSON / BSON fidelity

The thing database GUIs most often get wrong is types — it shows you a Long, you save, and now it's a double. FathomDB sidesteps that by moving documents as Canonical Extended JSON, which is lossless for BSON: ObjectId, Date, Decimal128, Long, Binary and the integer/double distinction all round-trip exactly. Documents you write are parsed in canonical mode, so an int stays an int and a double stays a double. Filters and pipelines, where that strictness would just get in the way, are parsed in relaxed mode — typing { age: 30 } behaves the way you'd expect.

Importing a CSV or JSON file

Got the data in a file already? Import ▾ in the toolbar loads a CSV or JSON file into the current collection, one document per row. It's a write like any other, so it needs Write mode and is refused on a Protected connection — the trigger stays dimmed until the connection is writable. Inserts go in batches, and if one fails partway through, FathomDB tells you how many rows did land, so you know where you stand rather than guessing.

Import CSV file…

The first row is the header. Types are inferred conservatively — a value stays a string unless it's unambiguously a boolean or a number that round-trips exactly, so leading-zero ids, zip codes and phone numbers keep their zeros. Blank cells are omitted rather than stored as empty strings.

Import JSON file…

A top-level array, a single object, or JSONL (one object per line). Extended JSON is honored, so { "$oid": … }, { "$date": … } and the rest become real BSON.

Bulk update & delete

Sometimes the fix isn't one document, it's every document matching the current filter. Update matching and Delete matching in the toolbar do that in one shot — which is exactly why they're the most guarded actions in the app. Both are write-gated in the main process like any other write, and both stop to confirm first.

Update matching

Takes an update-operator spec ({ "$set": … }) or an aggregation pipeline. A plain replacement document is refused — it would overwrite every matched document into identical copies.

Delete matching

Removes every document the filter matches.

Before either runs, FathomDB:

• Counts first. The confirmation states exactly how many documents will be affected — “This will UPDATE 1,240 document(s) matching {…} on "Prod" · shop.orders — this cannot be undone.”
• Makes you type the collection name to confirm.
• Warns louder on an empty filter. When the filter is empty or {}, the warning spells out that EVERY document in the collection will be affected.
• Adds the PROD caution on a production connection, like every destructive action.

Safety model

Read-only by default

The default posture is that you can't break anything. FathomDB opens read-only and remembers the choice across restarts — only an explicit switch to Write mode is persisted, so the safe state is the one you start in. The title bar toggle reads Read-only until you flip it to Write, and until you do, any write attempt is refused with “Read-only mode is on — enable Write mode to make changes.”

Per-connection flags

The global toggle is one switch for everything. For the connections you're genuinely nervous about, two flags under Safety in the connection editor tighten it further:

Protect (read-only)

Refuses every write to this connection in the main process — even when the global toggle is on Write. The only way past it is to uncheck it in the connection's settings, which is the point: writing to that database has to be a decision, not a slip.

Production database

Marks the connection with a loud PROD badge and adds a bold “⚠ {name} is flagged as a PRODUCTION database.” line to every destructive confirmation.

Destructive actions confirm

Anything destructive asks first, and the prompt names the target connection — because the classic mistake isn't dropping the wrong collection, it's dropping the right one on the wrong cluster. The riskiest operations go further and make you type a name to proceed:

• Drop database and drop collection require typing the database or collection name.
• Update matching and delete matching require typing the collection name, and warn louder when the filter is empty — see bulk update & delete.
• Restore with drop requires an explicit confirmation before it replaces existing data.
• Deleting a connection asks to confirm, and reminds you the database itself isn't touched.

Dump & restore

You shouldn't have to install mongodump to take a backup, so FathomDB bundles the MongoDB Database Tools for each platform. Dump writes a whole database or a single collection to a folder as standard BSON — the same format mongodump produces, so a dump taken here restores anywhere. Restore reads a dump folder back into any connection, with an optional drop-first for when you want a clean slate. Both start from the sidebar — the dump icon on a connection, database or collection; the restore icon on a connection — and you can watch progress stream into a panel as the job runs.

• Dump is read-only — allowed regardless of the write gate.
• Restore writes — it needs Write mode and respects a Protected connection.
• Both run over the same SSH tunnel, TLS and Amazon CA the app already uses, so an Amazon DocumentDB cluster dumps and restores with no extra exposure.
• The password is passed to the tools through a temporary 0600 config file, never on the command line, so it can't leak into ps.

Command line

The connections you save in the app are usable from a terminal too. The installer puts fathom and its alias fdb on your PATH; run it bare (or fathom open) and it launches the app, give it a subcommand and it runs headless — same connection manager, same SSH tunnels, same driver as the GUI — prints, and exits.

Managing connections

$ fathom ls                         # list saved connections
$ fathom ls "Local"                 # list databases in a connection
$ fathom ls "Local" shop            # list collections in a database
$ fathom add "Local" mongodb://127.0.0.1:27017
$ fathom add "Prod" "mongodb://cluster.example:27017" --docdb --ssh gbanker
$ fathom set "Local" --name "Local Mongo" --mongo --no-ssh
$ fathom rm "Local"

add takes a name and a URI, plus --docdb to mark it Amazon DocumentDB and --ssh <alias> to tunnel through a bastion. set edits a saved connection (--name, --uri, --docdb/--mongo, --ssh alias/--no-ssh). Passwords get the same treatment as in the GUI: any password in a URI is pulled out and sealed in the keychain.

Querying

$ fathom find "Local" shop.orders '{status:"shipped"}' --limit 5
$ fathom find "Local" shop.orders '{}' --sort '{createdAt:-1}' --projection '{orderNo:1}'
$ fathom agg  "Local" shop.orders '[{"$group":{"_id":"$status","n":{"$sum":1}}}]'

find takes an optional filter and --limit / --skip / --sort / --projection; agg takes a pipeline as an EJSON array. <conn> is a saved connection's name or id, and it resolves exactly as in the app — TLS, retryWrites and the SSH-bastion tunnel included — so a bastion-tunnelled DocumentDB connection you set up once in the UI is scriptable with no second setup.

stdout / stderr split

The output is built to be piped. Results print as canonical Extended JSON on stdout; the short status line goes to stderr instead (e.g. 5 shown · ~57 matched), so jq gets clean JSON and you still see what happened:

$ fathom find "Local" shop.orders '{status:"shipped"}' | jq '.[].orderNo'

Privacy & telemetry

FathomDB is local-first: there's no sign-in, no sync and no cloud in the path between you and your database. Your connections and settings live in one file on your disk (~/Fathom/connections.json), and passwords are sealed in the OS keychain — never in that file, never sent anywhere.

What telemetry does and doesn't send

There is telemetry, so here's the honest version. The app reports anonymous, cookieless usage and crash analytics — enough to fix bugs and see which features actually get used. It runs off the main thread so it can never block or slow the app, and what it sends is deliberately coarse, low-cardinality labels: the engine (mongodb / documentdb), whether TLS or SSH was on, a query's duration and result count, which export language you picked, handled/unhandled errors. What it never sends is anything that identifies you or your data — not your host or connection string, not credentials, not query text, not document contents.

It also stays dormant unless every one of these holds: telemetry is on (the default), a reporting key was compiled in (official CI builds only), the build is packaged, and it isn't a headless/test run — so a dev build or a CI run never reports anything. Want none of it? Open the gear (Settings) in the title bar and switch Anonymous telemetry off — it takes effect immediately. (That flips "telemetry": false under settings in connections.json, which you can also edit by hand.) And if you'd rather read the policy than take the summary on trust, the exact event list is in the repository's docs/ANALYTICS.md.