{"id":48467036,"url":"https://github.com/timescale/tigerfs","last_synced_at":"2026-05-29T19:01:46.218Z","repository":{"id":346025547,"uuid":"1140971886","full_name":"timescale/tigerfs","owner":"timescale","description":"Mount PostgreSQL as a filesystem. Build apps with files, explore databases with ls and cat.","archived":false,"fork":false,"pushed_at":"2026-05-28T06:42:19.000Z","size":2354,"stargazers_count":592,"open_issues_count":7,"forks_count":20,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-28T07:08:49.252Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://tigerfs.io/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/timescale.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T02:37:00.000Z","updated_at":"2026-05-28T06:42:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/timescale/tigerfs","commit_stats":null,"previous_names":["timescale/tigerfs"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/timescale/tigerfs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftigerfs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftigerfs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftigerfs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftigerfs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/timescale","download_url":"https://codeload.github.com/timescale/tigerfs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/timescale%2Ftigerfs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33666290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-29T02:00:06.066Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-07T05:00:42.105Z","updated_at":"2026-05-29T19:01:46.205Z","avatar_url":"https://github.com/timescale.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# TigerFS\n\nA filesystem backed by PostgreSQL, and a filesystem interface to PostgreSQL.\n\nEvery file is a real PostgreSQL row. Directories are tables. File contents are columns. Multiple agents and humans can read and write the same files concurrently with full ACID guarantees. Every change is versioned and reversible (file-first with history). No sync protocols. No coordination layer.  **The filesystem is the API.**\n\nYou can use TigerFS in two ways:\n\n* **File-first**: Write markdown with frontmatter or other file types, organize into directories. Writes are atomic, changes are versioned, and everything is reversible.  Any tool that works with files -- Claude Code, Cursor, grep, vim -- just works.  Build lightweight workspaces via the filesystem: multi-agent task coordination is just `mv`'ing files between todo/doing/done directories.\n\n* **Data-first**: Mount any Postgres database and explore it with `ls`, `cat`, `grep`, and other unix tools. For\nlarge databases, chain filters into paths that push down to SQL:\n`.by/customer_id/123/.order/created_at/.last/10/.export/json`. No database client or SQL needed, and ships with agent skills.\n\nBoth modes are backed by the same transactional database. You get real transactions, true concurrent access, and a SQL escape hatch when you need it. TigerFS mounts via FUSE on Linux and NFS on macOS, no extra dependencies needed.\n\n### Agent Skills\n\nTigerFS ships with agent skills for Claude Code, Gemini CLI, Codex, and others, automatically installed at mount time. You don't need to learn the filesystem interface. Just ask:\n\n- \"Create a workspace for my notes\"\n- \"What changed since the savepoint?\"\n- \"Undo agent-7's changes\"\n- \"Show me the last 10 orders by customer 123\"\n\nThe skills teach your agent the filesystem paths, diff commands, and undo workflows. For details on what's underneath, read on.\n\n### Install\n\n```bash\ncurl -fsSL https://install.tigerfs.io | sh\n```\n\n**New project?** Start file-first. **Existing database?** Start data-first.\n\n### The Filesystem is the API\n\nYour data lives in regular files and directories. Metadata, queries, and operations live in dot-directories: invisible by default, always available.\n\n```bash\n$ ls /mnt/db/notes/\nhello.md  tutorials/\n\n$ ls -a /mnt/db/notes/\n.  ..  .history/  .log/  .savepoint/  .undo/  hello.md  tutorials/\n```\n\nDot-directories are the control surface. Navigate them to browse history, filter data, undo changes, and manage schemas, all through the same filesystem interface.\n\n```\n┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐\n│  Unix Tools  │────▶│  Filesystem  │────▶│   TigerFS    │────▶│  PostgreSQL  │\n│  ls, cat,    │     │   Backend    │     │   Daemon     │     │   Database   │\n│  echo, rm    │◀────│  (FUSE/NFS)  │◀────│              │◀────│              │\n└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘\n```\n\n| File-first | Data-first |\n|------------|------------|\n| `.history/` past versions | `.info/` table metadata |\n| `.log/` operation log with diffs | `.by/` index lookups |\n| `.savepoint/` bookmarks for undo | `.filter/` column filtering |\n| `.undo/` preview and apply undo | `.order/`, `.first/`, `.last/` sort and paginate |\n| `.build/` create workspaces | `.export/`, `.import/` bulk I/O |\n| | `.create/`, `.modify/`, `.delete/` schema management |\n\n## File-First: Transactional Workspace\n\n### Workspaces\n\nWorkspaces tell TigerFS how to present a table as a native file format. Write \"markdown\" to `.build/` and the table becomes a directory of .md files with YAML frontmatter:\n\n```bash\n# Mount a database and create a workspace with history\ntigerfs mount postgres://localhost/mydb /mnt/db\necho \"markdown,history\" \u003e /mnt/db/.build/blog\n\n# Write a post. Frontmatter becomes columns, body becomes text\ncat \u003e /mnt/db/blog/hello-world.md \u003c\u003c 'EOF'\n---\ntitle: Hello World\nauthor: alice\ntags: [intro]\n---\n\n# Hello World\n\nWelcome to my blog...\nEOF\n\n# Search, edit, and manage content with standard tools\ngrep -l \"author: alice\" /mnt/db/blog/*.md\n```\n\nOrganize files into directories. `mkdir` creates folders, `mv` moves files between them:\n\n```bash\nmkdir /mnt/db/blog/tutorials\nmv /mnt/db/blog/hello-world.md /mnt/db/blog/tutorials/\n```\n\nSee [docs/file-first.md](docs/file-first.md) for column mapping, frontmatter handling, and use cases.\n\n### History, Savepoints, and Undo\n\nAny workspace can opt into automatic versioning. Every edit and delete is captured as a timestamped snapshot. Create savepoints before risky work, preview what changed, and undo if needed.\n\n```bash\necho '{\"description\":\"Before refactoring\"}' \u003e /mnt/db/notes/.savepoint/checkpoint.json\n# ... Perform refactoring ...\ndiff -u /mnt/db/notes/.log/\u003cid\u003e/before /mnt/db/notes/.log/\u003cid\u003e/current      # Compare changes to single file\ndiff -ru /mnt/db/notes/.undo/to-savepoint/checkpoint /mnt/db/notes/ -x '.*' # Review all changes\ntouch /mnt/db/notes/.undo/to-savepoint/checkpoint/.apply                    # Undo all changes since savepoint\n```\n\nPer-user undo, single-file undo, and full version history are also available. See [docs/history.md](docs/history.md) for the full guide.\n\n### Use Cases\n\n**Shared agent workspace.**\nMultiple agents and humans operate on the same knowledge base concurrently. Changes are visible instantly. Every edit is automatically versioned, so if one agent overwrites another's work, browse the full edit trail in `.history/` and recover it.\n\n```bash\n# Agent A writes research findings\ncat \u003e /mnt/db/kb/auth-analysis.md \u003c\u003c 'EOF'\n---\nauthor: agent-a\n---\nOAuth 2.0 is the recommended approach because...\nEOF\n\n# Agent B reads it immediately, no sync, no pull\ncat /mnt/db/kb/auth-analysis.md\n\n# Browse the full edit trail\nls /mnt/db/kb/.history/auth-analysis.md/\n```\n\n**Multi-agent task queue.** Three directories (`todo/`, `doing/`, `done/`) and `mv` is your only API. Moves are atomic database operations, so two agents can't claim the same task.\n\n```bash\n# Set up a task board\necho \"markdown,history\" \u003e /mnt/db/.build/tasks\nmkdir /mnt/db/tasks/todo /mnt/db/tasks/doing /mnt/db/tasks/done\n\n# Agent claims a task by moving it to doing\nmv /mnt/db/tasks/todo/fix-auth-bug.md /mnt/db/tasks/doing/fix-auth-bug.md\n\n# Marks it complete\nmv /mnt/db/tasks/doing/fix-auth-bug.md /mnt/db/tasks/done/fix-auth-bug.md\n\n# See what everyone is working on\nls /mnt/db/tasks/doing/\ngrep \"author:\" /mnt/db/tasks/doing/*.md\n```\n\n**Safe exploration.** An agent creates a savepoint, investigates a bug, makes changes across multiple files. If the approach doesn't work, undo atomically to the savepoint. Every file reverts in one step.\n\n```bash\n# Agent creates savepoint before investigating\necho '{\"description\":\"Before investigating auth bug\"}' \u003e /mnt/db/notes/.savepoint/pre-investigation.json\n\n# Agent explores, edits multiple files...\n# User reviews: \"that's not right, roll it back\"\ntouch /mnt/db/notes/.undo/to-savepoint/pre-investigation/.apply\n# All files restored to pre-investigation state\n```\n\n## Data-First: Database as Filesystem\n\nMount any Postgres database and explore it with `ls`, `cat`, `grep`. Every path resolves to optimized SQL pushed down to the database.\n\n```\n  Filesystem                       Database\n  ──────────                       ────────\n  /mnt/db/                     →   tables (default schema)\n  /mnt/db/users/               →   rows (by PK)\n  /mnt/db/users/123/           →   columns as files\n  /mnt/db/.schemas/            →   all schemas (including default)\n```\n\n```bash\n$ ls -a /mnt/db/users/\n.  ..  .by/  .filter/  .order/  .first/  .last/  .info/  .export/  .import/\n1/  2/  3/  4/  5/  ...\n```\n\n**Explore an unfamiliar database.** Point an agent at a mounted database and it understands the schema immediately using `ls` and `cat`. No SQL, no database client, no connection strings to pass around.\n\n**Quick data fixes.** Update a customer's email, toggle a feature flag, delete a test record. One shell command instead of opening a SQL client, remembering the table schema, and writing a `WHERE` clause.\n\n**Export and analyze.** Chain filters, ordering, and pagination into a single path, then pipe the result into `jq`, `awk`, or export as CSV for a spreadsheet.\n\n### Explore\n\n```bash\n# Mount an existing database\ntigerfs mount postgres://localhost/mydb /mnt/db\n\nls /mnt/db/                                      # List tables\nls /mnt/db/users/                                # List rows (by primary key)\ncat /mnt/db/users/123.json                       # Row as JSON\ncat /mnt/db/users/123/email.txt                  # Single column\ncat /mnt/db/users/.by/email/foo@example.com.json # Index lookup\n```\n\n### Modify\n\n```bash\necho 'new@example.com' \u003e /mnt/db/users/123/email.txt            # Update column\necho '{\"email\":\"a@b.com\",\"name\":\"A\"}' \u003e /mnt/db/users/123.json  # Update via JSON (PATCH)\nmkdir /mnt/db/users/456                                         # Create row\nrm -r /mnt/db/users/456/                                        # Delete row\n```\n\n### Pipeline Queries\n\nChain filters, ordering, and pagination in a single path. The database executes it as one query:\n\n```bash\ncat /mnt/db/orders/.by/customer_id/123/.order/created_at/.last/10/.export/json\n\n# Select specific columns from a filtered query\ncat /mnt/db/orders/.filter/status/shipped/.columns/id,total,created_at/.export/csv\n```\n\nPipeline segments can be chained in any order. Available segments: `.by/` (indexed filter), `.filter/` (any column), `.order/` (sort), `.columns/col1,...`  (projection), `.first/N/`, `.last/N/`, `.sample/N/` (pagination), and `.export/csv|json|tsv` (output format). \n \n\n### Ingest\n\nBulk-load data from CSV, JSON, or YAML. The write mode is part of the path: `.append/` adds rows, `.sync/` upserts by primary key, `.overwrite/` replaces the table.\n\n```bash\ncat data.csv \u003e /mnt/db/orders/.import/.append/csv\n```\n\n### Schema Management\n\nCreate, modify, and delete tables through a staging pattern:\n\n```bash\nmkdir /mnt/db/.create/orders \u0026\u0026 echo \"CREATE TABLE orders (...)\" \u003e /mnt/db/.create/orders/sql\ntouch /mnt/db/.create/orders/.commit\n```\n\nSee [docs/data-first.md](docs/data-first.md) for the full reference: row formats, index navigation, pipeline query chaining, schema management workflows, and configuration.\n\n## Why TigerFS\n\n### If you're building on files (file-first)\n\n- **vs. local files:** Instead of a single-writer assumption, TigerFS supports real concurrent access with isolation guarantees.\n\n- **vs. git:** Instead of asynchronous collaboration and merges, TigerFS provides immediate visibility with automatic version history.\n\n- **vs. object storage (S3):** Instead of blobs, you get structured rows, ACID transactions, and query pushdown.\n\n### If you're querying data (data-first)\n\n- **vs. database clients / psql:** No SQL to learn. Every agent already speaks files.\n\n- **vs. ORMs and APIs:** No schemas to define, no SDK to install. Mount and go.\n\n- **vs. using a database directly:** Instead of clients and schemas, you use files. Every tool and every agent already understands the interface.\n\nThe result is simple: you delete coordination code from your application.\n\n## Cloud Backends\n\nTigerFS works with any PostgreSQL database. Just pass a connection string. It also integrates with [Tiger Cloud](https://www.timescale.com/cloud) and [Ghost](https://ghost.build) through their CLIs for credential-free mounting. Use a prefix to specify the backend:\n\n```bash\n# Mount any Postgres database\ntigerfs mount postgres://user:pass@host/mydb /mnt/db\n\n# Or mount cloud services by ID\ntigerfs mount tiger:abcde12345 /mnt/db\ntigerfs mount ghost:fghij67890 /mnt/db\n```\n\nTigerFS calls the backend CLI to retrieve credentials, so there are no passwords in your config. Authenticate once with `tiger auth login` or `ghost login`.\n\nSet a default backend to skip the prefix:\n\n```bash\n# In ~/.config/tigerfs/config.yaml: default_backend: tiger\ntigerfs mount abcde12345 /mnt/db    # uses tiger: implicitly\n```\n\n### Create and Fork\n\n```bash\n# Create a new cloud database (auto-mounts)\ntigerfs create tiger:my-db\ntigerfs create tiger:my-db /mnt/data   # custom mount path\ntigerfs create ghost:my-db --no-mount  # create without mounting\n\n# Fork (clone) for safe experimentation\ntigerfs fork /mnt/db my-experiment\ntigerfs fork tiger:abcde12345 my-experiment\n\n# Inspect a mount\ntigerfs info /mnt/db\ntigerfs info --json /mnt/db           # JSON output for scripting\n```\n\n## Design Principles\n\n- **Keep the interface familiar.** If you can `ls`, you can explore a database.\n- **Make concurrency safe.** Multiple writers without corruption or conflicts.\n- **Push logic down.** Every path resolves to optimized SQL.\n- **Make changes reversible.** Savepoints, undo, and version history mean you can always go back.\n- **Remove coordination code.** The database handles it.\n\n## Try the Demo\n\n```bash\ncd scripts/demo\n./demo.sh start     # auto-detects platform (--docker or --mac)\n./demo.sh shell     # explore: ls, cat users/1.json, etc.\n./demo.sh stop\n```\n\n## Configuration\n\nConfig file: `~/.config/tigerfs/config.yaml`. Run `tigerfs config show` to see all options and their current values. All options support environment variables with `TIGERFS_` prefix. See [docs/spec.md](docs/spec.md) for the full reference.\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [docs/file-first.md](docs/file-first.md) | File-first mode: workspaces, column mapping, frontmatter, directories |\n| [docs/history.md](docs/history.md) | History, savepoints, and undo: versioned snapshots, safe exploration, atomic rollback |\n| [docs/data-first.md](docs/data-first.md) | Data-first mode: row formats, indexes, pipeline queries, schema management |\n| [docs/quickstart.md](docs/quickstart.md) | Guided scenarios with sample data |\n\n## Development\n\n```bash\ngit clone https://github.com/timescale/tigerfs.git\ncd tigerfs\ngo build -o bin/tigerfs ./cmd/tigerfs\ngo test ./...\n```\n\nFor development guidelines, architecture details, and the full specification, see [CLAUDE.md](CLAUDE.md) and [docs/spec.md](docs/spec.md).\n\n## Project Status\n\nTigerFS is early, but the core idea is stable: transactional, concurrent files as the foundation for human-agent collaboration.\n\n**v0.7.0.** Undo and recovery: savepoints, operation log, and atomic undo for safe exploration.\n\n**v0.6.0.** Dedicated tigerfs schema, security hardening, and unified demo.\n\n**Highlights:**\n- Markdown and plaintext workspaces with YAML frontmatter, directory hierarchies, and version history\n- Savepoints, undo, and operation log: create checkpoints, preview changes, roll back atomically\n- Per-user undo: multiple agents with separate identities, selectively undo one agent's work\n- Auto-savepoints: detect session boundaries on inactivity gaps\n- Relational directory model with parent-pointer hierarchy and UUIDv7 identifiers\n- Dedicated tigerfs schema with migration framework (`tigerfs migrate`)\n- TLS enforcement, SQL injection hardening, and credential sanitization\n- Agent skill auto-install for Claude Code, Gemini CLI, and Codex\n- Cloud backends: mount, create, and fork Tiger Cloud and Ghost databases by service ID\n- Pipeline queries with full database pushdown (`.by/`, `.filter/`, `.order/`, `.columns/`, chained pagination, `.export/`)\n- DDL staging for tables, indexes, views, and schemas (`.create/`, `.modify/`, `.delete/`)\n- Full CRUD with multiple formats (TSV, CSV, JSON, YAML), index navigation, and PATCH semantics\n- Binary distribution via GoReleaser with install script\n- Multi-tier stat caching and query reduction for fast operations over remote databases\n\n**Planned:**\n- Tables without primary keys (read-only via ctid)\n- Windows support\n\n## Contributing\n\nContributions are welcome! Please see the development guidelines in [CLAUDE.md](CLAUDE.md).\n\n## Support\n\n- **Issues**: https://github.com/timescale/tigerfs/issues\n- **Discussions**: https://github.com/timescale/tigerfs/discussions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimescale%2Ftigerfs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimescale%2Ftigerfs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimescale%2Ftigerfs/lists"}