### Quick Start: Install and Mount TigerFS

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

A quick start guide to install TigerFS using the curl installer and then mount a PostgreSQL database. This is suitable for initial testing and basic usage.

```bash
# Install
curl -fsSL https://install.tigerfs.io | sh

# Mount
tigerfs postgres://localhost/mydb /mnt/db

# Use
ls /mnt/db/public/users/
cat /mnt/db/public/users/123/email
```

--------------------------------

### Start Docker Demo

Source: https://github.com/timescale/tigerfs/blob/main/docs/quickstart.md

Starts the TigerFS Docker demo environment, which includes PostgreSQL and sample data. This is useful for trying TigerFS without local setup.

```bash
cd scripts/demo
./demo.sh start --docker
```

--------------------------------

### Start TigerFS Demo Environment

Source: https://github.com/timescale/tigerfs/blob/main/README.md

Start the ready-to-run TigerFS demo environment. It auto-detects the platform and can be started using Docker or native binaries.

```bash
cd scripts/demo
./demo.sh start     # auto-detects platform (--docker or --mac)
```

--------------------------------

### Install and Use Tiger CLI and TigerFS

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

First-time user flow for installing the Tiger CLI, authenticating, installing TigerFS, and creating/mounting a database.

```bash
# 1. Install tiger CLI
curl -fsSL https://cli.tigerdata.com | sh

# 2. Authenticate
tiger auth login

# 3. Install TigerFS
go install github.com/timescale/tigerfs/cmd/tigerfs@latest

# 4. Create and mount a database
tigerfs create tiger:my-db

# 5. Use filesystem
ls /tmp/my-db/
cat /tmp/my-db/users/1.json
```

--------------------------------

### Install TigerFS

Source: https://github.com/timescale/tigerfs/blob/main/README.md

Use this command to download and install TigerFS. It's a straightforward way to get started with the tool.

```bash
curl -fsSL https://install.tigerfs.io | sh
```

--------------------------------

### Example CREATE TABLE Statement

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

This is an example output from the `.info/schema` file, showing the CREATE TABLE statement for the 'users' table.

```sql
CREATE TABLE users (
  id INTEGER PRIMARY KEY,
  email TEXT NOT NULL,
  name TEXT,
  age INTEGER DEFAULT 0,
  created_at TIMESTAMP DEFAULT NOW()
);
```

--------------------------------

### Index Creation Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Example SQL statements for creating indexes on a 'users' table.

```sql
CREATE INDEX users_email_idx ON users(email);
CREATE INDEX users_name_idx ON users(last_name, first_name);
CREATE UNIQUE INDEX users_username_idx ON users(username);
```

--------------------------------

### Example Format File Configuration

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Example JSON configuration for a format file, specifying view details, columns, and frontmatter.

```json
{
  "format": "markdown",
  "view": "posts_md",
  "columns": {"filename": "slug", "body": "content"},
  "frontmatter": ["author", "date", "tags"],
  "source": "convention"
}
```

--------------------------------

### Setup Activity Log

Source: https://github.com/timescale/tigerfs/blob/main/skills/tigerfs/recipes.md

Initialize the activity log by creating a build file.

```bash
Bash "echo 'markdown' > mount/.build/activity"
```

--------------------------------

### Example Index Listing Output

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Example output from `ls /mnt/db/users/.indexes/`, showing directories for staging new indexes and existing indexes.

```text
.create/
email_idx/
created_at_idx/
```

--------------------------------

### Example Column List Output

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

This is an example output from the `.info/columns` file, listing the column names for the 'users' table.

```text
id
email
name
age
created_at
```

--------------------------------

### Create Table Interactive Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

An interactive example showing the steps to create a table using the staging pattern: creating the directory, viewing the template, writing the DDL, and preparing for commit.

```bash
# Create staging directory
mkdir /mnt/db/.create/orders

# View template
cat /mnt/db/.create/orders/sql

# Write DDL
cat > /mnt/db/.create/orders/sql << 'EOF'
CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    customer_id INTEGER NOT NULL,
    total NUMERIC(10,2) NOT NULL,
    status TEXT DEFAULT 'pending',
    created_at TIMESTAMP DEFAULT NOW()
);
EOF

```

--------------------------------

### Setup Session Context

Source: https://github.com/timescale/tigerfs/blob/main/skills/tigerfs/recipes.md

Initialize the session context by creating a build file.

```bash
Bash "echo 'markdown' > mount/.build/sessions"
```

--------------------------------

### Setup Knowledge Base

Source: https://github.com/timescale/tigerfs/blob/main/skills/tigerfs/recipes.md

Initialize the knowledge base by creating a build file and necessary directories for organizing information.

```bash
Bash "echo 'markdown,history' > mount/.build/kb"
Bash "mkdir mount/kb/architecture mount/kb/debugging mount/kb/conventions"
```

--------------------------------

### Example Usage of Index Pagination

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Provides practical examples of using `.first/N/` and `.last/N/` with index paths for common data retrieval scenarios.

```bash
# First 10 order timestamps
ls /mnt/db/orders/.created_at/.first/10/

# Last 5 orders for user 42
ls /mnt/db/orders/.user_id/42/.last/5/

# First 10 users with last name "Smith"
ls /mnt/db/users/.last_name.first_name/Smith/.first/10/
```

--------------------------------

### Start TigerFS Demo

Source: https://github.com/timescale/tigerfs/blob/main/scripts/demo/README.md

Launches the TigerFS demo environment. It auto-detects the platform (macOS or Linux/Docker).

```bash
# Start the demo (auto-detects platform)
./demo.sh start
```

