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
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.8.0rc3.tar.gz
(3.1 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.8.0rc3.tar.gz.
File metadata
- Download URL: pyturso-0.8.0rc3.tar.gz
- Upload date:
- Size: 3.1 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: maturin/1.14.1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
85ed890c6aea6402ed357b6210100fb3e85c9d9036f3c12154d406fabaa1ce8c
|
|
| MD5 |
db1100e5df2933b1f653f5fa3828f385
|
|
| BLAKE2b-256 |
94e9389aed8b631a4889001b944f387611b3f27ba31322d50c56e5f3080a6bd6
|
File details
Details for the file pyturso-0.8.0rc3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: pyturso-0.8.0rc3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 27.4 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 |
1b5bf508acac34d056dad33b83be1b1dad1f6bbe6a9ea75d884f8f9579ccb7c8
|
|
| MD5 |
66751e790fc2319739a3d2ba56cbfa40
|
|
| BLAKE2b-256 |
9508fc2389323685480974c2594140075c93667ea8df126a890ab95646681522
|
File details
Details for the file pyturso-0.8.0rc3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: pyturso-0.8.0rc3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 26.8 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 |
7c5635e6bb416c66d28c7a11e66218af02eac3067d8a6f5b05fd8f7ecf063de9
|
|
| MD5 |
e0e0fb96c407f62393be37024d9006e3
|
|
| BLAKE2b-256 |
e05e03fcc17889a588c3fda214909aac2ec1632a536d95eb14c5b33251588a57
|
File details
Details for the file pyturso-0.8.0rc3-cp310-abi3-macosx_11_0_arm64.whl.
File metadata
- Download URL: pyturso-0.8.0rc3-cp310-abi3-macosx_11_0_arm64.whl
- Upload date:
- Size: 8.0 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 |
c9b2b0b97b439b3e4520ba887100920d19a7609a2b0c837693581422609596f6
|
|
| MD5 |
34b3f9bf612ac70c8a740fa8a0651a60
|
|
| BLAKE2b-256 |
a1fa20658d42efdf14b27e85e59c9694d00e15758d885f7bba1999752552e2d5
|
File details
Details for the file pyturso-0.8.0rc3-cp310-abi3-macosx_10_12_x86_64.whl.
File metadata
- Download URL: pyturso-0.8.0rc3-cp310-abi3-macosx_10_12_x86_64.whl
- Upload date:
- Size: 9.1 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 |
9ac372d71c0373f07c9da932258f820a1dfeb45ec2434fd166f895981b1eda4c
|
|
| MD5 |
8cd5f320408e7306daacac86a8cd54e3
|
|
| BLAKE2b-256 |
3780cf42dd6fa107d29647d992fa0f449c705642ce9f9322f19a2d8c4d3b136a
|
