TigerFS: A Filesystem Backed by PostgreSQL

TigerFS is a filesystem backed by PostgreSQL, built by the Timescale team. It mounts a database as a local directory via FUSE on Linux and NFS on macOS. Every file is a real row. Every directory is a table. Writes are transactions. Multiple processes and machines can read and write concurrently with full ACID guarantees. There are two distinct ways to use it. ```bash # Install (Linux requires fuse3; macOS needs no extra dependencies) curl -fsSL https://install.tigerfs.io | sh # Mount any PostgreSQL database tigerfs mount postgres://localhost/mydb /mnt/db ``` --- ## Mode 1: Data-First Mount any existing PostgreSQL database and explore it with standard UNIX tools. Every path resolves to optimized SQL that gets pushed down to the database. ### Exploring ```bash ls /mnt/db/ # list tables ls /mnt/db/users/ # list rows by primary key cat /mnt/db/users/123.json # read a row as JSON cat /mnt/db/users/123/email.txt # read a single column cat /mnt/db/users/.by/email/[email protected] # lookup by indexed column ``` ### Modifying ```bash echo '[email protected]' > /mnt/db/users/123/email.txt # update a column echo '{"email":"[email protected]","name":"A"}' > /mnt/db/users/123.json # PATCH via JSON mkdir /mnt/db/users/456 # insert a row rm -r /mnt/db/users/456/ # delete a row ``` ### Pipeline Queries Filters, ordering, and pagination can be chained directly in the path. TigerFS executes the whole chain as a single SQL query: ```bash # Last 10 orders for customer 123, sorted by created_at, as JSON cat /mnt/db/orders/.by/customer_id/123/.order/created_at/.last/10/.export/json # Shipped orders, specific columns only, as CSV cat /mnt/db/orders/.filter/status/shipped/.columns/id,total,created_at/.export/csv ``` Available segments (chainable in any order): | Segment | Description | |---|---| | `.by/col/val` | Indexed filter | | `.filter/col/val` | Any column filter | | `.order/col` | Sort | | `.columns/a,b,c` | Column projection | | `.first/N`, `.last/N`, `.sample/N` | Pagination | | `.export/json\|csv\|tsv` | Output format | ### Bulk Ingest ```bash cat data.csv > /mnt/db/orders/.import/.append/csv # append rows cat data.csv > /mnt/db/orders/.import/.sync/csv # upsert by primary key cat data.csv > /mnt/db/orders/.import/.overwrite/csv # replace the table ``` ### Schema Management Tables, indexes, and views are managed through a staging pattern: ```bash mkdir /mnt/db/.create/orders echo "CREATE TABLE orders (...)" > /mnt/db/.create/orders/sql touch /mnt/db/.create/orders/.commit ``` --- ## Mode 2: File-First Create a new database and use it as a transactional shared workspace. Any tool that works with files works here: AI agents, `grep`, `vim`, shell scripts. ### Markdown Apps "Apps" define how TigerFS presents a table as a native file format. Writing `markdown` to `.build/` turns a table into a directory of `.md` files where YAML frontmatter maps to columns and the document body maps to a text column: ```bash echo "markdown" > /mnt/db/.build/blog cat > /mnt/db/blog/hello-world.md << 'EOF' --- title: Hello World author: alice tags: [intro] --- # Hello World Welcome to my blog... EOF # Standard tools work as expected grep -l "author: alice" /mnt/db/blog/*.md mkdir /mnt/db/blog/tutorials mv /mnt/db/blog/hello-world.md /mnt/db/blog/tutorials/ ``` ### Version History Add `history` to the app definition and every edit is captured as a timestamped snapshot in a read-only `.history/` directory. History uses TimescaleDB hypertables for compressed storage and tracks files across renames via stable row UUIDs: ```bash echo "markdown,history" > /mnt/db/.build/notes ls /mnt/db/notes/.history/hello.md/ # 2026-02-24T150000Z 2026-02-12T013000Z cat /mnt/db/notes/.history/hello.md/2026-02-12T013000Z ``` ### Multi-Agent Task Queue `mv` between directories is an atomic database operation. Two agents cannot claim the same task because the underlying transaction will fail for one of them - no distributed lock manager, no coordination API needed: ```bash echo "markdown,history" > /mnt/db/.build/tasks mkdir /mnt/db/tasks/todo /mnt/db/tasks/doing /mnt/db/tasks/done cat > /mnt/db/tasks/todo/fix-auth-bug.md << 'EOF' --- priority: high assigned_to: --- The OAuth token refresh is failing for users with... EOF # Agent claims the task - atomic database operation mv /mnt/db/tasks/todo/fix-auth-bug.md /mnt/db/tasks/doing/fix-auth-bug.md # Agent marks it done mv /mnt/db/tasks/doing/fix-auth-bug.md /mnt/db/tasks/done/fix-auth-bug.md # Check what is in progress ls /mnt/db/tasks/doing/ grep "assigned_to:" /mnt/db/tasks/doing/*.md ``` ### Shared Agent Workspace Multiple agents on different machines can read and write the same files concurrently. Changes are visible immediately with no pull, push, or merge step: ```bash # Agent A writes findings cat > /mnt/db/kb/auth-analysis.md << 'EOF' --- author: agent-a --- OAuth 2.0 is the recommended approach because... EOF # Agent B reads immediately, no sync needed cat /mnt/db/kb/auth-analysis.md # Agent B updates the document cat > /mnt/db/kb/auth-analysis.md << 'EOF' --- author: agent-a reviewed-by: agent-b status: approved --- OAuth 2.0 is the recommended approach because... [approved with comments] EOF # Full edit trail ls /mnt/db/kb/.history/auth-analysis.md/ ``` --- ## Cloud Backends TigerFS works with any PostgreSQL database via connection string. It also integrates with Timescale Cloud and Ghost through their CLIs - no passwords stored in config: ```bash tigerfs mount postgres://user:pass@host/mydb /mnt/db tigerfs mount tiger:abcde12345 /mnt/db # Timescale Cloud tigerfs mount ghost:fghij67890 /mnt/db # Ghost # Fork a database for safe experimentation tigerfs fork /mnt/db my-experiment ``` --- ## Why the File Interface The point of the filesystem abstraction is that every tool already speaks it. `grep`, `awk`, `jq`, shell scripts, AI coding agents (Claude Code, Cursor, and others) all understand files without any SDK, schema definition, or client library to set up. For multi-agent coordination specifically: | Approach | What you build on top | |---|---| | Custom REST API | Endpoints, auth, deployment | | Shared database directly | SQL or ORM, schema definitions, client libraries | | Git | Pull/push/merge workflow, conflict resolution | | S3 | No transactions, no structured queries | | TigerFS | Mount and use standard tools | The coordination logic - atomic task claims, version history, concurrent access - lives in PostgreSQL. The application doesn't implement it. --- ## Current Status TigerFS is at v0.5.0 and described as early-stage by the team, though the core design is stable. The data-first mode is functional today for any PostgreSQL database. Planned additions include support for tables without primary keys (read-only via ctid) and TimescaleDB hypertable time-based navigation. GitHub: [timescale/tigerfs](https://github.com/timescale/tigerfs) - Docs: [tigerfs.io](https://tigerfs.io) ```bash tigerfs mount postgres://localhost/yourdb /mnt/db ls /mnt/db/ ```