```bash
# Explore
ls /tmp/tigerfs-demo/           # macOS
# or: ./demo.sh shell           # Docker
```

```bash
# Stop
./demo.sh stop
```

--------------------------------

### Install TigerFS with Go

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Install the TigerFS command-line tool directly using Go. Ensure your Go environment is set up correctly.

```bash
go install github.com/timescale/tigerfs/cmd/tigerfs@latest
```

--------------------------------

### Convention-Based Setup

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/008-synthesized-apps.md

Shows how to configure TigerFS formats using convention-based directory structures.

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

--------------------------------

### Start macOS Native Demo

Source: https://github.com/timescale/tigerfs/blob/main/docs/quickstart.md

Starts the TigerFS demo on macOS using the native NFS backend, with PostgreSQL running in Docker. The mount point is typically /tmp/tigerfs-demo.

```bash
cd scripts/demo
./demo.sh start --mac
```

--------------------------------

### Configuration Option Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/006-bulk-export-capability.md

Example of a configuration setting for the maximum number of rows allowed for bulk import operations.

```yaml
# In config file
dir_writing_limit: 100000   # Max rows for bulk import (default: 100,000)
```

--------------------------------

### SQL Generation Examples

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Illustrates how different pipeline configurations translate into SQL queries, including simple, nested, and complex scenarios with subqueries. These examples are crucial for verifying the SQL generation logic.

```sql
-- Simple: .filter/status/active/.order/name/.first/100/
SELECT pk FROM t WHERE status = 'active' ORDER BY name LIMIT 100
```

```sql
-- Nested: .first/100/.last/50/
SELECT pk FROM (
    SELECT pk FROM t ORDER BY pk LIMIT 100
) sub ORDER BY pk DESC LIMIT 50
```

```sql
-- Complex: .first/1000/.filter/status/active/.sample/50/
SELECT pk FROM (
    SELECT * FROM (
        SELECT * FROM t ORDER BY pk LIMIT 1000
    ) sub1 WHERE status = 'active'
) sub2 ORDER BY RANDOM() LIMIT 50
```

--------------------------------

### Export Path Examples

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/006-bulk-export-capability.md

Demonstrates constructing export paths for different scenarios, including table-level, pagination, ordering, and index lookups.

```text
products/.export/csv
products/.first/100/.export/csv
products/.order/price/.last/50/.export/csv
products/.by/category/Electronics/.export/json
```

--------------------------------

### TigerFS Pipeline Query Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/data-first.md

Shows a practical example of chaining multiple operations to form a pipeline query for finding specific data, which is then translated into an optimized SQL query.

```bash
# Find the last 10 pending orders for customer 123, sorted by date, as JSON
cat /mnt/db/orders/.by/customer_id/123/.by/status/pending/.order/created_at/.last/10/.export/json
```

--------------------------------

### Nested Pagination Query Examples

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/007-pipeline-query-architecture.md

Demonstrates complex pagination scenarios by combining `.first/`, `.last/`, and `.sample/` capabilities. These examples show how to retrieve specific ranges or samples from data.

```text
.first/100/.last/50/                             # Rows 51-100 (OFFSET 50 LIMIT 50)
.last/100/.first/50/                             # Rows (n-99) to (n-50)
.first/1000/.sample/50/                          # Sample 50 from first 1000
.last/1000/.sample/50/                           # Sample 50 from last 1000
```

--------------------------------

### Using Default Backend

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Examples of using TigerFS commands when a default backend is configured, showing how to omit the explicit backend prefix.

```bash
tigerfs create my-db          # equivalent to: tigerfs create tiger:my-db
tigerfs fork my-db my-fork    # equivalent to: tigerfs fork tiger:my-db my-fork
```

--------------------------------

### Pagination Semantics Examples

Source: https://github.com/timescale/tigerfs/blob/main/docs/data-first.md

Demonstrates single-level and nested pagination, as well as post-pagination filtering.

```bash
.first/100/
```

```bash
.last/100/
```

```bash
.sample/100/
```

```bash
.last/500/.sample/25/
```

```bash
.last/1000/.filter/priority/high/.first/100/
```

--------------------------------

### Directory Structure Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/006-bulk-export-capability.md

An example directory structure illustrating the organization of data, metadata, and capabilities like export and import.

```text
/mnt/db/products/
├── .info/
│   ├── count
│   ├── ddl
│   ├── schema
│   └── columns
├── .export/
│   ├── csv
│   ├── tsv
│   ├── json
│   └── yaml
├── .import/
│   ├── .overwrite/
│   │   └── csv, tsv, json, yaml
│   ├── .sync/
│   │   └── csv, tsv, json, yaml
│   └── .append/
│       └── csv, tsv, json, yaml
├── .by/
│   └── category/
├── .order/
│   └── price/
│       └── .first/
│           └── 100/
│               └── .export/
│                   └── csv
├── .first/
│   └── 100/
│       └── .export/
│           └── csv
├── .indexes/
└── 1/
    
```

--------------------------------

### Install and Test GoReleaser

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Installs the GoReleaser tool and performs a local build test to verify configuration. Ensure binaries are created in the dist/ directory.

```bash
# Install goreleaser
go install github.com/goreleaser/goreleaser/v2@latest

# Test build
goreleaser build --snapshot --clean
# Should create binaries in dist/ 

ls dist/
# Should show binaries for all platforms
```

--------------------------------

### Test Unix Install Script Locally

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Simulates the execution of the install.sh script to verify its functionality. Checks if the tigerfs binary is installed correctly and is executable.

