pdfdb

pdfdb

Database-backed PDF reader workspace. VoltDB stores PDFs in a DBOS-style filesystem: users, directories, files, and fixed-size file blocks. The main development path is now the native Zathura fork in third_party/zathura-fork: it resolves pdfdb://doc/<slug-or-id> URIs through VoltDB, reconstructs immutable local cache files, and gives Zathura normal local PDFs so the existing PDF plugin ABI stays untouched.

PDF DB.app still exists as the small Wails controller, but it is no longer the primary path for the Zathura-native workflow.

Prerequisites

• Go 1.26+
• Bun
• Docker for local VoltDB development, or another VoltDB reachable on port 21212
• Zathura build dependencies from the fork's README.md
• VoltDB C++ client headers/library and Boost headers when building the Zathura fork with -Dpdfdb=enabled
• Wails v2 only when building the legacy desktop app

Install

go install github.com/lmist/pdfdb/cmd/pdfdb@latest
go install github.com/wailsapp/wails/v2/cmd/wails@latest

Quick Start

docker compose up -d voltdb
export VOLTDB_URL=voltdb://localhost:21212
pdfdb init-db
pdfdb seed
pdfdb list
pdfdb verify
pdfdb profile save default
pdfdb serve

pdfdb profile save default reads the current VOLTDB_URL and stores it in macOS Keychain. The desktop app and CLI can use that active profile without printing or embedding database connection strings.

The Compose file exposes VoltDB's client port at localhost:21212 and persists the database root in the voltdb-data Docker volume. If the default community image does not fit your machine, override it:

VOLTDB_IMAGE=your/voltdb-image:tag docker compose up -d voltdb

Initialize or reset schema through the CLI, not through Compose:

pdfdb init-db
pdfdb seed

Zathura-Native Workflow

Build the fork without requiring the VoltDB C++ client first; this preserves upstream-style builds and keeps the new code compiled behind the disabled bridge:

cd third_party/zathura-fork
meson setup build-pdfdb-disabled -Dpdfdb=disabled -Dseccomp=disabled -Dlandlock=disabled
meson compile -C build-pdfdb-disabled
meson test -C build-pdfdb-disabled pdfdb document types utils

When the VoltDB C++ client is installed, build the native bridge:

meson setup build-pdfdb \
  -Dpdfdb=enabled \
  -Dvoltdb-client-include=/path/to/voltdb-client-cpp/include \
  -Dvoltdb-client-libdir=/path/to/voltdb-client-cpp/lib \
  -Dseccomp=disabled \
  -Dlandlock=disabled
meson compile -C build-pdfdb

Minimal zathurarc:

set pdfdb-database-url voltdb://localhost:21212
set pdfdb-dbos-user pdfdb
set pdfdb-result-limit 200
map <C-b> toggle_pdfdb_explorer

On macOS the fork also registers Cmd+B directly for the pdfdb explorer. Explorer keys are vim-shaped: type to filter, Backspace edits, j/k and arrows move, Ctrl-d/Ctrl-u page results, Esc hides, Enter/o opens, t opens a tab slot, w opens a new Zathura process, and v opens the split target.

Zathura commands added by the fork:

:pdfdb
:pdfdb-open [tab|window|split] <slug-or-id>
:open pdfdb://doc/<slug-or-id>
:tabopen <path-or-pdfdb-uri>
:tabnext
:tabprevious
:tabclose
:splitopen <path-or-pdfdb-uri>
:pane-next

Build and launch the legacy desktop controller:

cd desktop
wails doctor
wails build
open "build/bin/PDF DB.app"

From there, search the database, double-click a PDF to open it in Zathura, use the green open indicators to see active Zathura documents, close them from the row button, and import new PDFs from either a URL or a local file.

For Zathura:

pdfdb open-all

Zathura receives normal read-only PDF files from ~/Library/Caches/pdfdb/documents. The DBOS filesystem remains the source of truth; the local files are disposable cache material for fast desktop opening.

Use Zathura's normal bindings to move through cached files: J/K for next/previous page, gg/G for first/last page, Tab for index mode, and :open <path> for another cached PDF. The native fork adds pdfdb:// before document open and still hands local application/pdf files to the normal PDF plugin.

Commands

pdfdb init-db                      create or update the DBOS filesystem schema in VoltDB
pdfdb ingest <url-or-path> [...]   copy PDFs into DBOS filesystem storage
pdfdb seed                         ingest the three DBOS seed PDFs
pdfdb list                         list documents with ids, slugs, sizes, and page counts
pdfdb verify                       reconstruct all PDFs from DBOS filesystem blocks and verify SHA-256
pdfdb ls [dbos-dir]                list DBOS filesystem directory entries
pdfdb export <id-or-slug> <dest>   copy a DBOS PDF out to a local path or directory
pdfdb rm <id-or-slug>              delete a PDF from DBOS filesystem storage
pdfdb mv <id-or-slug> <dest>       move or rename a PDF inside DBOS filesystem storage
pdfdb cp <id-or-slug> <dest>       copy a PDF inside DBOS filesystem storage
pdfdb serve [host:port]            run the HTTP API with PDF range support
pdfdb open <id-or-slug|all>        open cached PDF(s) in Zathura
pdfdb open-all                     open every cached PDF in Zathura
pdfdb zathura [id-or-slug|all]     start /Applications/Zathura.app from DB cache
pdfdb zathura-pick                 choose a database PDF and open it in Zathura
pdfdb profile list                 list Keychain-backed database profiles
pdfdb profile save [name]          save VOLTDB_URL as the active Keychain profile
pdfdb profile use <name>           switch the active database profile
pdfdb profile delete <name>        remove a database profile

For a database-backed picker in stock Zathura, add this to ~/.config/zathura/zathurarc:

map <C-o> exec /path/to/pdfdb zathura-pick

Use the absolute path printed by which pdfdb (typically $(go env GOPATH)/bin/pdfdb after go install). That gives Zathura a database-connected open action: press Ctrl-o, pick from the pdfdb library, and the selected PDF opens in the desktop Zathura app. A true Zathura plugin is a renderer plugin for a MIME type, not a general UI sidebar extension; the installed API exposes document/page/index/render hooks, not a global file-tree panel.