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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
pyturso-0.7.2.tar.gz
(2.9 MB
view details)
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pyturso-0.7.2.tar.gz.
File metadata
- Download URL: pyturso-0.7.2.tar.gz
- Upload date:
- Size: 2.9 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4d912f53338af195c3bc343b02c4450ae1a0be9892835aa7f962ec49b730ef9f
|
|
| MD5 |
72bcdb5e7b643225230dd27d6bdf39cc
|
|
| BLAKE2b-256 |
2300b92f81e67af1e1d0ee59b1462cbb5de21339e637ca415f9ebbd0ca8ab6fb
|
File details
Details for the file pyturso-0.7.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: pyturso-0.7.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 26.6 MB
- Tags: CPython 3.10+, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e324ccdf1b9d718abbb26a789ba061d554bb8a7c3fca162fdafdb398dee10aeb
|
|
| MD5 |
4836112bcfeb47d14059f5380d491494
|
|
| BLAKE2b-256 |
a54633c1b5b5ef2074bcca64107c4082fe7a775119e084e6ee65ffc53b2caa71
|
File details
Details for the file pyturso-0.7.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: pyturso-0.7.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 26.0 MB
- Tags: CPython 3.10+, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
76df85d56c485ff170542321a20fd73a72c6995264753c39952fe482d778de08
|
|
| MD5 |
aa5ea9105ca6f46427f5854b611ce6c2
|
|
| BLAKE2b-256 |
60a256b941cdde449c221b9b5bcf76807eba9dd8cb640d3798951449367b2711
|
File details
Details for the file pyturso-0.7.2-cp310-abi3-macosx_11_0_arm64.whl.
File metadata
- Download URL: pyturso-0.7.2-cp310-abi3-macosx_11_0_arm64.whl
- Upload date:
- Size: 7.8 MB
- Tags: CPython 3.10+, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ccae747300b7cc7f3e815dbbce3ca66bca489c9ab81e5f4bc9e3ac973a59501b
|
|
| MD5 |
4758593fa0c51cefcedf7dc7a9b97eef
|
|
| BLAKE2b-256 |
e866c2b259b658df748580aa81cb3da2cca654815b3458d30e9a9a06beefd0c9
|
File details
Details for the file pyturso-0.7.2-cp310-abi3-macosx_10_12_x86_64.whl.
File metadata
- Download URL: pyturso-0.7.2-cp310-abi3-macosx_10_12_x86_64.whl
- Upload date:
- Size: 8.8 MB
- Tags: CPython 3.10+, macOS 10.12+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
5399a4f500733bac23ccb89398fd0f6003e272a760dcb677a785ac2d32e69e20
|
|
| MD5 |
f3356f50f273882846c1d4e283bcfdf6
|
|
| BLAKE2b-256 |
f45ae1cdc67f3d7d7883207a0626a7baa4ed8379fb284506b3ed76e8c9a814d9
|