```bash
# Test locally (simulate download)
bash scripts/install.sh
# Should install tigerfs to ~/.local/bin/

# Verify
~/.local/bin/tigerfs version
# Should show version
```

--------------------------------

### Start PostgreSQL Container for Tests

Source: https://github.com/timescale/tigerfs/blob/main/docs/release-process.md

Starts a PostgreSQL 18 with TimescaleDB container for running database-dependent unit tests. Waits for the database to be ready.

```bash
docker run --rm -d --name tigerfs-release-pg -e POSTGRES_PASSWORD=test \
    -p 15432:5432 timescale/timescaledb-ha:pg18
sleep 5  # wait for PG to accept connections
```

--------------------------------

### TigerFS Configuration File Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

An example configuration file for TigerFS, demonstrating settings for database connections, filesystem behavior, metadata refresh, and logging. This file is located at ~/.config/tigerfs/config.yaml.

```yaml
# Connection defaults
connection:
  host: localhost              # Database hostname
  port: 5432                   # Database port
  user: myuser                 # Database username
  database: mydb               # Database name
  # NO password field (use .pgpass, env vars, or password_command)
  default_schema: public       # Schema to flatten to mount root
  pool_size: 10                # Max open connections
  pool_max_idle: 5             # Max idle connections
  password_command: "..."      # Command to retrieve password
  default_backend: tiger       # Default cloud backend for bare names (tiger or ghost)
  default_mount_dir: /tmp      # Base directory for auto-generated mountpoints
  insecure_no_ssl: false       # Skip TLS enforcement for remote connections

# Security note: TigerFS enforces sslmode=require for all non-localhost
# database connections. This ensures connections to remote databases are
# always encrypted. To disable this enforcement (not recommended), use
# --insecure-no-ssl or set insecure_no_ssl: true above.
# Localhost connections (127.0.0.1, ::1, Unix sockets) are exempt.

# Filesystem behavior
filesystem:
  dir_listing_limit: 1000            # Max rows returned by ls (prevents huge listings)
  max_pipeline_depth: 10            # Max chained pipeline ops before capabilities hidden (0=unlimited)
  trailing_newlines: true            # Add \n to column and .count file reads
  no_filename_extensions: false      # Disable type-based extensions (.txt, .json, etc.)
  attr_timeout: 1                    # FUSE attribute cache (seconds, FUSE backend only)
  entry_timeout: 1                   # FUSE entry cache (seconds, FUSE backend only)
  # Note: macOS NFS backend uses the system's NFS caching instead

# Metadata refresh
metadata:
  refresh_interval: 30         # Seconds between schema/column cache refreshes

# Logging
logging:
  level: info                  # debug, info, warn, error
  file: ~/.local/share/tigerfs/tigerfs.log
  format: json                 # json, text

```

--------------------------------

### Access File-First Apps

Source: https://github.com/timescale/tigerfs/blob/main/scripts/demo/README.md

Examples of interacting with file-first applications like blogs and documentation, which are seeded via the TigerFS mount.

```bash
# File-first apps
ls blog/                                      # List blog posts
```

```bash
cat blog/hello-world.md                       # Read a post
```

```bash
cat docs/getting-started/installation.md      # Read docs
```

```bash
cat snippets/todo.txt                         # Read a snippet
```

--------------------------------

### TigerFS Demo Commands

Source: https://github.com/timescale/tigerfs/blob/main/scripts/demo/README.md

Lists the available commands for managing the TigerFS demo environment, including starting, stopping, and checking status.

```bash
./demo.sh start # Start PostgreSQL, mount TigerFS, seed demo apps
```

```bash
./demo.sh stop  # Unmount TigerFS and stop containers
```

```bash
./demo.sh status  # Show current status
```

```bash
./demo.sh restart # Stop and start again
```

```bash
./demo.sh shell # Enter the TigerFS environment
```

--------------------------------

### Example: Random Sample of Active Users

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Fetches a random sample of 100 active users and exports the data as CSV.

```bash
cat /mnt/db/users/.by/status/active/.sample/100/.export/csv
```

--------------------------------

### Access Data-First Tables

Source: https://github.com/timescale/tigerfs/blob/main/scripts/demo/README.md

Examples of accessing data stored in PostgreSQL tables using standard command-line tools.

```bash
# Data-first tables
cat users/1.json                              # Read a user
```

```bash
cat products/.by/category/electronics/.export/json  # Products by category
```

```bash
ls orders/.sample/10/                         # Random orders
```

--------------------------------

### New .log/ Listing Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/016-undo-and-recovery.md

Illustrates the new UUIDv7 display format as applied to .log/ directory entries, showing timestamp and base36 entropy.

```bash
# New .log/ listing
ls notes/.log/.last/3
2026-04-07T143000.123Z-zzz0063hd8e5r42
2026-04-07T143001.456Z-a230b1c2d3e4f5x
2026-04-07T143005.789Z-1230deadbeef1z0
```

--------------------------------

### Current .history/ Listing Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/016-undo-and-recovery.md

Shows the traditional, second-precision format for .history/ directory listings before the new UUIDv7 display format was implemented.

```bash
# Current .history/ listing
ls notes/.history/hello.md/
2026-04-07T100000Z
2026-04-07T143000Z
2026-04-07T150000Z
```

--------------------------------

### Start TigerFS with HTTP Metrics Endpoint

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Launch TigerFS and expose performance metrics on a specified port for external monitoring tools.

```bash
tigerfs --metrics-port=9090 postgres://localhost/db /mnt/db

curl http://localhost:9090/metrics
# Prometheus format
# tigerfs_queries_total 1847
# tigerfs_query_duration_seconds_sum 42.5
```

--------------------------------

### Windows PowerShell One-line Installer

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Installs TigerFS using PowerShell by downloading and executing the install script from the official URL.

```powershell
irm https://install.tigerfs.io/install.ps1 | iex
```

--------------------------------

### Approach A: Slash-in-Table-Names Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/011-directory-hierarchies.md

Illustrates how Approach A would map paths to PostgreSQL table names, highlighting the potential ambiguity.

```text
/mnt/db/public/projects/          → table "projects"
/mnt/db/public/projects/web/      → table "projects/web"
```

--------------------------------

### Create Simple Updatable View

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Example of creating a simple PostgreSQL view that is updatable. This view can be directly written to.

```bash
psql -c "CREATE VIEW active_users AS SELECT * FROM users WHERE active = true;"
```

--------------------------------

### Task Filename Format Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/008-synthesized-apps.md

Illustrates the naming convention for task files, including numbering, name, and status symbol.

```bash
/work_tasks/
├── 1-setup-project-x.md
├── 1.01-create-repo-x.md
├── 1.02-add-readme-~.md
├── 2-implement-feature-o.md
└── 2.01-write-tests-o.md
```

--------------------------------

### Install TigerFS with apt (Debian/Ubuntu)

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Install TigerFS on Debian or Ubuntu systems using the apt package manager. This involves fetching a script and then installing the package.

```bash
curl -s https://packagecloud.io/install/repositories/timescale/tigerfs/script.deb.sh | sudo bash
sudo apt-get install tigerfs
```

--------------------------------

### Example Pagination Through Large Results

Source: https://github.com/timescale/tigerfs/blob/main/docs/data-first.md

Illustrates how to page through large result sets using `.first()` and `.last()` to retrieve specific ranges of rows.

```bash
# Page through large results
ls /mnt/db/events/.first/100/           # Page 1
ls /mnt/db/events/.first/200/.last/100/ # Page 2 (rows 101-200)
ls /mnt/db/events/.first/300/.last/100/ # Page 3 (rows 201-300)
```

--------------------------------

### Install TigerFS with yum (Red Hat/Fedora)

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Install TigerFS on Red Hat or Fedora systems using the yum package manager. This involves fetching a script and then installing the package.

```bash
curl -s https://packagecloud.io/install/repositories/timescale/tigerfs/script.rpm.sh | sudo bash
sudo yum install tigerfs
```

--------------------------------

### TigerFS Directory Structure Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/data-first.md

Illustrates the hierarchical mapping of a PostgreSQL table to a directory structure in TigerFS, showing how rows, columns, and metadata are represented.

```bash
/mnt/db/users/
├── 1.json                  # Row as JSON file
├── 1.tsv                   # Row as TSV file
├── 1/                      # Row as directory
│   ├── id                  # integer column (no extension)
│   ├── email.txt           # text column
│   ├── metadata.json       # jsonb column
│   └── avatar.bin          # bytea column
├── .by/                    # Index navigation
├── .first/  .last/  .sample/   # Pagination
├── .columns/  .filter/  .order/  .export/ # Pipeline queries
├── .info/                  # Table metadata
├── .create/  .modify/  .delete/ # Schema management
└── .indexes/               # Index metadata
```

--------------------------------

### SQL Trigger Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

An example of a SQL trigger definition using PL/pgSQL language.

```sql
CREATE OR REPLACE FUNCTION internal.tasks_shift_trigger()
RETURNS TRIGGER
AS $$
BEGIN
  -- Check if the new number is valid and unique within its scope
  IF NEW.number IS NOT NULL THEN
    IF NOT internal.is_valid_number(NEW.number) THEN
      RAISE EXCEPTION 'Invalid number format: %', NEW.number;
    END IF;
    IF internal.exists_in_scope(NEW.scope_id, NEW.number) THEN
      RAISE EXCEPTION 'Number % already exists in scope %', NEW.number, NEW.scope_id;
    END IF;
  END IF;
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER tasks_shift_trigger
BEFORE INSERT OR UPDATE ON internal.tasks
FOR EACH ROW EXECUTE FUNCTION internal.tasks_shift_trigger();

CREATE OR REPLACE FUNCTION internal.tasks_status_timestamp_trigger()
RETURNS TRIGGER
AS $$
BEGIN
  NEW.status_timestamp = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER tasks_status_timestamp_trigger
BEFORE INSERT OR UPDATE ON internal.tasks
FOR EACH ROW EXECUTE FUNCTION internal.tasks_status_timestamp_trigger();

CREATE OR REPLACE FUNCTION internal.tasks_compact(scope_id_in int)
RETURNS void
AS $$
DECLARE
  current_number bigint;
  row_record record;
BEGIN
  current_number := 1;
  FOR row_record IN SELECT * FROM internal.tasks WHERE scope_id = scope_id_in ORDER BY number_sort
  LOOP
    UPDATE internal.tasks SET number = current_number, number_sort = internal.number_to_sortable(current_number) WHERE id = row_record.id;
    current_number := current_number + 1;
  END LOOP;
END;
$$ LANGUAGE plpgsql;

-- CHECK constraint for number format (positive integers, no leading zeros)
ALTER TABLE internal.tasks
ADD CONSTRAINT tasks_number_format_check
CHECK (number ~ '^\d+$' AND (number = '0' OR NOT (number ~ '^0\d+$')));

-- Hierarchical number functions (example placeholders)
-- CREATE OR REPLACE FUNCTION internal.number_to_sortable(number bigint) RETURNS text ...
-- CREATE OR REPLACE FUNCTION internal.is_valid_number(number text) RETURNS boolean ...
-- CREATE OR REPLACE FUNCTION internal.exists_in_scope(scope_id int, number text) RETURNS boolean ...


```

