# Overview

> What TigerFS exposes (mount + dot-directories), file-first vs data-first entry paths, runtime assumptions (PostgreSQL, FUSE/NFS), and the first routes to read.

- Repository: timescale/tigerfs
- GitHub: https://github.com/timescale/tigerfs
- Human docs: https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3
- Complete Markdown: https://grok-wiki.com/public/docs/timescale-tigerfs-60719456a5c3/llms-full.txt

## Source Files

- `README.md`
- `docs/spec.md`
- `cmd/tigerfs/main.go`
- `internal/tigerfs/cmd/root.go`
- `docs/quickstart.md`

---

---
title: "Overview"
description: "What TigerFS exposes (mount + dot-directories), file-first vs data-first entry paths, runtime assumptions (PostgreSQL, FUSE/NFS), and the first routes to read."
---

TigerFS is a Go CLI (`tigerfs`) that mounts a PostgreSQL database at a local path and serves all filesystem semantics through `internal/tigerfs/fs.Operations`, with Linux using FUSE (`go-fuse`) and macOS using an in-process NFS v3 server (`go-nfs`). Every path under the mount resolves to SQL against PostgreSQL; Unix tools and agent file APIs operate on tables, rows, columns, and dot-directory capabilities without a separate query language.

## Runtime assumptions

| Requirement | Detail |
|-------------|--------|
| Database | PostgreSQL 12+ (driver: `pgx/v5`) |
| Linux | FUSE; user typically in `fuse` group |
| macOS | Native NFS mount to local NFS server (no FUSE kernel extension) |
| Connection | `postgres://` URI, `PG*` env vars, or `tiger:` / `ghost:` cloud prefixes |
| TLS | Non-localhost connections enforce `sslmode=require` unless `--insecure-no-ssl` |
| Go | 1.23+ to build from source |

The `mount` command connects once, registers the mount in `internal/tigerfs/mount`, and blocks until unmount or `SIGINT`/`SIGTERM`. `cmd/tigerfs/main.go` wires signal-aware shutdown into `cmd.Execute`.

<Note>
Windows is listed in `docs/spec.md` as WinFsp-backed; Linux and macOS are the primary supported paths in the mount implementation (`mount_linux.go`, `mount_darwin.go`).
</Note>

## What a mount exposes

At the mount root, tables from the default schema (usually `public`) appear as top-level directories. Non-default schemas use `/mount/<schema>/<table>/` or explicit `/mount/.schemas/<schema>/<table>/`.

```text
/mnt/db/                          # mount root (PathRoot)
├── users/                        # data-first table
│   ├── .info/                    # schema, columns, count
│   ├── .by/ .filter/ .order/     # pipeline capabilities
│   ├── 123/                      # row-as-directory
│   └── 123.json                  # row-as-file (not always in ls)
├── notes/                        # file-first workspace (.md files)
│   ├── hello.md
│   ├── .history/ .log/ .savepoint/ .undo/
│   └── tutorials/
├── .build/                       # create workspaces (PathBuild)
├── .create/ .modify/ .delete/    # DDL staging
├── .tables/                      # tigerfs-schema backing tables
├── .schemas/                     # explicit schema listing
└── .refresh                      # metadata cache invalidation
```

`ls` hides dot-directories by default; `ls -a` reveals `.info/`, `.by/`, and other control paths. Reserved dot names (`.build`, `.filter`, `.history`, etc.) cannot be created as user data — attempts return `EACCES`. User dotfiles such as `.gitignore` are allowed inside file-first workspaces when not on the reserved list.

## Dot-directories as the control surface

Capabilities are navigable paths, not separate APIs. `fs/path.go` classifies each path (`PathType`) and accumulates query state in `FSContext` for pipeline segments.

