Registry / database / libsql-experimental

libsql-experimental

library0.0.49pypypi✓ verified 53d ago

Python SDK for Turso, a distributed SQLite database built on libSQL. Provides a dbapi2-compatible interface for connecting to local SQLite files, libSQL servers, and Turso hosted databases. The package name on PyPI is libsql-experimental (not 'turso').

database

pip install libsql-experimental

package ↗

Install & Compatibility

Where this runs

tested against v0.0.55 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

build_error

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 2.0s · import 0.000s · 31MB

29MB installed

● package 29MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

libsql_experimental

✓ import libsql_experimental as libsql

✗ import turso

The package is named libsql-experimental on PyPI and imported as libsql_experimental. There is no 'turso' Python module.

connect

✓ import libsql_experimental as libsql conn = libsql.connect('mydb.db', sync_url='libsql://...', auth_token='...')

✗ import sqlite3 conn = sqlite3.connect('libsql://...')

sqlite3 cannot connect to Turso remote URLs. Use libsql_experimental.connect() with sync_url and auth_token for remote Turso databases.

Connect to a Turso database using an embedded replica pattern with local SQLite file and remote sync.

import os import libsql_experimental as libsql url = os.environ.get('TURSO_DATABASE_URL', '') token = os.environ.get('TURSO_AUTH_TOKEN', '') # Embedded replica with local file + remote sync conn = libsql.connect('local.db', sync_url=url, auth_token=token) conn.sync() conn.execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)') conn.execute('INSERT INTO users (name) VALUES (?)', ('Alice',)) conn.commit() rows = conn.execute('SELECT * FROM users').fetchall() for row in rows: print(row) conn.sync()

Debug

Known issues

gotchaThe package name is libsql-experimental, not turso or libsql. `pip install turso` will install a different unrelated package or fail.

fix

pip install libsql-experimental

affects: all

gotchaYou must call conn.sync() explicitly to push local writes to the remote Turso database and pull remote changes. Without sync(), embedded replicas remain stale.

fix

Call conn.sync() after writes and before reads that need fresh remote data.

affects: all

gotchaconn.commit() is required after INSERT/UPDATE/DELETE. Auto-commit is not enabled by default, matching dbapi2 behavior.

fix

Always call conn.commit() after write operations, or use conn.executescript() which auto-commits.

affects: all

gotchaWhen using sync_url for embedded replicas, the first positional argument must be a local file path (e.g., 'local.db'), not an empty string or ':memory:'.

fix

Provide a valid local file path: libsql.connect('local.db', sync_url=url, auth_token=token)

affects: all

gotchaFor remote-only connections (no local replica), pass the libsql:// URL as the first argument without sync_url. Mixing them up causes connection errors.

fix

Remote only: libsql.connect(url, auth_token=token). Embedded replica: libsql.connect('local.db', sync_url=url, auth_token=token).

affects: all

deprecatedThe package is marked 'experimental'. API surface may change between minor releases without deprecation warnings.

fix

Pin your version in production: libsql-experimental==0.0.49

affects: all

breakingBuilding `libsql-experimental` in `musl`-based Linux environments (e.g., Alpine Linux) requires `gcc` or `build-base` to be installed. Without it, `cargo` may fail to find necessary shared libraries (e.g., `libgcc_s.so.1`) or encounter relocation errors, preventing package installation.

fix

Ensure `gcc` or a development package like `build-base` is installed in your `musl` environment. For Alpine Linux, run: `apk add build-base`.

affects: all

Errors

Common errors & fixes

error: subprocess-exited-with-error × Building wheel for libsql-experimental (pyproject.toml) did not run successfully.

This error often occurs on Windows, especially with Python 3.12, due to missing build tools or issues with the underlying Rust `libsql-ffi` build script, which may rely on Unix-like commands (`cp`) not natively available.

fix

Ensure you have the Rust toolchain (Rustup, Cargo) and C++ build tools (e.g., from Visual Studio Build Tools) installed. Consider using a Linux or macOS environment, or a Docker container for development, as Windows support can be challenging due to platform differences in build environments. Upgrading `libsql-experimental` to a newer version might also include fixes for these build issues.

pyo3_runtime.PanicException: there is no reactor running, must be called from the context of a Tokio 1.x runtime

This panic occurs when attempting to connect to a remote Turso database or use other async features of `libsql-experimental` without an active asynchronous runtime (like `asyncio` in Python) in the current thread or scope.

fix

Ensure that your code is run within an `asyncio` event loop. For example, wrap your connection and query logic in an `async` function and run it using `asyncio.run()`.

ModuleNotFoundError: No module named 'libsql_experimental'

The `libsql-experimental` package has not been installed in your current Python environment, or the Python interpreter running your script is not the one where the package was installed.

fix

Install the package using pip: `pip install libsql-experimental`. If you are using virtual environments, ensure your environment is activated before installation and when running your script. Verify the Python interpreter being used (e.g., `which python` and `python -m pip install ...`).

pyo3_runtime.PanicException: not yet implemented (when inserting None values)

This error indicates that the `libsql-experimental` library, at the specific version used, does not yet support inserting `None` (Python's `null`) directly as a parameter in `execute` or `executemany` statements, resulting in an unimplemented panic in the underlying Rust code.

fix

Instead of passing `None` directly, explicitly pass an empty string `''` or a string representation of `NULL` if your schema allows it and the database interprets it correctly as a `NULL` value, or wait for a library update that implements this functionality.

Upgrade

Version history

0.0.55latest on PyPI

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node