--------------------------------

### Create initial savepoint data

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Creates an initial savepoint with a description using TSV format. This is part of the demo setup.

```bash
echo -e "description\nInitial data loaded" > mount/demo/.savepoint/initial-data.tsv
```

--------------------------------

### JSON Log Format Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Example of log entries in JSON format, suitable for machine parsing.

```json
{"time":"2026-01-23T10:30:15Z","level":"info","msg":"mount completed","database":"mydb","mountpoint":"/mnt/db"}
{"time":"2026-01-23T10:30:20Z","level":"debug","msg":"query","sql":"SELECT email FROM users WHERE id=123","duration_ms":15}
```

--------------------------------

### Post-Limit Operation Examples

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/007-pipeline-query-architecture.md

Shows how filtering, ordering, and sampling can be applied after an initial limit has been set. This allows for targeted operations on a subset of the data.

```text
.first/100/.filter/status/active/                # Filter the first 100
.last/100/.order/name/                           # Sort the last 100
.sample/50/.order/name/                          # Sort the sampled 50
.sample/50/.filter/status/active/                # Filter the sampled 50
```

--------------------------------

### Verify TigerFS Install Flow

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Run these commands to verify the installation process for TigerFS, including the auto-installation of skills.

```bash
./scripts/test-install.sh
goreleaser release --snapshot --clean
```

--------------------------------

### Install TigerFS with Homebrew

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Use Homebrew to install TigerFS on macOS or Linux. This is a convenient method for developers on these platforms.

```bash
brew install timescale/tap/tigerfs
```

--------------------------------

### Text Log Format Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Example of log entries in human-readable text format, suitable for direct viewing.

```text
2026-01-23 10:30:15 INFO  mount completed database=mydb mountpoint=/mnt/db
2026-01-23 10:30:20 DEBUG query sql="SELECT email FROM users WHERE id=123" duration_ms=15
```

--------------------------------

### Create New App from Scratch

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Use this command to create a new synthesized app from scratch. It sets up a backing table and a view, specifying the file format.

```bash
echo "markdown" > /mnt/db/.build/notes
```

--------------------------------

### Example of Creating a New Task

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Demonstrates how to create a new task by writing a description to the `.add` file. The system automatically assigns the next available number and status.

```bash
echo "Set up CI pipeline" > tasks/.add
```

--------------------------------

### Pipeline Query Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Construct a complex query by chaining operations in a filesystem path. This entire pipeline is translated into a single, optimized SQL query.

```bash
# Find last 10 pending orders for customer 123, sorted by date
cat /mnt/db/orders/.by/customer_id/123/.by/status/pending/.order/created_at/.last/10/.export/json
```

--------------------------------

### Set up a multi-agent task board

Source: https://github.com/timescale/tigerfs/blob/main/README.md

Initialize a task board using directories for 'todo', 'doing', and 'done' states. This setup facilitates task management among multiple agents.

```bash
# Set up a task board
echo "markdown,history" > /mnt/db/.build/tasks
mkdir /mnt/db/tasks/todo /mnt/db/tasks/doing /mnt/db/tasks/done
```

--------------------------------

### Filename-Based Hierarchy Example (Synth Only)

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/011-directory-hierarchies.md

Demonstrates how to insert data into a single view using filenames with slashes to create a virtual directory structure in the synth layer.

```sql
-- Single view, filenames contain paths
INSERT INTO notes (filename, body) VALUES ('tutorials/getting-started', '...');
INSERT INTO notes (filename, body) VALUES ('tutorials/advanced', '...');
INSERT INTO notes (filename, body) VALUES ('general/hello', '...');
```

--------------------------------

### Bulk Write Usage Examples

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Demonstrates how to use the `.import/` directory for bulk data import with different write modes and formats. Data is piped into specific import paths.

```bash
cat data.csv > /mnt/db/users/.import/.overwrite/csv
cat updates.json > /mnt/db/users/.import/.sync/json
cat new_rows.csv > /mnt/db/users/.import/.append/csv
```

--------------------------------

### Example Index DDL Output

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Example output from viewing an index's `.schema` file, showing the UNIQUE INDEX DDL statement.

```sql
CREATE UNIQUE INDEX email_idx ON public.users USING btree (email)
```

--------------------------------

### Verify Schema Creation with SQL Template

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Demonstrates how to verify the generated SQL for creating a schema using a test mount. The template should output 'CREATE SCHEMA name;'.

```bash
# Mount and test
mkdir /mnt/db/.schemas/.create/test_schema
cat /mnt/db/.schemas/.create/test_schema/.sql
# Shows: CREATE SCHEMA test_schema;
```

--------------------------------

### Setup Task Board Structure

Source: https://github.com/timescale/tigerfs/blob/main/skills/tigerfs/recipes.md

Initialize the directory structure for a task board application. This involves setting build configurations and creating directories for different task states (todo, doing, done).

```bash
Bash "echo 'markdown,history' > mount/.build/tasks"
Bash "mkdir mount/tasks/todo mount/tasks/doing mount/tasks/done"
```

--------------------------------

### Start Cache Reaper Goroutine

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/010-persistent-memfile.md

Starts a background goroutine that periodically calls `reapStaleCacheEntries` to commit idle cache entries, preventing memory leaks.

```go
func (f *OpsFilesystem) startCacheReaper() {
    go func() {
        ticker := time.NewTicker(30 * time.Second)
        for range ticker.C {
            f.reapStaleCacheEntries()  // Force-commit entries idle > 5 min
        }
    }()
}
```

