title: 'Turso Data Accelerator' sidebar_label: 'Turso Data Accelerator' description: 'Turso (libSQL) Data Accelerator Documentation' sidebar_position: 6 tags:
:::info Beta The Turso Data Accelerator is in Beta. Features and configuration may change. :::
:::warning[Deprecated]
The turso acceleration engine is deprecated in v2.4 and will be removed in v2.5. A Spicepod with a dataset or view that uses it logs one warning at startup, and one on each hot reload that adds or changes such a component, naming those datasets and views. A cluster executor does not log it. Runtimes up to and including v2.4.0-rc.3 do not log this warning. Move these accelerations to Spice Cayenne (opens in a new tab) before upgrading to v2.5; see Migrating to Spice Cayenne (opens in a new tab).
:::
The Turso Data Accelerator uses Turso (opens in a new tab) (built on libSQL (opens in a new tab), a fork of SQLite) as the acceleration engine for caching and accelerating query performance. Turso provides native async support and modern improvements over traditional SQLite while maintaining SQLite compatibility.
To enable Turso acceleration, set the dataset's acceleration.engine to turso:
By default, Turso acceleration uses mode: memory, creating an in-memory database for fast temporary caching:
When using mode: file, datasets are stored by default in a Turso database file on disk in the .spice/data directory relative to the spicepod.yaml. Specify the turso_file parameter to store the database file in a different location:
Turso acceleration supports the following optional parameters under acceleration.params:
turso_file (string, default: .spice/data/{dataset_name}.turso): Path to the Turso database file. Only applies if mode is file. If the file does not exist, Spice creates it automatically. Keep it on local NVMe or SSD for its per-I/O latency: Turso is SQLite-derived and inherits SQLite's dependence on file-system locking, so a network file system (NFS, SMB, EFS, Azure Files) is not recommended. On network block storage (EBS, Azure Managed Disks) the runtime resolves the acceleration's storage_profile (opens in a new tab) to ebs and raises Turso's page cache to ~200 MB to absorb per-I/O latency. See Storage (opens in a new tab).internal_timestamp_format (string, default: rfc3339): Internal timestamp storage format. See Timestamp Storage (opens in a new tab) section. Values: rfc3339, integer_millis.Refer to the datasets configuration reference (opens in a new tab) for additional supported fields.
Turso supports two timestamp storage formats to accommodate different use cases:
By default, timestamps are stored as RFC3339 TEXT strings (e.g., "2024-01-01T00:00:00.123456789Z"). This format preserves all timestamp information:
NULL (i64 nanosecond overflow). Second, Millisecond, and Microsecond precisions are not affected.For performance-critical use cases, set internal_timestamp_format: "integer_millis" to store timestamps as integers (milliseconds since Unix epoch):
Multi-Version Concurrency Control (MVCC) is automatically enabled for all Turso-accelerated datasets. The Turso accelerator sets PRAGMA journal_mode = 'mvcc' during connection pool initialization, enabling concurrent transactions via BEGIN CONCURRENT.
When MVCC is active:
enabled) and unique (unique) indexes are created and enforced normallyTurso supports index creation for improved query performance:
See Indexes (opens in a new tab) for more details.
Turso uses connection pooling for efficient database access. Connection pools are shared across datasets using the same database file.
Turso supports query federation, where queries can span multiple data sources. The accelerator pushes down filters, projections, and limits when possible for improved performance.
Turso SQL has no quantified comparisons, so a query that uses ANY or ALL, such as WHERE v > ANY (SELECT val FROM details), is not sent to Turso as written. This applies wherever the comparison appears, including inside another subquery. Turso still reads the tables, and Spice evaluates the comparison. A filter that contains a subquery, an outer reference, or unnest is also evaluated in Spice rather than pushed into the Turso scan.
turso_url and turso_auth_token are not supported in this accelerator context. Remote Turso support will be available when Turso is implemented as a data connector.List types of primitive data types are supported; lists with structs are not supported.NULL with a warning. Refreshing the acceleration or using a fresh file rewrites them in the supported encoding.Turso is built on libSQL (a fork of SQLite) and offers several advantages:
| Feature | Turso | SQLite |
|---|---|---|
| Async Support | Native async via libSQL | Synchronous with spawn_blocking |
| Connection Model | Modern async pooling | Traditional sync connections |
| Performance | Optimized for modern workloads | Traditional SQLite performance |
| File Extensions | .turso, .db, .sqlite, .sqlite3 | .db, .sqlite, .sqlite3 |
Choose Turso when you need:
Choose SQLite when you need:
:::warning[Memory Considerations]
When accelerating a dataset using mode: memory (the default), the dataset is loaded into memory. Ensure sufficient memory is available, including overhead for queries and the runtime, especially with concurrent queries.
In-memory limitations can be mitigated by storing acceleration data on disk using mode: file.
:::
Turso is an optional feature in Spice. To build with Turso support: