TigerFS Documentation

For tables with multi-column primary keys, TigerFS uses a comma-delimited path representation.

Path Format:

• For a primary key consisting of (customer_id, product_id) with values (5, 42), the directory name is 5,42.
• Values containing commas are URL-encoded as %2C to prevent path ambiguity.

Example: If a table order_items has a composite PK (customer_id, product_id):

• ls /mount/order_items/ might show 1,100.
• cat /mount/order_items/1,100/quantity retrieves the value for that specific composite row.

# Manual verification of composite PK
psql -c "CREATE TABLE order_items (customer_id int, product_id int, quantity int, PRIMARY KEY (customer_id, product_id));"
psql -c "INSERT INTO order_items VALUES (1, 100, 5), (1, 200, 3);"

ls /mount/order_items/            # Should show: 1,100
cat /mount/order_items/1,100      # Should show row data

In TigerFS, data stored in the memFile cache is committed to the underlying database based on the following triggers:

TigerFS uses a layered credential resolution strategy to find PostgreSQL database credentials. It prioritizes standard PostgreSQL conventions to ensure compatibility across desktop, server, container, and CI/CD environments.

When looking for a password, TigerFS checks sources in the following order of precedence (highest to lowest):

1. Connection String: The password provided directly in the connection string.
2. Environment Variables: The PGPASSWORD or TIGERFS_PASSWORD environment variables.
3. password_command: An external command configured in the settings used to fetch secrets from a manager.
4. ~/.pgpass file: The standard PostgreSQL password file (handled via the pgx library).

Note: TigerFS does not use system keyrings (like macOS Keychain or Windows Credential Manager) and does not support plain-text passwords in the configuration file.

To support arbitrary user-defined metadata in markdown files without changing the database schema, TigerFS uses a headers JSONB column.

How it works:

• Synthesis: During file generation, any key-value pairs stored in the headers JSONB column are merged into the YAML frontmatter block (sorted alphabetically after known columns).
• Parsing: When a user adds a key to the markdown frontmatter that does not correspond to a fixed column (like title or author), TigerFS collects these "unknown" keys and stores them in the headers JSONB column.
• Overwrite Semantics: If a key is removed from the markdown frontmatter, it is removed from the headers JSONB column in the database.

Requirement: The underlying table must have a headers JSONB DEFAULT '{}'::jsonb column for this to function.

TigerFS supports cloud-native backends like Tiger Cloud and Ghost using a URI prefix scheme. Instead of passing traditional database flags, you can use prefixes to identify the backend service.

Supported Prefixes:

• tiger:<id>
• ghost:<id>

Cloud Commands:

• create [BACKEND:]NAME [MOUNTPOINT]: Creates a new resource on the specified backend.
• fork SOURCE [DEST]: Forks an existing resource.
• info [MOUNTPOINT]: Displays detailed information about a cloud-backed mount.

Mounting with a prefix: Instead of using --host or --user, pass the prefixed connection string directly to the mount command.

Example:

go run ./cmd/tigerfs mount tiger:my-service-id /tmp/cloudmount

TigerFS allows you to access tables from different PostgreSQL schemas using two methods:

1. Schema Prefixes: Use the schema name as a directory prefix in your path.

   • /users/ maps to public.users (default schema).
   • /analytics/reports/ maps to analytics.reports.

2. Explicit Access via .schemas/: Use the .schemas/ directory to browse all available schemas explicitly.

   • /.schemas/public/users/ maps to public.users.

The default schema is configurable via the TigerFS configuration.

# Example: Accessing a table in the 'analytics' schema
ls /tmp/testmount/analytics/

# Example: Explicit access via .schemas directory
ls /tmp/testmount/.schemas/public/

To prevent column names from colliding with reserved capability names (like .first or .last), all index-based navigation is moved under a .by/ subdirectory. This directory contains subdirectories for every indexed column (single or composite).

Example Structure:

• .by/email/: Access via the email index.
• .by/last_name.first_name/: Access via the composite last_name and first_name index.

# Example directory structure
/mnt/db/users/
├── .by/
│   ├── email/           # single-column index
│   │   └── foo@example.com/
│   └── last_name.first_name/  # composite index
│       └── Smith/
│           └── John/
├── .info/
└── 1/