SQLite Extensions

SQLite Extensions

db-mcp supports both built-in and loadable SQLite extensions. Built-in extensions are compiled into SQLite and always available. Loadable extensions require CLI flags or environment variables.

---

Built-in Extensions

These extensions are compiled into SQLite and require no additional configuration:

Extension	Purpose	Tools	Notes
JSON1	JSON/JSONB operations	25 (json)	Foundation for the json tool group
FTS5	Full-text search with BM25 ranking	5 (text)	Native backend only; powers fts_* tools
R-Tree	Spatial indexing for range queries	1 (admin)	Used by create_rtree_table

JSON1 is available in both WASM and Native backends. FTS5 and R-Tree index creation require the Native backend (--sqlite-native).

---

Loadable Extensions

CSV Extension

Creates virtual tables backed by CSV files — query CSV data with SQL without importing.

Detail	Value
CLI Flag	--csv
Env Var	CSV_EXTENSION_PATH — path to the CSV extension binary
Backend	Native only
Tools	sqlite_create_csv_table, sqlite_analyze_csv_schema

Usage:

# Specify the extension path
CSV_EXTENSION_PATH=/path/to/csv.so node dist/cli.js --csv --sqlite-native ./database.db

# Docker (pre-installed if available)
docker run --rm -i \
  -e CSV_EXTENSION_PATH=/usr/lib/sqlite3/csv.so \
  -v ./data:/app/data \
  writenotenow/db-mcp:latest \
  --csv --sqlite-native /app/data/database.db

---

SpatiaLite Extension

Advanced GIS capabilities — geometry operations, spatial queries, coordinate transformations, and R-Tree spatial indexing.

Detail	Value
CLI Flag	--spatialite
Env Var	SPATIALITE_PATH — path to the SpatiaLite extension binary
Backend	Native only
Platform	Pre-installed on AMD64 Docker image only
Tools	7 tools: spatialite_load, spatialite_create_table, spatialite_query, spatialite_analyze, spatialite_index, spatialite_transform, spatialite_import

Usage:

# Linux (typical path)
SPATIALITE_PATH=/usr/lib/x86_64-linux-gnu/mod_spatialite.so \
  node dist/cli.js --spatialite --sqlite-native ./database.db

# macOS (Homebrew)
SPATIALITE_PATH=/opt/homebrew/lib/mod_spatialite.dylib \
  node dist/cli.js --spatialite --sqlite-native ./database.db

# Docker AMD64 (pre-installed)
docker run --rm -i \
  -v ./data:/app/data \
  writenotenow/db-mcp:latest \
  --spatialite --sqlite-native /app/data/database.db

ARM64 Note: SpatiaLite is not pre-installed in the ARM64 Docker image. You can install it manually or use a custom image.

---

Extension Availability Matrix

Extension	WASM	Native	Docker AMD64	Docker ARM64	CLI Flag
JSON1	✅	✅	✅	✅	—
FTS5	❌	✅	✅	✅	—
R-Tree	✅	✅	✅	✅	—
CSV	❌	✅	⚠️	⚠️	--csv
SpatiaLite	❌	✅	✅	❌	--spatialite

⚠️ CSV extension availability in Docker depends on the image build. Set CSV_EXTENSION_PATH to the binary location.

---

Loading Extensions at Runtime

Extensions are loaded during server startup when the corresponding CLI flag is passed. The server validates:

1. The extension binary exists at the specified path
2. The Native backend is active (extensions don't work with WASM)
3. SQLite has ENABLE_LOAD_EXTENSION compiled in

If loading fails, the server logs a warning and continues without the extension — affected tools return structured errors explaining the extension is unavailable.

---

Related

• Tool Reference — Full tool inventory including extension tools
• Quick Start — Extension configuration in MCP client JSON
• Troubleshooting — Extension loading issues