CalibreQuarry and cquarry: small read-only tools for Calibre libraries

[vrnvctss]

Hello everyone.

I'm a computer engineering student and have used Calibre for years. My library is a few thousand books with a lot of virtual libraries and hierarchical tags, and I kept wanting answers the GUI doesn't really give: which series have gaps, how much is unrated, what's actually inside a given virtual library. So I built some command-line tools for my own use. They get used constantly on my machine, and I'm posting them here in case someone else finds them handy.

Posting these particular tools in this particular place is doubly intimidating for me, because they work by reading Calibre's database directly, and this is the forum where Kovid Goyal and the people who actually build Calibre are active. But they're genuinely useful to me, and they might be to someone else, so here goes.

What they are

CalibreQuarry: a CLI (and a small TUI if you run it with no arguments) that opens metadata.db directly, in SQLite read-only mode. It does catalogs, stats, series gap detection, audits, and exports.

cquarry: the Python library underneath it, zero dependencies. If you write your own scripts against your library, this is probably the more useful half.

Both MIT, on GitHub and PyPI. Links at the bottom.

Searching

The search tries to speak Calibre's own grammar, so most of what you'd type into Calibre's search bar works the same way:

cquarry --search 'series:Mistborn and rating:>=4'
cquarry --search 'formats:PDF and not formats:EPUB'
cquarry --search 'search:"Needs Filtering"'    # saved searches work too
cquarry --stats --restrict 'vl:The Tabletop'   # scope any mode to a virtual library

Hierarchical tags match whole branches (tags:Fic.Fantasy picks up Fic.Fantasy.Epic too). It's close to Calibre's behavior but not identical everywhere; the small differences are written up in the README, since surprises are worse than limitations.

Some examples

cquarry --series                 # completeness + gap detection
cquarry --audit                  # untagged/unrated/coverless books, duplicates, db-vs-folder mismatches
cquarry --fts "the spice must flow"  # content search over Calibre's full-text index
cquarry --export --format csv    # the whole library

Series gaps were the original reason I started writing any of this:

Aubrey-Maturin: 20 of 20 (complete)
Asian Saga: Chronological Order: 4 of 6 (incomplete)  ⚠ missing: 2, 3

If Calibre is open

It still works. It reads straight from the database when it can, and if Calibre holds the lock it reads from a temporary snapshot instead (it says so, and the results reflect the last saved state). Nothing in the read path can write anything.

A note on reading the format directly

I know metadata.db is an internal Calibre format, not a documented interface, and that it can change between releases. I take that seriously. The read path opens the database in SQLite read-only mode, so the connection itself can't write. Part of maintaining the library is chasing those schema changes when they land. And when something doesn't look the way it expects, it says so rather than guessing. If anyone here who knows the format better than I do spots me doing something unwise, tell me and I'll fix it.

About writes

I was nervous about letting a program touch metadata.db at all, so the write side is deliberately awkward to do damage with. It's dry-run by default:

# just prints the plan: the ids it resolved and the verbs it would run
cquarry --from-search 'tags:Unsorted' --batch-add-tag Audited

# apply needs Calibre closed and a backup outside the library, then runs
# the whole pass as one transaction
cquarry --from-search 'tags:Unsorted' --batch-add-tag Audited --apply --backup-dir ~/backups

A few things are refused outright (reading-status columns, bulk rating clears), and every change queues an OPF resync so Calibre picks it up cleanly on its next start.

The library underneath

from cquarry.db import CalibreDB

with CalibreDB("~/Calibre Library/metadata.db") as db:
    books = db.search("tags:Fic.SciFi and rating:>=4")
    to_read = db.resolve_vl("To Read")
    notes = db.get_annotations(42)

Pure stdlib. A couple of my other little tools use it too, which is the main reason it ended up as a separate library.

Install

pip install calibrequarry   # the CLI; the command is cquarry
pip install cquarry         # the library

Caveat: I develop on Linux against Calibre 9.x, and that's the only setup I can honestly call tested. It also needs Python 3.14; that's what I run, and I set the floor to match, so I can't say whether older versions work.

One more thing: this code was written with a lot of AI assistance (it's how I learn). If you'd rather not use software written by AI, I completely understand. My feelings won't be hurt, but the AI's will. (jkjk)

Links:

CalibreQuarry: https://github.com/VirInvictus/CalibreQuarry
cquarry: https://github.com/VirInvictus/cquarry

Thanks for reading. If you try it and something breaks, I'd genuinely like to know. And if you have questions, replies in this thread are the best way to reach me.

Also, a big thank you to Kovid for making such a wonderful application. It really changed how I interact with books. These tools are just my attempt to express that in the CLI.

[kovidgoyal]

You're welcome, though why not just use the builtin calibredb command line tool with a script?

[vrnvctss]

Originally Posted by kovidgoyal

You're welcome, though why not just use the builtin calibredb command line tool with a script?

This question is the right one, and it's the question the project grew out of. It started in March as a single stdlib script for exporting my virtual libraries to text files, because I kept writing small parsers around calibredb's output to get machine-readable answers. The first README line even said "without calibredb". The zero-dependency library underneath it (cquarry) came out of that same work in August.

What ended up mattering:

• It's a library, not a subprocess. My tools import it and get structured rows back in-process instead of parsing calibredb's text output, and it's pure stdlib so it works wherever Python is installed.
• The read side works while Calibre is open. It opens the database in read-only mode, and if Calibre holds the lock it falls back to a snapshot copy. Scripting against calibredb locally means waiting for Calibre to close, since it shares the GUI's single-instance lock.
• The pile of scripts became reporting modes: series gap detection, audits (untagged/unrated/coverless, duplicates, database-vs-folder mismatches), stats scoped to a virtual library, and machine-readable exports.

And to be fair about where calibredb wins, it isn't close: adding books with the metadata plugins, the embed/backup/restore/clone verbs, content-server access to remote libraries, catalog generation to EPUB or MOBI, and schema changes tracked upstream automatically instead of by me. My run flush verb literally shells out to calibredb embed_metadata, because it is the right tool for that job.

If any of this is already in calibredb and I missed it, I'd genuinely like to know. I'd rather lean on the builtin where it fits.