Linked databases

tessera supports multiple databases that know about each other. This is useful when a large collection is spread across several drives, or when you want independent databases per sub-collection but still want to query them together.

Concepts

Root database — the database you run tessera commands from.
Linked (child) database — a database registered as a child of the root.
Ancestor database — a database whose root is a parent directory of the current root. tessera finds these automatically by walking up the directory tree.

By default, queries include the root database, all linked children, and all ancestors.

Managing linked databases

# List linked databases
tessera db ls

# Add a child database
tessera db add /path/to/child/collection

# Remove a child database
tessera db remove /path/to/child/collection

# Remove dead registrations (paths that no longer exist)
tessera db prune

Global registry

For collections that are not in parent/child directory relationships, use the global registry:

# Register the current database globally
tessera db register

# Unregister
tessera db unregister

# List all globally registered databases
tessera db registered

Query scope

# Default: current DB + children + ancestors
tessera find QUERY

# Current database only
tessera find QUERY --isolated

# All globally registered databases
tessera find QUERY --all-dbs

# Exclude ancestor databases
tessera find QUERY --no-parents

Pushing and pulling tags

Copy tag records between databases when files exist in both:

# Copy tags from root → child (for files the child knows about)
tessera db push /path/to/child --dry-run
tessera db push /path/to/child

# Copy tags from child → root
tessera db pull /path/to/child --dry-run
tessera db pull /path/to/child