Pre-release
This release is a pre-release and may not be stable for production use.
Turso Database for Python
About
Turso Database runs in production today at multiple organizations. It has not yet reached 1.0, so as with any database we recommend keeping backups — see the FAQ for where the project stands.
Features
- SQLite compatible: SQLite query language and file format support (status).
- In-process: No network overhead, runs directly in your Python process
- Cross-platform: Supports Linux, macOS, Windows
- Remote partial sync: Bootstrap from a remote database, pull remote changes, and push local changes when online — all while enjoying a fully operational database offline.
- Asyncio support: Built-in integration with asyncio to ensure queries won’t block your event loop
Installation
uv pip install pyturso
Database driver
A minimal DB‑API 2.0 example using an in‑memory database:
import turso
# Standard DB-API usage
conn = turso.connect(":memory:")
cur = conn.cursor()
cur.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, username TEXT)")
cur.execute("INSERT INTO users VALUES (1, 'alice'), (2, 'bob')")
cur.execute("SELECT * FROM users ORDER BY id")
rows = cur.fetchall()
print(rows) # [(1, 'alice'), (2, 'bob')]
conn.close()
Database driver (asyncio)
Non-blocking access with asyncio:
import asyncio
import turso.aio
async def main():
# Connect and use as an async context manager
async with turso.aio.connect(":memory:") as conn:
# Executes multiple statements
await conn.executescript("""
CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT);
INSERT INTO t(name) VALUES ('alice'), ('bob');
""")
# Use a cursor for parameterized queries
cur = conn.cursor()
await cur.execute("SELECT COUNT(*) FROM t WHERE name LIKE ?", ("a%",))
count = (await cur.fetchone())[0]
print(count) # 1
# JSON and generate_series also available
cur = conn.cursor()
await cur.execute("SELECT SUM(value) FROM generate_series(1, 10)")
print((await cur.fetchone())[0]) # 55
asyncio.run(main())
Synchronization driver
Use a remote Turso database while working locally. You can bootstrap local state from the remote, pull remote changes, and push local commits.
Note: You need a Turso remote URL. See the Turso docs for provisioning and authentication.
import turso.sync
# Connect a local database to a remote Turso database
conn = turso.sync.connect(
":memory:", # local db path (or a file path)
remote_url="https://<db>.<region>.turso.io" # your remote URL
)
# Read data (fetched from remote if not present locally yet)
rows = conn.execute("SELECT * FROM t").fetchall()
print(rows)
# Pull new changes from remote into local
changed = conn.pull()
print("Pulled:", changed) # True if there were new remote changes
# Make local changes
conn.execute("INSERT INTO t VALUES ('push works')")
conn.commit()
# Push local commits to remote
conn.push()
# Optional: inspect and manage sync state
stats = conn.stats()
print("Network received (bytes):", stats.network_received_bytes)
conn.checkpoint() # compact local WAL after many writes
conn.close()
Partial bootstrap to reduce initial network cost:
import turso.sync
conn = turso.sync.connect(
"local.db",
remote_url="https://<db>.<region>.turso.io",
# fetch first 128 KiB upfront
partial_sync_experimental=turso.sync.PartialSyncOpts(
bootstrap_strategy=turso.sync.PartialSyncPrefixBootstrap(length=128 * 1024),
),
)
Synchronization driver (asyncio)
The same sync primitives, but fully async:
import asyncio
async def main():
conn = await turso.aio.sync.connect(":memory:", remote_url="https://<db>.<region>.turso.io")
# Read data
rows = await (await conn.execute("SELECT * FROM t")).fetchall()
print(rows)
# Pull and push
await conn.pull()
await conn.execute("INSERT INTO t VALUES ('hello from asyncio')")
await conn.commit()
await conn.push()
# Stats and maintenance
stats = await conn.stats()
print("Main WAL size:", stats.main_wal_size)
await conn.checkpoint()
await conn.close()
asyncio.run(main())
License
This project is licensed under the MIT license.
Support
1 maintainer
Release files for pyturso 0.8.0rc11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pyturso-0.8.0rc11.tar.gz | 3.3 MB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| pyturso-0.8.0rc11-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ x86-64 | Details |
| pyturso-0.8.0rc11-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.17+ ARM64 | Details |
| pyturso-0.8.0rc11-cp310-abi3-macosx_11_0_arm64.whl | CPython 3.10 | abi3 | macOS 11.0+ ARM64 | Details |
| pyturso-0.8.0rc11-cp310-abi3-macosx_10_12_x86_64.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 76.2 MB
Release files / pyturso-0.8.0rc11.tar.gz
| Download URL | pyturso-0.8.0rc11.tar.gz |
|---|---|
| Size | 3.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
81c427e2758e796eaa7e5cd9252c3a4aa599e90f9cfeb04e86d39400b3388ff3
|
|
BLAKE2b-256 checksum How to use checksums |
5ceebcf833899909b3c867444aad71b33c6b395d156ee1ecad6a9a04c658310b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / pyturso-0.8.0rc11-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pyturso-0.8.0rc11-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 27.9 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
345982f253e3204f11457f9838fdc84cc458141ab458c31ca51189a3c82cb68e
|
|
BLAKE2b-256 checksum How to use checksums |
5b6bede5b6895aebd56815301e136cf1044328e3ea14c4d3afdf439962496deb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / pyturso-0.8.0rc11-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pyturso-0.8.0rc11-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 27.5 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
4ca9c6806121851032ba41e28e9546173e3cd18a3b129c2effdd4d2bc1d10175
|
|
BLAKE2b-256 checksum How to use checksums |
59e04e7062cda23a2d3d5266a6b08a3e8ce21b3664e1e75d423abd8f93f156a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / pyturso-0.8.0rc11-cp310-abi3-macosx_11_0_arm64.whl
| Download URL | pyturso-0.8.0rc11-cp310-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 8.2 MB |
| Tags | CPython 3.10 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
f6df49c364714e4b80d32700511f43d27ff0639bb95c6fba81dd52bcdcfd289c
|
|
BLAKE2b-256 checksum How to use checksums |
b854c0a2efdb752dc24b7b5010dfe27b8ca924ed72f0ec5519a03f5e34fe4b4d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / pyturso-0.8.0rc11-cp310-abi3-macosx_10_12_x86_64.whl
| Download URL | pyturso-0.8.0rc11-cp310-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 9.4 MB |
| Tags | CPython 3.10 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
c17856b9dfd96b96379fc16b2f6bb9c2a28fc573e14810c25123e54fe0e2b04a
|
|
BLAKE2b-256 checksum How to use checksums |
337ed98d35887e7b56b2e1bab3e873534f3b9420e27f0287f8d8b34a3c1ae043
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