--------------------------------

### Create Synthesized App from Scratch

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/008-synthesized-apps.md

Use this method to create a new table and a synthesized view from scratch. The view will be named cleanly, and the table will be prefixed with an underscore.

```bash
echo "markdown" > /mnt/db/public/.build/posts
# Creates: _posts table + posts view
```

--------------------------------

### Example Complete DDL Output

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

An example of the complete DDL output for the 'users' table, including table creation, primary key, indexes, foreign keys, and comments.

```sql
-- Table
CREATE TABLE public.users (
    id integer NOT NULL,
    email text NOT NULL,
    name text,
    created_at timestamp with time zone DEFAULT now()
);

-- Primary Key
ALTER TABLE ONLY public.users
    ADD CONSTRAINT users_pkey PRIMARY KEY (id);

-- Indexes
CREATE UNIQUE INDEX users_email_idx ON public.users USING btree (email);
CREATE INDEX users_created_at_idx ON public.users USING btree (created_at);

-- Foreign Keys
ALTER TABLE ONLY public.orders
    ADD CONSTRAINT orders_user_id_fkey FOREIGN KEY (user_id) REFERENCES public.users(id);

-- Comments
COMMENT ON TABLE public.users IS 'User accounts';
COMMENT ON COLUMN public.users.email IS 'Primary contact email';
```

--------------------------------

### Modify Table Template Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Provides examples for altering an existing table's schema. Includes placeholders for common operations like adding, dropping, or modifying columns.

```sql
-- Current schema:
-- CREATE TABLE users (
--     id serial PRIMARY KEY,
--     name text NOT NULL
-- );

-- Examples:
-- ADD COLUMN column_name type
-- DROP COLUMN column_name
-- ALTER COLUMN column_name TYPE new_type

ALTER TABLE users
```

--------------------------------

### Mount Database and Create File-First Workspace

Source: https://github.com/timescale/tigerfs/blob/main/README.md

Mounts a PostgreSQL database and configures a workspace for the 'blog' table to be managed as markdown files with history.

```bash
# Mount a database and create a workspace with history
tigerfs mount postgres://localhost/mydb /mnt/db
echo "markdown,history" > /mnt/db/.build/blog
```

--------------------------------

### Verify Table Creation in Default Schema

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Shows the command-line sequence for creating a table in the default schema, including verifying the template and committing the creation.

```bash
# Create in default schema
mkdir /mnt/db/.create/orders
cat /mnt/db/.create/orders/.sql
# Shows template

echo "CREATE TABLE orders (id serial PRIMARY KEY, name text)" > /mnt/db/.create/orders/.sql
touch /mnt/db/.create/orders/.test
touch /mnt/db/.create/orders/.commit
ls /mnt/db/
# Shows: orders
```

--------------------------------

### Create Workspaces

Source: https://github.com/timescale/tigerfs/blob/main/docs/file-first.md

Define how a database table is presented as files by writing a format to the .build/ directory. Use 'markdown,history' for recommended Markdown files with versioning.

```bash
echo "markdown,history" > /mnt/db/.build/notes    # Markdown with history (recommended)
echo "markdown" > /mnt/db/.build/notes            # Markdown without history
echo "plaintext" > /mnt/db/.build/snippets        # Plain text, no frontmatter
echo "history" > /mnt/db/.build/notes             # Add history to existing workspace
```

--------------------------------

### Data-First Access Examples

Source: https://github.com/timescale/tigerfs/blob/main/skills/tigerfs/SKILL.md

Demonstrates various data-first access patterns for reading row counts, individual rows as JSON, single columns, performing index lookups, and filtered exports.

```shell
Read "mount/users/.info/count"
Read "mount/users/1.json"
Read "mount/users/1/email"
Glob "mount/users/.by/email/alice@example.com/*"
Read "mount/users/.by/status/active/.export/json"
```

--------------------------------

### Verify Index Creation and Deletion

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Demonstrates the command-line steps to create a new index, verify its template, stage the creation, and then delete an existing index.

```bash
# Create index
mkdir /mnt/db/users/.indexes/.create/email_idx
cat /mnt/db/users/.indexes/.create/email_idx/.sql
# Shows template

echo "CREATE INDEX email_idx ON users(email)" > /mnt/db/users/.indexes/.create/email_idx/.sql
touch /mnt/db/users/.indexes/.create/email_idx/.test
# Exit 0

touch /mnt/db/users/.indexes/.create/email_idx/.commit
ls /mnt/db/users/.indexes/
# Shows: email_idx

# Delete index
echo "DROP INDEX email_idx" > /mnt/db/users/.indexes/email_idx/.delete/.sql
touch /mnt/db/users/.indexes/email_idx/.delete/.commit
```

--------------------------------

### Directory Listing Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Demonstrates typical directory listings in TigerFS, showing reserved dotfiles and row directories. Also shows entering a row directory and listing its column files.

```bash
$ ls /mount/users/
.by/  .columns/  .export/  .filter/  .first/  .import/  .info/  .last/  .order/  .sample/
1/  2/  3/  ...
```

```bash
$ cd /mount/users/1        # Enter row directory
$ ls
email.txt  name.txt  age  .json  .csv  .tsv  .yaml
```

--------------------------------

### Example Log Entry for NOT NULL Constraint Violation

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

This is an example of a detailed error log entry for a 'NOT NULL constraint violation' in TigerFS, showing operation, error details, path, user, and PID.

```log
2026-01-23 10:30:15 ERROR: NOT NULL constraint violation
  Operation: INSERT INTO users (id, name)
  Error: null value in column "email" violates not-null constraint
  Path: /mnt/db/users/125/name
  User: mfreed
  PID: 12345
```

