Mori

Prerequisites: Go 1.21+, Docker (for Shadow containers — all engines except SQLite and DuckDB).

Key Concepts

Supported Engines

Setup & Lifecycle

Build

go build -o mori ./cmd/mori

Initialize a Connection

Interactive mode walks through engine, provider, and credentials:

./mori init

Non-interactive with a connection string:

./mori init --from "postgres://user:pass@host:5432/mydb?sslmode=require" --name my-db

This saves the connection to mori.yaml. No containers or connections are created yet.

Start the Proxy

./mori start [connection-name] --port 9002 --verbose

On first start, Mori creates the Shadow database (schema-only clone of Prod), computes sequence offsets, and begins accepting connections. If only one connection exists, the name is optional.

Point Your App at Mori

Swap your application's connection string to localhost:<proxy-port>. Same credentials, same database name. The app won't know the difference.

Lifecycle

mori init         Save connection config to mori.yaml
     |
mori start        Create Shadow (first run), start proxy, accept connections
     |
  [app runs]      CRUD operations routed transparently
     |
mori stop         Persist state, shut down proxy
     |
mori reset        Wipe Shadow data + metadata, clean slate

CLI Reference

mori init

Add a database connection to mori.yaml.

mori start [name]

Start the proxy for a named connection. If only one connection exists, name is optional.

mori stop

Gracefully shut down the proxy. State is persisted automatically.

mori reset

Wipe all local mutations and restore a clean view of production.

Soft reset: truncates Shadow tables, clears Delta Map, Tombstone Set, Schema Registry, resets sequence offsets. Hard reset: drops and re-creates Shadow tables from current Prod schema.

mori status

Display current state: engine info, connection details, delta row counts, tombstone counts, schema diffs, sequence offsets.

mori inspect <table>

Deep dive on a single table's state — delta rows, tombstoned rows, schema differences.

mori log

Stream proxy activity (queries, routing decisions, timing).

mori ls

List all configured connections from mori.yaml.

mori rm <name>

Remove a connection from mori.yaml.

mori config

View or edit the current configuration.

mori dash

Launch the interactive TUI dashboard.

How Routing Works

Every incoming query follows this path:

App -> Proxy (wire protocol) -> Classifier -> Router -> Execute (strategy) -> Merge -> Return

The Classifier parses each query to determine its operation type, affected tables, and extractable primary keys. The Router uses this classification plus current delta/tombstone state to pick a routing strategy.

Understanding routing helps explain query behavior. For example, a SELECT on a table you've never modified goes straight to Prod (ProdDirect). Once you UPDATE a row in that table, subsequent SELECTs use MergedRead to combine Prod and Shadow results.

Configuration & State

Mori stores all state in a .mori/ directory at the project root.

.mori/
  mori.yaml                     # Connection configs (engine, host, port, user, password, database, ssl_mode)
  config.json                   # Runtime config (prod connection, shadow port, active connection)
  shadow/                       # Shadow container metadata (Docker IDs, port mappings)
  state/
    delta.json                  # Delta Map: { "table_name": ["pk1", "pk2", ...] }
    tombstones.json             # Tombstone Set: { "table_name": ["pk1", "pk2", ...] }
    schema_registry.json        # Schema divergence tracking (added/dropped/renamed columns per table)
    tables.json                 # Table metadata (PK columns, PK types per table)
    sequences.json              # Sequence offsets per table
  log/                          # Query logs, routing decisions

Reading State for Debugging

• Delta Map (state/delta.json): shows which tables have locally modified rows and which PKs. If a table appears here, reads on it use MergedRead.
• Tombstone Set (state/tombstones.json): shows locally deleted rows. These PKs are filtered from Prod results.
• Schema Registry (state/schema_registry.json): shows DDL differences. Non-empty means Shadow schema diverges from Prod.
• Tables (state/tables.json): PK columns and types per table. Used by the classifier and merge engine.
• Sequences (state/sequences.json): offset values for auto-increment columns. Prevents INSERT PK collisions.

MCP Server Integration

Mori includes an MCP (Model Context Protocol) server for AI agent integration. Start it alongside the proxy:

./mori start my-db --mcp --mcp-port 9000

The MCP server registers engine-specific tools based on your database type:

SQL engines (PostgreSQL, CockroachDB, MySQL, MariaDB, MSSQL, SQLite, DuckDB):

• db_query — Execute a SQL query. Parameter: query (string, required).

Redis:

• redis_command — Execute any Redis command (free-form).
• redis_get — Get the value of a key.
• redis_hgetall — Get all fields and values of a hash.
• redis_keys — Find keys matching a pattern.

Firestore:

• firestore_get — Retrieve a document by collection and document ID.

• firestore_list — List documents in a collection (default 25, max 100).

• firestore_query — Query with field filters (==, !=, <, <=, >, >=, in, array-contains).

• Endpoint: http://127.0.0.1:9000/mcp

• Behavior: All tools go through the proxy's full routing/merge logic, same as application connections. Reads from Prod, writes to Shadow.

MCP Client Configuration

To connect an MCP client (e.g., Claude Code), add to your MCP settings:

{
  "mcpServers": {
    "mori": {
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}

Debugging & Troubleshooting

Proxy won't start

1. Docker not running: Shadow containers require Docker. Check with docker ps.
2. Port conflict: Default proxy port is 9002. Use --port to pick another.
3. No .mori/ directory: Run mori init first to configure a connection.
4. Another connection active: Run mori stop before starting a different connection.

Unexpected query results

1. Run mori status to see which tables have deltas/tombstones. Tables with deltas use MergedRead instead of ProdDirect.
2. Run mori inspect <table> to see exactly which rows are modified/deleted locally.
3. Use --verbose when starting the proxy to log every query's classification and routing decision.
4. Check mori log for recent query activity and any errors.

Missing rows after INSERT

• Check sequence offsets in state/sequences.json. Shadow sequences start at max(prod_max * 10, prod_max + 10_000_000) to avoid PK collisions. If Prod has grown significantly since init, offsets may need recalculating via mori reset --hard.

Stale data after reset

• Soft reset keeps the Shadow schema from init time. If Prod schema has changed, use mori reset --hard to re-sync.

Shadow container issues

docker ps -a | grep mori-shadow    # List Mori Shadow containers
docker logs <container-id>          # Check container logs
docker restart <container-id>       # Restart a stuck container

When to use --hard reset

Use mori reset --hard when:

• Production schema changed since mori init (new tables, altered columns)
• Sequence offsets are exhausted or colliding
• Shadow is in an inconsistent state

Use soft mori reset (no flag) for routine testing cycles — it's faster and preserves the schema.

Known Limitations

• Multi-column ORDER BY: Only single-column re-sorting after merge is supported.
• Parameterized LIMIT: LIMIT $1 is not rewritten for over-fetching during merged reads.
• Aggregate merging: COUNT/SUM on delta tables are merged as rows, not re-aggregated. Results may differ from a direct Prod query.
• JOIN PK patching: Requires the primary key column to be in the SELECT list for JoinPatch to work.
• Tables without PKs: Treated as read-only (rare in practice).
• Bulk operations: Hydrating thousands of rows (e.g., UPDATE ... WHERE id IN (...) with many IDs) is slower than single-row operations.

Further Reading

• Architecture deep dive: docs/mori.md — covers routing logic, merge engine internals, design decisions, and the 4-layer write guard in detail.
• Testing status: docs/testing.md — tracks E2E test coverage per engine.
• Full documentation site: docs/mintlify/ — MDX-based docs covering concepts, engine guides, CLI reference, and advanced topics.