| Dot path | Role |
|----------|------|
| `.info/` | Table metadata (`schema`, `columns`, `count`, `indexes`) |
| `.by/` | Index-based navigation |
| `.filter/`, `.order/`, `.columns/` | Pipeline query segments |
| `.first/`, `.last/`, `.sample/` | Pagination |
| `.export/`, `.import/` | Bulk read/write |
| `.build/` | Create synthesized workspace (`markdown`, `plaintext`, `history`, …) |
| `.format/` | Add synthesized view to an existing table |
| `.create/`, `.modify/`, `.delete/` | DDL staging with `.commit` / `.abort` |
| `.history/`, `.log/`, `.savepoint/`, `.undo/` | File-first versioning and undo |
| `.tables/` | Data-first access to `tigerfs` schema backing tables |

Example pipeline (one SQL query):

```bash
cat /mnt/db/orders/.by/customer_id/123/.order/created_at/.last/10/.export/json
```

`--max-pipeline-depth` (default 10) limits how deep chained capabilities appear in listings.

## File-first vs data-first entry paths

Both modes share one mount and one PostgreSQL database. Per-directory mode is inferred from layout:

| Signal | Mode | Typical entry |
|--------|------|----------------|
| `.md` / `.txt` workspace files | File-first | `echo "markdown,history" > /mnt/db/.build/notes` |
| `.info/` under a table directory | Data-first | `ls /mnt/db` then `cat /mnt/db/users/.info/schema` |
| New project | File-first | `.build/` with `markdown` or `plaintext` |
| Existing database | Data-first | `tigerfs mount postgres://… /mnt/db` |

**File-first** presents rows as domain files (markdown with YAML frontmatter, or plaintext). Workspaces opt into `history` for `.log/`, `.savepoint/`, and `.undo/`. Subdirectories (`mkdir`, `mv`) map to hierarchical state; kanban-style flows use directory moves. Backing storage lives in the `tigerfs` schema; inspect via `/mnt/db/.tables/<workspace>/`.

**Data-first** presents each row as a file (`123.json`) and/or directory (`123/email.txt`). Updates use PATCH semantics for structured formats. Index navigation, pipeline paths, and DDL staging apply at the table level.

You can add file-first views to an existing table without rebuilding data:

```bash
echo "markdown" > /mnt/db/posts/.format/markdown
```

## Architecture

```mermaid
flowchart LR
  subgraph clients [Clients]
    Unix[Unix tools]
    Agents[Agent file APIs]
  end
  subgraph adapters [Platform adapters]
    FUSE[fuse.MountOps Linux]
    NFS[nfs.Mount macOS]
  end
  subgraph core [Shared core]
    Ops[fs.Operations]
    Path[fs/path.go PathType]
    DB[db + format]
  end
  PG[(PostgreSQL)]
  Unix --> FUSE
  Unix --> NFS
  Agents --> FUSE
  Agents --> NFS
  FUSE --> Ops
  NFS --> Ops
  Ops --> Path
  Ops --> DB
  DB --> PG
```

New filesystem behavior belongs in `internal/tigerfs/fs/`, not in FUSE/NFS adapters. Linux defaults to `fuse.MountOps` (shared `fs.Operations`); `--legacy-fuse` selects the older FUSE node tree. macOS always uses NFS because FUSE requires third-party kernel extensions.

<Warning>
On macOS NFS, `go-nfs` synthesizes Open/Write/Close per WRITE RPC; content commits on Close. `ReadFile` always queries PostgreSQL fresh; stat/path caches hold metadata only with write invalidation.
</Warning>

## CLI surface

Root command (`internal/tigerfs/cmd/root.go`) registers:

`mount`, `unmount`, `stop`, `status`, `info`, `list`, `create`, `fork`, `migrate`, `test-connection`, `config`, `version`

`mount` accepts:

```bash
tigerfs mount postgres://user@host:5432/mydb /mnt/db
tigerfs mount tiger:<service-id>              # optional auto mountpoint
tigerfs mount ghost:<service-id> /mnt/db
```

Configuration loads from `~/.config/tigerfs/config.yaml` with `TIGERFS_*` overrides (see configuration reference). Persistent flags include `--log-level`, `--config-dir`, `--read-only`, `--user-id`, and `--auto-savepoint-interval`.