--------------------------------

### Example of QuoteIdent

Source: https://github.com/timescale/tigerfs/blob/main/CLAUDE.md

Shows the output of quoting a single identifier.

```go
QuoteIdent("email") // -> "email"
```

--------------------------------

### Creating a Savepoint with Description

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/016-undo-and-recovery.md

Demonstrates creating a savepoint by writing a description to a file within the .savepoint directory. This maps to an INSERT operation in the savepoint table.

```bash
echo -e "description\nStarting agent exploration" > notes/.savepoint/before-exploration.tsv
```

--------------------------------

### Example of QuoteTable

Source: https://github.com/timescale/tigerfs/blob/main/CLAUDE.md

Shows the output of quoting a schema-qualified table reference.

```go
QuoteTable("public", "users") // -> "public"."users"
```

--------------------------------

### New .history/ Listing Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/016-undo-and-recovery.md

Demonstrates the new, lossless UUIDv7 display format for .history/ directory listings, including millisecond precision and base36 encoded entropy.

```bash
# New .history/ listing
ls notes/.history/hello.md/
2026-04-07T100000.000Z-a230b1c2d3e4f5x
2026-04-07T143000.123Z-zzz0063hd8e5r42
2026-04-07T150000.456Z-1230deadbeef1z0
```

--------------------------------

### Test Plain Text View Creation and Access

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Shows how to create a Plain Text synthesized view and create/access its files. Includes creating a text file and reading its content.

```bash
# Test plain text:
echo "txt" > /mnt/db/public/.build/snippets
echo "Hello world" > /mnt/db/public/snippets/hello.txt
cat /mnt/db/public/snippets/hello.txt
```

--------------------------------

### Disallowed Redundant Operations

Source: https://github.com/timescale/tigerfs/blob/main/docs/data-first.md

Examples of redundant path segments that are automatically simplified by TigerFS.

```bash
.first/100/.first/50/
```

```bash
.last/100/.last/50/
```

```bash
.sample/50/.sample/25/
```

```bash
.order/a/.order/b/
```

```bash
.columns/a,b/.columns/c/
```

```bash
.export/csv/.first/10/
```

--------------------------------

### View CREATE TABLE Statement

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Shows how to view the CREATE TABLE statement for a table by reading the `.info/schema` file.

```bash
cat /mnt/db/users/.info/schema
```

--------------------------------

### Test Index Discovery

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Demonstrates how to create indexes in PostgreSQL and then test the index discovery functionality using Go tests.

```bash
psql -c "CREATE INDEX users_email_idx ON users(email);"
psql -c "CREATE INDEX users_name_idx ON users(last_name, first_name);"

go test -v ./internal/tigerfs/db/ -run TestGetIndexes
```

--------------------------------

### Column Projection Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/data-first.md

Export specific columns from a dataset. Filters should precede column selection.

```bash
cat /mnt/db/users/.columns/id,name,email/.export/csv
```

```bash
cat /mnt/db/orders/.filter/status/shipped/.columns/id,total,created_at/.export/json
```

```bash
ls /mnt/db/users/.columns/
```

--------------------------------

### Resolve Backend References

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/013-backend-prefix-scheme.md

Example outputs for the Resolve function parsing various input references.

```go
Resolve("tiger:abc123")     → (TigerBackend, "abc123", nil)
Resolve("ghost:mydb")       → (GhostBackend, "mydb", nil)
Resolve("postgres://...")    → (nil, "postgres://...", nil)   // direct connection
Resolve("my-db")            → (nil, "my-db", nil)            // bare name, no backend
```

--------------------------------

### Initiating a CREATE Session for DDL Operations

Source: https://github.com/timescale/tigerfs/blob/main/skills/tigerfs/data.md

Start a CREATE session for schema changes by creating a directory under `.create/`. This prepares for defining new tables, views, or schemas.

```bash
mkdir mount/.create/products                                       # Start a CREATE session
```

--------------------------------

### Read Column Names

Source: https://github.com/timescale/tigerfs/blob/main/docs/quickstart.md

Get a list of column names for a table by reading the `.info/columns` file.

```bash
$ cat /mnt/db/users/.info/columns
id
name
email
age
active
bio
created_at
```

--------------------------------

### Verify Table Creation in Specific Schema

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Demonstrates how to create a table within a specific schema using command-line operations.

```bash
# Create in specific schema
echo "CREATE TABLE foo (id serial PRIMARY KEY)" > /mnt/db/.schemas/public/.create/foo/.sql
touch /mnt/db/.schemas/public/.create/foo/.commit
```

--------------------------------

### Periodic Statistics Log Entry

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Example of a log entry containing periodic statistics about TigerFS operations.

```text
2026-01-23 10:35:00 INFO stats queries=1847 qps=6.1 avg_query_ms=23 p95_query_ms=89 errors=12 pool_active=3/10
```

--------------------------------

### Test Markdown View via .build/

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Illustrates creating a Markdown synthesized view using the `.build/` directory. This method is an alternative to `.format/`.

```bash
echo "markdown" > /mnt/db/public/.build/notes
ls /mnt/db/public/notes/
cat /mnt/db/public/_notes/  # Native access
```

--------------------------------

### Explicit Format Mapping

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/008-synthesized-apps.md

Provides an example of explicitly mapping filename and body columns for a specific format.

```bash
echo '{filename:slug,body:content}' > /mnt/db/posts/.format/markdown
```

--------------------------------

### GET /path/.columns/{columns}/.export/{format}

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/007-pipeline-query-architecture.md

