turso-integration

Purpose

Research on whether DuckDB can connect to and query Turso libSQL databases, and if so, what integration patterns are available.

Key Findings

No Direct Native Connector

As of 2025, there is no official DuckDB extension or native connector for directly querying Turso/libSQL databases. DuckDB cannot use Turso’s libsql:// protocol or WebSocket/HTTP hrana protocol natively.

Integration Pattern: HTTP API + httpfs Extension

The most practical integration path uses Turso’s HTTP REST API combined with DuckDB’s httpfs extension:

Turso HTTP API:

Turso databases expose an HTTP API at /v2/pipeline endpoint
Replace libsql:// protocol with https:// to access via HTTP
Requires Bearer authentication (API token in Authorization header)
Returns results as JSON
HTTP works better for single queries; WebSockets better for sustained connections

DuckDB httpfs Extension:

Autoloads when querying HTTP(S) URLs — no manual installation needed
Supports reading files over HTTP (read-only access)
Works with CSV, Parquet, JSON, and other DuckDB-supported formats
For JSON: combine with json extension using read_json_auto()

Integration Workflow:

Query Turso via its HTTP API (https://your-db.turso.io/v2/pipeline)
Receive JSON response
Load JSON into DuckDB using httpfs + json extensions

Example:

LOAD json;
LOAD httpfs;
SELECT * FROM read_json_auto('https://your-turso-db.turso.io/v2/pipeline?q=SELECT+*+FROM+table');

Alternative: Embedded Replica as Shared File

libSQL’s embedded replica feature could enable a file-based integration:

Use libSQL client to sync a local SQLite file (embedded replica) from Turso
DuckDB reads the local SQLite file directly using its sqlite extension

This gives DuckDB read access to Turso data via a local file, but requires managing the sync separately.

Ecosystem Context

Turso strengthens the lightweight database ecosystem alongside DuckDB
Both are Rust-based, performance-focused, cloud-native tools
Turso extends SQLite’s concurrency limits; DuckDB focuses on analytics
Complementary use case: Turso for OLTP, DuckDB for OLAP analytics on exported data

Limitations

No real-time query federation — must export/sync data from Turso to DuckDB
HTTP API integration adds latency vs. direct database connection
Embedded replica approach requires periodic syncing

Recommendations

Use Turso HTTP API + DuckDB httpfs when:

You need one-time analytics on Turso data
You can tolerate HTTP request latency
Data freshness can lag slightly

Use embedded replica + DuckDB SQLite extension when:

You need repeated local analytics
You want to minimize API calls
You can manage a sync process

Don’t expect:

DuckDB to query Turso in real-time as a foreign data source
Direct libSQL protocol support in DuckDB