Bundled agent skills live under `skills/tigerfs/` (`SKILL.md`, `files.md`, `data.md`, `ops.md`, `recipes.md`). The install script (`scripts/install.sh`) copies them into detected agent skill directories or stages them under `~/.config/tigerfs/skills/tigerfs`.

## Consistency model (read this early)

PostgreSQL is the single source of truth across concurrent mounts:

- **Do not cache row content** — reads must reflect latest commits.
- **Cache metadata only** — directory listings, stat sizes, column lists (short TTL, invalidation on writes).
- **Pipeline paths need isolated cache keys** — e.g. `.export/json` vs `.filter/active/true/.export/json` must not share stat entries.

Violations surface as cross-mount staleness; new write paths must invalidate `statCache` and `pathCache` with the user schema key.

## Verification signals

After install or build:

```bash
go build -o bin/tigerfs ./cmd/tigerfs
tigerfs version
tigerfs mount postgres://localhost/mydb /mnt/db &
ls /mnt/db
tigerfs unmount /mnt/db
```

For a zero-setup trial, `scripts/demo/demo.sh start` mounts sample data (Docker or native macOS). Success looks like table directories (`users/`, `orders/`, …) and readable row files (`cat users/1.json`).

## First routes to read

Use this order to go from mount behavior to implementation detail:

<Steps>
<Step title="Product orientation">
Read `README.md` for file-first vs data-first examples, dot-directory tables, and cloud backend prefixes.
</Step>
<Step title="Hands-on paths">
Follow `docs/quickstart.md` for mount, `.build/` workspaces, savepoints, and pipeline `cat` paths.
</Step>
<Step title="Mode guides">
`docs/file-first.md` — workspaces, frontmatter, `.tables/`. `docs/data-first.md` — row formats, PATCH writes, DDL, pipelines.
</Step>
<Step title="Full contract">
`docs/spec.md` — complete hierarchy, formats, configuration, error mapping, NFS/FUSE notes.
</Step>
<Step title="Implementation map">
`CLAUDE.md` — package layout (`fs/`, `fuse/`, `nfs/`, `db/`), pipeline parsing in `fs/path.go`, synth layer in `fs/synth/`.
</Step>
<Step title="Agent usage">
`skills/tigerfs/SKILL.md` — mode detection rules and safe patterns for agents using Read/Write/Glob/Grep.
</Step>
</Steps>

| Topic | Location |
|-------|----------|
| Path parsing & `PathType` | `internal/tigerfs/fs/path.go` |
| Filesystem operations | `internal/tigerfs/fs/operations.go` |
| Mount & backends | `internal/tigerfs/cmd/mount.go`, `cmd/mount_linux.go`, `cmd/mount_darwin.go` |
| Synth formats | `internal/tigerfs/fs/synth/` |
| Integration tests | `test/integration/` |

## Related pages

<CardGroup>
<Card title="Installation" href="/installation">
Install paths, platform prerequisites (FUSE, NFS), and verification.
</Card>
<Card title="Quickstart" href="/quickstart">
First mount, `ls`/`cat` exploration, and demo workflows.
</Card>
<Card title="Filesystem as API" href="/filesystem-as-api">
Mount hierarchy and how paths map to SQL.
</Card>
<Card title="File-first and data-first" href="/file-first-and-data-first">
Mode detection, `.build/` vs raw tables, `.tables/` backing schema.
</Card>
<Card title="Capability directories" href="/capability-directories">
Pipeline grammar and `PathType` resolution.
</Card>
<Card title="Platform backends" href="/platform-backends">
FUSE vs NFS adapters, NFS write/commit model, mount registry.
</Card>
<Card title="Consistency and caching" href="/consistency-and-caching">
Cross-mount freshness, cache TTLs, invalidation rules.
</Card>
<Card title="CLI reference" href="/cli-reference">
All cobra commands, flags, and connection argument patterns.
</Card>
</CardGroup>