Projects specific columns from a dataset and exports them in the requested format.

```APIDOC
## GET /path/.columns/{columns}/.export/{format}

### Description
Selects specific columns from the dataset and exports the result in the specified format (e.g., csv, json).

### Method
GET

### Endpoint
/path/.columns/{columns}/.export/{format}

### Parameters
#### Path Parameters
- **columns** (string) - Required - Comma-separated list of column names to project.
- **format** (string) - Required - The output format (e.g., csv, json).
```

--------------------------------

### Dockerfile for TigerFS

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

This Dockerfile defines the environment for building and running TigerFS, including installing dependencies and setting up the entrypoint.

```dockerfile
HEALTHCHECK --interval=5s --timeout=3s --retries=3 \
    CMD pg_isready -U postgres || exit 1

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

ENTRYPOINT ["/entrypoint.sh"]
CMD ["bash"]
```

--------------------------------

### Test Tasks Format via .build/

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Tests the tasks format functionality by creating, moving, and verifying task files within the .build/ directory. Ensures the doing_at timestamp is correctly set.

```bash
echo "tasks" > /mnt/db/public/.build/work
echo "First task" > /mnt/db/public/work/1-setup-o.md
mv /mnt/db/public/work/1-setup-o.md /mnt/db/public/work/1-setup-~.md
# Verify doing_at timestamp set
cat /mnt/db/public/work/1-setup-~.md
```

--------------------------------

### Configure Log Format via Command Line

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Set the log format to text or JSON when starting TigerFS.

```bash
# Text format
tigerfs --log-format=text postgres://localhost/db /mnt/db

# JSON format
tigerfs --log-format=json postgres://localhost/db /mnt/db
```

--------------------------------

### Full Pipeline with Export

Source: https://github.com/timescale/tigerfs/blob/main/docs/data-first.md

Demonstrates a complete data retrieval pipeline including filtering, ordering, pagination, and final export.

```bash
.by/customer_id/123/.order/date/.last/10/.export/json
```

--------------------------------

### Scripting Examples for Diffing

Source: https://github.com/timescale/tigerfs/blob/main/docs/adr/016-undo-and-recovery.md

Bash scripts demonstrating how to automate diffing operations for specific log entries or a range of recent entries. Also shows how to compare an 'after' state with the 'current' live file.

```bash
# Diff a specific operation
diff -u --color notes/.log/<log_id>/before notes/.log/<log_id>/after

# Diff all recent changes
for id in $(ls notes/.log/.last/10); do
    echo "=== $id ==="
    diff -u --color notes/.log/$id/before notes/.log/$id/after
done

# What changed since this operation vs now?
diff -u --color notes/.log/<log_id>/after notes/.log/<log_id>/current
```

--------------------------------

### Creating a Savepoint and Undoing Changes

Source: https://github.com/timescale/tigerfs/blob/main/docs/file-first.md

Demonstrates how to create a savepoint before making changes and then compare the current state to the savepoint for potential undo operations. This is useful for managing versions and recovering from mistakes.

```bash
# Create savepoint, work, review, undo if needed
echo '{"description":"Before refactoring"}' > /mnt/db/notes/.savepoint/before-refactor.json
# ... make changes ...
diff -ru /mnt/db/notes/.undo/to-savepoint/before-refactor /mnt/db/notes/ -x '.*'
touch /mnt/db/notes/.undo/to-savepoint/before-refactor/.apply
```

--------------------------------

### Read individual field from savepoint

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

Reads a specific field's value from a savepoint. This example reads the 'description' field.

```bash
cat .savepoint/my-checkpoint/description
```

--------------------------------

### Commit Failure Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Illustrates a potential commit failure, such as when a table already exists, and notes that staging is preserved for recovery.

```bash
touch /mnt/db/.create/orders/.commit
# Returns EEXIST if table already exists
# Returns EIO with logged error details

```

--------------------------------

### File Ownership Example

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Shows that all files are owned by the user running the FUSE daemon, as indicated by `ls -l` output.

```bash
-rw-r--r-- 1 mfreed staff  25 Jan 23 10:00 /mnt/db/users/123/email
```

--------------------------------

### Verify Schema Discovery and Table Listing

Source: https://github.com/timescale/tigerfs/blob/main/docs/implementation/implementation-tasks.md

This bash script shows how to create a test table, mount the TigerFS filesystem, and verify that the table is listed in the root directory.

```bash
# Create test table
psql postgres://postgres:test@localhost/postgres -c "CREATE TABLE users (id serial primary key, email text);"

# Mount and list
go run ./cmd/tigerfs postgres://postgres:test@localhost/postgres /tmp/testmount
ls /tmp/testmount/
# Should show: users

umount /tmp/testmount
```

--------------------------------

### File Permissions Example based on PostgreSQL Grants

Source: https://github.com/timescale/tigerfs/blob/main/docs/spec.md

Illustrates how PostgreSQL table grants map to Unix-like file permissions, shown with `ls -l` output.

```bash
# User has SELECT + UPDATE on users table
-rw-r--r-- 1 user user  25 Jan 23 10:00 /mnt/db/users/123/email

# User has only SELECT on orders table
-r--r--r-- 1 user user 100 Jan 23 10:00 /mnt/db/orders/456/total
```

--------------------------------

### List All Files and Directories (including dot-directories)

Source: https://github.com/timescale/tigerfs/blob/main/README.md

Shows how to list all entries in a directory, including hidden dot-directories which control TigerFS operations.

```bash
$ ls -a /mnt/db/notes/
.  ..  .history/  .log/  .savepoint/  .undo/  hello.md  tutorials/
```